macro.catchAbort: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(8 intermediate revisions by 5 users not shown)
Line 1: Line 1:
Introduced in version 1.5.0. The variable ''macro.catchAbort'' can be used to override the default [[abort | {{code|abort()}}]] function to continue execution post [[abort | {{code|abort()}}]] statement.
Introduced in version 1.5.0. The variable {{code|macro.catchAbort}} can be used to override the behavior of the default {{func|abort}} function to continue execution instead of halting.


Wherever you set {{code|macro.catchAbort}} to any subsequent call to another macro using [[abort | {{code|abort()}}]] will not abort the current macro. So the abort is caught and the calling macro will proceed with execution.
Whenever you set {{code|macro.catchAbort}} to {{code|1}}, any use of {{func|abort}} in a subsequently called macro will not abort, but will trigger a return from the macro instead.


The variable ''macro.catchAbort'' must be in the variable scope where the abort should be caught. It is not a general flag to turn off abort behavior; just temporarily in the macro or variable scope where it's set.
The variable {{code|macro.catchAbort}} must be in the variable scope where the abort should be caught. It is not a general flag to turn off abort behavior, just temporarily in the macro or variable scope where it's set.


==Usage==
==Usage==


Set this variable to 0 (default abort behaviour) or 1 (catch aborts).
Set this variable to {{code|0}} (default abort behavior) or {{code|1}} (catch aborts).


<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: macro.catchAbort = 0]
[h: macro.catchAbort = 1]
[h: macro.catchAbort = 1]
[h: macro.catchAbort = 0]
</syntaxhighlight>
</source>


==Examples==
==Examples==


When a macro is called by another macro, the called macro may use the {{func|abort}} to cancel execution. Usually all macro execution would stop, so the calling macro would not continue. We can now override that default behavior by ''catching'' the abort.
When a macro is called by another macro, the called macro may use {{func|abort}} to cancel execution. Usually all macro execution would stop, so the calling macro would not continue. We can now override that default behavior by ''catching'' the abort.


===Default behaviour===
===Default behaviour===


The macro below will not have any output because the default behavior is that any call to abort will stop the overall macro execution. Whatever code is defined after the call to abort is not executed.
The macro below will not have any output because the default behavior is that any call to {{func|abort}} will stop the overall macro execution. Whatever code is defined after the call to {{func|abort}} is not executed.


{| class="wikitable" border="1" style="border-collapse:collapse;"
{| class="wikitable" border="1" style="border-collapse:collapse;"
Line 26: Line 26:
!Default abort Macro
!Default abort Macro
|-
|-
|valign="top"|<source lang="mtmacro" line>
|valign="top"|<syntaxhighlight lang="mtmacro" line>
[h: resultText = "defaultValue"]
[h: resultText = "defaultValue"]
[h: resultText = abort(0)]
[h: resultText = abort(0)]
[r: resultText]
[r: resultText]
</source>
</syntaxhighlight>
|}
|}


===Catch the abort===
===Catching the abort===


The macro below will output "defaultValue" as the {{code|macro.catchAbort}} set to 1 preventing the call to {{func|abort}} from actually terminating execution. The example shows how to set a default value for any return value of a function/macro that has a abort call in it. The macro then re-enables the normal function of {{func|abort}} again by setting {{code|macro.catchAbort}} to 0. As each macro has its own variable scope, this only affects calls to {{func|abort}} within the current macro or calls to other macros from the current macro.
The macro below will output {{code|defaultValue}} as the {{code|macro.catchAbort}} set to {{code|1}} prevents the call to {{func|abort}} from actually terminating execution. The example shows how to set a default value for any return value of a function/macro that has an {{func|abort}} call in it. The macro then re-enables the normal function of {{func|abort}} again by setting {{code|macro.catchAbort}} to {{code|0}}. As each macro has its own variable scope, this only affects calls to {{func|abort}} 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 {{func|abort}} is ignored.


