abort

abort() Function

• Introduced in version 1.3b42

The abort() function 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.

If you prefer to display an error message when exiting the macro see the assert() function.

Usage

abort(abrt)

Parameters

abrt - 0 if 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.

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)

Version Changes

1.3b49 - No message is displayed if called from a macroLink.