From 26cc1ad1dfb9ba4ffeaf6079762439822ab828ef Mon Sep 17 00:00:00 2001 From: Peter Stephenson Date: Sun, 14 May 2000 22:08:41 +0000 Subject: doc changes; typo in _jobs; integer builtin understands `-i base' --- Doc/Zsh/func.yo | 154 ++++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 133 insertions(+), 21 deletions(-) (limited to 'Doc/Zsh/func.yo') diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo index c2fc71d55..af21fba82 100644 --- a/Doc/Zsh/func.yo +++ b/Doc/Zsh/func.yo @@ -5,7 +5,8 @@ sect(Functions) )\ cindex(functions) findex(function) -The tt(function) reserved word is used to define shell functions. +Shell functions are defined with the tt(function) reserved word or the +special syntax `var(funcname) tt(())'. Shell functions are read in and stored internally. Alias names are resolved when the function is read. Functions are executed like commands with the arguments @@ -30,29 +31,119 @@ sect(Autoloading Functions) findex(autoload, use of) cindex(autoloading functions) cindex(functions, autoloading) + A function can be marked as em(undefined) using the tt(autoload) builtin (or `tt(functions -u)' or `tt(typeset -fu)'). Such a function has no -body. When the function is first executed, the tt(fpath) -variable will be searched for a file with the same name as the -function. +body. When the function is first executed, the shell searches for its +definition using the elements of the tt(fpath) variable. Thus to define +functions for autoloading, a typical sequence is: + +example(fpath=(~/myfuncs $fpath) +autoload myfunc1 myfunc2 ...) + +The usual alias expansion during reading will be suppressed if the +tt(autoload) builtin or its equivalent is given the option tt(-U). This is +recommended for the use of functions supplied with the zsh distribution. +Note that for functions precompiled with the tt(zcompile) builtin command +the flag tt(-U) must be created when the tt(.zwc) file is created, as the +corresponding information is compiled into the latter. + +For each var(element) in tt(fpath), the shell looks for three possible +files, the newest of which is used to load the definition for the function: + +startitem() +item(var(element)tt(.zwc))( +A file created with the tt(zcompile) builtin command, which is expected to +contain the definitions for all functions in the directory named +var(element). The file is treated in the same manner as a directory +containing files for functions and is searched for the definition of the +function. If the definition is not found, the search for a definition +proceeds with the the other two possibilities described below. + +If var(element) already includes a tt(.zwc) extension (i.e. the extension +was explicitly given by the user), var(element) is searched for the +definition of the function without comparing its age to that of other +files; in fact, there does not need to be any directory named var(element) +without the suffix. Thus including an element such as +`tt(/usr/local/funcs.zwc)' in tt(fpath) will speed up the search for +functions, with the disadvantage that functions included must be explicitly +recompiled by hand before the shell notices any changes. ) +item(var(element)tt(/)var(function)tt(.zwc))( A file created with +tt(zcompile), which is expected to contain the definition for +var(function). It may include other function definitions as well, but +those are neither loaded nor executed; a file found in this way is searched +em(only) for the definition of var(function). ) +item(var(element)tt(/)var(function))( A file of zsh command text, taken to +be the definition for var(function). ) enditem() + +In summary, the order of searching is, first, directories in tt(fpath), +with the earliest directory containing a function definition being used; +within that directory, the newest of the three possibilities --- a compiled +directory, a compiled function, or an ordinary function defition --- is +used. pindex(KSH_AUTOLOAD, use of) -If the tt(KSH_AUTOLOAD) option is set, or the file contains only a simple -definition of the function, the file's contents will be -executed. It would normally define the function in question, but may -also perform initialisation. -It is executed in the context of the function -execution, and may therefore define local parameters. - -Otherwise, the function is defined such that its body is the -complete contents of the file. This form allows the file to be -used directly as an executable shell script. -Initialisation code can be executed, but only as part of the first -function execution, so the function would have to redefine itself to -avoid reinitialising on the next execution. - -If this processing of the file results in the function being -fully defined, the function itself is then executed. +If the tt(KSH_AUTOLOAD) option is set, or the file contains only a +simple definition of the function, the file's contents will be executed. +This will normally define the function in question, but may also perform +initialization, which is executed in the context of the function execution, +and may therefore define local parameters. It is an error if the function +is not defined by loading the file. + +Otherwise, the function body with no surrounding `var(funcname)tt(() +{)var(...)tt(}) is taken to be the complete contents of the file. This +form allows the file to be used directly as an executable shell script. If +processing of the file results in the function being re-defined, the +function itself is not re-executed. To force the shell to perform +initialization and then call the function defined, the file should contain +initialization code (which will be executed then discarded) in addition to +a complete function definition (which will be retained for subsequent calls +to the function), and a call to the shell function, including any +arguments, at the end. + +For example, suppose the autoload file tt(func) contains + +example(func() { print This is func; } +print func is initialized +) + +then `tt(func; func)' with tt(KSH_AUTOLOAD) set will produce both messages +on the first call, but only the message `tt(This is func)' on the second +and subsequent calls. Without tt(KSH_AUTOLOAD) set, it will produce +the initialization message on the first call, and the other message on the +second and subsequent calls. + +It is also possible to create a function that is not marked as autoloaded, +but which loads its own definition by searching tt(fpath), by using +`tt(autoload -X)' within a shell function. For example, the following are +equivalent: + +example(myfunc() { + autoload -X +} +myfunc args...) + +and + +example(unfunction myfunc # if myfunc was defined +autoload myfunc +myfunc args...) + +In fact, the tt(functions) command outputs `tt(builtin autoload -X)' as +the body of an autoloaded function. A true autoloaded function can be +identified by the presence of the comment `tt(# undefined)' in the body, +because all comments are discarded from defined functions. This is done +so that + +example(eval "$(functions)") + +produces a reasonable result. + +To load the definition of an autoloaded function tt(myfunc) without +executing tt(myfunc), use: + +example(autoload +X myfunc) + sect(Special Functions) The following functions, if defined, have special meaning to the shell: @@ -102,6 +193,27 @@ or when the current function exits if defined inside a function. ) findex(TRAPZERR) item(tt(TRAPZERR))( -Executed whenever a command has a non-zero exit status. +Executed whenever a command has a non-zero exit status. However, the +function is not executed if the command occurred in a sublist followed by +`tt(&&)' or `tt(||)'; only the final command in a sublist of this type +causes the trap to be executed. ) enditem() + +The functions beginning `tt(TRAP)' may alternatively be defined with the +tt(trap) builtin: this may be preferable for some uses, as they are then +run in the environment of the calling process, rather than in their own +function environment. Apart from the difference in calling procedure and +the fact that the function form appears in lists of functions, the forms + +example(TRAPNAL() { + # code +}) + +and + +example(trap ' + # code +' NAL) + +are equivalent. -- cgit 1.4.1