return

return() Function

• Introduced in version 1.5.0

Is used to conditionally return from the execution of a macro like an abort, but not stopping further macro execution. Optionally also returning a value by automatically assigning macro.return. If the first argument to return() is 0 then the return is happening. If the first argument to return() is non zero then the macro continues. The optional second argument of return() defines if there is a value that should be returned to a calling macro. Any other output is discarded when using return().

Common uses for this function are

Ending a macro with or without a return value to stop the further execution of the following lines in the current macro.
The macro has conditions and based on these you want to return different values and not continue further in the current macro.

If you prefer to display an error message when exiting the macro see the assert() function or if you want to abort the flow of overall macro execution (e.g. in case of an error) see the abort() function.

Usage

return(continue, returnValue)

Parameters

continue - 0 if the return function should end the current macro, nonzero if it should not. So consistent to what the abort function is doing.
returnValue - Optional. Any value passed in here will automatically be used as a return value (set to macro.return) and passed to the calling macro.

Examples

The following example is about a called macro using the return() function to return a result to the calling macro. The calling macro could also be in a user defined function and then just used as a function in the caller macro.

Calling Macro

<!-- Call the testReturn library macro -->
[MACRO("testReturn@Lib:test"): ""]
Response is [r:macro.return].

Called Macro

<!-- testReturn macro in Lib:test token -->
[h: return(0, "hello world")]
[h: "this will not be executed anymore"]
[h: macro.return = "this will not be set"]

Results

TokenName: Response is hello world.

Version Changes

1.5.0 - introduced return function