v3.0.0 Alpha 2
Pre-release
3.0.0 Alpha 2 release
This is an alpha release - it contains experimental features with commands and APIs that are subject to change. Whilst it should not crash your machine, the new features it contains should not be considered to be stable, and may differ in the final release version.
As with other releases, this can be run on any Agon Light compatible machine, including the Agon Light, Agon Light 2, Agon Console8 and Agon Origins Edition.
Supporting development
If you would like to support the development of the Agon Console8 and Agon Light firmware, you can sponsor me on GitHub or join my Patreon.
Producing new versions of the Agon firmware is a lot of work. Financially, I could really use the help.
What is new
This release is a snapshot of the current "system variables" branch work, and builds on the previous release. The primary improvement from alpha 1 is the addition of APIs that expose all of the new functionality, making them available for programs to use.
(NB the original 3.0.0-alpha2 release has been removed and replaced with this slightly newer version, owing to the discovery of one critical bug, and a mistake in the release process that meant that the original release git tag did not tag the correct code.)
It should be noted that whilst the underlying functionality for these new APIs has been extensively tested, the API wrappers themselves have not. Documentation for these new APIs have not yet been written at the time of release. They will be added to the community documentation site in due course. Preliminary documentation can be seen against the API implementations in mos_api.asm
New commands
Most new commands were added in Alpha 1 - see the release notes for more information.
IfThere <filepath> then <command> [else <command>]
This command works essentially the same as the If command (added in Alpha 1) but will instead look for the presence of a file or directory at the given filepath. The filepath is transformed before it is checked, so variables may be used.
Try <command>
Try will perform the given command, trapping any errors that may occur. It will set Try$ReturnCode with the return code value for the command, and if an error occurred it will set Try$Error to the corresponding error string.
The Try command allows for commands that can fail to be included in script files.
%<command>
Prefixing any command with the % character makes the command interpreter skip command alias resolution. This means for example that you could redefine an internal MOS command with an alias, but have the alias make sure it uses the original command.
Other changes
The argument substitution system, as used by command aliases and hotkeys, has been updated to mean that arguments enclosed with double-quotes are treated as a single argument.
The command line interpreter will also recognise arguments enclosed by double-quotes. This means that you can now refer to filenames that include spaces from the CLI.
NB at the time of this release, the tab-completion system does not support this, so it will not play ball correctly with double-quotes, or auto-complete filenames appropriately that include spaces.
The Sys$Date system variable is now writable, so you can change the system RTC date via setting that variable.
New APIs
All of the new functionality is now available via APIs. The full list of new APIs is as follows:
mos_unpackrtc: EQU 23h
; MOS string functions
;
mos_pmatch: EQU 28h
mos_getargument: EQU 29h
mos_extractstring: EQU 2Ah
mos_extractnumber: EQU 2Bh
mos_escapestring: EQU 2Ch
; System variables and related functions
;
mod_setvarval: EQU 30h
mos_readvarval: EQU 31h
mos_gsinit: EQU 32h
mos_gsread: EQU 33h
mos_gstrans: EQU 34h
mos_substituteargs: EQU 35h
mos_evaluateexpression: EQU 36h ; not implemented, yet
; 37h not yet used
; Path resolution functions
;
mos_resolvepath: EQU 38h
mos_getdirforpath: EQU 39h
mos_getleafname: EQU 3Ah
mos_isdirectory: EQU 3Bh
mos_getabsolutepath: EQU 3Ch
Documentation for these will be added to the community documentation site in due course.