Preprocessor commands are put in braces. Put a left brace, and then the macro name, and then the arguments (if any), and then a right brace.
Macros are expanded (sometimes with side-effects) outside of any braces, as well as inside braces where a number or string is expected, but are not expanded as part of the definition or arguments to a user-defined macro.
Other tokens used in the preprocessor are a macro separator token, which is written by a vertical bar, and a macro argument token, which is written as one or more backslashes followed by a number from 1 to 255. The purpose of these are explained below.
Built-in macros include:
- {+}: Takes any number of arguments, all numbers, which are added together. With no arguments, the result is 0.
- {-}: Takes two arguments, both numbers; the result is the first minus the second.
- {*}: Takes any number of arguments, all numbers, which are multiplied together. With no arguments, the result is 1.
- {/}: Takes two arguments, both numbers; the result is the first divided by second (using rounding like in C).
- {mod}: Takes two arguments, both numbers; the result is the remainder of first divided by second (using rounding like in C).
- {band}: Takes any number of arguments, all numbers, which are bitwise ANDed together. With no arguments, the result is -1.
- {bor}: Takes any number of arguments, all numbers, which are bitwise ORed together. With no arguments, the result is zero.
- {bxor}: Takes any number of arguments, all numbers, which are bitwise XORed together. With no arguments, the result is zero.
- {bnot}: Takes one argument, which is a number. The result is the bitwise complement of that number.
- {bit}: Takes any number of arguments, all of which are numbers in range 0 to 31. The result is a number with only the corresponding bits set.
- {cat}: Takes any number of arguments, which can include name tokens, string tokens, numeric tokens, and macro separator tokens. Macro separator tokens are ignored; the rest are concatenated into a single string. Any sigils in a name token are omitted. Numeric tokens are converted to decimal (even if originally written in hexadecimal or octal).
- {version}: Takes one argument, which must be zero, otherwise it is an error. The expansion is nothing. Later versions of Free Hero Mesh may change the valid range of numbers.
- {define}: Define your own macros (or redefine an existing macro; even built-in macros can be redefined). The expansion is nothing, but defines a macro as a side-effect; see the section below for details.
- {include}: Takes one argument, which is a string. Causes it to read that file (like the #include command in the C preprocessor). Cannot be used inside of another macro.
- {call}: The first argument is a string that specifies the name of the macro; the rest is the arguments to that macro. It will call that macro; this can be used if the name of the macro to call must be given dynamically. Both built-in macros and user-defined macros can be called in this way.
User-defined macros
Use the {define} command to define your own macros. The first argument is a string that specifies the macro name; the rest is the definition of the macro that it will expand to.Inside of the definition, a macro argument token with a single backslash is replaced by the corresponding macro argument, and a macro argument token with multiple backslashes is replaced by the same one but with one less backslash (this way, a macro can define another macro).
When calling a user-defined macro, the arguments are given in the following way: Any group inside of braces/parentheses is treated as a single argument (including the braces/parentheses in the argument). A macro separator token outside of braces/parentheses means that this is the last argument consisting of everything up to the matching right brace, possibly including other macro separator tokens (but not the one that introduced this long argument).
Computational class
It is believed to be Turing-complete, because a tag system can be implemented, for example:
{define "skip" {call \2}}
{define "1" {skip \1|"3"|"3"|"2"|"1"|"H"}}
{define "2" {skip \1|"3"|"3"|"1"}}
{define "3" {skip \1|"3"|"3"}}
{define "H" \1}
{call "2"|"1"|"1"}