Revision as of 01:25, 4 January 2020

This script extends the Roll20 macro "language" by enabling:

• comments // like this one
• multi-line commands, indicated by \ at end of line
• textual inclusion of other macros using $include macroname
• textual substitution macros like $attack(hit,dam) = /me hits AC [[1d20+{hit}]] for [[1d8+{dam}]] damage

Macros written in this extended format can be cross-compiled into standard Roll20 macros for execution.

Note that the term macro in the Roll20 context refers to scripts containing multiple commands. We use the term meta-macro to refer to C-style macros (i.e. textual substitution rules).

Syntax

The syntax of the meta-macro language used in macros to be compiled is detailed below.

Comments

Whenever two forward-slashes // are encountered, the remainder of the line is treated as a comment and stripped.

Multi-line commands

Whenever a backslash \ is encountered at the end of a line, the backslash will be stripped and the line will be concatenated with the following line.

Including macros

The $include macroname command (which must appear on a line of its own) will cause the content of the macro macroname to be included in the current macro, in place of the $include command. An exception to this is that if a macro has previously been included, it won't be included again (this prevents infinite circular includes).

Meta-macros

Meta-macro definitions take the format $name(param_0, ..., param_n) = body where name, param_0 ... param_n are identifiers, i.e., non-empty strings consisting of alpha-numberic characters and/or _. For meta-macros without any parameters, the ( brackets </code>)</code> can be omitted.

After a meta-macro has been defined, any occurrance of $name(arg_0, ..., arg_n) will be replaced with the body of the meta-macro definition. Here any occurance of {param_0} ... {param_n} in body will be replaced with arg_0 ... arg_n, respectively. If arg_0 ... arg_n contain any meta-macro invocations, these will be resolved first. If the number of arguments does not match the number of parameters in the meta-macro definition, missing arguments will be treated as the empty string, while extra arguments will be discarded. For meta-macro invocations without any arguments, the ( brackets ) can be omitted.

If the body in a meta-macro definition contains any meta-macro invocations, these will be resolved at the time of definition (this prevents infinite circular resolution). As a result the order of meta-macro definitions matters:

$attack = [[1d20+$bab]]
$bab = 5
/me hits AC $attack

/me hits AC [[1d20+$bab]]

Numerical Evaluation (since 1.1)

When using the := operator in a meta-macro definition, the body will be evaluated numerically. Supports ( brackets ), operators +, -, * and /, and functions ceil and floor.

Note that evaluation will fail for meta-macros with parameters. Evaluation takes place after substitution, so care must be taken about operator precedence as usual:

$pow = 1 + floor(10/4)
$dam := 2 * $pow

will first substitute the body of $dam to 2 * 1 + floor(10/4) and then evaluate it to 4.

Script Use

Note that all compilation will replace any existing content of the target macro.

Compile a specific source macro into a target macro

The !compile sourceMacro targetMacro command will compile sourceMacro into targetMacro.

Compile a specific source macro

The !compile sourceMacro command will compile sourceMacro into _sourceMacro_.

Compile all source macros

The !compile all command will compile all macros which (1) do not start with _, and (2) contain extension-specific code.

To avoid unnecessary compilation of include files, it is recommended to start their name with _, e.g. _inc_common_macros.

Changelog

v1.0 (2018-09-26)

• Release

v1.1 (2020-01-04)

• Numerical evaluation