Macro Subsitution

The simplest use of Structured Comments is macro substitution - and if you've ever been a C/C++ developer the concept will be very familiar. You can define and un-define macros using the define and undef commands, and later on in your code use the ref command to insert the value, optionally replacing "normal" code.

Macros can also be used in Conditional Compilation to enable or disable sections of code, for example to enable debugging information on your test platform.

${define macro-name} [value]

Defines a macro called "macro-name" and assigns it the value "value"; "value" is optional and if not present an empty string is assigned.

For example:

    --+${define DEBUG} true

defines a macro called DEBUG and sets its value to" true".


${undef macro-name}

Removes a macro definition and discards the value.

For example:

    --+${undef DEBUG}



${ref macro-name} [data]

This comment is replaced with the value of the macro identified by macro-name; if the macro does not exist then the optional data is used instead.  If followed by an endref and data is not provided then the value between the ref and endref is used if the macro macro-name is not defined.  For example:

--${define mymacro} hello world
--${ref mymacro} test
--${ref anothermacro} my default value
--${ref somethingelse}
this is
a longer
alternative
--${endref}

will produce:

hello world
my default value
this is
a longer
alternative


${endref}

Completes a grouped ref command.