Merge of workers/{21071,21296,2236[05],2298[01],22984,2299[23]}.

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.