6502/cc65
1
0
Fork 0
mirror of https://github.com/cc65/cc65.git synced 2024-06-26 05:29:30 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #436 from bbbradsmith/ca65_define_macro_doc

Browse Source 
Small improvement to ca65 macro documentation
This commit is contained in:
Oliver Schmidt 2017-06-05 15:03:37 +02:00 committed by GitHub
commit b8f30ba0de
1 changed files with 39 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
doc/ca65.sgml
View File

@ -4305,6 +4305,13 @@ different:
some things may be done with both macro types, each type has special
usages. The types complement each other.
<item> Parentheses work differently from C macros.
The common practice of wrapping C macros in parentheses may cause
unintended problems here, such as accidentally implying an
indirect addressing mode. While the definition of a macro requires
parentheses around its argument list, when invoked they should not be
included.
</itemize>
Let's look at a few examples to make the advantages and disadvantages
@ -4337,18 +4344,42 @@ Macros with parameters may also be useful:
DEBUG "Assembling include file #3"
</verb></tscreen>
Note that, while formal parameters have to be placed in braces, this is
not true for the actual parameters. Beware: Since the assembler cannot
detect the end of one parameter, only the first token is used. If you
don't like that, use classic macros instead:
Note that, while formal parameters have to be placed in parentheses,
the actual argument used when invoking the macro should not be.
The invoked arguments are separated by commas only, if parentheses are
used by accident they will become part of the replaced token.
If you wish to have an expression follow the macro invocation, the
last parameter can be enclosed in curly braces {} to indicate the end of that
argument.
Examples:
<tscreen><verb>
.macro DEBUG message
.out message
.endmacro
.define COMBINE(ta,tb,tc) ta+tb*10+tc*100
.word COMBINE 5,6,7 ; 5+6*10+7*100 = 765
.word COMBINE(5,6,7) ; (5+6*10+7)*100 = 7200 ; incorrect use of parentheses
.word COMBINE 5,6,7+1 ; 5+6*10+7+1*100 = 172
.word COMBINE 5,6,{7}+1 ; 5+6*10+7*100+1 = 766 ; {} encloses the argument
.word COMBINE 5,6-2,7 ; 5+6-2*10+7*100 = 691
.word COMBINE 5,(6-2),7 ; 5+(6-2)*10+7*100 = 745
.word COMBINE 5,6,7+COMBINE 0,1,2 ; 5+6*10+7+0+1*10+2*100*100 = 20082
.word COMBINE 5,6,{7}+COMBINE 0,1,2 ; 5+6*10+7*100+0+1*10+2*100 = 975
</verb></tscreen>
(That is an example where a problem can be solved with both macro types).
With C macros it is common to enclose the results in parentheses to
prevent unintended interactions with the text of the arguments, but
additional care must be taken in this assembly context where parentheses
may alter the meaning of a statement. In particular, indirect addressing modes
may be accidentally implied:
<tscreen><verb>
.define DUO(ta,tb) (ta+(tb*10))
lda DUO(5,4), Y ; LDA (indirect), Y
lda 0+DUO(5,4), Y ; LDA absolute indexed, Y
</verb></tscreen>
<sect1>Characters in macros<p>