diff options
Diffstat (limited to 'Util/zsh-development-guide')
| -rw-r--r-- | Util/zsh-development-guide | 148 |
1 files changed, 148 insertions, 0 deletions
diff --git a/Util/zsh-development-guide b/Util/zsh-development-guide index f8e331f54..6e8eb1b2d 100644 --- a/Util/zsh-development-guide +++ b/Util/zsh-development-guide @@ -397,6 +397,154 @@ builtins and condition codes: ... } +Modules can also define function hooks. Other modules can then add +functions to these hooks to make the first module call these functions +instead of the default. + +Again, an array is used to define hooks: + + static struct hookdef foohooks[] = { + HOOKDEF("foo", foofunc, 0), + }; + +The first argument of the macro is the name of the hook. This name +is used whenever the hook is used. The second argument is the default +function for the hook or NULL if no default function exists. The +last argument is used to define flags for the hook. Currently only one +such flag is defined: `HOOKF_ALL'. If this flag is given and more than +one function was added to the hook, all functions will be called +(including the default function). Otherwise only the last function +added will be called. + +The functions that can be used as default functions or that can be +added to a hook have to be defined like: + + /**/ + static int + foofunc(Hookdef h, void *data) + { + ... + } + +The first argument is a pointer to the struct defining the hook. The +second argument is an arbitrary pointer that is given to the function +used to invoke hooks (see below). + +The functions to register and de-register hooks look like those for +the other things that can be defined by modules: + + /**/ + int + boot_foo(Module m) + { + int ret; + + ret = addhookdefs(m->nam, foohooks, sizeof(foohooks)/sizeof(*foohooks)) + ... + } + ... + /**/ + int + cleanup_foo(Module m) + { + deletehookdefs(m->nam, foohooks, sizeof(foohooks)/sizeof(*foohooks)); + ... + } + +Modules that define hooks can invoke the function(s) registered for +them by calling the function `runhook(name, data)'. The first argument +is the name of the hook and the second one is the pointer given to the +hook functions as their second argument. Hooks that have the `HOOKF_ALL' +flag call all function defined for them until one returns non-zero. +The return value of `runhook()' is the return value of the last hook +function called or zero if none was called. + +To add a function to a hook, the function `addhookfunc(name, func)' is +called with the name of the hook and a hook function as arguments. +Deleting them is done by calling `deletehookfunc(name, func)' with the +same arguments as for the corresponding call to `addhookfunc()'. + +Alternative forms of the last three function are provided for hooks +that are changed or called very often. These functions, +`runhookdef(def, data)', `addhookdeffunc(def, func)', and +`deletehookdeffunc(def, func)' get a pointer to the `hookdef' +structure defining the hook instead of the name and otherwise behave +like their counterparts. + +Modules can also define function hooks. Other modules can then add +functions to these hooks to make the first module call these functions +instead of the default. + +Again, an array is used to define hooks: + + static struct hookdef foohooks[] = { + HOOKDEF("foo", foofunc, 0), + }; + +The first argument of the macro is the name of the hook. This name +is used whenever the hook is used. The second argument is the default +function for the hook or NULL if no default function exists. The +last argument is used to define flags for the hook. Currently only one +such flag is defined: `HOOKF_ALL'. If this flag is given and more than +one function was added to the hook, all functions will be called +(including the default function). Otherwise only the last function +added will be called. + +The functions that can be used as default functions or that can be +added to a hook have to be defined like: + + /**/ + static int + foofunc(Hookdef h, void *data) + { + ... + } + +The first argument is a pointer to the struct defining the hook. The +second argument is an arbitrary pointer that is given to the function +used to invoke hooks (see below). + +The functions to register and de-register hooks look like those for +the other things that can be defined by modules: + + /**/ + int + boot_foo(Module m) + { + int ret; + + ret = addhookdefs(m->nam, foohooks, sizeof(foohooks)/sizeof(*foohooks)) + ... + } + ... + /**/ + int + cleanup_foo(Module m) + { + deletehookdefs(m->nam, foohooks, sizeof(foohooks)/sizeof(*foohooks)); + ... + } + +Modules that define hooks can invoke the function(s) registered for +them by calling the function `runhook(name, data)'. The first argument +is the name of the hook and the second one is the pointer given to the +hook functions as their second argument. Hooks that have the `HOOKF_ALL' +flag call all function defined for them until one returns non-zero. +The return value of `runhook()' is the return value of the last hook +function called or zero if none was called. + +To add a function to a hook, the function `addhookfunc(name, func)' is +called with the name of the hook and a hook function as arguments. +Deleting them is done by calling `deletehookfunc(name, func)' with the +same arguments as for the corresponding call to `addhookfunc()'. + +Alternative forms of the last three function are provided for hooks +that are changed or called very often. These functions, +`runhookdef(def, data)', `addhookdeffunc(def, func)', and +`deletehookdeffunc(def, func)' get a pointer to the `hookdef' +structure defining the hook instead of the name and otherwise behave +like their counterparts. + Finally, modules can define wrapper functions. These functions are called whenever a shell function is to be executed. |