defineFunction: Difference between revisions

Latest revision as of 23:59, 3 July 2023

This article is a stub, you can help the RPTools Wiki project by contributing content to expand this article.
This article needs: Could use examples of the ignoreOutput and newScope parameters.

defineFunction() Function

Note: This function can only be used in a Trusted Macro

• Introduced in version 1.3b51

Defines a user function that can be used anywhere that core functions can be used. A user defined function is a link to another macro. A special macro labeled onCampaignLoad is useful for defining functions upon the loading of your campaign. This because the function will be defined AFTER the macro has been run. In case of onCampaignLoad, that macro is always run when the campaign is loaded. This saves you the hassle of manually requiring to run this macro to enable the definition.

Usage

defineFunction(function, macro)
defineFunction(function, macro, ignoreOutput)
defineFunction(function, macro, ignoreOutput, newScope)

Parameters

function - The name of the user defined function to be defined.
macro - The name and location of the macro that is called when the user defined function is used.
ignoreOutput - If the defined function should ignore all output and only return the value of macro.return, defaults to false(0).
newScope - Whether the defined function should create a new variable scope when executed. Defaults to true(1). In the default setting, a function can reference only those variables it sets itself, variables passed to it, and global variables defined in token properties. When set to false(0), this function may reference variables defined in the calling function.

Note: Best practice is to use the default setting. The danger lies in inadvertently changing values in the calling function which makes it difficult to track down where the variable is being changed. Using a prefix on your variable declarations like v_varName is one practice to insure this doesn't happen and is a good visual indicator that the function shares a scope with the calling function. There is still a risk, however, as the calling function could've defined its variables with the same prefix!

Interactions between the ignoreOutput parameter and the macro.return special variable:

If the UDF sets the value of macro.return and ignoreOutput is 0 then any output is the return value and macro.return has the value assigned.

If the UDF sets the value of macro.return and ignoreOutput is 1 then the return value is the value assigned to macro.return and macro.return has the value assigned.

If the UDF has output to chat, macro.return is not set and ignoreOutput is 0 then that output is the return value and macro.return is empty.

If the UDF has output to chat, macro.return is not set and ignoreOutput is 1 then the return value and macro.return are empty.

The following table summarizes how these parameters are used. It assumes that the user-defined function is named UDF and is invoked as in [var = UDF()]

Summary of `macro.return` and `ignoreOutput` parameter usage
UDF Code	`ignoreOutput`	Output Result	Return Result
`[h: macro.return="abc"] def`	`0`	`"def"` stored in `var`	`macro.return` contains `"abc"`
`[h: macro.return="abc"] def`	`1`	`"abc"` stored in `var`	`macro.return` contains `"abc"`
macro.return not set `def`	`0`	`"def"` stored in `var`	`macro.return` is empty
macro.return not set `def`	`1`	`var` is empty	`macro.return` is empty

Example

[h: defineFunction("character.heal", "heal@Lib:Character")]

Defines a function character.heal() which calls heal@Lib:Character when evoked. Note that in this case there must exist a function called "heal" on a token called "lib:Character". The advantage of using the prefix "lib:" on the token name is that it becomes a "lib:token" which is accessible from ANY map instead of only the map you happen to have active.

Should you pass on any arguments e.g.

[h: character.heal("hello", "hi")]

then these parameters can be accessed inside character.heal() by using

[h: firstArg = arg(0)]
[h: theOtherOne = arg(1)]

Version Changes

1.3b56 - Added ignoreOutput and newScope parameter options.

@@ Line 5: / Line 5: @@
 |version=1.3b51
 |description=
-Defines a user function that can be used anywhere that core functions can be used. A user defined function is a link to another macro.
+Defines a user function that can be used anywhere that core functions can be used. A user defined function is a link to another macro. A special macro labeled [[onCampaignLoad]] is useful for defining functions upon the loading of your campaign. This because the function will be defined AFTER the macro has been run. In case of [[onCampaignLoad]], that macro is always run when the campaign is loaded. This saves you the hassle of manually requiring to run this macro to enable the definition.
 |usage=
-<source lang="mtmacro" line>
+<syntaxhighlight lang="mtmacro" line>
 defineFunction(function, macro)
-</source>
-<source lang="mtmacro" line>
 defineFunction(function, macro, ignoreOutput)
-</source>
-<source lang="mtmacro" line>
 defineFunction(function, macro, ignoreOutput, newScope)
-</source>
+</syntaxhighlight>
 '''Parameters'''
 {{param|function|The name of the user defined function to be defined. }}
 {{param|macro|The name and location of the macro that is called when the user defined function is used.}}
 {{param|ignoreOutput|If the defined function should ignore all output and only return the value of {{code|macro.return}}, defaults to {{false}}.}}
