Release 3.2.0

.NET 8 install required for the included executable.

The most recent version of the Reference Manual is also hosted at https://tollyh.github.io/AssEmbly

Additions:

• Improved macros: Improvements to the existing macro system as well as many new features, including:
  • Multi-line macros that can insert multiple lines into the program wherever the macro is used.
  • Macro parameters that enable the insertion of differing content with the same macro.
  • Macros can now be deleted with the %DELMACRO directive.
  • Ability to disable the expansion of macros on a specific line (by prefixing the line with !) or in entire blocks of lines (by surrounding the lines with !> and <!). Macro expansion is automatically disabled for the %MACRO and %DELMACRO directives so that it doesn't interfere with their operation.
  • Macro replacement on each line is now much more consistent, with nested macros now being reliably supported.
  • Errors and warnings will now display the name of the macro they were raised within, if applicable.
• Assembler variables: Added numeric variables defined with the %DEFINE directive that exist for the duration of assembly, which can be inserted into the program as a literal number. They can have mathematical and logical operations performed on them at assembly-time with the %VAROP directive.
  • Includes predefined assembler constants, which allow the program to determine things about the assembler, such as the current address, AssEmbly version, and the enabled compatibility flags.
  • Can be defined from the command line before assembly begins with the --define= parameter.
• Conditional assembly: %IF, %ELSE_IF, and %ELSE directives have been added which are used to only assemble blocks of code if specific conditions are met.
  • Can check for the existence of assembler variables as well as compare numeric values.
  • Can be nested within each other.
• Code repetition: %REPEAT and %WHILE assembler directives have been added that can be used to repeatedly assemble a section of source code - either a set number of times, or until a condition becomes false respectively.
• Open source licensing: AssEmbly is now released under the GPLv3 open source license. The documentation is released under a similarly permissive CC BY-SA 4.0 license.
• References can now be made to literal addresses without needing a label that points there.
  • The debugger will now use this syntax in the disassembled instruction view, instead of generating a dummy label name.
  • The disassembler will use this syntax if it cannot insert a label definition at the desired address. This means that the disassembler will now never produce programs that cannot be re-assembled.
• The following additional directives have been added:
  • A %LABEL_OVERRIDE directive that allows the assignment of a custom address to labels.
  • A %STOP directive that can be used to stop assembly with a guaranteed error and a custom message.
  • An %ASM_ONCE directive that prevents an imported file from being assembled multiple times, and can prevent cyclic import errors when used as the first statement in a file.
• All directives now begin with a % sign to distinguish them from regular instructions. The old directives can still be used if the --allow-old-directives parameter is given when running the assembler.
• Warnings will now be displayed if the processor halts while there is:
  • One or more allocated regions of memory that haven't been freed with HEAP_FRE.
  • A file still open that hasn't been closed with CFL.
  • An external assembly still open that hasn't been closed with ASMX_CLA.
• Considerable performance improvements have been made to both the assembler and disassembler. The assembler is now ~2.8x faster than 3.1.0, and the disassembler is now ~7x faster.
• The disassembler now includes backslashes in disassembled strings, and will use the line endings of the current system.
• The disassembler will now always produce byte-perfect programs. In order to achieve this, the valid but unused operand form 0xFF, 0x00, 0x.. for the base instruction set will now be treated as data instead of as an instruction. To restore the old behaviour, use the --allow-full-base-opcodes parameter.
• Debug information files now contain a map of addresses to the line and file that they were assembled from, so that the debugger can show the source location of each statement being executed.
• Using RCC will no longer print the character that the user typed to the console by default. You should instead give the character to WCC or use the --auto-echo parameter to restore the old behaviour.
• A new assembler suggestion has been added that detects label definitions that are never used.
• An --output-expanded parameter has been added that outputs the fully expanded source code lines assembled by the assembler for debugging purposes. This includes imported lines and expanded macros all within one file, so that you can see the lines as the assembler sees them.
• New compatibility parameters have been added to: disable assembler variable expansion (--disable-variables - for pre-3.2 strings), and to disable escape sequences (--disable-escapes - for pre-1.1 strings).

