assert: Difference between revisions

Latest revision as of 23:59, 14 March 2023

assert() Function

• Introduced in version 1.3b49

Halts execution and prints a custom error message if a condition is false(0). Note that the error message will be displayed in chat even if the command itself is in a [H: ] block.

Usage

assert(condition, message)

assert(condition, message, prefix)

Parameters

condition - The test condition that must evaluate to true(1) for the macro to continue.
message - The custom error message that is presented if the macro is halted due to the false(0) condition.
prefix - Determines if the error message should have the message prefix "Macro defined error: ". Defaults to true(1), set to false(0) if you do not wish your custom error message to have the message prefix.

Examples

Checks to see if a player is a GM, and if they are not halts execution of the macro and displays output.

[h: assert(isGM(),"This macro is for GM use only.",0)]

Chat output (if player is not GM): This macro is for GM use only.

Halts execution of the macro if var is a number. This is useful for making sure the variables you work with are the variable type you expect.

[h: assert(! isNumber(var), "The variable is a number.",1)]

Chat output (if var is a number): Macro defined error: The variable is a number.

Bear in mind, isNumber(var) returns true(1) when var is a number, but assert continues when condition is true(1). Using ! isNumber(var) inverts the boolean value.

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.catchAssert.

Version Changes

1.3b51 - Added prefix parameter option.
1.5.0 - catch an assert with macro.catchAssert

@@ Line 1: / Line 1: @@
-From b49 announcements:
+{{MacroFunction
+|name=assert
+|version=1.3b49
+|description=
+Halts execution and prints a custom error message if a condition is {{false}}.  Note that the error message will be displayed in chat even if the command itself is in a {{code|[H:&nbsp;]}} block.
-* New function: assert(condition, message) - if condition is zero, halts execution and prints a custom error message.
+|usage=
+<syntaxhighlight lang="mtmacro" line>
+assert(condition, message)
+</syntaxhighlight>
+<syntaxhighlight lang="mtmacro" line>
+assert(condition, message, prefix)
+</syntaxhighlight>
+'''Parameters'''
+{{param|condition|The test condition that must evaluate to {{true}} for the macro to continue.}}
+{{param|message|The custom error message that is presented if the macro is halted due to the {{false}} condition.}}
+{{param|prefix|Determines if the error message should have the message prefix {{code|"Macro defined error: "}}. Defaults to {{true}}, set to {{false}} if you do not wish your custom error message to have the message prefix.}}
-Note that the error message will be displayed in chat even if the command itself is in a [H: ] block.
+|examples=
+Checks to see if a player is a GM, and if they are not halts execution of the macro and displays output.
+<syntaxhighlight lang="mtmacro" line>
+[h: assert(isGM(),"This macro is for GM use only.",0)]
+</syntaxhighlight>
+Chat output (if player is not GM): {{code|This macro is for GM use only.}}
+Halts execution of the macro if {{code|var}} is a number.  This is useful for making sure the variables you work with are the variable type you expect.
+<syntaxhighlight lang="mtmacro" line>
+[h: assert(! isNumber(var), "The variable is a number.",1)]
+</syntaxhighlight>
+Chat output (if {{code|var}} is a number): {{code|Macro defined error: The variable is a number.}}
+Bear in mind, {{code|isNumber(var)}} returns {{true}} when var is a number, but assert continues when condition is {{true}}.  Using {{code|! isNumber(var)}} inverts the boolean value.
+===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.catchAssert.
+|also=
+{{ func|isGM}}
+{{ func|isNumber}}
+{{ func|abort}}
+[[ macro.catchAssert|macro.catchAssert]]
+|changes=
+{{change|1.3b51|Added {{code|prefix}} parameter option.}}
+{{change|1.5.0|catch an assert with macro.catchAssert}}
+}}
+[[Category:Miscellaneous Function]]