macro.args: Difference between revisions
m (Corrected a few headings) |
m (Corrected a few headings) |
(No difference)
|
Latest revision as of 23:59, 6 June 2023
macro.args Special Variable
Usage
Simply use macro.args like any variable. If no arguments were passed, it will be a blank value.
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
<!-- Call the doDamage macro -->
[h:damageDice="2d6"]
[h:theToken = "Bobo Fett"]
[h:jsonData = json.append("[]", damageDice, theToken)]
[MACRO("getDamage@Lib:test"): jsonData]
Called Macro
<!-- 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
<!-- 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
<!-- doDamage Macro -->
[h:dmg = json.get(macro.args, "Damage")]
[h:tokid = json.get(macro.args, "Token")]
You hit [r: tokid] for [r:dmg] damage!
"Damage"
field and the "Token"
field.Equivalents
See Also
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)
.