1. What IS a macro anyway?
A macro, simply put, is a shortcut to write things. If you have a common piece of code in Asar that you use over and over with very little or no changes, you can turn it into a macro and save a lot of time and effort, plus it lets you change it without searching and replacing each copy. It also can act sort of like a function, allowing you to pass variables to it. Macros can be a powerful tool that can shorten code and make coding easier.
2. How do macros work?
Macros are not true functions or subroutines in the same way C functions or subroutines are. They are more like defines. When you call a macro, the macro's contents get inserted where you call them. The difference is, a macro can be more then one line and contain most anything you want, including code, and you can additionally set arguments or variables that get inserted wherever you want.
3. How do I make a macro?
Macros are easy to make, if you know how they work. The first thing you need to do is declare the name and what augments it uses. To do this make a line in the asm file like this:
Code
macro name()
Note that "name" can be almost anything (as long as it's not a special character. For simplicity's sake, I will say just stick with letters and numbers), but each macro has to has to have it's own name.
After you made that line, every line after it is part of the macro until you end it. To end a macro, you have to put "endmacro" on a line by it's self.
4. How do I use a macro?
Now you should know how to make a basic macro, but how is it used? First we should learn how to "call" or run a macro. To do this, we use the "%" character in front of our macro name like this:
Code
%name()
Now when we call a macro the contents of a macro will replace the macro call. So if we do this:
Code
macro name() LDA #$24 endmacro %name()
Now "%name()" will be replaced by "LDA #$24". You can put as much code as you want in a macro, and even non-code things like "db" or "org" or most anything else Asar understands. There is even a special sort of label for macros. If you start a label name with the "?" character inside a macro, each time the macro is run the "?" will be replaced with something new, so you can branch to it without having to worry if it is redefined.
5. How do I use arguments?
Using arguments or variables allows you to replace parts of the macro with whatever you want. You may have noticed that the macro name I used is followed by "()". This is a required part of a macro. If you don't want to use arguments, just leave it empty. Otherwise, in between the "(" and the ")" is where you put the names of arguments or variables you use. Same rules apply to these names as the macro name. Here is an example:
Code
macro name(arg1)
Again "arg1" is an example. Inside a macro, you can insert an argument by placing the name of the argument inside "<" and ">" for example:
Code
macro name(arg1) LDA #<arg1> endmacro
Then when you call the macro, you simply put the text you want to insert in between the "(" and ")" like this:
Code
%name($24)
and the result will be:
Code
LDA #$24
You can have as many as you like, just make sure each one has a "," after it, in both the macro and the call, like this:
Code
macro name(arg1, arg2) LDA #<arg1> STA <arg2> endmacro %name($01, $19)
Which will result in:
Code
LDA #$01 STA $19
Now isn't that simple? :3
One last note: A macro call, as far as I know, can only be done on it's own line.
6. Some examples and stuff
Here are some example macros I made:
Code
; Loads a snes pal color into a, must be in 16-bit mode macro rgb(r, g, b) LDA.w #<b><<5|<g><<5|<r> endmacro ; Makes a rats tag for the space between two labels macro rats(start, end) db "STAR" ; Write RATS tag dw <end>-<start>-1 dw <end>-<start>-1^$FFFF endmacro ; Re-points a stim image to a new location or label macro ImagePointer(slot, pointer) org <slot>*3+$8084D0 dl <pointer> endmacro ; Re-points a layer 3 bg to a new location or label macro TileSetL3pointer(set, slot, pointer) org <set>*3+<slot>*3+$859000 dl <pointer> endmacro
Also, did you know you can use an argument for a macro to decide what macro to call? I found a few uses for that. :3
