From 355696d17da9147d12f63de855ec5ff089f0c285 Mon Sep 17 00:00:00 2001 From: Brad Smith Date: Mon, 22 May 2017 21:33:02 -0400 Subject: [PATCH 1/2] ca65 documentation of .define macros, making note that parentheses in ca65 macros are problematic especially when thinking of them as "C style", replacing unclear example with an example showing how accidental parentheses can cause a problem. --- doc/ca65.sgml | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/doc/ca65.sgml b/doc/ca65.sgml index 6ce5ecef6..74e081985 100644 --- a/doc/ca65.sgml +++ b/doc/ca65.sgml @@ -4282,6 +4282,12 @@ different: some things may be done with both macro types, each type has special usages. The types complement each other. + 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. + Let's look at a few examples to make the advantages and disadvantages @@ -4314,20 +4320,18 @@ Macros with parameters may also be useful: DEBUG "Assembling include file #3" -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 braces, +the actual parameters used when invoking the macro should not use braces. +The invoked parameters are separated by commas only, if parentheses are +used by accident they will become part of the replaced token: -.macro DEBUG message - .out message -.endmacro +.define COMBINE(ta,tb,tc) ta+tb*10+tc*100 + + COMBINE 5,6,7 ; 5+6*10+7*100 = 765 correct + COMBINE(5,6,7) ; (5+6*10+7)*100 = 7200 incorrect! -(That is an example where a problem can be solved with both macro types). - - Characters in macros

When using the option, characters are translated From 051cf11ce69ce147ff747c44e2732bf75a982c79 Mon Sep 17 00:00:00 2001 From: Brad Smith Date: Tue, 23 May 2017 17:07:45 -0400 Subject: [PATCH 2/2] expanding macro examples, trying to adhere to style guidelines --- doc/ca65.sgml | 41 ++++++++++++++++++++++++++++++++++------- 1 file changed, 34 insertions(+), 7 deletions(-) diff --git a/doc/ca65.sgml b/doc/ca65.sgml index 74e081985..d0a3d80e7 100644 --- a/doc/ca65.sgml +++ b/doc/ca65.sgml @@ -4286,7 +4286,8 @@ different: 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. + parentheses around its argument list, when invoked they should not be + included. @@ -4320,18 +4321,44 @@ Macros with parameters may also be useful: DEBUG "Assembling include file #3" -Note that, while formal parameters have to be placed in braces, -the actual parameters used when invoking the macro should not use braces. -The invoked parameters are separated by commas only, if parentheses are -used by accident they will become part of the replaced token: +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: .define COMBINE(ta,tb,tc) ta+tb*10+tc*100 - COMBINE 5,6,7 ; 5+6*10+7*100 = 765 correct - COMBINE(5,6,7) ; (5+6*10+7)*100 = 7200 incorrect! +.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 +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: + + +.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 + + + Characters in macros

When using the option, characters are translated