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

There are two groups of examples.

The first group is when only a single parameter value is provided. The second group passes a single parameter, but the parameter itself holds multiple values.

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 (which is a string).

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. All three techniques are demonstrated next.

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!

It's important to note that the default delimiter, a ; (semicolon), must not appear within the string property list as anything other than a delimiter! If any of the data elements include a semicolon, the string property list is considered malformed and will not be usable. (Potential workarounds include using encode() and decode() or one of the following two approaches.)

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 sent into the macro, but because it's either an array or an object you can retrieve individual fields quite easily.

In the next example, the json.append() is being passed "[]" as the first parameter, which means it's creating an empty JSON Array and then appending two new values to it. The result is then passed to the called macro.

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!

Because a JSON Array is being used to pass in the data, the calls to json.get() are given the integer index number of the value in the array to retrieve (the first element is index zero).

2C: Multiple parameters (using JSON Object)

In this next example, the json.set() is being passed "{}" as the first parameter. This indicates to the function that we are setting values on an empty 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!

With JSON objects, instead of using a numeric index as JSON arrays do, a string is used. This makes the receiving macro slightly more readable because the json.get() is told to retrieve the "Damage" field and the "Token" field.

Equivalents

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

See Also

[macro():], defineFunction(), 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, it will return 0.
• arg() will work as normal if macro.args is a JSON array; otherwise, will return all of macro.args when invoked as arg(0).