bslathi19/cc65
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages 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
parent 682fd226ae 051cf11ce6
commit b8f30ba0de
1 changed files with 39 additions and 8 deletions
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 some things may be done with both macro types, each type has special
usages. The types complement each other. 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> </itemize>
Let's look at a few examples to make the advantages and disadvantages 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" DEBUG "Assembling include file #3"
</verb></tscreen> </verb></tscreen>
Note that, while formal parameters have to be placed in braces, this is Note that, while formal parameters have to be placed in parentheses,
not true for the actual parameters. Beware: Since the assembler cannot the actual argument used when invoking the macro should not be.
detect the end of one parameter, only the first token is used. If you The invoked arguments are separated by commas only, if parentheses are
don't like that, use classic macros instead: 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> <tscreen><verb>
.macro DEBUG message .define COMBINE(ta,tb,tc) ta+tb*10+tc*100
.out message
.endmacro .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> </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> <sect1>Characters in macros<p>