macro.args: Difference between revisions
No edit summary |
m (Corrected a few headings) |
||
(9 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
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. | {{SpecialVariable | ||
|name=macro.args | |||
|description=The variable ''macro.args'' holds the value of the argument passed to a trusted macro via the [[macro (roll option)|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. | |||
===1: Single parameter=== | |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 [[Token:library_token|library token]] is called by another macro, the calling macro may pass one argument to the called macro: | When a macro on a [[Token:library_token|library token]] is called by another macro, the calling macro may pass one argument to the called macro: | ||
====Calling Macro==== | ==== Calling Macro ==== | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
<!-- Call the getDamage macro --> | <!-- Call the getDamage macro --> | ||
[h:damageDice="2d6"] | [h:damageDice="2d6"] | ||
[MACRO("getDamage@Lib:test"): damageDice] | [MACRO("getDamage@Lib:test"): damageDice] | ||
</ | </syntaxhighlight> | ||
====Called Macro==== | ==== Called Macro ==== | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
<!-- getDamage Macro --> | <!-- getDamage Macro --> | ||
[h:damageRoll = eval(macro.args) + 9] | [h:damageRoll = eval(macro.args) + 9] | ||
You hit your target for [r:damageRoll] damage! | You hit your target for [r:damageRoll] damage! | ||
</ | </syntaxhighlight> | ||
In the example above, ''damageDice'' is the argument being passed to the macro '''getDamage''', which resides on the '''Lib:test''' [[Token:library_token|library token]]. Within the '''getDamage''' macro, the variable {{code|macro.args}} is automatically generated and assigned the value of ''damageDice''. | In the example above, ''damageDice'' is the argument being passed to the macro '''getDamage''', which resides on the '''Lib:test''' [[Token:library_token|library token]]. Within the '''getDamage''' macro, the variable {{code|macro.args}} is automatically generated and assigned the value of ''damageDice'' (which is a [[string]]). | ||
It's important to note that only a <u>single</u> parameter can be passed to a macro and that parameter appears in the {{code|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 {{code|[[defineFunction|user-defined function]]}}. | It's important to note that only a <u>single</u> parameter can be passed to a macro and that parameter appears in the {{code|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 {{code|[[defineFunction|user-defined function]]}}. All three techniques are demonstrated next. | ||
===2A: Multiple parameters using String Property List=== | === 2A: Multiple parameters (using String Property List) === | ||
A | 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==== | ==== Calling Macro ==== | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
<!-- Call the doDamage macro --> | <!-- Call the doDamage macro --> | ||
[h:damageDice="2d6"] | [h:damageDice="2d6"] | ||
[h:theToken = "Bobo Fett"] | [h:theToken = "Bobo Fett"] | ||
[MACRO("getDamage@Lib:test"): "Damage="+damageDice+"; Token="+theToken] | [MACRO("getDamage@Lib:test"): "Damage="+damageDice+"; Token="+theToken] | ||
</ | </syntaxhighlight> | ||
====Called Macro==== | ==== Called Macro ==== | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
<!-- doDamage Macro --> | <!-- doDamage Macro --> | ||
[h:dmg = getStrProp(macro.args, "Damage")] | [h:dmg = getStrProp(macro.args, "Damage")] | ||
[h:tokid = getStrProp(macro.args, "Token")] | [h:tokid = getStrProp(macro.args, "Token")] | ||
You hit [r: tokid] for [r:dmg] damage! | You hit [r: tokid] for [r:dmg] damage! | ||
</ | </syntaxhighlight> | ||
It's important to note that the default delimiter, a {{code|;}} (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 {{func|encode}} and {{func|decode}} or one of the following two approaches.) | |||
===2B: Multiple parameters using JSON Array=== | === 2B: Multiple parameters (using JSON Array) === | ||
The second way to pass multiple parameters is to use a [[JSON Array]] or [[JSON Object]]. | 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 | 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 {{func|json.append}} is being passed {{code|"[]"}} 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 | ==== Calling Macro ==== | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
<!-- Call the doDamage macro --> | <!-- Call the doDamage macro --> | ||
[h:damageDice="2d6"] | [h:damageDice="2d6"] | ||
[h:theToken = "Bobo Fett"] | [h:theToken = "Bobo Fett"] | ||
[h:jsonData = json. | [h:jsonData = json.append("[]", damageDice, theToken)] | ||
[MACRO("getDamage@Lib:test"): jsonData] | [MACRO("getDamage@Lib:test"): jsonData] | ||
</ | </syntaxhighlight> | ||
====Called Macro | ==== Called Macro ==== | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
<!-- doDamage Macro --> | <!-- doDamage Macro --> | ||
[h:dmg = json.get(macro.args, 0)] | [h:dmg = json.get(macro.args, 0)] | ||
[h:tokid = json.get(macro.args, 1)] | [h:tokid = json.get(macro.args, 1)] | ||
You hit [r: tokid] for [r:dmg] damage! | You hit [r: tokid] for [r:dmg] damage! | ||
</ | </syntaxhighlight> | ||
Because a [[JSON Array]] is being used to pass in the data, the calls to {{func|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) === | |||
====Calling Macro | In this next example, the {{func|json.set}} is being passed {{code|"{}"}} as the first parameter. This indicates to the function that we are setting values on an empty [[JSON Object]]. | ||
< | |||
==== Calling Macro ==== | |||
<syntaxhighlight lang="mtmacro" line> | |||
<!-- Call the doDamage macro --> | <!-- Call the doDamage macro --> | ||
[h:damageDice="2d6"] | [h:damageDice="2d6"] | ||
Line 81: | Line 94: | ||
[h:jsonData = json.set("{}", "Damage", damageDice, "Token", theToken)] | [h:jsonData = json.set("{}", "Damage", damageDice, "Token", theToken)] | ||
[MACRO("getDamage@Lib:test"): jsonData] | [MACRO("getDamage@Lib:test"): jsonData] | ||
</ | </syntaxhighlight> | ||
====Called Macro | ==== Called Macro ==== | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
<!-- doDamage Macro --> | <!-- doDamage Macro --> | ||
[h:dmg = json.get(macro.args, "Damage")] | [h:dmg = json.get(macro.args, "Damage")] | ||
[h:tokid = json.get(macro.args, "Token")] | [h:tokid = json.get(macro.args, "Token")] | ||
You hit [r: tokid] for [r:dmg] damage! | You hit [r: tokid] for [r:dmg] damage! | ||
</ | </syntaxhighlight> | ||
With [[JSON Object|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 {{func|json.get}} is told to retrieve the {{code|"Damage"}} field and the {{code|"Token"}} field. | |||
|equivmacro= | |||
The {{func|arg}} function will show the contents of ''macro.args'' if it is not a JSON array or JSON object. | |||
|also= | |||
{{roll|macro}}, {{func|defineFunction}}, [[macro.return]] | |||
User defined functions can also use ''macro.args'', and have some related/replacement functions: | |||
* {{func|argCount}} will display the number of items if ''macro.args'' is a JSON array; otherwise, it will return 0. | |||
{{ | * {{func|arg}} will work as normal if ''macro.args'' is a JSON array; otherwise, will return all of ''macro.args'' when invoked as <code>arg(0)</code>. | ||
}} | |||
[[Category:Special Variable]] | [[Category:Special Variable]][[Category:Macro Function]] |
Latest revision as of 05:01, 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)
.