-{{param|newScope|If the defined function should create a new variable scope when executed, defaults to {{true}}. A new variable scope means that the defined function can only read the variables of the macro that called it; if you do not create a new scope the defined function can read, update, and create variables in its parent's variable scope.}}
+{{param|newScope|Whether the defined function should create a new variable scope when executed. Defaults to {{true}}. In the default setting, a function can reference only those variables it sets itself, variables passed to it, and global variables defined in token properties. When set to {{false}}, this function may reference variables defined in the calling function.
+{{note|Note: Best practice is to use the default setting. The danger lies in inadvertently changing values in the calling function which makes it difficult to track down where the variable is being changed. Using a prefix on your variable declarations like {{code|'''v_'''varName}} is one practice to insure this doesn't happen and is a good visual indicator that the function shares a scope with the calling function.  There is ''still'' a risk, however, as the calling function could've defined its variables with the same prefix!}} }}
+Interactions between the {{code|ignoreOutput}} parameter and the [[macro.return]] special variable:
+* If the UDF sets the value of [[macro.return]] and {{code|ignoreOutput}} is {{code|0}} then any output is the return value and [[macro.return]] has the value assigned.
+* If the UDF sets the value of [[macro.return]] and {{code|ignoreOutput}} is {{code|1}} then the return value is the value assigned to [[macro.return]] and [[macro.return]] has the value assigned.
+* If the UDF has output to chat, [[macro.return]] is not set and {{code|ignoreOutput}} is {{code|0}} then that output is the return value and [[macro.return]] is empty.
+* If the UDF has output to chat, [[macro.return]] is not set and {{code|ignoreOutput}} is {{code|1}} then the return value and [[macro.return]] are empty.
+The following table summarizes how these parameters are used.  It assumes that the user-defined function is named {{code|UDF}} and is invoked as in <code>[var = UDF()]</code>
+<!-- It seems to be impossible to insert a table inside a template.
+    The vertical bar ("&brvbar;") is used as the separator between parameters to
+    the template, so "{&brvbar;" indicates a new parameter and not the beginning
+    of a wiki table.  Even using {{!}} to generate a vertical bar doesn't seem to
+    work.  I also tried {<nowiki/>{{!}} with no luck.
+{<nowiki/>{{!}}
+|+ Summary of [[macro.return]] and {{code|ignoreOutput}} parameter
+|-
+! [[macro.return]] !! {{code|ignoreOutput}} !! Called By !! Output Result !! Return Result
+|-
+| [h: macro.return="abc"]def || {{code|0}} || [var=UDF()] || {{code|"def"}} stored in {{code|var}} || [[macro.return]] contains {{code|"abc"}}
+|}
+    So here's the table in raw HTML.
+-->
+<table class="wikitable" style="margin:auto; width:100%">
+<caption>Summary of {{code|macro.return}} and {{code|ignoreOutput}} parameter usage</caption>
+<tr><th>UDF Code
+    <th>{{code|ignoreOutput}}
+    <th>Output Result
+    <th>Return Result
+</tr>
+<tr><td><code>[h: macro.return="abc"]<br/>def</code>
+    <td>{{code|0}}
+    <td>{{code|"def"}} stored in {{code|var}}
+    <td>{{code|macro.return}} contains {{code|"abc"}}
+</tr>
+<tr><td><code>[h: macro.return="abc"]<br/>def</code>
+    <td>{{code|1}}
+    <td>{{code|"abc"}} stored in {{code|var}}
+    <td>{{code|macro.return}} contains {{code|"abc"}}
+</tr>
+<tr><td>''macro.return not set''<br/><code>def</code>
+    <td>{{code|0}}
+    <td>{{code|"def"}} stored in {{code|var}}
+    <td>{{code|macro.return}} is empty
+</tr>
+<tr><td>''macro.return not set''<br/><code>def</code>
+    <td>{{code|1}}
+    <td>{{code|var}} is empty
+    <td>{{code|macro.return}} is empty
+</tr>
+</table>
 |example=
-<source lang="mtmacro" line>
+<syntaxhighlight lang="mtmacro" line>
 [h: defineFunction("character.heal", "heal@Lib:Character")]
-</source>
+</syntaxhighlight>
+Defines a function {{code|character.heal()}} which calls {{code|heal@Lib:Character}} when evoked. Note that in this case there must exist a function called "heal" on a token called "lib:Character". The advantage of using the prefix "lib:" on the token name is that it becomes a "lib:token" which is accessible from ANY map instead of only the map you happen to have active.
-Defines a function {{code|character.heal()}} which calls {{code|heal@Lib:Character}} when evoked.
+Should you pass on any arguments e.g.
+<syntaxhighlight lang="mtmacro" line>
+[h: character.heal("hello", "hi")]
+</syntaxhighlight>
+then these parameters can be accessed inside {{code|character.heal()}} by using
+<syntaxhighlight lang="mtmacro" line>
+[h: firstArg = arg(0)]
+[h: theOtherOne = arg(1)]
+</syntaxhighlight>
 |also=
-{{func|oldFunction}}
+{{func|oldFunction}},
+{{func|getDefinedFunctions}},
+{{func|arg}},
+{{func|argCount}},
+[[onCampaignLoad]]
 |changes=

defineFunction: Difference between revisions

Latest revision as of 23:59, 3 July 2023

Contents

defineFunction() Function

Usage

Example

See Also

Version Changes

Navigation menu