{| class="wikitable" border="1" style="border-collapse:collapse;"
{| class="wikitable" border="1" style="border-collapse:collapse;"
Line 41: Line 41:
!Catching abort
!Catching abort
|-
|-
|valign="top"|<source lang="mtmacro" line>
|valign="top"|<syntaxhighlight lang="mtmacro" line>
[h: macro.catchAbort = 1]
[h: macro.catchAbort = 1]
[h: resultText = "defaultValue"]
[h: resultText = "defaultValue"]
Line 47: Line 47:
[r: resultText]
[r: resultText]
[h: macro.catchAbort = 0]
[h: macro.catchAbort = 0]
</source>
</syntaxhighlight>
|}
|}


===Catch the abort with 2 macros===
===Catching the abort with nested macro calls===


Same as in the above example, the calling macro below will output "defaultValue" cause we activate catching aborts (in anything that this macro will call afterwards) with {{code|macro.catchAbort}} set to 1 .  
Same as in the above example, the calling macro below will output {{code|defaultValue}} because we activate catching aborts (in anything that this macro will call afterwards) with {{code|macro.catchAbort}} set to {{code|1}} .  


{| class="wikitable" border="1" style="border-collapse:collapse;"
{| class="wikitable" border="1" style="border-collapse:collapse;"
Line 59: Line 59:
!Calling macro catching an abort
!Calling macro catching an abort
|-
|-
|valign="top"|<source lang="mtmacro" line>
|valign="top"|<syntaxhighlight lang="mtmacro" line>
[h: "this macro will do something and then abort"]
[h: "this macro will do something and then abort"]
[h: "... doing something"]
[h: "... doing something"]
[h: abort(0)]
[h: abort(0)]
</source>
</syntaxhighlight>
|<source lang="mtmacro" line>
|<syntaxhighlight lang="mtmacro" line>
[h: macro.catchAbort= 1]
[h: macro.catchAbort= 1]
[h: resultText = "defaultValue"]
[h: resultText = "defaultValue"]
Line 70: Line 70:
[r: resultText]
[r: resultText]
[h: macro.catchAbort= 0]
[h: macro.catchAbort= 0]
</source>
</syntaxhighlight>
|}
|}


===See also===
===See also===
[[ abort|abort()]]
[[ abort|abort()]]
[[ assert|assert()]]


===Version changes===
===Version changes===
Line 80: Line 81:


[[Category:Special Variable]]
[[Category:Special Variable]]
[[Category:Macro Function]]

Latest revision as of 20:02, 4 July 2023

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

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

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

Usage

Set this variable to 0 (default abort behavior) or 1 (catch aborts).

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

Examples

When a macro is called by another macro, the called macro may use abort() to cancel execution. Usually all macro execution would stop, so the calling macro would not continue. We can now override that default behavior by catching the abort.

Default behaviour

The macro below will not have any output because the default behavior is that any call to abort() will stop the overall macro execution. Whatever code is defined after the call to abort() is not executed.

Default abort Macro
[h: resultText = "defaultValue"]
[h: resultText = abort(0)]
[r: resultText]

Catching the abort

The macro below will output defaultValue as the macro.catchAbort set to 1 prevents the call to abort() from actually terminating execution. The example shows how to set a default value for any return value of a function/macro that has an abort() call in it. The macro then re-enables the normal function of abort() again by setting macro.catchAbort to 0. As each macro has its own variable scope, this only affects calls to abort() 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 abort() is ignored.

Catching abort
[h: macro.catchAbort = 1]
[h: resultText = "defaultValue"]
[h: resultText = abort(0)]
[r: resultText]
[h: macro.catchAbort = 0]

Catching the abort with nested macro calls

Same as in the above example, the calling macro below will output defaultValue because we activate catching aborts (in anything that this macro will call afterwards) with macro.catchAbort set to 1 .

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

See also

abort() assert()

Version changes

  • 1.5.0 - introduced macro.abortCatch