13.4 How to write and set exception–handlers ¶

An exception–handler function typically handles just a few exceptional–condition classes; every exception–handler must return using one among:

return_success_after_handling_exception
return_failure_after_handling_exception
return_after_not_handling_exception

The basic template of an exception–handler is as follows:

function my_exception_handler () {
    mbfl_mandatory_nameref_parameter(CND, 1, exceptional-condition object)

    if spiffy_condition_p _(CND)
    then
        do_some_thing _(CND)
        if handled_successfully
        then return_success_after_handling_exception
        else return_failure_after_handling_exception
        fi
    else return_after_not_handling_exception
    fi
}

most exceptional–condition objects are non–continuable: it is not possible to resume script’s execution after handling them; so we should just use return_failure_after_handling_exception.

Function: mbfl_exception_handler HANDLER ¶

Push HANDLER on the stack of exceptional–condition handlers. Register a location handler that pops HANDLER from the stack upon leaving the current location, Locations programming interface.

The parameter HANDLER should be an applicable identifier bound to a function, alias or command; it must accept a single mandatory parameter:

HANDLER CONDITION_OBJECT

Function: mbfl_default_exception_handler CND ¶

The default exception–handler; it is pushed on the global exception–handlers stack upon loading MBFL’s core library. We can think of it as having the following implementation:

mbfl_mandatory_nameref_parameter(mbfl_CND, 1, exceptional-condition object)

if mbfl_warning_condition_p _(mbfl_CND) &&
   mbfl_exceptional_condition_is_continuable _(mbfl_CND)
then
    mbfl_exceptional_condition_print _(mbfl_CND) >&2
    return_success_after_handling_exception
elif mbfl_uncaught_exceptional_condition_p _(mbfl_CND)
then
    mbfl_exceptional_condition_print _(mbfl_CND) >&2
    exit_because_uncaught_exception
else
    mbfl_default_object_declare(mbfl_ENVELOPE_CND)

    mbfl_uncaught_exceptional_condition_make _(mbfl_ENVELOPE_CND) $FUNCNAME _(mbfl_CND)
    mbfl_exception_raise _(mbfl_ENVELOPE_CND)
fi

Notice that if the default handler raises an “uncaught exceptional–condition”: the topmost exception–handler from the stack is applied to it; the exception–handlers we install have a chance to handle the uncaught exceptional–condition. Uncaught exceptional-condition objects.

Alias: return_success_after_handling_exception ¶

Return from an exception handler with a return status signalling to mbfl_exception_raise() that the exceptional–condition has been handled and that the script can resume execution.

Alias: return_failure_after_handling_exception ¶

Return from an exception handler with a return status signalling to mbfl_exception_raise() that the exceptional–condition has been handled but the script cannot resume execution.

Alias: return_after_not_handling_exception ¶

Return from an exception handler with a return status signalling to mbfl_exception_raise() that the exceptional–condition has not been handled.

Function: exit_because_uncaught_exception ¶

Exit with code 87 by calling mbfl_exit().

Function: exit_because_non_continuable_exception ¶

Exit with code 86 by calling mbfl_exit().