macro.catchAssert

From RPTools Wiki
Jump to navigationJump to search

Introduced in version 1.5.0. The variable macro.catchAssert can be used to override the behavior of the default assert() function to continue execution instead of halting.

Whenever you set macro.catchAssert to 1, any use of assert() in a subsequently called macro will not assert, but will trigger a return from the macro instead.

The variable macro.catchAssert must be in the variable scope where the assert should be caught. It is not a general flag to turn off assert behavior, just temporarily in the macro or variable scope where it's set.

Usage

Set this variable to 0 (default assert behavior) or 1 (catch asserts).

[h: macro.catchAssert = 0]
[h: macro.catchAssert = 1]

Examples

When a macro is called by another macro, the called macro may use assert() to cancel execution and show an error message. Usually all macro execution would stop, so the calling macro would not continue. We can now override that default behavior by catching the assert (it will still show the error message).

Default behaviour

The macro below will only have "error occured" as output because the default behavior is that any call to assert() will stop the overall macro execution. Whatever code is defined after the call to assert() is not executed.

Default assert Macro
[h: resultText = "defaultValue"]
[h: resultText = assert(0, "error occured")]
[r: resultText]

Catching the assert

The macro below will output "error occured" and defaultValue as the macro.catchAssert set to 1 prevents the call to assert() from actually terminating execution. The example shows how to set a default value for any return value of a function/macro that has an assert() call in it. The macro then re-enables the normal function of assert() again by setting macro.catchAssert to 0. As each macro has its own variable scope, this only affects calls to assert() within the current macro or calls to other macros from the current macro. The exception is if the called macro shares the scope with the calling macro, in which case the assert() is ignored.

Catching assert
[h: macro.catchAssert = 1]
[h: resultText = "defaultValue"]
[h: resultText = assert(0, "error occured")]
[r: resultText]
[h: macro.catchAssert = 0]

Catching the assert with nested macro calls

Same as in the above example, the calling macro below will output "error occured" and defaultValue because we activate deferred asserts (in anything that this macro will call afterwards) with macro.catchAssert set to 1 .

Called macro using an assert as function doSomething() Calling macro catching an assert
[h: "this macro will do something and then assert"]
[h: "... doing something"]
[h: assert(0, "error occured")]
[h: macro.catchAssert= 1]
[h: resultText = "defaultValue"]
[h: resultText = doSomething()]
[r: resultText]
[h: macro.catchAssert= 0]

See also

assert()

Version changes

  • 1.5.0 - introduced macro.assertCatch