Calling macros

 This article is a stub, you can help the RPTools Wiki project by contributing content to expand this article.

Calling macros from a macro

Sometimes you want to call a macro from a macro. When you are a coder you want this really often. It enables you to split your code in small, simple chunks and reuses it over and over again.

This is a handy technique to keep stack size requirement low and to get rid of large code-level-nesting.

If you want to use macros from another macro, you will want to transfer data from the one to the other and vice versa. Its also important to know what happens with chat output.

4 Methods to call a macro

The macro roll option

This is the most straight forward way to do so. You use the roll option [macro():] where you can specify the macro location and give a single argument. Note that this argument must always be specified, even when you dont need it. Common practice is to use an empty string "" in such a case.

This argument can be accessed inside the called macro via the special variable macro.args.

All output will then be inserted into the calling macro at the place where the macro roll option is.

You can change that to a manually set value by setting macro.return.

Usually the macro roll option output is inserted into the chat output but you can assign it to a variable or use it in a function call. The macro.return can be used in the calling macro after the macro was called and processed.

User Defined Function

In the forums often encountered as UDF. This is probably the most convenient way when you do complex coding.

A user defined function can be used just like a regular function. It can have arguments and it will be replaced by its result value when MapTool parses the calling macro. User defined means that you can specify what macro should be called when you write the given function name.

Arguments are given to the UDF by writing them comma separated in the parentheses(). The complete macro chat output will be used as result value (this is important. HTML comments for example will be in this output too, although they cant be seen in the chat window) and replace the function call, so you can easily assign it to a variable or use it as argument for another function. Note that only the first macro in an execution chain will dump its output to the chat. In the called macro the arguments are inside the macro.args variable formatted as JSON array. You can use argCount() and arg() for easier access.

To set up a UDF you have to call defineFunction(). You can do this automatically if you place all defineFunction()-calls on a library token inside the special macro onCampaignLoad

A good read is aliasmask's version of automated UDF-creation: see post

Macro Links

When you want to call macros on user reaction you can sent out clickable links to the chat or into frames. This way is also to be used if you want to work with html forms or the fancier form-based events.

See also macroLink(), macroLinkText().

Evaluate A Macro

Never used this much.

See also evalMacro(), execMacro()

Variable context

Usually a new macro creates a new context for variables, so locally defined variables in the one macro are not defined in the other.

Using defineFunction() you can call macros that operate in the same variable context then the caller macro -- when you want so.

The token context is usually transported with the macro call. With macro links you can specify the token context.