Click above to get retro games delivered to your door ever month!

Defining your own directives
============================

   The commands `.MACRO' and `.ENDM' allow you to define macros that
generate assembly output.  You can use these macros with a syntax
similar to built-in GASP or assembler directives.  For example, this
definition specifies a macro `SUM' that adds together a range of
consecutive registers:

             .MACRO  SUM FROM=0, TO=9
             ! \FROM \TO
             mov     r\FROM,r10
     COUNT   .ASSIGNA        \FROM+1
             .AWHILE \&COUNT LE \TO
             add     r\&COUNT,r10
     COUNT   .ASSIGNA        \&COUNT+1
             .AENDW
             .ENDM

With that definition, `SUM 0,5' generates this assembly output:

             ! 0 5
             mov     r0,r10
             add     r1,r10
             add     r2,r10
             add     r3,r10
             add     r4,r10
             add     r5,r10

`.MACRO MACNAME'
`.MACRO MACNAME MACARGS ...'
     Begin the definition of a macro called MACNAME.  If your macro
     definition requires arguments, specify their names after the macro
     name, separated by commas or spaces.  You can supply a default
     value for any macro argument by following the name with `=DEFLT'.
     For example, these are all valid `.MACRO' statements:

    `.MACRO COMM'
          Begin the definition of a macro called `COMM', which takes no
          arguments.

    `.MACRO PLUS1 P, P1'
    `.MACRO PLUS1 P P1'
          Either statement begins the definition of a macro called
          `PLUS1', which takes two arguments; within the macro
          definition, write `\P' or `\P1' to evaluate the arguments.

    `.MACRO RESERVE_STR P1=0 P2'
          Begin the definition of a macro called `RESERVE_STR', with two
          arguments.  The first argument has a default value, but not
          the second.  After the definition is complete, you can call
          the macro either as `RESERVE_STR A,B' (with `\P1' evaluating
          to A and `\P2' evaluating to B), or as `RESERVE_STR ,B' (with
          `\P1' evaluating as the default, in this case `0', and `\P2'
          evaluating to B).

     When you call a macro, you can specify the argument values either
     by position, or by keyword.  For example, `SUM 9,17' is equivalent
     to `SUM TO=17, FROM=9'.  Macro arguments are preprocessor variables
     similar to the variables you define with `.ASSIGNA' or `.ASSIGNC';
     in particular, you can use them in conditionals or for loop
     control.  (The only difference is the prefix you write to evaluate
     the variable: for a macro argument, write `\ARGNAME', but for a
     preprocessor variable, write `\&VARNAME'.)

`NAME .MACRO'
`NAME .MACRO ( MACARGS ... )'
     An alternative form of introducing a macro definition: specify the
     macro name in the label position, and the arguments (if any)
     between parentheses after the name.  Defaulting rules and usage
     work the same way as for the other macro definition syntax.

`.ENDM'
     Mark the end of a macro definition.

`.EXITM'
     Exit early from the current macro definition, `.AREPEAT' loop, or
     `.AWHILE' loop.

`\@'
     GASP maintains a counter of how many macros it has executed in
     this pseudo-variable; you can copy that number to your output with
     `\@', but *only within a macro definition*.

`LOCAL NAME [ , ... ]'
     *Warning: `LOCAL' is only available if you select "alternate macro
     syntax" with `-a' or `--alternate'.*  Alternate macro
     syntax: Alternate

     Generate a string replacement for each of the NAME arguments, and
     replace any instances of NAME in each macro expansion.  The
     replacement string is unique in the assembly, and different for
     each separate macro expansion.  `LOCAL' allows you to write macros
     that define symbols, without fear of conflict between separate
     macro expansions.