macro.args: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
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. " "


==Examples==
|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 ====
<source lang="mtmacro" line>
<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]
</source>
</syntaxhighlight>


====Called Macro====
==== Called Macro ====
<source lang="mtmacro" line>
<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!
</source>
</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]]}}.  The first two techniques are demonstrated below.
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 string property list essentially bundles multiple values into a single string which would then be split back apart inside the macro body.
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 ====
<source lang="mtmacro" line>
<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]
</source>
</syntaxhighlight>


====Called Macro====
==== Called Macro ====
<source lang="mtmacro" line>
<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!
</source>
</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 coming into the macro but because it's either an array or an object you can retrieve individual fields quite easily.
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.


As the {{func|json.set}} is being passed {{code|"[]"}} as the first parameter in this next code block, the data type being created is a [[JSON Array]].
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 using JSON Array====
==== Calling Macro ====
<source lang="mtmacro" line>
<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.set("[]", damageDice, theToken)]
[h:jsonData = json.append("[]", damageDice, theToken)]
[MACRO("getDamage@Lib:test"): jsonData]
[MACRO("getDamage@Lib:test"): jsonData]
</source>
</syntaxhighlight>


====Called Macro using JSON Array====
==== Called Macro ====
<source lang="mtmacro" line>
<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!
</source>
</syntaxhighlight>


===2C: Multiple parameters using JSON Object===
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).


Notice that in this next example, the {{func|json.set}} is being passed {{code|"{}"}} as the first parameter.  This indicates to the function that we want a [[JSON Object]].
=== 2C: Multiple parameters (using JSON Object) ===


====Calling Macro using JSON Object====
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]].
<source lang="mtmacro" line>
 
==== 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]
</source>
</syntaxhighlight>


====Called Macro using JSON Object====
==== Called Macro ====
<source lang="mtmacro" line>
<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!
</source>
</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]]


==See Also==
User defined functions can also use ''macro.args'', and have some related/replacement functions:
[[macro.return]],
* {{func|argCount}} will display the number of items if ''macro.args'' is a JSON array; otherwise, it will return 0.
{{roll|macro}}
* {{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

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

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