Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Script:MetaMacros"

From Roll20 Wiki

Jump to: navigation, search
(Meta-macros)
Line 36: Line 36:
 
where <code>name, param_0 ... param_n</code> are identifiers, i.e., non-empty strings consisting of alpha-numberic characters and/or _. For meta-macros without any parameters, the <code>(</code> brackets </code>)</code> can be omitted.
 
where <code>name, param_0 ... param_n</code> are identifiers, i.e., non-empty strings consisting of alpha-numberic characters and/or _. For meta-macros without any parameters, the <code>(</code> brackets </code>)</code> can be omitted.
  
After a meta-macro has been defined, any occurrance of <code>$name(arg_0, ..., arg_n)</code> will be replaced with the body of the meta-macro definition. Here any occurance of <code>{param_0} ... {param_n}<code> in <code>body</code> will be replaced with <code>arg_0 ... arg_n<code>, respectively. If <code>arg_0 ... arg_n</code> 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 <code>(</code> brackets <code>)</code> can be omitted.
+
After a meta-macro has been defined, any occurrance of <code>$name(arg_0, ..., arg_n)</code> will be replaced with the body of the meta-macro definition. Here any occurance of <code>{param_0} ... {param_n}</code> in <code>body</code> will be replaced with <code>arg_0 ... arg_n</code>, respectively. If <code>arg_0 ... arg_n</code> 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 <code>(</code> brackets <code>)</code> 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:
 
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:
Line 47: Line 47:
  
 
will compile into <pre>/me hits AC [[1d20+$bab]]</pre> as <code>$bab</code> was undefined at the time <code>$attack</code> was defined.
 
will compile into <pre>/me hits AC [[1d20+$bab]]</pre> as <code>$bab</code> was undefined at the time <code>$attack</code> was defined.
 +
 +
==== Numerical Evaluation (since 1.1) ====
 +
When using the <code>:=</code> operator in a meta-macro definition, the body will be evaluated numerically. Supports <code>(</code> brackets <code>)</code>, operators <code>+</code>, <code>-</code>, <code>*</code> and <code>/</code>, and functions <code>ceil</code> and <code>floor</code>.
 +
 +
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:
 +
 +
<pre>
 +
$pow = 1 + floor(10/4)
 +
$dam := 2 * $pow
 +
</pre>
 +
 +
will first substitute the body of <code>$dam</code> to <code>2 * 1 + floor(10/4)</code> and then evaluate it to <code>4</code>.
  
 
== Script Use ==
 
== Script Use ==

Revision as of 01:25, 4 January 2020

API ScriptAuthor: Henning K
Version: 1.1
Last Modified: 2020-01-04
Code: MetaMacros
Dependencies: None
Conflicts: None

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).

Contents

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
will compile into
/me hits AC [[1d20+$bab]]
as $bab was undefined at the time $attack was defined.

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