From b0c5f09169ac31855ebf0e93772bb57b9635b380 Mon Sep 17 00:00:00 2001 From: Peter Stephenson Date: Mon, 28 May 2007 22:57:39 +0000 Subject: see 23479: add initial features support for modules --- Doc/Zsh/builtins.yo | 64 ++++++++++++++++++++++++++++++++++++++++++++++++----- Doc/Zsh/compsys.yo | 7 ------ Doc/Zsh/mod_stat.yo | 17 +++++++++----- 3 files changed, 70 insertions(+), 18 deletions(-) (limited to 'Doc/Zsh') diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index 0f90bca6d..cd655c146 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -1845,6 +1845,7 @@ findex(zmodload) cindex(modules, loading) cindex(loading modules) xitem(tt(zmodload) [ tt(-dL) ] [ ... ]) +xitem(tt(zmodload -F) [ tt(-lLe) tt(-P) tt(param) ] var(module) [tt(PLUS()-)]var(feature...)) xitem(tt(zmodload -e) [ tt(-A) ] [ ... ]) xitem(tt(zmodload) [ tt(-a) [ tt(-bcpf) [ tt(-I) ] ] ] [ tt(-iL) ] ...) xitem(tt(zmodload) tt(-u) [ tt(-abcdpf) [ tt(-I) ] ] [ tt(-iL) ] ...) @@ -1867,21 +1868,24 @@ item(tt(zmodload) tt(-u) [ tt(-i) ] var(name) ...)( In the simplest case, tt(zmodload) loads a binary module. The module must be in a file with a name consisting of the specified var(name) followed by a standard suffix, usually `tt(.so)' (`tt(.sl)' on HPUX). -If the module to be loaded is -already loaded and the tt(-i) option is given, the duplicate module is -ignored. Otherwise tt(zmodload) prints an error message and returns -a non-zero status. If tt(zmodload) detects an inconsistency, such as an +If the module to be loaded is already loaded the duplicate module is +ignored. If tt(zmodload) detects an inconsistency, such as an invalid module name or circular dependency list, the current code block is -aborted. Hence `tt(zmodload -i) var(module) tt(2>/dev/null)' is sufficient +aborted. Hence `tt(zmodload) var(module) tt(2>/dev/null)' is sufficient to test whether a module is available. If it is available, the module is loaded if necessary, while if it -is not available, non-zero status is silently returned. +is not available, non-zero status is silently returned. The option +tt(-i) is accepted for compatibility but has no effect. The var(name)d module is searched for in the same way a command is, using tt($module_path) instead of tt($path). However, the path search is performed even when the module name contains a `tt(/)', which it usually does. There is no way to prevent the path search. +If the module supports features (see below), tt(zmodload) tries to +enable all features when loading a module. If the module was successfully +loaded but not all features could be enabled, tt(zmodload) returns status 2. + With tt(-u), tt(zmodload) unloads modules. The same var(name) must be given that was given when the module was loaded, but it is not necessary for the module to exist in the filesystem. @@ -1892,6 +1896,54 @@ Each module has a boot and a cleanup function. The module will not be loaded if its boot function fails. Similarly a module can only be unloaded if its cleanup function runs successfully. ) +item(tt(zmodload -F) [ tt(-lLe) tt(-P) tt(param) ] var(module) [tt(PLUS()-)]var(feature...))( +tt(zmodload -F) allows more selective control over the features provided +by modules. With no options apart from tt(-F), the module named +var(module) is loaded, if it was not already loaded, and the list of +var(feature)s is set to the required state. If no +var(feature)s are specified, the module is loaded, if it was not already +loaded, but the state of features is unchanged. Each feature +may be preceded by a tt(PLUS()) to turn the feature on, or tt(-) to turn it +off; the tt(PLUS()) is assumed if neither character is present. +Any feature not explicitly mentioned is left in its current state; +if the module was not previously loaded this means any such features will +remain disabled. The return status is zero if all features were +set, 1 if the module failed to load, and 2 if some features could +not be set (for example, a parameter couldn't be added because there +was a different parameter of the same name) but the module was loaded. + +The standard features are builtins, conditions, parameters and math +functions; these are indicated by the prefix `tt(b:)', `tt(c:)', `tt(p:)' +and `tt(f:)', respectively, followed by the name that the corresponding +feature would have in the shell. For example, `tt(b:strftime)' indicates +a builtin named tt(strftime) and tt(p:EPOCHSECONDS) indicates a parameter +named tt(EPOCHSECONDS). The module may provide other (`abstract') features +of its own as indicated by its documentation; these have no prefix. + +With tt(-l) or tt(-L), features provided by the module are listed. With +tt(-l) alone, a list of features together with their states is shown, one +feature per line. With tt(-L) alone, a tt(zmodload -F) command that would +cause enabled features of the module to be turned on is shown. With +tt(-lL), a tt(zmodload -F) command that would cause all the features to be +set to their current state is shown. If one of these combinations is given +the option tt(-P) var(param) then the parameter tt(param) is set to an +array of features, either features together with their state or (if +tt(-L) alone is given) enabled features. + +A set of features may be provided together with tt(-l) or tt(-L); in +that case only the state of features provided is considered. Each +feature may be preceded by tt(PLUS()) or tt(-) but the character +has no effect. If no set of features is provided, all features +are considered. + +With tt(-e), the command first tests that the module is loaded; +if it is not, status 1 is returned. If the module is loaded, +the list of features given as an argument is examined. Any feature +given with no prefix is simply tested to see if the module provides it; +any feature given with a prefix tt(PLUS()) or tt(-) is tested to +see if is provided and in the given state. If the tests on all features +in the list succeed, status 0 is returned, else status 1. +) xitem(tt(zmodload) tt(-d) [ tt(-L) ] [ var(name) ]) xitem(tt(zmodload) tt(-d) var(name) var(dep) ...) item(tt(zmodload) tt(-ud) var(name) [ var(dep) ... ])( diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 48df05471..963e43c96 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -1268,13 +1268,6 @@ If this is set to `true', the tt(_expand_alias) completer and bindable command will try to expand disabled aliases, too. The default is `tt(false)'. ) -kindex(disable-stat, completion style) -item(tt(disable-stat))( -This is used with an empty tag by the tt(_cvs) function -to decide whether the tt(zsh/stat) module should be used to -generate names of modified files in the appropriate places (this is its -only use). If the style is set, completion will use the tt(ls) command. -) kindex(domains, completion style) item(tt(domains))( A list of names of network domains for completion. diff --git a/Doc/Zsh/mod_stat.yo b/Doc/Zsh/mod_stat.yo index 0354196ad..e0fc15abd 100644 --- a/Doc/Zsh/mod_stat.yo +++ b/Doc/Zsh/mod_stat.yo @@ -1,17 +1,24 @@ COMMENT(!MOD!zsh/stat A builtin command interface to the tt(stat) system call. !MOD!) -The tt(zsh/stat) module makes available one builtin command: +The tt(zsh/stat) module makes available one builtin command under +two possible names: startitem() findex(stat) cindex(files, listing) cindex(files, examining) -item(tt(stat) [ tt(-gnNolLtTrs) ] [ tt(-f) var(fd) ] \ +xitem(tt(zstat) [ tt(-gnNolLtTrs) ] [ tt(-f) var(fd) ] \ [ tt(-H) var(hash) ] [ tt(-A) var(array) ] \ - [ tt(-F) var(fmt) ] [ tt(PLUS())var(element) ] [ var(file) ... ])( + [ tt(-F) var(fmt) ] [ tt(PLUS())var(element) ] [ var(file) ... ]) +itme(tt(stat) var(...))( The command acts as a front end to the tt(stat) system call (see -manref(stat)(2)). +manref(stat)(2)). The same command is provided with two names; as +the name tt(stat) is often used by an external command it is recommended +that only the tt(zstat) form of the command is used. This can be +arranged by loading the module with the command `tt(zmodload -F zsh/stat +zstat)'. + If the tt(stat) call fails, the appropriate system error message printed and status 1 is returned. The fields of tt(struct stat) give information about @@ -69,7 +76,7 @@ The number of disk blocks used by the file. item(tt(link))( If the file is a link and the tt(-L) option is in effect, this contains the name of the file linked to, otherwise -it is empty. Note that if this element is selected (``tt(stat PLUS()link)'') +it is empty. Note that if this element is selected (``tt(zstat PLUS()link)'') then the tt(-L) option is automatically used. ) enditem() -- cgit 1.4.1