diff options
author | Paul Ackersviller <packersv@users.sourceforge.net> | 2007-05-01 03:12:57 +0000 |
---|---|---|
committer | Paul Ackersviller <packersv@users.sourceforge.net> | 2007-05-01 03:12:57 +0000 |
commit | 45c4101a52596dbb43c9ecc55329690cce09fc78 (patch) | |
tree | aabc70580b423f6979c35c02e34416193f44325c | |
parent | d7075a5d0b530b0ff04a544ed5fe54d0b6da45c9 (diff) | |
download | zsh-45c4101a52596dbb43c9ecc55329690cce09fc78.tar.gz zsh-45c4101a52596dbb43c9ecc55329690cce09fc78.tar.xz zsh-45c4101a52596dbb43c9ecc55329690cce09fc78.zip |
Merge of workers/{21071,21296,2236[05],2298[01],22984,2299[23]}.
-rw-r--r-- | Doc/Zsh/func.yo | 201 |
1 files changed, 150 insertions, 51 deletions
diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo index ac853d9e7..16a838f9d 100644 --- a/Doc/Zsh/func.yo +++ b/Doc/Zsh/func.yo @@ -4,7 +4,7 @@ ifzman(\ sect(Functions) )\ cindex(functions) -findex(function) +findex(function, use of) 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. @@ -28,10 +28,11 @@ Function identifiers can be listed with the tt(functions) builtin. findex(unfunction, use of) Functions can be undefined with the tt(unfunction) builtin. sect(Autoloading Functions) -findex(autoload, use of) cindex(autoloading functions) cindex(functions, autoloading) +findex(autoload, use of) +vindex(fpath, use of) 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 shell searches for its @@ -42,83 +43,107 @@ 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). For -functions precompiled with the tt(zcompile) builtin command, this has to -be decided when creating the file; this is recommended for the use of -functions supplied with the zsh distribution. +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. +findex(zcompile, use of) +Note that for functions precompiled with the tt(zcompile) builtin command +the flag tt(-U) must be provided 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 files, the -newest of which is used to load the definition for the function: +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, expected to +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 like a directory containing files for -functions and is searched for the definition of the function; the search -goes on to the next two files if the definition is not found. +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 other two possibilities described below. -If var(element) already includes a tt(.zwc) extension, var(element) is -searched for the definition of the function without comparing its age to -that of other files. +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), 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). +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, in the em(parents of) +directories in tt(fpath) for the newer of either a compiled directory or +a directory in tt(fpath); second, if more than one of these contains a +definition for the function that is sought, the leftmost in the tt(fpath) +is chosen; and third, within a directory, the newer of either a compiled +function or an ordinary function definition 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. This will normally define the function in question, but may also perform -initialization; such initialization 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 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. If processing of the file results in the -function being re-defined, the function itself is not re-executed. To -force the function to perform initialization and be called, the file -should contain initialization code (which will be 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 at the end. +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; } +example(func+LPAR()RPAR() { 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, and just the message `tt(This is func)' on the second -and any subsequent calls. Without tt(KSH_AUTOLOAD) set, it will produce +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 autoloaded, -yet loads its own definition by searching tt(fpath): `tt(autoload -X)', -when called from within a shell function tt(myfunc), is equivalent to: +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+LPAR()RPAR() { + autoload -X +} +myfunc args...) -example(unfunction myfunc +and + +example(unfunction myfunc # if myfunc was defined autoload myfunc -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 +the body of an autoloaded function. This is done so that example(eval "$(functions)") -produces a reasonable result. +produces a reasonable result. 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. To load the definition of an autoloaded function tt(myfunc) without executing tt(myfunc), use: @@ -126,30 +151,65 @@ executing tt(myfunc), use: example(autoload +X myfunc) sect(Special Functions) -The following functions, if defined, have special meaning to -the shell: +Certain functions, if defined, have special meaning to the shell. + +In the case of tt(chpwd), tt(periodic), tt(precmd) and tt(preexec) it is +possible to define an array that has the same name with `tt(_functions)' +appended. Any element in such an array is taken as the name of a function +to execute; it is executed in the same context and with the same arguments +as the basic function. For example, if tt($chpwd_functions) is an array +containing the values `tt(mychpwd)', `tt(chpwd_save_dirstack)', then the +shell attempts to execute the functions `tt(chpwd)', `tt(mychpwd)' and +`tt(chpwd_save_dirstack)', in that order. Any function that does not exist +is silently ignored. A function found by this mechanism is referred to +elsewhere as a `hook function'. An error in any function causes +subsequent functions not to be run. Note further that an error +in a tt(precmd) hook causes an immediately following tt(periodic) +function not to run (thought it may run at the next opportunity). startitem() findex(chpwd) +vindex(chpwd_functions) item(tt(chpwd))( Executed whenever the current working directory is changed. ) findex(periodic) +vindex(periodic_functions) item(tt(periodic))( vindex(PERIOD) If the parameter tt(PERIOD) is set, this function is executed every tt($PERIOD) -seconds, just before a prompt. +seconds, just before a prompt. Note that if multiple functions +are defined using the array tt(periodic_functions) only one +period is applied to the complete set of functions, and the +scheduled time is not reset if the list of functions is altered. +Hence the set of functions is always called together. ) findex(precmd) +vindex(precmd_functions) item(tt(precmd))( Executed before each prompt. ) findex(preexec) +vindex(preexec_functions) item(tt(preexec))( Executed just after a command has been read and is about to be -executed. If the history mechanism is active, the string to be -executed is passed as an argument. +executed. If the history mechanism is active (and the line was not +discarded from the history buffer), the string that the user typed is +passed as the first argument, otherwise it is an empty string. The +actual command that will be executed (including expanded aliases) is +passed in two different forms: the second argument is a single-line, +size-limited version of the command (with things like function bodies +elided); the third argument contains the full text that is being +executed. +) +findex(zshexit) +vindex(zshexit_functions) +item(tt(zshexit))( +Executed at the point where the main shell is about to exit normally. +This is not called by exiting subshells, nor when the tt(exec) +precommand modifier is used before an external command. Also, unlike +tt(TRAPEXIT), it is not called when functions exit. ) item(tt(TRAP)var(NAL))( cindex(signals, trapping) @@ -162,6 +222,23 @@ The signal number will be passed as the first parameter to the function. If a function of this form is defined and null, the shell and processes spawned by it will ignore tt(SIG)var(NAL). + +The return status from the function is handled specially. If it is +zero, the signal is assumed to have been handled, and execution continues +normally. Otherwise, the shell will behave as interrupted except that +the return status of the trap is retained. + +Programs terminated by uncaught signals typically return the status 128 +plus the signal number. Hence the following causes the handler for +tt(SIGINT) to print a message, then mimic the usual effect of the signal. + +example(TRAPINT+LPAR()RPAR() { + print "Caught SIGINT, aborting." + return $(( 128 + $1 )) +}) + +The functions tt(TRAPZERR), tt(TRAPDEBUG) and tt(TRAPEXIT) are never +executed inside other traps. ) findex(TRAPDEBUG) item(tt(TRAPDEBUG))( @@ -171,14 +248,36 @@ findex(TRAPEXIT) item(tt(TRAPEXIT))( Executed when the shell exits, or when the current function exits if defined inside a function. +The value of tt($?) at the start of execution is the exit status of the +shell or the return status of the function exiting. ) findex(TRAPZERR) +findex(TRAPERR) 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. The function tt(TRAPERR) acts the same as +tt(TRAPZERR) on systems where there is no tt(SIGERR) (this is the usual +case). ) enditem() +findex(trap, use of) 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. +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+LPAR()RPAR() { + # code +}) + +and + +example(trap ' + # code +' NAL) + +are equivalent. |