macro.catchAbort: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
(new macro.catchAbort to catch an abort during macro execution)
 
No edit summary
Line 1: Line 1:
Introduced in version 1.5.0. The variable ''macro.catchAbort'' can be used to make sure that the overall macro execution is not aborted if a called macro uses the [[abort | {{code|abort()}}]] function.
Introduced in version 1.5.0. The variable ''macro.catchAbort'' can be used to make sure that the overall macro execution is not aborted if a called macro uses the [[abort | {{code|abort()}}]] function.
Whereever you set {{code|macro.catchAbort}} to 1 any subsequent call to some macro using [[abort | {{code|abort()}}]] will not abort the current macro. So the abort is kind of catched and the macro will proceed with execution.
Wherever you set {{code|macro.catchAbort}} to 1 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.


The variable ''macro.catchAbort'' must be in the variable scope where the abort should be catched. It is not a general flag to turn off abort behaviour, just temporary in the macro or variable scope where it's set.
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==
==Usage==
Line 15: Line 15:
==Examples==
==Examples==


When a macro on is called by another macro, the called macro may use the [[abort | {{code|abort()}}]] to cancel execution. Usually all macro execution would stop, so the calling macro would not proceed. We can now override that default behaviour by catching the abort.
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.


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


The macro below will not have any output cause the default behaviour 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 abort will stop the overall macro execution. Whatever code is defined after the call to abort is not executed.


{| class="wikitable" border="1" style="border-collapse:collapse;"
{| class="wikitable" border="1" style="border-collapse:collapse;"
Line 34: Line 34:
===Catch the abort===
===Catch the abort===


The macro below will output "defaultValue" cause we activate catching the abort with {{code|macro.catchAbort}} set to 1 . The example shows how to set a default value for any return value of a function/macro that has a abort call in it. Optionally it deactivates the catching of later aborts again with {{code|macro.catchAbort}} set to 0. You don't have to do this mostly, cause each macro will have it's own variable scope anyway, so setting it to 1 will not influence catching in other macros.
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.


{| class="wikitable" border="1" style="border-collapse:collapse;"
{| class="wikitable" border="1" style="border-collapse:collapse;"
Line 51: Line 51:
===Catch the abort with 2 macros===
===Catch the abort with 2 macros===


Sames as in the above example the calling macro below will output "defaultValue" cause we activate catching the abort (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 "defaultValue" cause we activate catching aborts (in anything that this macro will call afterwards) with {{code|macro.catchAbort}} set to 1 .  


{| class="wikitable" border="1" style="border-collapse:collapse;"
{| class="wikitable" border="1" style="border-collapse:collapse;"

Revision as of 22:33, 11 March 2019

Introduced in version 1.5.0. The variable macro.catchAbort can be used to make sure that the overall macro execution is not aborted if a called macro uses the abort() function. Wherever you set macro.catchAbort to 1 any subsequent call to another macro using abort() will not abort the current macro. So the abort is caught and the calling macro will proceed with execution.

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 behaviour) or 1 (catch aborts).

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

Examples

When a macro is called by another macro, the called macro may use the 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]

Catch the abort

The macro below will output "defaultValue" as the macro.catchAbort set to 1 preventing 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 a 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 [[|()]] within the current macro or calls to other macros from the current macro.

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

Catch the abort with 2 macros

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 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()

Version changes

  • 1.5.0 - introduced macro.abortCatch