abort: Difference between revisions
Jump to navigation
Jump to search
mNo edit summary |
|||
| (15 intermediate revisions by 9 users not shown) | |||
| Line 1: | Line 1: | ||
{{Languages|abort}} | |||
{{MacroFunction | {{MacroFunction | ||
|name=abort | |name=abort | ||
| Line 4: | Line 5: | ||
|description= | |description= | ||
Is used to conditionally abort the execution of a macro. If the argument to {{code|abort()}} is 0 then the execution of the macro stops and all macro output is discarded. If the argument to {{code|abort()}} is non zero then the macro continues. | |||
Note that only the output of the macro is discarded when the macro is aborted any changes made to macros will not be undone. | Note that only the output of the macro is discarded when the macro is aborted any changes made to macros will not be undone. | ||
| Line 13: | Line 14: | ||
* Silently bailing out of a macro if a certain condition is not met. | * Silently bailing out of a macro if a certain condition is not met. | ||
If you prefer to display an error message when exiting the macro see the [[assert | assert()]] function. | If you prefer to display an error message when exiting the macro see the [[assert | {{code|assert()}}]] function. | ||
|usage= | |usage= | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
abort( | abort(abrt) | ||
</ | </syntaxhighlight> | ||
'''Parameters''' | |||
{{param|abrt| {{code|0}} if the abort function should abort the macro, nonzero if it should not.}} | |||
|examples= | |examples= | ||
The following example will create a dialog box for the user to enter a value for the variable named blah, if the user clicks on cancel then res will be 0 so the abort() function will cause the macro to terminate, otherwise res will not be 0 so the macro will continue. | The following example will create a dialog box for the user to enter a value for the variable named blah, if the user clicks on cancel then res will be 0 so the abort() function will cause the macro to terminate, otherwise res will not be 0 so the macro will continue. | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
[h: res = input("blah")] [h: abort(res)] | [h: res = input("blah")] [h: abort(res)] | ||
</ | </syntaxhighlight> | ||
The following example discards any output in the macro. | The following example discards any output in the macro. | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
Hah! you will never see this! [abort(0)] | Hah! you will never see this! [abort(0)] | ||
</ | </syntaxhighlight> | ||
The following line can be used to protect macros that only the GM should run | The following line can be used to protect macros that only the GM should run | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
[h: abort(isGM())] | [h: abort(isGM())] | ||
</ | </syntaxhighlight> | ||
The following line can be used to silently end a macro that can only be run from a [[Trusted Macro]] | The following line can be used to silently end a macro that can only be run from a [[Trusted Macro]] | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
[h: abort(isTrusted())] | [h: abort(isTrusted())] | ||
</ | </syntaxhighlight> | ||
===Usage Notes=== | |||
When aborting a macro called from another macro (for example, a [[Token:library_token|library token]]), all macros are aborted, not just the one executing. | |||
Since 1.5.0 you can change that behaviour by using [[macro.catchAbort|macro.catchAbort]]. | |||
====Calling Macro==== | |||
<syntaxhighlight lang="mtmacro" line> | |||
<!-- Call the getAmmo library macro --> | |||
[MACRO("getAmmo@Lib:test"): "arrows"] | |||
You have [r:macro.return] arrows. | |||
</syntaxhighlight> | |||
====Called Macro==== | |||
<syntaxhighlight lang="mtmacro" line> | |||
<!-- getAmmo macro in Lib:test token --> | |||
[h: macro.return = 0] | |||
[h: abort(json.contains(ammunition, macro.args))] | |||
[h: macro.return = json.get(ammunition, macro.args)] | |||
</syntaxhighlight> | |||
====Results==== | |||
''assuming ammunition = { "arrows" : 30 }'' | |||
TokenName: You have 30 arrows. | |||
''assuming ammunition = { "bolts" : 20 }'' | |||
(nothing) | |||
|changes= | |changes= | ||
{{change|1.3b49|No message is displayed if called from a macroLink.}} | {{change|1.3b49|No message is displayed if called from a macroLink.}} | ||
{{change|1.5.0|catch an abort with macro.catchAbort}} | |||
|also= | |also= | ||
[[ assert|assert()]] | [[ assert|assert()]] | ||
[[ macro.catchAbort|macro.catchAbort]] | |||
}} | }} | ||
[[Category:Miscellaneous Function]] | [[Category:Miscellaneous Function]] | ||
{{Languages|abort}} | |||
Latest revision as of 23:59, 9 February 2023
abort() Function
• Introduced in version 1.3b42
Is used to conditionally abort the execution of a macro. If the argument to
abort() is 0 then the execution of the macro stops and all macro output is discarded. If the argument to abort() is non zero then the macro continues.
Note that only the output of the macro is discarded when the macro is aborted any changes made to macros will not be undone.
Common uses for this function are
- Ending a macro if the cancel button is clicked on an input dialog created using the input() function.
- Discarding all output generated by the macro, in effect making a "silent" macro.
- Silently bailing out of a macro if a certain condition is not met.
assert() function.Usage
abort(abrt)Parameters
abrt-0if the abort function should abort the macro, nonzero if it should not.
Examples
The following example will create a dialog box for the user to enter a value for the variable named blah, if the user clicks on cancel then res will be 0 so the abort() function will cause the macro to terminate, otherwise res will not be 0 so the macro will continue.
[h: res = input("blah")] [h: abort(res)]The following example discards any output in the macro.
Hah! you will never see this! [abort(0)]The following line can be used to protect macros that only the GM should run
[h: abort(isGM())]The following line can be used to silently end a macro that can only be run from a Trusted Macro
[h: abort(isTrusted())]Usage Notes
When aborting a macro called from another macro (for example, a library token), all macros are aborted, not just the one executing.
Since 1.5.0 you can change that behaviour by using macro.catchAbort.
Calling Macro
<!-- Call the getAmmo library macro -->
[MACRO("getAmmo@Lib:test"): "arrows"]
You have [r:macro.return] arrows.Called Macro
<!-- getAmmo macro in Lib:test token -->
[h: macro.return = 0]
[h: abort(json.contains(ammunition, macro.args))]
[h: macro.return = json.get(ammunition, macro.args)]Results
assuming ammunition = { "arrows" : 30 }
TokenName: You have 30 arrows.
assuming ammunition = { "bolts" : 20 }
(nothing)See Also
Version Changes
- 1.3b49 - No message is displayed if called from a macroLink.
- 1.5.0 - catch an abort with macro.catchAbort