defineFunction: Difference between revisions
Jump to navigation
Jump to search
m (Adding getDefinedFunctions to See Also list) |
m (Add interaction between ignoreOutput and macro.return) |
||
| Line 22: | Line 22: | ||
{{param|ignoreOutput|If the defined function should ignore all output and only return the value of {{code|macro.return}}, defaults to {{false}}.}} | {{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. Updating variables in the parent's scope includes over-writing any parameters that a parent might have stored within {{func|arg}}, if a user-defined function that does not create a new scope is called within another user-defined function.}} | {{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. Updating variables in the parent's scope includes over-writing any parameters that a parent might have stored within {{func|arg}}, if a user-defined function that does not create a new scope is called within another user-defined function.}} | ||
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. | |||
|example= | |example= | ||
Revision as of 18:14, 12 June 2021
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 ofmacro.return, defaults tofalse(0).newScope- If the defined function should create a new variable scope when executed, defaults totrue(1). 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. Updating variables in the parent's scope includes over-writing any parameters that a parent might have stored within arg(), if a user-defined function that does not create a new scope is called within another user-defined function.
Interactions between the ignoreOutput parameter and the macro.return special variable:
- If the UDF sets the value of macro.return and
ignoreOutputis0then any output is the return value and macro.return has the value assigned.
- If the UDF sets the value of macro.return and
ignoreOutputis1then 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
ignoreOutputis0then that output is the return value and macro.return is empty.
- If the UDF has output to chat, macro.return is not set and
ignoreOutputis1then the return value and macro.return are 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)]See Also
Version Changes
- 1.3b56 - Added
ignoreOutputandnewScopeparameter options.