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'. See section Alternate macro syntax. 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.