The conditional macros generate branch instructions based on the condition passed. In the simplest form they expect an expression of both a 6502 flag name as a single uppercase character: C, Z, N, V. ( They will also accept G symbolizing 'greater than', but this should be avoided where possible due to it requiring two branch instructions to evaluate and better options being available.) As well as a keyword: set or clear. Due to this, one should avoid using C Z N V G or clear or set as identifiers.

In the simplest use in an if statement:

if C set
; do code here if C flag is set
endif

Also accepted: Any number of negate signs in front of the condition:

if ! C set
; do code here if C not set
endif

Using the C-style macros in ca65, it's trivial to setup some more human friendly flag names:

    .define less                C clear
    .define greaterORequal      C set
    .define carry               C set
    .define zero                Z set
    .define equal               Z set
    .define plus                N clear
    .define positive            N clear
    .define minus               N set
    .define negative            N set
    .define bit7                N set
    .define overflow            V set
    .define bit6                V set
    .define bitset              Z clear

    .define greater             G set               ; Use greater and less/equal macros to simulate this functionality.
    .define lessORequal         G clear

The .define inline macro substitute any of these flags with the identifiers above. Included is the file ca65hl_defines.h that can be edited to customize this and some other features of the macro pack.

Macro "Functions" and Inline Code Expressions

If the expression does not match a flag definition as described above, and is not an indentifier (variable), the macro will attempt to execute the passed value as a macro or instruction. If you have defined a macro to be called in this way, it could use the statement set_flag_test or setFlagTest which should be followed by a valid flag definition. The flag setting defined is what you can think of as 'true' when compared to boolean logic.

Example:

.macro reg_is_negative reg
  .if .xmatch(reg,a)
    cmp #0
 .elseif .xmatch(reg,x)
    cpy #0
 .elseif .xmatch(reg,y)
    cpx #0
 .else
   .error "No register passed."
 .endif
  setFlagTest N set      ; tell the conditional statement to test the N flag, could also use 'negative'
.endmacro                ; when using this macro, 'N set' could be thought of as true, N clear is false.

The macro defines which cpu flags to test and can then be used thus:

if reg_is_negative a
;code
endif

As well, assembly code can be used to determine the condition, with any number of assembly statements and macros separated by colons. In this way, if set_flag_test is not used to define the cpu flag, the double equal can be used (==) or the not equal (!=) followed by the flag to be tested. The latter will invert the flag to be tested. Example:

if lda MyVariable : tay : dey == zero
; do code if MyVariable is equal to 1
endif

Another Example:

if jsr inRange == C set 
 ; do stuff if in range
endif

Note: Using the == or != symbol is a way of defining which flag to test and is not truly equality. It could be thought of as "If this results in this flag being set then the expression is TRUE."

Logical AND/OR Support

All conditional statements support logical AND and OR in the the expression, with the default operators && and || (which will also match .and and .or tokens in ca65.) These will actually be scanned for first in a conditional expression and generate multiple branches, with the only limitation being that all ORs must be before all ANDs in the same parentheses level. AND logic will always take precedence.

Parentheses

Parentheses can be placed around all expressions (for readability) but aren't needed:

if lda foo == zero goto myLabel

Is the same as:

if (lda foo == zero) goto myLabel

Parentheses can be used to generate complex branching logic:

if (( lda foo == negative && ldx bar == zero) || lda foo == zero) && (ror bar == C set || ldx baz : inx == zero) goto myLabel

Parentheses can be used in any order to help create complex branching logic. The only limitation being that all OR comparisons must be before all AND in the same parentheses level. Parentheses can be used to work around this limitation.

Parentheses should also be used to have the macro code ignore an enclosed section if required. For example, if your inline macro or code uses characters in its parameters that would normally be recognized as part of a conditional expression, you can enclose the parameters in parentheses and it will be ignored. This is especially useful with some on the integrated macro support.

Example:

if mySuperCoolMacro foo && bar goto myLabel

In this fictitious example, the macro, mySuperCoolMacro, requires the '&&' to be passed. This will be parsed by the if and cause an error. To work around this:

if mySuperCoolMacro(foo && bar) goto myLabel

The macro will have to check for, and remove any parentheses, but the && will be ignored by the if macro.

Braces (Curly Brackets)

Curly braces should be used to enclose the entire parameter line if including any commas for any reason, such as an inline index instruction:

if { ldx list,y == negative }
; some code
endif

Implied Register Loading and Expression Evaluation

If a condition references an identifier alone, the macro code will default to using the accumulator to load the identifier via a lda instruction. As well, if no flag is specified with either the double equal (==), not equal (!=) or set_flag_test, and the macro has found what seems to be valid assembly code or an identifier, it will default to using Z clear to simulate a non-zero result as true. Example:

if myFlag        ; myFlag is a variable, it gets loaded into reg A, and is evaluated as true if it is non-zero
; myFlag code
endif

; this will generate the same code as above:
if lda myFlag != zero
; my Flag code
endif

Inverting logic

By default, the logical 'boolean not' operator is not or ! - there are two matches that are functionally the same. You can negate an individual condition, or en entire expression in parentheses:

if !myFlag
; Don't do this unless the flag is clear/false
endif

; this will generate the same code as above:
if lda myFlag == zero
; my Flag code
endif

With parentheses:

if !((C set && Z set) || N clear) goto a_label

Home