View source for Macros:Branching and Looping

This page details the branching and looping structures in MapTool. With the exception of the Block If statement, these are all [[Macros:Roll:types | roll options]] and should follow the general form for roll options:

<source lang="mtmacro" line>
[option1[,option2]: body]
</source>

These may be combined with other roll options (note that in some examples, they are combined with the [[Macros:Roll:types#.5B_.5D_Hidden_Rolls | Hidden Roll]] option (''h'') to hide the default output of the loop or branch). 

'''If you wish to combine roll options in a single statement, separate the roll options with a comma, and place the colon at the end of the sequence of roll options.''' 

For example, if you want to combine a Hidden Roll, TOKEN(), and FOREACH() option in a single statement, you would enter the line like so:

<source lang="mtmacro" line>
[H,TOKEN("JoeRandom"),FOREACH(item, TokensItemList): "This item's name is "+item+"!"]
</source>


==Branching==

===IF Option===

'''Introduced''': Version 1.3.b46

This IF is a roll option (as mentioned above), but operates similarly to the block-style if.

====Usage====
<source lang="mtmacro" line>
[IF(condition): true_body; false_body]
</source>

;or
<source lang="mtmacro" line>
[IF(condition): true_body]
</source>

Either the ''true_body'' or ''false_body'' will be used, depending on the value of ''condition''. If the ''false_body'' is not given but the ''condition'' is false, then there is no output.

====Example====
<source lang="mtmacro" line>
[h:val=12]
[h,IF(val == 12): newVal=12*12]
New Value = [r:newVal]
</source>

Outputs ''New Value = 144''.

====Note====

For an alternate method for evaluating "if" conditions, see the function [[Macros:Functions:if|if()]].

===SWITCH Option===

'''Introduced''': Version 1.3.b46

SWITCH chooses among several options and executes code based on the switch expression. 

Note that the ''expression'' is a regular expression, so metacharacters such as '''*''' and '''()''' will need to have backslashes in front of them if you want to match them literally.

====Usage====

<source lang="mtmacro" line>
[SWITCH(expression):
case case1: body1;
case case2: body2;
default: default_body]
</source>

====Example====

<source lang="mtmacro" line>
[h:powerType="at-will"]
[SWITCH(powerType):
case "at-will": "You may use this power as much as you like";
case "encounter": "You may only use this power once per encounter";
case "daily": "You may only use this power once per day"]
</source>

Outputs "You may use this power as much as you like"

<source lang="mtmacro" line>
[h:powerType=".*sword.*"]
[SWITCH(powerType):
case "flail": "one-handed weapon; two-handed does Str*2 damage";
case "shortsword": "used for jabs, so is a puncturing weapon";
case "longsword": "a slashing weapon"]
</source>

Outputs "used for jabs, so is a puncturing weapon".  Notice that the first matching clause was the one that the SWITCH() option found.

===MACRO Option===

'''Introduced''': Version 1.3.b46

MACRO runs the named macro, inserting its text into chat.

====Usage====

<source lang="mtmacro" line>
[MACRO("macro_name@location"): macro_arguments]
</source>

The called macro sees a variable called [[Macros:Special_Variables:macro.args|''macro.args'']] which contains the value of ''macro_arguments''. The called macro can set a variable called [[Macros:Special_Variables:macro.return|''macro.return'']], which becomes available to the calling macro. Other than ''macro.return'', the called macro shares no variables with the calling macro.

====Examples====

<source lang="mtmacro" line>
[MACRO("getDamage@Lib:combat"): damageRoll]
</source>

Calls the macro "getDamage" which resides on a [[Token:library_token|library token]] called "Lib:combat", and passes the variable ''damageRoll'' as an argument to the called macro. 

====Location Requirements====

The ''location'' can be one of the following:

# TOKEN - the currently impersonated token (use the word "TOKEN", not the token's name)
# Library Token - a [[Token:library_token|Library Token]] in the current campaign
# ''this'' - if the macro is calling another macro in the same library, "this" may be used instead of retyping the full library token name

====Notes====

When a token macro calls another macro, the macro instructions in the ''called'' macro are executed against the ''calling'' token (in other words, the macro uses properties available on the calling token and applies all results to that token), unless the focus is explicitly changed to another token via either a roll option, or the [[Macros:Functions:switchToken|switchToken()]] function, or the [[Macros:Functions:getLibProperty|getLibProperty()]] function.

Also- as of at least 1.3.b50- a variable must be given for ''macro_arguments'', or the 
"Could not execute the command: Undefined function: MACRO"
error will result.  However, the variable given as ''macro_arguments'' doesn't have to be used.

===TOKEN Option===

'''Introduced''': Version 1.3.b48

TOKEN executes a series of instructions against a token specified in the argument to [TOKEN():], rather than against the token running the macro. 

This is a temporary change in the token that has the "focus" - only the instructions following the colon are applied to the designated token; following the end of that instruction block, operations resume being performed against the token running the macro.

To permanently switch (for the duration of the macro) the token against which macro commands are executed, see the [[Macros:Functions:switchToken|switchToken()]] function.

====Usage====

<source lang="mtmacro" line>
[token(token_identifier): ]
</source>

Executes the roll against token specified by ''token_identifier'', which can either be the token name or token id.

====Examples====

<source lang="mtmacro" line>
[h:target="Orc 5"]
[h,token(target): targetAC = getProperty("AC")]
</source>

Uses the [[Macros:Functions:getProperty|getProperty()]] function to retrieve the property ''AC'' from the token named "Orc 5", and assigns that value to the variable ''targetAC''. ''targetAC'' can be used in future calculations, such as determining whether an attack hits. If the TOKEN option was not used, the macro would have looked for the property ''AC'' on the token currently ''running'' the macro. Note also that this function is considered [[Macros:TrustedMacros|trusted]].

==Looping==

===COUNT Option===

'''Introduced''': Version 1.3.b41

The COUNT option executes a statement for a specified number of times, storing the number of the current iteration in a variable called ''[[Macros:Special_Variables:roll.count|roll.count]]''. 

====Usage====
<source lang="mtmacro" line>
[COUNT(num): body]
[COUNT(num, separator): body]
</source>

The ''[[roll.count]]'' variable will take on values from 0 to (number of loops - 1). The optional separator (default ", ") is printed between each iteration.

====Example====
<source lang="mtmacro" line>
[h:numHits=3]
[COUNT(numHits): Damage = Damage + 1d12]
</source>

This will iterate the ''Damage = Damage + 1d12'' operation 3 times, separating the result of each iteration with the default separator (a comma). An optional second argument to COUNT() allows the setting of a different separator.

===FOR Option===

'''Introduced''': Version 1.3.b46

Executes a statement for a number of iterations based on a start and end value.

====Usage====

<source lang="mtmacro" line>
[FOR(var, start, end): body]
[FOR(var, start, end, stepsize): body]
[FOR(var, start, end, stepsize, separator): body]
</source>

The ''var'' variable counts from ''start'' to ''end'' during the loop. The optional ''stepsize'' (default +1) is added to var at each iteration. The loop does ''not'' evaluate when {{code|var}} reaches {{code|end}}. 

====Example====
<source lang="mtmacro" line>
[FOR(i,10,0,-2): "i is now " + i]
</source>

Counts down even numbers from 10 to 0.

===FOREACH Option===

'''Introduced''': Version 1.3.b46

Iterates over the contents of a string list in the format "''item1, item2, item3''"

====Usage====
<source lang="mtmacro" line>
[FOREACH(var, list): body]
[FOREACH(var, list, output_separator): body]
[FOREACH(var, list, output_separator, list_separator): body]
</source>

====Example====
<source lang="mtmacro" line>
[h: enemyList="Orcs, Goblins, Ogres, Trolls"]
[FOREACH(enemy, enemyList, "<br>"): "You really hate " + enemy]
</source>

Outputs
 You really hate Orcs
 You really hate Goblins
 You really hate Ogres
 You really hate Trolls

===WHILE Option===

'''Introduced''': Version 1.3.b46

Repeatedly executes a statement until a condition becomes false.

====Usage====
<source lang="mtmacro" line>
[WHILE(condition): body]
[WHILE(condition, separator): body]
</source>

====Example====
<source lang="mtmacro" line>
[h:num=10]
[WHILE(num>=0): num = num-1]
</source>

Outputs ''9,8,7,6,5,4,3,2,1''

==Code Execution==

===CODE===

'''Introduced''': Version 1.3.b46

The CODE option is used in conjunction with looping / branching options to execute multiple statements within a single "block" of a loop or branch, allowing the creation of more complex loops and branches. 

====Usage====
<source lang="mtmacro" line>
[CODE: { code_block }]
</source>

The ''code_block'' is a collection of text and macro code, enclosed in a single {} pair. Everything within the {} is treated as a single block for the purposes of any looping or branching options.

====Example====

<source lang="mtmacro" line>
[h:num=5]
[WHILE(num > 0), CODE:
{
  This is iteration [r:num] <br>
  There are [r:num-1] iterations left<br>
  [num=num-1]
}]
</source>

Outputs

 This is iteration 5 There are 4 iterations left
 4, This is iteration 4 There are 3 iterations left
 3, This is iteration 3 There are 2 iterations left
 2, This is iteration 2 There are 1 iterations left
 1, This is iteration 1 There are 0 iterations left
 0

'''NOTE''': the digit output at the beginning of each line is an artifact of the WHILE loop's evaluation of ''num'' - since this roll does not have the ''h'' option active, the result of that evaluation is displayed.

====Nested CODE Blocks====

To nest CODE:{} blocks, use a second CODE:{ } option, like so:

<source lang="mtmacro" line>
[h:d20roll=1d20]
[h:attackRoll=d20roll+AttackBonus]
[h,IF(attackRoll >= 16),CODE:
{
  [IF(d20roll == 20),CODE:
  {
    The attack is a critical hit!
    [h:damage=critDamage]
  };
  {
    The attack is a hit!
    [h:damage=regDamage]
  };]
};
{
  The attack misses!
};]
</source>

MapTool can only handle two levels of nested code.


==Additions==

Conditional Operators:
* {{code|>}} - Greater than
* {{code|<}} - Less than
* {{code|>{{=}}}} - Greater than or equal to
* {{code|<{{=}}}} - Less than or equal to
* {{code|{{=}}{{=}}}} - Equal to
* {{code|!{{=}}}} or {{code|ne}} - Not equal

Logical Operators:
* {{code|&&}} - And
* {{code|{{!}}{{!}}}} - Or

Boolean Operators:
* {{code|true}}
* {{code|false}}

It is important to note that the ''Equal'' condition operator must be two equal signs. If you are checking for a text string, place quotes around the text.