macro.args

macro.args Special Variable

The variable macro.args holds the value of the argument passed to a trusted macro via the MACRO() roll option. macro.args exists only within the macro that is called, and may be manipulated like any variable in a macro. " "

Usage

Simply use macro.args like any variable. If no arguments were passed, it will be a blank value.

Examples

===1: Single parameter===

When a macro on a library token is called by another macro, the calling macro may pass one argument to the called macro:

Calling Macro

<!-- Call the getDamage macro -->
[h:damageDice="2d6"]
[MACRO("getDamage@Lib:test"): damageDice]

Called Macro

<!-- getDamage Macro -->
[h:damageRoll = eval(macro.args) + 9]
You hit your target for [r:damageRoll] damage!

In the example above, damageDice is the argument being passed to the macro getDamage, which resides on the Lib:test library token. Within the getDamage macro, the variable macro.args is automatically generated and assigned the value of damageDice.

It's important to note that only a single parameter can be passed to a macro and that parameter appears in the macro.args variable. If more than a single parameter needs to be sent to a macro, you may use string property lists, a JSON array or object, or a user-defined function. The first two techniques are demonstrated below.

2A: Multiple parameters using String Property List

A string property list essentially bundles multiple values into a single string which would then be split back apart inside the macro body.

Calling Macro

<!-- Call the doDamage macro -->
[h:damageDice="2d6"]
[h:theToken = "Bobo Fett"]
[MACRO("getDamage@Lib:test"): "Damage="+damageDice+"; Token="+theToken]

Called Macro

<!-- doDamage Macro -->
[h:dmg   = getStrProp(macro.args, "Damage")]
[h:tokid = getStrProp(macro.args, "Token")]
You hit [r: tokid] for [r:dmg] damage!

2B: Multiple parameters using JSON Array

The second way to pass multiple parameters is to use a JSON Array or JSON Object.

Using a JSON data type passes multiple values as a single unit. When using JSON data types, there will be a single parameter coming into the macro but because it's either an array or an object you can retrieve individual fields quite easily.

As the json.append() is being passed "[]" as the first parameter in this next code block, it's creating an empty JSON Array and then appending two new values to it.

Calling Macro using JSON Array

<!-- Call the doDamage macro -->
[h:damageDice="2d6"]
[h:theToken = "Bobo Fett"]
[h:jsonData = json.append("[]", damageDice, theToken)]
[MACRO("getDamage@Lib:test"): jsonData]

Called Macro using JSON Array

<!-- doDamage Macro -->
[h:dmg   = json.get(macro.args, 0)]
[h:tokid = json.get(macro.args, 1)]
You hit [r: tokid] for [r:dmg] damage!

2C: Multiple parameters using JSON Object

Notice that in this next example, the json.set() is being passed "{}" as the first parameter. This indicates to the function that we want a JSON Object.

Calling Macro using JSON Object

<!-- Call the doDamage macro -->
[h:damageDice="2d6"]
[h:theToken = "Bobo Fett"]
[h:jsonData = json.set("{}", "Damage", damageDice, "Token", theToken)]
[MACRO("getDamage@Lib:test"): jsonData]

Called Macro using JSON Object

<!-- doDamage Macro -->
[h:dmg   = json.get(macro.args, "Damage")]
[h:tokid = json.get(macro.args, "Token")]
You hit [r: tokid] for [r:dmg] damage!

Equivalents

The function call arg(0) will show the contents of macro.args if it is not a JSON array.

See Also

[macro():],

macro.return

User defined functions can also use macro.args, and have some related/replacement functions:

• argCount() will display the number of items if macro.args is a JSON array, otherwise will return 0.
• arg() will work as normal if macro.args is a JSON array, otherwise will return all of macro.args with arg(0).