diff options
Diffstat (limited to 'Etc')
| -rw-r--r-- | Etc/zsh-development-guide | 38 |
1 files changed, 27 insertions, 11 deletions
diff --git a/Etc/zsh-development-guide b/Etc/zsh-development-guide index cb645d416..299fd0a18 100644 --- a/Etc/zsh-development-guide +++ b/Etc/zsh-development-guide @@ -218,7 +218,7 @@ by the zsh core. The first one, named `setup_', should set up any data needed in the module, at least any data other modules may be interested in. -The next pair are features_ and enables_ and deal with enabling module +The next pair are `features_' and `enables_' and deal with enabling module features. Ensure you are familiar with the description of features under `zmodload -F'. The function features_ takes an argument `char ***featuresp'; *featuresp is to be set to a NULL-terminated array @@ -235,8 +235,7 @@ initialised so setting them is mandatory any time there are any present. A structure "struct features" should be used to contain all standard features as well as the number of abstract features (those only understood by the module itself). -It contains pointers to all builtins, conditions, parameters and -conditions controlled by the module. +See below. enables_ takes an argument `int **enablesp'. If *enablesp is NULL, it should be set to an array of the same length as *featuresp without the @@ -248,31 +247,44 @@ function handlefeatures() conveniently handles all standard features present in the module's features structure; abstract features must be handled by the module (as with the features array, the area of the enables array for abstract features is not even initialised by the main shell). As -with features_, any handling of the array by the module itself should take +with `features_', any handling of the array by the module itself should take into account that the array will not be freed and any allocation should therefore be from heap memory. -The functions features_ and enables_ can be called at any point -after setup_ has been called and before cleanup_ is called. In -particular they can be called before or after boot_. +The functions `features_' and `enables_' can be called at any point +after `setup_' has been called and before `cleanup_' is called. In +particular they can be called before or after `boot_'. The function named `boot_' should register function wrappers, hooks and anything that will be visible to the user that is not handled by features_ and enables_ (so features should not be turned on here). It will be called after the `setup_'-function, and also after the intial set of features -have been set by calls to features_ and enables_. +have been set by calls to `features_' and `enables_'. The function named `cleanup_', is called when the user tries to unload a module and should de-register all features and hooks. A call to setfeatures with the final argument NULL will remove all standard -features present in the module's features structure. +features present in the module's features structure. Note that +`cleanup_' is called whenever `setup_' succeeded, so that `cleanup_' +must be prepared to handle any state resulting from a failed `boot_' +or initial call to `features_'. Note also that a return code of 1 +from `cleanup_' will result in the module not being unloaded, so +usually `cleanup_' will return 0 even if it has to handle an unclean +state; if it does return 1, it must be prepared to be called again +in a future attempt to unload. The last function, `finish_' is called when the module is actually unloaded and should finalize all the data initialized in the `setup_'-function. +However, `finish_' is called even if `setup_' failed, so it should +not rely on the module successfully being set up. +The state from `finish_' module is currently ignored; it is called +too late to prevent the module from being unloaded. In short, the `cleanup_'-function should undo what the `boot_'-function did -(together with handling any residual effects of enables_), and the -`finish_'-function should undo what the `setup_'-function did. +(together with handling any residual effects of `enables_'), but should +not rely on `boot_' having been successful, and the +`finish_'-function should undo what the `setup_'-function did, but +should not rely on `setup_' having been successful. All of these functions should return zero if they succeeded and non-zero otherwise. @@ -302,6 +314,10 @@ as discussed below: 0, /* number of abstract features */ } +Within each individual table ("bintab", etc.), features should be listed +in ASCII order as no further sorting is performed by the shell when +features are listed. + Abstract features are handled by the module; the number present in `struct features' is there to ensure the main shell allocated space in the features and enables array in the standard |