Next: , Previous: Hook Example, Up: Hooks

24.6.2 Hook Reference

When you create a hook with make-hook, you must specify the arity of the procedures which can be added to the hook. If the arity is not given explicitly as an argument to make-hook, it defaults to zero. All procedures of a given hook must have the same arity, and when the procedures are invoked using run-hook, the number of arguments passed must match the arity specified at hook creation time.

The order in which procedures are added to a hook matters. If the third parameter to add-hook! is omitted or is equal to #f, the procedure is added in front of the procedures which might already be on that hook, otherwise the procedure is added at the end. The procedures are always called from the front to the end of the list when they are invoked via run-hook.

The ordering of the list of procedures returned by hook->list matches the order in which those procedures would be called if the hook was run using run-hook.

Note that the following C functions are for handling Scheme-level hooks in C; there are also C-level hooks which have their own interface (see C Hooks).

— Scheme Procedure: make-hook n-args
— C Function: scm_make_hook (n-args)

Create a hook object for storing procedure of arity n-args. n-args defaults to zero. The hook object can used with the other hook procedures.

— Scheme Procedure: hook? x
— C Function: scm_hook_p (x)

Return #t if x is a hook, #f otherwise.

— Scheme Procedure: hook-empty? hook
— C Function: scm_hook_empty_p (hook)

Return #t if hook is an empty hook, #f otherwise.

— Scheme Procedure: add-hook! hook proc append?
— C Function: scm_add_hook_x (hook, proc, append?)

Add the procedure proc to the hook hook. The procedure is added to the end if append? is true, otherwise it is added to the front.

— Scheme Procedure: remove-hook! hook proc
— C Function: scm_remove_hook_x (hook, proc)

Remove the procedure proc from the hook hook.

— Scheme Procedure: reset-hook! hook
— C Function: scm_reset_hook_x (hook)

Remove all procedures from the hook hook.

— Scheme Procedure: hook->list hook
— C Function: scm_hook_to_list (hook)

Convert the procedure list of hook to a list.

— Scheme Procedure: run-hook hook [args ...]
— C Function: scm_run_hook (hook, args) |1 |0 |1

Apply all procedures from the hook hook to the arguments args. The order of the procedure application is first to last.

If, in C code, you are certain that you have a hook object and well formed argument list for that hook, you can also use scm_c_run_hook, which is identical to scm_run_hook but does no type checking.

— C Function: void scm_c_run_hook (SCM hook, SCM args)

The same as scm_run_hook but without any type checking to confirm that hook is actually a hook object and that args is a well-formed list matching the arity of the hook.