Setting a trap is done in two parts. First the trap is defined by creating an instance of the appropriate trap class, with slot values specifying the condition under which the trap will fire and the action to take when it fires. Secondly the trap object thus created must be installed.
To make this immediately concrete, here is an example that sets a trap
to fire on the next application of the
facti procedure, and to
handle the trap by entering the command line debugger.
(install-trap (make <procedure-trap> #:procedure facti #:single-shot #t #:behaviour debug-trap))
Briefly, the elements of this incantation are as follows. (All of these are described more fully in the following subsubsections.)
<procedure-trap>is the trap class for trapping on invocation of a specific procedure.
#:procedure factisays that the specific procedure to trap on for this trap object is
#:single-shot #tsays that this trap should only fire on the next invocation of
facti, not on all future invocations (which is the default if the
#:single-shotoption is not specified).
#:behaviour debug-trapsays that the trap infrastructure should call the procedure
debug-trapwhen this trap fires.
install-trapcall installs the trap immediately.
It is of course possible for the user to define more convenient shorthands for setting common kinds of traps. See Trap Shorthands, for some examples.
The ability to install, uninstall and reinstall a trap without losing its definition is Guile's equivalent of the disable/enable commands provided by debuggers like GDB.
Install the trap object trap, so that its behaviour will be executed when the conditions for the trap firing are met.