diff options
Diffstat (limited to 'Doc/Zsh/builtins.yo')
| -rw-r--r-- | Doc/Zsh/builtins.yo | 117 |
1 files changed, 87 insertions, 30 deletions
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index 1ca1f24a8..81687c7a7 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -147,20 +147,42 @@ ifnzman(noderef(Aliasing)). findex(autoload) cindex(functions, autoloading) cindex(autoloading functions) -item(tt(autoload) [ {tt(PLUS())|tt(-)}tt(TUXkmtz) ] [ tt(-w) ] [ var(name) ... ])( +item(tt(autoload) [ {tt(PLUS())|tt(-)}tt(RTUXdkmrtWz) ] [ tt(-w) ] [ var(name) ... ])( vindex(fpath, searching) -Equivalent to tt(functions -u), with the exception of tt(-X)/tt(+X) and -tt(-w). See the section `Autoloading Functions' in ifzman(zmanref(zshmisc))\ +See the section `Autoloading Functions' in ifzman(zmanref(zshmisc))\ ifnzman(noderef(Functions)) for full details. The tt(fpath) parameter will be searched to find the function definition when the function is first referenced. -The flag tt(-X) may be used only inside a shell function, and may not be -followed by a var(name). It causes the calling function to be marked for -autoloading and then immediately loaded and executed, with the current -array of positional parameters as arguments. This replaces the previous -definition of the function. If no function definition is found, an error -is printed and the function remains undefined and marked for autoloading. +If var(name) consists of an absolute path, the function is defined to +load from the file given (searching as usual for dump files in the given +location). The name of the function is the basename (non-directory +part) of the file. It is normally an error if the function is not found +in the given location; however, if the option tt(-d) is given, searching +for the function defaults to tt($fpath). If a function is loaded by +absolute path, any functions loaded from it that are marked for +tt(autoload) without an absolute path have the load path of the parent +function temporarily prepended to tt($fpath). + +If the option tt(-r) or tt(-R) is given, the function is searched for +immediately and the location is recorded internally for use when the +function is executed; a relative path is expanded using the value of +tt($PWD). This protects against a change to tt($fpath) after the call +to tt(autoload). With tt(-r), if the function is not found, it is +silently left unresolved until execution; with tt(-R), an error message +is printed and command processing aborted immediately the search fails, +i.e. at the tt(autoload) command rather than at function execution.. + +The flag tt(-X) may be used only inside a shell function. It causes the +calling function to be marked for autoloading and then immediately +loaded and executed, with the current array of positional parameters as +arguments. This replaces the previous definition of the function. If +no function definition is found, an error is printed and the function +remains undefined and marked for autoloading. If an argument is given, +it is used as a directory (i.e. it does not include the name of the +function) in which the function is to be found; this may be combined +with the tt(-d) option to allow the function search to default to tt($fpath) +if it is not in the given location. The flag tt(+X) attempts to load each var(name) as an autoloaded function, but does em(not) execute it. The exit status is zero (success) if the @@ -176,6 +198,13 @@ If the tt(-m) flag is also given each var(name) is treated as a pattern and all functions already marked for autoload that match the pattern are loaded. +With the tt(-t) flag, turn on execution tracing; with tt(-T), turn on +execution tracing only for the current function, turning it off on entry +to any called functions that do not also have tracing enabled. + +With the tt(-U) flag, alias expansion is suppressed when the function is +loaded. + With the tt(-w) flag, the var(name)s are taken as names of files compiled with the tt(zcompile) builtin, and all functions defined in them are marked for autoloading. @@ -193,6 +222,10 @@ example(emulate zsh -c 'autoload -Uz var(func)') arranges that when var(func) is loaded the shell is in native tt(zsh) emulation, and this emulation is also applied when var(func) is run. + +Some of the functions of tt(autoload) are also provided by tt(functions +-u) or tt(functions -U), but tt(autoload) is a more comprehensive +interface. ) findex(bg) cindex(jobs, backgrounding) @@ -453,7 +486,7 @@ tt(echo) recognizes the following escape sequences: startsitem() sitem(tt(\a))(bell character) sitem(tt(\b))(backspace) -sitem(tt(\c))(suppress final newline) +sitem(tt(\c))(suppress subsequent characters and final newline) sitem(tt(\e))(escape) sitem(tt(\f))(form feed) sitem(tt(\n))(linefeed (newline)) @@ -570,7 +603,7 @@ with emulations to be set to their values in tt(sh). tt(fno) then calls tt(fni); because tt(fni) is also marked for sticky tt(sh) emulation, no option changes take place on entry to or exit from it. Hence the option tt(cshnullglob), turned off by tt(sh) emulation, will -be turned on within tt(fni) and remain on on return to tt(fno). On exit +be turned on within tt(fni) and remain on return to tt(fno). On exit from tt(fno), the emulation mode and all options will be restored to the state they were in before entry to the temporary emulation. @@ -656,7 +689,7 @@ An EOF condition will also cause the shell to exit, unless the tt(IGNORE_EOF) option is set. See notes at the end of -ifzman(the section JOBS in in zmanref(zshmisc))\ +ifzman(the section JOBS in zmanref(zshmisc))\ ifnzman(noderef(Jobs & Signals)) for some possibly unexpected interactions of the tt(exit) command with jobs. ) @@ -697,7 +730,7 @@ specifies the most recent event beginning with the given string. All substitutions var(old)tt(=)var(new), if any, are then performed on the text of the events. -In addition to the the number range, +In addition to the number range, startsitem() sitem(tt(-I))(restricts to only internal events (not from tt($HISTFILE))) sitem(tt(-L))(restricts to only local events (not from other shells, see @@ -806,18 +839,24 @@ Equivalent to tt(typeset -E), except that options irrelevant to floating point numbers are not permitted. ) findex(functions) -xitem(tt(functions) [ {tt(PLUS())|tt(-)}tt(UkmtTuz) ] [ tt(-x) var(num) ] [ var(name) ... ]) -xitem(tt(functions -M) var(mathfn) [ var(min) [ var(max) [ var(shellfn) ] ] ]) +xitem(tt(functions) [ {tt(PLUS())|tt(-)}tt(UkmtTuWz) ] [ tt(-x) var(num) ] [ var(name) ... ]) +xitem(tt(functions -M) [tt(-s)] var(mathfn) [ var(min) [ var(max) [ var(shellfn) ] ] ]) xitem(tt(functions -M) [ tt(-m) var(pattern) ... ]) item(tt(functions +M) [ tt(-m) ] var(mathfn) ... )( -Equivalent to tt(typeset -f), with the exception of the tt(-x) and -tt(-M) options. +Equivalent to tt(typeset -f), with the exception of the tt(-x), +tt(-M) and tt(-W) options. For tt(functions -u) and tt(functions -U), +see tt(autoload), which provides additional options. The tt(-x) option indicates that any functions output will have each leading tab for indentation, added by the shell to show syntactic structure, expanded to the given number var(num) of spaces. var(num) can also be 0 to suppress all indentation. +The tt(-W) option turns on the option tt(WARN_NESTED_VAR) for the named +function or functions only. The option is turned off at the start of +nested functions (apart from anonoymous functions) unless the called +function also has the tt(-W) attribute. + Use of the tt(-M) option may not be combined with any of the options handled by tt(typeset -f). @@ -843,6 +882,13 @@ The result of the last arithmetical expression evaluated inside the shell function (even if it is a form that normally only returns a status) gives the result of the mathematical function. +If the additional option tt(-s) is given to tt(functions -M), the +argument to the function is a single string: anything between the +opening and matching closing parenthesis is passed to the function as a +single argument, even if it includes commas or white space. The minimum +and maximum argument specifiers must therefore be 1 if given. An empty +argument list is passed as a zero-length string. + tt(functions -M) with no arguments lists all such user-defined functions in the same form as a definition. With the additional option tt(-m) and a list of arguments, all functions whose var(mathfn) matches one of @@ -850,15 +896,22 @@ the pattern arguments are listed. tt(function +M) removes the list of mathematical functions; with the additional option tt(-m) the arguments are treated as patterns and -all functions whose tt(mathfn) matches the pattern are removed. Note +all functions whose var(mathfn) matches the pattern are removed. Note that the shell function implementing the behaviour is not removed -(regardless of whether its name coincides with tt(mathfn)). +(regardless of whether its name coincides with var(mathfn)). For example, the following prints the cube of 3: example(zmath_cube+LPAR()RPAR() { (( $1 * $1 * $1 )) } functions -M cube 1 1 zmath_cube print $(( cube+LPAR()3+RPAR() ))) + +The following string function takes a single argument, including +the commas, so prints 11: + +example(stringfn+LPAR()RPAR() { (( $#1 )) } +functions -Ms stringfn +print $(( stringfn+LPAR()foo,bar,rod+RPAR() ))) ) module(getcap)(zsh/cap) findex(getln) @@ -1199,6 +1252,9 @@ Perform prompt expansion (see ifzman(EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\ ifnzman(noderef(Prompt Expansion))\ ). +In combination with `tt(-f)', +prompt escape sequences are parsed only within interpolated arguments, +not within the format string. ) item(tt(-r))( Ignore the escape conventions of tt(echo). @@ -1289,7 +1345,9 @@ required by the format than have been specified, the behaviour is as if zero or an empty string had been specified as the argument. The tt(-v) option causes the output to be stored as the value of the -parameter var(name), instead of printed. +parameter var(name), instead of printed. If var(name) is an array and +the format string is reused when consuming arguments then one +array element will be used for each use of the format string. ) findex(pushd) pindex(PUSHD_TO_HOME, use of) @@ -1918,11 +1976,6 @@ If the tt(-p) option is given, parameters and values are printed in the form of a typeset command with an assignment, regardless of other flags and options. Note that the tt(-H) flag on parameters is respected; no value will be shown for these parameters. - -As the intention of this option is to produce output that can restore -the current state, readonly specials (whose values cannot be -changed) are not shown and assignments to arrays are shown before -the tt(typeset) rendering the array readonly. ) item(tt(-T) [ var(scalar)[tt(=)var(value)] var(array)[tt(=LPAR())var(value) ...tt(RPAR())] [ var(sep) ] ])( This flag has a different meaning when used with tt(-f); see below. @@ -2019,23 +2072,27 @@ place in the output. ) item(tt(-a))( The names refer to array parameters. An array parameter may be -created this way, but it may not be assigned to in the tt(typeset) -statement. When displaying, both normal and associative arrays are -shown. +created this way, but it may be assigned to in the tt(typeset) +statement only if the reserved word form of tt(typeset) is enabled +(as it is by default). When displaying, both normal and associative +arrays are shown. ) item(tt(-f))( The names refer to functions rather than parameters. No assignments can be made, and the only other valid flags are tt(-t), tt(-T), tt(-k), tt(-u), tt(-U) and tt(-z). The flag tt(-t) turns on execution tracing for this function; the flag tt(-T) does the same, but turns off tracing -on any function called from the present one, unless that function also +for any named (not anonymous) function called from the present one, +unless that function also has the tt(-t) or tt(-T) flag. The tt(-u) and tt(-U) flags cause the function to be marked for autoloading; tt(-U) also causes alias expansion to be suppressed when the function is loaded. See the description of the `tt(autoload)' builtin for details. Note that the builtin tt(functions) provides the same basic capabilities -as tt(typeset -f) but gives access to a few extra options. +as tt(typeset -f) but gives access to a few extra options; tt(autoload) +gives further additional options for the case tt(typeset -fu) and +tt(typeset -fU). ) item(tt(-h))( Hide: only useful for special parameters (those marked `<S>' in the table in |