Fixes:

• Inserting a sole raw 0xFF byte will no longer crash the assembler.
• The assembler will no longer crash when the invalid literals 0x_ or 0b_ are used.
• The disassembler will now no longer crash if the program ends with a 0xFF byte.
• Command line arguments are now all consistently case-insensitive.
• Invalid ADI files will no longer be generated in the case that multiple imports start on the same address (this was only possible when importing files that insert no bytes).
• A warning is now correctly given when a negative literal is given as the second operand to the SHL, SHR, and SIGN_SHR instructions.
• Warning 0015 will no longer be erroneously given if the instruction following the %IMP directive is not executable.
• Suggestion 0011 will no longer be erroneously given for the %ANALYZER directive.
• Warnings 0001, 0009, and 0010 will no longer be erroneously given when the last instruction in the file is a state directive.
• The processor will now throw the correct exception type when an error occurs loading an external assembly.

Example program changes:

• A new bitmap encoding example has been added, along with a QOI to BMP converter program.
• The console input example program now handles the user pressing the backspace key, and also adds a null terminator after the final typed character.
• The calculator example has been updated to use a single input buffer allocated with the memory allocation extension set.
• Many examples have been updated to utilise the new features added in this release.
• Unused labels have been removed from the file read example.
• Unnecessary TST instructions have been removed from multiple examples.

Internal changes:

• The Assembler class has been significantly refactored. Much of it is no longer static and so now requires instantiation to be used. Assembly logic has been broken up across more methods to aid portability and readability.
  • All assembler directives are now located in a separate file within their own methods.
  • The assembler now has support for getting/setting its current position. This is primarily utilised by the %REPEAT/%WHILE directives.
• The disassembler has undergone major refactoring to improve performance.
  • A reverse lookup dictionary is now used to map opcodes to mnemonics instead of iterating over the mnemonic to opcode map each time.
  • The entire disassembly is now done in one pass, instead of the multi-pass string replacement based approach used before.
• Memory access functions in the Processor class have been marked with MethodImplOptions.AggressiveInlining for a slight performance boost.
• A Python script has been added to the repository for updating old AssEmbly programs to new syntax. There is also a script for converting programs written in the Whitespace esoteric language to equivalent AssEmbly programs.
• ADI files now use a StringBuilder during generation to improve performance.
• ADI files now consistently use LF (0xA) line endings.
• Some extension methods for Stack<T> operations have been implemented, such as cloning and nested copying.
• The Processor class now has properties for checking if resources are currently open.
• Applicable classes have been converted to use primary constructors.
• A new FilePosition struct has been created to replace storing file paths and line numbers separately.
• Processor runtime errors will now cause the host AssEmbly executable to exit with a non-zero exit code.
• The project is now built for multiple different platforms.
• The repository now contains a build.ps1 PowerShell script that can be used to build both the application and the documentation.
• The printed program header will now show when a debug build is being used. Debug builds also now re-throw most exceptions in addition to replacing them with a friendly error message as release builds do.
• Case-insensitive string comparisons now use the Equals method instead of the ToUpper/ToLower methods.
• Additional strings have been moved to the localisable string resource file.
• The string resource file now uses spaces instead of tab characters for indentation.
• The 0xFF full size opcode marker is now stored in a constant.
• The entire assembly result is now serialised when linting, allowing the VSCode extension to highlight unassembled lines.
• MnemonicComparer is no longer contained within its own file, as it is only ever used in Data.cs.
• A reverse lookup Dictionary for retrieving mnemonics from opcodes has been added.
• Many more unit tests have been added, including previously absent unit tests for the assembler and disassembler.
• Documentation for the AAP and ADI file formats has been added.
• The BNF grammar definitions have been removed.
• Built documentation files are now no longer included within the repository itself.

Documentation Errors

• The first code example in the "Address" subsection of the "Operand Types" section should use MVB, not MVQ.