From 7d8b69f6f0e253ea55ec8b338c47857953f3a1a4 Mon Sep 17 00:00:00 2001 From: cuz Date: Sun, 9 May 2004 20:28:43 +0000 Subject: [PATCH] Document the new curly braces feature git-svn-id: svn://svn.cc65.org/cc65/trunk@3015 b7a2c559-68d2-44c3-8de9-860c34a00d81 --- doc/ca65.sgml | 105 ++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 77 insertions(+), 28 deletions(-) diff --git a/doc/ca65.sgml b/doc/ca65.sgml index c093fd033..9294a94c5 100644 --- a/doc/ca65.sgml +++ b/doc/ca65.sgml @@ -80,7 +80,7 @@ development: Command line option overview

- + The assembler accepts the following options: @@ -1075,16 +1075,22 @@ either a string or an expression. .BLANK

- Builtin function. The function evaluates its argument in braces and - yields "false" if the argument is non blank (there is an argument), and - "true" if there is no argument. As an example, the - .if .blank(arg) + .if .blank({arg}) + .CONCAT

Builtin string function. The function allows to concatenate a list of string @@ -1145,7 +1151,10 @@ either a string or an expression. The first integer expression gives the number of tokens to extract from - the token list. The second argument is the token list itself. + the token list. The second argument is the token list itself. The token + list may optionally be enclosed into curly braces. This allows the + inclusion of tokens that would otherwise terminate the list (the closing + right paren in the given case). Example: @@ -1155,7 +1164,7 @@ either a string or an expression. .macro ldax arg ... - .if (.match (.left (1, arg), #)) + .if (.match (.left (1, {arg}), #)) ; ldax called with immidiate operand ... @@ -1205,7 +1214,10 @@ either a string or an expression. end-of-file - Often a macro parameter is used for any of the token lists. + The token lists may optionally be enclosed into curly braces. This allows + the inclusion of tokens that would otherwise terminate the list (the closing + right paren in the given case). Often a macro parameter is used for any of + the token lists. Please note that the function does only compare tokens, not token attributes. So any number is equal to any other number, regardless of the @@ -1224,7 +1236,7 @@ either a string or an expression. .macro asr arg - .if (.not .blank(arg)) .and (.not .match (arg, a)) + .if (.not .blank(arg)) .and (.not .match ({arg}, a)) .error "Syntax error" .endif @@ -1251,10 +1263,12 @@ either a string or an expression. .MID (<int expr>, <int expr>, <token list>) - The first integer expression gives the starting token in the list (the - first token has index 0). The second integer expression gives the number - of tokens to extract from the token list. The third argument is the - token list itself. + The first integer expression gives the starting token in the list (the first + token has index 0). The second integer expression gives the number of tokens + to extract from the token list. The third argument is the token list itself. + The token list may optionally be enclosed into curly braces. This allows the + inclusion of tokens that would otherwise terminate the list (the closing + right paren in the given case). Example: @@ -1264,7 +1278,7 @@ either a string or an expression. .macro ldax arg ... - .if (.match (.mid (0, 1, arg), #)) + .if (.match (.mid (0, 1, {arg}), #)) ; ldax called with immidiate operand ... @@ -1303,8 +1317,11 @@ either a string or an expression. .RIGHT (<int expr>, <token list>) - The first integer expression gives the number of tokens to extract from - the token list. The second argument is the token list itself. + The first integer expression gives the number of tokens to extract from the + token list. The second argument is the token list itself. The token list + may optionally be enclosed into curly braces. This allows the inclusion of + tokens that would otherwise terminate the list (the closing right paren in + the given case). See also the and builtin functions. @@ -1440,8 +1457,12 @@ either a string or an expression. .TCOUNT

- Builtin function. The function accepts a token list in braces. The - function result is the number of tokens given as argument. + Builtin function. The function accepts a token list in braces. The function + result is the number of tokens given as argument. The token list may + optionally be enclosed into curly braces which are not considered part of + the list and not counted. Enclosement in curly braces allows the inclusion + of tokens that would otherwise terminate the list (the closing right paren + in the given case). Example: @@ -1451,10 +1472,10 @@ either a string or an expression. .macro ldax arg - .if (.match (.mid (0, 1, arg), #)) + .if (.match (.mid (0, 1, {arg}), #)) ; ldax called with immidiate operand - lda #<(.right (.tcount (arg)-1, arg)) - ldx #>(.right (.tcount (arg)-1, arg)) + lda #<(.right (.tcount ({arg})-1, {arg})) + ldx #>(.right (.tcount ({arg})-1, {arg})) .else ... .endif @@ -1482,7 +1503,10 @@ either a string or an expression. end-of-file - Often a macro parameter is used for any of the token lists. + The token lists may optionally be enclosed into curly braces. This allows + the inclusion of tokens that would otherwise terminate the list (the closing + right paren in the given case). Often a macro parameter is used for any of + the token lists. The function compares tokens +Macro parameters may optionally be enclosed into curly braces. This allows the +inclusion of tokens that would otherwise terminate the parameter (the comma in +case of a macro parameter). + + + .macro foo arg1, arg2 + ... + .endmacro + + foo ($00,x) ; Two parameters passed + foo {($00,x)} ; One parameter passed + + +In the first case, the macro is called with two parameters: 'Detecting parameter types

@@ -3205,14 +3249,14 @@ functions will allow you to do exactly this: .macro ldax arg - .if (.match (.left (1, arg), #)) + .if (.match (.left (1, {arg}), #)) ; immediate mode - lda #<(.right (.tcount (arg)-1, arg)) - ldx #>(.right (.tcount (arg)-1, arg)) + lda #<(.right (.tcount ({arg})-1, {arg})) + ldx #>(.right (.tcount ({arg})-1, {arg})) .else ; assume absolute or zero page lda arg - ldx 1+(arg) + ldx 1+({arg}) .endif .endmacro @@ -3220,7 +3264,12 @@ functions will allow you to do exactly this: Using the / function, the macro is able to check if its argument begins with a hash mark. If so, two immediate loads are emitted, Otherwise a load from an absolute zero page memory location is -assumed. So this macro can be used as +assumed. Please note how the curly braces are used to enclose parameters to +pseudo functions handling token lists. This is necessary, because the token +lists may include commas or parens, which would be treated by the assembler +as end-of-list. + +The macro can be used as foo: .word $5678 -- 2.39.5