Node:Throw, Next:, Previous:Catch, Up:Exceptions

26.7.3 Throwing Exceptions

The throw primitive is used to throw an exception. One argument, the key, is mandatory, and must be a symbol; it indicates the type of exception that is being thrown. Following the key, throw accepts any number of additional arguments, whose meaning depends on the exception type. The documentation for each possible type of exception should specify the additional arguments that are expected for that kind of exception.

throw key . args Scheme Procedure
scm_throw (key, args) C Function
Invoke the catch form matching key, passing args to the handler.

key is a symbol. It will match catches of the same symbol or of #t.

If there is no handler at all, Guile prints an error and then exits.

When an exception is thrown, it will be caught by the innermost catch expression that applies to the type of the thrown exception; in other words, the innermost catch whose key is #t or is the same symbol as that used in the throw expression. Once Guile has identified the appropriate catch, it handles the exception by applying that catch expression's handler procedure to the arguments of the throw.

If there is no appropriate catch for a thrown exception, Guile prints an error to the current error port indicating an uncaught exception, and then exits. In practice, it is quite difficult to observe this behaviour, because Guile when used interactively installs a top level catch handler that will catch all exceptions and print an appropriate error message without exiting. For example, this is what happens if you try to throw an unhandled exception in the standard Guile REPL; note that Guile's command loop continues after the error message:

guile> (throw 'badex)
<unnamed port>:3:1: In procedure gsubr-apply ...
<unnamed port>:3:1: unhandled-exception: badex
ABORT: (misc-error)

The default uncaught exception behaviour can be observed by evaluating a throw expression from the shell command line:

$ guile -c "(begin (throw 'badex) (display \"here\\n\"))"
guile: uncaught throw to badex: ()

That Guile exits immediately following the uncaught exception is shown by the absence of any output from the display expression, because Guile never gets to the point of evaluating that expression.