diff options
Diffstat (limited to 'Doc')
73 files changed, 4753 insertions, 2649 deletions
diff --git a/Doc/Makefile.in b/Doc/Makefile.in index 5a6a705ff..23e5fc7e2 100644 --- a/Doc/Makefile.in +++ b/Doc/Makefile.in @@ -69,6 +69,7 @@ Zsh/mod_parameter.yo Zsh/mod_pcre.yo Zsh/mod_private.yo \ Zsh/mod_regex.yo Zsh/mod_sched.yo Zsh/mod_socket.yo \ Zsh/mod_stat.yo Zsh/mod_system.yo Zsh/mod_tcp.yo \ Zsh/mod_termcap.yo Zsh/mod_terminfo.yo \ +Zsh/mod_watch.yo \ Zsh/mod_zftp.yo Zsh/mod_zle.yo Zsh/mod_zleparameter.yo \ Zsh/mod_zprof.yo Zsh/mod_zpty.yo Zsh/mod_zselect.yo \ Zsh/mod_zutil.yo diff --git a/Doc/Zsh/arith.yo b/Doc/Zsh/arith.yo index c152bf48d..bc3e35ad5 100644 --- a/Doc/Zsh/arith.yo +++ b/Doc/Zsh/arith.yo @@ -20,7 +20,7 @@ The tt(let) builtin command takes arithmetic expressions as arguments; each is evaluated separately. Since many of the arithmetic operators, as well as spaces, require quoting, an alternative form is provided: for any command which begins with a `tt(LPAR()LPAR())', all the characters until a -matching `tt(RPAR()RPAR())' are treated as a quoted expression and +matching `tt(RPAR()RPAR())' are treated as a double-quoted expression and arithmetic expansion performed as for an argument of tt(let). More precisely, `tt(LPAR()LPAR())var(...)tt(RPAR()RPAR())' is equivalent to `tt(let ")var(...)tt(")'. The return status is 0 if the arithmetic value diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index ada69c99a..1d74f0c17 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -105,7 +105,13 @@ For each var(name) with a corresponding var(value), define an alias with that value. A trailing space in var(value) causes the next word to be checked for alias expansion. If the tt(-g) flag is present, define a global alias; global aliases are expanded even if they do not -occur in command position. +occur in command position: + +example(% perldoc --help 2>&1 | grep 'built-in functions' + -f Search Perl built-in functions +% alias -g HG='--help 2>&1 | grep' +% perldoc HG 'built-in functions' + -f Search Perl built-in functions) If the tt(-s) flag is present, define a suffix alias: if the command word on a command line is in the form `var(text)tt(.)var(name)', where @@ -730,7 +736,7 @@ findex(fc) cindex(history, editing) cindex(editing history) redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ ))ifnztexi( ))) -xitem(tt(fc) [ tt(-e) var(ename) ] [ tt(-LI) ] [ tt(-m) var(match) ] [ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ]) +xitem(tt(fc) [ tt(-e) var(ename) ] [ tt(-s) ] [ tt(-LI) ] [ tt(-m) var(match) ] [ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ]) xitem(tt(fc -l )[ tt(-LI) ] [ tt(-nrdfEiD) ] [ tt(-t) var(timefmt) ] [ tt(-m) var(match) ]) xitem(SPACES()[ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ]) xitem(tt(fc -p )[ tt(-a) ] [ var(filename) [ var(histsize) [ var(savehistsize) ] ] ]) @@ -750,15 +756,16 @@ 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 number range, +The range of events selected by numbers can be narrowed further by the +following flags. 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 tt(SHARE_HISTORY) in ifzman(zmanref(zshoptions))\ ifnzman(noderef(Description of Options)) -- note that tt($HISTFILE) is considered local when read at startup)) -sitem(tt(-m))(takes the first argument as a pattern (should be quoted) and -only the history events matching this pattern are considered) +sitem(tt(-m))(takes the first argument as a pattern (which should be +quoted) and only the history events matching this pattern are considered) endsitem() If var(first) is not specified, it will be set to -1 (the most recent @@ -777,6 +784,7 @@ the parameter tt(EDITOR) is used; if that is not set a builtin default, usually `tt(vi)' is used. If var(ename) is `tt(-)', no editor is invoked. When editing is complete, the edited command is executed. +The flag `tt(-s)' is equivalent to `tt(-e -)'. The flag tt(-r) reverses the order of the events and the flag tt(-n) suppresses event numbers when listing. @@ -886,6 +894,10 @@ without affecting the other. A typical idiom is that var(oldfn) is the name of a library shell function which is then redefined to call tt(newfn), thereby installing a modified version of the function. +em(The )tt(-M)em( and )tt(+M)em( flags) +cindex(defining mathematical functions) +cindex(functions, defining mathematical) + Use of the tt(-M) option may not be combined with any of the options handled by tt(typeset -f). @@ -907,9 +919,55 @@ expressions. The name of the function in tt($0) is var(mathfn) (not var(shellfn) as would usually be the case), provided the option tt(FUNCTION_ARGZERO) is in effect. The positional parameters in the shell function correspond to the arguments of the mathematical function call. -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. + +The result of the last arithmetical expression evaluated inside the shell +function gives the result of the mathematical function. This is not limited to +arithmetic substitutions of the form tt($+LPAR()+LPAR())var(...)tt(+RPAR()+RPAR()), +but also includes arithmetical expressions evaluated in any other way, including +by the tt(let) builtin, +by tt(+LPAR()+LPAR())var(...)tt(+RPAR()+RPAR()) statements, +and even +by the tt(return) builtin +and +by array subscripts. +Therefore, care must be taken not to use syntactical constructs that perform +arithmetic evaluation after evaluating what is to be the result of the function. +For example: + +findex(zmath_cube) +findex(cube) +example(# WRONG +zmath_cube+LPAR()+RPAR() { + (( $1 * $1 * $1 )) + return 0 +} +functions -M cube 1 1 zmath_cube +print $(( cube+LPAR()3+RPAR() ))) + +This will print `tt(0)' because of the tt(return). + +Commenting the tt(return) out would lead to a different problem: the +tt(+LPAR()+LPAR())var(...)tt(+RPAR()+RPAR()) statement would become +the last statement in the function, so the em(return status) (tt($?)) of the +function would be non-zero (indicating failure) whenever the em(arithmetic +result) of the function would happen to be zero (numerically): + +example(# WRONG +zmath_cube+LPAR()+RPAR() { + (( $1 * $1 * $1 )) +} +functions -M cube 1 1 zmath_cube +print $(( cube+LPAR()0+RPAR() ))) + +Instead, the tt(true) builtin can be used: + +example(# RIGHT +zmath_cube+LPAR()+RPAR() { + (( $1 * $1 * $1 )) + true +} +functions -M cube 1 1 zmath_cube +print $(( cube+LPAR()3+RPAR() ))) If the additional option tt(-s) is given to tt(functions -M), the argument to the function is a single string: anything between the @@ -917,6 +975,12 @@ 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. +Thus, the following string function takes a single argument, including +the commas, and prints 11: + +example(stringfn+LPAR()RPAR() { (( $#1 )); true } +functions -Ms stringfn +print $(( stringfn+LPAR()foo,bar,rod+RPAR() ))) 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 @@ -928,19 +992,6 @@ additional option tt(-m) the arguments are treated as patterns and 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 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) @@ -975,7 +1026,8 @@ vindex(OPTARG, use of) The first option to be examined may be changed by explicitly assigning to tt(OPTIND). tt(OPTIND) has an initial value of tt(1), and is normally set to tt(1) upon entry to a shell function and restored -upon exit (this is disabled by the tt(POSIX_BUILTINS) option). tt(OPTARG) +upon exit. (The tt(POSIX_BUILTINS) option disables this, and also changes +the way the value is calculated to match other shells.) tt(OPTARG) is not reset and retains its value from the most recent call to tt(getopts). If either of tt(OPTIND) or tt(OPTARG) is explicitly unset, it remains unset, and the index or option argument is not @@ -1062,6 +1114,24 @@ The tt(-Z) option replaces the shell's argument and environment space with the given string, truncated if necessary to fit. This will normally be visible in tt(ps) (manref(ps)(1)) listings. This feature is typically used by daemons, to indicate their state. + +Full job control is only available in the top-level interactive shell, +not in commands run in the left hand side of pipelines or within +the tt(LPAR())var(...)tt(RPAR()) construct. However, a snapshot +of the job state at that point is taken, so it is still possible +to use the tt(jobs) builtin, or any parameter providing job information. +This gives information about the state of jobs at the point the subshell +was created. If background processes are created within the subshell, +then instead information about those processes is provided. + +For example, + +example(sleep 10 & # Job in background +LPAR() # Shell forks +jobs # Shows information about "sleep 10 &" +sleep 5 & # Process in background (no job control) +jobs # Shows information about "sleep 5 &" +RPAR()) ) findex(kill) cindex(killing jobs) @@ -1184,14 +1254,6 @@ Same as tt(typeset), except that the options tt(-g), and tt(-f) are not permitted. In this case the tt(-x) option does not force the use of tt(-g), i.e. exported variables will be local to functions. ) -findex(log) -vindex(watch, use of) -cindex(watching users) -cindex(users, watching) -item(tt(log))( -List all users currently logged in who are affected by -the current setting of the tt(watch) parameter. -) findex(logout) item(tt(logout) [ var(n) ])( Same as tt(exit), except that it only works in a login shell. @@ -1442,7 +1504,7 @@ findex(read) vindex(IFS, use of) redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ ))ifnztexi( ))) xitem(tt(read )[ tt(-rszpqAclneE) ] [ tt(-t) [ var(num) ] ] [ tt(-k) [ var(num) ] ] [ tt(-d) var(delim) ]) -item(SPACES()[ tt(-u) var(n) ] [ var(name)[tt(?)var(prompt)] ] [ var(name) ... ])( +item(SPACES()[ tt(-u) var(n) ] [ [var(name)][tt(?)var(prompt)] ] [ var(name) ... ])( vindex(REPLY, use of) vindex(reply, use of) Read one line and break it into fields using the characters @@ -1576,7 +1638,13 @@ cindex(functions, returning from) item(tt(return) [ var(n) ])( Causes a shell function or `tt(.)' script to return to the invoking script with the return status specified by -an arithmetic expression var(n). If var(n) +an arithmetic expression var(n). +For example, the following prints `tt(42)': + +example(() { integer foo=40; return "foo + 2" } +echo $?) + +If var(n) is omitted, the return status is that of the last command executed. @@ -1587,7 +1655,7 @@ will return to whatever it was previously processing; with a non-zero status, the shell will behave as interrupted except that the return status of the trap is retained. Note that the numeric value of the signal which caused the trap is passed as the first argument, so the statement -`tt(return $((128PLUS()$1)))' will return the same status as if the signal +`tt(return "128PLUS()$1")' will return the same status as if the signal had not been trapped. ) module(sched)(zsh/sched) @@ -1836,7 +1904,8 @@ unfreezing the tty does not guarantee settings made on the command line are preserved. Strings of commands run between editing the command line will see a consistent tty state. See also the shell variable tt(STTY) for a means of initialising -the tty before running external commands. +the tty before running external commands and/or freezing the tty +around a single command. ) findex(type) item(tt(type) [ tt(-wfpamsS) ] var(name) ...)( @@ -1865,7 +1934,11 @@ ifnzman(noderef(Local Parameters))\ retain their special attributes when made local. For each var(name)tt(=)var(value) assignment, the parameter -var(name) is set to var(value). +var(name) is set to var(value). If the assignment is omitted and var(name) +does em(not) refer to an existing parameter, a new parameter is intialized +to empty string, zero, or empty array (as appropriate), em(unless) the +shell option tt(TYPESET_TO_UNSET) is set. When that option is set, +the parameter attributes are recorded but the parameter remains unset. If the shell option tt(TYPESET_SILENT) is not set, for each remaining var(name) that refers to a parameter that is already set, the name and @@ -1933,7 +2006,7 @@ a set of three normal command line arguments to tt(typeset) after expansion. Hence it is not possible to assign to multiple arrays by this means. -Note that each interface to any of the commands my be disabled +Note that each interface to any of the commands may be disabled separately. For example, `tt(disable -r typeset)' disables the reserved word interface to tt(typeset), exposing the builtin interface, while `tt(disable typeset)' disables the builtin. Note that disabling the @@ -2294,7 +2367,7 @@ findex(umask) cindex(umask) item(tt(umask) [ tt(-S) ] [ var(mask) ])( The umask is set to var(mask). var(mask) can be either -an octal number or a symbolic value as described in manref(chmod)(1). +an octal number or a symbolic value as described in the manref(chmod)(1) man page. If var(mask) is omitted, the current value is printed. The tt(-S) option causes the mask to be printed as a symbolic value. Otherwise, the mask is printed as an octal number. Note that in diff --git a/Doc/Zsh/calsys.yo b/Doc/Zsh/calsys.yo index c20c87e61..a8fd876a5 100644 --- a/Doc/Zsh/calsys.yo +++ b/Doc/Zsh/calsys.yo @@ -478,7 +478,7 @@ item(tt(calendar_add) [ tt(-BL) ] var(event) ...)( Adds a single event to the calendar in the appropriate location. The event can contain multiple lines, as described in ifnzman(noderef(Calendar File and Date Formats))\ -ifzman(the section Calendar File Format above). +ifzman(the section `Calendar File Format' above). Using this function ensures that the calendar file is sorted in date and time order. It also makes special arrangements for locking the file while it is altered. The old calendar is left in a file diff --git a/Doc/Zsh/compat.yo b/Doc/Zsh/compat.yo index f1be15fee..4d3567d45 100644 --- a/Doc/Zsh/compat.yo +++ b/Doc/Zsh/compat.yo @@ -30,8 +30,7 @@ tt(PROMPT2), tt(PROMPT3), tt(PROMPT4), tt(psvar), -tt(status), -tt(watch). +tt(status). vindex(ENV, use of) The usual zsh startup/shutdown scripts are not executed. Login shells @@ -74,3 +73,9 @@ tt(PROMPT_SUBST) and tt(SINGLE_LINE_ZLE) options are set if zsh is invoked as tt(ksh). + +Please note that, whilst reasonable efforts are taken to address +incompatibilities when they arise, zsh does not guarantee complete +emulation of other shells, nor POSIX compliance. For more information on +the differences between zsh and other shells, please refer to chapter 2 +of the shell FAQ, uref(https://www.zsh.org/FAQ/). diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index c2d20ca40..584ede441 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -49,7 +49,7 @@ Styles modify various operations of the completion system, such as output formatting, but also what kinds of completers are used (and in what order), or which tags are examined. Styles may accept arguments and are manipulated using the tt(zstyle) command described in -ifzman(see zmanref(zshmodules))\ +ifzman(zmanref(zshmodules))\ ifnzman(noderef(The zsh/zutil Module)). In summary, tags describe em(what) the completion objects are, and style @@ -190,7 +190,7 @@ tt(compinit) will ask if the completion system should really be used. To avoid these tests and make all files found be used without asking, use the option tt(-u), and to make tt(compinit) silently ignore all insecure files and directories use the option tt(-i). This security check is skipped -entirely when the tt(-C) option is given. +entirely when the tt(-C) option is given, provided the dumpfile exists. findex(compaudit) The security check can be retried at any time by running the function @@ -322,15 +322,15 @@ item(tt(-array-value-))( The right hand side of an array-assignment (`var(name)tt(=LPAR())var(...)tt(RPAR())') ) -kindex(-brace-parameter-, completion context) -item(tt(-brace-parameter-))( -The name of a parameter expansion within braces (`tt(${)var(...)tt(})') -) kindex(-assign-parameter-, completion context) item(tt(-assign-parameter-))( The name of a parameter in an assignment, i.e. on the left hand side of an `tt(=)' ) +kindex(-brace-parameter-, completion context) +item(tt(-brace-parameter-))( +The name of a parameter expansion within braces (`tt(${)var(...)tt(})') +) kindex(-command-, completion context) item(tt(-command-))( A word in command position @@ -658,8 +658,8 @@ ifnzman(noderef(Bindable Commands)). When looking up styles the completion system uses full context names, including the tag. Looking up the value of a style therefore consists of two things: the context, which is matched to the most specific (best -fitting) style pattern, and the name of the style itself, which must be -matched exactly. The following examples demonstrate that style patterns +fitting) pattern, and the name of the style itself, which must be +matched exactly. The following examples demonstrate that patterns may be loosely defined for styles that apply broadly, or as tightly defined as desired for styles that apply in narrower circumstances. @@ -673,7 +673,7 @@ example(zstyle ':completion:*' verbose yes) in a startup file (probably tt(.zshrc)). This gives the tt(verbose) style the value tt(yes) in every context inside the completion system, unless that context has a more -specific definition. It is best to avoid giving the context as `tt(*)' +specific definition. It is best to avoid giving the pattern as `tt(*)' in case the style has some meaning outside the completion system. Many such general purpose styles can be configured simply by using the @@ -710,15 +710,21 @@ as tt(menu) and tt(list-rows-first). Note that the order in which styles are em(defined) does not matter; the style mechanism uses the most specific possible match for a particular -style to determine the set of values. More precisely, strings are +style to determine the set of values. Strings are preferred over patterns (for example, `tt(:completion::complete:::foo)' is more specific than `tt(:completion::complete:::*')), and longer patterns are -preferred over shorter patterns. - -A good rule of thumb is that any completion style pattern that needs to -include more than one wildcard (tt(*)) and that does not end in a tag -name, should include all six colons (tt(:)), possibly surrounding -additional wildcards. +preferred over the pattern `tt(*)'. See +ifzman(zmanref(zmodules))ifnzman(noderef(The zsh/zutil Module)) +for details. + +Context patterns that use something other than a wildcard (tt(*)) to match the +middle parts of the context DASH()- the var(completer), var(command), and +var(argument) in +tt(:completion:)var(function)tt(:)var(completer)tt(:)var(command)tt(:)var(argument)tt(:)var(tag) +DASH()- should include all six colons (tt(:)) explicitly. Without this, +a pattern such as tt(:completion:*:foo:*) could match tt(foo) against a +component other than the intended one (for example, against var(completer) when +a match against var(command) was intended). Style names like those of tags are arbitrary and depend on the completion function. However, the following two sections list some of the most @@ -885,14 +891,14 @@ kindex(indexes, completion tag) item(tt(indexes))( for array indexes ) -kindex(jobs, completion tag) -item(tt(jobs))( -for jobs (as listed by the `tt(jobs)' builtin) -) kindex(interfaces, completion tag) item(tt(interfaces))( for network interfaces ) +kindex(jobs, completion tag) +item(tt(jobs))( +for jobs (as listed by the `tt(jobs)' builtin) +) kindex(keymaps, completion tag) item(tt(keymaps))( for names of zsh keymaps @@ -916,14 +922,14 @@ directory when completing arguments of tt(cd) and related builtin commands (compare tt(path-directories)) DASH()- when the tt(cdpath) array is unset, tt(directories) is used instead ) -kindex(manuals, completion tag) -item(tt(manuals))( -for names of manual pages -) kindex(mailboxes, completion tag) item(tt(mailboxes))( for e-mail folders ) +kindex(manuals, completion tag) +item(tt(manuals))( +for names of manual pages +) kindex(maps, completion tag) item(tt(maps))( for map names (e.g. NIS maps) @@ -973,11 +979,6 @@ kindex(other-accounts, completion tag) item(tt(other-accounts))( used to look up the tt(users-hosts) style ) -kindex(other-files, completion tag) -item(tt(other-files))( -for the names of any non-directory files. This is used instead -of tt(all-files) when the tt(list-dirs-first) style is in effect. -) kindex(packages, completion tag) item(tt(packages))( for packages (e.g. tt(rpm) or installed tt(Debian) packages) @@ -1388,6 +1389,12 @@ components after the first ambiguous one will also be added. This means that the resulting string is the longest unambiguous string possible. However, menu completion can be used to cycle through all matches. ) +kindex(extra-verbose, completion style) +item(tt(extra-verbose))( +If set, the completion listing is more verbose at the cost of +a probable decrease in completion speed. Completion performance +will suffer if this style is set to `true'. +) kindex(fake, completion style) item(tt(fake))( This style may be set for any completion context. It @@ -1523,9 +1530,10 @@ If no `tt(:)var(tag)' is given the `tt(files)' tag will be used. The var(tag) may also be followed by an optional second colon and a description, which will be used for the `tt(%d)' in the value of the tt(format) style (if that is set) instead of the default -description supplied by the completion function. If the description -given here contains itself a `tt(%d)', that is replaced with the -description supplied by the completion function. +description supplied by the completion function. The inclusion +of a description also gives precedence to associated options such as +for completion grouping so it can be used where files should be +separated. For example, to make the tt(rm) command first complete only names of object files and then the names of all files if there is no matching @@ -1547,6 +1555,15 @@ all files using the pattern `tt(*)' at the first step and stops when it sees this pattern. Note also it will never try a pattern more than once for a single completion attempt. +To separate directories into a separate group from the files but still +complete them at the first attempt, a description needs to be given. +Note that directories need to be explicitly excluded from the +globbed-files because `tt(*)' will match directories. For grouping, it +is also necessary to set the tt(group-name) style. + +example(zstyle ':completion:*' file-patterns \ + '%p+LPAR()^-/RPAR():globbed-files *(-/):directories:location') + During the execution of completion functions, the tt(EXTENDED_GLOB) option is in effect, so the characters `tt(#)', `tt(~)' and `tt(^)' have special meanings in the patterns. @@ -1641,6 +1658,15 @@ ifzman(zmanref(zshmodules))\ ifnzman(noderef(The zsh/zutil Module))\ . ) +kindex(gain-privileges, completion style) +item(tt(gain-privileges))( +If set to tt(true), this style enables the use of commands like tt(sudo) +or tt(doas) to gain extra privileges when retrieving information for +completion. This is only done when a command such as tt(sudo) appears on +the command-line. To force the use of, e.g. tt(sudo) or to override any +prefix that might be added due to tt(gain-privileges), the tt(command) +style can be used with a value that begins with a hyphen. +) kindex(glob, completion style) item(tt(glob))( This is used by the tt(_expand) completer. If @@ -1679,6 +1705,9 @@ example(zstyle ':completion:*' group-name '') All matches for which no group name is defined will be put in a group named tt(-default-). + +To display the group name in the output, see the tt(format) style (q.v.) +under the tt(descriptions) tag. ) kindex(group-order, completion style) item(tt(group-order))( @@ -1784,12 +1813,6 @@ Excluded values act in a similar fashion to values of the tt(ignored-patterns) style, so they can be restored to consideration by the tt(_ignored) completer. ) -kindex(extra-verbose, completion style) -item(tt(extra-verbose))( -If set, the completion listing is more verbose at the cost of -a probable decrease in completion speed. Completion performance -will suffer if this style is set to `true'. -) kindex(ignored-patterns, completion style) item(tt(ignored-patterns))( A list of patterns; any trial completion matching one of the patterns @@ -1826,6 +1849,28 @@ be unsuccessful until that point. If the value is any other string, menu completion will be started when the string typed by the user is longer than the common prefix to the corresponding IDs. ) +kindex(insert-sections, completion style) +item(tt(insert-sections))( +This style is used with tags of the form `tt(manuals.)var(X)' when +completing names of manual pages. If set and the var(X) in the tag name matches +the section number of the page being completed, the section number is inserted +along with the page name. For example, given + +example(zstyle ':completion:*:manuals.*' insert-sections true) + +tt(man ssh_<TAB>) may be completed to tt(man 5 ssh_config). + +The value may also be set to one of `tt(prepend)', or `tt(suffix)'. +`tt(prepend)' behaves the same as `true' as in the above example, while +`tt(suffix)' would complete tt(man ssh_<TAB>) as tt(man ssh_config.5). + +This is especially useful in conjunction with tt(separate-sections), as +it ensures that the page requested of tt(man) corresponds to the one +displayed in the completion listing when there are multiple pages with the +same name (e.g., tt(printf+LPAR()1+RPAR()) and tt(printf+LPAR()3+RPAR())). + +The default for this style is `false'. +) kindex(insert-tab, completion style) item(tt(insert-tab))( If this is set to `true', the completion system will @@ -1864,15 +1909,6 @@ In the case of the tt(_match) completer, the style may also be set to the string `tt(pattern)'. Then the pattern on the line is left unchanged if it does not match unambiguously. ) -kindex(gain-privileges, completion style) -item(tt(gain-privileges))( -If set to tt(true), this style enables the use of commands like tt(sudo) -or tt(doas) to gain extra privileges when retrieving information for -completion. This is only done when a command such as tt(sudo) appears on -the command-line. To force the use of, e.g. tt(sudo) or to override any -prefix that might be added due to tt(gain-privileges), the tt(command) -style can be used with a value that begins with a hyphen. -) kindex(keep-prefix, completion style) item(tt(keep-prefix))( This style is used by the tt(_expand) completer. If it is `true', the @@ -1888,6 +1924,13 @@ The behaviour of tt(_expand) when this style is `true' is to cause tt(_expand) to give up when a single expansion with the restored prefix is the same as the original; hence any remaining completers may be called. ) +kindex(known-hosts-files) +item(tt(known-hosts-files))( +This style should contain a list of files to search for host names and +(if the tt(use-ip) style is set) IP addresses in a format compatible with +ssh tt(known_hosts) files. If it is not set, the files +tt(/etc/ssh/ssh_known_hosts) and tt(~/.ssh/known_hosts) are used. +) kindex(last-prompt, completion style) item(tt(last-prompt))( This is a more flexible form of the tt(ALWAYS_LAST_PROMPT) option. @@ -1899,13 +1942,6 @@ previous line if this style is `true' for all types of match. Note that unlike the tt(ALWAYS_LAST_PROMPT) option this is independent of the numeric argument. ) -kindex(known-hosts-files) -item(tt(known-hosts-files))( -This style should contain a list of files to search for host names and -(if the tt(use-ip) style is set) IP addresses in a format compatible with -ssh tt(known_hosts) files. If it is not set, the files -tt(/etc/ssh/ssh_known_hosts) and tt(~/.ssh/known_hosts) are used. -) kindex(list, completion style) item(tt(list))( This style is used by the tt(_history_complete_word) bindable command. @@ -1945,11 +1981,10 @@ obtained by setting the style to an empty string (i.e. tt('')). ) kindex(list-dirs-first, completion style) item(tt(list-dirs-first))( -This is used by file completion. If set, directories to be completed -are listed separately from and before completion for other files, -regardless of tag ordering. In addition, the tag tt(other-files) -is used in place of tt(all-files) for the remaining files, to indicate -that no directories are presented with that tag. +This is used by file completion and corresponds to a particular +setting of the tt(file-patterns) style. +If set, the default directories to be completed +are listed separately from and before completion for other files. ) kindex(list-grouped, completion style) item(tt(list-grouped))( @@ -2004,6 +2039,12 @@ This style is tested in the same way as the tt(list-packed) style and determines whether matches are to be listed in a rows-first fashion as if the tt(LIST_ROWS_FIRST) option were set. ) +kindex(list-separator, completion style) +item(tt(list-separator))( +The value of this style is used in completion listing to separate the +string to complete from a description when possible (e.g. when +completing options). It defaults to `tt(-)tt(-)' (two hyphens). +) kindex(list-suffixes, completion style) item(tt(list-suffixes))( This style is used by the function that completes filenames. If it is @@ -2011,12 +2052,6 @@ This style is used by the function that completes filenames. If it is typed pathname components, all ambiguous components will be shown. Otherwise, completion stops at the first ambiguous component. ) -kindex(list-separator, completion style) -item(tt(list-separator))( -The value of this style is used in completion listing to separate the -string to complete from a description when possible (e.g. when -completing options). It defaults to `tt(-)tt(-)' (two hyphens). -) kindex(local, completion style) item(tt(local))( This is for use with functions that complete URLs for which the @@ -2445,7 +2480,7 @@ For example, example(zstyle ':completion:*' recursive-files '*/zsh/*') If the current directory is tt(/home/pws/zsh/Src), then -tt(zle_tr)em(TAB) can be completed to tt(Zle/zle_tricky.c). +tt(zle_tr<TAB>) can be completed to tt(Zle/zle_tricky.c). ) kindex(regular, completion style) item(tt(regular))( @@ -2502,12 +2537,13 @@ kindex(separate-sections, completion style) item(tt(separate-sections))( This style is used with the tt(manuals) tag when completing names of manual pages. If it is `true', entries for different sections are -added separately using tag names of the form `tt(manual.)var(X)', +added separately using tag names of the form `tt(manuals.)var(X)', where var(X) is the section number. When the tt(group-name) style is also in effect, pages from different sections will appear separately. This style is also used similarly with the tt(words) style when completing words for the dict command. It allows words from different -dictionary databases to be added separately. +dictionary databases to be added separately. See also tt(insert-sections). + The default for this style is `false'. ) kindex(show-ambiguity, completion style) @@ -3584,8 +3620,18 @@ described using the var(spec)s which are of the form: `var(tag)tt(:)var(descr)tt(:)var(action)'. The var(tag)s are offered using tt(_tags) and if the tag is requested, the var(action) is executed with the given description var(descr). The var(action)s are those accepted -by the tt(_arguments) function (described below), excluding the -`tt(->)var(state)' and `tt(=)var(...)' forms. +by the tt(_arguments) function (described below), with the following +exceptions: +startitemize() +itemiz(\ +The `tt(->)var(state)' and `tt(=)var(...)' forms are not supported. +) +itemiz(\ +The `tt(LPAR()LPAR()a\:bar b\:baz)tt(RPAR()RPAR())' form does not need +the colon to be escaped, since the var(spec)s have no colon-separated fields +after the var(action). +) +enditemize() For example, the var(action) may be a simple function call: @@ -3715,6 +3761,12 @@ The default var(matchspec) allows partial word completion after `tt(_)' and var(matchspec) is: example(tt(r:|[_-]=* r:|=*)) ) +item(tt(-0))( +When populating values of the `tt(opt_args)' associative array, don't +backslash-escape colons and backslashes and use NUL rather than colon for +joining multiple values. This option is described in more detail below, under +the heading em(var(spec)s: actions). +) enditem() em(var(spec)s: overview) @@ -3887,6 +3939,7 @@ specific contexts: on the first call `tt(_arguments $global_options)' is used, and on subsequent calls `tt(_arguments !$^global_options)'. em(var(spec)s: actions) +COMMENT(If you change this section title, change the references to it in running text.) In each of the forms above the var(action) determines how completions should be generated. Except for the `tt(->)var(string)' @@ -4008,9 +4061,21 @@ the normal arguments from the command line, i.e. the words from the command line after the command name excluding all options and their arguments. Options are stored in the associative array `tt(opt_args)' with option names as keys and their arguments as -the values. For options that have more than one argument these are -given as one string, separated by colons. All colons and backslashes -in the original arguments are preceded with backslashes. +the values. By default, all colons and backslashes in the value are escaped +with backslashes, and if an option has multiple arguments (for example, when +using an var(optspec) of the form `tt(*)var(optspec)'), they are joined with +(unescaped) colons. However, if the tt(-0) option was passed, no backslash +escaping is performed, and multiple values are joined with NUL bytes. For +example, after `tt(zsh -o foo:foo -o bar:bar -o <TAB>)', the contents of +`tt(opt_args)' would be + +example(typeset -A opt_args=( [-o]='foo\:foo:bar\:bar:' )) + +by default, and + +example(typeset -A opt_args=( [-o]=$'foo:foo\x00bar:bar\x00' )) + +if tt(_arguments) had been called with the tt(-0) option. The parameter `tt(context)' is set when returning to the calling function to perform an action of the form `tt(->)var(string)'. It is set to an @@ -4223,7 +4288,7 @@ The last two descriptions say what should be completed as arguments. The first describes the first argument as a `var(postscript file)' and makes files ending in `tt(ps)' or `tt(eps)' be completed. The last description gives all other arguments the -description `var(page numbers)' but does not offer completions. +description `var(page number)' but does not offer completions. ) findex(_cache_invalid) item(tt(_cache_invalid) var(cache_identifier))( @@ -4349,6 +4414,15 @@ Include the leading underscore (`tt(_)') in the matches. ) enditem() ) +findex(_default) +item(tt(_default))( +This function corresponds to the tt(-default-) special context which is +applied where no completion is defined. It is useful to call it under +certain error conditions such as completion after an unrecognised +subcommand. This applies the concept of graceful degradation to the +completion system, allowing it to fallback on basic completion of +commonly useful things like filenames. +) findex(_describe) redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ @ @ ))ifnztexi( ))) xitem(tt(_describe )[tt(-12JVx)] [ tt(-oO) | tt(-t) var(tag) ] var(descr) var(name1) [ var(name2) ] [ var(opt) ... ]) @@ -4422,8 +4496,22 @@ not contain an explanation string to be displayed above the matches. If tt(_description) is called with more than three arguments, the additional var(spec)s should be of the form `var(char)tt(:)var(str)'. These supply escape sequence replacements for the tt(format) style: -every appearance of `tt(%)var(char)' will be -replaced by var(string). +every appearance of `tt(%)var(char)' will be replaced by var(string). +If no additional var(spec)s are given but the description in var(descr) +conforms to a common form then further escape sequences are set for +elements of that description. These elements correspond to a default +value (`tt(%o)'), the units (`tt(%m)') range of acceptable values +(`tt(%r)') and the remaining initial part of the description (`tt(%h)'). +The form the description takes consists of specifying the units and +range in parentheses and the default value in square brackets, for +example: + +example(_description times expl 'timeout (seconds) (0-60) [20]') + +It is possible to use tt(zformat) conditional expressions when styling +these elements. So, for example, to add `tt(default:)' as a tag but only +when there is a default value to show, the tt(format) style might +include `tt(%(o.default: %o.))'. If the tt(-x) option is given, the description will be passed to tt(compadd) using the tt(-x) option instead of the default tt(-X). This @@ -4699,6 +4787,69 @@ checked. If it is set completion is terminated at that point even if no matches have been found. This is the same effect as in the tt(-first-) context. ) +findex(_numbers) +item(tt(_numbers) [ var(option) ... ] [ var(description) ] [ var(suffix) ... ])( +This can be used where a number is followed by a suffix to indicate the units. +The unit suffixes are completed and can also be included in the description +used when completion is invoked for the preceding number. + +In addition to common tt(compadd) options, tt(_numbers) accepts the following +options: + +startitem() +item(tt(-t) var(tag))( +Specify a tag to use instead of the default of tt(numbers). +) +item(tt(-u) var(units))( +Indicate the default units for the number, e.g. tt(bytes). +) +item(tt(-l) var(min))( +Specify the lowest possible value for the number. +) +item(tt(-m) var(max))( +Specify the highest possible value for the number. +) +item(tt(-d) var(default))( +Specify the default value. +) +item(tt(-N))( +Allow negative numbers. This is implied if the range includes a negative. +) +item(tt(-f))( +Allow decimal numbers. +) +enditem() + +Where a particular suffix represents the default units for a number, it +should be prefixed with a colon. Additionally, suffixes can be followed +by a colon and a description. So for example, the following allows the +age of something to be specified, either in seconds or with an optional +suffix with a longer unit of time: + +example(_numbers -u seconds age :s:seconds m:minutes h:hours d:days) + +It is typically helpful for units to be presented in order of magnitude +when completed. To facilitate this, the order in which they are given +is preserved. + +When the tt(format) style is looked up with the tt(descriptions) tag or +the tag specified with tt(-t), the list of suffixes is available as a +`tt(%x)' escape sequence. This is in addition to the usual sequences +documented under the tt(format) style. The form this list takes can also +be configured. To this end, the tt(format) style is first looked up with +the tag tt(unit-suffixes). The retrieved format is applied to each +suffix in turn and the results are then concatenated to form the +completed list. For the tt(unit-suffixes) format, `tt(%x)' expands to +the individual suffix and `tt(%X)' to its description. tt(%d)' indicates +a default suffix and can be used in a condition. The index and reverse +index are set in `tt(%i)' and `tt(%r)' respectively and are useful for +text included only with the first and last suffixes in the list. So for +example, the following joins the suffixes together as a comma-separated +list: + +example(zstyle ':completion:*:unit-suffixes' format '%x%(r::,)') +) + findex(_options) item(tt(_options))( This can be used to complete the names of shell options. It provides a @@ -5244,7 +5395,11 @@ matches with the given description: example(local expl _wanted tag expl 'description' \ - compadd matches...) + compadd -- var(match1) var(match2)...) + +See also the use of tt(_wanted) in the example function in +ifzman(the subsection `Dynamic named directories' in zmanref(zshexpn))\ +ifnzman(noderef(Dynamic named directories)). Note that, as for tt(_requested), the var(command) must be able to accept options to be passed down to tt(compadd). @@ -5284,7 +5439,6 @@ in the tt(_comp_caller_options) associative array. Option names, spelled in lowercase without underscores, are mapped to one or other of the strings `tt(on)' and `tt(off)'. ) - item(tt(_comp_priv_prefix))( Completion functions such as tt(_sudo) can set the tt(_comp_priv_prefix) array to a command prefix that may then be used by tt(_call_program) to @@ -5292,6 +5446,8 @@ match the privileges when calling programs to generate matches. ) enditem() +vindex(compprefuncs, use of) +vindex(comppostfuncs, use of) Two more features are offered by the tt(_main_complete) function. The arrays tt(compprefuncs) and tt(comppostfuncs) may contain names of functions that are to be called immediately before or after diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo index 0b98d07b2..d32a0702f 100644 --- a/Doc/Zsh/compwid.yo +++ b/Doc/Zsh/compwid.yo @@ -39,7 +39,7 @@ using the tt(bindkey) builtin command defined in the tt(zsh/zle) module ifzman(see zmanref(zshzle))\ ifnzman(noderef(Zsh Line Editor))\ ), typing that key will call the shell function `tt(completer)'. This -function is responsible for generating the possible matches using the +function is responsible for generating completion matches using the builtins described below. As with other ZLE widgets, the function is called with its standard input closed. @@ -213,7 +213,7 @@ The string of an exact match if one was found, otherwise unset. ) vindex(ignored, compstate) item(tt(ignored))( -The number of words that were ignored because they matched one of the +The number of completions that were ignored because they matched one of the patterns given with the tt(-F) option to the tt(compadd) builtin command. ) @@ -309,8 +309,7 @@ will be used in the same way as the value of tt(LISTMAX). ) vindex(nmatches, compstate) item(tt(nmatches))( -The number of matches generated and accepted by the completion code so -far. +The number of matches added by the completion code so far. ) vindex(old_insert, compstate) item(tt(old_insert))( @@ -346,7 +345,8 @@ value of a parameter assignment. vindex(pattern_insert, compstate) item(tt(pattern_insert))( Normally this is set to tt(menu), which specifies that menu completion will -be used whenever a set of matches was generated using pattern matching. If +be used whenever a set of matches was generated using tt(pattern_match) +(see below). If it is set to any other non-empty string by the user and menu completion is not selected by other option settings, the code will instead insert any common prefix for the generated matches as with normal completion. @@ -362,7 +362,7 @@ command line will be treated as patterns; if it is `tt(*)', then additionally a wildcard `tt(*)' is assumed at the cursor position; if it is empty or unset, metacharacters will be treated literally. -Note that the matcher specifications given to the tt(compadd) builtin +Note that the match specifications given to the tt(compadd) builtin command are not used if this is set to a non-empty string. ) vindex(quote, compstate) @@ -456,17 +456,16 @@ xitem(SPACES()[tt(-V) var(group-name) ] [ tt(-o) [ var(order) ] ]) xitem(SPACES()[tt(-r) var(remove-chars) ] [ tt(-R) var(remove-func) ]) xitem(SPACES()[tt(-D) var(array) ] [ tt(-O) var(array) ] [ tt(-A) var(array) ]) xitem(SPACES()[tt(-E) var(number) ]) -item(SPACES()[tt(-M) var(match-spec) ] [ tt(-)tt(-) ] [ var(words) ... ])( +item(SPACES()[tt(-M) var(match-spec) ] [ tt(-)tt(-) ] [ var(completions) ... ])( This builtin command can be used to add matches directly and control all the information the completion code stores with each possible -match. The return status is zero if at least one match was added and +completion. The return status is zero if at least one match was added and non-zero if no matches were added. -The completion code breaks the string to complete into seven fields in -the order: +The completion code breaks each match into seven fields in the order: -indent(var(<ipre><apre><hpre><word><hsuf><asuf><isuf>)) +indent(var(<ipre><apre><hpre><body><hsuf><asuf><isuf>)) The first field is an ignored prefix taken from the command line, the contents of the @@ -474,12 +473,12 @@ tt(IPREFIX) parameter plus the string given with the tt(-i) option. With the tt(-U) option, only the string from the tt(-i) option is used. The field var(<apre>) is an optional prefix string given with the tt(-P) option. The var(<hpre>) field is a string -that is considered part of the match but that should not be shown when +that is considered part of the match but that should not be shown when listing completions, given with the tt(-p) option; for example, functions that do filename generation might specify -a common path prefix this way. var(<word>) is the part of the match that -should appear in the list of completions, i.e. one of the var(words) given -at the end of the tt(compadd) command line. The suffixes var(<hsuf>), +a common path prefix this way. var(<body>) is the part of the match that +should appear in the list of matches shown to the user. +The suffixes var(<hsuf>), var(<asuf>) and var(<isuf>) correspond to the prefixes var(<hpre>), var(<apre>) and var(<ipre>) and are given by the options tt(-s), tt(-S) and tt(-I), respectively. @@ -488,52 +487,52 @@ The supported flags are: startitem() item(tt(-P) var(prefix))( -This gives a string to be inserted before the given var(words). The +This gives a string to be inserted before each match. The string given is not considered as part of the match and any shell metacharacters in it will not be quoted when the string is inserted. ) item(tt(-S) var(suffix))( -Like tt(-P), but gives a string to be inserted after the match. +Like tt(-P), but gives a string to be inserted after each match. ) item(tt(-p) var(hidden-prefix))( -This gives a string that should be inserted into the command line before the +This gives a string that should be inserted before each match but that should not appear in the list of matches. Unless the tt(-U) option is given, this string must be matched as part of the string on the command line. ) item(tt(-s) var(hidden-suffix))( -Like `tt(-p)', but gives a string to insert after the match. +Like `tt(-p)', but gives a string to insert after each match. ) item(tt(-i) var(ignored-prefix))( -This gives a string to insert into the command line just before any +This gives a string to insert just before any string given with the `tt(-P)' option. Without `tt(-P)' the string is -inserted before the string given with `tt(-p)' or directly before the +inserted before the string given with `tt(-p)' or directly before each match. ) item(tt(-I) var(ignored-suffix))( Like tt(-i), but gives an ignored suffix. ) item(tt(-a))( -With this flag the var(words) are taken as names of arrays and the -possible matches are their values. If only some elements of the -arrays are needed, the var(words) may also contain subscripts, as in +With this flag the var(completions) are taken as names of arrays and the +actual completions are their values. If only some elements of the +arrays are needed, the var(completions) may also contain subscripts, as in `tt(foo[2,-1])'. ) item(tt(-k))( -With this flag the var(words) are taken as names of associative arrays -and the possible matches are their keys. As for tt(-a), the +With this flag the var(completions) are taken as names of associative arrays +and the actual completions are their keys. As for tt(-a), the var(words) may also contain subscripts, as in `tt(foo[(R)*bar*])'. ) item(tt(-d) var(array))( -This adds per-match display strings. The var(array) should contain one -element per var(word) given. The completion code will then display the -first element instead of the first var(word), and so on. The +This adds per-completion display strings. The var(array) should contain one +element per var(completion) given. The completion code will then display the +first element instead of the first var(completion), and so on. The var(array) may be given as the name of an array parameter or directly as a space-separated list of words in parentheses. -If there are fewer display strings than var(words), the leftover -var(words) will be displayed unchanged and if there are more display -strings than var(words), the leftover display strings will be silently +If there are fewer display strings than var(completions), the leftover +var(completions) will be displayed unchanged and if there are more display +strings than var(completions), the leftover display strings will be silently ignored. ) item(tt(-l))( @@ -556,7 +555,8 @@ by the tt(-d) option). This is the default if `tt(-o)' is specified but the var(order) argument is omitted. ) item(tt(nosort))( -This specifies that the matches are pre-sorted and their order should be +This specifies that the var(completions) +are pre-sorted and their order should be preserved. This value only makes sense alone and cannot be combined with any others. ) @@ -570,7 +570,7 @@ Arrange the matches backwards by reversing the sort ordering. enditem() ) item(tt(-J) var(group-name))( -Gives the name of the group of matches the words should be stored in. +Gives the name of the group that the matches should be stored in. ) item(tt(-V) var(group-name))( Like tt(-J) but naming an unsorted group. This option is identical to @@ -616,13 +616,13 @@ produce unexpected results. If arbitrary text is to be passed in a description, it can be escaped using e.g. tt(${my_str//\%/%%}). ) item(tt(-x) var(message))( -Like tt(-X), but the var(message) will be printed even if there are no +Like tt(-X), but the var(message) will be printed even if there are no matches in the group. ) item(tt(-q))( -The suffix given with tt(-S) will be automatically removed if +The suffix given with tt(-S) will be automatically removed if the next character typed is a blank or does not insert anything, or if -the suffix consists of only one character and the next character typed +the suffix consists of only one character and the next character typed is the same character. ) item(tt(-r) var(remove-chars))( @@ -644,8 +644,8 @@ automatically added space will be removed when one of the characters in the list is typed. ) item(tt(-R) var(remove-func))( -This is another form of the tt(-r) option. When a suffix -has been inserted and the completion accepted, the function +This is another form of the tt(-r) option. When a match +has been accepted and a suffix has been inserted, the function var(remove-func) will be called after the next character typed. It is passed the length of the suffix as an argument and can use the special parameters available in ordinary (non-completion) zle widgets (see @@ -654,7 +654,7 @@ ifnzman(noderef(Zsh Line Editor))\ ) to analyse and modify the command line. ) item(tt(-f))( -If this flag is given, all of the matches built from var(words) are +If this flag is given, all of the matches built from the var(completions) are marked as being the names of files. They are not required to be actual filenames, but if they are, and the option tt(LIST_TYPES) is set, the characters describing the types of the files in the completion lists will @@ -668,15 +668,14 @@ the tt(AUTO_PARAM_SLASH) and tt(AUTO_PARAM_KEYS) options be used for the matches. ) item(tt(-W) var(file-prefix))( -This string is a pathname that will be -prepended to each of the matches formed by the given var(words) together +This string is a pathname that will be prepended to each match together with any prefix specified by the tt(-p) option to form a complete filename for testing. Hence it is only useful if combined with the tt(-f) flag, as the tests will not otherwise be performed. ) item(tt(-F) var(array))( -Specifies an array containing patterns. Words matching one of these -patterns are ignored, i.e. not considered to be possible matches. +Specifies an array containing patterns. var(completions) that match one of +these patterns are ignored, that is, not considered to be matches. The var(array) may be the name of an array parameter or a list of literal patterns enclosed in parentheses and quoted, as in `tt(-F "(*?.o @@ -684,8 +683,8 @@ literal patterns enclosed in parentheses and quoted, as in `tt(-F "(*?.o taken as the patterns. ) item(tt(-Q))( -This flag instructs the completion -code not to quote any metacharacters in the words when inserting them +This flag instructs the completion +code not to quote any metacharacters in the matches when inserting them into the command line. ) item(tt(-M) var(match-spec))( @@ -696,47 +695,50 @@ between them to form the specification string to use. Note that they will only be used if the tt(-U) option is not given. ) item(tt(-n))( -Specifies that the words added are to be used as possible -matches, but are not to appear in the completion listing. +Specifies that matching var(completions) are to be added to the set of +matches, but are not to be listed to the user. ) item(tt(-U))( -If this flag is given, all words given will be accepted and no matching +If this flag is given, all var(completions) are added +to the set of matches and no matching will be done by the completion code. Normally this is used in functions that do the matching themselves. ) item(tt(-O) var(array))( -If this option is given, the var(words) are em(not) added to the set of -possible completions. Instead, matching is done as usual and all of the -var(words) given as arguments that match the string on the command line +If this option is given, the var(completions) are em(not) added to the set of +matches. Instead, matching is done as usual and all of the +var(completions) that match will be stored in the array parameter whose name is given as var(array). ) item(tt(-A) var(array))( -As the tt(-O) option, except that instead of those of the var(words) which +As the tt(-O) option, except that instead of those of the var(completions) +which match being stored in var(array), the strings generated internally by the -completion code are stored. For example, -with a matching specification of `tt(-M "L:|no=")', the string `tt(nof)' -on the command line and the string `tt(foo)' as one of the var(words), this +completion code are stored. For example, +with a match specification of `tt(-M "L:|no=")', a current word of `tt(nof)' +and var(completions) of `tt(foo)', this option stores the string `tt(nofoo)' in the array, whereas the tt(-O) option stores the `tt(foo)' originally given. ) item(tt(-D) var(array))( -As with tt(-O), the var(words) are not added to the set of possible -completions. Instead, the completion code tests whether each var(word) -in turn matches what is on the line. If the var(n)th var(word) does not +As with tt(-O), the var(completions) are not added to the set of matches. +Instead, whenever the var(n)th var(completion) does not match, the var(n)th element of the var(array) is removed. Elements -for which the corresponding var(word) is matched are retained. +for which the corresponding var(completion) matches are retained. +This option can be used more than once to remove elements from multiple +arrays. ) item(tt(-C))( This option adds a special match which expands to all other matches when inserted into the line, even those that are added after this option is used. Together with the tt(-d) option it is possible to -specify a string that should be displayed in the list for this special -match. If no string is given, it will be shown as a string containing -the strings that would be inserted for the other matches, truncated to +specify a string that should be displayed in the list for this special +match. If no string is given, it will be shown as a string containing +the strings that would be inserted for the other matches, truncated to the width of the screen. ) item(tt(-E) var(number))( -This option adds var(number) empty matches after the var(words) have +This option adds var(number) empty matches after matching var(completions) have been added. An empty match takes up space in completion listings but will never be inserted in the line and can't be selected with menu completion or menu selection. This makes empty matches only useful to @@ -751,7 +753,7 @@ added. xitem(tt(-)) item(tt(-)tt(-))( This flag ends the list of flags and options. All arguments after it -will be taken as the words to use as matches even if they begin with +will be taken as the var(completions) even if they begin with hyphens. ) enditem() @@ -788,7 +790,7 @@ Without the optional var(number), the longest match is taken, but if var(number) is given, anything up to the var(number)th match is moved. If the var(number) is negative, the var(number)th longest match is moved. For example, if tt(PREFIX) contains the string -`tt(a=b=c)', then tt(compset -P '*\=') will move the string `tt(a=b=)' +`tt(a=b=c)', then tt(compset -P '*\=') will move the string `tt(a=b=)' into the tt(IPREFIX) parameter, but tt(compset -P 1 '*\=') will move only the string `tt(a=)'. ) @@ -801,7 +803,7 @@ As tt(-P), but match the last portion of tt(SUFFIX) and transfer the matched portion to the front of the value of tt(ISUFFIX). ) item(tt(-n) var(begin) [ var(end) ])( -If the current word position as specified by the parameter tt(CURRENT) +If the current word position as specified by the parameter tt(CURRENT) is greater than or equal to var(begin), anything up to the var(begin)th word is removed from the tt(words) array and the value of the parameter tt(CURRENT) is decremented by var(begin). @@ -824,7 +826,7 @@ point to the same word in the changed array. If the optional pattern var(end-pat) is also given, and there is an element in the tt(words) array matching this pattern, the parameters are modified only if the index of this word is higher than the one -given by the tt(CURRENT) parameter (so that the matching word has +given by the tt(CURRENT) parameter (so that the matching word has to be after the cursor). In this case, the words starting with the one matching tt(end-pat) are also removed from the tt(words) array. If tt(words) contains no word matching var(end-pat), the @@ -833,7 +835,7 @@ testing and modification is performed as if it were not given. item(tt(-q))( The word currently being completed is split on spaces into separate words, -respecting the usual shell quoting conventions. The +respecting the usual shell quoting conventions. The resulting words are stored in the tt(words) array, and tt(CURRENT), tt(PREFIX), tt(SUFFIX), tt(QIPREFIX), and tt(QISUFFIX) are modified to reflect the word part that is completed. @@ -885,7 +887,7 @@ item(tt(-suffix) [ var(number) ] var(pattern))( true if the test for the tt(-S) option of tt(compset) would succeed. ) item(tt(-after) var(beg-pat))( -true if the test of the tt(-N) option with only the var(beg-pat) given +true if the test of the tt(-N) option with only the var(beg-pat) given would succeed. ) item(tt(-between) var(beg-pat end-pat))( @@ -896,270 +898,286 @@ enditem() texinode(Completion Matching Control)(Completion Widget Example)(Completion Condition Codes)(Completion Widgets) sect(Completion Matching Control) -It is possible by use of the -tt(-M) option of the tt(compadd) builtin command to specify how the -characters in the string to be completed (referred to here as the -command line) map onto the characters in the list of matches produced by -the completion code (referred to here as the trial completions). Note -that this is not used if the command line contains a glob pattern and -the tt(GLOB_COMPLETE) option is set or the tt(pattern_match) of the -tt(compstate) special association is set to a non-empty string. +When the user invokes completion, the current em(word) on the command line +(that is, the word the cursor is currently on) is used to generate a em(match +pattern). Only those em(completions) that match the pattern are offered to the +user as em(matches). -The var(match-spec) given as the argument to the tt(-M) option (see +The default match pattern is generated from the current word by either + +startitemize() +itemiz(\ +appending a `tt(*)' (matching any number of characters in a completion) +em(or,)\ +) +itemiz(\ +if the shell option tt(COMPLETE_IN_WORD) is set, inserting a `tt(*)' at the +cursor position.\ +) +enditemize() + +This narrow pattern can be broadened selectively by passing a em(match +specification) to the tt(compadd) builtin command through its tt(-M) option +(see ifzman(`Completion Builtin Commands' above)\ ifnzman(noderef(Completion Builtin Commands))\ -) consists of one or more matching descriptions separated by -whitespace. Each description consists of a letter followed by a colon -and then the patterns describing which character sequences on the line match -which character sequences in the trial completion. Any sequence of -characters not handled in this fashion must match exactly, as usual. - -The forms of var(match-spec) understood are as follows. In each case, the -form with an upper case initial character retains the string already -typed on the command line as the final result of completion, while with -a lower case initial character the string on the command line is changed -into the corresponding part of the trial completion. +). A match specification consists of one or more var(matchers) separated by +whitespace. Matchers in a match specification are applied one at a time, from +left to right. Once all matchers have been applied, completions are compared +to the final match pattern and non-matching ones are discarded. + +startitemize() +itemiz(\ +Note that the tt(-M) option is ignored if the current word contains a glob +pattern and the shell option tt(GLOB_COMPLETE) is set or if the +tt(pattern_match) key of the special associative array tt(compstate) is set to +a non-empty value (see +ifzman(`Completion Special Parameters' above)\ +ifnzman(noderef(Completion Special Parameters))\ +).\ +) +itemiz(\ +Users of the \ +ifzman(completion system (see zmanref(zshcompsys))) \ +ifnzman(noderef(Completion System)) \ +should generally not use the tt(-M) option directly, but rather use the +tt(matcher-list) and tt(matcher) styles (see the subsection em(Standard Styles) +in +ifzman(\ +the documentation for COMPLETION SYSTEM CONFIGURATION in zmanref(zshcompsys))\ +ifnzman(noderef(Completion System Configuration))\ +).\ +) +enditemize() + +Each matcher consists of + +startitemize() +itemiz(a case-sensitive letter) +itemiz(a `tt(:)',) +itemiz(one or more patterns separated by pipes (`tt(|)'),) +itemiz(an equals sign (`tt(=)'), and) +itemiz(another pattern.) +enditemize() + +The patterns before the `tt(=)' are used to match substrings of the current +word. For each matched substring, the corresponding part of the match pattern +is broadened with the pattern after the `tt(=)', by means of a logical tt(OR). + +Each pattern in a matcher cosists of either + +startitemize() +itemiz(the empty string or) +itemiz(a sequence of + +startitemize() +itemiz(literal characters (which may be quoted with a `tt(\)'),) +itemiz(question marks (`tt(?)'),) +itemiz(\ +bracket expressions (`tt([...])'; see the subsection em(Glob Operators) in +ifnzman(noderef(Filename Generation))\ +ifzman(the documentation for GLOB OPERATORS in zmanref(zshexpn))\ +), and/or\ +) +itemiz(brace expressions (see below).) +enditemize() +) +enditemize() + +Other shell patterns are not allowed. + +A brace expression, like a bracket expression, consists of a list of + +startitemize() +itemiz(literal characters,) +itemiz(ranges (`tt(0-9)'), and/or) +itemiz(character classes (`tt([:)var(name)tt(:])').) +enditemize() + +However, they differ from each other as follows: + +startitemize() +itemiz(\ +A brace expression is delimited by a pair of braces (`tt({...})').\ +) +itemiz(\ +Brace expressions do not support negations. That is, an initial +`tt(!)' or `tt(^)' has no special meaning and will be interpreted as a literal +character.\ +) +itemiz(\ +When a character in the current word matches the var(n)th pattern in a brace +expression, the corresponding part of the match pattern is broadened only with +the var(n)th pattern of the brace expression on the other side of the `tt(=)', +if there is one; if there is no brace expression on the other side, then this +pattern is the empty string. However, if either brace expression has more +elements than the other, then the excess entries are simply ignored. When +comparing indexes, each literal character or character class counts as one +element, but each range is instead expanded to the full list of literal +characters it represents. Additionally, if on em(both) sides of the +`tt(=)', the var(n)th pattern is `tt([:upper:])' or `tt([:lower:])', then these +are expanded as ranges, too.\ +) +enditemize() + +Note that, although the matching system does not yet handle multibyte +characters, this is likely to be a future extension. Hence, using +`tt([:upper:])' and `tt([:lower:])' is recommended over +`tt(A-Z)' and `tt(a-z)'. + +Below are the different forms of matchers supported. Each em(uppercase) form +behaves exactly like its lowercase counterpart, but adds an additional step +em(after) the match pattern has filtered out non-matching completions: Each of +a match's substrings that was matched by a subpattern from an uppercase matcher +is replaced with the corresponding substring of the current word. However, +patterns from em(lowercase) matchers have higher weight: If a substring of the +current word was matched by patterns from both a lowercase and an uppercase +matcher, then the lowercase matcher's pattern wins and the corresponding part +of the match is not modified. + +Unless indicated otherwise, each example listed assumes tt(COMPLETE_IN_WORD) to +be unset (as it is by default). startitem() -xitem(tt(m:)var(lpat)tt(=)var(tpat)) -item(tt(M:)var(lpat)tt(=)var(tpat))( -Here, var(lpat) is a pattern that matches on the command line, -corresponding to var(tpat) which matches in the trial completion. -) -xitem(tt(l:)var(lanchor)tt(|)var(lpat)tt(=)var(tpat)) -xitem(tt(L:)var(lanchor)tt(|)var(lpat)tt(=)var(tpat)) -xitem(tt(l:)var(lanchor)tt(||)var(ranchor)tt(=)var(tpat)) -xitem(tt(L:)var(lanchor)tt(||)var(ranchor)tt(=)var(tpat)) -xitem(tt(b:)var(lpat)tt(=)var(tpat)) -item(tt(B:)var(lpat)tt(=)var(tpat))( -These letters are for patterns that are anchored by another pattern on -the left side. Matching for var(lpat) and var(tpat) is as for tt(m) and -tt(M), but the pattern var(lpat) matched on the command line must be -preceded by the pattern var(lanchor). The var(lanchor) can be blank to -anchor the match to the start of the command line string; otherwise the -anchor can occur anywhere, but must match in both the command line and -trial completion strings. - -If no var(lpat) is given but a var(ranchor) is, this matches the gap -between substrings matched by var(lanchor) and var(ranchor). Unlike -var(lanchor), the var(ranchor) only needs to match the trial -completion string. - -The tt(b) and tt(B) forms are similar to tt(l) and tt(L) with an empty -anchor, but need to match only the beginning of the word on the command line -or trial completion, respectively. -) -xitem(tt(r:)var(lpat)tt(|)var(ranchor)tt(=)var(tpat)) -xitem(tt(R:)var(lpat)tt(|)var(ranchor)tt(=)var(tpat)) -xitem(tt(r:)var(lanchor)tt(||)var(ranchor)tt(=)var(tpat)) -xitem(tt(R:)var(lanchor)tt(||)var(ranchor)tt(=)var(tpat)) -xitem(tt(e:)var(lpat)tt(=)var(tpat)) -item(tt(E:)var(lpat)tt(=)var(tpat))( -As tt(l), tt(L), tt(b) and tt(B), with the difference that the command -line and trial completion patterns are anchored on the right side. -Here an empty var(ranchor) and the tt(e) and tt(E) forms force the -match to the end of the command line or trial completion string. +xitem(tt(m:)var(word-pat)tt(=)var(match-pat)) +item(tt(M:)var(word-pat)tt(=)var(match-pat))( + +For each substring of the current word that matches var(word-pat), broaden the +corresponding part of the match pattern to additionally match var(match-pat). + +startitem() +item(Examples:)( + +tt(m:{[:lower:]}={[:upper:]}) lets any lower case character in the current word +be completed to itself or its uppercase counterpart. So, the completions +`tt(foo)', `tt(FOO)' and `tt(Foo)' will are be considered matches for the word +`tt(fo)'. + +tt(M:_=) inserts every underscore from the current word into each match, in the +same relative position, determined by matching the substrings around it. So, +given a completion `tt(foo)', the word `tt(f_o)' will be completed to the match +`tt(f_oo)', even though the latter was not present as a completion. ) -item(tt(x:))( -This form is used to mark the end of matching specifications: -subsequent specifications are ignored. In a single standalone list -of specifications this has no use but where matching specifications -are accumulated, such as from nested function calls, it can allow one -function to override another. +enditem() +) +xitem(tt(b:)var(word-pat)tt(=)var(match-pat)) +xitem(tt(B:)var(word-pat)tt(=)var(match-pat)) +xitem(tt(e:)var(word-pat)tt(=)var(match-pat)) +item(tt(E:)var(word-pat)tt(=)var(match-pat))( + +For each consecutive substring at the tt(b:)eginning or tt(e:)nd of the current +word that matches var(word-pat), broaden the corresponding part of the match +pattern to additionally match var(match-pat). + +startitem() +item(Examples:)( + +`tt(b:-=+)' lets any number of minuses at the start of the current word be +completed to a minus or a plus. + +`tt(B:0=)' adds all zeroes at the beginning of the current word to the +beginning of each match. ) enditem() +) +xitem(tt(l:)tt(|)var(word-pat)tt(=)var(match-pat)) +xitem(tt(L:)tt(|)var(word-pat)tt(=)var(match-pat)) +xitem(tt(R:)var(word-pat)tt(|)tt(=)var(match-pat)) +item(tt(r:)var(word-pat)tt(|)tt(=)var(match-pat))( -Each var(lpat), var(tpat) or var(anchor) is either an empty string or -consists of a sequence of literal characters (which may be quoted with a -backslash), question marks, character classes, and correspondence -classes; ordinary shell patterns are not used. Literal characters match -only themselves, question marks match any character, and character -classes are formed as for globbing and match any character in the given -set. - -Correspondence classes are defined like character classes, but with two -differences: they are delimited by a pair of braces, and negated classes -are not allowed, so the characters tt(!) and tt(^) have no special -meaning directly after the opening brace. They indicate that a range of -characters on the line match a range of characters in the trial -completion, but (unlike ordinary character classes) paired according to -the corresponding position in the sequence. For example, to make any -ASCII lower case letter on the line match the corresponding upper case -letter in the trial completion, you can use `tt(m:{a-z}={A-Z})' -(however, see below for the recommended form for this). More -than one pair of classes can occur, in which case the first class before -the tt(=) corresponds to the first after it, and so on. If one side has -more such classes than the other side, the superfluous classes behave -like normal character classes. In anchor patterns correspondence classes -also behave like normal character classes. - -The standard `tt([:)var(name)tt(:])' forms described for standard shell -patterns (see -ifnzman(noderef(Filename Generation))\ -ifzman(the section FILENAME GENERATION in zmanref(zshexpn))) -may appear in correspondence classes as well as normal character -classes. The only special behaviour in correspondence classes is if -the form on the left and the form on the right are each one of -tt([:upper:]), tt([:lower:]). In these cases the -character in the word and the character on the line must be the same up -to a difference in case. Hence to make any lower case character on the -line match the corresponding upper case character in the trial -completion you can use `tt(m:{[:lower:]}={[:upper:]})'. Although the -matching system does not yet handle multibyte characters, this is likely -to be a future extension, at which point this syntax will handle -arbitrary alphabets; hence this form, rather than the use of explicit -ranges, is the recommended form. In other cases -`tt([:)var(name)tt(:])' forms are allowed. If the two forms on the left -and right are the same, the characters must match exactly. In remaining -cases, the corresponding tests are applied to both characters, but they -are not otherwise constrained; any matching character in one set goes -with any matching character in the other set: this is equivalent to the -behaviour of ordinary character classes. - -The pattern var(tpat) may also be one or two stars, `tt(*)' or -`tt(**)'. This means that the pattern on the command line can match -any number of characters in the trial completion. In this case the -pattern must be anchored (on either side); in the case of a single -star, the var(anchor) then determines how much of the trial completion -is to be included DASH()- only the characters up to the next appearance of -the anchor will be matched. With two stars, substrings matched by the -anchor can be matched, too. - -Examples: - -The keys of the tt(options) association defined by the tt(parameter) -module are the option names in all-lower-case form, without -underscores, and without the optional tt(no) at the beginning even -though the builtins tt(setopt) and tt(unsetopt) understand option names -with upper case letters, underscores, and the optional tt(no). The -following alters the matching rules so that the prefix tt(no) and any -underscore are ignored when trying to match the trial completions -generated and upper case letters on the line match the corresponding -lower case letters in the words: - -example(compadd -M 'L:|[nN][oO]= M:_= M:{[:upper:]}={[:lower:]}' - \ - ${(k)options} ) - -The first part says that the pattern `tt([nN][oO])' at the beginning -(the empty anchor before the pipe symbol) of the string on the -line matches the empty string in the list of words generated by -completion, so it will be ignored if present. The second part does the -same for an underscore anywhere in the command line string, and the -third part uses correspondence classes so that any -upper case letter on the line matches the corresponding lower case -letter in the word. The use of the upper case forms of the -specification characters (tt(L) and tt(M)) guarantees that what has -already been typed on the command line (in particular the prefix -tt(no)) will not be deleted. - -Note that the use of tt(L) in the first part means that it matches -only when at the beginning of both the command line string and the -trial completion. I.e., the string `tt(_NO_f)' would not be -completed to `tt(_NO_foo)', nor would `tt(NONO_f)' be completed to -`tt(NONO_foo)' because of the leading underscore or the second -`tt(NO)' on the line which makes the pattern fail even though they are -otherwise ignored. To fix this, one would use `tt(B:[nN][oO]=)' -instead of the first part. As described above, this matches at the -beginning of the trial completion, independent of other characters or -substrings at the beginning of the command line word which are ignored -by the same or other var(match-spec)s. - -The second example makes completion case insensitive. This is just -the same as in the option example, except here we wish to retain the -characters in the list of completions: - -example(compadd -M 'm:{[:lower:]}={[:upper:]}' ... ) - -This makes lower case letters match their upper case counterparts. -To make upper case letters match the lower case forms as well: - -example(compadd -M 'm:{[:lower:][:upper:]}={[:upper:][:lower:]}' ... ) - -A nice example for the use of tt(*) patterns is partial word -completion. Sometimes you would like to make strings like `tt(c.s.u)' -complete to strings like `tt(comp.source.unix)', i.e. the word on the -command line consists of multiple parts, separated by a dot in this -example, where each part should be completed separately DASH()- note, -however, that the case where each part of the word, i.e. `tt(comp)', -`tt(source)' and `tt(unix)' in this example, is to be completed from -separate sets of matches -is a different problem to be solved by the implementation of the -completion widget. The example can be handled by: - -example(compadd -M 'r:|.=* r:|=*' \ - - comp.sources.unix comp.sources.misc ...) - -The first specification says that var(lpat) is the empty string, while -var(anchor) is a dot; var(tpat) is tt(*), so this can match anything -except for the `tt(.)' from the anchor in -the trial completion word. So in `tt(c.s.u)', the matcher sees `tt(c)', -followed by the empty string, followed by the anchor `tt(.)', and -likewise for the second dot, and replaces the empty strings before the -anchors, giving `tt(c)[tt(omp)]tt(.s)[tt(ources)]tt(.u)[tt(nix)]', where -the last part of the completion is just as normal. - -With the pattern shown above, the string `tt(c.u)' could not be -completed to `tt(comp.sources.unix)' because the single star means -that no dot (matched by the anchor) can be skipped. By using two stars -as in `tt(r:|.=**)', however, `tt(c.u)' could be completed to -`tt(comp.sources.unix)'. This also shows that in some cases, -especially if the anchor is a real pattern, like a character class, -the form with two stars may result in more matches than one would like. - -The second specification is needed to make this work when the cursor is -in the middle of the string on the command line and the option -tt(COMPLETE_IN_WORD) is set. In this case the completion code would -normally try to match trial completions that end with the string as -typed so far, i.e. it will only insert new characters at the cursor -position rather than at the end. However in our example we would like -the code to recognise matches which contain extra characters after the -string on the line (the `tt(nix)' in the example). Hence we say that the -empty string at the end of the string on the line matches any characters -at the end of the trial completion. - -More generally, the specification - -example(compadd -M 'r:|[.,_-]=* r:|=*' ... ) - -allows one to complete words with abbreviations before any of the -characters in the square brackets. For example, to -complete tt(veryverylongfile.c) rather than tt(veryverylongheader.h) -with the above in effect, you can just type tt(very.c) before attempting -completion. - -The specifications with both a left and a right anchor are useful to -complete partial words whose parts are not separated by some -special character. For example, in some places strings have to be -completed that are formed `tt(LikeThis)' (i.e. the separate parts are -determined by a leading upper case letter) or maybe one has to -complete strings with trailing numbers. Here one could use the simple -form with only one anchor as in: - -example(compadd -M 'r:|[[:upper:]0-9]=* r:|=*' LikeTHIS FooHoo 5foo123 5bar234) - -But with this, the string `tt(H)' would neither complete to `tt(FooHoo)' -nor to `tt(LikeTHIS)' because in each case there is an upper case -letter before the `tt(H)' and that is matched by the anchor. Likewise, -a `tt(2)' would not be completed. In both cases this could be changed -by using `tt(r:|[[:upper:]0-9]=**)', but then `tt(H)' completes to both -`tt(LikeTHIS)' and `tt(FooHoo)' and a `tt(2)' matches the other -strings because characters can be inserted before every upper case -letter and digit. To avoid this one would use: - -example(compadd -M 'r:[^[:upper:]0-9]||[[:upper:]0-9]=** r:|=*' \ - LikeTHIS FooHoo foo123 bar234) - -By using these two anchors, a `tt(H)' matches only upper case `tt(H)'s that -are immediately preceded by something matching the left anchor -`tt([^[:upper:]0-9])'. The effect is, of course, that `tt(H)' matches only -the string `tt(FooHoo)', a `tt(2)' matches only `tt(bar234)' and so on. - -When using the completion system (see -ifzman(zmanref(zshcompsys))\ +If there is a substring at the tt(l:)eft or tt(r:)ight edge of the current word +that matches var(word-pat), then broaden the corresponding part of the match +pattern to additionally match var(match-pat). + +For each tt(l:), tt(L:), tt(r:) and tt(R:) matcher (including the ones below), +the pattern var(match-pat) may also be a `tt(*)'. This matches any number of +characters in a completion. + +startitem() +item(Examples:)( + +`tt(r:|=*)' appends a `tt(*)' to the match pattern, even when +tt(COMPLETE_IN_WORD) is set and the cursor is not at the end of the current +word. + +If the current word starts with a minus, then `tt(L:|-=)' will prepend it to +each match. +) +enditem() +) +xitem(tt(l:)var(anchor)tt(|)var(word-pat)tt(=)var(match-pat)) +xitem(tt(L:)var(anchor)tt(|)var(word-pat)tt(=)var(match-pat)) +xitem(tt(r:)var(word-pat)tt(|)var(anchor)tt(=)var(match-pat)) +item(tt(R:)var(word-pat)tt(|)var(anchor)tt(=)var(match-pat))( + +For each substring of the current word that matches var(word-pat) and has on +its tt(l:)eft or tt(r:)ight another substring matching var(anchor), broaden the +corresponding part of the match pattern to additionally match var(match-pat). + +Note that these matchers (and the ones below) modify only what is matched by +var(word-pat); they do not change the matching behavior of what is matched by +var(anchor) (or var(coanchor); see the matchers below). Thus, unless its +corresponding part of the match pattern has been modified, the anchor in the +current word has to match literally in each completion, just like any other +substring of the current word. + +If a matcher includes at least one anchor (which includes the matchers with two +anchors, below), then var(match-pat) may also be `tt(*)' or `tt(**)'. `tt(*)' +can match any part of a completion that does not contain any substrings +matching var(anchor), whereas a `tt(**)' can match any part of a completion, +period. (Note that this is different from the behavior of `tt(*)' in the +anchorless forms of `tt(l:)' and `tt(r:)' and and also different from `tt(*)' +and `tt(**)' in glob expressions.) + +startitem() +item(Examples:)( + +`tt(r:|.=*)' makes the completion `tt(comp.sources.unix)' a match for the word +`tt(..u)' DASH()- but em(not) for the word `tt(.u)'. + +Given a completion `tt(-)tt(-foo)', the matcher `tt(L:--|no-=)' will complete +the word `tt(-)tt(-no-)' to the match `tt(-)tt(-no-foo)'. +) +enditem() +) +xitem(tt(l:)var(anchor)tt(||)var(coanchor)tt(=)var(match-pat)) +xitem(tt(L:)var(anchor)tt(||)var(coanchor)tt(=)var(match-pat)) +xitem(tt(r:)var(coanchor)tt(||)var(anchor)tt(=)var(match-pat)) +item(tt(R:)var(coanchor)tt(||)var(anchor)tt(=)var(match-pat))( + +For any two consecutive substrings of the current word that match var(anchor) +and var(coanchor), in the order given, insert the pattern var(match-pat) +between their corresponding parts in the match pattern. + +Note that, unlike var(anchor), the pattern var(coanchor) does not change what +`tt(*)' can match. + +startitem() +item(Examples:)( + +`tt(r:?||[[:upper:]]=*)' will complete the current word `tt(fB)' to +`tt(fooBar)', but it will not complete it to `tt(fooHooBar)' (because `tt(*)' +here cannot match anything that includes a match for `tt([[:upper:]])), nor +will it complete `tt(B)' to `tt(fooBar)' (because there is no character in the +current word to match var(coanchor)). + +Given the current word `tt(pass.n)' and a completion `tt(pass.byname)', the +matcher `tt(L:.||[[:alpha:]]=by)' will produce the match `tt(pass.name)'. +) +enditem() +) +item(tt(x:))( + +Ignore this matcher and all matchers to its right. + +This matcher is used to mark the end of a match specification. In a single +standalone list of matchers, this has no use, but where match specifications +are concatenated, as is often the case when using the +ifzman(completion system (see zmanref(zshcompsys)))\ ifnzman(noderef(Completion System))\ -), users can define match specifications that are to be used for -specific contexts by using the tt(matcher) and tt(matcher-list) -styles. The values for the latter will be used everywhere. +, it can allow one match specification to override another. +) +enditem() texinode(Completion Widget Example)()(Completion Matching Control)(Completion Widgets) sect(Completion Widget Example) @@ -1180,5 +1198,5 @@ matches, e.g.: example(complete-files LPAR()RPAR() { compadd - * }) -This function will complete files in the current directory matching the +This function will complete files in the current directory matching the current word. diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index c6bf745b7..0ef59dbc9 100644 --- a/Doc/Zsh/contrib.yo +++ b/Doc/Zsh/contrib.yo @@ -347,7 +347,7 @@ as the var(hook) argument. var(widgetname) is the name of a ZLE widget. If no options are given this is added to the array of widgets to be invoked in the given hook context. Widgets are invoked in the order they were added, with -example(tt(zle )var(widgetname)tt( -Nw -- "$@")) +example(tt(zle )var(widgetname)tt( -Nw -f "nolast" -- "$@")) vindex(WIDGET, in hooks) Note that this means that the `tt(WIDGET)' special parameter tracks the @@ -465,7 +465,7 @@ allows you to edit the list of directories, one per line. The list can be edited to any extent you like; no sanity checking is performed. Completion is available. No quoting is necessary (except for newlines, where I have in any case no sympathy); directories are in -unabbreviated from and contain an absolute path, i.e. they start with tt(/). +unabbreviated form and contain an absolute path, i.e. they start with tt(/). Usually the first entry should be left as the current directory. ) item(tt(-p ')var(pattern)tt('))( @@ -598,7 +598,7 @@ changes to descendant directories; earlier directories on the list are not pruned. For example, changing from ~pws/yet/another to ~pws/some/other/dir does not cause ~pws to be pruned. ) -item(tt(pattern:var(pattern)))( +item(tt(pattern:)var(pattern))( Gives a zsh pattern for directories that should not be added to the recent list (if not already there). This element can be repeated to add different patterns. For example, @@ -660,7 +660,7 @@ sect(Abbreviated dynamic references to directories) The dynamic directory naming system is described in the subsection em(Dynamic named directories) of -ifzman(the section em(Filename Expansion) in zmanref(expn))\ +ifzman(the section em(Filename Expansion) in zmanref(zshexpn))\ ifnzman(noderef(Filename Expansion)). In this, a reference to tt(~[)var(...)tt(]) is expanded by a function found by the hooks mechanism. @@ -708,7 +708,7 @@ that the wrapper function gets. This configuration is described below. Then arrange for the wrapper to be run as a zsh_directory_name hook: -example(autoload -Uz add-zsh-hook zsh_diretory_name_generic zdn_mywrapper +example(autoload -Uz add-zsh-hook zsh_directory_name_generic zdn_mywrapper add-zsh-hook -U zsh_directory_name zdn_mywrapper) subsect(Configuration) @@ -1159,7 +1159,7 @@ This is used by the Perforce backend (tt(p4)) to decide if it should contact the Perforce server to find out if a directory is managed by Perforce. This is the only reliable way of doing this, but runs the risk of a delay if the server name cannot be found. If the -server (more specifically, the tt(host)tt(:)tt(port) pair describing the +server (more specifically, the var(host)tt(:)var(port) pair describing the server) cannot be contacted, its name is put into the associative array tt(vcs_info_p4_dead_servers) and is not contacted again during the session until it is removed by hand. If you do not set this style, the tt(p4) @@ -1177,7 +1177,7 @@ If there are two different ways of gathering information, you can select the simpler one by setting this style to true; the default is to use the not-that-simple code, which is potentially a lot slower but might be more accurate in all possible cases. This style is -used by the tt(bzr) and tt(hg) backends. In the case of tt(hg) it will invoke +used by the tt(bzr), tt(hg), and tt(git) backends. In the case of tt(hg) it will invoke the external hexdump program to parse the binary dirstate cache file; this method will not return the local revision number. ) @@ -1236,7 +1236,7 @@ item(tt(get-unapplied))( This boolean style controls whether a backend should attempt to gather a list of unapplied patches (for example with Mercurial Queue patches). -Used by the tt(quilt) and tt(hg) backends. +Used by the tt(quilt), tt(hg), and tt(git) backends. ) enditem() @@ -1318,7 +1318,7 @@ tt(%Q) expando. item(tt(%Q))( Quilt series information. When quilt is used (either in `addon' mode or as a `standalone' backend), -this expando is set to quilt series' tt(patch-format) string. +this expando is set to the quilt series' tt(patch-format) string. The tt(set-patch-format) hook and tt(nopatch-format) style are honoured. See ifzman(tt(Quilt Support))ifnzman(noderef(vcs_info Quilt Support)) below for details. @@ -1328,7 +1328,8 @@ enditem() In tt(branchformat) these replacements are done: startsitem() -sitem(tt(%b))(The branch name.) +sitem(tt(%b))(The branch name. For tt(hg), the branch name can include a +topic name.) sitem(tt(%r))(The current revision number or the tt(hgrevformat) style for tt(hg).) endsitem() @@ -1403,7 +1404,7 @@ a directory that holds quilt's patches needs to be found. That directory is configurable via the `tt(QUILT_PATCHES)' environment variable. If that variable exists its value is used, otherwise the value `tt(patches)' is assumed. The value from tt($QUILT_PATCHES) can be overwritten using the -`tt(quilt-patches)' style. (Note: you can use tt(vcs_info) to keep the value +`tt(quilt-patch-dir)' style. (Note: you can use tt(vcs_info) to keep the value of tt($QUILT_PATCHES) correct all the time via the tt(post-quilt) hook). When the directory in question is found, quilt is assumed to be active. To @@ -1509,7 +1510,7 @@ below for details. ) findex(vcs_info_lastmsg) item(tt(vcs_info_lastmsg))( -Outputs the last tt(${vcs_info_msg_*_}) value. +Outputs the current values of tt(${vcs_info_msg_*_}). Takes into account the value of the tt(use-prompt-escapes) style in tt(':vcs_info:formats:command:-all-'). It also only prints tt(max-exports) values. @@ -1651,16 +1652,28 @@ Called in the tt(git) (with tt(stgit) or during rebase or merge), and tt(hg) is generated; the tt(use-quilt) zstyle must be true for tt(quilt) (the tt(mq) and tt(stgit) backends are active by default). -This hook gets the names of all applied patches which tt(vcs_info) collected -so far in the opposite order, which means that the first argument is the +The arguments to this hook describe applied patches +in the opposite order, which means that the first argument is the top-most patch and so forth. +When the patches' log messages can be extracted, those are embedded +within each argument after a space, so each argument is of the form +`var(patch-name) var(first line of the log message)', where var(patch-name) +contains no whitespace. The tt(mq) backend passes arguments of +the form `var(patch name)', with possible embedded spaces, but without +extracting the patch's log message. + When setting tt(ret) to non-zero, the string in tt(${hook_com[applied-string]}) will be available as tt(%p) in the tt(patch-format) and tt(nopatch-format) styles. This hook is, in concert with tt(set-patch-format), responsible for tt(%)-escaping that value for use in the prompt. (See ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).) + +COMMENT(This paragraph is repeated above/below)\ +The tt(quilt) backend passes to this hook the inputs +tt(${hook_com[quilt-patches-dir]}) and, if it has been +determined, tt(${hook_com[quilt-pc-dir]}). ) item(tt(gen-unapplied-string))( Called in the tt(git) (with tt(stgit) or during rebase), and tt(hg) (with @@ -1668,15 +1681,22 @@ tt(mq)) backend and in tt(quilt) support when the tt(unapplied-string) is generated; the tt(get-unapplied) style must be true. This hook gets the names of all unapplied patches which tt(vcs_info) -collected so far in order, which means that the first argument is +in order, which means that the first argument is the patch next-in-line to be applied and so forth. +The format of each argument is as for tt(gen-applied-string), above. + When setting tt(ret) to non-zero, the string in tt(${hook_com[unapplied-string]}) will be available as tt(%u) in the tt(patch-format) and tt(nopatch-format) styles. This hook is, in concert with tt(set-patch-format), responsible for tt(%)-escaping that value for use in the prompt. (See ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).) + +COMMENT(This paragraph is repeated above/below)\ +The tt(quilt) backend passes to this hook the inputs +tt(${hook_com[quilt-patches-dir]}) and, if it has been +determined, tt(${hook_com[quilt-pc-dir]}). ) item(tt(gen-mqguards-string))( Called in the tt(hg) backend when tt(guards-string) is generated; the @@ -1759,6 +1779,11 @@ This hook is, in concert with the tt(gen-applied-string) or tt(gen-unapplied-string) hooks if they are defined, responsible for tt(%)-escaping the final tt(patch-format) value for use in the prompt. (See ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).) + +COMMENT(This paragraph is repeated above/below)\ +The tt(quilt) backend passes to this hook the inputs +tt(${hook_com[quilt-patches-dir]}) and, if it has been +determined, tt(${hook_com[quilt-pc-dir]}). ) item(tt(set-message))( Called each time before a `tt(vcs_info_msg_)var(N)tt(_)' message is set. @@ -1826,16 +1851,28 @@ If you do use tt(use-simple), please report if it does `the-right-thing[tm]'. Display the revision number in yellow for tt(bzr) and tt(svn): example(zstyle ':vcs_info:(svn|bzr):*' \ + branchformat '%b%%F{yellow}:%r') + +The doubled percent sign is explained in +ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)). + +Alternatively, one can use the raw colour codes directly: + +example(zstyle ':vcs_info:(svn|bzr):*' \ branchformat '%b%{'${fg[yellow]}'%}:%r') -If you want colors, make sure you enclose the color codes in tt(%{)var(...)tt(%}) +Normally when a variable is interpolated into a format string, the variable +needs to be tt(%)-escaped. In this example we skipped that because we assume +the value of tt(${fg[yellow]}) doesn't contain any tt(%) signs. + +Make sure you enclose the color codes in tt(%{)var(...)tt(%}) if you want to use the string provided by tt(vcs_info) in prompts. Here is how to print the VCS information as a command (not in a prompt): -example(alias vcsi='vcs_info command; vcs_info_lastmsg') +example(vcsi+LPAR()+RPAR() { vcs_info interactive; vcs_info_lastmsg }) This way, you can even define different formats for output via -tt(vcs_info_lastmsg) in the 'tt(:vcs_info:*:command:*)' namespace. +tt(vcs_info_lastmsg) in the 'tt(:vcs_info:*:interactive:*)' namespace. Now as promised, some code that uses hooks: say, you'd like to replace the string `svn' by `subversion' in @@ -1919,7 +1956,7 @@ subsect(Installation) You should make sure all the functions from the tt(Functions/Prompts) directory of the source distribution are available; they all begin with -the string `tt(prompt_)' except for the special function`tt(promptinit)'. +the string `tt(prompt_)' except for the special function `tt(promptinit)'. You also need the `tt(colors)' and `tt(add-zsh-hook)' functions from tt(Functions/Misc). All these functions may already be installed on your system; if not, @@ -2019,27 +2056,30 @@ setopts (tt(promptbang), etc.) are turned on, all other prompt-related options are turned off. The tt(prompt_opts) array preserves setopts even beyond the scope of tt(localoptions), should your function need that. ) -item(Modify precmd and preexec)( -Use of tt(add-zsh-hook) is recommended. The tt(precmd) and tt(preexec) -hooks are automatically adjusted if the prompt theme changes or is -disabled. +item(Modify hooks)( +Use of tt(add-zsh-hook) and tt(add-zle-hook-widget) is recommended (see +the bf(Manipulating Hook Functions) section above). +All hooks that follow the naming pattern tt(prompt_)var(theme)tt(_)var(hook) +are automatically removed when the prompt theme changes or is disabled. ) item(Declare cleanup)( If your function makes any other changes that should be undone when the theme is disabled, your setup function may call + example(prompt_cleanup var(command)) + where var(command) should be suitably quoted. If your theme is ever disabled or replaced by another, var(command) is executed with tt(eval). You may declare more than one such cleanup hook. ) item(Define preview)( -Define or autoload a function tt(prompt_var(name)_preview) to display +Define or autoload a function tt(prompt_)var(name)tt(_preview) to display a simulated version of your prompt. A simple default previewer is defined by tt(promptinit) for themes that do not define their own. This preview function is called by `tt(prompt -p)'. ) item(Provide help)( -Define or autoload a function tt(prompt_var(name)_help) to display +Define or autoload a function tt(prompt_)var(name)tt(_help) to display documentation or help text for your theme. This help function is called by `tt(prompt -h)'. ) @@ -2316,8 +2356,8 @@ directly. ) tindex(bracketed-paste-magic) item(tt(bracketed-paste-magic))( -The tt(bracketed-paste) widget (see ifzman(subsection Miscellaneous in -zmanref(zshzle))ifnzman(noderef(Miscellaneous) in noderef(Zle Widgets))) +The tt(bracketed-paste) widget (see ifzman(the subsection `Miscellaneous' in +zmanref(zshzle))ifnzman(noderef(Miscellaneous) in noderef(Standard Widgets))) inserts pasted text literally into the editor buffer rather than interpret it as keystrokes. This disables some common usages where the self-insert widget is replaced in order to accomplish some extra processing. An @@ -2471,6 +2511,12 @@ item(tt(edit-command-line))( Edit the command line using your visual editor, as in tt(ksh). example(bindkey -M vicmd v edit-command-line) + +The editor to be used can also be specified using the tt(editor) style in +the context of the widget. It is specified as an array of command and +arguments: + +example(zstyle :zle:edit-command-line editor gvim -f) ) tindex(expand-absolute-path) item(tt(expand-absolute-path))( @@ -3159,7 +3205,7 @@ investigate the command word found. The default is tt(whence -c). tindex(zcalc-auto-insert) item(tt(zcalc-auto-insert))( This function is useful together with the tt(zcalc) function described in -ifzman(the section Mathematical Functions)\ +ifzman(the section `Mathematical Functions')\ ifnzman(noderef(Mathematical Functions)). It should be bound to a key representing a binary operator such as `tt(PLUS())', `tt(-)', `tt(*)' or `tt(/)'. When running in zcalc, @@ -3559,7 +3605,8 @@ Calling tt(zsh-mime-setup) with the option tt(-v) causes verbose output to be shown during the setup operation. The system respects the tt(mailcap) flags tt(needsterminal) and -tt(copiousoutput), see manref(mailcap)(4). +tt(copiousoutput); see manref(mailcap)(4) or manref(mailcap)(5) +(the man page's name varies across platforms). The functions use the following styles, which are defined with the tt(zstyle) builtin command (\ @@ -3632,7 +3679,7 @@ types even if they are executable. As this example shows, the complete file name is matched against the pattern, regardless of how the file was passed to the handler. The file is resolved to a full path using the tt(:P) modifier described in -ifzman(the subsection Modifiers in zmanref(zshexpn))\ +ifzman(the subsection `Modifiers' in zmanref(zshexpn))\ ifnzman(noderef(Modifiers)); this means that symbolic links are resolved where possible, so that links into other file systems behave in the correct fashion. @@ -4264,6 +4311,12 @@ Same as tt(zed -f). This function does not appear in the zsh distribution, but can be created by linking tt(zed) to the name tt(fned) in some directory in your tt(fpath). ) +findex(histed) +item(tt(histed) [ [ var(name) ] var(size) ])( +Same as tt(zed -h). This function does not appear in the zsh +distribution, but can be created by linking tt(zed) to the name tt(histed) +in some directory in your tt(fpath). +) findex(is-at-least) item(tt(is-at-least) var(needed) [ var(present) ])( Perform a greater-than-or-equal-to comparison of two strings having the @@ -4297,7 +4350,7 @@ See also the tt(pager), tt(prompt) and tt(rprompt) styles below. findex(regexp-replace) item(tt(regexp-replace) var(var) var(regexp) var(replace))( Use regular expressions to perform a global search and replace operation -on a variable. POSIX extended regular expressions are used, +on a variable. POSIX extended regular expressions (ERE) are used, unless the option tt(RE_MATCH_PCRE) has been set, in which case Perl-compatible regular expressions are used (this requires the shell to be linked against the tt(pcre) @@ -4315,6 +4368,9 @@ and arithmetic expressions which will be replaced: in particular, a reference to tt($MATCH) will be replaced by the text matched by the pattern. The return status is 0 if at least one match was performed, else 1. + +Note that if using POSIX EREs, the tt(^) or word boundary operators +(where available) may not work properly. ) findex(run-help) item(tt(run-help) var(cmd))( @@ -4355,6 +4411,7 @@ directory. These must be autoloaded, or placed as executable scripts in your search path, in order to be found and used by tt(run-help). startitem() +findex(run-help-btrfs) findex(run-help-git) findex(run-help-ip) findex(run-help-openssl) @@ -4362,14 +4419,16 @@ findex(run-help-p4) findex(run-help-sudo) findex(run-help-svk) findex(run-help-svn) -xitem(run-help-git) -xitem(run-help-ip) -xitem(run-help-openssl) -xitem(run-help-p4) -xitem(run-help-sudo) -xitem(run-help-svk) +xitem(tt(run-help-btrfs)) +xitem(tt(run-help-git)) +xitem(tt(run-help-ip)) +xitem(tt(run-help-openssl)) +xitem(tt(run-help-p4)) +xitem(tt(run-help-sudo)) +xitem(tt(run-help-svk)) item(tt(run-help-svn))( Assistant functions for the +tt(btrfs), tt(git), tt(ip), tt(openssl), @@ -4464,12 +4523,13 @@ counts the number of arguments passed to each execution of var(command), em(including) any var(arg) list. Also, any time tt(-i) or tt(-I) is used, each var(input) is processed separately as if by `tt(-L) tt(1)'. -For details of the other tt(zargs) options, see zmanref(xargs) (but note +For details of the other tt(zargs) options, see the manref(xargs)(1) man page (but note the difference in function between tt(zargs) and tt(xargs)) or run tt(zargs) with the tt(-)tt(-help) option. ) findex(zed) xitem(tt(zed) [ tt(-f) [ tt(-x) var(num) ] ] var(name)) +xitem(tt(zed) [ tt(-h) [ var(name) ] var(size) ]) item(tt(zed -b))( This function uses the ZLE editor to edit a file or function. @@ -4484,7 +4544,14 @@ the given number of spaces; `tt(-x 2)' is consistent with the layout of functions distributed with the shell. Without tt(-f), var(name) is the path name of the file to edit, which need -not exist; it is created on write, if necessary. +not exist; it is created on write, if necessary. With tt(-h), the file is +presumed to contain history events. + +When no file name is provided for tt(-h) the current shell history is edited +in place. The history is renumbered when zed exits successfully. + +When editing history, multi-line events must have a trailing backslash on +every line before the last. While editing, the function sets the main keymap to tt(zed) and the vi command keymap to tt(zed-vicmd). These will be copied from the existing @@ -4500,16 +4567,20 @@ suitable for putting into a startup file. Note that, if rerun, this will overwrite the existing tt(zed) and tt(zed-vicmd) keymaps. Completion is available, and styles may be set with the context prefix -`tt(:completion:zed)'. - -A zle widget tt(zed-set-file-name) is available. This can be called by -name from within zed using `tt(\ex zed-set-file-name)' (note, however, that -because of zed's rebindings you will have to type tt(^j) at the end instead -of the return key), or can be bound to a key in either of the tt(zed) or -tt(zed-vicmd) keymaps after `tt(zed -b)' has been run. When the widget is -called, it prompts for a new name for the file being edited. When zed -exits the file will be written under that name and the original file will -be left alone. The widget has no effect with `tt(zed -f)'. +`tt(:completion:zed:)'. + +findex(zed-set-file-name) +A zle widget tt(zed-set-file-name) is available. This can be called +by name from within zed using `tt(\ex zed-set-file-name)' or can be +bound to a key in either of the tt(zed) or tt(zed-vicmd) keymaps after +`tt(zed -b)' has been run. When the widget is called, it prompts for +a new name for the file being edited. When zed exits the file will be +written under that name and the original file will be left alone. The +widget has no effect when invoked from `tt(zed -f)'. The completion +context is changed to `tt(:completion:zed-set-file-name:)'. When editing +the current history with `tt(zed -h)', the history is first updated and +then the file is written, but the global setting of tt(HISTFILE) is not +altered. While tt(zed-set-file-name) is running, zed uses the keymap tt(zed-normal-keymap), which is linked from the main keymap in effect @@ -4551,7 +4622,7 @@ the same result, the destination was an existing regular file and tt(-f) was not given) causes the entire function to abort without doing anything. -In addition to pattern replacement, the variable tt($f) can be referrred +In addition to pattern replacement, the variable tt($f) can be referred to in the second (replacement) argument. This makes it possible to use variable substitution to alter the argument; see examples below. diff --git a/Doc/Zsh/exec.yo b/Doc/Zsh/exec.yo index 5f79967de..2b3d29500 100644 --- a/Doc/Zsh/exec.yo +++ b/Doc/Zsh/exec.yo @@ -14,9 +14,20 @@ a shell builtin by that name, the builtin is invoked. vindex(path, use of) Otherwise, the shell searches each element of tt($path) for a -directory containing an executable file by that name. If the -search is unsuccessful, the shell prints an error message and returns -a nonzero exit status. +directory containing an executable file by that name. + +If execution fails: an error message is printed, and one of the +following values is returned. + +startsitem() +sitem(127)(The search was unsuccessful. The error message is +`tt(command not found:) var(cmd)'.) +sitem(126)(The executable file has insufficient permissions, is a +directory or special file, or is not a script and is in a format +unrecognized by the operating system. The exact conditions and error +message are operating system-dependent; see +manref(execve)(2).) +endsitem() If execution fails because the file is not in executable format, and the file is not a directory, it is assumed to be a shell @@ -29,10 +40,6 @@ not handle this executable format in the kernel. If no external command is found but a function tt(command_not_found_handler) exists the shell executes this function with all command line arguments. The return status of the function becomes the -status of the command. If the function wishes to mimic the -behaviour of the shell when the command is not found, it should -print the message `tt(command not found:) var(cmd)' to standard error -and return status 127. Note that the handler is executed in a +status of the command. Note that the handler is executed in a subshell forked to execute an external command, hence changes to directories, shell parameters, etc. have no effect on the main shell. - diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo index c129b4228..bbacc6ae4 100644 --- a/Doc/Zsh/expn.yo +++ b/Doc/Zsh/expn.yo @@ -84,7 +84,7 @@ vindex(histchars, use of) A history expansion begins with the first character of the tt(histchars) parameter, which is `tt(!)' by default, and may occur anywhere on the command line, including inside double quotes (but not inside single quotes -tt('...') or C-style quotes tt($'...') nor when escaped with a backslash). +tt('...') or C-style quotes tt($'...') nor when escaped with a backslash). The first character is followed by an optional event designator (ifzman(see )noderef(Event Designators)) and then an optional word @@ -287,8 +287,10 @@ expansion. ) item(tt(P))( Turn a file name into an absolute path, like tt(realpath+LPAR()3+RPAR()). -The resulting path will be absolute, have neither `tt(.)' nor `tt(..)' components, -and refer to the same directory entry as the input filename. +The resulting path will be absolute, +will refer to the same directory entry as the input filename, +and none of its components will be symbolic links or equal to +`tt(.)' or `tt(..)'. Unlike tt(realpath+LPAR()3+RPAR()), non-existent trailing components are permitted and preserved. @@ -494,7 +496,7 @@ which treats var(arg) as a file name and replaces it with the file's contents. The tt(=) form is useful as both the tt(/dev/fd) and the named pipe -implementation of tt(<LPAR())var(...)tt(RPAR()) have drawbacks. In +implementation of tt(<LPAR())var(...)tt(RPAR()) have drawbacks. In the former case, some programmes may automatically close the file descriptor in question before examining the file on the command line, particularly if this is necessary for security reasons such as when the @@ -509,7 +511,7 @@ information using a pipe, so that programmes that expect to lseek Also note that the previous example can be more compactly and efficiently written (provided the tt(MULTIOS) option is set) as: -example(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR()) ifzman(\ +example(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR()) ifzman(\ )tt(> >LPAR())var(process1)tt(RPAR() > >LPAR())var(process2)tt(RPAR())) The shell uses pipes instead of FIFOs to implement the latter @@ -870,7 +872,8 @@ of the string tt($-) and the array tt($*) respectively. If tt(POSIX_IDENTIFIERS) is set, then braces are required for the tt(#) to be treated in this fashion. ) -item(tt(${^)var(spec)tt(}))( +xitem(tt(${^)var(spec)tt(})) +item(tt(${^^)var(spec)tt(}))( pindex(RC_EXPAND_PARAM, toggle) cindex(array expansion style, rc) cindex(rc, array expansion style) @@ -893,7 +896,8 @@ happening later. If word splitting is also in effect the tt($var[)var(N)tt(]) may themselves be split into different list elements. ) -item(tt(${=)var(spec)tt(}))( +xitem(tt(${=)var(spec)tt(})) +item(tt(${==)var(spec)tt(}))( pindex(SH_WORD_SPLIT, toggle) cindex(field splitting, sh style, parameter) cindex(sh, field splitting style, parameter) @@ -909,7 +913,8 @@ Note that splitting is applied to var(word) in the assignment forms of var(spec) em(before) the assignment to var(name) is performed. This affects the result of array assignments with the tt(A) flag. ) -item(tt(${~)var(spec)tt(}))( +xitem(tt(${~)var(spec)tt(})) +item(tt(${~~)var(spec)tt(}))( pindex(GLOB_SUBST, toggle) Turn on the tt(GLOB_SUBST) option for the evaluation of var(spec); if the `tt(~)' is doubled, turn it off. When this option is @@ -963,16 +968,17 @@ following flags are supported: startitem() item(tt(#))( -Evaluate the resulting words as numeric expressions and output the -characters corresponding to the resulting integer. Note that this form is -entirely distinct from use of the tt(#) without parentheses. +Evaluate the resulting words as numeric expressions and interpret +these as character codes. Output the corresponding characters. Note +that this form is entirely distinct from use of the tt(#) without +parentheses. If the tt(MULTIBYTE) option is set and the number is greater than 127 (i.e. not an ASCII character) it is treated as a Unicode character. ) item(tt(%))( Expand all tt(%) escapes in the resulting words in the same way as in -prompts (see +prompts (see ifzman(EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\ ifnzman(noderef(Prompt Expansion))). If this flag is given twice, full prompt expansion is done on the resulting words, depending on the @@ -1092,22 +1098,31 @@ Convert all letters in the result to lower case. item(tt(n))( Sort decimal integers numerically; if the first differing characters of two test strings are not digits, sorting -is lexical. Integers with more initial zeroes -are sorted before those with fewer or none. Hence the array `tt(foo1 foo02 +is lexical. `tt(+)' and `tt(-)' are not treated specially; they are treated as +any other non-digit. Integers with more initial zeroes +are sorted before those with fewer or none. Hence the array `tt(foo+24 foo1 foo02 foo2 foo3 foo20 foo23)' is sorted into the order shown. May be combined with `tt(i)' or `tt(O)'. ) +item(tt(-))( +As tt(n), but a leading minus sign indicates a negative decimal +integer. A leading minus sign not followed by an integer does not trigger +numeric sorting. +Note that `tt(+)' signs are not handled specially (this may change in the +future). +) item(tt(o))( Sort the resulting words in ascending order; if this appears on its own the sorting is lexical and case-sensitive (unless the locale renders it case-insensitive). Sorting in ascending order is the default for other forms of sorting, so this is ignored if combined -with `tt(a)', `tt(i)' or `tt(n)'. +with `tt(a)', `tt(i)', `tt(n)' or `tt(-)'. ) item(tt(O))( Sort the resulting words in descending order; `tt(O)' without `tt(a)', -`tt(i)' or `tt(n)' sorts in reverse lexical order. May be combined -with `tt(a)', `tt(i)' or `tt(n)' to reverse the order of sorting. +`tt(i)', `tt(n)' or `tt(-)' sorts in reverse lexical order. May be +combined with `tt(a)', `tt(i)', `tt(n)' or `tt(-)' to reverse the +order of sorting. ) item(tt(P))( This forces the value of the parameter var(name) to be interpreted as a @@ -1191,6 +1206,11 @@ for readonly parameters item(tt(tag))( for tagged parameters ) +item(tt(tied))( +for parameters tied to another parameter in the manner of tt(PATH) +(colon-separated list) and tt(path) (array), whether these are +special parameters or user-defined with `tt(typeset -T)' +) item(tt(export))( for exported parameters ) @@ -1377,16 +1397,29 @@ i.e. tt("${(@s.:.)line}"). item(tt(Z:)var(opts)tt(:))( As tt(z) but takes a combination of option letters between a following pair of delimiter characters. With no options the effect is identical -to tt(z). tt(LPAR()Z+PLUS()c+PLUS()RPAR()) +to tt(z). The following options are available: + +startitem() +item(tt(LPAR()Z+PLUS()c+PLUS()RPAR()))( causes comments to be parsed as a string and retained; any field in the resulting array beginning with an unquoted comment character is a -comment. tt(LPAR()Z+PLUS()C+PLUS()RPAR()) causes comments to be parsed +comment. +) +item(tt(LPAR()Z+PLUS()C+PLUS()RPAR()))( +causes comments to be parsed and removed. The rule for comments is standard: anything between a word starting with the third character of tt($HISTCHARS), default tt(#), up to -the next newline is a comment. tt(LPAR()Z+PLUS()n+PLUS()RPAR()) causes +the next newline is a comment. +) +item(tt(LPAR()Z+PLUS()n+PLUS()RPAR()))( +causes unquoted newlines to be treated as ordinary whitespace, else they are treated as if they are shell code delimiters and converted to -semicolons. Options are combined within the same set of delimiters, +semicolons. +) +enditem() + +Options are combined within the same set of delimiters, e.g. tt(LPAR()Z+PLUS()Cn+PLUS()RPAR()). ) item(tt(_:)var(flags)tt(:))( @@ -1398,7 +1431,7 @@ error, and the flag itself has no effect. enditem() The following flags are meaningful with the tt(${)...tt(#)...tt(}) or -tt(${)...tt(%)...tt(}) forms. The tt(S) and tt(I) flags may also be +tt(${)...tt(%)...tt(}) forms. The tt(S), tt(I), and tt(*) flags may also be used with the tt(${)...tt(/)...tt(}) forms. startitem() @@ -1464,6 +1497,10 @@ will remove the same matches as for `tt(#)', but in reverse order, and the form using `tt(%%)' will remove the same matches as for `tt(##)' in reverse order. ) +item(tt(*))( +Enable tt(EXTENDED_GLOB) for substitution via tt(${)...tt(/)...tt(}) or +tt(${)...tt(//)...tt(}). +) item(tt(B))( Include the index of the beginning of the match in the result. ) @@ -1483,7 +1520,9 @@ Include the unmatched portion in the result (the em(R)est). enditem() subsect(Rules) - +cindex(parameter expansion rules) +cindex(rules, parameter expansion) +cindex(substitution, parameter, rules) Here is a summary of the rules for substitution; this assumes that braces are present around the substitution, i.e. tt(${)var(...)tt(}). Some particular examples are given below. Note that the Zsh Development Group accepts @@ -1681,6 +1720,7 @@ expression) and replaced with the corresponding value, with internal flags enditem() subsect(Examples) +cindex(parameter expansion, examples) The flag tt(f) is useful to split a double-quoted substitution line by line. For example, tt(${(f)"$LPAR()<)var(file)tt(RPAR()"}) substitutes the contents of var(file) divided so that each line is @@ -1698,7 +1738,7 @@ This produces the result tt(b). First, the inner substitution tt("${foo}"), which has no array (tt(@)) flag, produces a single word result tt("bar baz"). The outer substitution tt("${(@)...[1]}") detects that this is a scalar, so that (despite the `tt((@))' flag) the subscript -picks the first character. +picks the first character. ) item(tt("${${(@)foo}[1]}"))( This produces the result `tt(bar)'. In this case, the inner substitution @@ -1732,7 +1772,7 @@ sect(Command Substitution) cindex(command substitution) cindex(substitution, command) A command enclosed in parentheses preceded by a dollar sign, like -`tt($LPAR())...tt(RPAR())', or quoted with grave +`tt($LPAR())...tt(RPAR())', or quoted with grave accents, like `tt(`)...tt(`)', is replaced with its standard output, with any trailing newlines deleted. If the substitution is not enclosed in double quotes, the @@ -1823,7 +1863,7 @@ has similar effects. To combine brace expansion with array expansion, see the tt(${^)var(spec)tt(}) form described -ifzman(in the section Parameter Expansion)\ +ifzman(in the section `Parameter Expansion')\ ifnzman(in noderef(Parameter Expansion)) above. @@ -1858,11 +1898,18 @@ The tt(PUSHD_MINUS) option exchanges the effects of `tt(~PLUS())' and `tt(~-)' where they are followed by a number. +startmenu() +menu(Dynamic named directories) +menu(Static named directories) +menu(`=' expansion) +menu(Notes) +endmenu() + +texinode(Dynamic named directories)(Static named directories)()(Filename Expansion) subsect(Dynamic named directories) cindex(directories, named, dynamic) cindex(named directories, dynamic) cindex(dynamic named directories) - If the function tt(zsh_directory_name) exists, or the shell variable tt(zsh_directory_name_functions) exists and contains an array of function names, then the functions are used to implement dynamic @@ -1952,6 +1999,7 @@ example(zsh_directory_name+LPAR()RPAR() { return 0 }) +texinode(Static named directories)(`=' expansion)(Dynamic named directories)(Filename Expansion) subsect(Static named directories) cindex(directories, named, static) cindex(named directories, static) @@ -1978,6 +2026,7 @@ i.e. either the directory name or the full path; the name is used if they are the same length. The parameters tt($PWD) and tt($OLDPWD) are never abbreviated in this fashion. +texinode(`=' expansion)(Notes)(Static named directories)(Filename Expansion) subsect(`=' expansion) If a word begins with an unquoted `tt(=)' @@ -1987,8 +2036,9 @@ name of a command. If a command exists by that name, the word is replaced by the full pathname of the command. +texinode(Notes)()(`=' expansion)(Filename Expansion) subsect(Notes) - +cindex(filename expansion, notes) Filename expansion is performed on the right hand side of a parameter assignment, including those appearing after commands of the tt(typeset) family. In this case, the right hand side will be treated @@ -2033,6 +2083,7 @@ No filename generation pattern matches the files `tt(.)' or `tt(..)'. In other instances of pattern matching, the `tt(/)' and `tt(.)' are not treated specially. subsect(Glob Operators) +cindex(glob operators) startitem() item(tt(*))( Matches any string, including the null string. @@ -2103,7 +2154,8 @@ is not sensitive to the locale: startitem() item(tt([:IDENT:]))( The character is allowed to form part of a shell identifier, such -as a parameter name +as a parameter name; this test respects the tt(POSIX_IDENTIFIERS) +option ) item(tt([:IFS:]))( The character is used as an input field separator, i.e. is contained in the @@ -2263,6 +2315,8 @@ within `tt([[)...tt(]])'), a `tt(/)' is not special; and `tt(/)' is also not special after a `tt(~)' appearing outside parentheses in a filename pattern. subsect(Globbing Flags) +cindex(globbing flags) +cindex(glob flags) There are various flags which affect any text to their right up to the end of the enclosing group or to the end of the pattern; they require the tt(EXTENDED_GLOB) option. All take the form @@ -2427,7 +2481,7 @@ qualifiers are also not applied in ordinary pattern matching. ) item(tt(u))( Respect the current locale in determining the presence of multibyte -characters in a pattern, provided the shell was compiled with +characters in a pattern, provided the shell was compiled with tt(MULTIBYTE_SUPPORT). This overrides the tt(MULTIBYTE) option; the default behaviour is taken from the option. Compare tt(U). (Mnemonic: typically multibyte characters are from Unicode in the UTF-8 @@ -2457,6 +2511,8 @@ searched for all files which match, so that a pattern of the form tt(LPAR()#i)tt(RPAR()/foo/bar/...) is potentially slow. subsect(Approximate Matching) +cindex(approximate matching) +cindex(matching, approximate) When matching approximately, the shell keeps a count of the errors found, which cannot exceed the number specified in the tt(LPAR()#a)var(num)tt(RPAR()) flags. Four types of error are recognised: @@ -2522,6 +2578,8 @@ approximate match. It is best to place the tt((#a1)) after any path segments which are known to be correct. subsect(Recursive Globbing) +cindex(recursive globbing) +cindex(globbing, recursive) A pathname component of the form `tt(LPAR())var(foo)tt(/RPAR()#)' matches a path consisting of zero or more directories matching the pattern var(foo). @@ -2674,18 +2732,18 @@ expected, if combined with a `tt(=)', the value given must match the file-modes exactly, with a `tt(PLUS())', at least the bits in the given number must be set in the file-modes, and with a `tt(-)', the bits in the number must not be set. Giving a `tt(?)' instead of a -octal digit anywhere in the number ensures that the corresponding bits +octal digit anywhere in the number ensures that the corresponding bits in the file-modes are not checked, this is only useful in combination with `tt(=)'. If the qualifier `tt(f)' is followed by any other character anything -up to the next matching character (`tt([)', `tt({)', and `tt(<)' match +up to the next matching character (`tt([)', `tt({)', and `tt(<)' match `tt(])', `tt(})', and `tt(>)' respectively, any other character matches itself) is taken as a list of comma-separated var(sub-spec)s. Each var(sub-spec) may be either an octal number as described above or a list of any of the characters `tt(u)', `tt(g)', `tt(o)', and `tt(a)', followed by a `tt(=)', a `tt(PLUS())', or a -`tt(-)', followed by a list of any of the characters `tt(r)', `tt(w)', +`tt(-)', followed by a list of any of the characters `tt(r)', `tt(w)', `tt(x)', `tt(s)', and `tt(t)', or an octal digit. The first list of characters specify which access rights are to be checked. If a `tt(u)' is given, those for the owner of the file are used, if a `tt(g)' is @@ -2694,7 +2752,7 @@ of other users, and the `tt(a)' says to test all three groups. The `tt(=)', `tt(PLUS())', and `tt(-)' again says how the modes are to be checked and have the same meaning as described for the first form above. The second list of characters finally says which access rights -are to be expected: `tt(r)' for read access, `tt(w)' for write access, +are to be expected: `tt(r)' for read access, `tt(w)' for write access, `tt(x)' for the right to execute the file (or to search a directory), `tt(s)' for the setuid and setgid bits, and `tt(t)' for the sticky bit. @@ -2703,7 +2761,7 @@ Thus, `tt(*(f70?))' gives the files for which the owner has read, write, and execute permission, and for which other group members have no rights, independent of the permissions for other users. The pattern `tt(*(f-100))' gives all files for which the owner does not have -execute permission, and `tt(*(f:gu+w,o-rx:))' gives the files for which +execute permission, and `tt(*(f:gu+w,o-rx:))' gives the files for which the owner and the other members of the group have at least write permission, and for which other users don't have read or execute permission. @@ -2824,7 +2882,9 @@ negates all qualifiers following it ) item(tt(-))( toggles between making the qualifiers work on symbolic links (the -default) and the files they point to +default) and the files they point to, if any; any symbolic link for +whose target the `tt(stat)' system call fails (whatever the cause of the +failure) is treated as a file in its own right ) item(tt(M))( sets the tt(MARK_DIRS) option for the current pattern @@ -2854,18 +2914,26 @@ matches in directory traversal order will be considered. Implies tt(oN) when no tt(o)var(c) qualifier is used. ) item(tt(o)var(c))( -specifies how the names of the files should be sorted. If var(c) is -tt(n) they are sorted by name; if it is tt(L) they -are sorted depending on the size (length) of the files; if tt(l) -they are sorted by the number of links; if tt(a), tt(m), or tt(c) -they are sorted by the time of the last access, modification, or -inode change respectively; if tt(d), files in subdirectories appear before +specifies how the names of the files should be sorted. The following values +of var(c) sort in the following ways: + +startsitem() +sitem(tt(n))(By name.) +sitem(tt(L))(By the size (length) of the files.) +sitem(tt(l))(By number of links.) +sitem(tt(a))(By time of last access, youngest first.) +sitem(tt(m))(By time of last modification, youngest first.) +sitem(tt(c))(By time of last inode change, youngest first.) +sitem(tt(d))(By directories: files in subdirectories appear before those in the current directory at each level of the search DASH()- this is best combined with other criteria, for example `tt(odon)' to sort on names for -files within the same directory; if tt(N), no sorting is performed. -Note that tt(a), tt(m), and tt(c) compare -the age against the current time, hence the first name in the list is the -youngest file. Also note that the modifiers tt(^) and tt(-) are used, +files within the same directory.) +sitem(tt(N))(No sorting is performed.) +xitem(tt(e)var(string)) +sitem(tt(+)var(cmd))(Sort by shell code (see below).) +endsitem() + +Note that the modifiers tt(^) and tt(-) are used, so `tt(*(^-oL))' gives a list of all files sorted by file size in descending order, following any symbolic links. Unless tt(oN) is used, multiple order specifiers may occur to resolve ties. @@ -2885,8 +2953,8 @@ repeated, but note that the maximum number of sort operators of any kind that may appear in any glob expression is 12. ) item(tt(O)var(c))( -like `tt(o)', but sorts in descending order; i.e. `tt(*(^oc))' is the -same as `tt(*(Oc))' and `tt(*(^Oc))' is the same as `tt(*(oc))'; `tt(Od)' +like `tt(o)', but sorts in descending order; i.e. `tt(*+LPAR()^o)var(c)tt(+RPAR())' is the +same as `tt(*+LPAR()O)var(c)tt(+RPAR())' and `tt(*+LPAR()^O)var(c)tt(+RPAR())' is the same as `tt(*+LPAR()o)var(c)tt(+RPAR())'; `tt(Od)' puts files in the current directory before those in subdirectories at each level of the search. ) @@ -2894,7 +2962,7 @@ item(tt([)var(beg)[tt(,)var(end)]tt(]))( specifies which of the matched filenames should be included in the returned list. The syntax is the same as for array subscripts. var(beg) and the optional var(end) may be mathematical -expressions. As in parameter subscripting they may be negative to make +expressions. As in parameter subscripting they may be negative to make them count from the last match backward. E.g.: `tt(*(-OL[1,3]))' gives a list of the names of the three largest files. ) diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo index d500a78ae..12db3f56a 100644 --- a/Doc/Zsh/func.yo +++ b/Doc/Zsh/func.yo @@ -206,13 +206,14 @@ findex(hook functions) For the functions below, it is possible to define an array that has the same name as the function 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 +in the same context and with the same arguments and same initial value of tt($?) +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 +elsewhere as a em(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 (though it may run at the next opportunity). @@ -275,7 +276,7 @@ the history file. In case of a conflict, the first non-zero status value is taken. A hook function may call `tt(fc -p) var(...)' to switch the history -context so that the history is saved in a different file from the +context so that the history is saved in a different file from that in the global tt(HISTFILE) parameter. This is handled specially: the history context is automatically restored after the processing of the history line is finished. diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo index e028c8512..f8f4ada86 100644 --- a/Doc/Zsh/grammar.yo +++ b/Doc/Zsh/grammar.yo @@ -288,7 +288,9 @@ for each selection until a break or end-of-file is encountered. cindex(subshell) item(tt(LPAR()) var(list) tt(RPAR()))( Execute var(list) in a subshell. Traps set by the tt(trap) builtin -are reset to their default values while executing var(list). +are reset to their default values while executing var(list); an +exception is that ignored signals will continue to be ignored +if the option tt(POSIXTRAPS) is set. ) item(tt({) var(list) tt(}))( Execute var(list). @@ -357,7 +359,7 @@ deliberately left unspecified, because historically there was a mismatch between the documented and implemented behaviours. Cf. 20076, 21734/21735, 45075.) ) findex(function) -xitem(tt(function) var(word) ... [ tt(()) ] [ var(term) ] tt({) var(list) tt(})) +xitem(tt(function) [ tt(-T) ] var(word) ... [ tt(()) ] [ var(term) ] tt({) var(list) tt(})) xitem(var(word) ... tt(()) [ var(term) ] tt({) var(list) tt(})) item(var(word) ... tt(()) [ var(term) ] var(command))( where var(term) is one or more newline or tt(;). @@ -367,6 +369,17 @@ are usually only useful for setting traps. The body of the function is the var(list) between the tt({) and tt(}). See noderef(Functions). +The options of tt(function) have the following meanings: + +startitem() +item(-T)( +Enable tracing for this function, as though with tt(functions -T). See the +documentation of the tt(-f) option to the tt(typeset) builtin, in +ifzman(zmanref(zshbuiltins))\ +ifnzman(noderef(Shell Builtin Commands)). +) +enditem() + If the option tt(SH_GLOB) is set for compatibility with other shells, then whitespace may appear between the left and right parentheses when there is a single var(word); otherwise, the parentheses will be treated as @@ -417,6 +430,8 @@ else the end of the test will not be recognized. For the tt(for), tt(repeat), tt(case) and tt(select) commands no such special form for the arguments is necessary, but the other condition (the special form of var(sublist) or use of the tt(SHORT_LOOPS) option) still applies. +The tt(SHORT_REPEAT) option is available to enable the short version only +for the tt(repeat) command. startitem() item(tt(if) var(list) tt({) var(list) tt(}) [ tt(elif) var(list) tt({) var(list) tt(}) ] ... [ tt(else {) var(list) tt(}) ])( @@ -558,6 +573,11 @@ position (if it could be the first word of a simple command), or if the alias is global. If the replacement text ends with a space, the next word in the shell input is always eligible for purposes of alias expansion. + +It is an error for the function name, var(word), in the sh-compatible function +definition syntax `var(word) tt(+LPAR()+RPAR()) ...' to be a word that resulted +from alias expansion, unless the tt(ALIAS_FUNC_DEF) option is set. + findex(alias, use of) cindex(aliases, global) An alias is defined using the tt(alias) builtin; global aliases @@ -584,6 +604,15 @@ word, e.g. tt(\foo). Any form of quoting works, although there is nothing to prevent an alias being defined for the quoted form such as tt(\foo) as well. +In particular, note that quoting must be used when using tt(unalias) to remove +global aliases: + +example(% alias -g foo=bar +% unalias foo +unalias: no such hash table element: bar +% unalias \foo +% ) + When tt(POSIX_ALIASES) is set, only plain unquoted strings are eligible for aliasing. The tt(alias) builtin does not reject ineligible aliases, but they are not expanded. @@ -634,26 +663,6 @@ a problem in shell scripts, functions, and code executed with `tt(source)' or `tt(.)'. Consequently, use of functions rather than aliases is recommended in non-interactive code. -Note also the unhelpful interaction of aliases and function definitions: - -example(alias func='noglob func' -func+LPAR()RPAR() { - echo Do something with $* -}) - -Because aliases are expanded in function definitions, this causes the -following command to be executed: - -example(noglob func+LPAR()RPAR() { - echo Do something with $* -}) - -which defines tt(noglob) as well as tt(func) as functions with the -body given. To avoid this, either quote the name tt(func) or use the -alternative function definition form `tt(function func)'. Ensuring the -alias is defined after the function works but is problematic if the -code fragment might be re-executed. - texinode(Quoting)()(Aliasing)(Shell Grammar) sect(Quoting) cindex(quoting) diff --git a/Doc/Zsh/intro.yo b/Doc/Zsh/intro.yo index 75d25ce27..474e537c2 100644 --- a/Doc/Zsh/intro.yo +++ b/Doc/Zsh/intro.yo @@ -45,7 +45,7 @@ zsh most closely resembles bf(ksh) but includes many enhancements. It does not provide compatibility with POSIX or other shells in its default operating mode: see ifnzman(the section noderef(Compatibility))\ -ifzman(the section Compatibility below). +ifzman(the section `Compatibility' below). Zsh has command line editing, builtin spelling correction, programmable command completion, shell functions (with autoloading), a history diff --git a/Doc/Zsh/jobs.yo b/Doc/Zsh/jobs.yo index 70559f2d8..3ab0698ae 100644 --- a/Doc/Zsh/jobs.yo +++ b/Doc/Zsh/jobs.yo @@ -111,7 +111,7 @@ cindex(jobs, disowning) cindex(disowning jobs) findex(disown, use of) To avoid having the shell terminate the running jobs, either -use the bf(nohup) command (see manref(nohup)(1)) +use the manref(nohup)(1) command or the tt(disown) builtin. sect(Signals) The tt(INT) and tt(QUIT) signals for an invoked @@ -135,4 +135,4 @@ ifzman(the section PROCESS SUBSTITUTION in the zmanref(zshexpn) manual page)\ ifnzman(noderef(Process Substitution)), and the handler processes for multios, see ifzman(the section MULTIOS in the zmanref(zshmisc) manual page)\ -ifnzman(the section Multios in noderef(Redirection)). +ifnzman(the section em(Multios) in noderef(Redirection)). diff --git a/Doc/Zsh/manmodmenu.yo b/Doc/Zsh/manmodmenu.yo index 53c0e01c9..e91a5ce3d 100644 --- a/Doc/Zsh/manmodmenu.yo +++ b/Doc/Zsh/manmodmenu.yo @@ -27,6 +27,7 @@ menu(The zsh/system Module) menu(The zsh/net/tcp Module) menu(The zsh/termcap Module) menu(The zsh/terminfo Module) +menu(The zsh/watch Module) menu(The zsh/zftp Module) menu(The zsh/zle Module) menu(The zsh/zleparameter Module) diff --git a/Doc/Zsh/manual.yo b/Doc/Zsh/manual.yo index 119849e4c..dc4d6ed07 100644 --- a/Doc/Zsh/manual.yo +++ b/Doc/Zsh/manual.yo @@ -108,6 +108,8 @@ Zsh Line Editor menu(Keymaps) menu(Zle Builtins) menu(Zle Widgets) +menu(User-Defined Widgets) +menu(Standard Widgets) menu(Character Highlighting) Completion Widgets @@ -196,7 +198,7 @@ produce a nicely formatted printed manual. item(The HTML manual)( An HTML version of this manual is available at the Zsh web site via: -uref(http://zsh.sourceforge.net/Doc/). +uref(https://zsh.sourceforge.io/Doc/). (The HTML version is produced with bf(texi2html), which may be obtained from uref(http://www.nongnu.org/texi2html/). The command is diff --git a/Doc/Zsh/metafaq.yo b/Doc/Zsh/metafaq.yo index c123a7cea..c780808e3 100644 --- a/Doc/Zsh/metafaq.yo +++ b/Doc/Zsh/metafaq.yo @@ -10,12 +10,12 @@ endmenu() texinode(Author)(Availability)()(Introduction) sect(Author) cindex(author) -Zsh was originally written by Paul Falstad tt(<pf@zsh.org>). -Zsh is now maintained by the members of the zsh-workers mailing -list tt(<zsh-workers@zsh.org>). The development is currently -coordinated by Peter Stephenson tt(<pws@zsh.org>). The coordinator -can be contacted at tt(<coordinator@zsh.org>), but matters relating to -the code should generally go to the mailing list. +Zsh was originally written by Paul Falstad. Zsh is now maintained by +the members of the zsh-workers mailing list tt(<zsh-workers@zsh.org>). +The development is currently coordinated by Peter Stephenson +tt(<pws@zsh.org>). The coordinator can be contacted at +tt(<coordinator@zsh.org>), but matters relating to the code should +generally go to the mailing list. texinode(Availability)(Mailing Lists)(Author)(Introduction) sect(Availability) Zsh is available from the following HTTP and anonymous FTP site. @@ -25,17 +25,16 @@ cindex(acquiring zsh by FTP) cindex(availability of zsh) nofill(uref(ftp://ftp.zsh.org/pub/) uref(https://www.zsh.org/pub/)) -) The up-to-date source code is available via Git from Sourceforge. See uref(https://sourceforge.net/projects/zsh/) for details. A summary of instructions for the archive can be found at -uref(http://zsh.sourceforge.net/). +uref(https://zsh.sourceforge.io/). texinode(Mailing Lists)(The Zsh FAQ)(Availability)(Introduction) sect(Mailing Lists) cindex(mailing lists) -Zsh has 3 mailing lists: +Zsh has several mailing lists: startitem() item(tt(<zsh-announce@zsh.org>))( @@ -48,6 +47,12 @@ User discussions. item(tt(<zsh-workers@zsh.org>))( Hacking, development, bug reports and patches. ) +item(tt(<zsh-security@zsh.org>))( +Private mailing list (the general public cannot subscribe to it) for discussing +bug reports with security implications, i.e., potential vulnerabilities. + +If you find a security problem in zsh itself, please mail this address. +) enditem() To subscribe or unsubscribe, send mail @@ -69,12 +74,11 @@ bf(zsh-users). All submissions to bf(zsh-users) are automatically forwarded to bf(zsh-workers). If you have problems subscribing/unsubscribing to any of the mailing -lists, send mail to tt(<listmaster@zsh.org>). The mailing lists are -maintained by Karsten Thygesen tt(<karthy@kom.auc.dk>). +lists, send mail to tt(<listmaster@zsh.org>). The mailing lists are archived; the archives can be accessed via the administrative addresses listed above. There is also a hypertext -archive, maintained by Geoff Wing tt(<gcw@zsh.org>), available at +archive available at uref(https://www.zsh.org/mla/). texinode(The Zsh FAQ)(The Zsh Web Page)(Mailing Lists)(Introduction) sect(The Zsh FAQ) @@ -82,12 +86,11 @@ Zsh has a list of Frequently Asked Questions (FAQ), maintained by Peter Stephenson tt(<pws@zsh.org>). It is regularly posted to the newsgroup bf(comp.unix.shell) and the bf(zsh-announce) mailing list. The latest version can be found at any of the Zsh FTP sites, or at -uref(http://www.zsh.org/FAQ/). The contact address for FAQ-related matters +uref(https://www.zsh.org/FAQ/). The contact address for FAQ-related matters is tt(<faqmaster@zsh.org>). texinode(The Zsh Web Page)(The Zsh Userguide)(The Zsh FAQ)(Introduction) sect(The Zsh Web Page) -Zsh has a web page which is located at uref(https://www.zsh.org/). This is -maintained by Karsten Thygesen tt(<karthy@zsh.org>), of SunSITE Denmark. +Zsh has a web page which is located at uref(https://www.zsh.org/). The contact address for web-related matters is tt(<webmaster@zsh.org>). texinode(The Zsh Userguide)(See Also)(The Zsh Web Page)(Introduction) sect(The Zsh Userguide) @@ -95,6 +98,6 @@ A userguide is currently in preparation. It is intended to complement the manual, with explanations and hints on issues where the manual can be cabbalistic, hierographic, or downright mystifying (for example, the word `hierographic' does not exist). It can be viewed in its current state at -uref(http://zsh.sourceforge.net/Guide/). At the time of writing, chapters +uref(https://zsh.sourceforge.io/Guide/). At the time of writing, chapters dealing with startup files and their contents and the new completion system were essentially complete. diff --git a/Doc/Zsh/mod_curses.yo b/Doc/Zsh/mod_curses.yo index 6e4831abe..e2d5690e2 100644 --- a/Doc/Zsh/mod_curses.yo +++ b/Doc/Zsh/mod_curses.yo @@ -157,7 +157,7 @@ input. This is only available with the ncurses library; mouse handling can be detected by checking for the exit status of `tt(zcurses mouse)' with no arguments. If a mouse button is clicked (or double- or triple-clicked, or pressed or released with -a configurable delay from being clicked) then tt(kparam) is set to the string +a configurable delay from being clicked) then var(kparam) is set to the string tt(MOUSE), and var(mparam) is set to an array consisting of the following elements: startitem() diff --git a/Doc/Zsh/mod_datetime.yo b/Doc/Zsh/mod_datetime.yo index da65a9bbd..853656128 100644 --- a/Doc/Zsh/mod_datetime.yo +++ b/Doc/Zsh/mod_datetime.yo @@ -6,8 +6,8 @@ The tt(zsh/datetime) module makes available one builtin command: startitem() findex(strftime) cindex(date string, printing) -xitem(tt(strftime) [ tt(-s) var(scalar) ] var(format) [ var(epochtime) [ var(nanoseconds) ] ] ) -item(tt(strftime) tt(-r) [ tt(-q) ] [ tt(-s) var(scalar) ] var(format) var(timestring) )( +xitem(tt(strftime) [ tt(-s) var(scalar) | tt(-n) ] var(format) [ var(epochtime) [ var(nanoseconds) ] ] ) +item(tt(strftime) tt(-r) [ tt(-q) ] [ tt(-s) var(scalar) | tt(-n) ] var(format) var(timestring) )( Output the date in the var(format) specified. With no var(epochtime), the current system date/time is used; optionally, var(epochtime) may be used to specify the number of seconds since the epoch, and var(nanoseconds) may @@ -18,6 +18,9 @@ ifzman(the section EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\ ifnzman(noderef(Prompt Expansion)) are also available. startitem() +item(tt(-n))( +Suppress printing a newline after the formatted string. +) item(tt(-q))( Run quietly; suppress printing of all error messages described below. Errors for invalid var(epochtime) values are always printed. diff --git a/Doc/Zsh/mod_mapfile.yo b/Doc/Zsh/mod_mapfile.yo index 640beeb12..9d8f07214 100644 --- a/Doc/Zsh/mod_mapfile.yo +++ b/Doc/Zsh/mod_mapfile.yo @@ -13,7 +13,7 @@ value is the content of the file. The value is treated identically to any other text coming from a parameter. The value may also be assigned to, in which case the file in question is written (whether or not it originally existed); or an element may be unset, which will delete the file in -question. For example, `tt(vared mapfile[myfile])' works as expected, +question. For example, `tt(vared 'mapfile[myfile]')' works as expected, editing the file `tt(myfile)'. When the array is accessed as a whole, the keys are the names of files in diff --git a/Doc/Zsh/mod_newuser.yo b/Doc/Zsh/mod_newuser.yo index 92a64a013..7937e43c3 100644 --- a/Doc/Zsh/mod_newuser.yo +++ b/Doc/Zsh/mod_newuser.yo @@ -44,4 +44,4 @@ even if the tt(zsh/newuser) module is disabled. Note, however, that if the module is not installed the function will not be installed either. The function is documented in ifnzman(noderef(User Configuration Functions))\ -ifzman(the section User Configuration Functions in zmanref(zshcontrib)). +ifzman(the section `User Configuration Functions' in zmanref(zshcontrib)). diff --git a/Doc/Zsh/mod_parameter.yo b/Doc/Zsh/mod_parameter.yo index 2e3011e44..f3bcd7957 100644 --- a/Doc/Zsh/mod_parameter.yo +++ b/Doc/Zsh/mod_parameter.yo @@ -165,6 +165,8 @@ The keys of the associative arrays are usually valid job numbers, and these are the values output with, for example, tt(${(k)jobdirs}). Non-numeric job references may be used when looking up a value; for example, tt(${jobdirs[%+]}) refers to the current job. + +See the tt(jobs) builtin for how job information is provided in a subshell. ) vindex(jobtexts) item(tt(jobtexts))( @@ -173,6 +175,8 @@ that were used to start the jobs. Handling of the keys of the associative array is as described for tt(jobdirs) above. + +See the tt(jobs) builtin for how job information is provided in a subshell. ) vindex(jobstates) item(tt(jobstates))( @@ -189,6 +193,8 @@ the var(state) describes the state of that process. Handling of the keys of the associative array is as described for tt(jobdirs) above. + +See the tt(jobs) builtin for how job information is provided in a subshell. ) vindex(nameddirs) item(tt(nameddirs))( diff --git a/Doc/Zsh/mod_private.yo b/Doc/Zsh/mod_private.yo index 78aee0acf..184fa2be8 100644 --- a/Doc/Zsh/mod_private.yo +++ b/Doc/Zsh/mod_private.yo @@ -10,12 +10,16 @@ ifnzman() startitem() findex(private) cindex(private parameter, creating) -item(tt(private) [ {tt(PLUS())|tt(-)}tt(AHUahlprtux) ] \ +item(tt(private) [ {tt(PLUS())|tt(-)}tt(AHUahlmrtux) ] \ [ {tt(PLUS())|tt(-)}tt(EFLRZi) [ var(n) ] ] [ var(name)[tt(=)var(value)] ... ])( The tt(private) builtin accepts all the same options and arguments as tt(local) (ifzman(zmanref(zshbuiltins))ifnzman(noderef(Shell Builtin Commands))) except for the `tt(-)tt(T)' option. Tied parameters may not be made private. +The `tt(-)tt(p)' option is presently a no-op because the state of +private parameters cannot reliably be reloaded. This also applies +to printing private parameters with `tt(typeset -p)'. + If used at the top level (outside a function scope), tt(private) creates a normal parameter in the same manner as tt(declare) or tt(typeset). A warning about this is printed if tt(WARN_CREATE_GLOBAL) is set @@ -75,7 +79,8 @@ itemiz(Within any other function called by the declaring function, the private parameter does em(NOT) hide other parameters of the same name, so for example a global parameter of the same name is visible and may be assigned or unset. This includes calls to anonymous functions, although -that may also change in the future.) +that may also change in the future. However, the private name may not be +created outside the local scope when it was not previously declared.) itemiz(An exported private remains in the environment of inner scopes but appears unset for the current shell in those scopes. Generally, exporting private parameters should be avoided.) diff --git a/Doc/Zsh/mod_regex.yo b/Doc/Zsh/mod_regex.yo index f20451664..40ee92785 100644 --- a/Doc/Zsh/mod_regex.yo +++ b/Doc/Zsh/mod_regex.yo @@ -26,5 +26,17 @@ tt(-regex-match) operator. If tt(BASH_REMATCH) is set, then the array tt(BASH_REMATCH) will be set instead of tt(MATCH) and tt(match). + +Note that the tt(zsh/regex) module logic relies on the host system. The +same var(expr) and var(regex) pair could produce different results on different +platforms if a var(regex) with non-standard syntax is given. + +For example, no syntax for matching a word boundary is defined in the POSIX +extended regular expression standard. GNU tt(libc) and BSD tt(libc) both provide +such syntaxes as extensions (tt(\b) and tt([[:<:]])/tt([[:>:]]) respectively), +but neither of these syntaxes is supported by both of these implementations. + +Refer to the manref(regcomp)(3) and manref(re_format)(7) manual pages on your +system for locally-supported syntax. ) enditem() diff --git a/Doc/Zsh/mod_stat.yo b/Doc/Zsh/mod_stat.yo index 9caed1e45..b591d4003 100644 --- a/Doc/Zsh/mod_stat.yo +++ b/Doc/Zsh/mod_stat.yo @@ -118,6 +118,8 @@ formatting of the time elements. The format string supports all of the zsh extensions described in ifzman(the section EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\ ifnzman(noderef(Prompt Expansion)). +In particular, tt(-F %s.%N) can be used to show timestamps with nanosecond +precision if supported by the system. The tt(-s) option is implied. ) item(tt(-g))( diff --git a/Doc/Zsh/mod_system.yo b/Doc/Zsh/mod_system.yo index 6292af071..884c3e753 100644 --- a/Doc/Zsh/mod_system.yo +++ b/Doc/Zsh/mod_system.yo @@ -62,6 +62,9 @@ suppress updating of the file atime item(tt(nofollow))( fail if var(file) is a symbolic link ) +item(tt(nonblock))( +the file is opened in nonblocking mode +) item(tt(sync))( request that writes wait until data has been physically written ) @@ -166,7 +169,7 @@ to the command, or 2 for an error on the write; no error message is printed in the last case, but the parameter tt(ERRNO) will reflect the error that occurred. ) -xitem(tt(zsystem flock) [ tt(-t) var(timeout) ] [ tt(-f) var(var) ] [tt(-er)] var(file)) +xitem(tt(zsystem flock) [ tt(-t) var(timeout) ] [ tt(-i) var(interval) ] [ tt(-f) var(var) ] [tt(-er)] var(file)) item(tt(zsystem flock -u) var(fd_expr))( The builtin tt(zsystem)'s subcommand tt(flock) performs advisory file locking (via the manref(fcntl)(2) system call) over the entire contents @@ -196,9 +199,16 @@ a safety check that the file descriptor is in use for file locking. By default the shell waits indefinitely for the lock to succeed. The option tt(-t) var(timeout) specifies a timeout for the lock in -seconds; currently this must be an integer. The shell will attempt -to lock the file once a second during this period. If the attempt -times out, status 2 is returned. +seconds; fractional seconds are allowed. During this period, the +shell will attempt to lock the file every var(interval) seconds +if the tt(-i) var(interval) option is given, otherwise once a second. +(This var(interval) is shortened before the last attempt if needed, +so that the shell waits only until the var(timeout) and not longer.) +If the attempt times out, status 2 is returned. + +(Note: var(timeout) is limited to 2^30-1 seconds (about 34 years), and +var(interval) to 0.999 * LONG_MAX microseconds (only about 35 minutes +on 32-bit systems).) If the option tt(-e) is given, the file descriptor for the lock is preserved when the shell uses tt(exec) to start a new process; @@ -256,9 +266,9 @@ tt($$), which returns the process ID of the main shell process. ) item(tt(ppid))( vindex(ppid, sysparams) -Returns the process ID of the parent of the current process, even in -subshells. Compare tt($PPID), which returns the process ID of the parent -of the main shell process. +Returns the current process ID of the parent of the current process, even +in subshells. Compare tt($PPID), which returns the process ID of the +initial parent of the main shell process. ) item(tt(procsubstpid))( Returns the process ID of the last process started for process diff --git a/Doc/Zsh/mod_watch.yo b/Doc/Zsh/mod_watch.yo new file mode 100644 index 000000000..d97a41d13 --- /dev/null +++ b/Doc/Zsh/mod_watch.yo @@ -0,0 +1,146 @@ +COMMENT(!MOD!zsh/watch +Reporting of login and logout events. +!MOD!) +The tt(zsh/watch) module can be used to report when specific users log in or +out. This is controlled via the following parameters. + +startitem() +vindex(LOGCHECK) +item(tt(LOGCHECK))( +The interval in seconds between checks for login/logout activity +using the tt(watch) parameter. +) +vindex(watch) +vindex(WATCH) +item(tt(watch) <S> <Z> (tt(WATCH) <S>))( +An array (colon-separated list) of login/logout events to report. + +If it contains the single word `tt(all)', then all login/logout events +are reported. If it contains the single word `tt(notme)', then all +events are reported as with `tt(all)' except tt($USERNAME). + +An entry in this list may consist of a username, +an `tt(@)' followed by a remote hostname, +and a `tt(%)' followed by a line (tty). Any of these may +be a pattern (be sure to quote this during the assignment to +tt(watch) so that it does not immediately perform file generation); +the setting of the tt(EXTENDED_GLOB) option is respected. +Any or all of these components may be present in an entry; +if a login/logout event matches all of them, +it is reported. + +For example, with the tt(EXTENDED_GLOB) option set, the following: + +example(watch=('^(pws|barts)')) + +causes reports for activity associated with any user other than tt(pws) +or tt(barts). +) +vindex(WATCHFMT) +item(tt(WATCHFMT))( +The format of login/logout reports if the tt(watch) parameter is set. +Default is `tt(%n has %a %l from %m)'. +Recognizes the following escape sequences: + +startitem() +item(tt(%n))( +The name of the user that logged in/out. +) +item(tt(%a))( +The observed action, i.e. "logged on" or "logged off". +) +item(tt(%l))( +The line (tty) the user is logged in on. +) +item(tt(%M))( +The full hostname of the remote host. +) +item(tt(%m))( +The hostname up to the first `tt(.)'. If only the +IP address is available or the utmp field contains +the name of an X-windows display, the whole name is printed. + +em(NOTE:) +The `tt(%m)' and `tt(%M)' escapes will work only if there is a host name +field in the utmp on your machine. Otherwise they are +treated as ordinary strings. +) +item(tt(%F{)var(color)tt(}) LPAR()tt(%f)RPAR())( +Start (stop) using a different foreground color. +) +item(tt(%K{)var(color)tt(}) LPAR()tt(%k)RPAR())( +Start (stop) using a different background color. +) +item(tt(%S) LPAR()tt(%s)RPAR())( +Start (stop) standout mode. +) +item(tt(%U) LPAR()tt(%u)RPAR())( +Start (stop) underline mode. +) +item(tt(%B) LPAR()tt(%b)RPAR())( +Start (stop) boldface mode. +) +xitem(tt(%t)) +item(tt(%@))( +The time, in 12-hour, am/pm format. +) +item(tt(%T))( +The time, in 24-hour format. +) +item(tt(%w))( +The date in `var(day)tt(-)var(dd)' format. +) +item(tt(%W))( +The date in `var(mm)tt(/)var(dd)tt(/)var(yy)' format. +) +item(tt(%D))( +The date in `var(yy)tt(-)var(mm)tt(-)var(dd)' format. +) +item(tt(%D{)var(string)tt(}))( +The date formatted as var(string) using the tt(strftime) function, with +zsh extensions as described by +ifzman(EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\ +ifnzman(noderef(Prompt Expansion)). +) +item(tt(%LPAR())var(x)tt(:)var(true-text)tt(:)var(false-text)tt(RPAR()))( +Specifies a ternary expression. +The character following the var(x) is +arbitrary; the same character is used to separate the text +for the "true" result from that for the "false" result. +Both the separator and the right parenthesis may be escaped +with a backslash. +Ternary expressions may be nested. + +The test character var(x) may be any one of `tt(l)', `tt(n)', `tt(m)' +or `tt(M)', which indicate a `true' result if the corresponding +escape sequence would return a non-empty value; or it may be `tt(a)', +which indicates a `true' result if the watched user has logged in, +or `false' if he has logged out. +Other characters evaluate to neither true nor false; the entire +expression is omitted in this case. + +If the result is `true', then the var(true-text) +is formatted according to the rules above and printed, +and the var(false-text) is skipped. +If `false', the var(true-text) is skipped and the var(false-text) +is formatted and printed. +Either or both of the branches may be empty, but +both separators must be present in any case. +) +enditem() +) +enditem() + +Furthermore, the tt(zsh/watch) module makes available one builtin +command: + +startitem() +findex(log) +vindex(watch, use of) +cindex(watching users) +cindex(users, watching) +item(tt(log))( +List all users currently logged in who are affected by +the current setting of the tt(watch) parameter. +) +enditem() diff --git a/Doc/Zsh/mod_zselect.yo b/Doc/Zsh/mod_zselect.yo index e0651571e..faf59c165 100644 --- a/Doc/Zsh/mod_zselect.yo +++ b/Doc/Zsh/mod_zselect.yo @@ -12,7 +12,7 @@ The tt(zselect) builtin is a front-end to the `select' system call, which blocks until a file descriptor is ready for reading or writing, or has an error condition, with an optional timeout. If this is not available on your system, the command prints an error message and returns status 2 -(normal errors return status 1). For more information, see your systems +(normal errors return status 1). For more information, see your system's documentation for manref(select)(3). Note there is no connection with the shell builtin of the same name. diff --git a/Doc/Zsh/mod_zutil.yo b/Doc/Zsh/mod_zutil.yo index 24aebdfaf..3cf9e5028 100644 --- a/Doc/Zsh/mod_zutil.yo +++ b/Doc/Zsh/mod_zutil.yo @@ -32,20 +32,27 @@ If two patterns are equally specific, the tie is broken in favour of the pattern that was defined first. em(Example) +kindex(preferred-precipitation, example style) +findex(weather, example function) -For example, to define your preferred form of precipitation depending on which -city you're in, you might set the following in your tt(zshrc): +For example, a fictional `tt(weather)' plugin might state in its documentation +that it looks up the tt(preferred-precipitation) style under the +`tt(:weather:)var(continent)tt(:)var(day-of-the-week)tt(:)var(phase-of-the-moon)' context. +According to this, you might set the following in your tt(zshrc): example(zstyle ':weather:europe:*' preferred-precipitation rain -zstyle ':weather:europe:germany:* preferred-precipitation none -zstyle ':weather:europe:germany:*:munich' preferred-precipitation snow) +zstyle ':weather:*:Sunday:*' preferred-precipitation snow) -Then, the fictional `tt(weather)' plugin might run under the hood a command -such as +Then the plugin would run under the hood a command such as -example(zstyle -s ":weather:${continent}:${country}:${county}:${city}" preferred-precipitation REPLY) +example(zstyle -s ":weather:${continent}:${day_of_week}:${moon_phase}" preferred-precipitation REPLY) in order to retrieve your preference into the scalar variable tt($REPLY). +On Sundays tt($REPLY) would be set to `tt(snow)'; in Europe it would be set +to `tt(rain)'; and on Sundays in Europe it would be set to `tt(snow)' again, +because the patterns `tt(:weather:europe:*)' and `tt(:weather:*:Sunday:*)' both +match the var(context) argument to tt(zstyle -s), are equally specific, and the +latter is more specific (because it has more colon-separated components). em(Usage) @@ -143,8 +150,9 @@ enditem() ) findex(zformat) xitem(tt(zformat -f) var(param) var(format) var(spec) ...) +xitem(tt(zformat -F) var(param) var(format) var(spec) ...) item(tt(zformat -a) var(array) var(sep) var(spec) ...)( -This builtin provides two different forms of formatting. The first form +This builtin provides different forms of formatting. The first form is selected with the tt(-f) option. In this case the var(format) string will be modified by replacing sequences starting with a percent sign in it with strings from the var(spec)s. Each var(spec) should be @@ -188,7 +196,13 @@ outputs "The answer is 'yes'." to tt(REPLY) since the value for the format specifier tt(c) is 3, agreeing with the digit argument to the ternary expression. -The second form, using the tt(-a) option, can be used for aligning +With tt(-F) instead of tt(-f), ternary expressions choose between the +`true' or `false' text on the basis of whether the format specifier is +present and non-empty. A test number indicates a minimum width for the +value given in the format specifier. Negative numbers reverse this, +so the test is for whether the value exceeds a maximum width. + +The form, using the tt(-a) option, can be used for aligning strings. Here, the var(spec)s are of the form `var(left)tt(:)var(right)' where `var(left)' and `var(right)' are arbitrary strings. These strings are modified by replacing the colons diff --git a/Doc/Zsh/modlist.yo b/Doc/Zsh/modlist.yo index 484321e69..d066879a9 100644 --- a/Doc/Zsh/modlist.yo +++ b/Doc/Zsh/modlist.yo @@ -87,6 +87,9 @@ Interface to the termcap database. item(tt(zsh/terminfo))( Interface to the terminfo database. ) +item(tt(zsh/watch))( +Reporting of login and logout events. +) item(tt(zsh/zftp))( A builtin FTP client. ) @@ -195,10 +198,13 @@ includefile(Zsh/mod_tcp.yo) texinode(The zsh/termcap Module)(The zsh/terminfo Module)(The zsh/net/tcp Module)(Zsh Modules) sect(The zsh/termcap Module) includefile(Zsh/mod_termcap.yo) -texinode(The zsh/terminfo Module)(The zsh/zftp Module)(The zsh/termcap Module)(Zsh Modules) +texinode(The zsh/terminfo Module)(The zsh/watch Module)(The zsh/termcap Module)(Zsh Modules) sect(The zsh/terminfo Module) includefile(Zsh/mod_terminfo.yo) -texinode(The zsh/zftp Module)(The zsh/zle Module)(The zsh/terminfo Module)(Zsh Modules) +texinode(The zsh/watch Module)(The zsh/zftp Module)(The zsh/terminfo Module)(Zsh Modules) +sect(The zsh/watch Module) +includefile(Zsh/mod_watch.yo) +texinode(The zsh/zftp Module)(The zsh/zle Module)(The zsh/watch Module)(Zsh Modules) sect(The zsh/zftp Module) includefile(Zsh/mod_zftp.yo) texinode(The zsh/zle Module)(The zsh/zleparameter Module)(The zsh/zftp Module)(Zsh Modules) diff --git a/Doc/Zsh/modmenu.yo b/Doc/Zsh/modmenu.yo index 2d29b6e96..c922390a4 100644 --- a/Doc/Zsh/modmenu.yo +++ b/Doc/Zsh/modmenu.yo @@ -28,6 +28,7 @@ menu(The zsh/system Module) menu(The zsh/net/tcp Module) menu(The zsh/termcap Module) menu(The zsh/terminfo Module) +menu(The zsh/watch Module) menu(The zsh/zftp Module) menu(The zsh/zle Module) menu(The zsh/zleparameter Module) diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo index fdea51412..443676b78 100644 --- a/Doc/Zsh/options.yo +++ b/Doc/Zsh/options.yo @@ -41,6 +41,9 @@ will be treated just as `tt(-f)', but the string `tt(-f i)' is an error. This is because many systems which implement the `tt(#!)' mechanism for calling scripts do not strip trailing whitespace. +It is possible for options to be set within a function scope. See the +description of the option tt(LOCAL_OPTIONS) below. + texinode(Description of Options)(Option Aliases)(Specifying Options)(Options) sect(Description of Options) cindex(options, description) @@ -474,6 +477,22 @@ item(tt(CASE_MATCH) <D>)( Make regular expressions using the tt(zsh/regex) module (including matches with tt(=~)) sensitive to case. ) +pindex(CASE_PATHS) +pindex(NO_CASE_PATHS) +pindex(CASEPATHS) +pindex(NOCASEPATHS) +cindex(case-sensitive globbing, option) +item(tt(CASE_PATHS))( +If tt(CASE_PATHS) is not set (the default), tt(CASE_GLOB) affects the +interpretation of em(every) path component, whenever a special +character appears in em(any) component. When tt(CASE_PATHS) is set, +file path components that do em(not) contain special filename +generation characters are always sensitive to case, thus restricting +tt(NO_CASE_GLOB) to components that contain globbing characters. + +Note that if the filesystem itself is not sensitive to case, then +tt(CASE_PATHS) has no effect. +) pindex(CSH_NULL_GLOB) pindex(NO_CSH_NULL_GLOB) pindex(CSHNULLGLOB) @@ -586,7 +605,7 @@ Substitutions using the tt(:s) and tt(:&) history modifiers are performed with pattern matching instead of string matching. This occurs wherever history modifiers are valid, including glob qualifiers and parameters. See -ifzman(the section Modifiers in zmanref(zshexpn))\ +ifzman(the section `Modifiers' in zmanref(zshexpn))\ ifnzman(noderef(Modifiers)). ) pindex(IGNORE_BRACES) @@ -1124,7 +1143,7 @@ pindex(GLOBALRCS) pindex(NOGLOBALRCS) cindex(startup files, global, inhibiting) cindex(files, global startup, inhibiting) -item(tt(GLOBAL_RCS) (tt(-d)) <D>)( +item(tt(GLOBAL_RCS) (tt(+d)) <D>)( If this option is unset, the startup files tt(zprofile()), tt(zshrc()), tt(zlogin()) and tt(zlogout()) will not be run. It can be disabled and re-enabled at any time, including inside local startup @@ -1168,6 +1187,22 @@ If the option is not set, and the option tt(APPEND_CREATE) is also not set, `tt(>>!)' or `tt(>>|)' must be used to create a file. If either option is set, `tt(>>)' may be used. ) +pindex(CLOBBER_EMPTY) +pindex(NO_CLOBBER_EMPTY) +pindex(CLOBBEREMPTY) +pindex(NOCLOBBEREMPTY) +cindex(clobbering, of empty files) +cindex(file clobbering, of empty files) +item(tt(CLOBBER_EMPTY))( +This option is only used if the option tt(CLOBBER) is not set: note that +it is set by default. + +If this option is set, then regular files of zero length may be +ovewritten (`clobbered'). Note that it is possible another process +has written to the file between this test and use of the file by +the current process. This option should therefore not be used in +cases where files to be clobbered may be written to asynchronously. +) pindex(CORRECT) pindex(NO_CORRECT) pindex(NOCORRECT) @@ -1377,6 +1412,14 @@ item(tt(SHORT_LOOPS) <C> <Z>)( Allow the short forms of tt(for), tt(repeat), tt(select), tt(if), and tt(function) constructs. ) +pindex(SHORT_REPEAT) +pindex(NO_SHORT_REPEAT) +pindex(SHORTREPEAT) +pindex(NOSHORTREPEAT) +item(tt(SHORT_REPEAT))( +Allow the short form tt(repeat) as tt(SHORT_LOOPS) but without enabling +it for the other constructs. +) pindex(SUN_KEYBOARD_HACK) pindex(NO_SUN_KEYBOARD_HACK) pindex(SUNKEYBOARDHACK) @@ -1443,7 +1486,7 @@ The check is omitted if the commands run from the previous command line included a `tt(jobs)' command, since it is assumed the user is aware that there are background or suspended jobs. A `tt(jobs)' command run from one of the hook functions defined in -ifnzman(the section Special Functions in noderef(Functions))\ +ifnzman(the section `Special Functions' in noderef(Functions))\ ifzman(the section SPECIAL FUNCTIONS in zmanref(zshmisc)) is not counted for this purpose. ) @@ -1902,6 +1945,16 @@ If the option is set, they will only be shown when parameters are selected with the `tt(-m)' option. The option `tt(-p)' is available whether or not the option is set. ) +pindex(TYPESET_TO_UNSET) +pindex(NO_TYPESET_TO_UNSET) +pindex(TYPESETTOUNSET) +pindex(NOTYPESETTOUNSET) +item(tt(TYPESET_TO_UNSET) <K> <S>)( +When declaring a new parameter with any of the `tt(typeset)' family of +related commands, the parameter remains unset unless and until a +value is explicity assigned to it, either in the `tt(typeset)' command +itself or as a later assignment statement. +) pindex(VERBOSE) pindex(NO_VERBOSE) pindex(NOVERBOSE) @@ -2199,7 +2252,8 @@ command found in the path. Furthermore, the tt(getopts) builtin behaves in a POSIX-compatible fashion in that the associated variable tt(OPTIND) is not made -local to functions. +local to functions, and its value is calculated differently to match +other shells. Moreover, the warning and special exit code from tt([[ -o )var(non_existent_option)tt( ]]) are suppressed. @@ -2279,10 +2333,15 @@ When this option is set, the usual zsh behaviour of executing traps for tt(EXIT) on exit from shell functions is suppressed. In that case, manipulating tt(EXIT) traps always alters the global trap for exiting the shell; the tt(LOCAL_TRAPS) option is -ignored for the tt(EXIT) trap. Furthermore, a tt(return) statement -executed in a trap with no argument passes back from the function the -value from the surrounding context, not from code executed within the -trap. +ignored for the tt(EXIT) trap. + +Also, a tt(return) statement executed in a trap with no argument passes +back from the function the value from the surrounding context, not from +code executed within the trap. + +Furthermore, if a trap is set to be ignored, this state persists when +a subshell is entered. Without the option, the trap would be reset to +its default state at this point. ) pindex(SH_FILE_EXPANSION) pindex(NO_SH_FILE_EXPANSION) diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo index 8daf33d5e..6d2d41b7a 100644 --- a/Doc/Zsh/params.yo +++ b/Doc/Zsh/params.yo @@ -106,7 +106,7 @@ may be in any order. Note that this syntax is strict: tt([) and tt(]=) must not be quoted, and var(key) may not consist of the unquoted string tt(]=), but is otherwise treated as a simple string. The enhanced forms of subscript expression that may be used when directly subscripting a -variable name, described in the section Array Subscripts below, are not +variable name, described in the section `Array Subscripts' below, are not available. The syntaxes with and without the explicit key may be mixed. An implicit @@ -393,12 +393,21 @@ is compared to the pattern, and the first matching key found is the result. On failure substitutes the length of the array plus one, as discussed under the description of `tt(r)', or the empty string for an associative array. + +Note: Although `tt(i)' may be applied to a scalar substitution to find +the offset of a substring, the results are likely to be misleading when +searching within substitutions that yield an empty string, or when +searching for the empty substring. ) item(tt(I))( Like `tt(i)', but gives the index of the last match, or all possible matching keys in an associative array. On failure substitutes 0, or the empty string for an associative array. This flag is best when testing for values or keys that do not exist. + +Note: If the option tt(KSH_ARRAYS) is in effect and no match is found, the +result is indistinguishable from the case when the first element of the array +matches. ) item(tt(k))( If used in a subscript on an associative array, this flag causes the keys @@ -623,6 +632,14 @@ In the parameter lists that follow, the mark `<S>' indicates that the parameter is special. `<Z>' indicates that the parameter does not exist when the shell initializes in tt(sh) or tt(ksh) emulation mode. +The parameters `tt(!)', `tt(#)', `tt(*)', `tt(-)', `tt(?)', `tt(@)', +`tt($)', `tt(ARGC)', `tt(HISTCMD)', `tt(LINENO)', `tt(PPID)', +`tt(status)', `tt(TTYIDLE)', `tt(zsh_eval_context)', +`tt(ZSH_EVAL_CONTEXT)', and `tt(ZSH_SUBSHELL)' are read-only and thus +cannot be restored by the user, so they are not output by +`tt(typeset -p)'. This also applies to many read-only parameters loaded +from modules. + The following parameters are automatically set by the shell: startitem() @@ -645,10 +662,11 @@ Same as tt(#). ) vindex($) item(tt($) <S>)( -The process ID of this shell. Note that this indicates the original -shell started by invoking tt(zsh); all processes forked from the shells -without executing a new program, such as subshells started by -tt(LPAR())var(...)tt(RPAR()), substitute the same value. +The process ID of this shell, set when the shell initializes. Processes +forked from the shell without executing a new program, such as command +substitutions and commands grouped with tt(LPAR())var(...)tt(RPAR()), +are subshells that duplicate the current shell, and thus substitute the +same value for tt($$) as their parent shell. ) vindex(-) item(tt(-) <S>)( @@ -727,7 +745,7 @@ explicitly set locally. ) vindex(ERRNO) item(tt(ERRNO) <S>)( -The value of errno (see manref(errno)(3)) +The value of tt(errno) (see manref(errno)(3)) as set by the most recently failed system call. This value is system dependent and is intended for debugging purposes. It is also useful with the tt(zsh/system) module which @@ -808,9 +826,9 @@ The operating system, as determined at compile time. ) vindex(PPID) item(tt(PPID) <S>)( -The process ID of the parent of the shell. As for tt($$), the -value indicates the parent of the original shell and does not -change in subshells. +The process ID of the parent of the shell, set when the shell initializes. +As with tt($$), the value does not change in subshells created as a +duplicate of the current shell. ) vindex(PWD) item(tt(PWD))( @@ -836,8 +854,9 @@ will be the value that was assigned plus the number of seconds since the assignment. Unlike other special parameters, the type of the tt(SECONDS) parameter can -be changed using the tt(typeset) command. Only integer and one of the -floating point types are allowed. For example, `tt(typeset -F SECONDS)' +be changed using the tt(typeset) command. The type may be changed only +to one of the floating point types or back to integer. For example, +`tt(typeset -F SECONDS)' causes the value to be reported as a floating point number. The value is available to microsecond accuracy, although the shell may show more or fewer digits depending on the use of tt(typeset). See @@ -1313,11 +1332,6 @@ most as many lines as given by the absolute value. If set to zero, the shell asks only if the top of the listing would scroll off the screen. ) -vindex(LOGCHECK) -item(tt(LOGCHECK))( -The interval in seconds between checks for login/logout activity -using the tt(watch) parameter. -) vindex(MAIL) item(tt(MAIL))( If this parameter is set and tt(mailpath) is not set, @@ -1556,6 +1570,11 @@ if it is in the environment of the shell but not explicitly assigned to in the input line. This avoids running stty at every external command by accidentally exporting it. Also note that tt(STTY) should not be used for window size specifications; these will not be local to the command. + +If the parameter is set and empty, all of the above applies except +that tt(stty) is not run. This can be useful as a way to freeze the tty +around a single command, blocking its changes to tty settings, +similar to the tt(ttyctl) builtin. ) vindex(TERM) item(tt(TERM) <S>)( @@ -1651,119 +1670,6 @@ to be interpreted as a file extension. The default is not to append any suffix, thus this parameter should be assigned only when needed and then unset again. ) -vindex(watch) -vindex(WATCH) -item(tt(watch) <S> <Z> (tt(WATCH) <S>))( -An array (colon-separated list) of login/logout events to report. - -If it contains the single word `tt(all)', then all login/logout events -are reported. If it contains the single word `tt(notme)', then all -events are reported as with `tt(all)' except tt($USERNAME). - -An entry in this list may consist of a username, -an `tt(@)' followed by a remote hostname, -and a `tt(%)' followed by a line (tty). Any of these may -be a pattern (be sure to quote this during the assignment to -tt(watch) so that it does not immediately perform file generation); -the setting of the tt(EXTENDED_GLOB) option is respected. -Any or all of these components may be present in an entry; -if a login/logout event matches all of them, -it is reported. - -For example, with the tt(EXTENDED_GLOB) option set, the following: - -example(watch=('^(pws|barts)')) - -causes reports for activity associated with any user other than tt(pws) -or tt(barts). -) -vindex(WATCHFMT) -item(tt(WATCHFMT))( -The format of login/logout reports if the tt(watch) parameter is set. -Default is `tt(%n has %a %l from %m)'. -Recognizes the following escape sequences: - -startitem() -item(tt(%n))( -The name of the user that logged in/out. -) -item(tt(%a))( -The observed action, i.e. "logged on" or "logged off". -) -item(tt(%l))( -The line (tty) the user is logged in on. -) -item(tt(%M))( -The full hostname of the remote host. -) -item(tt(%m))( -The hostname up to the first `tt(.)'. If only the -IP address is available or the utmp field contains -the name of an X-windows display, the whole name is printed. - -em(NOTE:) -The `tt(%m)' and `tt(%M)' escapes will work only if there is a host name -field in the utmp on your machine. Otherwise they are -treated as ordinary strings. -) -item(tt(%S) LPAR()tt(%s)RPAR())( -Start (stop) standout mode. -) -item(tt(%U) LPAR()tt(%u)RPAR())( -Start (stop) underline mode. -) -item(tt(%B) LPAR()tt(%b)RPAR())( -Start (stop) boldface mode. -) -xitem(tt(%t)) -item(tt(%@))( -The time, in 12-hour, am/pm format. -) -item(tt(%T))( -The time, in 24-hour format. -) -item(tt(%w))( -The date in `var(day)tt(-)var(dd)' format. -) -item(tt(%W))( -The date in `var(mm)tt(/)var(dd)tt(/)var(yy)' format. -) -item(tt(%D))( -The date in `var(yy)tt(-)var(mm)tt(-)var(dd)' format. -) -item(tt(%D{)var(string)tt(}))( -The date formatted as var(string) using the tt(strftime) function, with -zsh extensions as described by -ifzman(EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\ -ifnzman(noderef(Prompt Expansion)). -) -item(tt(%LPAR())var(x)tt(:)var(true-text)tt(:)var(false-text)tt(RPAR()))( -Specifies a ternary expression. -The character following the var(x) is -arbitrary; the same character is used to separate the text -for the "true" result from that for the "false" result. -Both the separator and the right parenthesis may be escaped -with a backslash. -Ternary expressions may be nested. - -The test character var(x) may be any one of `tt(l)', `tt(n)', `tt(m)' -or `tt(M)', which indicate a `true' result if the corresponding -escape sequence would return a non-empty value; or it may be `tt(a)', -which indicates a `true' result if the watched user has logged in, -or `false' if he has logged out. -Other characters evaluate to neither true nor false; the entire -expression is omitted in this case. - -If the result is `true', then the var(true-text) -is formatted according to the rules above and printed, -and the var(false-text) is skipped. -If `false', the var(true-text) is skipped and the var(false-text) -is formatted and printed. -Either or both of the branches may be empty, but -both separators must be present in any case. -) -enditem() -) vindex(WORDCHARS) item(tt(WORDCHARS) <S>)( A list of non-alphanumeric characters considered part of a word diff --git a/Doc/Zsh/redirect.yo b/Doc/Zsh/redirect.yo index 2b48974b4..fd40ab5a4 100644 --- a/Doc/Zsh/redirect.yo +++ b/Doc/Zsh/redirect.yo @@ -86,7 +86,8 @@ item(tt(<<<) var(word))( Perform shell expansion on var(word) and pass the result to standard input. This is known as a em(here-string). Compare the use of var(word) in here-documents above, where var(word) -does not undergo shell expansion. +does not undergo shell expansion. The result will have a trailing newline +after it. ) xitem(tt(<&) var(number)) item(tt(>&) var(number))( diff --git a/Doc/Zsh/roadmap.yo b/Doc/Zsh/roadmap.yo index 94ef74d1f..2db90889b 100644 --- a/Doc/Zsh/roadmap.yo +++ b/Doc/Zsh/roadmap.yo @@ -20,7 +20,7 @@ The function is designed to be self-explanatory. You can run it by hand with `tt(autoload -Uz zsh-newuser-install; zsh-newuser-install -f)'. See also ifnzman(noderef(User Configuration Functions))\ -ifzman(the section User Configuration Functions in zmanref(zshcontrib)). +ifzman(the section `User Configuration Functions' in zmanref(zshcontrib)). sect(Interactive Use) @@ -49,7 +49,7 @@ The shell now supports the UTF-8 character set (and also others if supported by the operating system). This is (mostly) handled transparently by the shell, but the degree of support in terminal emulators is variable. There is some discussion of this in the shell FAQ, -uref(http://www.zsh.org/FAQ/). Note in particular that for combining +uref(https://www.zsh.org/FAQ/). Note in particular that for combining characters to be handled the option tt(COMBINING_CHARS) needs to be set. Because the shell is now more sensitive to the definition of the character set, note that if you are upgrading from an older version of diff --git a/Doc/Zsh/zftpsys.yo b/Doc/Zsh/zftpsys.yo index 349039edc..c2fbdd23f 100644 --- a/Doc/Zsh/zftpsys.yo +++ b/Doc/Zsh/zftpsys.yo @@ -518,13 +518,11 @@ command `tt(zstyle ':zftp:*') var(style) var(value) ...'. defines the var(style) to have value var(value); more than one value may be given, although that is not useful in the cases described here. These values will then be used throughout the zftp function system. For more -precise control, the first argument, which gives a context in which the +precise control, the first argument, which gives a pattern that matches em(contexts) in which the style applies, can be modified to include a particular function, as for example `tt(:zftp:zfget)': the style will then have the given value only -in the tt(zfget) function. Values for the same style in different contexts -may be set; the most specific function will be used, where -strings are held to be more specific than patterns, and longer patterns and -shorter patterns. Note that only the top level function name, as called by +in the tt(zfget) function, and will override styles set under `tt(:zftp:*)'. +Note that only the top level function name, as called by the user, is used; calling of lower level functions is transparent to the user. Hence modifications to the title bar in tt(zftp_chpwd) use the contexts tt(:zftp:zfopen), tt(:zftp:zfcd), etc., depending where it was diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo index c928b8ca2..2d033a0a1 100644 --- a/Doc/Zsh/zle.yo +++ b/Doc/Zsh/zle.yo @@ -50,13 +50,15 @@ argument causes the next command entered to be repeated the specified number of times, unless otherwise noted below; this is implemented by the tt(digit-argument) widget. See also ifzman(the em(Arguments) subsection of the em(Widgets) section )\ -ifnzman(noderef(Arguments) )\ +ifnzman(noderef(Arguments))\ for some other ways the numeric argument can be modified. startmenu() menu(Keymaps) menu(Zle Builtins) menu(Zle Widgets) +menu(User-Defined Widgets) +menu(Standard Widgets) menu(Character Highlighting) endmenu() @@ -107,6 +109,7 @@ In the `tt(.safe)' keymap, each single key is bound to tt(self-insert), except for ^J (line feed) and ^M (return) which are bound to tt(accept-line). This is deliberately not pleasant to use; if you are using it, it means you deleted the main keymap, and you should put it back. + subsect(Reading Commands) When ZLE is reading a command from the terminal, it may read a sequence that is bound to some command and is also a prefix of a longer bound string. @@ -137,6 +140,7 @@ in user-defined widgets with the tt(read-command) widget, described in ifzman(the subsection `Miscellaneous' of the section `Standard Widgets' below)\ ifnzman(noderef(Miscellaneous) below)\ . + subsect(Local Keymaps) cindex(local keymaps) While for normal editing a single keymap is used exclusively, in many @@ -415,7 +419,7 @@ xitem(tt(zle) tt(-K) var(keymap)) xitem(tt(zle) tt(-F) [ tt(-L) | tt(-w) ] [ var(fd) [ var(handler) ] ]) xitem(tt(zle) tt(-I)) xitem(tt(zle) tt(-T) [ tt(tc) var(function) | tt(-r) tt(tc) | tt(-L) ] ) -item(tt(zle) var(widget) [ tt(-n) var(num) ] [ tt(-Nw) ] [ tt(-K) var(keymap) ] var(args) ...)( +item(tt(zle) var(widget) [ tt(-n) var(num) ] [ tt(-f) var(flag) ] [ tt(-Nw) ] [ tt(-K) var(keymap) ] var(args) ...)( The tt(zle) builtin performs a number of different actions concerning ZLE. @@ -501,8 +505,7 @@ ifnzman(noderef(Completion Widgets))\ . ) item(tt(-R) [ tt(-c) ] [ var(display-string) ] [ var(string) ... ])( -Redisplay the command line; this is to be called from within a user-defined -widget to allow changes to become visible. If a var(display-string) is +Redisplay the command line. If a var(display-string) is given and not empty, this is shown in the status line (immediately below the line being edited). @@ -511,9 +514,9 @@ prompt in the same way as completion lists are printed. If no var(string)s are given but the tt(-c) option is used such a list is cleared. -Note that this option is only useful for widgets that do not exit -immediately after using it because the strings displayed will be erased -immediately after return from the widget. +Note that immediately after returning from running widgets, the command line +will be redisplayed and the strings displayed will be erased. Therefore, this +option is only useful for widgets that do not exit immediately after using it. This command can safely be called outside user defined widgets; if zle is active, the display will be refreshed, while if zle is not active, the @@ -683,7 +686,7 @@ optional argument for debugging or testing. Note that this transformation is not applied to other non-printing characters such as carriage returns and newlines. ) -item(var(widget) [ tt(-n) var(num) ] [ tt(-Nw) ] [ tt(-K) var(keymap) ] var(args) ...)( +item(var(widget) [ tt(-n) var(num) ] [ tt(-f) var(flag) ] [ tt(-Nw) ] [ tt(-K) var(keymap) ] var(args) ...)( Invoke the specified var(widget). This can only be done when ZLE is active; normally this will be within a user-defined widget. @@ -702,6 +705,9 @@ appears as if the top-level widget called by the user were still active. With the option tt(-w), tt(WIDGET) and related parameters are set to reflect the widget being executed by the tt(zle) call. +Normally, when var(widget) returns the special parameter tt(LASTWIDGET) will +point to it. This can be inhibited by passing the option tt(-f nolast). + Any further arguments will be passed to the widget; note that as standard argument handling is performed, any general argument list should be preceded by tt(-)tt(-). If it is a shell @@ -726,15 +732,17 @@ enditem() ) enditem() -texinode(Zle Widgets)(Character Highlighting)(Zle Builtins)(Zsh Line Editor) -sect(Widgets) +texinode(Zle Widgets)(User-Defined Widgets)(Zle Builtins)(Zsh Line Editor) +sect(Zle Widgets) cindex(widgets) All actions in the editor are performed by `widgets'. A widget's job is simply to perform some small action. The ZLE commands that key sequences in keymaps are bound to are in fact widgets. Widgets can be user-defined or built in. -The standard widgets built into ZLE are listed in Standard Widgets below. +The standard widgets built into ZLE are listed in +ifzman(the section `Standard Widgets' below)\ +ifnzman(noderef(Standard Widgets)). Other built-in widgets can be defined by other modules (see ifzman(zmanref(zshmodules))\ ifnzman(noderef(Zsh Modules))\ @@ -748,6 +756,8 @@ as shell functions. When the widget is executed, the corresponding shell function is executed, and can perform editing (or other) actions. It is recommended that user-defined widgets should not have names starting with `tt(.)'. + +texinode(User-Defined Widgets)(Standard Widgets)(Zle Widgets)(Zsh Line Editor) sect(User-Defined Widgets) cindex(widgets, user-defined) User-defined widgets, being implemented as shell functions, @@ -974,27 +984,39 @@ of the non-editable parts of the command line in tt(PREDISPLAY) and tt(POSTDISPLAY) are possible, but note that the tt(P) flag is needed for character indexing to include tt(PREDISPLAY). -Each string consists of the following parts: +Each string consists of the following whitespace-separated parts: startitemize() itemiz(Optionally, a `tt(P)' to signify that the start and end offset that follow include any string set by the tt(PREDISPLAY) special parameter; this is needed if the predisplay string itself is to be highlighted. -Whitespace may follow the `tt(P)'.) -itemiz(A start offset in the same units as tt(CURSOR), terminated by -whitespace.) -itemiz(An end offset in the same units as tt(CURSOR), terminated by -whitespace.) +Whitespace between the `tt(P)' and the start offset is optional.) +itemiz(A start offset in the same units as tt(CURSOR).) +itemiz(An end offset in the same units as tt(CURSOR).) itemiz(A highlight specification in the same format as used for contexts in the parameter tt(zle_highlight), see ifnzman(noderef(Character Highlighting))\ ifzman(the section `Character Highlighting' below); -for example, tt(standout) or tt(fg=red,bold)). +for example, tt(standout) or tt(fg=red,bold).) +itemiz(Optionally, a string of the form `tt(memo=)var(token)'. +The var(token) consists of everything between the `tt(=)' and the next +whitespace, comma, NUL, or the end of the string. +The var(token) is preserved verbatim but not parsed in any way. + +Plugins may use this to identify array elements they have added: for example, +a plugin might set var(token) to its (the plugin's) name and then use +`tt(region_highlight=+LPAR() ${region_highlight:#*memo=)var(token)tt(} +RPAR())' +in order to remove array elements it have added. + +(This example uses the `tt(${)var(name)tt(:#)var(pattern)tt(})' array-grepping +syntax described in +ifzman(the section `Parameter Expansion' in zmanref(zshexpn))\ +ifnzman(noderef(Parameter Expansion)).)) enditemize() For example, -example(region_highlight=("P0 20 bold")) +example(region_highlight=("P0 20 bold memo=foobar")) specifies that the first twenty characters of the text including any predisplay string should be highlighted in bold. @@ -1002,6 +1024,14 @@ any predisplay string should be highlighted in bold. Note that the effect of tt(region_highlight) is not saved and disappears as soon as the line is accepted. +Note that zsh 5.8 and older do not support the `tt(memo=)var(token)' field +and may misparse the third (highlight specification) field when a memo +is given. +COMMENT(The syntax `tt(0 20 bold, memo=foobar)' (with an auxiliary comma) +happens to work on both zsh <=5.8 and zsh 5.9-to-be, but that seems to be more of +an accident of implementation than something we should make a first-class-citizen +API promise. It's mentioned in the "Incompatibilities" section of README.) + The final highlighting on the command line depends on both tt(region_highlight) and tt(zle_highlight); see ifzman(the section CHARACTER HIGHLIGHTING below)\ @@ -1184,6 +1214,7 @@ This can be used for detecting switches between the vi command ) enditem() +texinode(Standard Widgets)(Character Highlighting)(User-Defined Widgets)(Zsh Line Editor) sect(Standard Widgets) cindex(widgets, standard) The following is a list of all the standard widgets, @@ -1209,7 +1240,7 @@ menu(Completion) menu(Miscellaneous) menu(Text Objects) endmenu() -texinode(Movement)(History Control)()(Zle Widgets) +texinode(Movement)(History Control)()(Standard Widgets) subsect(Movement) startitem() tindex(vi-backward-blank-word) @@ -1356,7 +1387,7 @@ item(tt(up-line) (unbound) (unbound) (unbound))( Move up a line in the buffer. ) enditem() -texinode(History Control)(Modifying Text)(Movement)(Zle Widgets) +texinode(History Control)(Modifying Text)(Movement)(Standard Widgets) subsect(History Control) startitem() tindex(beginning-of-buffer-or-history) @@ -1704,7 +1735,7 @@ the numeric argument. Zero for both local and imported lines and nonzero for only local lines. ) enditem() -texinode(Modifying Text)(Arguments)(History Control)(Zle Widgets) +texinode(Modifying Text)(Arguments)(History Control)(Standard Widgets) subsect(Modifying Text) startitem() tindex(vi-add-eol) @@ -2030,7 +2061,7 @@ into the kill buffer. Arguably, this is what Y should do in vi, but it isn't what it actually does. ) enditem() -texinode(Arguments)(Completion)(Modifying Text)(Zle Widgets) +texinode(Arguments)(Completion)(Modifying Text)(Standard Widgets) subsect(Arguments) startitem() tindex(digit-argument) @@ -2078,7 +2109,7 @@ example(zle argument-base 16 zle universal-argument) ) enditem() -texinode(Completion)(Miscellaneous)(Arguments)(Zle Widgets) +texinode(Completion)(Miscellaneous)(Arguments)(Standard Widgets) subsect(Completion) startitem() tindex(accept-and-menu-complete) @@ -2153,7 +2184,7 @@ When a previous completion displayed a list below the prompt, this widget can be used to move the prompt below the list. ) enditem() -texinode(Miscellaneous)(Text Objects)(Completion)(Zle Widgets) +texinode(Miscellaneous)(Text Objects)(Completion)(Standard Widgets) subsect(Miscellaneous) startitem() tindex(accept-and-hold) @@ -2200,7 +2231,7 @@ item(tt(beep))( Beep, unless the tt(BEEP) option is unset. ) tindex(bracketed-paste) -item(tt(bracketed-paste))( +item(tt(bracketed-paste) (tt(^[[200~)) (tt(^[[200~)) (tt(^[[200~)))( This widget is invoked when text is pasted to the terminal emulator. It is not intended to be bound to actual keys but instead to the special sequence generated by the terminal emulator when text is pasted. @@ -2551,7 +2582,7 @@ If the last command executed was a digit as part of an argument, continue the argument. Otherwise, execute vi-beginning-of-line. ) enditem() -texinode(Text Objects)()(Miscellaneous)(Zle Widgets) +texinode(Text Objects)()(Miscellaneous)(Standard Widgets) subsect(Text Objects) cindex(text objects) Text objects are commands that can be used to select a block of text @@ -2596,7 +2627,7 @@ argument, multiple words will be selected. ) enditem() -texinode(Character Highlighting)()(Zle Widgets)(Zsh Line Editor) +texinode(Character Highlighting)()(Standard Widgets)(Zsh Line Editor) sect(Character Highlighting) vindex(zle_highlight, setting) diff --git a/Doc/help/alias b/Doc/help/alias index 7fe9e3166..a746af240 100644 --- a/Doc/help/alias +++ b/Doc/help/alias @@ -3,7 +3,13 @@ alias [ {+|-}gmrsL ] [ name[=value] ... ] that value. A trailing space in value causes the next word to be checked for alias expansion. If the -g flag is present, de- fine a global alias; global aliases are expanded even if they do - not occur in command position. + not occur in command position: + + % perldoc --help 2>&1 | grep 'built-in functions' + -f Search Perl built-in functions + % alias -g HG='--help 2>&1 | grep' + % perldoc HG 'built-in functions' + -f Search Perl built-in functions If the -s flag is present, define a suffix alias: if the command word on a command line is in the form `text.name', where text is diff --git a/Doc/help/fc b/Doc/help/fc index 07fa8ae01..5a4b149e2 100644 --- a/Doc/help/fc +++ b/Doc/help/fc @@ -1,4 +1,5 @@ -fc [ -e ename ] [ -LI ] [ -m match ] [ old=new ... ] [ first [ last ] ] +fc [ -e ename ] [ -s ] [ -LI ] [ -m match ] [ old=new ... ] [ first [ +last ] ] fc -l [ -LI ] [ -nrdfEiD ] [ -t timefmt ] [ -m match ] [ old=new ... ] [ first [ last ] ] fc -p [ -a ] [ filename [ histsize [ savehistsize ] ] ] @@ -6,26 +7,27 @@ fc -P fc -ARWI [ filename ] The fc command controls the interactive history mechanism. Note that reading and writing of history options is only performed if - the shell is interactive. Usually this is detected automati- - cally, but it can be forced by setting the interactive option + the shell is interactive. Usually this is detected automati- + cally, but it can be forced by setting the interactive option when starting the shell. - The first two forms of this command select a range of events - from first to last from the history list. The arguments first - and last may be specified as a number or as a string. A nega- - tive number is used as an offset to the current history event + The first two forms of this command select a range of events + from first to last from the history list. The arguments first + and last may be specified as a number or as a string. A nega- + tive number is used as an offset to the current history event number. A string specifies the most recent event beginning with - the given string. All substitutions old=new, if any, are then + the given string. All substitutions old=new, if any, are then performed on the text of the events. - In addition to the number range, + The range of events selected by numbers can be narrowed further + by the following flags. -I restricts to only internal events (not from $HISTFILE) -L restricts to only local events (not from other shells, see SHARE_HISTORY in zshoptions(1) -- note that $HISTFILE is considered local when read at startup) - -m takes the first argument as a pattern (should be quoted) - and only the history events matching this pattern are - considered + -m takes the first argument as a pattern (which should be + quoted) and only the history events matching this pattern + are considered If first is not specified, it will be set to -1 (the most recent event), or to -16 if the -l flag is given. If last is not spec- @@ -43,65 +45,66 @@ fc -ARWI [ filename ] ename is `-', no editor is invoked. When editing is complete, the edited command is executed. - The flag -r reverses the order of the events and the flag -n - suppresses event numbers when listing. + The flag `-s' is equivalent to `-e -'. The flag -r reverses the + order of the events and the flag -n suppresses event numbers + when listing. Also when listing, -d prints timestamps for each event - -f prints full time-date stamps in the US `MM/DD/YY hh:mm' + -f prints full time-date stamps in the US `MM/DD/YY hh:mm' format - -E prints full time-date stamps in the European `dd.mm.yyyy + -E prints full time-date stamps in the European `dd.mm.yyyy hh:mm' format -i prints full time-date stamps in ISO8601 `yyyy-mm-dd hh:mm' format - -t fmt prints time and date stamps in the given format; fmt is - formatted with the strftime function with the zsh exten- - sions described for the %D{string} prompt format in the + -t fmt prints time and date stamps in the given format; fmt is + formatted with the strftime function with the zsh exten- + sions described for the %D{string} prompt format in the section EXPANSION OF PROMPT SEQUENCES in zshmisc(1). The resulting formatted string must be no more than 256 char- acters or will not be printed -D prints elapsed times; may be combined with one of the op- tions above - `fc -p' pushes the current history list onto a stack and + `fc -p' pushes the current history list onto a stack and switches to a new history list. If the -a option is also speci- - fied, this history list will be automatically popped when the - current function scope is exited, which is a much better solu- + fied, this history list will be automatically popped when the + current function scope is exited, which is a much better solu- tion than creating a trap function to call `fc -P' manually. If - no arguments are specified, the history list is left empty, - $HISTFILE is unset, and $HISTSIZE & $SAVEHIST are set to their - default values. If one argument is given, $HISTFILE is set to + no arguments are specified, the history list is left empty, + $HISTFILE is unset, and $HISTSIZE & $SAVEHIST are set to their + default values. If one argument is given, $HISTFILE is set to that filename, $HISTSIZE & $SAVEHIST are left unchanged, and the - history file is read in (if it exists) to initialize the new - list. If a second argument is specified, $HISTSIZE & $SAVEHIST + history file is read in (if it exists) to initialize the new + list. If a second argument is specified, $HISTSIZE & $SAVEHIST are instead set to the single specified numeric value. Finally, if a third argument is specified, $SAVEHIST is set to a separate - value from $HISTSIZE. You are free to change these environment - values for the new history list however you desire in order to + value from $HISTSIZE. You are free to change these environment + values for the new history list however you desire in order to manipulate the new history list. `fc -P' pops the history list back to an older list saved by `fc - -p'. The current list is saved to its $HISTFILE before it is - destroyed (assuming that $HISTFILE and $SAVEHIST are set appro- - priately, of course). The values of $HISTFILE, $HISTSIZE, and - $SAVEHIST are restored to the values they had when `fc -p' was - called. Note that this restoration can conflict with making + -p'. The current list is saved to its $HISTFILE before it is + destroyed (assuming that $HISTFILE and $SAVEHIST are set appro- + priately, of course). The values of $HISTFILE, $HISTSIZE, and + $SAVEHIST are restored to the values they had when `fc -p' was + called. Note that this restoration can conflict with making these variables "local", so your best bet is to avoid local dec- - larations for these variables in functions that use `fc -p'. - The one other guaranteed-safe combination is declaring these - variables to be local at the top of your function and using the - automatic option (-a) with `fc -p'. Finally, note that it is + larations for these variables in functions that use `fc -p'. + The one other guaranteed-safe combination is declaring these + variables to be local at the top of your function and using the + automatic option (-a) with `fc -p'. Finally, note that it is legal to manually pop a push marked for automatic popping if you need to do so before the function exits. - `fc -R' reads the history from the given file, `fc -W' writes - the history out to the given file, and `fc -A' appends the his- - tory out to the given file. If no filename is specified, the - $HISTFILE is assumed. If the -I option is added to -R, only - those events that are not already contained within the internal - history list are added. If the -I option is added to -A or -W, - only those events that are new since last incremental ap- - pend/write to the history file are appended/written. In any + `fc -R' reads the history from the given file, `fc -W' writes + the history out to the given file, and `fc -A' appends the his- + tory out to the given file. If no filename is specified, the + $HISTFILE is assumed. If the -I option is added to -R, only + those events that are not already contained within the internal + history list are added. If the -I option is added to -A or -W, + only those events that are new since last incremental ap- + pend/write to the history file are appended/written. In any case, the created file will have no more than $SAVEHIST entries. history diff --git a/Doc/help/fg b/Doc/help/fg index f52ca1fd5..da8897332 100644 --- a/Doc/help/fg +++ b/Doc/help/fg @@ -1,4 +1,4 @@ fg [ job ... ] job ... - Bring each specified job in turn to the foreground. If no job + Bring each specified job in turn to the foreground. If no job is specified, resume the current job. diff --git a/Doc/help/functions b/Doc/help/functions index 2f1a5dd0b..cadbd0350 100644 --- a/Doc/help/functions +++ b/Doc/help/functions @@ -3,50 +3,92 @@ functions -c oldfn newfn functions -M [-s] mathfn [ min [ max [ shellfn ] ] ] functions -M [ -m pattern ... ] functions +M [ -m ] mathfn ... - Equivalent to typeset -f, with the exception of the -c, -x, -M - and -W options. For functions -u and functions -U, see au- + Equivalent to typeset -f, with the exception of the -c, -x, -M + and -W options. For functions -u and functions -U, see au- toload, which provides additional options. The -x option indicates that any functions output will have each - leading tab for indentation, added by the shell to show syntac- - tic structure, expanded to the given number num of spaces. num + leading tab for indentation, added by the shell to show syntac- + tic structure, expanded to the given number num of spaces. num can also be 0 to suppress all indentation. - The -W option turns on the option 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) un- + The -W option turns on the option 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) un- less the called function also has the -W attribute. - The -c option causes oldfn to be copied to newfn. The copy is - efficiently handled internally by reference counting. If oldfn + The -c option causes oldfn to be copied to newfn. The copy is + efficiently handled internally by reference counting. If oldfn was marked for autoload it is first loaded and if this fails the copy fails. Either function may subsequently be redefined with- - out affecting the other. A typical idiom is that oldfn is the + out affecting the other. A typical idiom is that oldfn is the name of a library shell function which is then redefined to call newfn, thereby installing a modified version of the function. + The -M and +M flags + Use of the -M option may not be combined with any of the options handled by typeset -f. functions -M mathfn defines mathfn as the name of a mathematical - function recognised in all forms of arithmetical expressions; - see the section `Arithmetic Evaluation' in zshmisc(1). By de- - fault mathfn may take any number of comma-separated arguments. - If min is given, it must have exactly min args; if min and max - are both given, it must have at least min and at most max args. + function recognised in all forms of arithmetical expressions; + see the section `Arithmetic Evaluation' in zshmisc(1). By de- + fault mathfn may take any number of comma-separated arguments. + If min is given, it must have exactly min args; if min and max + are both given, it must have at least min and at most max args. max may be -1 to indicate that there is no upper limit. - By default the function is implemented by a shell function of - the same name; if shellfn is specified it gives the name of the - corresponding shell function while mathfn remains the name used - in arithmetical expressions. The name of the function in $0 is - mathfn (not shellfn as would usually be the case), provided the + By default the function is implemented by a shell function of + the same name; if shellfn is specified it gives the name of the + corresponding shell function while mathfn remains the name used + in arithmetical expressions. The name of the function in $0 is + mathfn (not shellfn as would usually be the case), provided the option FUNCTION_ARGZERO is in effect. The positional parameters - in the shell function correspond to the arguments of the mathe- - matical function call. The result of the last arithmetical ex- - pression evaluated inside the shell function (even if it is a - form that normally only returns a status) gives the result of - the mathematical function. + in the shell function correspond to the arguments of the mathe- + matical function call. + + The result of the last arithmetical expression evaluated inside + the shell function gives the result of the mathematical func- + tion. This is not limited to arithmetic substitutions of the + form $((...)), but also includes arithmetical expressions evalu- + ated in any other way, including by the let builtin, by ((...)) + statements, and even by the return builtin and by array sub- + scripts. Therefore, care must be taken not to use syntactical + constructs that perform arithmetic evaluation after evaluating + what is to be the result of the function. For example: + + # WRONG + zmath_cube() { + (( $1 * $1 * $1 )) + return 0 + } + functions -M cube 1 1 zmath_cube + print $(( cube(3) )) + + This will print `0' because of the return. + + Commenting the return out would lead to a different problem: the + ((...)) statement would become the last statement in the func- + tion, so the return status ($?) of the function would be + non-zero (indicating failure) whenever the arithmetic result of + the function would happen to be zero (numerically): + + # WRONG + zmath_cube() { + (( $1 * $1 * $1 )) + } + functions -M cube 1 1 zmath_cube + print $(( cube(0) )) + + Instead, the true builtin can be used: + + # RIGHT + zmath_cube() { + (( $1 * $1 * $1 )) + true + } + functions -M cube 1 1 zmath_cube + print $(( cube(3) )) If the additional option -s is given to functions -M, the argu- ment to the function is a single string: anything between the @@ -54,28 +96,20 @@ functions +M [ -m ] mathfn ... tion as a single argument, even if it includes commas or white space. The minimum and maximum argument specifiers must there- fore be 1 if given. An empty argument list is passed as a - zero-length string. + zero-length string. Thus, the following string function takes a + single argument, including the commas, and prints 11: + + stringfn() { (( $#1 )); true } + functions -Ms stringfn + print $(( stringfn(foo,bar,rod) )) functions -M with no arguments lists all such user-defined func- tions in the same form as a definition. With the additional op- - tion -m and a list of arguments, all functions whose mathfn + tion -m and a list of arguments, all functions whose mathfn matches one of the pattern arguments are listed. function +M removes the list of mathematical functions; with the - additional option -m the arguments are treated as patterns and - all functions whose mathfn matches the pattern are removed. - Note that the shell function implementing the behaviour is not + additional option -m the arguments are treated as patterns and + all functions whose mathfn matches the pattern are removed. + Note that the shell function implementing the behaviour is not removed (regardless of whether its name coincides with mathfn). - - For example, the following prints the cube of 3: - - zmath_cube() { (( $1 * $1 * $1 )) } - functions -M cube 1 1 zmath_cube - print $(( cube(3) )) - - The following string function takes a single argument, including - the commas, so prints 11: - - stringfn() { (( $#1 )) } - functions -Ms stringfn - print $(( stringfn(foo,bar,rod) )) diff --git a/Doc/help/getopts b/Doc/help/getopts index ef73c55c1..bb89d2f2a 100644 --- a/Doc/help/getopts +++ b/Doc/help/getopts @@ -16,15 +16,16 @@ getopts optstring name [ arg ... ] The first option to be examined may be changed by explicitly as- signing to OPTIND. OPTIND has an initial value of 1, and is normally set to 1 upon entry to a shell function and restored - upon exit (this is disabled by the POSIX_BUILTINS option). OP- - TARG is not reset and retains its value from the most recent - call to getopts. If either of OPTIND or OPTARG is explicitly + upon exit. (The POSIX_BUILTINS option disables this, and also + changes the way the value is calculated to match other shells.) + OPTARG is not reset and retains its value from the most recent + call to getopts. If either of OPTIND or OPTARG is explicitly unset, it remains unset, and the index or option argument is not stored. The option itself is still stored in name in this case. A leading `:' in optstring causes getopts to store the letter of - any invalid option in OPTARG, and to set name to `?' for an un- - known option and to `:' when a required argument is missing. - Otherwise, getopts sets name to `?' and prints an error message - when an option is invalid. The exit status is nonzero when + any invalid option in OPTARG, and to set name to `?' for an un- + known option and to `:' when a required argument is missing. + Otherwise, getopts sets name to `?' and prints an error message + when an option is invalid. The exit status is nonzero when there are no more options. diff --git a/Doc/help/hash b/Doc/help/hash index c1dfb49f2..dcbc7fd1c 100644 --- a/Doc/help/hash +++ b/Doc/help/hash @@ -1,47 +1,47 @@ hash [ -Ldfmrv ] [ name[=value] ] ... - hash can be used to directly modify the contents of the command - hash table, and the named directory hash table. Normally one - would modify these tables by modifying one's PATH (for the com- - mand hash table) or by creating appropriate shell parameters - (for the named directory hash table). The choice of hash table - to work on is determined by the -d option; without the option - the command hash table is used, and with the option the named + hash can be used to directly modify the contents of the command + hash table, and the named directory hash table. Normally one + would modify these tables by modifying one's PATH (for the com- + mand hash table) or by creating appropriate shell parameters + (for the named directory hash table). The choice of hash table + to work on is determined by the -d option; without the option + the command hash table is used, and with the option the named directory hash table is used. A command name starting with a / is never hashed, whether by ex- - plicit use of the hash command or otherwise. Such a command is + plicit use of the hash command or otherwise. Such a command is always found by direct look up in the file system. - Given no arguments, and neither the -r or -f options, the se- + Given no arguments, and neither the -r or -f options, the se- lected hash table will be listed in full. - The -r option causes the selected hash table to be emptied. It - will be subsequently rebuilt in the normal fashion. The -f op- - tion causes the selected hash table to be fully rebuilt immedi- - ately. For the command hash table this hashes all the absolute - directories in the PATH, and for the named directory hash table + The -r option causes the selected hash table to be emptied. It + will be subsequently rebuilt in the normal fashion. The -f op- + tion causes the selected hash table to be fully rebuilt immedi- + ately. For the command hash table this hashes all the absolute + directories in the PATH, and for the named directory hash table this adds all users' home directories. These two options cannot be used with any arguments. - The -m option causes the arguments to be taken as patterns - (which should be quoted) and the elements of the hash table - matching those patterns are printed. This is the only way to + The -m option causes the arguments to be taken as patterns + (which should be quoted) and the elements of the hash table + matching those patterns are printed. This is the only way to display a limited selection of hash table elements. - For each name with a corresponding value, put `name' in the se- + For each name with a corresponding value, put `name' in the se- lected hash table, associating it with the pathname `value'. In - the command hash table, this means that whenever `name' is used - as a command argument, the shell will try to execute the file + the command hash table, this means that whenever `name' is used + as a command argument, the shell will try to execute the file given by `value'. In the named directory hash table, this means that `value' may be referred to as `~name'. - For each name with no corresponding value, attempt to add name + For each name with no corresponding value, attempt to add name to the hash table, checking what the appropriate value is in the - normal manner for that hash table. If an appropriate value + normal manner for that hash table. If an appropriate value can't be found, then the hash table will be unchanged. The -v option causes hash table entries to be listed as they are - added by explicit specification. If has no effect if used with + added by explicit specification. If has no effect if used with -f. If the -L flag is present, then each hash table entry is printed diff --git a/Doc/help/jobs b/Doc/help/jobs index 7a602da2b..56f4e34fd 100644 --- a/Doc/help/jobs +++ b/Doc/help/jobs @@ -1,14 +1,33 @@ jobs [ -dlprs ] [ job ... ] jobs -Z string - Lists information about each given job, or all jobs if job is - omitted. The -l flag lists process IDs, and the -p flag lists - process groups. If the -r flag is specified only running jobs + Lists information about each given job, or all jobs if job is + omitted. The -l flag lists process IDs, and the -p flag lists + process groups. If the -r flag is specified only running jobs will be listed and if the -s flag is given only stopped jobs are - shown. If the -d flag is given, the directory from which the - job was started (which may not be the current directory of the + shown. If the -d flag is given, the directory from which the + job was started (which may not be the current directory of the job) will also be shown. - The -Z option replaces the shell's argument and environment - space with the given string, truncated if necessary to fit. + The -Z option replaces the shell's argument and environment + space with the given string, truncated if necessary to fit. This will normally be visible in ps (ps(1)) listings. This fea- ture is typically used by daemons, to indicate their state. + + Full job control is only available in the top-level interactive + shell, not in commands run in the left hand side of pipelines or + within the (...) construct. However, a snapshot of the job + state at that point is taken, so it is still possible to use the + jobs builtin, or any parameter providing job information. This + gives information about the state of jobs at the point the sub- + shell was created. If background processes are created within + the subshell, then instead information about those processes is + provided. + + For example, + + sleep 10 & # Job in background + ( # Shell forks + jobs # Shows information about "sleep 10 &" + sleep 5 & # Process in background (no job control) + jobs # Shows information about "sleep 5 &" + ) diff --git a/Doc/help/kill b/Doc/help/kill index c68d46704..9112ffefe 100644 --- a/Doc/help/kill +++ b/Doc/help/kill @@ -1,24 +1,24 @@ kill [ -s signal_name | -n signal_number | -sig ] job ... kill -l [ sig ... ] - Sends either SIGTERM or the specified signal to the given jobs - or processes. Signals are given by number or by names, with or - without the `SIG' prefix. If the signal being sent is not - `KILL' or `CONT', then the job will be sent a `CONT' signal if - it is stopped. The argument job can be the process ID of a job + Sends either SIGTERM or the specified signal to the given jobs + or processes. Signals are given by number or by names, with or + without the `SIG' prefix. If the signal being sent is not + `KILL' or `CONT', then the job will be sent a `CONT' signal if + it is stopped. The argument job can be the process ID of a job not in the job list. In the second form, kill -l, if sig is not - specified the signal names are listed. Otherwise, for each sig - that is a name, the corresponding signal number is listed. For - each sig that is a signal number or a number representing the - exit status of a process which was terminated or stopped by a + specified the signal names are listed. Otherwise, for each sig + that is a name, the corresponding signal number is listed. For + each sig that is a signal number or a number representing the + exit status of a process which was terminated or stopped by a signal the name of the signal is printed. - On some systems, alternative signal names are allowed for a few + On some systems, alternative signal names are allowed for a few signals. Typical examples are SIGCHLD and SIGCLD or SIGPOLL and SIGIO, assuming they correspond to the same signal number. kill - -l will only list the preferred form, however kill -l alt will - show if the alternative form corresponds to a signal number. + -l will only list the preferred form, however kill -l alt will + show if the alternative form corresponds to a signal number. For example, under Linux kill -l IO and kill -l POLL both output 29, hence kill -IO and kill -POLL have the same effect. - Many systems will allow process IDs to be negative to kill a + Many systems will allow process IDs to be negative to kill a process group or zero to kill the current process group. diff --git a/Doc/help/let b/Doc/help/let index 96f3dc167..2119df55c 100644 --- a/Doc/help/let +++ b/Doc/help/let @@ -1,6 +1,6 @@ let arg ... - Evaluate each arg as an arithmetic expression. See the section - `Arithmetic Evaluation' in zshmisc(1) for a description of - arithmetic expressions. The exit status is 0 if the value of + Evaluate each arg as an arithmetic expression. See the section + `Arithmetic Evaluation' in zshmisc(1) for a description of + arithmetic expressions. The exit status is 0 if the value of the last expression is nonzero, 1 if it is zero, and 2 if an er- ror occurred. diff --git a/Doc/help/limit b/Doc/help/limit index 1e31b122d..342df33da 100644 --- a/Doc/help/limit +++ b/Doc/help/limit @@ -1,17 +1,17 @@ limit [ -hs ] [ resource [ limit ] ] ... - Set or display resource limits. Unless the -s flag is given, - the limit applies only the children of the shell. If -s is - given without other arguments, the resource limits of the cur- - rent shell is set to the previously set resource limits of the + Set or display resource limits. Unless the -s flag is given, + the limit applies only the children of the shell. If -s is + given without other arguments, the resource limits of the cur- + rent shell is set to the previously set resource limits of the children. If limit is not specified, print the current limit placed on re- - source, otherwise set the limit to the specified value. If the + source, otherwise set the limit to the specified value. If the -h flag is given, use hard limits instead of soft limits. If no resource is given, print all limits. When looping over multiple resources, the shell will abort imme- - diately if it detects a badly formed argument. However, if it + diately if it detects a badly formed argument. However, if it fails to set a limit for some other reason it will continue try- ing to set the remaining limits. @@ -20,7 +20,7 @@ limit [ -hs ] [ resource [ limit ] ] ... addressspace Maximum amount of address space used. aiomemorylocked - Maximum amount of memory locked in RAM for AIO opera- + Maximum amount of memory locked in RAM for AIO opera- tions. aiooperations Maximum number of AIO operations. @@ -71,10 +71,10 @@ limit [ -hs ] [ resource [ limit ] ] ... for the resource by the operating system. If argument corresponds to a number which is out of the range of - the resources configured into the shell, the shell will try to + the resources configured into the shell, the shell will try to read or write the limit anyway, and will report an error if this - fails. As the shell does not store such resources internally, - an attempt to set the limit will fail unless the -s option is + fails. As the shell does not store such resources internally, + an attempt to set the limit will fail unless the -s option is present. limit is a number, with an optional scaling factor, as follows: @@ -86,6 +86,6 @@ limit [ -hs ] [ resource [ limit ] ] ... [mm:]ss minutes and seconds - The limit command is not made available by default when the - shell starts in a mode emulating another shell. It can be made + The limit command is not made available by default when the + shell starts in a mode emulating another shell. It can be made available with the command `zmodload -F zsh/rlimits b:limit'. diff --git a/Doc/help/log b/Doc/help/log deleted file mode 100644 index e6627fc5f..000000000 --- a/Doc/help/log +++ /dev/null @@ -1,2 +0,0 @@ -log List all users currently logged in who are affected by the cur- - rent setting of the watch parameter. diff --git a/Doc/help/read b/Doc/help/read index 743389f72..ac14407ea 100644 --- a/Doc/help/read +++ b/Doc/help/read @@ -1,5 +1,5 @@ read [ -rszpqAclneE ] [ -t [ num ] ] [ -k [ num ] ] [ -d delim ] - [ -u n ] [ name[?prompt] ] [ name ... ] + [ -u n ] [ [name][?prompt] ] [ name ... ] Read one line and break it into fields using the characters in $IFS as separators, except as noted below. The first field is assigned to the first name, the second field to the second name, diff --git a/Doc/help/return b/Doc/help/return index d9a53e15b..61a32d48a 100644 --- a/Doc/help/return +++ b/Doc/help/return @@ -1,8 +1,13 @@ return [ n ] Causes a shell function or `.' script to return to the invoking script with the return status specified by an arithmetic expres- - sion n. If n is omitted, the return status is that of the last - command executed. + sion n. For example, the following prints `42': + + () { integer foo=40; return "foo + 2" } + echo $? + + If n is omitted, the return status is that of the last command + executed. If return was executed from a trap in a TRAPNAL function, the effect is different for zero and non-zero return status. With @@ -12,5 +17,5 @@ return [ n ] rupted except that the return status of the trap is retained. Note that the numeric value of the signal which caused the trap is passed as the first argument, so the statement `return - $((128+$1))' will return the same status as if the signal had - not been trapped. + "128+$1"' will return the same status as if the signal had not + been trapped. diff --git a/Doc/help/ttyctl b/Doc/help/ttyctl index 6736658f2..937fdf913 100644 --- a/Doc/help/ttyctl +++ b/Doc/help/ttyctl @@ -18,4 +18,5 @@ ttyctl [ -fu ] command line are preserved. Strings of commands run between editing the command line will see a consistent tty state. See also the shell variable STTY for a means of initialising the tty - before running external commands. + before running external commands and/or freezing the tty around + a single command. diff --git a/Doc/help/typeset b/Doc/help/typeset index 31f505fb7..852b39153 100644 --- a/Doc/help/typeset +++ b/Doc/help/typeset @@ -5,16 +5,21 @@ typeset -T [ {+|-}Uglrux ] [ {+|-}LRZp [ n ] ] typeset -f [ {+|-}TUkmtuz ] [ + ] [ name ... ] Set or display attributes and values for shell parameters. - Except as noted below for control flags that change the behav- - ior, a parameter is created for each name that does not already - refer to one. When inside a function, a new parameter is cre- - ated for every name (even those that already exist), and is un- - set again when the function completes. See `Local Parameters' - in zshparam(1). The same rules apply to special shell parame- + Except as noted below for control flags that change the behav- + ior, a parameter is created for each name that does not already + refer to one. When inside a function, a new parameter is cre- + ated for every name (even those that already exist), and is un- + set again when the function completes. See `Local Parameters' + in zshparam(1). The same rules apply to special shell parame- ters, which retain their special attributes when made local. - For each name=value assignment, the parameter name is set to - value. + For each name=value assignment, the parameter name is set to + value. If the assignment is omitted and name does not refer to + an existing parameter, a new parameter is intialized to empty + string, zero, or empty array (as appropriate), unless the shell + option TYPESET_TO_UNSET is set. When that option is set, the + parameter attributes are recorded but the parameter remains un- + set. If the shell option TYPESET_SILENT is not set, for each remain- ing name that refers to a parameter that is already set, the @@ -88,7 +93,7 @@ typeset -f [ {+|-}TUkmtuz ] [ + ] [ name ... ] to typeset after expansion. Hence it is not possible to assign to multiple arrays by this means. - Note that each interface to any of the commands my be disabled + Note that each interface to any of the commands may be disabled separately. For example, `disable -r typeset' disables the re- served word interface to typeset, exposing the builtin inter- face, while `disable typeset' disables the builtin. Note that @@ -395,16 +400,16 @@ declare Same as typeset. float [ {+|-}Hghlprtux ] [ {+|-}EFLRZ [ n ] ] [ name[=value] ... ] - Equivalent to typeset -E, except that options irrelevant to + Equivalent to typeset -E, except that options irrelevant to floating point numbers are not permitted. integer [ {+|-}Hghlprtux ] [ {+|-}LRZi [ n ] ] [ name[=value] ... ] - Equivalent to typeset -i, except that options irrelevant to in- + Equivalent to typeset -i, except that options irrelevant to in- tegers are not permitted. local [ {+|-}AHUahlprtux ] [ {+|-}EFLRZi [ n ] ] [ name[=value] ... ] Same as typeset, except that the options -g, and -f are not per- - mitted. In this case the -x option does not force the use of + mitted. In this case the -x option does not force the use of -g, i.e. exported variables will be local to functions. readonly diff --git a/Doc/help/umask b/Doc/help/umask index ed29a4361..a27f722c8 100644 --- a/Doc/help/umask +++ b/Doc/help/umask @@ -1,8 +1,8 @@ umask [ -S ] [ mask ] The umask is set to mask. mask can be either an octal number or - a symbolic value as described in chmod(1). If mask is omitted, - the current value is printed. The -S option causes the mask to - be printed as a symbolic value. Otherwise, the mask is printed - as an octal number. Note that in the symbolic form the permis- - sions you specify are those which are to be allowed (not denied) - to the users specified. + a symbolic value as described in the chmod(1) man page. If mask + is omitted, the current value is printed. The -S option causes + the mask to be printed as a symbolic value. Otherwise, the mask + is printed as an octal number. Note that in the symbolic form + the permissions you specify are those which are to be allowed + (not denied) to the users specified. diff --git a/Doc/version.yo b/Doc/version.yo index 970c93892..ed5d73cbc 100644 --- a/Doc/version.yo +++ b/Doc/version.yo @@ -1,6 +1,6 @@ IFDEF(INCWSLEVEL)(INCWSLEVEL())(STARTDEF()) -def(version)(0)(5.8.1) -def(date)(0)(February 12, 2022) +def(version)(0)(5.8.1.2-test) +def(date)(0)(April 9, 2022) def(zshenv)(0)(/etc/zshenv) def(zprofile)(0)(/etc/zprofile) def(zshrc)(0)(/etc/zshrc) @@ -1,4 +1,4 @@ -.TH "ZSH" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSH" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zsh \- the Z shell .\" Yodl file: Zsh/intro.yo @@ -48,19 +48,19 @@ login shell and as a shell script command processor\&. Of the standard shells, zsh most closely resembles \fBksh\fP but includes many enhancements\&. It does not provide compatibility with POSIX or other shells in its default operating mode: see -the section Compatibility below\&. +the section `Compatibility\&' below\&. .PP Zsh has command line editing, builtin spelling correction, programmable command completion, shell functions (with autoloading), a history mechanism, and a host of other features\&. .\" Yodl file: Zsh/metafaq.yo .SH "AUTHOR" -Zsh was originally written by Paul Falstad \fB<pf@zsh\&.org>\fP\&. -Zsh is now maintained by the members of the zsh\-workers mailing -list \fB<zsh\-workers@zsh\&.org>\fP\&. The development is currently -coordinated by Peter Stephenson \fB<pws@zsh\&.org>\fP\&. The coordinator -can be contacted at \fB<coordinator@zsh\&.org>\fP, but matters relating to -the code should generally go to the mailing list\&. +Zsh was originally written by Paul Falstad\&. Zsh is now maintained by +the members of the zsh\-workers mailing list \fB<zsh\-workers@zsh\&.org>\fP\&. +The development is currently coordinated by Peter Stephenson +\fB<pws@zsh\&.org>\fP\&. The coordinator can be contacted at +\fB<coordinator@zsh\&.org>\fP, but matters relating to the code should +generally go to the mailing list\&. .SH "AVAILABILITY" Zsh is available from the following HTTP and anonymous FTP site\&. .PP @@ -68,15 +68,14 @@ Zsh is available from the following HTTP and anonymous FTP site\&. \fBftp://ftp\&.zsh\&.org/pub/\fP \fBhttps://www\&.zsh\&.org/pub/\fP .fi -) .PP The up\-to\-date source code is available via Git from Sourceforge\&. See \fBhttps://sourceforge\&.net/projects/zsh/\fP for details\&. A summary of instructions for the archive can be found at -\fBhttp://zsh\&.sourceforge\&.net/\fP\&. +\fBhttps://zsh\&.sourceforge\&.io/\fP\&. .PP .SH "MAILING LISTS" -Zsh has 3 mailing lists: +Zsh has several mailing lists: .PP .PD 0 .TP @@ -90,6 +89,14 @@ User discussions\&. .TP \fB<zsh\-workers@zsh\&.org>\fP Hacking, development, bug reports and patches\&. +.TP +\fB<zsh\-security@zsh\&.org>\fP +Private mailing list (the general public cannot subscribe to it) for discussing +bug reports with security implications, i\&.e\&., potential vulnerabilities\&. +.RS +.PP +If you find a security problem in zsh itself, please mail this address\&. +.RE .PP To subscribe or unsubscribe, send mail to the associated administrative address for the mailing list\&. @@ -116,30 +123,28 @@ All submissions to \fBzsh\-announce\fP are automatically forwarded to forwarded to \fBzsh\-workers\fP\&. .PP If you have problems subscribing/unsubscribing to any of the mailing -lists, send mail to \fB<listmaster@zsh\&.org>\fP\&. The mailing lists are -maintained by Karsten Thygesen \fB<karthy@kom\&.auc\&.dk>\fP\&. +lists, send mail to \fB<listmaster@zsh\&.org>\fP\&. .PP The mailing lists are archived; the archives can be accessed via the administrative addresses listed above\&. There is also a hypertext -archive, maintained by Geoff Wing \fB<gcw@zsh\&.org>\fP, available at +archive available at \fBhttps://www\&.zsh\&.org/mla/\fP\&. .SH "THE ZSH FAQ" Zsh has a list of Frequently Asked Questions (FAQ), maintained by Peter Stephenson \fB<pws@zsh\&.org>\fP\&. It is regularly posted to the newsgroup \fBcomp\&.unix\&.shell\fP and the \fBzsh\-announce\fP mailing list\&. The latest version can be found at any of the Zsh FTP sites, or at -\fBhttp://www\&.zsh\&.org/FAQ/\fP\&. The contact address for FAQ\-related matters +\fBhttps://www\&.zsh\&.org/FAQ/\fP\&. The contact address for FAQ\-related matters is \fB<faqmaster@zsh\&.org>\fP\&. .SH "THE ZSH WEB PAGE" -Zsh has a web page which is located at \fBhttps://www\&.zsh\&.org/\fP\&. This is -maintained by Karsten Thygesen \fB<karthy@zsh\&.org>\fP, of SunSITE Denmark\&. +Zsh has a web page which is located at \fBhttps://www\&.zsh\&.org/\fP\&. The contact address for web\-related matters is \fB<webmaster@zsh\&.org>\fP\&. .SH "THE ZSH USERGUIDE" A userguide is currently in preparation\&. It is intended to complement the manual, with explanations and hints on issues where the manual can be cabbalistic, hierographic, or downright mystifying (for example, the word `hierographic\&' does not exist)\&. It can be viewed in its current state at -\fBhttp://zsh\&.sourceforge\&.net/Guide/\fP\&. At the time of writing, chapters +\fBhttps://zsh\&.sourceforge\&.io/Guide/\fP\&. At the time of writing, chapters dealing with startup files and their contents and the new completion system were essentially complete\&. .\" Yodl file: Zsh/invoke.yo @@ -274,8 +279,7 @@ parameters are not special and not initialized by the shell: \fBPROMPT3\fP, \fBPROMPT4\fP, \fBpsvar\fP, -\fBstatus\fP, -\fBwatch\fP\&. +\fBstatus\fP\&. .PP The usual zsh startup/shutdown scripts are not executed\&. Login shells source \fB/etc/profile\fP followed by \fB$HOME/\&.profile\fP\&. If the @@ -317,6 +321,12 @@ Also, the and \fBSINGLE_LINE_ZLE\fP options are set if zsh is invoked as \fBksh\fP\&. +.PP +Please note that, whilst reasonable efforts are taken to address +incompatibilities when they arise, zsh does not guarantee complete +emulation of other shells, nor POSIX compliance\&. For more information on +the differences between zsh and other shells, please refer to chapter 2 +of the shell FAQ, \fBhttps://www\&.zsh\&.org/FAQ/\fP\&. .\" Yodl file: Zsh/restricted.yo .SH "RESTRICTED SHELL" When the basename of the command used to invoke zsh starts with the letter diff --git a/Doc/zsh.texi b/Doc/zsh.texi index 5d96e06cb..4509b7c92 100644 --- a/Doc/zsh.texi +++ b/Doc/zsh.texi @@ -27,8 +27,8 @@ @end iftex @titlepage @title The Z Shell Manual -@subtitle Version 5.8.1 -@subtitle Updated February 12, 2022 +@subtitle Version 5.8.1.2-test +@subtitle Updated April 9, 2022 @author Original documentation by Paul Falstad @page This is a texinfo version of the documentation for the Z Shell, originally by @@ -63,7 +63,7 @@ POSIX shells, but its default mode is not POSIX compatible, either. @noindent @cindex version -Version 5.8.1, last updated February 12, 2022. +Version 5.8.1.2-test, last updated April 9, 2022. @end ifinfo @menu @@ -179,6 +179,8 @@ Zsh Line Editor * Keymaps:: * Zle Builtins:: * Zle Widgets:: +* User-Defined Widgets:: +* Standard Widgets:: * Character Highlighting:: @noindent @@ -246,6 +248,7 @@ Zsh Modules * The zsh/net/tcp Module:: * The zsh/termcap Module:: * The zsh/terminfo Module:: +* The zsh/watch Module:: * The zsh/zftp Module:: * The zsh/zle Module:: * The zsh/zleparameter Module:: @@ -327,7 +330,7 @@ produce a nicely formatted printed manual. An HTML version of this manual is available at the Zsh web site via: @noindent -@t{@uref{http://zsh.sourceforge.net/Doc/}}. +@t{@uref{https://zsh.sourceforge.io/Doc/}}. @noindent (The HTML version is produced with @cite{texi2html}, which may be obtained @@ -375,12 +378,12 @@ mechanism, and a host of other features. @section Author @noindent @cindex author -Zsh was originally written by Paul Falstad @t{<pf@@zsh.org>}. -Zsh is now maintained by the members of the zsh-workers mailing -list @t{<zsh-workers@@zsh.org>}. The development is currently -coordinated by Peter Stephenson @t{<pws@@zsh.org>}. The coordinator -can be contacted at @t{<coordinator@@zsh.org>}, but matters relating to -the code should generally go to the mailing list. +Zsh was originally written by Paul Falstad. Zsh is now maintained by +the members of the zsh-workers mailing list @t{<zsh-workers@@zsh.org>}. +The development is currently coordinated by Peter Stephenson +@t{<pws@@zsh.org>}. The coordinator can be contacted at +@t{<coordinator@@zsh.org>}, but matters relating to the code should +generally go to the mailing list. @node Availability, Mailing Lists, Author, Introduction @section Availability @@ -393,13 +396,12 @@ Zsh is available from the following HTTP and anonymous FTP site. @cindex availability of zsh @t{@uref{ftp://ftp.zsh.org/pub/}}@* @t{@uref{https://www.zsh.org/pub/}} -) @noindent The up-to-date source code is available via Git from Sourceforge. See @t{@uref{https://sourceforge.net/projects/zsh/}} for details. A summary of instructions for the archive can be found at -@t{@uref{http://zsh.sourceforge.net/}}. +@t{@uref{https://zsh.sourceforge.io/}}. @noindent @node Mailing Lists, The Zsh FAQ, Availability, Introduction @@ -407,7 +409,7 @@ instructions for the archive can be found at @section Mailing Lists @noindent @cindex mailing lists -Zsh has 3 mailing lists: +Zsh has several mailing lists: @noindent @table @asis @@ -421,6 +423,13 @@ User discussions. @item @t{<zsh-workers@@zsh.org>} Hacking, development, bug reports and patches. +@item @t{<zsh-security@@zsh.org>} +Private mailing list (the general public cannot subscribe to it) for discussing +bug reports with security implications, i.e., potential vulnerabilities. + +@noindent +If you find a security problem in zsh itself, please mail this address. + @end table @noindent @@ -448,13 +457,12 @@ forwarded to @cite{zsh-workers}. @noindent If you have problems subscribing/unsubscribing to any of the mailing -lists, send mail to @t{<listmaster@@zsh.org>}. The mailing lists are -maintained by Karsten Thygesen @t{<karthy@@kom.auc.dk>}. +lists, send mail to @t{<listmaster@@zsh.org>}. @noindent The mailing lists are archived; the archives can be accessed via the administrative addresses listed above. There is also a hypertext -archive, maintained by Geoff Wing @t{<gcw@@zsh.org>}, available at +archive available at @t{@uref{https://www.zsh.org/mla/}}. @node The Zsh FAQ, The Zsh Web Page, Mailing Lists, Introduction @@ -464,14 +472,13 @@ Zsh has a list of Frequently Asked Questions (FAQ), maintained by Peter Stephenson @t{<pws@@zsh.org>}. It is regularly posted to the newsgroup @cite{comp.unix.shell} and the @cite{zsh-announce} mailing list. The latest version can be found at any of the Zsh FTP sites, or at -@t{@uref{http://www.zsh.org/FAQ/}}. The contact address for FAQ-related matters +@t{@uref{https://www.zsh.org/FAQ/}}. The contact address for FAQ-related matters is @t{<faqmaster@@zsh.org>}. @node The Zsh Web Page, The Zsh Userguide, The Zsh FAQ, Introduction @section The Zsh Web Page @noindent -Zsh has a web page which is located at @t{@uref{https://www.zsh.org/}}. This is -maintained by Karsten Thygesen @t{<karthy@@zsh.org>}, of SunSITE Denmark. +Zsh has a web page which is located at @t{@uref{https://www.zsh.org/}}. The contact address for web-related matters is @t{<webmaster@@zsh.org>}. @node The Zsh Userguide, See Also, The Zsh Web Page, Introduction @@ -481,7 +488,7 @@ A userguide is currently in preparation. It is intended to complement the manual, with explanations and hints on issues where the manual can be cabbalistic, hierographic, or downright mystifying (for example, the word `hierographic' does not exist). It can be viewed in its current state at -@t{@uref{http://zsh.sourceforge.net/Guide/}}. At the time of writing, chapters +@t{@uref{https://zsh.sourceforge.io/Guide/}}. At the time of writing, chapters dealing with startup files and their contents and the new completion system were essentially complete. @c (avoiding a yodl bug) @@ -490,12 +497,12 @@ were essentially complete. @section See Also @noindent -man page sh(1), -man page csh(1), -man page tcsh(1), -man page rc(1), -man page bash(1), -man page ksh(1) +sh(1), +csh(1), +tcsh(1), +rc(1), +bash(1), +ksh(1) @noindent @cite{IEEE Standard for information Technology - @@ -564,7 +571,7 @@ The shell now supports the UTF-8 character set (and also others if supported by the operating system). This is (mostly) handled transparently by the shell, but the degree of support in terminal emulators is variable. There is some discussion of this in the shell FAQ, -@t{@uref{http://www.zsh.org/FAQ/}}. Note in particular that for combining +@t{@uref{https://www.zsh.org/FAQ/}}. Note in particular that for combining characters to be handled the option @t{COMBINING_CHARS} needs to be set. Because the shell is now more sensitive to the definition of the character set, note that if you are upgrading from an older version of @@ -911,8 +918,7 @@ parameters are not special and not initialized by the shell: @t{PROMPT3}, @t{PROMPT4}, @t{psvar}, -@t{status}, -@t{watch}. +@t{status}. @noindent @vindex ENV, use of @@ -957,6 +963,13 @@ Also, the and @t{SINGLE_LINE_ZLE} options are set if zsh is invoked as @t{ksh}. + +@noindent +Please note that, whilst reasonable efforts are taken to address +incompatibilities when they arise, zsh does not guarantee complete +emulation of other shells, nor POSIX compliance. For more information on +the differences between zsh and other shells, please refer to chapter 2 +of the shell FAQ, @t{@uref{https://www.zsh.org/FAQ/}}. @c (avoiding a yodl bug) @c Yodl file: Zsh/restricted.yo @node Restricted Shell, , Compatibility, Invocation @@ -1489,7 +1502,9 @@ for each selection until a break or end-of-file is encountered. @cindex subshell @item @t{(} @var{list} @t{)} Execute @var{list} in a subshell. Traps set by the @t{trap} builtin -are reset to their default values while executing @var{list}. +are reset to their default values while executing @var{list}; an +exception is that ignored signals will continue to be ignored +if the option @t{POSIXTRAPS} is set. @item @t{@{} @var{list} @t{@}} Execute @var{list}. @@ -1566,7 +1581,7 @@ execution of @var{always-list}, just like @t{break} and @t{continue}. @findex function -@item @t{function} @var{word} ... [ @t{()} ] [ @var{term} ] @t{@{} @var{list} @t{@}} +@item @t{function} [ @t{-T} ] @var{word} ... [ @t{()} ] [ @var{term} ] @t{@{} @var{list} @t{@}} @itemx @var{word} ... @t{()} [ @var{term} ] @t{@{} @var{list} @t{@}} @itemx @var{word} ... @t{()} [ @var{term} ] @var{command} where @var{term} is one or more newline or @t{;}. @@ -1577,6 +1592,18 @@ The body of the function is the @var{list} between the @t{@{} and @t{@}}. See @ref{Functions}. @noindent +The options of @t{function} have the following meanings: + +@noindent +@table @asis +@item -T +Enable tracing for this function, as though with @t{functions -T}. See the +documentation of the @t{-f} option to the @t{typeset} builtin, in +@ref{Shell Builtin Commands}. + +@end table + +@noindent If the option @t{SH_GLOB} is set for compatibility with other shells, then whitespace may appear between the left and right parentheses when there is a single @var{word}; otherwise, the parentheses will be treated as @@ -1635,6 +1662,8 @@ else the end of the test will not be recognized. For the @t{for}, @t{repeat}, @t{case} and @t{select} commands no such special form for the arguments is necessary, but the other condition (the special form of @var{sublist} or use of the @t{SHORT_LOOPS} option) still applies. +The @t{SHORT_REPEAT} option is available to enable the short version only +for the @t{repeat} command. @noindent @table @asis @@ -1823,6 +1852,13 @@ position (if it could be the first word of a simple command), or if the alias is global. If the replacement text ends with a space, the next word in the shell input is always eligible for purposes of alias expansion. + +@noindent +It is an error for the function name, @var{word}, in the sh-compatible function +definition syntax `@var{word} @t{()} ...' to be a word that resulted +from alias expansion, unless the @t{ALIAS_FUNC_DEF} option is set. + +@noindent @findex alias, use of @cindex aliases, global An alias is defined using the @t{alias} builtin; global aliases @@ -1860,6 +1896,19 @@ nothing to prevent an alias being defined for the quoted form such as @t{\foo} as well. @noindent +In particular, note that quoting must be used when using @t{unalias} to remove +global aliases: + +@noindent +@example +% alias -g foo=bar +% unalias foo +unalias: no such hash table element: bar +% unalias \foo +% +@end example + +@noindent When @t{POSIX_ALIASES} is set, only plain unquoted strings are eligible for aliasing. The @t{alias} builtin does not reject ineligible aliases, but they are not expanded. @@ -1923,35 +1972,6 @@ or `@t{.}'. Consequently, use of functions rather than aliases is recommended in non-interactive code. @noindent -Note also the unhelpful interaction of aliases and function definitions: - -@noindent -@example -alias func='noglob func' -func() @{ - echo Do something with $* -@} -@end example - -@noindent -Because aliases are expanded in function definitions, this causes the -following command to be executed: - -@noindent -@example -noglob func() @{ - echo Do something with $* -@} -@end example - -@noindent -which defines @t{noglob} as well as @t{func} as functions with the -body given. To avoid this, either quote the name @t{func} or use the -alternative function definition form `@t{function func}'. Ensuring the -alias is defined after the function works but is problematic if the -code fragment might be re-executed. - -@noindent @node Quoting, , Aliasing, Shell Grammar @section Quoting @@ -2083,12 +2103,13 @@ tabs are stripped from @var{word} and from the document. Perform shell expansion on @var{word} and pass the result to standard input. This is known as a @emph{here-string}. Compare the use of @var{word} in here-documents above, where @var{word} -does not undergo shell expansion. +does not undergo shell expansion. The result will have a trailing newline +after it. @item @t{<&} @var{number} @itemx @t{>&} @var{number} The standard input/output is duplicated from file descriptor -@var{number} (see man page dup2(2)). +@var{number} (see dup2(2)). @item @t{<& -} @itemx @t{>& -} @@ -2462,9 +2483,24 @@ a shell builtin by that name, the builtin is invoked. @noindent @vindex path, use of Otherwise, the shell searches each element of @t{$path} for a -directory containing an executable file by that name. If the -search is unsuccessful, the shell prints an error message and returns -a nonzero exit status. +directory containing an executable file by that name. + +@noindent +If execution fails: an error message is printed, and one of the +following values is returned. + +@noindent +@table @asis +@item 127 +The search was unsuccessful. The error message is +`@t{command not found:} @var{cmd}'. +@item 126 +The executable file has insufficient permissions, is a +directory or special file, or is not a script and is in a format +unrecognized by the operating system. The exact conditions and error +message are operating system-dependent; see +execve(2). +@end table @noindent If execution fails because the file is not in executable format, @@ -2479,14 +2515,9 @@ not handle this executable format in the kernel. If no external command is found but a function @t{command_not_found_handler} exists the shell executes this function with all command line arguments. The return status of the function becomes the -status of the command. If the function wishes to mimic the -behaviour of the shell when the command is not found, it should -print the message `@t{command not found:} @var{cmd}' to standard error -and return status 127. Note that the handler is executed in a +status of the command. Note that the handler is executed in a subshell forked to execute an external command, hence changes to directories, shell parameters, etc. have no effect on the main shell. - -@noindent @c (avoiding a yodl bug) @c Yodl file: Zsh/func.yo @node Functions, Jobs & Signals, Command Execution, Top @@ -2757,13 +2788,14 @@ Certain functions, if defined, have special meaning to the shell. For the functions below, it is possible to define an array that has the same name as the function with `@t{_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 +in the same context and with the same arguments and same initial value of @t{$?} +as the basic function. For example, if @t{$chpwd_functions} is an array containing the values `@t{mychpwd}', `@t{chpwd_save_dirstack}', then the shell attempts to execute the functions `@t{chpwd}', `@t{mychpwd}' and `@t{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 +elsewhere as a @emph{hook function}. An error in any function causes subsequent functions not to be run. Note further that an error in a @t{precmd} hook causes an immediately following @t{periodic} function not to run (though it may run at the next opportunity). @@ -2830,7 +2862,7 @@ value is taken. @noindent A hook function may call `@t{fc -p} @var{...}' to switch the history -context so that the history is saved in a different file from the +context so that the history is saved in a different file from that in the global @t{HISTFILE} parameter. This is handled specially: the history context is automatically restored after the processing of the history line is finished. @@ -3123,7 +3155,7 @@ a @t{SIGHUP} signal, if the @t{HUP} option is set. @cindex disowning jobs @findex disown, use of To avoid having the shell terminate the running jobs, either -use the @cite{nohup} command (see man page nohup(1)) +use the nohup(1) command or the @t{disown} builtin. @section Signals @@ -3148,7 +3180,7 @@ exit without waiting. Examples of such asynchronous jobs are process substitution, see @ref{Process Substitution}, and the handler processes for multios, see -the section Multios in @ref{Redirection}. +the section @emph{Multios} in @ref{Redirection}. @c (avoiding a yodl bug) @c Yodl file: Zsh/arith.yo @node Arithmetic Evaluation, Conditional Expressions, Jobs & Signals, Top @@ -3173,7 +3205,7 @@ The @t{let} builtin command takes arithmetic expressions as arguments; each is evaluated separately. Since many of the arithmetic operators, as well as spaces, require quoting, an alternative form is provided: for any command which begins with a `@t{((}', all the characters until a -matching `@t{))}' are treated as a quoted expression and +matching `@t{))}' are treated as a double-quoted expression and arithmetic expansion performed as for an argument of @t{let}. More precisely, `@t{((}@var{...}@t{))}' is equivalent to `@t{let "}@var{...}@t{"}'. The return status is 0 if the arithmetic value @@ -3983,7 +4015,7 @@ The date in @var{mm}@t{/}@var{dd}@t{/}@var{yy} format. @item @t{%D@{}@var{string}@t{@}} @var{string} is formatted using the @t{strftime} function. -See man page strftime(3) for more details. Various zsh +See strftime(3) for more details. Various zsh extensions provide numbers with no leading zero or space if the number is a single digit: @@ -4322,7 +4354,7 @@ you may see in your prompt (see A history expansion begins with the first character of the @t{histchars} parameter, which is `@t{!}' by default, and may occur anywhere on the command line, including inside double quotes (but not inside single quotes -@t{'...'} or C-style quotes @t{$'...'} nor when escaped with a backslash). +@t{'...'} or C-style quotes @t{$'...'} nor when escaped with a backslash). @noindent The first character is followed by an optional event designator @@ -4553,8 +4585,10 @@ expansion. @item @t{P} Turn a file name into an absolute path, like @t{realpath(3)}. -The resulting path will be absolute, have neither `@t{.}' nor `@t{..}' components, -and refer to the same directory entry as the input filename. +The resulting path will be absolute, +will refer to the same directory entry as the input filename, +and none of its components will be symbolic links or equal to +`@t{.}' or `@t{..}'. @noindent Unlike @t{realpath(3)}, non-existent trailing components are @@ -4770,7 +4804,7 @@ If @t{=(}@var{...}@t{)} is used instead of then the file passed as an argument will be the name of a temporary file containing the output of the @var{list} process. This may be used instead of the @t{<} -form for a program that expects to lseek (see man page lseek(2)) +form for a program that expects to lseek (see lseek(2)) on the input file. @noindent @@ -4785,7 +4819,7 @@ contents. @noindent The @t{=} form is useful as both the @t{/dev/fd} and the named pipe -implementation of @t{<(}@var{...}@t{)} have drawbacks. In +implementation of @t{<(}@var{...}@t{)} have drawbacks. In the former case, some programmes may automatically close the file descriptor in question before examining the file on the command line, particularly if this is necessary for security reasons such as when the @@ -4795,7 +4829,7 @@ from or write to the pipe will (in a typical implementation, different operating systems may have different behaviour) block for ever and have to be killed explicitly. In both cases, the shell actually supplies the information using a pipe, so that programmes that expect to lseek -(see man page lseek(2)) on the file will not work. +(see lseek(2)) on the file will not work. @noindent Also note that the previous example can be more compactly and @@ -5229,6 +5263,7 @@ of the string @t{$-} and the array @t{$*} respectively. If the @t{#} to be treated in this fashion. @item @t{$@{^}@var{spec}@t{@}} +@itemx @t{$@{^^}@var{spec}@t{@}} @pindex RC_EXPAND_PARAM, toggle @cindex array expansion style, rc @cindex rc, array expansion style @@ -5253,6 +5288,7 @@ happening later. If word splitting is also in effect the elements. @item @t{$@{=}@var{spec}@t{@}} +@itemx @t{$@{==}@var{spec}@t{@}} @pindex SH_WORD_SPLIT, toggle @cindex field splitting, sh style, parameter @cindex sh, field splitting style, parameter @@ -5270,6 +5306,7 @@ of @var{spec} @emph{before} the assignment to @var{name} is performed. This affects the result of array assignments with the @t{A} flag. @item @t{$@{~}@var{spec}@t{@}} +@itemx @t{$@{~~}@var{spec}@t{@}} @pindex GLOB_SUBST, toggle Turn on the @t{GLOB_SUBST} option for the evaluation of @var{spec}; if the `@t{~}' is doubled, turn it off. When this option is @@ -5329,9 +5366,10 @@ following flags are supported: @noindent @table @asis @item @t{#} -Evaluate the resulting words as numeric expressions and output the -characters corresponding to the resulting integer. Note that this form is -entirely distinct from use of the @t{#} without parentheses. +Evaluate the resulting words as numeric expressions and interpret +these as character codes. Output the corresponding characters. Note +that this form is entirely distinct from use of the @t{#} without +parentheses. @noindent If the @t{MULTIBYTE} option is set and the number is greater than 127 @@ -5339,7 +5377,7 @@ If the @t{MULTIBYTE} option is set and the number is greater than 127 @item @t{%} Expand all @t{%} escapes in the resulting words in the same way as in -prompts (see +prompts (see @ref{Prompt Expansion}). If this flag is given twice, full prompt expansion is done on the resulting words, depending on the setting of the @t{PROMPT_PERCENT}, @t{PROMPT_SUBST} and @t{PROMPT_BANG} @@ -5468,22 +5506,31 @@ Convert all letters in the result to lower case. @item @t{n} Sort decimal integers numerically; if the first differing characters of two test strings are not digits, sorting -is lexical. Integers with more initial zeroes -are sorted before those with fewer or none. Hence the array `@t{foo1 foo02 +is lexical. `@t{+}' and `@t{-}' are not treated specially; they are treated as +any other non-digit. Integers with more initial zeroes +are sorted before those with fewer or none. Hence the array `@t{foo+24 foo1 foo02 foo2 foo3 foo20 foo23}' is sorted into the order shown. May be combined with `@t{i}' or `@t{O}'. +@item @t{-} +As @t{n}, but a leading minus sign indicates a negative decimal +integer. A leading minus sign not followed by an integer does not trigger +numeric sorting. +Note that `@t{+}' signs are not handled specially (this may change in the +future). + @item @t{o} Sort the resulting words in ascending order; if this appears on its own the sorting is lexical and case-sensitive (unless the locale renders it case-insensitive). Sorting in ascending order is the default for other forms of sorting, so this is ignored if combined -with `@t{a}', `@t{i}' or `@t{n}'. +with `@t{a}', `@t{i}', `@t{n}' or `@t{-}'. @item @t{O} Sort the resulting words in descending order; `@t{O}' without `@t{a}', -`@t{i}' or `@t{n}' sorts in reverse lexical order. May be combined -with `@t{a}', `@t{i}' or `@t{n}' to reverse the order of sorting. +`@t{i}', `@t{n}' or `@t{-}' sorts in reverse lexical order. May be +combined with `@t{a}', `@t{i}', `@t{n}' or `@t{-}' to reverse the +order of sorting. @item @t{P} This forces the value of the parameter @var{name} to be interpreted as a @@ -5573,6 +5620,11 @@ for readonly parameters @item @t{tag} for tagged parameters +@item @t{tied} +for parameters tied to another parameter in the manner of @t{PATH} +(colon-separated list) and @t{path} (array), whether these are +special parameters or user-defined with `@t{typeset -T}' + @item @t{export} for exported parameters @@ -5784,16 +5836,31 @@ i.e. @t{"$@{(@@s.:.)line@}"}. @item @t{Z:}@var{opts}@t{:} As @t{z} but takes a combination of option letters between a following pair of delimiter characters. With no options the effect is identical -to @t{z}. @t{(Z+c+)} +to @t{z}. The following options are available: + +@noindent +@table @asis +@item @t{(Z+c+)} causes comments to be parsed as a string and retained; any field in the resulting array beginning with an unquoted comment character is a -comment. @t{(Z+C+)} causes comments to be parsed +comment. + +@item @t{(Z+C+)} +causes comments to be parsed and removed. The rule for comments is standard: anything between a word starting with the third character of @t{$HISTCHARS}, default @t{#}, up to -the next newline is a comment. @t{(Z+n+)} causes +the next newline is a comment. + +@item @t{(Z+n+)} +causes unquoted newlines to be treated as ordinary whitespace, else they are treated as if they are shell code delimiters and converted to -semicolons. Options are combined within the same set of delimiters, +semicolons. + +@end table + +@noindent +Options are combined within the same set of delimiters, e.g. @t{(Z+Cn+)}. @item @t{_:}@var{flags}@t{:} @@ -5806,7 +5873,7 @@ error, and the flag itself has no effect. @noindent The following flags are meaningful with the @t{$@{}...@t{#}...@t{@}} or -@t{$@{}...@t{%}...@t{@}} forms. The @t{S} and @t{I} flags may also be +@t{$@{}...@t{%}...@t{@}} forms. The @t{S}, @t{I}, and @t{*} flags may also be used with the @t{$@{}...@t{/}...@t{@}} forms. @noindent @@ -5889,6 +5956,10 @@ will remove the same matches as for `@t{#}', but in reverse order, and the form using `@t{%%}' will remove the same matches as for `@t{##}' in reverse order. +@item @t{*} +Enable @t{EXTENDED_GLOB} for substitution via @t{$@{}...@t{/}...@t{@}} or +@t{$@{}...@t{//}...@t{@}}. + @item @t{B} Include the index of the beginning of the match in the result. @@ -5911,8 +5982,9 @@ Include the unmatched portion in the result (the @emph{R}est). @subsection Rules @noindent - -@noindent +@cindex parameter expansion rules +@cindex rules, parameter expansion +@cindex substitution, parameter, rules Here is a summary of the rules for substitution; this assumes that braces are present around the substitution, i.e. @t{$@{}@var{...}@t{@}}. Some particular examples are given below. Note that the Zsh Development Group accepts @@ -6121,6 +6193,7 @@ expression) and replaced with the corresponding value, with internal flags @subsection Examples @noindent +@cindex parameter expansion, examples The flag @t{f} is useful to split a double-quoted substitution line by line. For example, @t{$@{(f)"$(<}@var{file}@t{)"@}} substitutes the contents of @var{file} divided so that each line is @@ -6140,7 +6213,7 @@ This produces the result @t{b}. First, the inner substitution @t{"$@{foo@}"}, which has no array (@t{@@}) flag, produces a single word result @t{"bar baz"}. The outer substitution @t{"$@{(@@)...[1]@}"} detects that this is a scalar, so that (despite the `@t{(@@)}' flag) the subscript -picks the first character. +picks the first character. @item @t{"$@{$@{(@@)foo@}[1]@}"} This produces the result `@t{bar}'. In this case, the inner substitution @@ -6179,7 +6252,7 @@ empty string will then be elided, as it is not in double quotes. @cindex command substitution @cindex substitution, command A command enclosed in parentheses preceded by a dollar sign, like -`@t{$(}...@t{)}', or quoted with grave +`@t{$(}...@t{)}', or quoted with grave accents, like `@t{`}...@t{`}', is replaced with its standard output, with any trailing newlines deleted. If the substitution is not enclosed in double quotes, the @@ -6323,14 +6396,21 @@ option exchanges the effects of `@t{~+}' and `@t{~-}' where they are followed by a number. @noindent +@menu +* Dynamic named directories:: +* Static named directories:: +* `=' expansion:: +* Notes:: +@end menu + +@noindent +@node Dynamic named directories, Static named directories, , Filename Expansion @subsection Dynamic named directories @noindent @cindex directories, named, dynamic @cindex named directories, dynamic @cindex dynamic named directories - -@noindent If the function @t{zsh_directory_name} exists, or the shell variable @t{zsh_directory_name_functions} exists and contains an array of function names, then the functions are used to implement dynamic @@ -6432,6 +6512,7 @@ zsh_directory_name() @{ @end example @noindent +@node Static named directories, `=' expansion, Dynamic named directories, Filename Expansion @subsection Static named directories @noindent @@ -6463,6 +6544,7 @@ if they are the same length. The parameters @t{$PWD} and @t{$OLDPWD} are never abbreviated in this fashion. @noindent +@node `=' expansion, Notes, Static named directories, Filename Expansion @subsection `=' expansion @noindent @@ -6476,11 +6558,11 @@ exists by that name, the word is replaced by the full pathname of the command. @noindent +@node Notes, , `=' expansion, Filename Expansion @subsection Notes @noindent - -@noindent +@cindex filename expansion, notes Filename expansion is performed on the right hand side of a parameter assignment, including those appearing after commands of the @t{typeset} family. In this case, the right hand side will be treated @@ -6533,6 +6615,7 @@ matching, the `@t{/}' and `@t{.}' are not treated specially. @subsection Glob Operators @noindent +@cindex glob operators @table @asis @item @t{*} Matches any string, including the null string. @@ -6551,7 +6634,7 @@ There are also several named classes of characters, in the form The first set use the macros provided by the operating system to test for the given character combinations, including any modifications due to local language settings, see -man page ctype(3): +ctype(3): @noindent @table @asis @@ -6605,7 +6688,8 @@ is not sensitive to the locale: @table @asis @item @t{[:IDENT:]} The character is allowed to form part of a shell identifier, such -as a parameter name +as a parameter name; this test respects the @t{POSIX_IDENTIFIERS} +option @item @t{[:IFS:]} The character is used as an input field separator, i.e. is contained in the @@ -6773,6 +6857,8 @@ pattern. @subsection Globbing Flags @noindent +@cindex globbing flags +@cindex glob flags There are various flags which affect any text to their right up to the end of the enclosing group or to the end of the pattern; they require the @t{EXTENDED_GLOB} option. All take the form @@ -6955,7 +7041,7 @@ qualifiers are also not applied in ordinary pattern matching. @item @t{u} Respect the current locale in determining the presence of multibyte -characters in a pattern, provided the shell was compiled with +characters in a pattern, provided the shell was compiled with @t{MULTIBYTE_SUPPORT}. This overrides the @t{MULTIBYTE} option; the default behaviour is taken from the option. Compare @t{U}. (Mnemonic: typically multibyte characters are from Unicode in the UTF-8 @@ -6990,6 +7076,8 @@ searched for all files which match, so that a pattern of the form @subsection Approximate Matching @noindent +@cindex approximate matching +@cindex matching, approximate When matching approximately, the shell keeps a count of the errors found, which cannot exceed the number specified in the @t{(#a}@var{num}@t{)} flags. Four types of error are recognised: @@ -7064,6 +7152,8 @@ segments which are known to be correct. @subsection Recursive Globbing @noindent +@cindex recursive globbing +@cindex globbing, recursive A pathname component of the form `@t{(}@var{foo}@t{/)#}' matches a path consisting of zero or more directories matching the pattern @var{foo}. @@ -7239,19 +7329,19 @@ expected, if combined with a `@t{=}', the value given must match the file-modes exactly, with a `@t{+}', at least the bits in the given number must be set in the file-modes, and with a `@t{-}', the bits in the number must not be set. Giving a `@t{?}' instead of a -octal digit anywhere in the number ensures that the corresponding bits +octal digit anywhere in the number ensures that the corresponding bits in the file-modes are not checked, this is only useful in combination with `@t{=}'. @noindent If the qualifier `@t{f}' is followed by any other character anything -up to the next matching character (`@t{[}', `@t{@{}', and `@t{<}' match +up to the next matching character (`@t{[}', `@t{@{}', and `@t{<}' match `@t{]}', `@t{@}}', and `@t{>}' respectively, any other character matches itself) is taken as a list of comma-separated @var{sub-spec}s. Each @var{sub-spec} may be either an octal number as described above or a list of any of the characters `@t{u}', `@t{g}', `@t{o}', and `@t{a}', followed by a `@t{=}', a `@t{+}', or a -`@t{-}', followed by a list of any of the characters `@t{r}', `@t{w}', +`@t{-}', followed by a list of any of the characters `@t{r}', `@t{w}', `@t{x}', `@t{s}', and `@t{t}', or an octal digit. The first list of characters specify which access rights are to be checked. If a `@t{u}' is given, those for the owner of the file are used, if a `@t{g}' is @@ -7260,7 +7350,7 @@ of other users, and the `@t{a}' says to test all three groups. The `@t{=}', `@t{+}', and `@t{-}' again says how the modes are to be checked and have the same meaning as described for the first form above. The second list of characters finally says which access rights -are to be expected: `@t{r}' for read access, `@t{w}' for write access, +are to be expected: `@t{r}' for read access, `@t{w}' for write access, `@t{x}' for the right to execute the file (or to search a directory), `@t{s}' for the setuid and setgid bits, and `@t{t}' for the sticky bit. @@ -7270,7 +7360,7 @@ Thus, `@t{*(f70?)}' gives the files for which the owner has read, write, and execute permission, and for which other group members have no rights, independent of the permissions for other users. The pattern `@t{*(f-100)}' gives all files for which the owner does not have -execute permission, and `@t{*(f:gu+w,o-rx:)}' gives the files for which +execute permission, and `@t{*(f:gu+w,o-rx:)}' gives the files for which the owner and the other members of the group have at least write permission, and for which other users don't have read or execute permission. @@ -7401,7 +7491,9 @@ negates all qualifiers following it @item @t{-} toggles between making the qualifiers work on symbolic links (the -default) and the files they point to +default) and the files they point to, if any; any symbolic link for +whose target the `@t{stat}' system call fails (whatever the cause of the +failure) is treated as a file in its own right @item @t{M} sets the @t{MARK_DIRS} option for the current pattern @@ -7432,18 +7524,37 @@ matches in directory traversal order will be considered. Implies @t{oN} when no @t{o}@var{c} qualifier is used. @item @t{o}@var{c} -specifies how the names of the files should be sorted. If @var{c} is -@t{n} they are sorted by name; if it is @t{L} they -are sorted depending on the size (length) of the files; if @t{l} -they are sorted by the number of links; if @t{a}, @t{m}, or @t{c} -they are sorted by the time of the last access, modification, or -inode change respectively; if @t{d}, files in subdirectories appear before +specifies how the names of the files should be sorted. The following values +of @var{c} sort in the following ways: + +@noindent +@table @asis +@item @t{n} +By name. +@item @t{L} +By the size (length) of the files. +@item @t{l} +By number of links. +@item @t{a} +By time of last access, youngest first. +@item @t{m} +By time of last modification, youngest first. +@item @t{c} +By time of last inode change, youngest first. +@item @t{d} +By directories: files in subdirectories appear before those in the current directory at each level of the search --- this is best combined with other criteria, for example `@t{odon}' to sort on names for -files within the same directory; if @t{N}, no sorting is performed. -Note that @t{a}, @t{m}, and @t{c} compare -the age against the current time, hence the first name in the list is the -youngest file. Also note that the modifiers @t{^} and @t{-} are used, +files within the same directory. +@item @t{N} +No sorting is performed. +@item @t{e}@var{string} +@itemx @t{+}@var{cmd} +Sort by shell code (see below). +@end table + +@noindent +Note that the modifiers @t{^} and @t{-} are used, so `@t{*(^-oL)}' gives a list of all files sorted by file size in descending order, following any symbolic links. Unless @t{oN} is used, multiple order specifiers may occur to resolve ties. @@ -7465,8 +7576,8 @@ repeated, but note that the maximum number of sort operators of any kind that may appear in any glob expression is 12. @item @t{O}@var{c} -like `@t{o}', but sorts in descending order; i.e. `@t{*(^oc)}' is the -same as `@t{*(Oc)}' and `@t{*(^Oc)}' is the same as `@t{*(oc)}'; `@t{Od}' +like `@t{o}', but sorts in descending order; i.e. `@t{*(^o}@var{c}@t{)}' is the +same as `@t{*(O}@var{c}@t{)}' and `@t{*(^O}@var{c}@t{)}' is the same as `@t{*(o}@var{c}@t{)}'; `@t{Od}' puts files in the current directory before those in subdirectories at each level of the search. @@ -7474,7 +7585,7 @@ level of the search. specifies which of the matched filenames should be included in the returned list. The syntax is the same as for array subscripts. @var{beg} and the optional @var{end} may be mathematical -expressions. As in parameter subscripting they may be negative to make +expressions. As in parameter subscripting they may be negative to make them count from the last match backward. E.g.: `@t{*(-OL[1,3])}' gives a list of the names of the three largest files. @@ -7718,7 +7829,7 @@ may be in any order. Note that this syntax is strict: @t{[} and @t{]=} must not be quoted, and @var{key} may not consist of the unquoted string @t{]=}, but is otherwise treated as a simple string. The enhanced forms of subscript expression that may be used when directly subscripting a -variable name, described in the section Array Subscripts below, are not +variable name, described in the section `Array Subscripts' below, are not available. @noindent @@ -8088,12 +8199,23 @@ result. On failure substitutes the length of the array plus one, as discussed under the description of `@t{r}', or the empty string for an associative array. +@noindent +Note: Although `@t{i}' may be applied to a scalar substitution to find +the offset of a substring, the results are likely to be misleading when +searching within substitutions that yield an empty string, or when +searching for the empty substring. + @item @t{I} Like `@t{i}', but gives the index of the last match, or all possible matching keys in an associative array. On failure substitutes 0, or the empty string for an associative array. This flag is best when testing for values or keys that do not exist. +@noindent +Note: If the option @t{KSH_ARRAYS} is in effect and no match is found, the +result is indistinguishable from the case when the first element of the array +matches. + @item @t{k} If used in a subscript on an associative array, this flag causes the keys to be interpreted as patterns, and returns the value for the first key @@ -8351,6 +8473,15 @@ parameter is special. `<Z>' indicates that the parameter does not exist when the shell initializes in @t{sh} or @t{ksh} emulation mode. @noindent +The parameters `@t{!}', `@t{#}', `@t{*}', `@t{-}', `@t{?}', `@t{@@}', +`@t{$}', `@t{ARGC}', `@t{HISTCMD}', `@t{LINENO}', `@t{PPID}', +`@t{status}', `@t{TTYIDLE}', `@t{zsh_eval_context}', +`@t{ZSH_EVAL_CONTEXT}', and `@t{ZSH_SUBSHELL}' are read-only and thus +cannot be restored by the user, so they are not output by +`@t{typeset -p}'. This also applies to many read-only parameters loaded +from modules. + +@noindent The following parameters are automatically set by the shell: @noindent @@ -8374,10 +8505,11 @@ Same as @t{#}. @vindex $ @item @t{$} <S> -The process ID of this shell. Note that this indicates the original -shell started by invoking @t{zsh}; all processes forked from the shells -without executing a new program, such as subshells started by -@t{(}@var{...}@t{)}, substitute the same value. +The process ID of this shell, set when the shell initializes. Processes +forked from the shell without executing a new program, such as command +substitutions and commands grouped with @t{(}@var{...}@t{)}, +are subshells that duplicate the current shell, and thus substitute the +same value for @t{$$} as their parent shell. @vindex - @item @t{-} <S> @@ -8458,7 +8590,7 @@ explicitly set locally. @vindex ERRNO @item @t{ERRNO} <S> -The value of errno (see man page errno(3)) +The value of @t{errno} (see errno(3)) as set by the most recently failed system call. This value is system dependent and is intended for debugging purposes. It is also useful with the @t{zsh/system} module which @@ -8511,7 +8643,7 @@ If the corresponding variable is not set in the environment of the shell, it is initialized to the login name corresponding to the current login session. This parameter is exported by default but this can be disabled using the @t{typeset} builtin. The value -is set to the string returned by the man page getlogin(3) system call +is set to the string returned by the getlogin(3) system call if that is available. @vindex MACHTYPE @@ -8540,9 +8672,9 @@ The operating system, as determined at compile time. @vindex PPID @item @t{PPID} <S> -The process ID of the parent of the shell. As for @t{$$}, the -value indicates the parent of the original shell and does not -change in subshells. +The process ID of the parent of the shell, set when the shell initializes. +As with @t{$$}, the value does not change in subshells created as a +duplicate of the current shell. @vindex PWD @item @t{PWD} @@ -8570,8 +8702,9 @@ since the assignment. @noindent Unlike other special parameters, the type of the @t{SECONDS} parameter can -be changed using the @t{typeset} command. Only integer and one of the -floating point types are allowed. For example, `@t{typeset -F SECONDS}' +be changed using the @t{typeset} command. The type may be changed only +to one of the floating point types or back to integer. For example, +`@t{typeset -F SECONDS}' causes the value to be reported as a floating point number. The value is available to microsecond accuracy, although the shell may show more or fewer digits depending on the use of @t{typeset}. See @@ -9062,11 +9195,6 @@ most as many lines as given by the absolute value. If set to zero, the shell asks only if the top of the listing would scroll off the screen. -@vindex LOGCHECK -@item @t{LOGCHECK} -The interval in seconds between checks for login/logout activity -using the @t{watch} parameter. - @vindex MAIL @item @t{MAIL} If this parameter is set and @t{mailpath} is not set, @@ -9310,6 +9438,12 @@ the input line. This avoids running stty at every external command by accidentally exporting it. Also note that @t{STTY} should not be used for window size specifications; these will not be local to the command. +@noindent +If the parameter is set and empty, all of the above applies except +that @t{stty} is not run. This can be useful as a way to freeze the tty +around a single command, blocking its changes to tty settings, +similar to the @t{ttyctl} builtin. + @vindex TERM @item @t{TERM} <S> The type of terminal in use. This is used when looking up termcap @@ -9322,16 +9456,16 @@ take effect. @vindex TERMINFO @item @t{TERMINFO} <S> A reference to your terminfo database, used by the `terminfo' library when the -system has it; see man page terminfo(5). +system has it; see terminfo(5). If set, this causes the shell to reinitialise the terminal, making the workaround `@t{TERM=$TERM}' unnecessary. @vindex TERMINFO_DIRS @item @t{TERMINFO_DIRS} <S> A colon-seprarated list of terminfo databases, used by the `terminfo' library -when the system has it; see man page terminfo(5). This variable is only +when the system has it; see terminfo(5). This variable is only used by certain terminal libraries, in particular ncurses; see -man page terminfo(5) to check support on your system. If set, this +terminfo(5) to check support on your system. If set, this causes the shell to reinitialise the terminal, making the workaround `@t{TERM=$TERM}' unnecessary. Note that unlike other colon-separated arrays this is not tied to a zsh array. @@ -9426,129 +9560,6 @@ to be interpreted as a file extension. The default is not to append any suffix, thus this parameter should be assigned only when needed and then unset again. -@vindex watch -@vindex WATCH -@item @t{watch} <S> <Z> (@t{WATCH} <S>) -An array (colon-separated list) of login/logout events to report. - -@noindent -If it contains the single word `@t{all}', then all login/logout events -are reported. If it contains the single word `@t{notme}', then all -events are reported as with `@t{all}' except @t{$USERNAME}. - -@noindent -An entry in this list may consist of a username, -an `@t{@@}' followed by a remote hostname, -and a `@t{%}' followed by a line (tty). Any of these may -be a pattern (be sure to quote this during the assignment to -@t{watch} so that it does not immediately perform file generation); -the setting of the @t{EXTENDED_GLOB} option is respected. -Any or all of these components may be present in an entry; -if a login/logout event matches all of them, -it is reported. - -@noindent -For example, with the @t{EXTENDED_GLOB} option set, the following: - -@noindent -@example -watch=('^(pws|barts)') -@end example - -@noindent -causes reports for activity associated with any user other than @t{pws} -or @t{barts}. - -@vindex WATCHFMT -@item @t{WATCHFMT} -The format of login/logout reports if the @t{watch} parameter is set. -Default is `@t{%n has %a %l from %m}'. -Recognizes the following escape sequences: - -@noindent -@table @asis -@item @t{%n} -The name of the user that logged in/out. - -@item @t{%a} -The observed action, i.e. "logged on" or "logged off". - -@item @t{%l} -The line (tty) the user is logged in on. - -@item @t{%M} -The full hostname of the remote host. - -@item @t{%m} -The hostname up to the first `@t{.}'. If only the -IP address is available or the utmp field contains -the name of an X-windows display, the whole name is printed. - -@noindent -@emph{NOTE:} -The `@t{%m}' and `@t{%M}' escapes will work only if there is a host name -field in the utmp on your machine. Otherwise they are -treated as ordinary strings. - -@item @t{%S} (@t{%s}) -Start (stop) standout mode. - -@item @t{%U} (@t{%u}) -Start (stop) underline mode. - -@item @t{%B} (@t{%b}) -Start (stop) boldface mode. - -@item @t{%t} -@itemx @t{%@@} -The time, in 12-hour, am/pm format. - -@item @t{%T} -The time, in 24-hour format. - -@item @t{%w} -The date in `@var{day}@t{-}@var{dd}' format. - -@item @t{%W} -The date in `@var{mm}@t{/}@var{dd}@t{/}@var{yy}' format. - -@item @t{%D} -The date in `@var{yy}@t{-}@var{mm}@t{-}@var{dd}' format. - -@item @t{%D@{}@var{string}@t{@}} -The date formatted as @var{string} using the @t{strftime} function, with -zsh extensions as described by -@ref{Prompt Expansion}. - -@item @t{%(}@var{x}@t{:}@var{true-text}@t{:}@var{false-text}@t{)} -Specifies a ternary expression. -The character following the @var{x} is -arbitrary; the same character is used to separate the text -for the "true" result from that for the "false" result. -Both the separator and the right parenthesis may be escaped -with a backslash. -Ternary expressions may be nested. - -@noindent -The test character @var{x} may be any one of `@t{l}', `@t{n}', `@t{m}' -or `@t{M}', which indicate a `true' result if the corresponding -escape sequence would return a non-empty value; or it may be `@t{a}', -which indicates a `true' result if the watched user has logged in, -or `false' if he has logged out. -Other characters evaluate to neither true nor false; the entire -expression is omitted in this case. - -@noindent -If the result is `true', then the @var{true-text} -is formatted according to the rules above and printed, -and the @var{false-text} is skipped. -If `false', the @var{true-text} is skipped and the @var{false-text} -is formatted and printed. -Either or both of the branches may be empty, but -both separators must be present in any case. - -@end table - @vindex WORDCHARS @item @t{WORDCHARS} <S> A list of non-alphanumeric characters considered part of a word @@ -9723,6 +9734,10 @@ This is because many systems which implement the `@t{#!}' mechanism for calling scripts do not strip trailing whitespace. @noindent +It is possible for options to be set within a function scope. See the +description of the option @t{LOCAL_OPTIONS} below. + +@noindent @node Description of Options, Option Aliases, Specifying Options, Options @section Description of Options @@ -10169,6 +10184,23 @@ can match the directory @t{CVS} owing to the presence of the globbing flag Make regular expressions using the @t{zsh/regex} module (including matches with @t{=~}) sensitive to case. +@pindex CASE_PATHS +@pindex NO_CASE_PATHS +@pindex CASEPATHS +@pindex NOCASEPATHS +@cindex case-sensitive globbing, option +@item @t{CASE_PATHS} +If @t{CASE_PATHS} is not set (the default), @t{CASE_GLOB} affects the +interpretation of @emph{every} path component, whenever a special +character appears in @emph{any} component. When @t{CASE_PATHS} is set, +file path components that do @emph{not} contain special filename +generation characters are always sensitive to case, thus restricting +@t{NO_CASE_GLOB} to components that contain globbing characters. + +@noindent +Note that if the filesystem itself is not sensitive to case, then +@t{CASE_PATHS} has no effect. + @pindex CSH_NULL_GLOB @pindex NO_CSH_NULL_GLOB @pindex CSHNULLGLOB @@ -10848,7 +10880,7 @@ most portable way to achieve this behaviour. @pindex NOGLOBALRCS @cindex startup files, global, inhibiting @cindex files, global startup, inhibiting -@item @t{GLOBAL_RCS} (@t{-d}) <D> +@item @t{GLOBAL_RCS} (@t{+d}) <D> If this option is unset, the startup files @t{/etc/zprofile}, @t{/etc/zshrc}, @t{/etc/zlogin} and @t{/etc/zlogout} will not be run. It can be disabled and re-enabled at any time, including inside local startup @@ -10896,6 +10928,23 @@ If the option is not set, and the option @t{APPEND_CREATE} is also not set, `@t{>>!}' or `@t{>>|}' must be used to create a file. If either option is set, `@t{>>}' may be used. +@pindex CLOBBER_EMPTY +@pindex NO_CLOBBER_EMPTY +@pindex CLOBBEREMPTY +@pindex NOCLOBBEREMPTY +@cindex clobbering, of empty files +@cindex file clobbering, of empty files +@item @t{CLOBBER_EMPTY} +This option is only used if the option @t{CLOBBER} is not set: note that +it is set by default. + +@noindent +If this option is set, then regular files of zero length may be +ovewritten (`clobbered'). Note that it is possible another process +has written to the file between this test and use of the file by +the current process. This option should therefore not be used in +cases where files to be clobbered may be written to asynchronously. + @pindex CORRECT @pindex NO_CORRECT @pindex NOCORRECT @@ -11055,7 +11104,7 @@ command path. See @item @t{PRINT_EIGHT_BIT} Print eight bit characters literally in completion lists, etc. This option is not necessary if your system correctly returns the -printability of eight bit characters (see man page ctype(3)). +printability of eight bit characters (see ctype(3)). @pindex PRINT_EXIT_VALUE @pindex NO_PRINT_EXIT_VALUE @@ -11108,6 +11157,14 @@ avoided by expanding the `@t{*}' in ZLE (with tab). Allow the short forms of @t{for}, @t{repeat}, @t{select}, @t{if}, and @t{function} constructs. +@pindex SHORT_REPEAT +@pindex NO_SHORT_REPEAT +@pindex SHORTREPEAT +@pindex NOSHORTREPEAT +@item @t{SHORT_REPEAT} +Allow the short form @t{repeat} as @t{SHORT_LOOPS} but without enabling +it for the other constructs. + @pindex SUN_KEYBOARD_HACK @pindex NO_SUN_KEYBOARD_HACK @pindex SUNKEYBOARDHACK @@ -11178,7 +11235,7 @@ The check is omitted if the commands run from the previous command line included a `@t{jobs}' command, since it is assumed the user is aware that there are background or suspended jobs. A `@t{jobs}' command run from one of the hook functions defined in -the section Special Functions in @ref{Functions} +the section `Special Functions' in @ref{Functions} is not counted for this purpose. @pindex CHECK_RUNNING_JOBS @@ -11669,6 +11726,16 @@ If the option is set, they will only be shown when parameters are selected with the `@t{-m}' option. The option `@t{-p}' is available whether or not the option is set. +@pindex TYPESET_TO_UNSET +@pindex NO_TYPESET_TO_UNSET +@pindex TYPESETTOUNSET +@pindex NOTYPESETTOUNSET +@item @t{TYPESET_TO_UNSET} <K> <S> +When declaring a new parameter with any of the `@t{typeset}' family of +related commands, the parameter remains unset unless and until a +value is explicity assigned to it, either in the `@t{typeset}' command +itself or as a later assignment statement. + @pindex VERBOSE @pindex NO_VERBOSE @pindex NOVERBOSE @@ -11734,7 +11801,7 @@ substrings. @pindex NOBSDECHO @cindex echo, BSD compatible @item @t{BSD_ECHO} <S> -Make the @t{echo} builtin compatible with the BSD man page echo(1) command. +Make the @t{echo} builtin compatible with the BSD echo(1) command. This disables backslashed escape sequences in echo strings unless the @t{-e} option is specified. @@ -11986,7 +12053,8 @@ command found in the path. @noindent Furthermore, the @t{getopts} builtin behaves in a POSIX-compatible fashion in that the associated variable @t{OPTIND} is not made -local to functions. +local to functions, and its value is calculated differently to match +other shells. @noindent Moreover, the warning and special exit code from @@ -12074,10 +12142,17 @@ When this option is set, the usual zsh behaviour of executing traps for @t{EXIT} on exit from shell functions is suppressed. In that case, manipulating @t{EXIT} traps always alters the global trap for exiting the shell; the @t{LOCAL_TRAPS} option is -ignored for the @t{EXIT} trap. Furthermore, a @t{return} statement -executed in a trap with no argument passes back from the function the -value from the surrounding context, not from code executed within the -trap. +ignored for the @t{EXIT} trap. + +@noindent +Also, a @t{return} statement executed in a trap with no argument passes +back from the function the value from the surrounding context, not from +code executed within the trap. + +@noindent +Furthermore, if a trap is set to be ignored, this state persists when +a subshell is entered. Without the option, the trap would be reset to +its default state at this point. @pindex SH_FILE_EXPANSION @pindex NO_SH_FILE_EXPANSION @@ -12721,7 +12796,16 @@ For each @var{name} with a corresponding @var{value}, define an alias with that value. A trailing space in @var{value} causes the next word to be checked for alias expansion. If the @t{-g} flag is present, define a global alias; global aliases are expanded even if they do not -occur in command position. +occur in command position: + +@noindent +@example +% perldoc --help 2>&1 | grep 'built-in functions' + -f Search Perl built-in functions +% alias -g HG='--help 2>&1 | grep' +% perldoc HG 'built-in functions' + -f Search Perl built-in functions +@end example @noindent If the @t{-s} flag is present, define a suffix alias: if the command @@ -13450,7 +13534,7 @@ Do nothing and return an exit status of 1. @cindex history, editing @cindex editing history -@item @t{fc} [ @t{-e} @var{ename} ] [ @t{-LI} ] [ @t{-m} @var{match} ] [ @var{old}@t{=}@var{new} ... ] [ @var{first} [ @var{last} ] ] +@item @t{fc} [ @t{-e} @var{ename} ] [ @t{-s} ] [ @t{-LI} ] [ @t{-m} @var{match} ] [ @var{old}@t{=}@var{new} ... ] [ @var{first} [ @var{last} ] ] @itemx @t{fc -l }[ @t{-LI} ] [ @t{-nrdfEiD} ] [ @t{-t} @var{timefmt} ] [ @t{-m} @var{match} ] @itemx @t{@ @ @ @ @ @ }[ @var{old}@t{=}@var{new} ... ] [ @var{first} [ @var{last} ] ] @itemx @t{fc -p }[ @t{-a} ] [ @var{filename} [ @var{histsize} [ @var{savehistsize} ] ] ] @@ -13472,7 +13556,8 @@ substitutions @var{old}@t{=}@var{new}, if any, are then performed on the text of the events. @noindent -In addition to the number range, +The range of events selected by numbers can be narrowed further by the +following flags. @table @asis @item @t{-I} restricts to only internal events (not from @t{$HISTFILE}) @@ -13481,8 +13566,8 @@ restricts to only local events (not from other shells, see @t{SHARE_HISTORY} in @ref{Description of Options} -- note that @t{$HISTFILE} is considered local when read at startup) @item @t{-m} -takes the first argument as a pattern (should be quoted) and -only the history events matching this pattern are considered +takes the first argument as a pattern (which should be +quoted) and only the history events matching this pattern are considered @end table @noindent @@ -13504,6 +13589,7 @@ usually `@t{vi}' is used. If @var{ename} is `@t{-}', no editor is invoked. When editing is complete, the edited command is executed. @noindent +The flag `@t{-s}' is equivalent to `@t{-e -}'. The flag @t{-r} reverses the order of the events and the flag @t{-n} suppresses event numbers when listing. @@ -13625,6 +13711,11 @@ name of a library shell function which is then redefined to call @t{newfn}, thereby installing a modified version of the function. @noindent +@emph{The }@t{-M}@emph{ and }@t{+M}@emph{ flags} +@cindex defining mathematical functions +@cindex functions, defining mathematical + +@noindent Use of the @t{-M} option may not be combined with any of the options handled by @t{typeset -f}. @@ -13646,52 +13737,99 @@ expressions. The name of the function in @t{$0} is @var{mathfn} (not @var{shellfn} as would usually be the case), provided the option @t{FUNCTION_ARGZERO} is in effect. The positional parameters in the shell function correspond to the arguments of the mathematical function call. -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. @noindent -If the additional option @t{-s} is given to @t{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. +The result of the last arithmetical expression evaluated inside the shell +function gives the result of the mathematical function. This is not limited to +arithmetic substitutions of the form @t{$((}@var{...}@t{))}, +but also includes arithmetical expressions evaluated in any other way, including +by the @t{let} builtin, +by @t{((}@var{...}@t{))} statements, +and even +by the @t{return} builtin +and +by array subscripts. +Therefore, care must be taken not to use syntactical constructs that perform +arithmetic evaluation after evaluating what is to be the result of the function. +For example: @noindent -@t{functions -M} with no arguments lists all such user-defined functions in -the same form as a definition. With the additional option @t{-m} and -a list of arguments, all functions whose @var{mathfn} matches one of -the pattern arguments are listed. +@findex zmath_cube +@findex cube +@example +# WRONG +zmath_cube() @{ + (( $1 * $1 * $1 )) + return 0 +@} +functions -M cube 1 1 zmath_cube +print $(( cube(3) )) +@end example @noindent -@t{function +M} removes the list of mathematical functions; with the -additional option @t{-m} the arguments are treated as patterns and -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 @var{mathfn}). +This will print `@t{0}' because of the @t{return}. @noindent -For example, the following prints the cube of 3: +Commenting the @t{return} out would lead to a different problem: the +@t{((}@var{...}@t{))} statement would become +the last statement in the function, so the @emph{return status} (@t{$?}) of the +function would be non-zero (indicating failure) whenever the @emph{arithmetic +result} of the function would happen to be zero (numerically): @noindent @example -zmath_cube() @{ (( $1 * $1 * $1 )) @} +# WRONG +zmath_cube() @{ + (( $1 * $1 * $1 )) +@} +functions -M cube 1 1 zmath_cube +print $(( cube(0) )) +@end example + +@noindent +Instead, the @t{true} builtin can be used: + +@noindent +@example +# RIGHT +zmath_cube() @{ + (( $1 * $1 * $1 )) + true +@} functions -M cube 1 1 zmath_cube print $(( cube(3) )) @end example @noindent -The following string function takes a single argument, including -the commas, so prints 11: +If the additional option @t{-s} is given to @t{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. +Thus, the following string function takes a single argument, including +the commas, and prints 11: @noindent @example -stringfn() @{ (( $#1 )) @} +stringfn() @{ (( $#1 )); true @} functions -Ms stringfn print $(( stringfn(foo,bar,rod) )) @end example +@noindent +@t{functions -M} with no arguments lists all such user-defined functions in +the same form as a definition. With the additional option @t{-m} and +a list of arguments, all functions whose @var{mathfn} matches one of +the pattern arguments are listed. + +@noindent +@t{function +M} removes the list of mathematical functions; with the +additional option @t{-m} the arguments are treated as patterns and +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 @var{mathfn}). + @item @t{getcap} See @ref{The zsh/cap Module}. @@ -13729,7 +13867,8 @@ is stored in @t{OPTARG}. The first option to be examined may be changed by explicitly assigning to @t{OPTIND}. @t{OPTIND} has an initial value of @t{1}, and is normally set to @t{1} upon entry to a shell function and restored -upon exit (this is disabled by the @t{POSIX_BUILTINS} option). @t{OPTARG} +upon exit. (The @t{POSIX_BUILTINS} option disables this, and also changes +the way the value is calculated to match other shells.) @t{OPTARG} is not reset and retains its value from the most recent call to @t{getopts}. If either of @t{OPTIND} or @t{OPTARG} is explicitly unset, it remains unset, and the index or option argument is not @@ -13826,9 +13965,32 @@ be shown. @noindent The @t{-Z} option replaces the shell's argument and environment space with the given string, truncated if necessary to fit. This will normally be -visible in @t{ps} (man page ps(1)) listings. This feature is typically +visible in @t{ps} (ps(1)) listings. This feature is typically used by daemons, to indicate their state. +@noindent +Full job control is only available in the top-level interactive shell, +not in commands run in the left hand side of pipelines or within +the @t{(}@var{...}@t{)} construct. However, a snapshot +of the job state at that point is taken, so it is still possible +to use the @t{jobs} builtin, or any parameter providing job information. +This gives information about the state of jobs at the point the subshell +was created. If background processes are created within the subshell, +then instead information about those processes is provided. + +@noindent +For example, + +@noindent +@example +sleep 10 & # Job in background +( # Shell forks +jobs # Shows information about "sleep 10 &" +sleep 5 & # Process in background (no job control) +jobs # Shows information about "sleep 5 &" +) +@end example + @findex kill @cindex killing jobs @cindex jobs, killing @@ -13986,14 +14148,6 @@ Same as @t{typeset}, except that the options @t{-g}, and @t{-f} are not permitted. In this case the @t{-x} option does not force the use of @t{-g}, i.e. exported variables will be local to functions. -@findex log -@vindex watch, use of -@cindex watching users -@cindex users, watching -@item @t{log} -List all users currently logged in who are affected by -the current setting of the @t{watch} parameter. - @findex logout @item @t{logout} [ @var{n} ] Same as @t{exit}, except that it only works in a login shell. @@ -14255,7 +14409,7 @@ Same as @t{fc -e -}. @vindex IFS, use of @item @t{read }[ @t{-rszpqAclneE} ] [ @t{-t} [ @var{num} ] ] [ @t{-k} [ @var{num} ] ] [ @t{-d} @var{delim} ] -@itemx @t{@ @ @ @ @ }[ @t{-u} @var{n} ] [ @var{name}[@t{?}@var{prompt}] ] [ @var{name} ... ] +@itemx @t{@ @ @ @ @ }[ @t{-u} @var{n} ] [ [@var{name}][@t{?}@var{prompt}] ] [ @var{name} ... ] @vindex REPLY, use of @vindex reply, use of Read one line and break it into fields using the characters @@ -14396,7 +14550,17 @@ Same as @t{hash -r}. @item @t{return} [ @var{n} ] Causes a shell function or `@t{.}' script to return to the invoking script with the return status specified by -an arithmetic expression @var{n}. If @var{n} +an arithmetic expression @var{n}. +For example, the following prints `@t{42}': + +@noindent +@example +() @{ integer foo=40; return "foo + 2" @} +echo $? +@end example + +@noindent +If @var{n} is omitted, the return status is that of the last command executed. @@ -14408,7 +14572,7 @@ will return to whatever it was previously processing; with a non-zero status, the shell will behave as interrupted except that the return status of the trap is retained. Note that the numeric value of the signal which caused the trap is passed as the first argument, so the statement -`@t{return $((128+$1))}' will return the same status as if the signal +`@t{return "128+$1"}' will return the same status as if the signal had not been trapped. @item @t{sched} @@ -14692,7 +14856,8 @@ unfreezing the tty does not guarantee settings made on the command line are preserved. Strings of commands run between editing the command line will see a consistent tty state. See also the shell variable @t{STTY} for a means of initialising -the tty before running external commands. +the tty before running external commands and/or freezing the tty +around a single command. @findex type @item @t{type} [ @t{-wfpamsS} ] @var{name} ... @@ -14720,7 +14885,11 @@ retain their special attributes when made local. @noindent For each @var{name}@t{=}@var{value} assignment, the parameter -@var{name} is set to @var{value}. +@var{name} is set to @var{value}. If the assignment is omitted and @var{name} +does @emph{not} refer to an existing parameter, a new parameter is intialized +to empty string, zero, or empty array (as appropriate), @emph{unless} the +shell option @t{TYPESET_TO_UNSET} is set. When that option is set, +the parameter attributes are recorded but the parameter remains unset. @noindent If the shell option @t{TYPESET_SILENT} is not set, for each remaining @@ -14814,7 +14983,7 @@ expansion. Hence it is not possible to assign to multiple arrays by this means. @noindent -Note that each interface to any of the commands my be disabled +Note that each interface to any of the commands may be disabled separately. For example, `@t{disable -r typeset}' disables the reserved word interface to @t{typeset}, exposing the builtin interface, while `@t{disable typeset}' disables the builtin. Note that disabling the @@ -15224,7 +15393,7 @@ will report an error if this fails. @cindex umask @item @t{umask} [ @t{-S} ] [ @var{mask} ] The umask is set to @var{mask}. @var{mask} can be either -an octal number or a symbolic value as described in man page chmod(1). +an octal number or a symbolic value as described in the chmod(1) man page. If @var{mask} is omitted, the current value is printed. The @t{-S} option causes the mask to be printed as a symbolic value. Otherwise, the mask is printed as an octal number. Note that in @@ -15961,13 +16130,15 @@ by typing the number before entering a command. Generally the numeric argument causes the next command entered to be repeated the specified number of times, unless otherwise noted below; this is implemented by the @t{digit-argument} widget. See also -@ref{Arguments} for some other ways the numeric argument can be modified. +@ref{Arguments}for some other ways the numeric argument can be modified. @noindent @menu * Keymaps:: * Zle Builtins:: * Zle Widgets:: +* User-Defined Widgets:: +* Standard Widgets:: * Character Highlighting:: @end menu @@ -16037,6 +16208,8 @@ except for ^J (line feed) and ^M (return) which are bound to @t{accept-line}. This is deliberately not pleasant to use; if you are using it, it means you deleted the main keymap, and you should put it back. +@noindent + @subsection Reading Commands @noindent When ZLE is reading a command from the terminal, it may read a sequence @@ -16070,6 +16243,8 @@ A key sequence typed by the user can be turned into a command name for use in user-defined widgets with the @t{read-command} widget, described in @ref{Miscellaneous} below. +@noindent + @subsection Local Keymaps @noindent @cindex local keymaps @@ -16399,7 +16574,7 @@ refer to a terminal an error is reported. @itemx @t{zle} @t{-F} [ @t{-L} | @t{-w} ] [ @var{fd} [ @var{handler} ] ] @itemx @t{zle} @t{-I} @itemx @t{zle} @t{-T} [ @t{tc} @var{function} | @t{-r} @t{tc} | @t{-L} ] -@itemx @t{zle} @var{widget} [ @t{-n} @var{num} ] [ @t{-Nw} ] [ @t{-K} @var{keymap} ] @var{args} ... +@itemx @t{zle} @var{widget} [ @t{-n} @var{num} ] [ @t{-f} @var{flag} ] [ @t{-Nw} ] [ @t{-K} @var{keymap} ] @var{args} ... The @t{zle} builtin performs a number of different actions concerning ZLE. @@ -16490,8 +16665,7 @@ For further information, see @ref{Completion Widgets}. @item @t{-R} [ @t{-c} ] [ @var{display-string} ] [ @var{string} ... ] -Redisplay the command line; this is to be called from within a user-defined -widget to allow changes to become visible. If a @var{display-string} is +Redisplay the command line. If a @var{display-string} is given and not empty, this is shown in the status line (immediately below the line being edited). @@ -16502,9 +16676,9 @@ prompt in the same way as completion lists are printed. If no cleared. @noindent -Note that this option is only useful for widgets that do not exit -immediately after using it because the strings displayed will be erased -immediately after return from the widget. +Note that immediately after returning from running widgets, the command line +will be redisplayed and the strings displayed will be erased. Therefore, this +option is only useful for widgets that do not exit immediately after using it. @noindent This command can safely be called outside user defined widgets; if zle is @@ -16700,7 +16874,7 @@ optional argument for debugging or testing. Note that this transformation is not applied to other non-printing characters such as carriage returns and newlines. -@item @var{widget} [ @t{-n} @var{num} ] [ @t{-Nw} ] [ @t{-K} @var{keymap} ] @var{args} ... +@item @var{widget} [ @t{-n} @var{num} ] [ @t{-f} @var{flag} ] [ @t{-Nw} ] [ @t{-K} @var{keymap} ] @var{args} ... Invoke the specified @var{widget}. This can only be done when ZLE is active; normally this will be within a user-defined widget. @@ -16723,6 +16897,10 @@ active. With the option @t{-w}, @t{WIDGET} and related parameters are set to reflect the widget being executed by the @t{zle} call. @noindent +Normally, when @var{widget} returns the special parameter @t{LASTWIDGET} will +point to it. This can be inhibited by passing the option @t{-f nolast}. + +@noindent Any further arguments will be passed to the widget; note that as standard argument handling is performed, any general argument list should be preceded by @t{-}@t{-}. If it is a shell @@ -16750,9 +16928,9 @@ it should call the @t{beep} widget directly. @end table @noindent -@node Zle Widgets, Character Highlighting, Zle Builtins, Zsh Line Editor +@node Zle Widgets, User-Defined Widgets, Zle Builtins, Zsh Line Editor -@section Widgets +@section Zle Widgets @noindent @cindex widgets All actions in the editor are performed by `widgets'. A widget's job is @@ -16761,7 +16939,8 @@ in keymaps are bound to are in fact widgets. Widgets can be user-defined or built in. @noindent -The standard widgets built into ZLE are listed in Standard Widgets below. +The standard widgets built into ZLE are listed in +@ref{Standard Widgets}. Other built-in widgets can be defined by other modules (see @ref{Zsh Modules}). Each built-in widget has two names: its normal canonical name, and the same name preceded by a `@t{.}'. The `@t{.}' name is special: it can't be @@ -16775,6 +16954,9 @@ shell function is executed, and can perform editing (or other) actions. It is recommended that user-defined widgets should not have names starting with `@t{.}'. +@noindent +@node User-Defined Widgets, Standard Widgets, Zle Widgets, Zsh Line Editor + @section User-Defined Widgets @noindent @cindex widgets, user-defined @@ -17012,7 +17194,7 @@ and @t{POSTDISPLAY} are possible, but note that the @t{P} flag is needed for character indexing to include @t{PREDISPLAY}. @noindent -Each string consists of the following parts: +Each string consists of the following whitespace-separated parts: @noindent @itemize @bullet @@ -17021,18 +17203,32 @@ Each string consists of the following parts: Optionally, a `@t{P}' to signify that the start and end offset that follow include any string set by the @t{PREDISPLAY} special parameter; this is needed if the predisplay string itself is to be highlighted. -Whitespace may follow the `@t{P}'. +Whitespace between the `@t{P}' and the start offset is optional. @item -A start offset in the same units as @t{CURSOR}, terminated by -whitespace. +A start offset in the same units as @t{CURSOR}. @item -An end offset in the same units as @t{CURSOR}, terminated by -whitespace. +An end offset in the same units as @t{CURSOR}. @item A highlight specification in the same format as used for contexts in the parameter @t{zle_highlight}, see @ref{Character Highlighting}; for example, @t{standout} or @t{fg=red,bold}. +@item +Optionally, a string of the form `@t{memo=}@var{token}'. +The @var{token} consists of everything between the `@t{=}' and the next +whitespace, comma, NUL, or the end of the string. +The @var{token} is preserved verbatim but not parsed in any way. + +@noindent +Plugins may use this to identify array elements they have added: for example, +a plugin might set @var{token} to its (the plugin's) name and then use +`@t{region_highlight=( $@{region_highlight:#*memo=}@var{token}@t{@} )}' +in order to remove array elements it have added. + +@noindent +(This example uses the `@t{$@{}@var{name}@t{:#}@var{pattern}@t{@}}' array-grepping +syntax described in +@ref{Parameter Expansion}.) @end itemize @noindent @@ -17040,7 +17236,7 @@ For example, @noindent @example -region_highlight=("P0 20 bold") +region_highlight=("P0 20 bold memo=foobar") @end example @noindent @@ -17052,6 +17248,12 @@ Note that the effect of @t{region_highlight} is not saved and disappears as soon as the line is accepted. @noindent +Note that zsh 5.8 and older do not support the `@t{memo=}@var{token}' field +and may misparse the third (highlight specification) field when a memo +is given. + + +@noindent The final highlighting on the command line depends on both @t{region_highlight} and @t{zle_highlight}; see @ref{Character Highlighting} for details. @@ -17264,6 +17466,7 @@ This can be used for detecting switches between the vi command @end table @noindent +@node Standard Widgets, Character Highlighting, User-Defined Widgets, Zsh Line Editor @section Standard Widgets @noindent @@ -17291,7 +17494,7 @@ the @t{KEYTIMEOUT} parameter, see @ref{Parameters}. * Miscellaneous:: * Text Objects:: @end menu -@node Movement, History Control, , Zle Widgets +@node Movement, History Control, , Standard Widgets @subsection Movement @noindent @@ -17440,7 +17643,7 @@ Repeat the last @t{vi-find} command in the opposite direction. Move up a line in the buffer. @end table -@node History Control, Modifying Text, Movement, Zle Widgets +@node History Control, Modifying Text, Movement, Standard Widgets @subsection History Control @noindent @@ -17819,7 +18022,7 @@ the numeric argument. Zero for both local and imported lines and nonzero for only local lines. @end table -@node Modifying Text, Arguments, History Control, Zle Widgets +@node Modifying Text, Arguments, History Control, Standard Widgets @subsection Modifying Text @noindent @@ -18154,7 +18357,7 @@ into the kill buffer. Arguably, this is what Y should do in vi, but it isn't what it actually does. @end table -@node Arguments, Completion, Modifying Text, Zle Widgets +@node Arguments, Completion, Modifying Text, Standard Widgets @subsection Arguments @noindent @@ -18210,7 +18413,7 @@ zle universal-argument @end example @end table -@node Completion, Miscellaneous, Arguments, Zle Widgets +@node Completion, Miscellaneous, Arguments, Standard Widgets @subsection Completion @noindent @@ -18287,7 +18490,7 @@ When a previous completion displayed a list below the prompt, this widget can be used to move the prompt below the list. @end table -@node Miscellaneous, Text Objects, Completion, Zle Widgets +@node Miscellaneous, Text Objects, Completion, Standard Widgets @subsection Miscellaneous @noindent @@ -18338,7 +18541,7 @@ a desired suffix-preservation behavior. Beep, unless the @t{BEEP} option is unset. @tindex bracketed-paste -@item @t{bracketed-paste} +@item @t{bracketed-paste} (@t{^[[200~}) (@t{^[[200~}) (@t{^[[200~}) This widget is invoked when text is pasted to the terminal emulator. It is not intended to be bound to actual keys but instead to the special sequence generated by the terminal emulator when text is pasted. @@ -18711,7 +18914,7 @@ If the last command executed was a digit as part of an argument, continue the argument. Otherwise, execute vi-beginning-of-line. @end table -@node Text Objects, , Miscellaneous, Zle Widgets +@node Text Objects, , Miscellaneous, Standard Widgets @subsection Text Objects @noindent @@ -18760,7 +18963,7 @@ argument, multiple words will be selected. @end table @noindent -@node Character Highlighting, , Zle Widgets, Zsh Line Editor +@node Character Highlighting, , Standard Widgets, Zsh Line Editor @section Character Highlighting @noindent @@ -19053,7 +19256,7 @@ work even if the widget in question has been re-bound. When this newly defined widget is bound to a key using the @t{bindkey} builtin command defined in the @t{zsh/zle} module (@ref{Zsh Line Editor}), typing that key will call the shell function `@t{completer}'. This -function is responsible for generating the possible matches using the +function is responsible for generating completion matches using the builtins described below. As with other ZLE widgets, the function is called with its standard input closed. @@ -19241,7 +19444,7 @@ The string of an exact match if one was found, otherwise unset. @vindex ignored, compstate @item @t{ignored} -The number of words that were ignored because they matched one of the +The number of completions that were ignored because they matched one of the patterns given with the @t{-F} option to the @t{compadd} builtin command. @@ -19344,8 +19547,7 @@ will be used in the same way as the value of @t{LISTMAX}. @vindex nmatches, compstate @item @t{nmatches} -The number of matches generated and accepted by the completion code so -far. +The number of matches added by the completion code so far. @vindex old_insert, compstate @item @t{old_insert} @@ -19383,7 +19585,8 @@ value of a parameter assignment. @vindex pattern_insert, compstate @item @t{pattern_insert} Normally this is set to @t{menu}, which specifies that menu completion will -be used whenever a set of matches was generated using pattern matching. If +be used whenever a set of matches was generated using @t{pattern_match} +(see below). If it is set to any other non-empty string by the user and menu completion is not selected by other option settings, the code will instead insert any common prefix for the generated matches as with normal completion. @@ -19400,7 +19603,7 @@ additionally a wildcard `@t{*}' is assumed at the cursor position; if it is empty or unset, metacharacters will be treated literally. @noindent -Note that the matcher specifications given to the @t{compadd} builtin +Note that the match specifications given to the @t{compadd} builtin command are not used if this is set to a non-empty string. @vindex quote, compstate @@ -19498,21 +19701,20 @@ edited. @itemx @t{@ @ @ @ @ @ @ @ }[@t{-r} @var{remove-chars} ] [ @t{-R} @var{remove-func} ] @itemx @t{@ @ @ @ @ @ @ @ }[@t{-D} @var{array} ] [ @t{-O} @var{array} ] [ @t{-A} @var{array} ] @itemx @t{@ @ @ @ @ @ @ @ }[@t{-E} @var{number} ] -@itemx @t{@ @ @ @ @ @ @ @ }[@t{-M} @var{match-spec} ] [ @t{-}@t{-} ] [ @var{words} ... ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-M} @var{match-spec} ] [ @t{-}@t{-} ] [ @var{completions} ... ] @noindent This builtin command can be used to add matches directly and control all the information the completion code stores with each possible -match. The return status is zero if at least one match was added and +completion. The return status is zero if at least one match was added and non-zero if no matches were added. @noindent -The completion code breaks the string to complete into seven fields in -the order: +The completion code breaks each match into seven fields in the order: @noindent @quotation -@var{<ipre><apre><hpre><word><hsuf><asuf><isuf>} +@var{<ipre><apre><hpre><body><hsuf><asuf><isuf>} @end quotation @noindent @@ -19522,12 +19724,12 @@ is an ignored prefix taken from the command line, the contents of the option. With the @t{-U} option, only the string from the @t{-i} option is used. The field @var{<apre>} is an optional prefix string given with the @t{-P} option. The @var{<hpre>} field is a string -that is considered part of the match but that should not be shown when +that is considered part of the match but that should not be shown when listing completions, given with the @t{-p} option; for example, functions that do filename generation might specify -a common path prefix this way. @var{<word>} is the part of the match that -should appear in the list of completions, i.e. one of the @var{words} given -at the end of the @t{compadd} command line. The suffixes @var{<hsuf>}, +a common path prefix this way. @var{<body>} is the part of the match that +should appear in the list of matches shown to the user. +The suffixes @var{<hsuf>}, @var{<asuf>} and @var{<isuf>} correspond to the prefixes @var{<hpre>}, @var{<apre>} and @var{<ipre>} and are given by the options @t{-s}, @t{-S} and @t{-I}, respectively. @@ -19538,53 +19740,53 @@ The supported flags are: @noindent @table @asis @item @t{-P} @var{prefix} -This gives a string to be inserted before the given @var{words}. The +This gives a string to be inserted before each match. The string given is not considered as part of the match and any shell metacharacters in it will not be quoted when the string is inserted. @item @t{-S} @var{suffix} -Like @t{-P}, but gives a string to be inserted after the match. +Like @t{-P}, but gives a string to be inserted after each match. @item @t{-p} @var{hidden-prefix} -This gives a string that should be inserted into the command line before the +This gives a string that should be inserted before each match but that should not appear in the list of matches. Unless the @t{-U} option is given, this string must be matched as part of the string on the command line. @item @t{-s} @var{hidden-suffix} -Like `@t{-p}', but gives a string to insert after the match. +Like `@t{-p}', but gives a string to insert after each match. @item @t{-i} @var{ignored-prefix} -This gives a string to insert into the command line just before any +This gives a string to insert just before any string given with the `@t{-P}' option. Without `@t{-P}' the string is -inserted before the string given with `@t{-p}' or directly before the +inserted before the string given with `@t{-p}' or directly before each match. @item @t{-I} @var{ignored-suffix} Like @t{-i}, but gives an ignored suffix. @item @t{-a} -With this flag the @var{words} are taken as names of arrays and the -possible matches are their values. If only some elements of the -arrays are needed, the @var{words} may also contain subscripts, as in +With this flag the @var{completions} are taken as names of arrays and the +actual completions are their values. If only some elements of the +arrays are needed, the @var{completions} may also contain subscripts, as in `@t{foo[2,-1]}'. @item @t{-k} -With this flag the @var{words} are taken as names of associative arrays -and the possible matches are their keys. As for @t{-a}, the +With this flag the @var{completions} are taken as names of associative arrays +and the actual completions are their keys. As for @t{-a}, the @var{words} may also contain subscripts, as in `@t{foo[(R)*bar*]}'. @item @t{-d} @var{array} -This adds per-match display strings. The @var{array} should contain one -element per @var{word} given. The completion code will then display the -first element instead of the first @var{word}, and so on. The +This adds per-completion display strings. The @var{array} should contain one +element per @var{completion} given. The completion code will then display the +first element instead of the first @var{completion}, and so on. The @var{array} may be given as the name of an array parameter or directly as a space-separated list of words in parentheses. @noindent -If there are fewer display strings than @var{words}, the leftover -@var{words} will be displayed unchanged and if there are more display -strings than @var{words}, the leftover display strings will be silently +If there are fewer display strings than @var{completions}, the leftover +@var{completions} will be displayed unchanged and if there are more display +strings than @var{completions}, the leftover display strings will be silently ignored. @item @t{-l} @@ -19608,7 +19810,8 @@ by the @t{-d} option). This is the default if `@t{-o}' is specified but the @var{order} argument is omitted. @item @t{nosort} -This specifies that the matches are pre-sorted and their order should be +This specifies that the @var{completions} +are pre-sorted and their order should be preserved. This value only makes sense alone and cannot be combined with any others. @@ -19622,7 +19825,7 @@ Arrange the matches backwards by reversing the sort ordering. @end table @item @t{-J} @var{group-name} -Gives the name of the group of matches the words should be stored in. +Gives the name of the group that the matches should be stored in. @item @t{-V} @var{group-name} Like @t{-J} but naming an unsorted group. This option is identical to @@ -19666,13 +19869,13 @@ produce unexpected results. If arbitrary text is to be passed in a description, it can be escaped using e.g. @t{$@{my_str//\%/%%@}}. @item @t{-x} @var{message} -Like @t{-X}, but the @var{message} will be printed even if there are no +Like @t{-X}, but the @var{message} will be printed even if there are no matches in the group. @item @t{-q} -The suffix given with @t{-S} will be automatically removed if +The suffix given with @t{-S} will be automatically removed if the next character typed is a blank or does not insert anything, or if -the suffix consists of only one character and the next character typed +the suffix consists of only one character and the next character typed is the same character. @item @t{-r} @var{remove-chars} @@ -19695,15 +19898,15 @@ automatically added space will be removed when one of the characters in the list is typed. @item @t{-R} @var{remove-func} -This is another form of the @t{-r} option. When a suffix -has been inserted and the completion accepted, the function +This is another form of the @t{-r} option. When a match +has been accepted and a suffix has been inserted, the function @var{remove-func} will be called after the next character typed. It is passed the length of the suffix as an argument and can use the special parameters available in ordinary (non-completion) zle widgets (see @ref{Zsh Line Editor}) to analyse and modify the command line. @item @t{-f} -If this flag is given, all of the matches built from @var{words} are +If this flag is given, all of the matches built from the @var{completions} are marked as being the names of files. They are not required to be actual filenames, but if they are, and the option @t{LIST_TYPES} is set, the characters describing the types of the files in the completion lists will @@ -19717,15 +19920,14 @@ the @t{AUTO_PARAM_SLASH} and @t{AUTO_PARAM_KEYS} options be used for the matches. @item @t{-W} @var{file-prefix} -This string is a pathname that will be -prepended to each of the matches formed by the given @var{words} together +This string is a pathname that will be prepended to each match together with any prefix specified by the @t{-p} option to form a complete filename for testing. Hence it is only useful if combined with the @t{-f} flag, as the tests will not otherwise be performed. @item @t{-F} @var{array} -Specifies an array containing patterns. Words matching one of these -patterns are ignored, i.e. not considered to be possible matches. +Specifies an array containing patterns. @var{completions} that match one of +these patterns are ignored, that is, not considered to be matches. @noindent The @var{array} may be the name of an array parameter or a list of @@ -19734,8 +19936,8 @@ literal patterns enclosed in parentheses and quoted, as in `@t{-F "(*?.o taken as the patterns. @item @t{-Q} -This flag instructs the completion -code not to quote any metacharacters in the words when inserting them +This flag instructs the completion +code not to quote any metacharacters in the matches when inserting them into the command line. @item @t{-M} @var{match-spec} @@ -19746,47 +19948,50 @@ between them to form the specification string to use. Note that they will only be used if the @t{-U} option is not given. @item @t{-n} -Specifies that the words added are to be used as possible -matches, but are not to appear in the completion listing. +Specifies that matching @var{completions} are to be added to the set of +matches, but are not to be listed to the user. @item @t{-U} -If this flag is given, all words given will be accepted and no matching +If this flag is given, all @var{completions} are added +to the set of matches and no matching will be done by the completion code. Normally this is used in functions that do the matching themselves. @item @t{-O} @var{array} -If this option is given, the @var{words} are @emph{not} added to the set of -possible completions. Instead, matching is done as usual and all of the -@var{words} given as arguments that match the string on the command line +If this option is given, the @var{completions} are @emph{not} added to the set of +matches. Instead, matching is done as usual and all of the +@var{completions} that match will be stored in the array parameter whose name is given as @var{array}. @item @t{-A} @var{array} -As the @t{-O} option, except that instead of those of the @var{words} which +As the @t{-O} option, except that instead of those of the @var{completions} +which match being stored in @var{array}, the strings generated internally by the -completion code are stored. For example, -with a matching specification of `@t{-M "L:|no="}', the string `@t{nof}' -on the command line and the string `@t{foo}' as one of the @var{words}, this +completion code are stored. For example, +with a match specification of `@t{-M "L:|no="}', a current word of `@t{nof}' +and @var{completions} of `@t{foo}', this option stores the string `@t{nofoo}' in the array, whereas the @t{-O} option stores the `@t{foo}' originally given. @item @t{-D} @var{array} -As with @t{-O}, the @var{words} are not added to the set of possible -completions. Instead, the completion code tests whether each @var{word} -in turn matches what is on the line. If the @var{n}th @var{word} does not +As with @t{-O}, the @var{completions} are not added to the set of matches. +Instead, whenever the @var{n}th @var{completion} does not match, the @var{n}th element of the @var{array} is removed. Elements -for which the corresponding @var{word} is matched are retained. +for which the corresponding @var{completion} matches are retained. +This option can be used more than once to remove elements from multiple +arrays. @item @t{-C} This option adds a special match which expands to all other matches when inserted into the line, even those that are added after this option is used. Together with the @t{-d} option it is possible to -specify a string that should be displayed in the list for this special -match. If no string is given, it will be shown as a string containing -the strings that would be inserted for the other matches, truncated to +specify a string that should be displayed in the list for this special +match. If no string is given, it will be shown as a string containing +the strings that would be inserted for the other matches, truncated to the width of the screen. @item @t{-E} @var{number} -This option adds @var{number} empty matches after the @var{words} have +This option adds @var{number} empty matches after matching @var{completions} have been added. An empty match takes up space in completion listings but will never be inserted in the line and can't be selected with menu completion or menu selection. This makes empty matches only useful to @@ -19801,7 +20006,7 @@ added. @item @t{-} @itemx @t{-}@t{-} This flag ends the list of flags and options. All arguments after it -will be taken as the words to use as matches even if they begin with +will be taken as the @var{completions} even if they begin with hyphens. @end table @@ -19842,7 +20047,7 @@ Without the optional @var{number}, the longest match is taken, but if @var{number} is given, anything up to the @var{number}th match is moved. If the @var{number} is negative, the @var{number}th longest match is moved. For example, if @t{PREFIX} contains the string -`@t{a=b=c}', then @t{compset -P '*\='} will move the string `@t{a=b=}' +`@t{a=b=c}', then @t{compset -P '*\='} will move the string `@t{a=b=}' into the @t{IPREFIX} parameter, but @t{compset -P 1 '*\='} will move only the string `@t{a=}'. @@ -19855,7 +20060,7 @@ As @t{-P}, but match the last portion of @t{SUFFIX} and transfer the matched portion to the front of the value of @t{ISUFFIX}. @item @t{-n} @var{begin} [ @var{end} ] -If the current word position as specified by the parameter @t{CURRENT} +If the current word position as specified by the parameter @t{CURRENT} is greater than or equal to @var{begin}, anything up to the @var{begin}th word is removed from the @t{words} array and the value of the parameter @t{CURRENT} is decremented by @var{begin}. @@ -19881,7 +20086,7 @@ point to the same word in the changed array. If the optional pattern @var{end-pat} is also given, and there is an element in the @t{words} array matching this pattern, the parameters are modified only if the index of this word is higher than the one -given by the @t{CURRENT} parameter (so that the matching word has +given by the @t{CURRENT} parameter (so that the matching word has to be after the cursor). In this case, the words starting with the one matching @t{end-pat} are also removed from the @t{words} array. If @t{words} contains no word matching @var{end-pat}, the @@ -19890,7 +20095,7 @@ testing and modification is performed as if it were not given. @item @t{-q} The word currently being completed is split on spaces into separate words, -respecting the usual shell quoting conventions. The +respecting the usual shell quoting conventions. The resulting words are stored in the @t{words} array, and @t{CURRENT}, @t{PREFIX}, @t{SUFFIX}, @t{QIPREFIX}, and @t{QISUFFIX} are modified to reflect the word part that is completed. @@ -19954,7 +20159,7 @@ true if the test for the @t{-P} option of @t{compset} would succeed. true if the test for the @t{-S} option of @t{compset} would succeed. @item @t{-after} @var{beg-pat} -true if the test of the @t{-N} option with only the @var{beg-pat} given +true if the test of the @t{-N} option with only the @var{beg-pat} given would succeed. @item @t{-between} @var{beg-pat end-pat} @@ -19969,311 +20174,329 @@ true if the test for the @t{-N} option with both patterns would succeed. @noindent @noindent -It is possible by use of the -@t{-M} option of the @t{compadd} builtin command to specify how the -characters in the string to be completed (referred to here as the -command line) map onto the characters in the list of matches produced by -the completion code (referred to here as the trial completions). Note -that this is not used if the command line contains a glob pattern and -the @t{GLOB_COMPLETE} option is set or the @t{pattern_match} of the -@t{compstate} special association is set to a non-empty string. +When the user invokes completion, the current @emph{word} on the command line +(that is, the word the cursor is currently on) is used to generate a @emph{match +pattern}. Only those @emph{completions} that match the pattern are offered to the +user as @emph{matches}. @noindent -The @var{match-spec} given as the argument to the @t{-M} option (see -@ref{Completion Builtin Commands}) consists of one or more matching descriptions separated by -whitespace. Each description consists of a letter followed by a colon -and then the patterns describing which character sequences on the line match -which character sequences in the trial completion. Any sequence of -characters not handled in this fashion must match exactly, as usual. +The default match pattern is generated from the current word by either @noindent -The forms of @var{match-spec} understood are as follows. In each case, the -form with an upper case initial character retains the string already -typed on the command line as the final result of completion, while with -a lower case initial character the string on the command line is changed -into the corresponding part of the trial completion. +@itemize @bullet + +@item +appending a `@t{*}' (matching any number of characters in a completion) +@emph{or,} +@item +if the shell option @t{COMPLETE_IN_WORD} is set, inserting a `@t{*}' at the +cursor position. +@end itemize @noindent -@table @asis -@item @t{m:}@var{lpat}@t{=}@var{tpat} -@itemx @t{M:}@var{lpat}@t{=}@var{tpat} -Here, @var{lpat} is a pattern that matches on the command line, -corresponding to @var{tpat} which matches in the trial completion. +This narrow pattern can be broadened selectively by passing a @emph{match +specification} to the @t{compadd} builtin command through its @t{-M} option +(see +@ref{Completion Builtin Commands}). A match specification consists of one or more @var{matchers} separated by +whitespace. Matchers in a match specification are applied one at a time, from +left to right. Once all matchers have been applied, completions are compared +to the final match pattern and non-matching ones are discarded. -@item @t{l:}@var{lanchor}@t{|}@var{lpat}@t{=}@var{tpat} -@itemx @t{L:}@var{lanchor}@t{|}@var{lpat}@t{=}@var{tpat} -@itemx @t{l:}@var{lanchor}@t{||}@var{ranchor}@t{=}@var{tpat} -@itemx @t{L:}@var{lanchor}@t{||}@var{ranchor}@t{=}@var{tpat} -@itemx @t{b:}@var{lpat}@t{=}@var{tpat} -@itemx @t{B:}@var{lpat}@t{=}@var{tpat} -These letters are for patterns that are anchored by another pattern on -the left side. Matching for @var{lpat} and @var{tpat} is as for @t{m} and -@t{M}, but the pattern @var{lpat} matched on the command line must be -preceded by the pattern @var{lanchor}. The @var{lanchor} can be blank to -anchor the match to the start of the command line string; otherwise the -anchor can occur anywhere, but must match in both the command line and -trial completion strings. +@noindent +@itemize @bullet + +@item +Note that the @t{-M} option is ignored if the current word contains a glob +pattern and the shell option @t{GLOB_COMPLETE} is set or if the +@t{pattern_match} key of the special associative array @t{compstate} is set to +a non-empty value (see +@ref{Completion Special Parameters}). +@item +Users of the @ref{Completion System} should generally not use the @t{-M} option directly, but rather use the +@t{matcher-list} and @t{matcher} styles (see the subsection @emph{Standard Styles} +in +@ref{Completion System Configuration}). +@end itemize @noindent -If no @var{lpat} is given but a @var{ranchor} is, this matches the gap -between substrings matched by @var{lanchor} and @var{ranchor}. Unlike -@var{lanchor}, the @var{ranchor} only needs to match the trial -completion string. +Each matcher consists of @noindent -The @t{b} and @t{B} forms are similar to @t{l} and @t{L} with an empty -anchor, but need to match only the beginning of the word on the command line -or trial completion, respectively. +@itemize @bullet -@item @t{r:}@var{lpat}@t{|}@var{ranchor}@t{=}@var{tpat} -@itemx @t{R:}@var{lpat}@t{|}@var{ranchor}@t{=}@var{tpat} -@itemx @t{r:}@var{lanchor}@t{||}@var{ranchor}@t{=}@var{tpat} -@itemx @t{R:}@var{lanchor}@t{||}@var{ranchor}@t{=}@var{tpat} -@itemx @t{e:}@var{lpat}@t{=}@var{tpat} -@itemx @t{E:}@var{lpat}@t{=}@var{tpat} -As @t{l}, @t{L}, @t{b} and @t{B}, with the difference that the command -line and trial completion patterns are anchored on the right side. -Here an empty @var{ranchor} and the @t{e} and @t{E} forms force the -match to the end of the command line or trial completion string. +@item +a case-sensitive letter +@item +a `@t{:}', +@item +one or more patterns separated by pipes (`@t{|}'), +@item +an equals sign (`@t{=}'), and +@item +another pattern. +@end itemize -@item @t{x:} -This form is used to mark the end of matching specifications: -subsequent specifications are ignored. In a single standalone list -of specifications this has no use but where matching specifications -are accumulated, such as from nested function calls, it can allow one -function to override another. +@noindent +The patterns before the `@t{=}' are used to match substrings of the current +word. For each matched substring, the corresponding part of the match pattern +is broadened with the pattern after the `@t{=}', by means of a logical @t{OR}. -@end table +@noindent +Each pattern in a matcher cosists of either @noindent -Each @var{lpat}, @var{tpat} or @var{anchor} is either an empty string or -consists of a sequence of literal characters (which may be quoted with a -backslash), question marks, character classes, and correspondence -classes; ordinary shell patterns are not used. Literal characters match -only themselves, question marks match any character, and character -classes are formed as for globbing and match any character in the given -set. +@itemize @bullet + +@item +the empty string or +@item +a sequence of @noindent -Correspondence classes are defined like character classes, but with two -differences: they are delimited by a pair of braces, and negated classes -are not allowed, so the characters @t{!} and @t{^} have no special -meaning directly after the opening brace. They indicate that a range of -characters on the line match a range of characters in the trial -completion, but (unlike ordinary character classes) paired according to -the corresponding position in the sequence. For example, to make any -ASCII lower case letter on the line match the corresponding upper case -letter in the trial completion, you can use `@t{m:@{a-z@}=@{A-Z@}}' -(however, see below for the recommended form for this). More -than one pair of classes can occur, in which case the first class before -the @t{=} corresponds to the first after it, and so on. If one side has -more such classes than the other side, the superfluous classes behave -like normal character classes. In anchor patterns correspondence classes -also behave like normal character classes. - -@noindent -The standard `@t{[:}@var{name}@t{:]}' forms described for standard shell -patterns (see -@ref{Filename Generation}) -may appear in correspondence classes as well as normal character -classes. The only special behaviour in correspondence classes is if -the form on the left and the form on the right are each one of -@t{[:upper:]}, @t{[:lower:]}. In these cases the -character in the word and the character on the line must be the same up -to a difference in case. Hence to make any lower case character on the -line match the corresponding upper case character in the trial -completion you can use `@t{m:@{[:lower:]@}=@{[:upper:]@}}'. Although the -matching system does not yet handle multibyte characters, this is likely -to be a future extension, at which point this syntax will handle -arbitrary alphabets; hence this form, rather than the use of explicit -ranges, is the recommended form. In other cases -`@t{[:}@var{name}@t{:]}' forms are allowed. If the two forms on the left -and right are the same, the characters must match exactly. In remaining -cases, the corresponding tests are applied to both characters, but they -are not otherwise constrained; any matching character in one set goes -with any matching character in the other set: this is equivalent to the -behaviour of ordinary character classes. - -@noindent -The pattern @var{tpat} may also be one or two stars, `@t{*}' or -`@t{**}'. This means that the pattern on the command line can match -any number of characters in the trial completion. In this case the -pattern must be anchored (on either side); in the case of a single -star, the @var{anchor} then determines how much of the trial completion -is to be included --- only the characters up to the next appearance of -the anchor will be matched. With two stars, substrings matched by the -anchor can be matched, too. +@itemize @bullet + +@item +literal characters (which may be quoted with a `@t{\}'), +@item +question marks (`@t{?}'), +@item +bracket expressions (`@t{[...]}'; see the subsection @emph{Glob Operators} in +@ref{Filename Generation}), and/or +@item +brace expressions (see below). +@end itemize + +@end itemize @noindent -Examples: +Other shell patterns are not allowed. @noindent -The keys of the @t{options} association defined by the @t{parameter} -module are the option names in all-lower-case form, without -underscores, and without the optional @t{no} at the beginning even -though the builtins @t{setopt} and @t{unsetopt} understand option names -with upper case letters, underscores, and the optional @t{no}. The -following alters the matching rules so that the prefix @t{no} and any -underscore are ignored when trying to match the trial completions -generated and upper case letters on the line match the corresponding -lower case letters in the words: +A brace expression, like a bracket expression, consists of a list of @noindent -@example -compadd -M 'L:|[nN][oO]= M:_= M:@{[:upper:]@}=@{[:lower:]@}' - \ - $@{(k)options@} -@end example +@itemize @bullet + +@item +literal characters, +@item +ranges (`@t{0-9}'), and/or +@item +character classes (`@t{[:}@var{name}@t{:]}'). +@end itemize @noindent -The first part says that the pattern `@t{[nN][oO]}' at the beginning -(the empty anchor before the pipe symbol) of the string on the -line matches the empty string in the list of words generated by -completion, so it will be ignored if present. The second part does the -same for an underscore anywhere in the command line string, and the -third part uses correspondence classes so that any -upper case letter on the line matches the corresponding lower case -letter in the word. The use of the upper case forms of the -specification characters (@t{L} and @t{M}) guarantees that what has -already been typed on the command line (in particular the prefix -@t{no}) will not be deleted. +However, they differ from each other as follows: @noindent -Note that the use of @t{L} in the first part means that it matches -only when at the beginning of both the command line string and the -trial completion. I.e., the string `@t{_NO_f}' would not be -completed to `@t{_NO_foo}', nor would `@t{NONO_f}' be completed to -`@t{NONO_foo}' because of the leading underscore or the second -`@t{NO}' on the line which makes the pattern fail even though they are -otherwise ignored. To fix this, one would use `@t{B:[nN][oO]=}' -instead of the first part. As described above, this matches at the -beginning of the trial completion, independent of other characters or -substrings at the beginning of the command line word which are ignored -by the same or other @var{match-spec}s. +@itemize @bullet + +@item +A brace expression is delimited by a pair of braces (`@t{@{...@}}'). +@item +Brace expressions do not support negations. That is, an initial +`@t{!}' or `@t{^}' has no special meaning and will be interpreted as a literal +character. +@item +When a character in the current word matches the @var{n}th pattern in a brace +expression, the corresponding part of the match pattern is broadened only with +the @var{n}th pattern of the brace expression on the other side of the `@t{=}', +if there is one; if there is no brace expression on the other side, then this +pattern is the empty string. However, if either brace expression has more +elements than the other, then the excess entries are simply ignored. When +comparing indexes, each literal character or character class counts as one +element, but each range is instead expanded to the full list of literal +characters it represents. Additionally, if on @emph{both} sides of the +`@t{=}', the @var{n}th pattern is `@t{[:upper:]}' or `@t{[:lower:]}', then these +are expanded as ranges, too. +@end itemize @noindent -The second example makes completion case insensitive. This is just -the same as in the option example, except here we wish to retain the -characters in the list of completions: +Note that, although the matching system does not yet handle multibyte +characters, this is likely to be a future extension. Hence, using +`@t{[:upper:]}' and `@t{[:lower:]}' is recommended over +`@t{A-Z}' and `@t{a-z}'. @noindent -@example -compadd -M 'm:@{[:lower:]@}=@{[:upper:]@}' ... -@end example +Below are the different forms of matchers supported. Each @emph{uppercase} form +behaves exactly like its lowercase counterpart, but adds an additional step +@emph{after} the match pattern has filtered out non-matching completions: Each of +a match's substrings that was matched by a subpattern from an uppercase matcher +is replaced with the corresponding substring of the current word. However, +patterns from @emph{lowercase} matchers have higher weight: If a substring of the +current word was matched by patterns from both a lowercase and an uppercase +matcher, then the lowercase matcher's pattern wins and the corresponding part +of the match is not modified. @noindent -This makes lower case letters match their upper case counterparts. -To make upper case letters match the lower case forms as well: +Unless indicated otherwise, each example listed assumes @t{COMPLETE_IN_WORD} to +be unset (as it is by default). @noindent -@example -compadd -M 'm:@{[:lower:][:upper:]@}=@{[:upper:][:lower:]@}' ... -@end example +@table @asis +@item @t{m:}@var{word-pat}@t{=}@var{match-pat} +@itemx @t{M:}@var{word-pat}@t{=}@var{match-pat} @noindent -A nice example for the use of @t{*} patterns is partial word -completion. Sometimes you would like to make strings like `@t{c.s.u}' -complete to strings like `@t{comp.source.unix}', i.e. the word on the -command line consists of multiple parts, separated by a dot in this -example, where each part should be completed separately --- note, -however, that the case where each part of the word, i.e. `@t{comp}', -`@t{source}' and `@t{unix}' in this example, is to be completed from -separate sets of matches -is a different problem to be solved by the implementation of the -completion widget. The example can be handled by: +For each substring of the current word that matches @var{word-pat}, broaden the +corresponding part of the match pattern to additionally match @var{match-pat}. @noindent -@example -compadd -M 'r:|.=* r:|=*' \ - - comp.sources.unix comp.sources.misc ... -@end example +@table @asis +@item Examples: @noindent -The first specification says that @var{lpat} is the empty string, while -@var{anchor} is a dot; @var{tpat} is @t{*}, so this can match anything -except for the `@t{.}' from the anchor in -the trial completion word. So in `@t{c.s.u}', the matcher sees `@t{c}', -followed by the empty string, followed by the anchor `@t{.}', and -likewise for the second dot, and replaces the empty strings before the -anchors, giving `@t{c}[@t{omp}]@t{.s}[@t{ources}]@t{.u}[@t{nix}]', where -the last part of the completion is just as normal. +@t{m:@{[:lower:]@}=@{[:upper:]@}} lets any lower case character in the current word +be completed to itself or its uppercase counterpart. So, the completions +`@t{foo}', `@t{FOO}' and `@t{Foo}' will are be considered matches for the word +`@t{fo}'. @noindent -With the pattern shown above, the string `@t{c.u}' could not be -completed to `@t{comp.sources.unix}' because the single star means -that no dot (matched by the anchor) can be skipped. By using two stars -as in `@t{r:|.=**}', however, `@t{c.u}' could be completed to -`@t{comp.sources.unix}'. This also shows that in some cases, -especially if the anchor is a real pattern, like a character class, -the form with two stars may result in more matches than one would like. +@t{M:_=} inserts every underscore from the current word into each match, in the +same relative position, determined by matching the substrings around it. So, +given a completion `@t{foo}', the word `@t{f_o}' will be completed to the match +`@t{f_oo}', even though the latter was not present as a completion. + +@end table + +@item @t{b:}@var{word-pat}@t{=}@var{match-pat} +@itemx @t{B:}@var{word-pat}@t{=}@var{match-pat} +@itemx @t{e:}@var{word-pat}@t{=}@var{match-pat} +@itemx @t{E:}@var{word-pat}@t{=}@var{match-pat} @noindent -The second specification is needed to make this work when the cursor is -in the middle of the string on the command line and the option -@t{COMPLETE_IN_WORD} is set. In this case the completion code would -normally try to match trial completions that end with the string as -typed so far, i.e. it will only insert new characters at the cursor -position rather than at the end. However in our example we would like -the code to recognise matches which contain extra characters after the -string on the line (the `@t{nix}' in the example). Hence we say that the -empty string at the end of the string on the line matches any characters -at the end of the trial completion. +For each consecutive substring at the @t{b:}eginning or @t{e:}nd of the current +word that matches @var{word-pat}, broaden the corresponding part of the match +pattern to additionally match @var{match-pat}. @noindent -More generally, the specification +@table @asis +@item Examples: @noindent -@example -compadd -M 'r:|[.,_-]=* r:|=*' ... -@end example +`@t{b:-=+}' lets any number of minuses at the start of the current word be +completed to a minus or a plus. @noindent -allows one to complete words with abbreviations before any of the -characters in the square brackets. For example, to -complete @t{veryverylongfile.c} rather than @t{veryverylongheader.h} -with the above in effect, you can just type @t{very.c} before attempting -completion. +`@t{B:0=}' adds all zeroes at the beginning of the current word to the +beginning of each match. + +@end table + +@item @t{l:}@t{|}@var{word-pat}@t{=}@var{match-pat} +@itemx @t{L:}@t{|}@var{word-pat}@t{=}@var{match-pat} +@itemx @t{R:}@var{word-pat}@t{|}@t{=}@var{match-pat} +@itemx @t{r:}@var{word-pat}@t{|}@t{=}@var{match-pat} @noindent -The specifications with both a left and a right anchor are useful to -complete partial words whose parts are not separated by some -special character. For example, in some places strings have to be -completed that are formed `@t{LikeThis}' (i.e. the separate parts are -determined by a leading upper case letter) or maybe one has to -complete strings with trailing numbers. Here one could use the simple -form with only one anchor as in: +If there is a substring at the @t{l:}eft or @t{r:}ight edge of the current word +that matches @var{word-pat}, then broaden the corresponding part of the match +pattern to additionally match @var{match-pat}. @noindent -@example -compadd -M 'r:|[[:upper:]0-9]=* r:|=*' LikeTHIS FooHoo 5foo123 5bar234 -@end example +For each @t{l:}, @t{L:}, @t{r:} and @t{R:} matcher (including the ones below), +the pattern @var{match-pat} may also be a `@t{*}'. This matches any number of +characters in a completion. @noindent -But with this, the string `@t{H}' would neither complete to `@t{FooHoo}' -nor to `@t{LikeTHIS}' because in each case there is an upper case -letter before the `@t{H}' and that is matched by the anchor. Likewise, -a `@t{2}' would not be completed. In both cases this could be changed -by using `@t{r:|[[:upper:]0-9]=**}', but then `@t{H}' completes to both -`@t{LikeTHIS}' and `@t{FooHoo}' and a `@t{2}' matches the other -strings because characters can be inserted before every upper case -letter and digit. To avoid this one would use: +@table @asis +@item Examples: @noindent -@example -compadd -M 'r:[^[:upper:]0-9]||[[:upper:]0-9]=** r:|=*' \ - LikeTHIS FooHoo foo123 bar234 -@end example +`@t{r:|=*}' appends a `@t{*}' to the match pattern, even when +@t{COMPLETE_IN_WORD} is set and the cursor is not at the end of the current +word. + +@noindent +If the current word starts with a minus, then `@t{L:|-=}' will prepend it to +each match. + +@end table + +@item @t{l:}@var{anchor}@t{|}@var{word-pat}@t{=}@var{match-pat} +@itemx @t{L:}@var{anchor}@t{|}@var{word-pat}@t{=}@var{match-pat} +@itemx @t{r:}@var{word-pat}@t{|}@var{anchor}@t{=}@var{match-pat} +@itemx @t{R:}@var{word-pat}@t{|}@var{anchor}@t{=}@var{match-pat} + +@noindent +For each substring of the current word that matches @var{word-pat} and has on +its @t{l:}eft or @t{r:}ight another substring matching @var{anchor}, broaden the +corresponding part of the match pattern to additionally match @var{match-pat}. + +@noindent +Note that these matchers (and the ones below) modify only what is matched by +@var{word-pat}; they do not change the matching behavior of what is matched by +@var{anchor} (or @var{coanchor}; see the matchers below). Thus, unless its +corresponding part of the match pattern has been modified, the anchor in the +current word has to match literally in each completion, just like any other +substring of the current word. + +@noindent +If a matcher includes at least one anchor (which includes the matchers with two +anchors, below), then @var{match-pat} may also be `@t{*}' or `@t{**}'. `@t{*}' +can match any part of a completion that does not contain any substrings +matching @var{anchor}, whereas a `@t{**}' can match any part of a completion, +period. (Note that this is different from the behavior of `@t{*}' in the +anchorless forms of `@t{l:}' and `@t{r:}' and and also different from `@t{*}' +and `@t{**}' in glob expressions.) @noindent -By using these two anchors, a `@t{H}' matches only upper case `@t{H}'s that -are immediately preceded by something matching the left anchor -`@t{[^[:upper:]0-9]}'. The effect is, of course, that `@t{H}' matches only -the string `@t{FooHoo}', a `@t{2}' matches only `@t{bar234}' and so on. +@table @asis +@item Examples: @noindent -When using the completion system (see -@ref{Completion System}), users can define match specifications that are to be used for -specific contexts by using the @t{matcher} and @t{matcher-list} -styles. The values for the latter will be used everywhere. +`@t{r:|.=*}' makes the completion `@t{comp.sources.unix}' a match for the word +`@t{..u}' --- but @emph{not} for the word `@t{.u}'. + +@noindent +Given a completion `@t{-}@t{-foo}', the matcher `@t{L:--|no-=}' will complete +the word `@t{-}@t{-no-}' to the match `@t{-}@t{-no-foo}'. + +@end table + +@item @t{l:}@var{anchor}@t{||}@var{coanchor}@t{=}@var{match-pat} +@itemx @t{L:}@var{anchor}@t{||}@var{coanchor}@t{=}@var{match-pat} +@itemx @t{r:}@var{coanchor}@t{||}@var{anchor}@t{=}@var{match-pat} +@itemx @t{R:}@var{coanchor}@t{||}@var{anchor}@t{=}@var{match-pat} + +@noindent +For any two consecutive substrings of the current word that match @var{anchor} +and @var{coanchor}, in the order given, insert the pattern @var{match-pat} +between their corresponding parts in the match pattern. + +@noindent +Note that, unlike @var{anchor}, the pattern @var{coanchor} does not change what +`@t{*}' can match. + +@noindent +@table @asis +@item Examples: + +@noindent +`@t{r:?||[[:upper:]]=*}' will complete the current word `@t{fB}' to +`@t{fooBar}', but it will not complete it to `@t{fooHooBar}' (because `@t{*}' +here cannot match anything that includes a match for `@t{[[:upper:]]}), nor +will it complete `@t{B}' to `@t{fooBar}' (because there is no character in the +current word to match @var{coanchor}). + +@noindent +Given the current word `@t{pass.n}' and a completion `@t{pass.byname}', the +matcher `@t{L:.||[[:alpha:]]=by}' will produce the match `@t{pass.name}'. + +@end table + +@item @t{x:} + +@noindent +Ignore this matcher and all matchers to its right. + +@noindent +This matcher is used to mark the end of a match specification. In a single +standalone list of matchers, this has no use, but where match specifications +are concatenated, as is often the case when using the +@ref{Completion System}, it can allow one match specification to override another. + +@end table @noindent @node Completion Widget Example, , Completion Matching Control, Completion Widgets @@ -20310,7 +20533,7 @@ complete-files () @{ compadd - * @} @end example @noindent -This function will complete files in the current directory matching the +This function will complete files in the current directory matching the current word. @c (avoiding a yodl bug) @c Yodl file: Zsh/compsys.yo @@ -20537,7 +20760,7 @@ root or by the current user. If such files or directories are found, avoid these tests and make all files found be used without asking, use the option @t{-u}, and to make @t{compinit} silently ignore all insecure files and directories use the option @t{-i}. This security check is skipped -entirely when the @t{-C} option is given. +entirely when the @t{-C} option is given, provided the dumpfile exists. @noindent @findex compaudit @@ -20688,15 +20911,15 @@ The special contexts for which completion functions can be defined are: The right hand side of an array-assignment (`@var{name}@t{=(}@var{...}@t{)}') -@kindex -brace-parameter-, completion context -@item @t{-brace-parameter-} -The name of a parameter expansion within braces (`@t{$@{}@var{...}@t{@}}') - @kindex -assign-parameter-, completion context @item @t{-assign-parameter-} The name of a parameter in an assignment, i.e. on the left hand side of an `@t{=}' +@kindex -brace-parameter-, completion context +@item @t{-brace-parameter-} +The name of a parameter expansion within braces (`@t{$@{}@var{...}@t{@}}') + @kindex -command-, completion context @item @t{-command-} A word in command position @@ -21089,8 +21312,8 @@ described in When looking up styles the completion system uses full context names, including the tag. Looking up the value of a style therefore consists of two things: the context, which is matched to the most specific (best -fitting) style pattern, and the name of the style itself, which must be -matched exactly. The following examples demonstrate that style patterns +fitting) pattern, and the name of the style itself, which must be +matched exactly. The following examples demonstrate that patterns may be loosely defined for styles that apply broadly, or as tightly defined as desired for styles that apply in narrower circumstances. @@ -21109,7 +21332,7 @@ zstyle ':completion:*' verbose yes in a startup file (probably @t{.zshrc}). This gives the @t{verbose} style the value @t{yes} in every context inside the completion system, unless that context has a more -specific definition. It is best to avoid giving the context as `@t{*}' +specific definition. It is best to avoid giving the pattern as `@t{*}' in case the style has some meaning outside the completion system. @noindent @@ -21159,16 +21382,22 @@ as @t{menu} and @t{list-rows-first}. @noindent Note that the order in which styles are @emph{defined} does not matter; the style mechanism uses the most specific possible match for a particular -style to determine the set of values. More precisely, strings are +style to determine the set of values. Strings are preferred over patterns (for example, `@t{:completion::complete:::foo}' is more specific than `@t{:completion::complete:::*'}), and longer patterns are -preferred over shorter patterns. +preferred over the pattern `@t{*}'. See +@ref{The zsh/zutil Module} +for details. @noindent -A good rule of thumb is that any completion style pattern that needs to -include more than one wildcard (@t{*}) and that does not end in a tag -name, should include all six colons (@t{:}), possibly surrounding -additional wildcards. +Context patterns that use something other than a wildcard (@t{*}) to match the +middle parts of the context --- the @var{completer}, @var{command}, and +@var{argument} in +@t{:completion:}@var{function}@t{:}@var{completer}@t{:}@var{command}@t{:}@var{argument}@t{:}@var{tag} +--- should include all six colons (@t{:}) explicitly. Without this, +a pattern such as @t{:completion:*:foo:*} could match @t{foo} against a +component other than the intended one (for example, against @var{completer} when +a match against @var{command} was intended). @noindent Style names like those of tags are arbitrary and depend on the completion @@ -21341,14 +21570,14 @@ for hostnames @item @t{indexes} for array indexes -@kindex jobs, completion tag -@item @t{jobs} -for jobs (as listed by the `@t{jobs}' builtin) - @kindex interfaces, completion tag @item @t{interfaces} for network interfaces +@kindex jobs, completion tag +@item @t{jobs} +for jobs (as listed by the `@t{jobs}' builtin) + @kindex keymaps, completion tag @item @t{keymaps} for names of zsh keymaps @@ -21372,14 +21601,14 @@ directory when completing arguments of @t{cd} and related builtin commands (compare @t{path-directories}) --- when the @t{cdpath} array is unset, @t{directories} is used instead -@kindex manuals, completion tag -@item @t{manuals} -for names of manual pages - @kindex mailboxes, completion tag @item @t{mailboxes} for e-mail folders +@kindex manuals, completion tag +@item @t{manuals} +for names of manual pages + @kindex maps, completion tag @item @t{maps} for map names (e.g. NIS maps) @@ -21429,11 +21658,6 @@ offering the original string as a match @item @t{other-accounts} used to look up the @t{users-hosts} style -@kindex other-files, completion tag -@item @t{other-files} -for the names of any non-directory files. This is used instead -of @t{all-files} when the @t{list-dirs-first} style is in effect. - @kindex packages, completion tag @item @t{packages} for packages (e.g. @t{rpm} or installed @t{Debian} packages) @@ -21871,6 +22095,12 @@ components after the first ambiguous one will also be added. This means that the resulting string is the longest unambiguous string possible. However, menu completion can be used to cycle through all matches. +@kindex extra-verbose, completion style +@item @t{extra-verbose} +If set, the completion listing is more verbose at the cost of +a probable decrease in completion speed. Completion performance +will suffer if this style is set to `true'. + @kindex fake, completion style @item @t{fake} This style may be set for any completion context. It @@ -22030,9 +22260,10 @@ If no `@t{:}@var{tag}' is given the `@t{files}' tag will be used. The @var{tag} may also be followed by an optional second colon and a description, which will be used for the `@t{%d}' in the value of the @t{format} style (if that is set) instead of the default -description supplied by the completion function. If the description -given here contains itself a `@t{%d}', that is replaced with the -description supplied by the completion function. +description supplied by the completion function. The inclusion +of a description also gives precedence to associated options such as +for completion grouping so it can be used where files should be +separated. @noindent For example, to make the @t{rm} command first complete only names of @@ -22064,6 +22295,19 @@ sees this pattern. Note also it will never try a pattern more than once for a single completion attempt. @noindent +To separate directories into a separate group from the files but still +complete them at the first attempt, a description needs to be given. +Note that directories need to be explicitly excluded from the +globbed-files because `@t{*}' will match directories. For grouping, it +is also necessary to set the @t{group-name} style. + +@noindent +@example +zstyle ':completion:*' file-patterns \ + '%p(^-/):globbed-files *(-/):directories:location' +@end example + +@noindent During the execution of completion functions, the @t{EXTENDED_GLOB} option is in effect, so the characters `@t{#}', `@t{~}' and `@t{^}' have special meanings in the patterns. @@ -22160,6 +22404,15 @@ and similar escape sequences. This is handled by the @t{zformat} builtin command from the @t{zsh/zutil} module, see @ref{The zsh/zutil Module}. +@kindex gain-privileges, completion style +@item @t{gain-privileges} +If set to @t{true}, this style enables the use of commands like @t{sudo} +or @t{doas} to gain extra privileges when retrieving information for +completion. This is only done when a command such as @t{sudo} appears on +the command-line. To force the use of, e.g. @t{sudo} or to override any +prefix that might be added due to @t{gain-privileges}, the @t{command} +style can be used with a value that begins with a hyphen. + @kindex glob, completion style @item @t{glob} This is used by the @t{_expand} completer. If @@ -22208,6 +22461,10 @@ zstyle ':completion:*' group-name @value{dsq} All matches for which no group name is defined will be put in a group named @t{-default-}. +@noindent +To display the group name in the output, see the @t{format} style (q.v.) +under the @t{descriptions} tag. + @kindex group-order, completion style @item @t{group-order} This style is additional to the @t{group-name} style to specify the @@ -22323,12 +22580,6 @@ Excluded values act in a similar fashion to values of the @t{ignored-patterns} style, so they can be restored to consideration by the @t{_ignored} completer. -@kindex extra-verbose, completion style -@item @t{extra-verbose} -If set, the completion listing is more verbose at the cost of -a probable decrease in completion speed. Completion performance -will suffer if this style is set to `true'. - @kindex ignored-patterns, completion style @item @t{ignored-patterns} A list of patterns; any trial completion matching one of the patterns @@ -22367,6 +22618,35 @@ be unsuccessful until that point. If the value is any other string, menu completion will be started when the string typed by the user is longer than the common prefix to the corresponding IDs. +@kindex insert-sections, completion style +@item @t{insert-sections} +This style is used with tags of the form `@t{manuals.}@var{X}' when +completing names of manual pages. If set and the @var{X} in the tag name matches +the section number of the page being completed, the section number is inserted +along with the page name. For example, given + +@noindent +@example +zstyle ':completion:*:manuals.*' insert-sections true +@end example + +@noindent +@t{man ssh_<TAB>} may be completed to @t{man 5 ssh_config}. + +@noindent +The value may also be set to one of `@t{prepend}', or `@t{suffix}'. +`@t{prepend}' behaves the same as `true' as in the above example, while +`@t{suffix}' would complete @t{man ssh_<TAB>} as @t{man ssh_config.5}. + +@noindent +This is especially useful in conjunction with @t{separate-sections}, as +it ensures that the page requested of @t{man} corresponds to the one +displayed in the completion listing when there are multiple pages with the +same name (e.g., @t{printf(1)} and @t{printf(3)}). + +@noindent +The default for this style is `false'. + @kindex insert-tab, completion style @item @t{insert-tab} If this is set to `true', the completion system will @@ -22409,15 +22689,6 @@ In the case of the @t{_match} completer, the style may also be set to the string `@t{pattern}'. Then the pattern on the line is left unchanged if it does not match unambiguously. -@kindex gain-privileges, completion style -@item @t{gain-privileges} -If set to @t{true}, this style enables the use of commands like @t{sudo} -or @t{doas} to gain extra privileges when retrieving information for -completion. This is only done when a command such as @t{sudo} appears on -the command-line. To force the use of, e.g. @t{sudo} or to override any -prefix that might be added due to @t{gain-privileges}, the @t{command} -style can be used with a value that begins with a hyphen. - @kindex keep-prefix, completion style @item @t{keep-prefix} This style is used by the @t{_expand} completer. If it is `true', the @@ -22434,6 +22705,13 @@ The behaviour of @t{_expand} when this style is `true' is to cause @t{_expand} to give up when a single expansion with the restored prefix is the same as the original; hence any remaining completers may be called. +@kindex known-hosts-files +@item @t{known-hosts-files} +This style should contain a list of files to search for host names and +(if the @t{use-ip} style is set) IP addresses in a format compatible with +ssh @t{known_hosts} files. If it is not set, the files +@t{/etc/ssh/ssh_known_hosts} and @t{~/.ssh/known_hosts} are used. + @kindex last-prompt, completion style @item @t{last-prompt} This is a more flexible form of the @t{ALWAYS_LAST_PROMPT} option. @@ -22445,13 +22723,6 @@ previous line if this style is `true' for all types of match. Note that unlike the @t{ALWAYS_LAST_PROMPT} option this is independent of the numeric argument. -@kindex known-hosts-files -@item @t{known-hosts-files} -This style should contain a list of files to search for host names and -(if the @t{use-ip} style is set) IP addresses in a format compatible with -ssh @t{known_hosts} files. If it is not set, the files -@t{/etc/ssh/ssh_known_hosts} and @t{~/.ssh/known_hosts} are used. - @kindex list, completion style @item @t{list} This style is used by the @t{_history_complete_word} bindable command. @@ -22496,11 +22767,10 @@ obtained by setting the style to an empty string (i.e. @t{@value{dsq}}). @kindex list-dirs-first, completion style @item @t{list-dirs-first} -This is used by file completion. If set, directories to be completed -are listed separately from and before completion for other files, -regardless of tag ordering. In addition, the tag @t{other-files} -is used in place of @t{all-files} for the remaining files, to indicate -that no directories are presented with that tag. +This is used by file completion and corresponds to a particular +setting of the @t{file-patterns} style. +If set, the default directories to be completed +are listed separately from and before completion for other files. @kindex list-grouped, completion style @item @t{list-grouped} @@ -22555,6 +22825,12 @@ This style is tested in the same way as the @t{list-packed} style and determines whether matches are to be listed in a rows-first fashion as if the @t{LIST_ROWS_FIRST} option were set. +@kindex list-separator, completion style +@item @t{list-separator} +The value of this style is used in completion listing to separate the +string to complete from a description when possible (e.g. when +completing options). It defaults to `@t{-}@t{-}' (two hyphens). + @kindex list-suffixes, completion style @item @t{list-suffixes} This style is used by the function that completes filenames. If it is @@ -22562,12 +22838,6 @@ This style is used by the function that completes filenames. If it is typed pathname components, all ambiguous components will be shown. Otherwise, completion stops at the first ambiguous component. -@kindex list-separator, completion style -@item @t{list-separator} -The value of this style is used in completion listing to separate the -string to complete from a description when possible (e.g. when -completing options). It defaults to `@t{-}@t{-}' (two hyphens). - @kindex local, completion style @item @t{local} This is for use with functions that complete URLs for which the @@ -23059,7 +23329,7 @@ zstyle ':completion:*' recursive-files '*/zsh/*' @noindent If the current directory is @t{/home/pws/zsh/Src}, then -@t{zle_tr}@emph{TAB} can be completed to @t{Zle/zle_tricky.c}. +@t{zle_tr<TAB>} can be completed to @t{Zle/zle_tricky.c}. @kindex regular, completion style @item @t{regular} @@ -23117,12 +23387,14 @@ The default is to scroll by single lines. @item @t{separate-sections} This style is used with the @t{manuals} tag when completing names of manual pages. If it is `true', entries for different sections are -added separately using tag names of the form `@t{manual.}@var{X}', +added separately using tag names of the form `@t{manuals.}@var{X}', where @var{X} is the section number. When the @t{group-name} style is also in effect, pages from different sections will appear separately. This style is also used similarly with the @t{words} style when completing words for the dict command. It allows words from different -dictionary databases to be added separately. +dictionary databases to be added separately. See also @t{insert-sections}. + +@noindent The default for this style is `false'. @kindex show-ambiguity, completion style @@ -24349,8 +24621,19 @@ described using the @var{spec}s which are of the form: `@var{tag}@t{:}@var{descr}@t{:}@var{action}'. The @var{tag}s are offered using @t{_tags} and if the tag is requested, the @var{action} is executed with the given description @var{descr}. The @var{action}s are those accepted -by the @t{_arguments} function (described below), excluding the -`@t{->}@var{state}' and `@t{=}@var{...}' forms. +by the @t{_arguments} function (described below), with the following +exceptions: +@itemize @bullet + +@item +The `@t{->}@var{state}' and `@t{=}@var{...}' forms are not supported. + +@item +The `@t{((a\:bar b\:baz}@t{))}' form does not need +the colon to be escaped, since the @var{spec}s have no colon-separated fields +after the @var{action}. + +@end itemize @noindent For example, the @var{action} may be a simple function call: @@ -24502,6 +24785,12 @@ The default @var{matchspec} allows partial word completion after `@t{_}' and @t{r:|[_-]=* r:|=*} @end example +@item @t{-0} +When populating values of the `@t{opt_args}' associative array, don't +backslash-escape colons and backslashes and use NUL rather than colon for +joining multiple values. This option is described in more detail below, under +the heading @emph{@var{spec}s: actions}. + @end table @noindent @@ -24695,6 +24984,7 @@ used, and on subsequent calls `@t{_arguments !$^global_options}'. @noindent @emph{@var{spec}s: actions} + @noindent In each of the forms above the @var{action} determines how completions should be generated. Except for the `@t{->}@var{string}' @@ -24836,9 +25126,29 @@ the normal arguments from the command line, i.e. the words from the command line after the command name excluding all options and their arguments. Options are stored in the associative array `@t{opt_args}' with option names as keys and their arguments as -the values. For options that have more than one argument these are -given as one string, separated by colons. All colons and backslashes -in the original arguments are preceded with backslashes. +the values. By default, all colons and backslashes in the value are escaped +with backslashes, and if an option has multiple arguments (for example, when +using an @var{optspec} of the form `@t{*}@var{optspec}'), they are joined with +(unescaped) colons. However, if the @t{-0} option was passed, no backslash +escaping is performed, and multiple values are joined with NUL bytes. For +example, after `@t{zsh -o foo:foo -o bar:bar -o <TAB>}', the contents of +`@t{opt_args}' would be + +@noindent +@example +typeset -A opt_args=( [-o]='foo\:foo:bar\:bar:' ) +@end example + +@noindent +by default, and + +@noindent +@example +typeset -A opt_args=( [-o]=$'foo:foo\x00bar:bar\x00' ) +@end example + +@noindent +if @t{_arguments} had been called with the @t{-0} option. @noindent The parameter `@t{context}' is set when returning to the calling function @@ -25112,7 +25422,7 @@ The last two descriptions say what should be completed as arguments. The first describes the first argument as a `@var{postscript file}' and makes files ending in `@t{ps}' or `@t{eps}' be completed. The last description gives all other arguments the -description `@var{page numbers}' but does not offer completions. +description `@var{page number}' but does not offer completions. @findex _cache_invalid @item @t{_cache_invalid} @var{cache_identifier} @@ -25253,6 +25563,15 @@ Include the leading underscore (`@t{_}') in the matches. @end table +@findex _default +@item @t{_default} +This function corresponds to the @t{-default-} special context which is +applied where no completion is defined. It is useful to call it under +certain error conditions such as completion after an unrecognised +subcommand. This applies the concept of graceful degradation to the +completion system, allowing it to fallback on basic completion of +commonly useful things like filenames. + @findex _describe @item @t{_describe }[@t{-12JVx}] [ @t{-oO} | @t{-t} @var{tag} ] @var{descr} @var{name1} [ @var{name2} ] [ @var{opt} ... ] @@ -25336,8 +25655,26 @@ not contain an explanation string to be displayed above the matches. If @t{_description} is called with more than three arguments, the additional @var{spec}s should be of the form `@var{char}@t{:}@var{str}'. These supply escape sequence replacements for the @t{format} style: -every appearance of `@t{%}@var{char}' will be -replaced by @var{string}. +every appearance of `@t{%}@var{char}' will be replaced by @var{string}. +If no additional @var{spec}s are given but the description in @var{descr} +conforms to a common form then further escape sequences are set for +elements of that description. These elements correspond to a default +value (`@t{%o}'), the units (`@t{%m}') range of acceptable values +(`@t{%r}') and the remaining initial part of the description (`@t{%h}'). +The form the description takes consists of specifying the units and +range in parentheses and the default value in square brackets, for +example: + +@noindent +@example +_description times expl 'timeout (seconds) (0-60) [20]' +@end example + +@noindent +It is possible to use @t{zformat} conditional expressions when styling +these elements. So, for example, to add `@t{default:}' as a tag but only +when there is a default value to show, the @t{format} style might +include `@t{%(o.default: %o.)}'. @noindent If the @t{-x} option is given, the description will be passed to @@ -25653,6 +25990,81 @@ checked. If it is set completion is terminated at that point even if no matches have been found. This is the same effect as in the @t{-first-} context. +@findex _numbers +@item @t{_numbers} [ @var{option} ... ] [ @var{description} ] [ @var{suffix} ... ] +This can be used where a number is followed by a suffix to indicate the units. +The unit suffixes are completed and can also be included in the description +used when completion is invoked for the preceding number. + +@noindent +In addition to common @t{compadd} options, @t{_numbers} accepts the following +options: + +@noindent +@table @asis +@item @t{-t} @var{tag} +Specify a tag to use instead of the default of @t{numbers}. + +@item @t{-u} @var{units} +Indicate the default units for the number, e.g. @t{bytes}. + +@item @t{-l} @var{min} +Specify the lowest possible value for the number. + +@item @t{-m} @var{max} +Specify the highest possible value for the number. + +@item @t{-d} @var{default} +Specify the default value. + +@item @t{-N} +Allow negative numbers. This is implied if the range includes a negative. + +@item @t{-f} +Allow decimal numbers. + +@end table + +@noindent +Where a particular suffix represents the default units for a number, it +should be prefixed with a colon. Additionally, suffixes can be followed +by a colon and a description. So for example, the following allows the +age of something to be specified, either in seconds or with an optional +suffix with a longer unit of time: + +@noindent +@example +_numbers -u seconds age :s:seconds m:minutes h:hours d:days +@end example + +@noindent +It is typically helpful for units to be presented in order of magnitude +when completed. To facilitate this, the order in which they are given +is preserved. + +@noindent +When the @t{format} style is looked up with the @t{descriptions} tag or +the tag specified with @t{-t}, the list of suffixes is available as a +`@t{%x}' escape sequence. This is in addition to the usual sequences +documented under the @t{format} style. The form this list takes can also +be configured. To this end, the @t{format} style is first looked up with +the tag @t{unit-suffixes}. The retrieved format is applied to each +suffix in turn and the results are then concatenated to form the +completed list. For the @t{unit-suffixes} format, `@t{%x}' expands to +the individual suffix and `@t{%X}' to its description. @t{%d}' indicates +a default suffix and can be used in a condition. The index and reverse +index are set in `@t{%i}' and `@t{%r}' respectively and are useful for +text included only with the first and last suffixes in the list. So for +example, the following joins the suffixes together as a comma-separated +list: + +@noindent +@example +zstyle ':completion:*:unit-suffixes' format '%x%(r::,)' +@end example + + +@noindent @findex _options @item @t{_options} This can be used to complete the names of shell options. It provides a @@ -26288,10 +26700,14 @@ matches with the given description: @example local expl _wanted tag expl 'description' \ - compadd matches... + compadd -- @var{match1} @var{match2}... @end example @noindent +See also the use of @t{_wanted} in the example function in +@ref{Dynamic named directories}. + +@noindent Note that, as for @t{_requested}, the @var{command} must be able to accept options to be passed down to @t{compadd}. @@ -26334,8 +26750,6 @@ in the @t{_comp_caller_options} associative array. Option names, spelled in lowercase without underscores, are mapped to one or other of the strings `@t{on}' and `@t{off}'. - -@noindent @item @t{_comp_priv_prefix} Completion functions such as @t{_sudo} can set the @t{_comp_priv_prefix} array to a command prefix that may then be used by @t{_call_program} to @@ -26344,6 +26758,8 @@ match the privileges when calling programs to generate matches. @end table @noindent +@vindex compprefuncs, use of +@vindex comppostfuncs, use of Two more features are offered by the @t{_main_complete} function. The arrays @t{compprefuncs} and @t{comppostfuncs} may contain names of functions that are to be called immediately before or after @@ -27288,6 +27704,9 @@ Interface to the termcap database. @item @t{zsh/terminfo} Interface to the terminfo database. +@item @t{zsh/watch} +Reporting of login and logout events. + @item @t{zsh/zftp} A builtin FTP client. @@ -27342,6 +27761,7 @@ styles. * The zsh/net/tcp Module:: * The zsh/termcap Module:: * The zsh/terminfo Module:: +* The zsh/watch Module:: * The zsh/zftp Module:: * The zsh/zle Module:: * The zsh/zleparameter Module:: @@ -28252,7 +28672,7 @@ input. This is only available with the ncurses library; mouse handling can be detected by checking for the exit status of `@t{zcurses mouse}' with no arguments. If a mouse button is clicked (or double- or triple-clicked, or pressed or released with -a configurable delay from being clicked) then @t{kparam} is set to the string +a configurable delay from being clicked) then @var{kparam} is set to the string @t{MOUSE}, and @var{mparam} is set to an array consisting of the following elements: @table @asis @@ -28395,18 +28815,21 @@ The @t{zsh/datetime} module makes available one builtin command: @table @asis @findex strftime @cindex date string, printing -@item @t{strftime} [ @t{-s} @var{scalar} ] @var{format} [ @var{epochtime} [ @var{nanoseconds} ] ] -@itemx @t{strftime} @t{-r} [ @t{-q} ] [ @t{-s} @var{scalar} ] @var{format} @var{timestring} +@item @t{strftime} [ @t{-s} @var{scalar} | @t{-n} ] @var{format} [ @var{epochtime} [ @var{nanoseconds} ] ] +@itemx @t{strftime} @t{-r} [ @t{-q} ] [ @t{-s} @var{scalar} | @t{-n} ] @var{format} @var{timestring} Output the date in the @var{format} specified. With no @var{epochtime}, the current system date/time is used; optionally, @var{epochtime} may be used to specify the number of seconds since the epoch, and @var{nanoseconds} may additionally be used to specify the number of nanoseconds past the second (otherwise that number is assumed to be 0). -See man page strftime(3) for details. The zsh extensions described in +See strftime(3) for details. The zsh extensions described in @ref{Prompt Expansion} are also available. @noindent @table @asis +@item @t{-n} +Suppress printing a newline after the formatted string. + @item @t{-q} Run quietly; suppress printing of all error messages described below. Errors for invalid @var{epochtime} values are always printed. @@ -28415,7 +28838,7 @@ Errors for invalid @var{epochtime} values are always printed. With the option @t{-r} (reverse), use @var{format} to parse the input string @var{timestring} and output the number of seconds since the epoch at which the time occurred. The parsing is implemented by the system -function @t{strptime}; see man page strptime(3). This means that zsh +function @t{strptime}; see strptime(3). This means that zsh format extensions are not available, but for reverse lookup they are not required. @@ -28758,7 +29181,7 @@ directories are first created if necessary, and there will be no complaint if the directory already exists. The @t{-m} option can be used to specify (in octal) a set of file permissions for the created directories, otherwise mode 777 modified by the current -@t{umask} (see man page umask(2)) is used. +@t{umask} (see umask(2)) is used. @findex mv @item @t{mv} [ @t{-fi} ] @var{filename} @var{dest} @@ -28790,7 +29213,7 @@ Removes files and directories specified. @noindent Normally, @t{rm} will not remove directories (except with the @t{-R} or @t{-r} options). The @t{-d} option causes @t{rm} to try removing directories -with @t{unlink} (see man page unlink(2)), the same method used for files. +with @t{unlink} (see unlink(2)), the same method used for files. Typically only the super-user can actually succeed in unlinking directories in this way. @t{-d} takes precedence over @t{-R} and @t{-r}. @@ -28807,7 +29230,7 @@ silently deleted, without querying, and suppresses all error indications. @noindent The @t{-R} and @t{-r} options cause @t{rm} to recursively descend into directories, deleting all files in the directory before removing the directory -with the @t{rmdir} system call (see man page rmdir(2)). +with the @t{rmdir} system call (see rmdir(2)). @noindent The @t{-s} option is a zsh extension to @t{rm} functionality. It enables @@ -28826,7 +29249,7 @@ Removes empty directories specified. @findex sync @item @t{sync} -Calls the system call of the same name (see man page sync(2)), which +Calls the system call of the same name (see sync(2)), which flushes dirty buffers to disk. It might return before the I/O has actually been completed. @@ -28896,7 +29319,7 @@ value is the content of the file. The value is treated identically to any other text coming from a parameter. The value may also be assigned to, in which case the file in question is written (whether or not it originally existed); or an element may be unset, which will delete the file in -question. For example, `@t{vared mapfile[myfile]}' works as expected, +question. For example, `@t{vared 'mapfile[myfile]'}' works as expected, editing the file `@t{myfile}'. @noindent @@ -28992,7 +29415,7 @@ returns an integer. @noindent The function @t{signgam} takes no arguments, and returns an integer, which -is the C variable of the same name, as described in man page gamma(3). Note +is the C variable of the same name, as described in gamma(3). Note that it is therefore only useful immediately after a call to @t{gamma} or @t{lgamma}. Note also that `@t{signgam()}' and `@t{signgam}' are distinct expressions. @@ -29341,6 +29764,9 @@ and these are the values output with, for example, @t{$@{(k)jobdirs@}}. Non-numeric job references may be used when looking up a value; for example, @t{$@{jobdirs[%+]@}} refers to the current job. +@noindent +See the @t{jobs} builtin for how job information is provided in a subshell. + @vindex jobtexts @item @t{jobtexts} This associative array maps job numbers to the texts of the command lines @@ -29350,6 +29776,9 @@ that were used to start the jobs. Handling of the keys of the associative array is as described for @t{jobdirs} above. +@noindent +See the @t{jobs} builtin for how job information is provided in a subshell. + @vindex jobstates @item @t{jobstates} This associative array gives information about the states of the jobs @@ -29367,6 +29796,9 @@ the @var{state} describes the state of that process. Handling of the keys of the associative array is as described for @t{jobdirs} above. +@noindent +See the @t{jobs} builtin for how job information is provided in a subshell. + @vindex nameddirs @item @t{nameddirs} This associative array maps the names of named directories to the pathnames @@ -29564,12 +29996,17 @@ This module provides a single autoloaded builtin: @table @asis @findex private @cindex private parameter, creating -@item @t{private} [ @{@t{+}|@t{-}@}@t{AHUahlprtux} ] [ @{@t{+}|@t{-}@}@t{EFLRZi} [ @var{n} ] ] [ @var{name}[@t{=}@var{value}] ... ] +@item @t{private} [ @{@t{+}|@t{-}@}@t{AHUahlmrtux} ] [ @{@t{+}|@t{-}@}@t{EFLRZi} [ @var{n} ] ] [ @var{name}[@t{=}@var{value}] ... ] The @t{private} builtin accepts all the same options and arguments as @t{local} (@ref{Shell Builtin Commands}) except for the `@t{-}@t{T}' option. Tied parameters may not be made private. @noindent +The `@t{-}@t{p}' option is presently a no-op because the state of +private parameters cannot reliably be reloaded. This also applies +to printing private parameters with `@t{typeset -p}'. + +@noindent If used at the top level (outside a function scope), @t{private} creates a normal parameter in the same manner as @t{declare} or @t{typeset}. A warning about this is printed if @t{WARN_CREATE_GLOBAL} is set @@ -29646,7 +30083,8 @@ Within any other function called by the declaring function, the private parameter does @emph{NOT} hide other parameters of the same name, so for example a global parameter of the same name is visible and may be assigned or unset. This includes calls to anonymous functions, although -that may also change in the future. +that may also change in the future. However, the private name may not be +created outside the local scope when it was not previously declared. @item An exported private remains in the environment of inner scopes but appears unset for the current shell in those scopes. Generally, exporting @@ -29700,6 +30138,21 @@ automatically load this module as needed and will invoke the If @t{BASH_REMATCH} is set, then the array @t{BASH_REMATCH} will be set instead of @t{MATCH} and @t{match}. +@noindent +Note that the @t{zsh/regex} module logic relies on the host system. The +same @var{expr} and @var{regex} pair could produce different results on different +platforms if a @var{regex} with non-standard syntax is given. + +@noindent +For example, no syntax for matching a word boundary is defined in the POSIX +extended regular expression standard. GNU @t{libc} and BSD @t{libc} both provide +such syntaxes as extensions (@t{\b} and @t{[[:<:]]}/@t{[[:>:]]} respectively), +but neither of these syntaxes is supported by both of these implementations. + +@noindent +Refer to the regcomp(3) and re_format(7) manual pages on your +system for locally-supported syntax. + @end table @c (avoiding a yodl bug) @node The zsh/sched Module, The zsh/net/socket Module, The zsh/regex Module, Zsh Modules @@ -29900,7 +30353,7 @@ two possible names: @itemx @t{@ @ @ @ @ @ }[ @t{+}@var{element} ] [ @var{file} ... ] @itemx @t{stat} @var{...} The command acts as a front end to the @t{stat} system call (see -man page stat(2)). The same command is provided with two names; as +stat(2)). The same command is provided with two names; as the name @t{stat} is often used by an external command it is recommended that only the @t{zstat} form of the command is used. This can be arranged by loading the module with the command `@t{zmodload -F zsh/stat @@ -30002,10 +30455,12 @@ Use the file on file descriptor @var{fd} instead of named files; no list of file names is allowed in this case. @item @t{-F} @var{fmt} -Supplies a @t{strftime} (see man page strftime(3)) string for the +Supplies a @t{strftime} (see strftime(3)) string for the formatting of the time elements. The format string supports all of the zsh extensions described in @ref{Prompt Expansion}. +In particular, @t{-F %s.%N} can be used to show timestamps with nanosecond +precision if supported by the system. The @t{-s} option is implied. @item @t{-g} @@ -30018,11 +30473,11 @@ output or an array as appropriate) and return immediately; arguments, and options other than @t{-A}, are ignored. @item @t{-L} -Perform an @t{lstat} (see man page lstat(2)) rather than a @t{stat} +Perform an @t{lstat} (see lstat(2)) rather than a @t{stat} system call. In this case, if the file is a link, information about the link itself rather than the target file is returned. This option is required to make the @t{link} element useful. -It's important to note that this is the exact opposite from man page ls(1), +It's important to note that this is the exact opposite from ls(1), etc. @item @t{-n} @@ -30138,6 +30593,9 @@ suppress updating of the file atime @item @t{nofollow} fail if @var{file} is a symbolic link +@item @t{nonblock} +the file is opened in nonblocking mode + @item @t{sync} request that writes wait until data has been physically written @@ -30254,10 +30712,10 @@ to the command, or 2 for an error on the write; no error message is printed in the last case, but the parameter @t{ERRNO} will reflect the error that occurred. -@item @t{zsystem flock} [ @t{-t} @var{timeout} ] [ @t{-f} @var{var} ] [@t{-er}] @var{file} +@item @t{zsystem flock} [ @t{-t} @var{timeout} ] [ @t{-i} @var{interval} ] [ @t{-f} @var{var} ] [@t{-er}] @var{file} @itemx @t{zsystem flock -u} @var{fd_expr} The builtin @t{zsystem}'s subcommand @t{flock} performs advisory file -locking (via the man page fcntl(2) system call) over the entire contents +locking (via the fcntl(2) system call) over the entire contents of the given file. This form of locking requires the processes accessing the file to cooperate; its most obvious use is between two instances of the shell itself. @@ -30287,9 +30745,17 @@ a safety check that the file descriptor is in use for file locking. @noindent By default the shell waits indefinitely for the lock to succeed. The option @t{-t} @var{timeout} specifies a timeout for the lock in -seconds; currently this must be an integer. The shell will attempt -to lock the file once a second during this period. If the attempt -times out, status 2 is returned. +seconds; fractional seconds are allowed. During this period, the +shell will attempt to lock the file every @var{interval} seconds +if the @t{-i} @var{interval} option is given, otherwise once a second. +(This @var{interval} is shortened before the last attempt if needed, +so that the shell waits only until the @var{timeout} and not longer.) +If the attempt times out, status 2 is returned. + +@noindent +(Note: @var{timeout} is limited to 2^30-1 seconds (about 34 years), and +@var{interval} to 0.999 * LONG_MAX microseconds (only about 35 minutes +on 32-bit systems).) @noindent If the option @t{-e} is given, the file descriptor for the lock is @@ -30359,9 +30825,9 @@ Returns the process ID of the current process, even in subshells. Compare @item @t{ppid} @vindex ppid, sysparams -Returns the process ID of the parent of the current process, even in -subshells. Compare @t{$PPID}, which returns the process ID of the parent -of the main shell process. +Returns the current process ID of the parent of the current process, even +in subshells. Compare @t{$PPID}, which returns the process ID of the +initial parent of the main shell process. @item @t{procsubstpid} Returns the process ID of the last process started for process @@ -30623,7 +31089,7 @@ their values. @end table @c (avoiding a yodl bug) -@node The zsh/terminfo Module, The zsh/zftp Module, The zsh/termcap Module, Zsh Modules +@node The zsh/terminfo Module, The zsh/watch Module, The zsh/termcap Module, Zsh Modules @section The zsh/terminfo Module @noindent @@ -30653,7 +31119,170 @@ their values. @end table @c (avoiding a yodl bug) -@node The zsh/zftp Module, The zsh/zle Module, The zsh/terminfo Module, Zsh Modules +@node The zsh/watch Module, The zsh/zftp Module, The zsh/terminfo Module, Zsh Modules + +@section The zsh/watch Module +@noindent +@c Yodl file: Zsh/mod_watch.yo + +The @t{zsh/watch} module can be used to report when specific users log in or +out. This is controlled via the following parameters. + +@noindent +@table @asis +@vindex LOGCHECK +@item @t{LOGCHECK} +The interval in seconds between checks for login/logout activity +using the @t{watch} parameter. + +@vindex watch +@vindex WATCH +@item @t{watch} <S> <Z> (@t{WATCH} <S>) +An array (colon-separated list) of login/logout events to report. + +@noindent +If it contains the single word `@t{all}', then all login/logout events +are reported. If it contains the single word `@t{notme}', then all +events are reported as with `@t{all}' except @t{$USERNAME}. + +@noindent +An entry in this list may consist of a username, +an `@t{@@}' followed by a remote hostname, +and a `@t{%}' followed by a line (tty). Any of these may +be a pattern (be sure to quote this during the assignment to +@t{watch} so that it does not immediately perform file generation); +the setting of the @t{EXTENDED_GLOB} option is respected. +Any or all of these components may be present in an entry; +if a login/logout event matches all of them, +it is reported. + +@noindent +For example, with the @t{EXTENDED_GLOB} option set, the following: + +@noindent +@example +watch=('^(pws|barts)') +@end example + +@noindent +causes reports for activity associated with any user other than @t{pws} +or @t{barts}. + +@vindex WATCHFMT +@item @t{WATCHFMT} +The format of login/logout reports if the @t{watch} parameter is set. +Default is `@t{%n has %a %l from %m}'. +Recognizes the following escape sequences: + +@noindent +@table @asis +@item @t{%n} +The name of the user that logged in/out. + +@item @t{%a} +The observed action, i.e. "logged on" or "logged off". + +@item @t{%l} +The line (tty) the user is logged in on. + +@item @t{%M} +The full hostname of the remote host. + +@item @t{%m} +The hostname up to the first `@t{.}'. If only the +IP address is available or the utmp field contains +the name of an X-windows display, the whole name is printed. + +@noindent +@emph{NOTE:} +The `@t{%m}' and `@t{%M}' escapes will work only if there is a host name +field in the utmp on your machine. Otherwise they are +treated as ordinary strings. + +@item @t{%F@{}@var{color}@t{@}} (@t{%f}) +Start (stop) using a different foreground color. + +@item @t{%K@{}@var{color}@t{@}} (@t{%k}) +Start (stop) using a different background color. + +@item @t{%S} (@t{%s}) +Start (stop) standout mode. + +@item @t{%U} (@t{%u}) +Start (stop) underline mode. + +@item @t{%B} (@t{%b}) +Start (stop) boldface mode. + +@item @t{%t} +@itemx @t{%@@} +The time, in 12-hour, am/pm format. + +@item @t{%T} +The time, in 24-hour format. + +@item @t{%w} +The date in `@var{day}@t{-}@var{dd}' format. + +@item @t{%W} +The date in `@var{mm}@t{/}@var{dd}@t{/}@var{yy}' format. + +@item @t{%D} +The date in `@var{yy}@t{-}@var{mm}@t{-}@var{dd}' format. + +@item @t{%D@{}@var{string}@t{@}} +The date formatted as @var{string} using the @t{strftime} function, with +zsh extensions as described by +@ref{Prompt Expansion}. + +@item @t{%(}@var{x}@t{:}@var{true-text}@t{:}@var{false-text}@t{)} +Specifies a ternary expression. +The character following the @var{x} is +arbitrary; the same character is used to separate the text +for the "true" result from that for the "false" result. +Both the separator and the right parenthesis may be escaped +with a backslash. +Ternary expressions may be nested. + +@noindent +The test character @var{x} may be any one of `@t{l}', `@t{n}', `@t{m}' +or `@t{M}', which indicate a `true' result if the corresponding +escape sequence would return a non-empty value; or it may be `@t{a}', +which indicates a `true' result if the watched user has logged in, +or `false' if he has logged out. +Other characters evaluate to neither true nor false; the entire +expression is omitted in this case. + +@noindent +If the result is `true', then the @var{true-text} +is formatted according to the rules above and printed, +and the @var{false-text} is skipped. +If `false', the @var{true-text} is skipped and the @var{false-text} +is formatted and printed. +Either or both of the branches may be empty, but +both separators must be present in any case. + +@end table + +@end table + +@noindent +Furthermore, the @t{zsh/watch} module makes available one builtin +command: + +@noindent +@table @asis +@findex log +@vindex watch, use of +@cindex watching users +@cindex users, watching +@item @t{log} +List all users currently logged in who are affected by +the current setting of the @t{watch} parameter. + +@end table +@c (avoiding a yodl bug) +@node The zsh/zftp Module, The zsh/zle Module, The zsh/watch Module, Zsh Modules @section The zsh/zftp Module @noindent @@ -31444,8 +32073,8 @@ The @t{zselect} builtin is a front-end to the `select' system call, which blocks until a file descriptor is ready for reading or writing, or has an error condition, with an optional timeout. If this is not available on your system, the command prints an error message and returns status 2 -(normal errors return status 1). For more information, see your systems -documentation for man page select(3). Note there is no connection with the +(normal errors return status 1). For more information, see your system's +documentation for select(3). Note there is no connection with the shell builtin of the same name. @noindent @@ -31547,29 +32176,36 @@ the pattern that was defined first. @noindent @emph{Example} +@kindex preferred-precipitation, example style +@findex weather, example function @noindent -For example, to define your preferred form of precipitation depending on which -city you're in, you might set the following in your @t{zshrc}: +For example, a fictional `@t{weather}' plugin might state in its documentation +that it looks up the @t{preferred-precipitation} style under the +`@t{:weather:}@var{continent}@t{:}@var{day-of-the-week}@t{:}@var{phase-of-the-moon}' context. +According to this, you might set the following in your @t{zshrc}: @noindent @example zstyle ':weather:europe:*' preferred-precipitation rain -zstyle ':weather:europe:germany:* preferred-precipitation none -zstyle ':weather:europe:germany:*:munich' preferred-precipitation snow +zstyle ':weather:*:Sunday:*' preferred-precipitation snow @end example @noindent -Then, the fictional `@t{weather}' plugin might run under the hood a command -such as +Then the plugin would run under the hood a command such as @noindent @example -zstyle -s ":weather:$@{continent@}:$@{country@}:$@{county@}:$@{city@}" preferred-precipitation REPLY +zstyle -s ":weather:$@{continent@}:$@{day_of_week@}:$@{moon_phase@}" preferred-precipitation REPLY @end example @noindent in order to retrieve your preference into the scalar variable @t{$REPLY}. +On Sundays @t{$REPLY} would be set to `@t{snow}'; in Europe it would be set +to `@t{rain}'; and on Sundays in Europe it would be set to `@t{snow}' again, +because the patterns `@t{:weather:europe:*}' and `@t{:weather:*:Sunday:*}' both +match the @var{context} argument to @t{zstyle -s}, are equally specific, and the +latter is more specific (because it has more colon-separated components). @noindent @emph{Usage} @@ -31677,8 +32313,9 @@ Match a value. Returns status zero if the @findex zformat @item @t{zformat -f} @var{param} @var{format} @var{spec} ... +@itemx @t{zformat -F} @var{param} @var{format} @var{spec} ... @itemx @t{zformat -a} @var{array} @var{sep} @var{spec} ... -This builtin provides two different forms of formatting. The first form +This builtin provides different forms of formatting. The first form is selected with the @t{-f} option. In this case the @var{format} string will be modified by replacing sequences starting with a percent sign in it with strings from the @var{spec}s. Each @var{spec} should be @@ -31729,7 +32366,14 @@ specifier @t{c} is 3, agreeing with the digit argument to the ternary expression. @noindent -The second form, using the @t{-a} option, can be used for aligning +With @t{-F} instead of @t{-f}, ternary expressions choose between the +`true' or `false' text on the basis of whether the format specifier is +present and non-empty. A test number indicates a minimum width for the +value given in the format specifier. Negative numbers reverse this, +so the test is for whether the value exceeds a maximum width. + +@noindent +The form, using the @t{-a} option, can be used for aligning strings. Here, the @var{spec}s are of the form `@var{left}@t{:}@var{right}' where `@var{left}' and `@var{right}' are arbitrary strings. These strings are modified by replacing the colons @@ -32865,7 +33509,7 @@ The location of the main calendar. The default is @t{~/calendar}. @kindex date-format @item @t{date-format} -A @t{strftime} format string (see man page strftime(3)) with the zsh +A @t{strftime} format string (see strftime(3)) with the zsh extensions providing various numbers with no leading zero or space if the number is a single digit as described for the @t{%D@{}@var{string}@t{@}} prompt format in @@ -34052,7 +34696,7 @@ This describes the set of shell functions supplied with the source distribution as an interface to the @t{zftp} builtin command, allowing you to perform FTP operations from the shell command line or within functions or scripts. The interface is similar to a traditional FTP client (e.g. the -@t{ftp} command itself, see man page ftp(1)), but as it is entirely done +@t{ftp} command itself, see ftp(1)), but as it is entirely done within the shell all the familiar completion, editing and globbing features, and so on, are present, and macros are particularly simple to write as they are just ordinary shell functions. @@ -34634,13 +35278,11 @@ command `@t{zstyle ':zftp:*'} @var{style} @var{value} ...'. defines the @var{style} to have value @var{value}; more than one value may be given, although that is not useful in the cases described here. These values will then be used throughout the zftp function system. For more -precise control, the first argument, which gives a context in which the +precise control, the first argument, which gives a pattern that matches @emph{contexts} in which the style applies, can be modified to include a particular function, as for example `@t{:zftp:zfget}': the style will then have the given value only -in the @t{zfget} function. Values for the same style in different contexts -may be set; the most specific function will be used, where -strings are held to be more specific than patterns, and longer patterns and -shorter patterns. Note that only the top level function name, as called by +in the @t{zfget} function, and will override styles set under `@t{:zftp:*}'. +Note that only the top level function name, as called by the user, is used; calling of lower level functions is transparent to the user. Hence modifications to the title bar in @t{zftp_chpwd} use the contexts @t{:zftp:zfopen}, @t{:zftp:zfcd}, etc., depending where it was @@ -34876,7 +35518,7 @@ distribution in your home directory, you would use the commands: @noindent @example mkdir ~/zsh_help -perl ~/zsh-5.8.1/Util/helpfiles ~/zsh_help +perl ~/zsh-5.8.1.2-test/Util/helpfiles ~/zsh_help @end example @noindent @@ -35037,7 +35679,7 @@ Run @t{zkbd} either as an autoloaded function, or as a shell script: @noindent @example -zsh -f ~/zsh-5.8.1/Functions/Misc/zkbd +zsh -f ~/zsh-5.8.1.2-test/Functions/Misc/zkbd @end example @noindent @@ -35102,7 +35744,7 @@ command and redirect the output into a file: @noindent @example -. ~/zsh-5.8.1/Util/reporter > zsh.report +. ~/zsh-5.8.1.2-test/Util/reporter > zsh.report @end example @noindent @@ -35243,7 +35885,7 @@ as the @var{hook} argument. is added to the array of widgets to be invoked in the given hook context. Widgets are invoked in the order they were added, with @example -@t{zle }@var{widgetname}@t{ -Nw -- "$@@"} +@t{zle }@var{widgetname}@t{ -Nw -f "nolast" -- "$@@"} @end example @noindent @@ -35397,7 +36039,7 @@ allows you to edit the list of directories, one per line. The list can be edited to any extent you like; no sanity checking is performed. Completion is available. No quoting is necessary (except for newlines, where I have in any case no sympathy); directories are in -unabbreviated from and contain an absolute path, i.e. they start with @t{/}. +unabbreviated form and contain an absolute path, i.e. they start with @t{/}. Usually the first entry should be left as the current directory. @item @t{-p '}@var{pattern}@t{'} @@ -35554,7 +36196,7 @@ changes to descendant directories; earlier directories on the list are not pruned. For example, changing from ~pws/yet/another to ~pws/some/other/dir does not cause ~pws to be pruned. -@item @t{pattern:@var{pattern}} +@item @t{pattern:}@var{pattern} Gives a zsh pattern for directories that should not be added to the recent list (if not already there). This element can be repeated to add different patterns. For example, @@ -35691,7 +36333,7 @@ Then arrange for the wrapper to be run as a zsh_directory_name hook: @noindent @example -autoload -Uz add-zsh-hook zsh_diretory_name_generic zdn_mywrapper +autoload -Uz add-zsh-hook zsh_directory_name_generic zdn_mywrapper add-zsh-hook -U zsh_directory_name zdn_mywrapper @end example @@ -36255,7 +36897,7 @@ This is used by the Perforce backend (@t{p4}) to decide if it should contact the Perforce server to find out if a directory is managed by Perforce. This is the only reliable way of doing this, but runs the risk of a delay if the server name cannot be found. If the -server (more specifically, the @t{host}@t{:}@t{port} pair describing the +server (more specifically, the @var{host}@t{:}@var{port} pair describing the server) cannot be contacted, its name is put into the associative array @t{vcs_info_p4_dead_servers} and is not contacted again during the session until it is removed by hand. If you do not set this style, the @t{p4} @@ -36274,7 +36916,7 @@ If there are two different ways of gathering information, you can select the simpler one by setting this style to true; the default is to use the not-that-simple code, which is potentially a lot slower but might be more accurate in all possible cases. This style is -used by the @t{bzr} and @t{hg} backends. In the case of @t{hg} it will invoke +used by the @t{bzr}, @t{hg}, and @t{git} backends. In the case of @t{hg} it will invoke the external hexdump program to parse the binary dirstate cache file; this method will not return the local revision number. @@ -36334,7 +36976,7 @@ This boolean style controls whether a backend should attempt to gather a list of unapplied patches (for example with Mercurial Queue patches). @noindent -Used by the @t{quilt} and @t{hg} backends. +Used by the @t{quilt}, @t{hg}, and @t{git} backends. @end table @@ -36461,7 +37103,7 @@ The @t{quilt} `standalone' backend sets this expando to the same value as the @item @t{%Q} Quilt series information. When quilt is used (either in `addon' mode or as a `standalone' backend), -this expando is set to quilt series' @t{patch-format} string. +this expando is set to the quilt series' @t{patch-format} string. The @t{set-patch-format} hook and @t{nopatch-format} style are honoured. @noindent @@ -36475,7 +37117,8 @@ In @t{branchformat} these replacements are done: @noindent @table @asis @item @t{%b} -The branch name. +The branch name. For @t{hg}, the branch name can include a +topic name. @item @t{%r} The current revision number or the @t{hgrevformat} style for @t{hg}. @@ -36580,7 +37223,7 @@ a directory that holds quilt's patches needs to be found. That directory is configurable via the `@t{QUILT_PATCHES}' environment variable. If that variable exists its value is used, otherwise the value `@t{patches}' is assumed. The value from @t{$QUILT_PATCHES} can be overwritten using the -`@t{quilt-patches}' style. (Note: you can use @t{vcs_info} to keep the value +`@t{quilt-patch-dir}' style. (Note: you can use @t{vcs_info} to keep the value of @t{$QUILT_PATCHES} correct all the time via the @t{post-quilt} hook). @noindent @@ -36700,7 +37343,7 @@ below for details. @findex vcs_info_lastmsg @item @t{vcs_info_lastmsg} -Outputs the last @t{$@{vcs_info_msg_*_@}} value. +Outputs the current values of @t{$@{vcs_info_msg_*_@}}. Takes into account the value of the @t{use-prompt-escapes} style in @t{':vcs_info:formats:command:-all-'}. It also only prints @t{max-exports} values. @@ -36874,11 +37517,19 @@ is generated; the @t{use-quilt} zstyle must be true for @t{quilt} (the @t{mq} and @t{stgit} backends are active by default). @noindent -This hook gets the names of all applied patches which @t{vcs_info} collected -so far in the opposite order, which means that the first argument is the +The arguments to this hook describe applied patches +in the opposite order, which means that the first argument is the top-most patch and so forth. @noindent +When the patches' log messages can be extracted, those are embedded +within each argument after a space, so each argument is of the form +`@var{patch-name} @var{first line of the log message}', where @var{patch-name} +contains no whitespace. The @t{mq} backend passes arguments of +the form `@var{patch name}', with possible embedded spaces, but without +extracting the patch's log message. + +@noindent When setting @t{ret} to non-zero, the string in @t{$@{hook_com[applied-string]@}} will be available as @t{%p} in the @t{patch-format} and @t{nopatch-format} styles. @@ -36886,6 +37537,11 @@ This hook is, in concert with @t{set-patch-format}, responsible for @t{%}-escaping that value for use in the prompt. (See @ref{vcs_info Oddities}.) +@noindent +The @t{quilt} backend passes to this hook the inputs +@t{$@{hook_com[quilt-patches-dir]@}} and, if it has been +determined, @t{$@{hook_com[quilt-pc-dir]@}}. + @item @t{gen-unapplied-string} Called in the @t{git} (with @t{stgit} or during rebase), and @t{hg} (with @t{mq}) backend and in @t{quilt} support when the @t{unapplied-string} is @@ -36893,10 +37549,13 @@ generated; the @t{get-unapplied} style must be true. @noindent This hook gets the names of all unapplied patches which @t{vcs_info} -collected so far in order, which means that the first argument is +in order, which means that the first argument is the patch next-in-line to be applied and so forth. @noindent +The format of each argument is as for @t{gen-applied-string}, above. + +@noindent When setting @t{ret} to non-zero, the string in @t{$@{hook_com[unapplied-string]@}} will be available as @t{%u} in the @t{patch-format} and @t{nopatch-format} styles. @@ -36904,6 +37563,11 @@ This hook is, in concert with @t{set-patch-format}, responsible for @t{%}-escaping that value for use in the prompt. (See @ref{vcs_info Oddities}.) +@noindent +The @t{quilt} backend passes to this hook the inputs +@t{$@{hook_com[quilt-patches-dir]@}} and, if it has been +determined, @t{$@{hook_com[quilt-pc-dir]@}}. + @item @t{gen-mqguards-string} Called in the @t{hg} backend when @t{guards-string} is generated; the @t{get-mq} style must be true (default). @@ -37000,6 +37664,11 @@ This hook is, in concert with the @t{gen-applied-string} or @t{%}-escaping the final @t{patch-format} value for use in the prompt. (See @ref{vcs_info Oddities}.) +@noindent +The @t{quilt} backend passes to this hook the inputs +@t{$@{hook_com[quilt-patches-dir]@}} and, if it has been +determined, @t{$@{hook_com[quilt-pc-dir]@}}. + @item @t{set-message} Called each time before a `@t{vcs_info_msg_}@var{N}@t{_}' message is set. It takes two arguments; the first being the `@var{N}' in the message @@ -37091,22 +37760,40 @@ If you do use @t{use-simple}, please report if it does `the-right-thing[tm]'. Display the revision number in yellow for @t{bzr} and @t{svn}: @example zstyle ':vcs_info:(svn|bzr):*' \ + branchformat '%b%%F@{yellow@}:%r' +@end example + +@noindent +The doubled percent sign is explained in +@ref{vcs_info Oddities}. + +@noindent +Alternatively, one can use the raw colour codes directly: + +@noindent +@example +zstyle ':vcs_info:(svn|bzr):*' \ branchformat '%b%@{'$@{fg[yellow]@}'%@}:%r' @end example @noindent -If you want colors, make sure you enclose the color codes in @t{%@{}@var{...}@t{%@}} +Normally when a variable is interpolated into a format string, the variable +needs to be @t{%}-escaped. In this example we skipped that because we assume +the value of @t{$@{fg[yellow]@}} doesn't contain any @t{%} signs. + +@noindent +Make sure you enclose the color codes in @t{%@{}@var{...}@t{%@}} if you want to use the string provided by @t{vcs_info} in prompts. @noindent Here is how to print the VCS information as a command (not in a prompt): @example -alias vcsi='vcs_info command; vcs_info_lastmsg' +vcsi() @{ vcs_info interactive; vcs_info_lastmsg @} @end example @noindent This way, you can even define different formats for output via -@t{vcs_info_lastmsg} in the '@t{:vcs_info:*:command:*}' namespace. +@t{vcs_info_lastmsg} in the '@t{:vcs_info:*:interactive:*}' namespace. @noindent Now as promised, some code that uses hooks: @@ -37223,7 +37910,7 @@ This concludes our guided tour through zsh's @t{vcs_info}. @noindent You should make sure all the functions from the @t{Functions/Prompts} directory of the source distribution are available; they all begin with -the string `@t{prompt_}' except for the special function`@t{promptinit}'. +the string `@t{prompt_}' except for the special function `@t{promptinit}'. You also need the `@t{colors}' and `@t{add-zsh-hook}' functions from @t{Functions/Misc}. All these functions may already be installed on your system; if not, @@ -37350,29 +38037,34 @@ setopts (@t{promptbang}, etc.) are turned on, all other prompt-related options are turned off. The @t{prompt_opts} array preserves setopts even beyond the scope of @t{localoptions}, should your function need that. -@item Modify precmd and preexec -Use of @t{add-zsh-hook} is recommended. The @t{precmd} and @t{preexec} -hooks are automatically adjusted if the prompt theme changes or is -disabled. +@item Modify hooks +Use of @t{add-zsh-hook} and @t{add-zle-hook-widget} is recommended (see +the @cite{Manipulating Hook Functions} section above). +All hooks that follow the naming pattern @t{prompt_}@var{theme}@t{_}@var{hook} +are automatically removed when the prompt theme changes or is disabled. @item Declare cleanup If your function makes any other changes that should be undone when the theme is disabled, your setup function may call + +@noindent @example prompt_cleanup @var{command} @end example + +@noindent where @var{command} should be suitably quoted. If your theme is ever disabled or replaced by another, @var{command} is executed with @t{eval}. You may declare more than one such cleanup hook. @item Define preview -Define or autoload a function @t{prompt_@var{name}_preview} to display +Define or autoload a function @t{prompt_}@var{name}@t{_preview} to display a simulated version of your prompt. A simple default previewer is defined by @t{promptinit} for themes that do not define their own. This preview function is called by `@t{prompt -p}'. @item Provide help -Define or autoload a function @t{prompt_@var{name}_help} to display +Define or autoload a function @t{prompt_}@var{name}@t{_help} to display documentation or help text for your theme. This help function is called by `@t{prompt -h}'. @@ -37706,7 +38398,7 @@ directly. @tindex bracketed-paste-magic @item @t{bracketed-paste-magic} -The @t{bracketed-paste} widget (see @ref{Miscellaneous} in @ref{Zle Widgets}) +The @t{bracketed-paste} widget (see @ref{Miscellaneous} in @ref{Standard Widgets}) inserts pasted text literally into the editor buffer rather than interpret it as keystrokes. This disables some common usages where the self-insert widget is replaced in order to accomplish some extra processing. An @@ -37895,6 +38587,16 @@ Edit the command line using your visual editor, as in @t{ksh}. bindkey -M vicmd v edit-command-line @end example +@noindent +The editor to be used can also be specified using the @t{editor} style in +the context of the widget. It is specified as an array of command and +arguments: + +@noindent +@example +zstyle :zle:edit-command-line editor gvim -f +@end example + @tindex expand-absolute-path @item @t{expand-absolute-path} Expand the file name under the cursor to an absolute path, resolving @@ -39254,7 +39956,8 @@ Calling @t{zsh-mime-setup} with the option @noindent The system respects the @t{mailcap} flags @t{needsterminal} and -@t{copiousoutput}, see man page mailcap(4). +@t{copiousoutput}; see mailcap(4) or mailcap(5) +(the man page's name varies across platforms). @noindent The functions use the following styles, which are defined with the @@ -40043,6 +40746,12 @@ Same as @t{zed -f}. This function does not appear in the zsh distribution, but can be created by linking @t{zed} to the name @t{fned} in some directory in your @t{fpath}. +@findex histed +@item @t{histed} [ [ @var{name} ] @var{size} ] +Same as @t{zed -h}. This function does not appear in the zsh +distribution, but can be created by linking @t{zed} to the name @t{histed} +in some directory in your @t{fpath}. + @findex is-at-least @item @t{is-at-least} @var{needed} [ @var{present} ] Perform a greater-than-or-equal-to comparison of two strings having the @@ -40079,7 +40788,7 @@ See also the @t{pager}, @t{prompt} and @t{rprompt} styles below. @findex regexp-replace @item @t{regexp-replace} @var{var} @var{regexp} @var{replace} Use regular expressions to perform a global search and replace operation -on a variable. POSIX extended regular expressions are used, +on a variable. POSIX extended regular expressions (ERE) are used, unless the option @t{RE_MATCH_PCRE} has been set, in which case Perl-compatible regular expressions are used (this requires the shell to be linked against the @t{pcre} @@ -40102,6 +40811,10 @@ reference to @t{$MATCH} will be replaced by the text matched by the pattern. @noindent The return status is 0 if at least one match was performed, else 1. +@noindent +Note that if using POSIX EREs, the @t{^} or word boundary operators +(where available) may not work properly. + @findex run-help @item @t{run-help} @var{cmd} This function is designed to be invoked by the @t{run-help} ZLE widget, @@ -40148,6 +40861,7 @@ your search path, in order to be found and used by @t{run-help}. @noindent @table @asis +@findex run-help-btrfs @findex run-help-git @findex run-help-ip @findex run-help-openssl @@ -40155,14 +40869,16 @@ your search path, in order to be found and used by @t{run-help}. @findex run-help-sudo @findex run-help-svk @findex run-help-svn -@item run-help-git -@itemx run-help-ip -@itemx run-help-openssl -@itemx run-help-p4 -@itemx run-help-sudo -@itemx run-help-svk +@item @t{run-help-btrfs} +@itemx @t{run-help-git} +@itemx @t{run-help-ip} +@itemx @t{run-help-openssl} +@itemx @t{run-help-p4} +@itemx @t{run-help-sudo} +@itemx @t{run-help-svk} @itemx @t{run-help-svn} Assistant functions for the +@t{btrfs}, @t{git}, @t{ip}, @t{openssl}, @@ -40284,12 +41000,13 @@ counts the number of arguments passed to each execution of @var{command}, each @var{input} is processed separately as if by `@t{-L} @t{1}'. @noindent -For details of the other @t{zargs} options, see man page xargs(1) (but note +For details of the other @t{zargs} options, see the xargs(1) man page (but note the difference in function between @t{zargs} and @t{xargs}) or run @t{zargs} with the @t{-}@t{-help} option. @findex zed @item @t{zed} [ @t{-f} [ @t{-x} @var{num} ] ] @var{name} +@itemx @t{zed} [ @t{-h} [ @var{name} ] @var{size} ] @itemx @t{zed -b} This function uses the ZLE editor to edit a file or function. @@ -40306,7 +41023,16 @@ of functions distributed with the shell. @noindent Without @t{-f}, @var{name} is the path name of the file to edit, which need -not exist; it is created on write, if necessary. +not exist; it is created on write, if necessary. With @t{-h}, the file is +presumed to contain history events. + +@noindent +When no file name is provided for @t{-h} the current shell history is edited +in place. The history is renumbered when zed exits successfully. + +@noindent +When editing history, multi-line events must have a trailing backslash on +every line before the last. @noindent While editing, the function sets the main keymap to @t{zed} and the @@ -40326,17 +41052,21 @@ this will overwrite the existing @t{zed} and @t{zed-vicmd} keymaps. @noindent Completion is available, and styles may be set with the context prefix -`@t{:completion:zed}'. +`@t{:completion:zed:}'. @noindent -A zle widget @t{zed-set-file-name} is available. This can be called by -name from within zed using `@t{\ex zed-set-file-name}' (note, however, that -because of zed's rebindings you will have to type @t{^j} at the end instead -of the return key), or can be bound to a key in either of the @t{zed} or -@t{zed-vicmd} keymaps after `@t{zed -b}' has been run. When the widget is -called, it prompts for a new name for the file being edited. When zed -exits the file will be written under that name and the original file will -be left alone. The widget has no effect with `@t{zed -f}'. +@findex zed-set-file-name +A zle widget @t{zed-set-file-name} is available. This can be called +by name from within zed using `@t{\ex zed-set-file-name}' or can be +bound to a key in either of the @t{zed} or @t{zed-vicmd} keymaps after +`@t{zed -b}' has been run. When the widget is called, it prompts for +a new name for the file being edited. When zed exits the file will be +written under that name and the original file will be left alone. The +widget has no effect when invoked from `@t{zed -f}'. The completion +context is changed to `@t{:completion:zed-set-file-name:}'. When editing +the current history with `@t{zed -h}', the history is first updated and +then the file is written, but the global setting of @t{HISTFILE} is not +altered. @noindent While @t{zed-set-file-name} is running, zed uses the keymap @@ -40384,7 +41114,7 @@ was not given) causes the entire function to abort without doing anything. @noindent -In addition to pattern replacement, the variable @t{$f} can be referrred +In addition to pattern replacement, the variable @t{$f} can be referred to in the second (replacement) argument. This makes it possible to use variable substitution to alter the argument; see examples below. diff --git a/Doc/zshall.1 b/Doc/zshall.1 index 4891d1abf..15ff09107 100644 --- a/Doc/zshall.1 +++ b/Doc/zshall.1 @@ -1,4 +1,4 @@ -.TH "ZSHALL" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHALL" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zshall \- the Z shell meta\-man page .\" Yodl file: Zsh/intro.yo @@ -47,19 +47,19 @@ login shell and as a shell script command processor\&. Of the standard shells, zsh most closely resembles \fBksh\fP but includes many enhancements\&. It does not provide compatibility with POSIX or other shells in its default operating mode: see -the section Compatibility below\&. +the section `Compatibility' below\&. .PP Zsh has command line editing, builtin spelling correction, programmable command completion, shell functions (with autoloading), a history mechanism, and a host of other features\&. .\" Yodl file: Zsh/metafaq.yo .SH "AUTHOR" -Zsh was originally written by Paul Falstad \fB<pf@zsh\&.org>\fP\&. -Zsh is now maintained by the members of the zsh\-workers mailing -list \fB<zsh\-workers@zsh\&.org>\fP\&. The development is currently -coordinated by Peter Stephenson \fB<pws@zsh\&.org>\fP\&. The coordinator -can be contacted at \fB<coordinator@zsh\&.org>\fP, but matters relating to -the code should generally go to the mailing list\&. +Zsh was originally written by Paul Falstad\&. Zsh is now maintained by +the members of the zsh\-workers mailing list \fB<zsh\-workers@zsh\&.org>\fP\&. +The development is currently coordinated by Peter Stephenson +\fB<pws@zsh\&.org>\fP\&. The coordinator can be contacted at +\fB<coordinator@zsh\&.org>\fP, but matters relating to the code should +generally go to the mailing list\&. .SH "AVAILABILITY" Zsh is available from the following HTTP and anonymous FTP site\&. .PP @@ -67,15 +67,14 @@ Zsh is available from the following HTTP and anonymous FTP site\&. \fBftp://ftp\&.zsh\&.org/pub/\fP \fBhttps://www\&.zsh\&.org/pub/\fP .fi -) .PP The up\-to\-date source code is available via Git from Sourceforge\&. See \fBhttps://sourceforge\&.net/projects/zsh/\fP for details\&. A summary of instructions for the archive can be found at -\fBhttp://zsh\&.sourceforge\&.net/\fP\&. +\fBhttps://zsh\&.sourceforge\&.io/\fP\&. .PP .SH "MAILING LISTS" -Zsh has 3 mailing lists: +Zsh has several mailing lists: .PP .PD 0 .TP @@ -89,6 +88,14 @@ User discussions\&. .TP \fB<zsh\-workers@zsh\&.org>\fP Hacking, development, bug reports and patches\&. +.TP +\fB<zsh\-security@zsh\&.org>\fP +Private mailing list (the general public cannot subscribe to it) for discussing +bug reports with security implications, i\&.e\&., potential vulnerabilities\&. +.RS +.PP +If you find a security problem in zsh itself, please mail this address\&. +.RE .PP To subscribe or unsubscribe, send mail to the associated administrative address for the mailing list\&. @@ -115,30 +122,28 @@ All submissions to \fBzsh\-announce\fP are automatically forwarded to forwarded to \fBzsh\-workers\fP\&. .PP If you have problems subscribing/unsubscribing to any of the mailing -lists, send mail to \fB<listmaster@zsh\&.org>\fP\&. The mailing lists are -maintained by Karsten Thygesen \fB<karthy@kom\&.auc\&.dk>\fP\&. +lists, send mail to \fB<listmaster@zsh\&.org>\fP\&. .PP The mailing lists are archived; the archives can be accessed via the administrative addresses listed above\&. There is also a hypertext -archive, maintained by Geoff Wing \fB<gcw@zsh\&.org>\fP, available at +archive available at \fBhttps://www\&.zsh\&.org/mla/\fP\&. .SH "THE ZSH FAQ" Zsh has a list of Frequently Asked Questions (FAQ), maintained by Peter Stephenson \fB<pws@zsh\&.org>\fP\&. It is regularly posted to the newsgroup \fBcomp\&.unix\&.shell\fP and the \fBzsh\-announce\fP mailing list\&. The latest version can be found at any of the Zsh FTP sites, or at -\fBhttp://www\&.zsh\&.org/FAQ/\fP\&. The contact address for FAQ\-related matters +\fBhttps://www\&.zsh\&.org/FAQ/\fP\&. The contact address for FAQ\-related matters is \fB<faqmaster@zsh\&.org>\fP\&. .SH "THE ZSH WEB PAGE" -Zsh has a web page which is located at \fBhttps://www\&.zsh\&.org/\fP\&. This is -maintained by Karsten Thygesen \fB<karthy@zsh\&.org>\fP, of SunSITE Denmark\&. +Zsh has a web page which is located at \fBhttps://www\&.zsh\&.org/\fP\&. The contact address for web\-related matters is \fB<webmaster@zsh\&.org>\fP\&. .SH "THE ZSH USERGUIDE" A userguide is currently in preparation\&. It is intended to complement the manual, with explanations and hints on issues where the manual can be cabbalistic, hierographic, or downright mystifying (for example, the word `hierographic' does not exist)\&. It can be viewed in its current state at -\fBhttp://zsh\&.sourceforge\&.net/Guide/\fP\&. At the time of writing, chapters +\fBhttps://zsh\&.sourceforge\&.io/Guide/\fP\&. At the time of writing, chapters dealing with startup files and their contents and the new completion system were essentially complete\&. .\" Yodl file: Zsh/invoke.yo @@ -273,8 +278,7 @@ parameters are not special and not initialized by the shell: \fBPROMPT3\fP, \fBPROMPT4\fP, \fBpsvar\fP, -\fBstatus\fP, -\fBwatch\fP\&. +\fBstatus\fP\&. .PP The usual zsh startup/shutdown scripts are not executed\&. Login shells source \fB/etc/profile\fP followed by \fB$HOME/\&.profile\fP\&. If the @@ -316,6 +320,12 @@ Also, the and \fBSINGLE_LINE_ZLE\fP options are set if zsh is invoked as \fBksh\fP\&. +.PP +Please note that, whilst reasonable efforts are taken to address +incompatibilities when they arise, zsh does not guarantee complete +emulation of other shells, nor POSIX compliance\&. For more information on +the differences between zsh and other shells, please refer to chapter 2 +of the shell FAQ, \fBhttps://www\&.zsh\&.org/FAQ/\fP\&. .\" Yodl file: Zsh/restricted.yo .SH "RESTRICTED SHELL" When the basename of the command used to invoke zsh starts with the letter @@ -476,7 +486,7 @@ file will be used instead\&. .so man1/zshtcpsys.1 .so man1/zshzftpsys.1 .so man1/zshcontrib.1 -.TH "ZSHALL" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHALL" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2\-test" .\" Yodl file: Zsh/filelist.yo .SH "FILES" .PD 0 diff --git a/Doc/zshbuiltins.1 b/Doc/zshbuiltins.1 index 82b9225f2..5b4acbfd0 100644 --- a/Doc/zshbuiltins.1 +++ b/Doc/zshbuiltins.1 @@ -1,4 +1,4 @@ -.TH "ZSHBUILTINS" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHBUILTINS" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zshbuiltins \- zsh built\-in commands .\" Yodl file: Zsh/builtins.yo @@ -77,9 +77,19 @@ For each \fIname\fP with a corresponding \fIvalue\fP, define an alias with that value\&. A trailing space in \fIvalue\fP causes the next word to be checked for alias expansion\&. If the \fB\-g\fP flag is present, define a global alias; global aliases are expanded even if they do not -occur in command position\&. +occur in command position: .RS .PP +.RS +.nf +\fB% perldoc \-\-help 2>&1 | grep \&'built\-in functions' + \-f Search Perl built\-in functions +% alias \-g HG=\&'\-\-help 2>&1 | grep' +% perldoc HG \&'built\-in functions' + \-f Search Perl built\-in functions\fP +.fi +.RE +.PP If the \fB\-s\fP flag is present, define a suffix alias: if the command word on a command line is in the form `\fItext\fP\fB\&.\fP\fIname\fP\&', where \fItext\fP is any non\-empty string, it is replaced by the text @@ -770,7 +780,7 @@ Do nothing and return an exit status of 1\&. .TP .PD 0 -\fBfc\fP [ \fB\-e\fP \fIename\fP ] [ \fB\-LI\fP ] [ \fB\-m\fP \fImatch\fP ] [ \fIold\fP\fB=\fP\fInew\fP \&.\&.\&. ] [ \fIfirst\fP [ \fIlast\fP ] ] +\fBfc\fP [ \fB\-e\fP \fIename\fP ] [ \fB\-s\fP ] [ \fB\-LI\fP ] [ \fB\-m\fP \fImatch\fP ] [ \fIold\fP\fB=\fP\fInew\fP \&.\&.\&. ] [ \fIfirst\fP [ \fIlast\fP ] ] .TP .PD 0 \fBfc \-l \fP[ \fB\-LI\fP ] [ \fB\-nrdfEiD\fP ] [ \fB\-t\fP \fItimefmt\fP ] [ \fB\-m\fP \fImatch\fP ] @@ -801,7 +811,8 @@ specifies the most recent event beginning with the given string\&. All substitutions \fIold\fP\fB=\fP\fInew\fP, if any, are then performed on the text of the events\&. .PP -In addition to the number range, +The range of events selected by numbers can be narrowed further by the +following flags\&. .PD 0 .TP \fB\-I\fP @@ -813,8 +824,8 @@ restricts to only local events (not from other shells, see considered local when read at startup) .TP \fB\-m\fP -takes the first argument as a pattern (should be quoted) and -only the history events matching this pattern are considered +takes the first argument as a pattern (which should be +quoted) and only the history events matching this pattern are considered .PD .PP If \fIfirst\fP is not specified, it will be set to \-1 (the most recent @@ -833,6 +844,7 @@ the parameter \fBEDITOR\fP is used; if that is not set a builtin default, usually `\fBvi\fP\&' is used\&. If \fIename\fP is `\fB\-\fP', no editor is invoked\&. When editing is complete, the edited command is executed\&. .PP +The flag `\fB\-s\fP\&' is equivalent to `\fB\-e \-\fP'\&. The flag \fB\-r\fP reverses the order of the events and the flag \fB\-n\fP suppresses event numbers when listing\&. .PP @@ -957,6 +969,8 @@ without affecting the other\&. A typical idiom is that \fIoldfn\fP is the name of a library shell function which is then redefined to call \fBnewfn\fP, thereby installing a modified version of the function\&. .PP +\fIThe \fP\fB\-M\fP\fI and \fP\fB+M\fP\fI flags\fP +.PP Use of the \fB\-M\fP option may not be combined with any of the options handled by \fBtypeset \-f\fP\&. .PP @@ -976,48 +990,93 @@ expressions\&. The name of the function in \fB$0\fP is \fImathfn\fP (not \fIshellfn\fP as would usually be the case), provided the option \fBFUNCTION_ARGZERO\fP is in effect\&. The positional parameters in the shell function correspond to the arguments of the mathematical function call\&. -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\&. .PP -If the additional option \fB\-s\fP is given to \fBfunctions \-M\fP, 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\&. +The result of the last arithmetical expression evaluated inside the shell +function gives the result of the mathematical function\&. This is not limited to +arithmetic substitutions of the form \fB$((\fP\fI\&.\&.\&.\fP\fB))\fP, +but also includes arithmetical expressions evaluated in any other way, including +by the \fBlet\fP builtin, +by \fB((\fP\fI\&.\&.\&.\fP\fB))\fP statements, +and even +by the \fBreturn\fP builtin +and +by array subscripts\&. +Therefore, care must be taken not to use syntactical constructs that perform +arithmetic evaluation after evaluating what is to be the result of the function\&. +For example: .PP -\fBfunctions \-M\fP with no arguments lists all such user\-defined functions in -the same form as a definition\&. With the additional option \fB\-m\fP and -a list of arguments, all functions whose \fImathfn\fP matches one of -the pattern arguments are listed\&. +.RS +.nf +\fB# WRONG +zmath_cube() { + (( $1 * $1 * $1 )) + return 0 +} +functions \-M cube 1 1 zmath_cube +print $(( cube(3) ))\fP +.fi +.RE .PP -\fBfunction +M\fP removes the list of mathematical functions; with the -additional option \fB\-m\fP the arguments are treated as patterns and -all functions whose \fImathfn\fP matches the pattern are removed\&. Note -that the shell function implementing the behaviour is not removed -(regardless of whether its name coincides with \fImathfn\fP)\&. +This will print `\fB0\fP\&' because of the \fBreturn\fP\&. .PP -For example, the following prints the cube of 3: +Commenting the \fBreturn\fP out would lead to a different problem: the +\fB((\fP\fI\&.\&.\&.\fP\fB))\fP statement would become +the last statement in the function, so the \fIreturn status\fP (\fB$?\fP) of the +function would be non\-zero (indicating failure) whenever the \fIarithmetic +result\fP of the function would happen to be zero (numerically): .PP .RS .nf -\fBzmath_cube() { (( $1 * $1 * $1 )) } +\fB# WRONG +zmath_cube() { + (( $1 * $1 * $1 )) +} +functions \-M cube 1 1 zmath_cube +print $(( cube(0) ))\fP +.fi +.RE +.PP +Instead, the \fBtrue\fP builtin can be used: +.PP +.RS +.nf +\fB# RIGHT +zmath_cube() { + (( $1 * $1 * $1 )) + true +} functions \-M cube 1 1 zmath_cube print $(( cube(3) ))\fP .fi .RE .PP -The following string function takes a single argument, including -the commas, so prints 11: +If the additional option \fB\-s\fP is given to \fBfunctions \-M\fP, 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\&. +Thus, the following string function takes a single argument, including +the commas, and prints 11: .PP .RS .nf -\fBstringfn() { (( $#1 )) } +\fBstringfn() { (( $#1 )); true } functions \-Ms stringfn print $(( stringfn(foo,bar,rod) ))\fP .fi .RE +.PP +\fBfunctions \-M\fP with no arguments lists all such user\-defined functions in +the same form as a definition\&. With the additional option \fB\-m\fP and +a list of arguments, all functions whose \fImathfn\fP matches one of +the pattern arguments are listed\&. +.PP +\fBfunction +M\fP removes the list of mathematical functions; with the +additional option \fB\-m\fP the arguments are treated as patterns and +all functions whose \fImathfn\fP matches the pattern are removed\&. Note +that the shell function implementing the behaviour is not removed +(regardless of whether its name coincides with \fImathfn\fP)\&. .RE .TP \fBgetcap\fP @@ -1049,7 +1108,8 @@ is stored in \fBOPTARG\fP\&. The first option to be examined may be changed by explicitly assigning to \fBOPTIND\fP\&. \fBOPTIND\fP has an initial value of \fB1\fP, and is normally set to \fB1\fP upon entry to a shell function and restored -upon exit (this is disabled by the \fBPOSIX_BUILTINS\fP option)\&. \fBOPTARG\fP +upon exit\&. (The \fBPOSIX_BUILTINS\fP option disables this, and also changes +the way the value is calculated to match other shells\&.) \fBOPTARG\fP is not reset and retains its value from the most recent call to \fBgetopts\fP\&. If either of \fBOPTIND\fP or \fBOPTARG\fP is explicitly unset, it remains unset, and the index or option argument is not @@ -1141,6 +1201,28 @@ The \fB\-Z\fP option replaces the shell\&'s argument and environment space with the given string, truncated if necessary to fit\&. This will normally be visible in \fBps\fP (\fIps\fP(1)) listings\&. This feature is typically used by daemons, to indicate their state\&. +.PP +Full job control is only available in the top\-level interactive shell, +not in commands run in the left hand side of pipelines or within +the \fB(\fP\fI\&.\&.\&.\fP\fB)\fP construct\&. However, a snapshot +of the job state at that point is taken, so it is still possible +to use the \fBjobs\fP builtin, or any parameter providing job information\&. +This gives information about the state of jobs at the point the subshell +was created\&. If background processes are created within the subshell, +then instead information about those processes is provided\&. +.PP +For example, +.PP +.RS +.nf +\fBsleep 10 & # Job in background +( # Shell forks +jobs # Shows information about "sleep 10 &" +sleep 5 & # Process in background (no job control) +jobs # Shows information about "sleep 5 &" +)\fP +.fi +.RE .RE .TP .PD 0 @@ -1316,10 +1398,6 @@ Same as \fBtypeset\fP, except that the options \fB\-g\fP, and \fB\-f\fP are not permitted\&. In this case the \fB\-x\fP option does not force the use of \fB\-g\fP, i\&.e\&. exported variables will be local to functions\&. .TP -\fBlog\fP -List all users currently logged in who are affected by -the current setting of the \fBwatch\fP parameter\&. -.TP \fBlogout\fP [ \fIn\fP ] Same as \fBexit\fP, except that it only works in a login shell\&. .TP @@ -1575,7 +1653,7 @@ Same as \fBfc \-e \-\fP\&. \fBread \fP[ \fB\-rszpqAclneE\fP ] [ \fB\-t\fP [ \fInum\fP ] ] [ \fB\-k\fP [ \fInum\fP ] ] [ \fB\-d\fP \fIdelim\fP ] .TP .PD -\fB \fP[ \fB\-u\fP \fIn\fP ] [ \fIname\fP[\fB?\fP\fIprompt\fP] ] [ \fIname\fP \&.\&.\&. ] +\fB \fP[ \fB\-u\fP \fIn\fP ] [ [\fIname\fP][\fB?\fP\fIprompt\fP] ] [ \fIname\fP \&.\&.\&. ] Read one line and break it into fields using the characters in \fB$IFS\fP as separators, except as noted below\&. The first field is assigned to the first \fIname\fP, the second field @@ -1714,10 +1792,20 @@ Same as \fBhash \-r\fP\&. \fBreturn\fP [ \fIn\fP ] Causes a shell function or `\fB\&.\fP\&' script to return to the invoking script with the return status specified by -an arithmetic expression \fIn\fP\&. If \fIn\fP +an arithmetic expression \fIn\fP\&. +For example, the following prints `\fB42\fP\&': +.RS +.PP +.RS +.nf +\fB() { integer foo=40; return "foo + 2" } +echo $?\fP +.fi +.RE +.PP +If \fIn\fP is omitted, the return status is that of the last command executed\&. -.RS .PP If \fBreturn\fP was executed from a trap in a \fBTRAP\fP\fINAL\fP function, the effect is different for zero and non\-zero return status\&. With zero @@ -1726,7 +1814,7 @@ will return to whatever it was previously processing; with a non\-zero status, the shell will behave as interrupted except that the return status of the trap is retained\&. Note that the numeric value of the signal which caused the trap is passed as the first argument, so the statement -`\fBreturn $((128+$1))\fP\&' will return the same status as if the signal +`\fBreturn "128+$1"\fP\&' will return the same status as if the signal had not been trapped\&. .RE .TP @@ -1980,7 +2068,8 @@ unfreezing the tty does not guarantee settings made on the command line are preserved\&. Strings of commands run between editing the command line will see a consistent tty state\&. See also the shell variable \fBSTTY\fP for a means of initialising -the tty before running external commands\&. +the tty before running external commands and/or freezing the tty +around a single command\&. .RE .TP \fBtype\fP [ \fB\-wfpamsS\fP ] \fIname\fP \&.\&.\&. @@ -2013,7 +2102,11 @@ function completes\&. See retain their special attributes when made local\&. .PP For each \fIname\fP\fB=\fP\fIvalue\fP assignment, the parameter -\fIname\fP is set to \fIvalue\fP\&. +\fIname\fP is set to \fIvalue\fP\&. If the assignment is omitted and \fIname\fP +does \fInot\fP refer to an existing parameter, a new parameter is intialized +to empty string, zero, or empty array (as appropriate), \fIunless\fP the +shell option \fBTYPESET_TO_UNSET\fP is set\&. When that option is set, +the parameter attributes are recorded but the parameter remains unset\&. .PP If the shell option \fBTYPESET_SILENT\fP is not set, for each remaining \fIname\fP that refers to a parameter that is already set, the name and @@ -2101,7 +2194,7 @@ a set of three normal command line arguments to \fBtypeset\fP after expansion\&. Hence it is not possible to assign to multiple arrays by this means\&. .PP -Note that each interface to any of the commands my be disabled +Note that each interface to any of the commands may be disabled separately\&. For example, `\fBdisable \-r typeset\fP\&' disables the reserved word interface to \fBtypeset\fP, exposing the builtin interface, while `\fBdisable typeset\fP\&' disables the builtin\&. Note that disabling the @@ -2514,7 +2607,7 @@ will report an error if this fails\&. .TP \fBumask\fP [ \fB\-S\fP ] [ \fImask\fP ] The umask is set to \fImask\fP\&. \fImask\fP can be either -an octal number or a symbolic value as described in \fIchmod\fP(1)\&. +an octal number or a symbolic value as described in the \fIchmod\fP(1) man page\&. If \fImask\fP is omitted, the current value is printed\&. The \fB\-S\fP option causes the mask to be printed as a symbolic value\&. Otherwise, the mask is printed as an octal number\&. Note that in diff --git a/Doc/zshcalsys.1 b/Doc/zshcalsys.1 index e49e2b05c..0a9b557b6 100644 --- a/Doc/zshcalsys.1 +++ b/Doc/zshcalsys.1 @@ -1,4 +1,4 @@ -.TH "ZSHCALSYS" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHCALSYS" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zshcalsys \- zsh calendar system .\" Yodl file: Zsh/calsys.yo @@ -531,7 +531,7 @@ the dates in the calendar file\&. \fBcalendar_add\fP [ \fB\-BL\fP ] \fIevent\fP \&.\&.\&. Adds a single event to the calendar in the appropriate location\&. The event can contain multiple lines, as described in -the section Calendar File Format above\&. +the section `Calendar File Format\&' above\&. Using this function ensures that the calendar file is sorted in date and time order\&. It also makes special arrangements for locking the file while it is altered\&. The old calendar is left in a file diff --git a/Doc/zshcompctl.1 b/Doc/zshcompctl.1 index deb884a07..a70703099 100644 --- a/Doc/zshcompctl.1 +++ b/Doc/zshcompctl.1 @@ -1,4 +1,4 @@ -.TH "ZSHCOMPCTL" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHCOMPCTL" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zshcompctl \- zsh programmable completion .\" Yodl file: Zsh/compctl.yo diff --git a/Doc/zshcompsys.1 b/Doc/zshcompsys.1 index 09cf8c120..1edd707b8 100644 --- a/Doc/zshcompsys.1 +++ b/Doc/zshcompsys.1 @@ -1,4 +1,4 @@ -.TH "ZSHCOMPSYS" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHCOMPSYS" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zshcompsys \- zsh completion system .\" Yodl file: Zsh/compsys.yo @@ -48,7 +48,7 @@ Styles modify various operations of the completion system, such as output formatting, but also what kinds of completers are used (and in what order), or which tags are examined\&. Styles may accept arguments and are manipulated using the \fBzstyle\fP command described in -see \fIzshmodules\fP(1)\&. +\fIzshmodules\fP(1)\&. .PP In summary, tags describe \fIwhat\fP the completion objects are, and style \fBhow\fP they are to be completed\&. At various points of execution, the @@ -175,7 +175,7 @@ root or by the current user\&. If such files or directories are found, avoid these tests and make all files found be used without asking, use the option \fB\-u\fP, and to make \fBcompinit\fP silently ignore all insecure files and directories use the option \fB\-i\fP\&. This security check is skipped -entirely when the \fB\-C\fP option is given\&. +entirely when the \fB\-C\fP option is given, provided the dumpfile exists\&. .PP The security check can be retried at any time by running the function \fBcompaudit\fP\&. This is the same check used by \fBcompinit\fP, but when it @@ -312,13 +312,13 @@ The special contexts for which completion functions can be defined are: The right hand side of an array\-assignment (`\fIname\fP\fB=(\fP\fI\&.\&.\&.\fP\fB)\fP\&') .TP -\fB\-brace\-parameter\-\fP -The name of a parameter expansion within braces (`\fB${\fP\fI\&.\&.\&.\fP\fB}\fP\&') -.TP \fB\-assign\-parameter\-\fP The name of a parameter in an assignment, i\&.e\&. on the left hand side of an `\fB=\fP\&' .TP +\fB\-brace\-parameter\-\fP +The name of a parameter expansion within braces (`\fB${\fP\fI\&.\&.\&.\fP\fB}\fP\&') +.TP \fB\-command\-\fP A word in command position .TP @@ -667,8 +667,8 @@ the section `Bindable Commands\&' below\&. When looking up styles the completion system uses full context names, including the tag\&. Looking up the value of a style therefore consists of two things: the context, which is matched to the most specific (best -fitting) style pattern, and the name of the style itself, which must be -matched exactly\&. The following examples demonstrate that style patterns +fitting) pattern, and the name of the style itself, which must be +matched exactly\&. The following examples demonstrate that patterns may be loosely defined for styles that apply broadly, or as tightly defined as desired for styles that apply in narrower circumstances\&. .PP @@ -686,7 +686,7 @@ put in a startup file (probably \fB\&.zshrc\fP)\&. This gives the \fBverbose\fP style the value \fByes\fP in every context inside the completion system, unless that context has a more -specific definition\&. It is best to avoid giving the context as `\fB*\fP\&' +specific definition\&. It is best to avoid giving the pattern as `\fB*\fP\&' in case the style has some meaning outside the completion system\&. .PP Many such general purpose styles can be configured simply by using the @@ -733,15 +733,21 @@ as \fBmenu\fP and \fBlist\-rows\-first\fP\&. .PP Note that the order in which styles are \fIdefined\fP does not matter; the style mechanism uses the most specific possible match for a particular -style to determine the set of values\&. More precisely, strings are +style to determine the set of values\&. Strings are preferred over patterns (for example, `\fB:completion::complete:::foo\fP\&' is more specific than `\fB:completion::complete:::*\&'\fP), and longer patterns are -preferred over shorter patterns\&. -.PP -A good rule of thumb is that any completion style pattern that needs to -include more than one wildcard (\fB*\fP) and that does not end in a tag -name, should include all six colons (\fB:\fP), possibly surrounding -additional wildcards\&. +preferred over the pattern `\fB*\fP\&'\&. See +\fIzmodules\fP(1) +for details\&. +.PP +Context patterns that use something other than a wildcard (\fB*\fP) to match the +middle parts of the context \-\- the \fIcompleter\fP, \fIcommand\fP, and +\fIargument\fP in +\fB:completion:\fP\fIfunction\fP\fB:\fP\fIcompleter\fP\fB:\fP\fIcommand\fP\fB:\fP\fIargument\fP\fB:\fP\fItag\fP +\-\- should include all six colons (\fB:\fP) explicitly\&. Without this, +a pattern such as \fB:completion:*:foo:*\fP could match \fBfoo\fP against a +component other than the intended one (for example, against \fIcompleter\fP when +a match against \fIcommand\fP was intended)\&. .PP Style names like those of tags are arbitrary and depend on the completion function\&. However, the following two sections list some of the most @@ -874,12 +880,12 @@ for hostnames \fBindexes\fP for array indexes .TP -\fBjobs\fP -for jobs (as listed by the `\fBjobs\fP\&' builtin) -.TP \fBinterfaces\fP for network interfaces .TP +\fBjobs\fP +for jobs (as listed by the `\fBjobs\fP\&' builtin) +.TP \fBkeymaps\fP for names of zsh keymaps .TP @@ -898,12 +904,12 @@ directory when completing arguments of \fBcd\fP and related builtin commands (compare \fBpath\-directories\fP) \-\- when the \fBcdpath\fP array is unset, \fBdirectories\fP is used instead .TP -\fBmanuals\fP -for names of manual pages -.TP \fBmailboxes\fP for e\-mail folders .TP +\fBmanuals\fP +for names of manual pages +.TP \fBmaps\fP for map names (e\&.g\&. NIS maps) .TP @@ -941,10 +947,6 @@ offering the original string as a match \fBother\-accounts\fP used to look up the \fBusers\-hosts\fP style .TP -\fBother\-files\fP -for the names of any non\-directory files\&. This is used instead -of \fBall\-files\fP when the \fBlist\-dirs\-first\fP style is in effect\&. -.TP \fBpackages\fP for packages (e\&.g\&. \fBrpm\fP or installed \fBDebian\fP packages) .TP @@ -1329,6 +1331,11 @@ that the resulting string is the longest unambiguous string possible\&. However, menu completion can be used to cycle through all matches\&. .RE .TP +\fBextra\-verbose\fP +If set, the completion listing is more verbose at the cost of +a probable decrease in completion speed\&. Completion performance +will suffer if this style is set to `true\&'\&. +.TP \fBfake\fP This style may be set for any completion context\&. It specifies additional strings that will always be completed in that @@ -1483,9 +1490,10 @@ If no `\fB:\fP\fItag\fP\&' is given the `\fBfiles\fP' tag will be used\&. The \fItag\fP may also be followed by an optional second colon and a description, which will be used for the `\fB%d\fP\&' in the value of the \fBformat\fP style (if that is set) instead of the default -description supplied by the completion function\&. If the description -given here contains itself a `\fB%d\fP\&', that is replaced with the -description supplied by the completion function\&. +description supplied by the completion function\&. The inclusion +of a description also gives precedence to associated options such as +for completion grouping so it can be used where files should be +separated\&. .PP For example, to make the \fBrm\fP command first complete only names of object files and then the names of all files if there is no matching @@ -1515,6 +1523,19 @@ all files using the pattern `\fB*\fP\&' at the first step and stops when it sees this pattern\&. Note also it will never try a pattern more than once for a single completion attempt\&. .PP +To separate directories into a separate group from the files but still +complete them at the first attempt, a description needs to be given\&. +Note that directories need to be explicitly excluded from the +globbed\-files because `\fB*\fP\&' will match directories\&. For grouping, it +is also necessary to set the \fBgroup\-name\fP style\&. +.PP +.RS +.nf +\fBzstyle \&':completion:*' file\-patterns \e + \&'%p(^\-/):globbed\-files *(\-/):directories:location'\fP +.fi +.RE +.PP During the execution of completion functions, the \fBEXTENDED_GLOB\fP option is in effect, so the characters `\fB#\fP\&', `\fB~\fP' and `\fB^\fP' have special meanings in the patterns\&. @@ -1605,6 +1626,14 @@ builtin command from the \fBzsh/zutil\fP module, see \fIzshmodules\fP(1)\&. .RE .TP +\fBgain\-privileges\fP +If set to \fBtrue\fP, this style enables the use of commands like \fBsudo\fP +or \fBdoas\fP to gain extra privileges when retrieving information for +completion\&. This is only done when a command such as \fBsudo\fP appears on +the command\-line\&. To force the use of, e\&.g\&. \fBsudo\fP or to override any +prefix that might be added due to \fBgain\-privileges\fP, the \fBcommand\fP +style can be used with a value that begins with a hyphen\&. +.TP \fBglob\fP This is used by the \fB_expand\fP completer\&. If it is set to `true\&' (the default), globbing will be attempted on the @@ -1649,6 +1678,9 @@ different types of matches displayed separately, one can just set: .PP All matches for which no group name is defined will be put in a group named \fB\-default\-\fP\&. +.PP +To display the group name in the output, see the \fBformat\fP style (q\&.v\&.) +under the \fBdescriptions\fP tag\&. .RE .TP \fBgroup\-order\fP @@ -1760,11 +1792,6 @@ Excluded values act in a similar fashion to values of the the \fB_ignored\fP completer\&. .RE .TP -\fBextra\-verbose\fP -If set, the completion listing is more verbose at the cost of -a probable decrease in completion speed\&. Completion performance -will suffer if this style is set to `true\&'\&. -.TP \fBignored\-patterns\fP A list of patterns; any trial completion matching one of the patterns will be excluded from consideration\&. The @@ -1802,6 +1829,33 @@ string, menu completion will be started when the string typed by the user is longer than the common prefix to the corresponding IDs\&. .RE .TP +\fBinsert\-sections\fP +This style is used with tags of the form `\fBmanuals\&.\fP\fIX\fP\&' when +completing names of manual pages\&. If set and the \fIX\fP in the tag name matches +the section number of the page being completed, the section number is inserted +along with the page name\&. For example, given +.RS +.PP +.RS +.nf +\fBzstyle \&':completion:*:manuals\&.*' insert\-sections true\fP +.fi +.RE +.PP +\fBman ssh_<TAB>\fP may be completed to \fBman 5 ssh_config\fP\&. +.PP +The value may also be set to one of `\fBprepend\fP\&', or `\fBsuffix\fP'\&. +`\fBprepend\fP\&' behaves the same as `true' as in the above example, while +`\fBsuffix\fP\&' would complete \fBman ssh_<TAB>\fP as \fBman ssh_config\&.5\fP\&. +.PP +This is especially useful in conjunction with \fBseparate\-sections\fP, as +it ensures that the page requested of \fBman\fP corresponds to the one +displayed in the completion listing when there are multiple pages with the +same name (e\&.g\&., \fBprintf(1)\fP and \fBprintf(3)\fP)\&. +.PP +The default for this style is `false\&'\&. +.RE +.TP \fBinsert\-tab\fP If this is set to `true\&', the completion system will insert a TAB character (assuming that was used to start completion) instead @@ -1842,14 +1896,6 @@ the string `\fBpattern\fP\&'\&. Then the pattern on the line is left unchanged if it does not match unambiguously\&. .RE .TP -\fBgain\-privileges\fP -If set to \fBtrue\fP, this style enables the use of commands like \fBsudo\fP -or \fBdoas\fP to gain extra privileges when retrieving information for -completion\&. This is only done when a command such as \fBsudo\fP appears on -the command\-line\&. To force the use of, e\&.g\&. \fBsudo\fP or to override any -prefix that might be added due to \fBgain\-privileges\fP, the \fBcommand\fP -style can be used with a value that begins with a hyphen\&. -.TP \fBkeep\-prefix\fP This style is used by the \fB_expand\fP completer\&. If it is `true\&', the completer will try to keep a prefix containing a tilde or parameter @@ -1866,6 +1912,12 @@ to give up when a single expansion with the restored prefix is the same as the original; hence any remaining completers may be called\&. .RE .TP +\fBknown\-hosts\-files\fP +This style should contain a list of files to search for host names and +(if the \fBuse\-ip\fP style is set) IP addresses in a format compatible with +ssh \fBknown_hosts\fP files\&. If it is not set, the files +\fB/etc/ssh/ssh_known_hosts\fP and \fB~/\&.ssh/known_hosts\fP are used\&. +.TP \fBlast\-prompt\fP This is a more flexible form of the \fBALWAYS_LAST_PROMPT\fP option\&. If it is `true\&', the completion system will try to return the cursor to @@ -1876,12 +1928,6 @@ previous line if this style is `true\&' for all types of match\&. Note that unlike the \fBALWAYS_LAST_PROMPT\fP option this is independent of the numeric argument\&. .TP -\fBknown\-hosts\-files\fP -This style should contain a list of files to search for host names and -(if the \fBuse\-ip\fP style is set) IP addresses in a format compatible with -ssh \fBknown_hosts\fP files\&. If it is not set, the files -\fB/etc/ssh/ssh_known_hosts\fP and \fB~/\&.ssh/known_hosts\fP are used\&. -.TP \fBlist\fP This style is used by the \fB_history_complete_word\fP bindable command\&. If it is set to `true\&' it has no effect\&. If it is set to `false' @@ -1922,11 +1968,10 @@ obtained by setting the style to an empty string (i\&.e\&. \fB\&''\fP)\&. .RE .TP \fBlist\-dirs\-first\fP -This is used by file completion\&. If set, directories to be completed -are listed separately from and before completion for other files, -regardless of tag ordering\&. In addition, the tag \fBother\-files\fP -is used in place of \fBall\-files\fP for the remaining files, to indicate -that no directories are presented with that tag\&. +This is used by file completion and corresponds to a particular +setting of the \fBfile\-patterns\fP style\&. +If set, the default directories to be completed +are listed separately from and before completion for other files\&. .TP \fBlist\-grouped\fP If this style is `true\&' (the default), the completion system will try to @@ -1977,17 +2022,17 @@ This style is tested in the same way as the \fBlist\-packed\fP style and determines whether matches are to be listed in a rows\-first fashion as if the \fBLIST_ROWS_FIRST\fP option were set\&. .TP +\fBlist\-separator\fP +The value of this style is used in completion listing to separate the +string to complete from a description when possible (e\&.g\&. when +completing options)\&. It defaults to `\fB\-\fP\fB\-\fP\&' (two hyphens)\&. +.TP \fBlist\-suffixes\fP This style is used by the function that completes filenames\&. If it is `true\&', and completion is attempted on a string containing multiple partially typed pathname components, all ambiguous components will be shown\&. Otherwise, completion stops at the first ambiguous component\&. .TP -\fBlist\-separator\fP -The value of this style is used in completion listing to separate the -string to complete from a description when possible (e\&.g\&. when -completing options)\&. It defaults to `\fB\-\fP\fB\-\fP\&' (two hyphens)\&. -.TP \fBlocal\fP This is for use with functions that complete URLs for which the corresponding files are available directly from the file system\&. @@ -2448,7 +2493,7 @@ For example, .RE .PP If the current directory is \fB/home/pws/zsh/Src\fP, then -\fBzle_tr\fP\fITAB\fP can be completed to \fBZle/zle_tricky\&.c\fP\&. +\fBzle_tr<TAB>\fP can be completed to \fBZle/zle_tricky\&.c\fP\&. .RE .TP \fBregular\fP @@ -2501,13 +2546,16 @@ The default is to scroll by single lines\&. \fBseparate\-sections\fP This style is used with the \fBmanuals\fP tag when completing names of manual pages\&. If it is `true\&', entries for different sections are -added separately using tag names of the form `\fBmanual\&.\fP\fIX\fP\&', +added separately using tag names of the form `\fBmanuals\&.\fP\fIX\fP\&', where \fIX\fP is the section number\&. When the \fBgroup\-name\fP style is also in effect, pages from different sections will appear separately\&. This style is also used similarly with the \fBwords\fP style when completing words for the dict command\&. It allows words from different -dictionary databases to be added separately\&. +dictionary databases to be added separately\&. See also \fBinsert\-sections\fP\&. +.RS +.PP The default for this style is `false\&'\&. +.RE .TP \fBshow\-ambiguity\fP If the \fBzsh/complist\fP module is loaded, this style can be used to @@ -3644,8 +3692,20 @@ described using the \fIspec\fPs which are of the form: `\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP\&'\&. The \fItag\fPs are offered using \fB_tags\fP and if the tag is requested, the \fIaction\fP is executed with the given description \fIdescr\fP\&. The \fIaction\fPs are those accepted -by the \fB_arguments\fP function (described below), excluding the -`\fB\->\fP\fIstate\fP\&' and `\fB=\fP\fI\&.\&.\&.\fP' forms\&. +by the \fB_arguments\fP function (described below), with the following +exceptions: +.PD 0 +.TP +.PD +\(bu +The `\fB\->\fP\fIstate\fP\&' and `\fB=\fP\fI\&.\&.\&.\fP' forms are not supported\&. + +.TP +\(bu +The `\fB((a\e:bar b\e:baz\fP\fB))\fP\&' form does not need +the colon to be escaped, since the \fIspec\fPs have no colon\-separated fields +after the \fIaction\fP\&. + .PP For example, the \fIaction\fP may be a simple function call: .PP @@ -3800,6 +3860,12 @@ The default \fImatchspec\fP allows partial word completion after `\fB_\fP\&' and \fB\fBr:|[_\-]=* r:|=*\fP\fP .fi .RE +.TP +\fB\-0\fP +When populating values of the `\fBopt_args\fP\&' associative array, don't +backslash\-escape colons and backslashes and use NUL rather than colon for +joining multiple values\&. This option is described in more detail below, under +the heading \fI\fIspec\fPs: actions\fP\&. .PP \fI\fIspec\fPs: overview\fP .PP @@ -4006,6 +4072,7 @@ specific contexts: on the first call `\fB_arguments $global_options\fP\&' is used, and on subsequent calls `\fB_arguments !$^global_options\fP\&'\&. .PP \fI\fIspec\fPs: actions\fP + .PP In each of the forms above the \fIaction\fP determines how completions should be generated\&. Except for the `\fB\->\fP\fIstring\fP\&' @@ -4147,9 +4214,29 @@ the normal arguments from the command line, i\&.e\&. the words from the command line after the command name excluding all options and their arguments\&. Options are stored in the associative array `\fBopt_args\fP\&' with option names as keys and their arguments as -the values\&. For options that have more than one argument these are -given as one string, separated by colons\&. All colons and backslashes -in the original arguments are preceded with backslashes\&. +the values\&. By default, all colons and backslashes in the value are escaped +with backslashes, and if an option has multiple arguments (for example, when +using an \fIoptspec\fP of the form `\fB*\fP\fIoptspec\fP\&'), they are joined with +(unescaped) colons\&. However, if the \fB\-0\fP option was passed, no backslash +escaping is performed, and multiple values are joined with NUL bytes\&. For +example, after `\fBzsh \-o foo:foo \-o bar:bar \-o <TAB>\fP\&', the contents of +`\fBopt_args\fP\&' would be +.PP +.RS +.nf +\fBtypeset \-A opt_args=( [\-o]=\&'foo\e:foo:bar\e:bar:' )\fP +.fi +.RE +.PP +by default, and +.PP +.RS +.nf +\fBtypeset \-A opt_args=( [\-o]=$\&'foo:foo\ex00bar:bar\ex00' )\fP +.fi +.RE +.PP +if \fB_arguments\fP had been called with the \fB\-0\fP option\&. .PP The parameter `\fBcontext\fP\&' is set when returning to the calling function to perform an action of the form `\fB\->\fP\fIstring\fP\&'\&. It is set to an @@ -4398,7 +4485,7 @@ The last two descriptions say what should be completed as arguments\&. The first describes the first argument as a `\fIpostscript file\fP\&' and makes files ending in `\fBps\fP' or `\fBeps\fP' be completed\&. The last description gives all other arguments the -description `\fIpage numbers\fP\&' but does not offer completions\&. +description `\fIpage number\fP\&' but does not offer completions\&. .RE .TP \fB_cache_invalid\fP \fIcache_identifier\fP @@ -4533,6 +4620,14 @@ This function completes names of completers\&. \fB\-p\fP Include the leading underscore (`\fB_\fP\&') in the matches\&. .RE +.TP +\fB_default\fP +This function corresponds to the \fB\-default\-\fP special context which is +applied where no completion is defined\&. It is useful to call it under +certain error conditions such as completion after an unrecognised +subcommand\&. This applies the concept of graceful degradation to the +completion system, allowing it to fallback on basic completion of +commonly useful things like filenames\&. .TP .PD 0 @@ -4611,8 +4706,26 @@ not contain an explanation string to be displayed above the matches\&. If \fB_description\fP is called with more than three arguments, the additional \fIspec\fPs should be of the form `\fIchar\fP\fB:\fP\fIstr\fP\&'\&. These supply escape sequence replacements for the \fBformat\fP style: -every appearance of `\fB%\fP\fIchar\fP\&' will be -replaced by \fIstring\fP\&. +every appearance of `\fB%\fP\fIchar\fP\&' will be replaced by \fIstring\fP\&. +If no additional \fIspec\fPs are given but the description in \fIdescr\fP +conforms to a common form then further escape sequences are set for +elements of that description\&. These elements correspond to a default +value (`\fB%o\fP\&'), the units (`\fB%m\fP') range of acceptable values +(`\fB%r\fP\&') and the remaining initial part of the description (`\fB%h\fP')\&. +The form the description takes consists of specifying the units and +range in parentheses and the default value in square brackets, for +example: +.PP +.RS +.nf +\fB_description times expl \&'timeout (seconds) (0\-60) [20]'\fP +.fi +.RE +.PP +It is possible to use \fBzformat\fP conditional expressions when styling +these elements\&. So, for example, to add `\fBdefault:\fP\&' as a tag but only +when there is a default value to show, the \fBformat\fP style might +include `\fB%(o\&.default: %o\&.)\fP\&'\&. .PP If the \fB\-x\fP option is given, the description will be passed to \fBcompadd\fP using the \fB\-x\fP option instead of the default \fB\-X\fP\&. This @@ -4916,6 +5029,78 @@ no matches have been found\&. This is the same effect as in the \fB\-first\-\fP context\&. .RE .TP +\fB_numbers\fP [ \fIoption\fP \&.\&.\&. ] [ \fIdescription\fP ] [ \fIsuffix\fP \&.\&.\&. ] +This can be used where a number is followed by a suffix to indicate the units\&. +The unit suffixes are completed and can also be included in the description +used when completion is invoked for the preceding number\&. +.RS +.PP +In addition to common \fBcompadd\fP options, \fB_numbers\fP accepts the following +options: +.PP +.PD 0 +.TP +.PD +\fB\-t\fP \fItag\fP +Specify a tag to use instead of the default of \fBnumbers\fP\&. +.TP +\fB\-u\fP \fIunits\fP +Indicate the default units for the number, e\&.g\&. \fBbytes\fP\&. +.TP +\fB\-l\fP \fImin\fP +Specify the lowest possible value for the number\&. +.TP +\fB\-m\fP \fImax\fP +Specify the highest possible value for the number\&. +.TP +\fB\-d\fP \fIdefault\fP +Specify the default value\&. +.TP +\fB\-N\fP +Allow negative numbers\&. This is implied if the range includes a negative\&. +.TP +\fB\-f\fP +Allow decimal numbers\&. +.PP +Where a particular suffix represents the default units for a number, it +should be prefixed with a colon\&. Additionally, suffixes can be followed +by a colon and a description\&. So for example, the following allows the +age of something to be specified, either in seconds or with an optional +suffix with a longer unit of time: +.PP +.RS +.nf +\fB_numbers \-u seconds age :s:seconds m:minutes h:hours d:days\fP +.fi +.RE +.PP +It is typically helpful for units to be presented in order of magnitude +when completed\&. To facilitate this, the order in which they are given +is preserved\&. +.PP +When the \fBformat\fP style is looked up with the \fBdescriptions\fP tag or +the tag specified with \fB\-t\fP, the list of suffixes is available as a +`\fB%x\fP\&' escape sequence\&. This is in addition to the usual sequences +documented under the \fBformat\fP style\&. The form this list takes can also +be configured\&. To this end, the \fBformat\fP style is first looked up with +the tag \fBunit\-suffixes\fP\&. The retrieved format is applied to each +suffix in turn and the results are then concatenated to form the +completed list\&. For the \fBunit\-suffixes\fP format, `\fB%x\fP\&' expands to +the individual suffix and `\fB%X\fP\&' to its description\&. \fB%d\fP' indicates +a default suffix and can be used in a condition\&. The index and reverse +index are set in `\fB%i\fP\&' and `\fB%r\fP' respectively and are useful for +text included only with the first and last suffixes in the list\&. So for +example, the following joins the suffixes together as a comma\-separated +list: +.PP +.RS +.nf +\fBzstyle \&':completion:*:unit\-suffixes' format '%x%(r::,)'\fP +.fi +.RE +.RE +.PP +.TP \fB_options\fP This can be used to complete the names of shell options\&. It provides a matcher specification that ignores a leading `\fBno\fP\&', ignores @@ -5513,10 +5698,13 @@ matches with the given description: .nf \fBlocal expl _wanted tag expl \&'description' \e - compadd matches\&.\&.\&.\fP + compadd \-\- \fImatch1\fP \fImatch2\fP\&.\&.\&.\fP .fi .RE .PP +See also the use of \fB_wanted\fP in the example function in +the subsection `Dynamic named directories\&' in \fIzshexpn\fP(1)\&. +.PP Note that, as for \fB_requested\fP, the \fIcommand\fP must be able to accept options to be passed down to \fBcompadd\fP\&. .PP @@ -5549,8 +5737,6 @@ needs to know what the user\&'s option preferences are\&. These are saved in the \fB_comp_caller_options\fP associative array\&. Option names, spelled in lowercase without underscores, are mapped to one or other of the strings `\fBon\fP\&' and `\fBoff\fP'\&. -.RS -.PP .TP \fB_comp_priv_prefix\fP Completion functions such as \fB_sudo\fP can set the \fB_comp_priv_prefix\fP diff --git a/Doc/zshcompwid.1 b/Doc/zshcompwid.1 index 2e44b5272..54cc3ee72 100644 --- a/Doc/zshcompwid.1 +++ b/Doc/zshcompwid.1 @@ -1,4 +1,4 @@ -.TH "ZSHCOMPWID" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHCOMPWID" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zshcompwid \- zsh completion widgets .\" Yodl file: Zsh/compwid.yo @@ -35,7 +35,7 @@ work even if the widget in question has been re\-bound\&. When this newly defined widget is bound to a key using the \fBbindkey\fP builtin command defined in the \fBzsh/zle\fP module (see \fIzshzle\fP(1)), typing that key will call the shell function `\fBcompleter\fP\&'\&. This -function is responsible for generating the possible matches using the +function is responsible for generating completion matches using the builtins described below\&. As with other ZLE widgets, the function is called with its standard input closed\&. .PP @@ -201,7 +201,7 @@ was generated, the match is accepted\&. The string of an exact match if one was found, otherwise unset\&. .TP \fBignored\fP -The number of words that were ignored because they matched one of the +The number of completions that were ignored because they matched one of the patterns given with the \fB\-F\fP option to the \fBcompadd\fP builtin command\&. .TP @@ -294,8 +294,7 @@ It may be set to any other value; when the widget exits this value will be used in the same way as the value of \fBLISTMAX\fP\&. .TP \fBnmatches\fP -The number of matches generated and accepted by the completion code so -far\&. +The number of matches added by the completion code so far\&. .TP \fBold_insert\fP On entry to the widget this will be set to the number of the match of @@ -331,7 +330,8 @@ value of a parameter assignment\&. .TP \fBpattern_insert\fP Normally this is set to \fBmenu\fP, which specifies that menu completion will -be used whenever a set of matches was generated using pattern matching\&. If +be used whenever a set of matches was generated using \fBpattern_match\fP +(see below)\&. If it is set to any other non\-empty string by the user and menu completion is not selected by other option settings, the code will instead insert any common prefix for the generated matches as with normal completion\&. @@ -347,7 +347,7 @@ additionally a wildcard `\fB*\fP\&' is assumed at the cursor position; if it is empty or unset, metacharacters will be treated literally\&. .RS .PP -Note that the matcher specifications given to the \fBcompadd\fP builtin +Note that the match specifications given to the \fBcompadd\fP builtin command are not used if this is set to a non\-empty string\&. .RE .TP @@ -450,20 +450,19 @@ edited\&. \fB \fP[\fB\-E\fP \fInumber\fP ] .TP .PD -\fB \fP[\fB\-M\fP \fImatch\-spec\fP ] [ \fB\-\fP\fB\-\fP ] [ \fIwords\fP \&.\&.\&. ] +\fB \fP[\fB\-M\fP \fImatch\-spec\fP ] [ \fB\-\fP\fB\-\fP ] [ \fIcompletions\fP \&.\&.\&. ] .RS .PP This builtin command can be used to add matches directly and control all the information the completion code stores with each possible -match\&. The return status is zero if at least one match was added and +completion\&. The return status is zero if at least one match was added and non\-zero if no matches were added\&. .PP -The completion code breaks the string to complete into seven fields in -the order: +The completion code breaks each match into seven fields in the order: .PP .RS .nf -\fI<ipre><apre><hpre><word><hsuf><asuf><isuf>\fP +\fI<ipre><apre><hpre><body><hsuf><asuf><isuf>\fP .fi .RE .PP @@ -473,12 +472,12 @@ is an ignored prefix taken from the command line, the contents of the option\&. With the \fB\-U\fP option, only the string from the \fB\-i\fP option is used\&. The field \fI<apre>\fP is an optional prefix string given with the \fB\-P\fP option\&. The \fI<hpre>\fP field is a string -that is considered part of the match but that should not be shown when +that is considered part of the match but that should not be shown when listing completions, given with the \fB\-p\fP option; for example, functions that do filename generation might specify -a common path prefix this way\&. \fI<word>\fP is the part of the match that -should appear in the list of completions, i\&.e\&. one of the \fIwords\fP given -at the end of the \fBcompadd\fP command line\&. The suffixes \fI<hsuf>\fP, +a common path prefix this way\&. \fI<body>\fP is the part of the match that +should appear in the list of matches shown to the user\&. +The suffixes \fI<hsuf>\fP, \fI<asuf>\fP and \fI<isuf>\fP correspond to the prefixes \fI<hpre>\fP, \fI<apre>\fP and \fI<ipre>\fP and are given by the options \fB\-s\fP, \fB\-S\fP and \fB\-I\fP, respectively\&. @@ -489,53 +488,53 @@ The supported flags are: .TP .PD \fB\-P\fP \fIprefix\fP -This gives a string to be inserted before the given \fIwords\fP\&. The +This gives a string to be inserted before each match\&. The string given is not considered as part of the match and any shell metacharacters in it will not be quoted when the string is inserted\&. .TP \fB\-S\fP \fIsuffix\fP -Like \fB\-P\fP, but gives a string to be inserted after the match\&. +Like \fB\-P\fP, but gives a string to be inserted after each match\&. .TP \fB\-p\fP \fIhidden\-prefix\fP -This gives a string that should be inserted into the command line before the +This gives a string that should be inserted before each match but that should not appear in the list of matches\&. Unless the \fB\-U\fP option is given, this string must be matched as part of the string on the command line\&. .TP \fB\-s\fP \fIhidden\-suffix\fP -Like `\fB\-p\fP\&', but gives a string to insert after the match\&. +Like `\fB\-p\fP\&', but gives a string to insert after each match\&. .TP \fB\-i\fP \fIignored\-prefix\fP -This gives a string to insert into the command line just before any +This gives a string to insert just before any string given with the `\fB\-P\fP\&' option\&. Without `\fB\-P\fP' the string is -inserted before the string given with `\fB\-p\fP\&' or directly before the +inserted before the string given with `\fB\-p\fP\&' or directly before each match\&. .TP \fB\-I\fP \fIignored\-suffix\fP Like \fB\-i\fP, but gives an ignored suffix\&. .TP \fB\-a\fP -With this flag the \fIwords\fP are taken as names of arrays and the -possible matches are their values\&. If only some elements of the -arrays are needed, the \fIwords\fP may also contain subscripts, as in +With this flag the \fIcompletions\fP are taken as names of arrays and the +actual completions are their values\&. If only some elements of the +arrays are needed, the \fIcompletions\fP may also contain subscripts, as in `\fBfoo[2,\-1]\fP\&'\&. .TP \fB\-k\fP -With this flag the \fIwords\fP are taken as names of associative arrays -and the possible matches are their keys\&. As for \fB\-a\fP, the +With this flag the \fIcompletions\fP are taken as names of associative arrays +and the actual completions are their keys\&. As for \fB\-a\fP, the \fIwords\fP may also contain subscripts, as in `\fBfoo[(R)*bar*]\fP\&'\&. .TP \fB\-d\fP \fIarray\fP -This adds per\-match display strings\&. The \fIarray\fP should contain one -element per \fIword\fP given\&. The completion code will then display the -first element instead of the first \fIword\fP, and so on\&. The +This adds per\-completion display strings\&. The \fIarray\fP should contain one +element per \fIcompletion\fP given\&. The completion code will then display the +first element instead of the first \fIcompletion\fP, and so on\&. The \fIarray\fP may be given as the name of an array parameter or directly as a space\-separated list of words in parentheses\&. .RS .PP -If there are fewer display strings than \fIwords\fP, the leftover -\fIwords\fP will be displayed unchanged and if there are more display -strings than \fIwords\fP, the leftover display strings will be silently +If there are fewer display strings than \fIcompletions\fP, the leftover +\fIcompletions\fP will be displayed unchanged and if there are more display +strings than \fIcompletions\fP, the leftover display strings will be silently ignored\&. .RE .TP @@ -562,7 +561,8 @@ by the \fB\-d\fP option)\&. This is the default if `\fB\-o\fP\&' is specified bu the \fIorder\fP argument is omitted\&. .TP \fBnosort\fP -This specifies that the matches are pre\-sorted and their order should be +This specifies that the \fIcompletions\fP +are pre\-sorted and their order should be preserved\&. This value only makes sense alone and cannot be combined with any others\&. .TP @@ -575,7 +575,7 @@ Arrange the matches backwards by reversing the sort ordering\&. .RE .TP \fB\-J\fP \fIgroup\-name\fP -Gives the name of the group of matches the words should be stored in\&. +Gives the name of the group that the matches should be stored in\&. .TP \fB\-V\fP \fIgroup\-name\fP Like \fB\-J\fP but naming an unsorted group\&. This option is identical to @@ -620,13 +620,13 @@ description, it can be escaped using e\&.g\&. \fB${my_str//\e%/%%}\fP\&. .RE .TP \fB\-x\fP \fImessage\fP -Like \fB\-X\fP, but the \fImessage\fP will be printed even if there are no +Like \fB\-X\fP, but the \fImessage\fP will be printed even if there are no matches in the group\&. .TP \fB\-q\fP -The suffix given with \fB\-S\fP will be automatically removed if +The suffix given with \fB\-S\fP will be automatically removed if the next character typed is a blank or does not insert anything, or if -the suffix consists of only one character and the next character typed +the suffix consists of only one character and the next character typed is the same character\&. .TP \fB\-r\fP \fIremove\-chars\fP @@ -650,15 +650,15 @@ list is typed\&. .RE .TP \fB\-R\fP \fIremove\-func\fP -This is another form of the \fB\-r\fP option\&. When a suffix -has been inserted and the completion accepted, the function +This is another form of the \fB\-r\fP option\&. When a match +has been accepted and a suffix has been inserted, the function \fIremove\-func\fP will be called after the next character typed\&. It is passed the length of the suffix as an argument and can use the special parameters available in ordinary (non\-completion) zle widgets (see \fIzshzle\fP(1)) to analyse and modify the command line\&. .TP \fB\-f\fP -If this flag is given, all of the matches built from \fIwords\fP are +If this flag is given, all of the matches built from the \fIcompletions\fP are marked as being the names of files\&. They are not required to be actual filenames, but if they are, and the option \fBLIST_TYPES\fP is set, the characters describing the types of the files in the completion lists will @@ -672,15 +672,14 @@ the \fBAUTO_PARAM_SLASH\fP and \fBAUTO_PARAM_KEYS\fP options be used for the matches\&. .TP \fB\-W\fP \fIfile\-prefix\fP -This string is a pathname that will be -prepended to each of the matches formed by the given \fIwords\fP together +This string is a pathname that will be prepended to each match together with any prefix specified by the \fB\-p\fP option to form a complete filename for testing\&. Hence it is only useful if combined with the \fB\-f\fP flag, as the tests will not otherwise be performed\&. .TP \fB\-F\fP \fIarray\fP -Specifies an array containing patterns\&. Words matching one of these -patterns are ignored, i\&.e\&. not considered to be possible matches\&. +Specifies an array containing patterns\&. \fIcompletions\fP that match one of +these patterns are ignored, that is, not considered to be matches\&. .RS .PP The \fIarray\fP may be the name of an array parameter or a list of @@ -690,8 +689,8 @@ taken as the patterns\&. .RE .TP \fB\-Q\fP -This flag instructs the completion -code not to quote any metacharacters in the words when inserting them +This flag instructs the completion +code not to quote any metacharacters in the matches when inserting them into the command line\&. .TP \fB\-M\fP \fImatch\-spec\fP @@ -702,47 +701,50 @@ between them to form the specification string to use\&. Note that they will only be used if the \fB\-U\fP option is not given\&. .TP \fB\-n\fP -Specifies that the words added are to be used as possible -matches, but are not to appear in the completion listing\&. +Specifies that matching \fIcompletions\fP are to be added to the set of +matches, but are not to be listed to the user\&. .TP \fB\-U\fP -If this flag is given, all words given will be accepted and no matching +If this flag is given, all \fIcompletions\fP are added +to the set of matches and no matching will be done by the completion code\&. Normally this is used in functions that do the matching themselves\&. .TP \fB\-O\fP \fIarray\fP -If this option is given, the \fIwords\fP are \fInot\fP added to the set of -possible completions\&. Instead, matching is done as usual and all of the -\fIwords\fP given as arguments that match the string on the command line +If this option is given, the \fIcompletions\fP are \fInot\fP added to the set of +matches\&. Instead, matching is done as usual and all of the +\fIcompletions\fP that match will be stored in the array parameter whose name is given as \fIarray\fP\&. .TP \fB\-A\fP \fIarray\fP -As the \fB\-O\fP option, except that instead of those of the \fIwords\fP which +As the \fB\-O\fP option, except that instead of those of the \fIcompletions\fP +which match being stored in \fIarray\fP, the strings generated internally by the -completion code are stored\&. For example, -with a matching specification of `\fB\-M "L:|no="\fP\&', the string `\fBnof\fP' -on the command line and the string `\fBfoo\fP\&' as one of the \fIwords\fP, this +completion code are stored\&. For example, +with a match specification of `\fB\-M "L:|no="\fP\&', a current word of `\fBnof\fP' +and \fIcompletions\fP of `\fBfoo\fP\&', this option stores the string `\fBnofoo\fP\&' in the array, whereas the \fB\-O\fP option stores the `\fBfoo\fP\&' originally given\&. .TP \fB\-D\fP \fIarray\fP -As with \fB\-O\fP, the \fIwords\fP are not added to the set of possible -completions\&. Instead, the completion code tests whether each \fIword\fP -in turn matches what is on the line\&. If the \fIn\fPth \fIword\fP does not +As with \fB\-O\fP, the \fIcompletions\fP are not added to the set of matches\&. +Instead, whenever the \fIn\fPth \fIcompletion\fP does not match, the \fIn\fPth element of the \fIarray\fP is removed\&. Elements -for which the corresponding \fIword\fP is matched are retained\&. +for which the corresponding \fIcompletion\fP matches are retained\&. +This option can be used more than once to remove elements from multiple +arrays\&. .TP \fB\-C\fP This option adds a special match which expands to all other matches when inserted into the line, even those that are added after this option is used\&. Together with the \fB\-d\fP option it is possible to -specify a string that should be displayed in the list for this special -match\&. If no string is given, it will be shown as a string containing -the strings that would be inserted for the other matches, truncated to +specify a string that should be displayed in the list for this special +match\&. If no string is given, it will be shown as a string containing +the strings that would be inserted for the other matches, truncated to the width of the screen\&. .TP \fB\-E\fP \fInumber\fP -This option adds \fInumber\fP empty matches after the \fIwords\fP have +This option adds \fInumber\fP empty matches after matching \fIcompletions\fP have been added\&. An empty match takes up space in completion listings but will never be inserted in the line and can\&'t be selected with menu completion or menu selection\&. This makes empty matches only useful to @@ -760,7 +762,7 @@ added\&. .PD \fB\-\fP\fB\-\fP This flag ends the list of flags and options\&. All arguments after it -will be taken as the words to use as matches even if they begin with +will be taken as the \fIcompletions\fP even if they begin with hyphens\&. .PP Except for the \fB\-M\fP flag, if any of these flags is given more than @@ -811,7 +813,7 @@ Without the optional \fInumber\fP, the longest match is taken, but if \fInumber\fP is given, anything up to the \fInumber\fPth match is moved\&. If the \fInumber\fP is negative, the \fInumber\fPth longest match is moved\&. For example, if \fBPREFIX\fP contains the string -`\fBa=b=c\fP\&', then \fBcompset \-P '*\e='\fP will move the string `\fBa=b=\fP' +`\fBa=b=c\fP\&', then \fBcompset \-P '*\e='\fP will move the string `\fBa=b=\fP' into the \fBIPREFIX\fP parameter, but \fBcompset \-P 1 \&'*\e='\fP will move only the string `\fBa=\fP\&'\&. .RE @@ -825,7 +827,7 @@ As \fB\-P\fP, but match the last portion of \fBSUFFIX\fP and transfer the matched portion to the front of the value of \fBISUFFIX\fP\&. .TP \fB\-n\fP \fIbegin\fP [ \fIend\fP ] -If the current word position as specified by the parameter \fBCURRENT\fP +If the current word position as specified by the parameter \fBCURRENT\fP is greater than or equal to \fIbegin\fP, anything up to the \fIbegin\fPth word is removed from the \fBwords\fP array and the value of the parameter \fBCURRENT\fP is decremented by \fIbegin\fP\&. @@ -851,7 +853,7 @@ point to the same word in the changed array\&. If the optional pattern \fIend\-pat\fP is also given, and there is an element in the \fBwords\fP array matching this pattern, the parameters are modified only if the index of this word is higher than the one -given by the \fBCURRENT\fP parameter (so that the matching word has +given by the \fBCURRENT\fP parameter (so that the matching word has to be after the cursor)\&. In this case, the words starting with the one matching \fBend\-pat\fP are also removed from the \fBwords\fP array\&. If \fBwords\fP contains no word matching \fIend\-pat\fP, the @@ -861,7 +863,7 @@ testing and modification is performed as if it were not given\&. \fB\-q\fP The word currently being completed is split on spaces into separate words, -respecting the usual shell quoting conventions\&. The +respecting the usual shell quoting conventions\&. The resulting words are stored in the \fBwords\fP array, and \fBCURRENT\fP, \fBPREFIX\fP, \fBSUFFIX\fP, \fBQIPREFIX\fP, and \fBQISUFFIX\fP are modified to reflect the word part that is completed\&. @@ -916,7 +918,7 @@ true if the test for the \fB\-P\fP option of \fBcompset\fP would succeed\&. true if the test for the \fB\-S\fP option of \fBcompset\fP would succeed\&. .TP \fB\-after\fP \fIbeg\-pat\fP -true if the test of the \fB\-N\fP option with only the \fIbeg\-pat\fP given +true if the test of the \fB\-N\fP option with only the \fIbeg\-pat\fP given would succeed\&. .TP \fB\-between\fP \fIbeg\-pat end\-pat\fP @@ -924,319 +926,352 @@ true if the test for the \fB\-N\fP option with both patterns would succeed\&. .PP .SH "COMPLETION MATCHING CONTROL" .PP -It is possible by use of the -\fB\-M\fP option of the \fBcompadd\fP builtin command to specify how the -characters in the string to be completed (referred to here as the -command line) map onto the characters in the list of matches produced by -the completion code (referred to here as the trial completions)\&. Note -that this is not used if the command line contains a glob pattern and -the \fBGLOB_COMPLETE\fP option is set or the \fBpattern_match\fP of the -\fBcompstate\fP special association is set to a non\-empty string\&. -.PP -The \fImatch\-spec\fP given as the argument to the \fB\-M\fP option (see -`Completion Builtin Commands\&' above) consists of one or more matching descriptions separated by -whitespace\&. Each description consists of a letter followed by a colon -and then the patterns describing which character sequences on the line match -which character sequences in the trial completion\&. Any sequence of -characters not handled in this fashion must match exactly, as usual\&. -.PP -The forms of \fImatch\-spec\fP understood are as follows\&. In each case, the -form with an upper case initial character retains the string already -typed on the command line as the final result of completion, while with -a lower case initial character the string on the command line is changed -into the corresponding part of the trial completion\&. +When the user invokes completion, the current \fIword\fP on the command line +(that is, the word the cursor is currently on) is used to generate a \fImatch +pattern\fP\&. Only those \fIcompletions\fP that match the pattern are offered to the +user as \fImatches\fP\&. +.PP +The default match pattern is generated from the current word by either .PP .PD 0 .TP +.PD +\(bu +appending a `\fB*\fP\&' (matching any number of characters in a completion) +\fIor,\fP +.TP +\(bu +if the shell option \fBCOMPLETE_IN_WORD\fP is set, inserting a `\fB*\fP\&' at the +cursor position\&. +.PP +This narrow pattern can be broadened selectively by passing a \fImatch +specification\fP to the \fBcompadd\fP builtin command through its \fB\-M\fP option +(see +`Completion Builtin Commands\&' above)\&. A match specification consists of one or more \fImatchers\fP separated by +whitespace\&. Matchers in a match specification are applied one at a time, from +left to right\&. Once all matchers have been applied, completions are compared +to the final match pattern and non\-matching ones are discarded\&. +.PP .PD 0 -\fBm:\fP\fIlpat\fP\fB=\fP\fItpat\fP .TP .PD -\fBM:\fP\fIlpat\fP\fB=\fP\fItpat\fP -Here, \fIlpat\fP is a pattern that matches on the command line, -corresponding to \fItpat\fP which matches in the trial completion\&. +\(bu +Note that the \fB\-M\fP option is ignored if the current word contains a glob +pattern and the shell option \fBGLOB_COMPLETE\fP is set or if the +\fBpattern_match\fP key of the special associative array \fBcompstate\fP is set to +a non\-empty value (see +`Completion Special Parameters\&' above)\&. .TP +\(bu +Users of the completion system (see \fIzshcompsys\fP(1)) should generally not use the \fB\-M\fP option directly, but rather use the +\fBmatcher\-list\fP and \fBmatcher\fP styles (see the subsection \fIStandard Styles\fP +in +the documentation for COMPLETION SYSTEM CONFIGURATION in \fIzshcompsys\fP(1))\&. +.PP +Each matcher consists of +.PP .PD 0 -\fBl:\fP\fIlanchor\fP\fB|\fP\fIlpat\fP\fB=\fP\fItpat\fP .TP -.PD 0 -\fBL:\fP\fIlanchor\fP\fB|\fP\fIlpat\fP\fB=\fP\fItpat\fP +.PD +\(bu +a case\-sensitive letter +.TP +\(bu +a `\fB:\fP\&', +.TP +\(bu +one or more patterns separated by pipes (`\fB|\fP\&'), +.TP +\(bu +an equals sign (`\fB=\fP\&'), and .TP +\(bu +another pattern\&. +.PP +The patterns before the `\fB=\fP\&' are used to match substrings of the current +word\&. For each matched substring, the corresponding part of the match pattern +is broadened with the pattern after the `\fB=\fP\&', by means of a logical \fBOR\fP\&. +.PP +Each pattern in a matcher cosists of either +.PP .PD 0 -\fBl:\fP\fIlanchor\fP\fB||\fP\fIranchor\fP\fB=\fP\fItpat\fP .TP +.PD +\(bu +the empty string or +.TP +\(bu +a sequence of +.RS +.PP .PD 0 -\fBL:\fP\fIlanchor\fP\fB||\fP\fIranchor\fP\fB=\fP\fItpat\fP .TP +.PD +\(bu +literal characters (which may be quoted with a `\fB\e\fP\&'), +.TP +\(bu +question marks (`\fB?\fP\&'), +.TP +\(bu +bracket expressions (`\fB[\&.\&.\&.]\fP\&'; see the subsection \fIGlob Operators\fP in +the documentation for GLOB OPERATORS in \fIzshexpn\fP(1)), and/or +.TP +\(bu +brace expressions (see below)\&. + +.RE +.PP +Other shell patterns are not allowed\&. +.PP +A brace expression, like a bracket expression, consists of a list of +.PP .PD 0 -\fBb:\fP\fIlpat\fP\fB=\fP\fItpat\fP .TP .PD -\fBB:\fP\fIlpat\fP\fB=\fP\fItpat\fP -These letters are for patterns that are anchored by another pattern on -the left side\&. Matching for \fIlpat\fP and \fItpat\fP is as for \fBm\fP and -\fBM\fP, but the pattern \fIlpat\fP matched on the command line must be -preceded by the pattern \fIlanchor\fP\&. The \fIlanchor\fP can be blank to -anchor the match to the start of the command line string; otherwise the -anchor can occur anywhere, but must match in both the command line and -trial completion strings\&. -.RS +\(bu +literal characters, +.TP +\(bu +ranges (`\fB0\-9\fP\&'), and/or +.TP +\(bu +character classes (`\fB[:\fP\fIname\fP\fB:]\fP\&')\&. .PP -If no \fIlpat\fP is given but a \fIranchor\fP is, this matches the gap -between substrings matched by \fIlanchor\fP and \fIranchor\fP\&. Unlike -\fIlanchor\fP, the \fIranchor\fP only needs to match the trial -completion string\&. +However, they differ from each other as follows: .PP -The \fBb\fP and \fBB\fP forms are similar to \fBl\fP and \fBL\fP with an empty -anchor, but need to match only the beginning of the word on the command line -or trial completion, respectively\&. -.RE +.PD 0 +.TP +.PD +\(bu +A brace expression is delimited by a pair of braces (`\fB{\&.\&.\&.}\fP\&')\&. +.TP +\(bu +Brace expressions do not support negations\&. That is, an initial +`\fB!\fP\&' or `\fB^\fP' has no special meaning and will be interpreted as a literal +character\&. +.TP +\(bu +When a character in the current word matches the \fIn\fPth pattern in a brace +expression, the corresponding part of the match pattern is broadened only with +the \fIn\fPth pattern of the brace expression on the other side of the `\fB=\fP\&', +if there is one; if there is no brace expression on the other side, then this +pattern is the empty string\&. However, if either brace expression has more +elements than the other, then the excess entries are simply ignored\&. When +comparing indexes, each literal character or character class counts as one +element, but each range is instead expanded to the full list of literal +characters it represents\&. Additionally, if on \fIboth\fP sides of the +`\fB=\fP\&', the \fIn\fPth pattern is `\fB[:upper:]\fP' or `\fB[:lower:]\fP', then these +are expanded as ranges, too\&. +.PP +Note that, although the matching system does not yet handle multibyte +characters, this is likely to be a future extension\&. Hence, using +`\fB[:upper:]\fP\&' and `\fB[:lower:]\fP' is recommended over +`\fBA\-Z\fP\&' and `\fBa\-z\fP'\&. +.PP +Below are the different forms of matchers supported\&. Each \fIuppercase\fP form +behaves exactly like its lowercase counterpart, but adds an additional step +\fIafter\fP the match pattern has filtered out non\-matching completions: Each of +a match\&'s substrings that was matched by a subpattern from an uppercase matcher +is replaced with the corresponding substring of the current word\&. However, +patterns from \fIlowercase\fP matchers have higher weight: If a substring of the +current word was matched by patterns from both a lowercase and an uppercase +matcher, then the lowercase matcher\&'s pattern wins and the corresponding part +of the match is not modified\&. +.PP +Unless indicated otherwise, each example listed assumes \fBCOMPLETE_IN_WORD\fP to +be unset (as it is by default)\&. +.PP +.PD 0 .TP .PD 0 -\fBr:\fP\fIlpat\fP\fB|\fP\fIranchor\fP\fB=\fP\fItpat\fP +\fBm:\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP .TP +.PD +\fBM:\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP +.RS +.PP +For each substring of the current word that matches \fIword\-pat\fP, broaden the +corresponding part of the match pattern to additionally match \fImatch\-pat\fP\&. +.PP .PD 0 -\fBR:\fP\fIlpat\fP\fB|\fP\fIranchor\fP\fB=\fP\fItpat\fP +.TP +.PD +Examples: +.RS +.PP +\fBm:{[:lower:]}={[:upper:]}\fP lets any lower case character in the current word +be completed to itself or its uppercase counterpart\&. So, the completions +`\fBfoo\fP\&', `\fBFOO\fP' and `\fBFoo\fP' will are be considered matches for the word +`\fBfo\fP\&'\&. +.PP +\fBM:_=\fP inserts every underscore from the current word into each match, in the +same relative position, determined by matching the substrings around it\&. So, +given a completion `\fBfoo\fP\&', the word `\fBf_o\fP' will be completed to the match +`\fBf_oo\fP\&', even though the latter was not present as a completion\&. +.RE +.RE .TP .PD 0 -\fBr:\fP\fIlanchor\fP\fB||\fP\fIranchor\fP\fB=\fP\fItpat\fP +\fBb:\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP .TP .PD 0 -\fBR:\fP\fIlanchor\fP\fB||\fP\fIranchor\fP\fB=\fP\fItpat\fP +\fBB:\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP .TP .PD 0 -\fBe:\fP\fIlpat\fP\fB=\fP\fItpat\fP +\fBe:\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP .TP .PD -\fBE:\fP\fIlpat\fP\fB=\fP\fItpat\fP -As \fBl\fP, \fBL\fP, \fBb\fP and \fBB\fP, with the difference that the command -line and trial completion patterns are anchored on the right side\&. -Here an empty \fIranchor\fP and the \fBe\fP and \fBE\fP forms force the -match to the end of the command line or trial completion string\&. -.TP -\fBx:\fP -This form is used to mark the end of matching specifications: -subsequent specifications are ignored\&. In a single standalone list -of specifications this has no use but where matching specifications -are accumulated, such as from nested function calls, it can allow one -function to override another\&. -.PP -Each \fIlpat\fP, \fItpat\fP or \fIanchor\fP is either an empty string or -consists of a sequence of literal characters (which may be quoted with a -backslash), question marks, character classes, and correspondence -classes; ordinary shell patterns are not used\&. Literal characters match -only themselves, question marks match any character, and character -classes are formed as for globbing and match any character in the given -set\&. -.PP -Correspondence classes are defined like character classes, but with two -differences: they are delimited by a pair of braces, and negated classes -are not allowed, so the characters \fB!\fP and \fB^\fP have no special -meaning directly after the opening brace\&. They indicate that a range of -characters on the line match a range of characters in the trial -completion, but (unlike ordinary character classes) paired according to -the corresponding position in the sequence\&. For example, to make any -ASCII lower case letter on the line match the corresponding upper case -letter in the trial completion, you can use `\fBm:{a\-z}={A\-Z}\fP\&' -(however, see below for the recommended form for this)\&. More -than one pair of classes can occur, in which case the first class before -the \fB=\fP corresponds to the first after it, and so on\&. If one side has -more such classes than the other side, the superfluous classes behave -like normal character classes\&. In anchor patterns correspondence classes -also behave like normal character classes\&. -.PP -The standard `\fB[:\fP\fIname\fP\fB:]\fP\&' forms described for standard shell -patterns (see -the section FILENAME GENERATION in \fIzshexpn\fP(1)) -may appear in correspondence classes as well as normal character -classes\&. The only special behaviour in correspondence classes is if -the form on the left and the form on the right are each one of -\fB[:upper:]\fP, \fB[:lower:]\fP\&. In these cases the -character in the word and the character on the line must be the same up -to a difference in case\&. Hence to make any lower case character on the -line match the corresponding upper case character in the trial -completion you can use `\fBm:{[:lower:]}={[:upper:]}\fP\&'\&. Although the -matching system does not yet handle multibyte characters, this is likely -to be a future extension, at which point this syntax will handle -arbitrary alphabets; hence this form, rather than the use of explicit -ranges, is the recommended form\&. In other cases -`\fB[:\fP\fIname\fP\fB:]\fP\&' forms are allowed\&. If the two forms on the left -and right are the same, the characters must match exactly\&. In remaining -cases, the corresponding tests are applied to both characters, but they -are not otherwise constrained; any matching character in one set goes -with any matching character in the other set: this is equivalent to the -behaviour of ordinary character classes\&. -.PP -The pattern \fItpat\fP may also be one or two stars, `\fB*\fP\&' or -`\fB**\fP\&'\&. This means that the pattern on the command line can match -any number of characters in the trial completion\&. In this case the -pattern must be anchored (on either side); in the case of a single -star, the \fIanchor\fP then determines how much of the trial completion -is to be included \-\- only the characters up to the next appearance of -the anchor will be matched\&. With two stars, substrings matched by the -anchor can be matched, too\&. +\fBE:\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP +.RS +.PP +For each consecutive substring at the \fBb:\fPeginning or \fBe:\fPnd of the current +word that matches \fIword\-pat\fP, broaden the corresponding part of the match +pattern to additionally match \fImatch\-pat\fP\&. .PP +.PD 0 +.TP +.PD Examples: +.RS .PP -The keys of the \fBoptions\fP association defined by the \fBparameter\fP -module are the option names in all\-lower\-case form, without -underscores, and without the optional \fBno\fP at the beginning even -though the builtins \fBsetopt\fP and \fBunsetopt\fP understand option names -with upper case letters, underscores, and the optional \fBno\fP\&. The -following alters the matching rules so that the prefix \fBno\fP and any -underscore are ignored when trying to match the trial completions -generated and upper case letters on the line match the corresponding -lower case letters in the words: +`\fBb:\-=+\fP\&' lets any number of minuses at the start of the current word be +completed to a minus or a plus\&. .PP -.RS -.nf -\fBcompadd \-M \&'L:|[nN][oO]= M:_= M:{[:upper:]}={[:lower:]}' \- \e - ${(k)options} \fP -.fi +`\fBB:0=\fP\&' adds all zeroes at the beginning of the current word to the +beginning of each match\&. +.RE .RE +.TP +.PD 0 +\fBl:\fP\fB|\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD 0 +\fBL:\fP\fB|\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD 0 +\fBR:\fP\fIword\-pat\fP\fB|\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD +\fBr:\fP\fIword\-pat\fP\fB|\fP\fB=\fP\fImatch\-pat\fP +.RS .PP -The first part says that the pattern `\fB[nN][oO]\fP\&' at the beginning -(the empty anchor before the pipe symbol) of the string on the -line matches the empty string in the list of words generated by -completion, so it will be ignored if present\&. The second part does the -same for an underscore anywhere in the command line string, and the -third part uses correspondence classes so that any -upper case letter on the line matches the corresponding lower case -letter in the word\&. The use of the upper case forms of the -specification characters (\fBL\fP and \fBM\fP) guarantees that what has -already been typed on the command line (in particular the prefix -\fBno\fP) will not be deleted\&. -.PP -Note that the use of \fBL\fP in the first part means that it matches -only when at the beginning of both the command line string and the -trial completion\&. I\&.e\&., the string `\fB_NO_f\fP\&' would not be -completed to `\fB_NO_foo\fP\&', nor would `\fBNONO_f\fP' be completed to -`\fBNONO_foo\fP\&' because of the leading underscore or the second -`\fBNO\fP\&' on the line which makes the pattern fail even though they are -otherwise ignored\&. To fix this, one would use `\fBB:[nN][oO]=\fP\&' -instead of the first part\&. As described above, this matches at the -beginning of the trial completion, independent of other characters or -substrings at the beginning of the command line word which are ignored -by the same or other \fImatch\-spec\fPs\&. -.PP -The second example makes completion case insensitive\&. This is just -the same as in the option example, except here we wish to retain the -characters in the list of completions: +If there is a substring at the \fBl:\fPeft or \fBr:\fPight edge of the current word +that matches \fIword\-pat\fP, then broaden the corresponding part of the match +pattern to additionally match \fImatch\-pat\fP\&. .PP +For each \fBl:\fP, \fBL:\fP, \fBr:\fP and \fBR:\fP matcher (including the ones below), +the pattern \fImatch\-pat\fP may also be a `\fB*\fP\&'\&. This matches any number of +characters in a completion\&. +.PP +.PD 0 +.TP +.PD +Examples: .RS -.nf -\fBcompadd \-M \&'m:{[:lower:]}={[:upper:]}' \&.\&.\&. \fP -.fi -.RE .PP -This makes lower case letters match their upper case counterparts\&. -To make upper case letters match the lower case forms as well: +`\fBr:|=*\fP\&' appends a `\fB*\fP' to the match pattern, even when +\fBCOMPLETE_IN_WORD\fP is set and the cursor is not at the end of the current +word\&. .PP -.RS -.nf -\fBcompadd \-M \&'m:{[:lower:][:upper:]}={[:upper:][:lower:]}' \&.\&.\&. \fP -.fi +If the current word starts with a minus, then `\fBL:|\-=\fP\&' will prepend it to +each match\&. +.RE .RE +.TP +.PD 0 +\fBl:\fP\fIanchor\fP\fB|\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD 0 +\fBL:\fP\fIanchor\fP\fB|\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD 0 +\fBr:\fP\fIword\-pat\fP\fB|\fP\fIanchor\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD +\fBR:\fP\fIword\-pat\fP\fB|\fP\fIanchor\fP\fB=\fP\fImatch\-pat\fP +.RS .PP -A nice example for the use of \fB*\fP patterns is partial word -completion\&. Sometimes you would like to make strings like `\fBc\&.s\&.u\fP\&' -complete to strings like `\fBcomp\&.source\&.unix\fP\&', i\&.e\&. the word on the -command line consists of multiple parts, separated by a dot in this -example, where each part should be completed separately \-\- note, -however, that the case where each part of the word, i\&.e\&. `\fBcomp\fP\&', -`\fBsource\fP\&' and `\fBunix\fP' in this example, is to be completed from -separate sets of matches -is a different problem to be solved by the implementation of the -completion widget\&. The example can be handled by: +For each substring of the current word that matches \fIword\-pat\fP and has on +its \fBl:\fPeft or \fBr:\fPight another substring matching \fIanchor\fP, broaden the +corresponding part of the match pattern to additionally match \fImatch\-pat\fP\&. +.PP +Note that these matchers (and the ones below) modify only what is matched by +\fIword\-pat\fP; they do not change the matching behavior of what is matched by +\fIanchor\fP (or \fIcoanchor\fP; see the matchers below)\&. Thus, unless its +corresponding part of the match pattern has been modified, the anchor in the +current word has to match literally in each completion, just like any other +substring of the current word\&. +.PP +If a matcher includes at least one anchor (which includes the matchers with two +anchors, below), then \fImatch\-pat\fP may also be `\fB*\fP\&' or `\fB**\fP'\&. `\fB*\fP' +can match any part of a completion that does not contain any substrings +matching \fIanchor\fP, whereas a `\fB**\fP\&' can match any part of a completion, +period\&. (Note that this is different from the behavior of `\fB*\fP\&' in the +anchorless forms of `\fBl:\fP\&' and `\fBr:\fP' and and also different from `\fB*\fP' +and `\fB**\fP\&' in glob expressions\&.) .PP +.PD 0 +.TP +.PD +Examples: .RS -.nf -\fBcompadd \-M \&'r:|\&.=* r:|=*' \e - \- comp\&.sources\&.unix comp\&.sources\&.misc \&.\&.\&.\fP -.fi -.RE .PP -The first specification says that \fIlpat\fP is the empty string, while -\fIanchor\fP is a dot; \fItpat\fP is \fB*\fP, so this can match anything -except for the `\fB\&.\fP\&' from the anchor in -the trial completion word\&. So in `\fBc\&.s\&.u\fP\&', the matcher sees `\fBc\fP', -followed by the empty string, followed by the anchor `\fB\&.\fP\&', and -likewise for the second dot, and replaces the empty strings before the -anchors, giving `\fBc\fP[\fBomp\fP]\fB\&.s\fP[\fBources\fP]\fB\&.u\fP[\fBnix\fP]\&', where -the last part of the completion is just as normal\&. -.PP -With the pattern shown above, the string `\fBc\&.u\fP\&' could not be -completed to `\fBcomp\&.sources\&.unix\fP\&' because the single star means -that no dot (matched by the anchor) can be skipped\&. By using two stars -as in `\fBr:|\&.=**\fP\&', however, `\fBc\&.u\fP' could be completed to -`\fBcomp\&.sources\&.unix\fP\&'\&. This also shows that in some cases, -especially if the anchor is a real pattern, like a character class, -the form with two stars may result in more matches than one would like\&. -.PP -The second specification is needed to make this work when the cursor is -in the middle of the string on the command line and the option -\fBCOMPLETE_IN_WORD\fP is set\&. In this case the completion code would -normally try to match trial completions that end with the string as -typed so far, i\&.e\&. it will only insert new characters at the cursor -position rather than at the end\&. However in our example we would like -the code to recognise matches which contain extra characters after the -string on the line (the `\fBnix\fP\&' in the example)\&. Hence we say that the -empty string at the end of the string on the line matches any characters -at the end of the trial completion\&. -.PP -More generally, the specification +`\fBr:|\&.=*\fP\&' makes the completion `\fBcomp\&.sources\&.unix\fP' a match for the word +`\fB\&.\&.u\fP\&' \-\- but \fInot\fP for the word `\fB\&.u\fP'\&. .PP -.RS -.nf -\fBcompadd \-M \&'r:|[\&.,_\-]=* r:|=*' \&.\&.\&. \fP -.fi +Given a completion `\fB\-\fP\fB\-foo\fP\&', the matcher `\fBL:\-\-|no\-=\fP' will complete +the word `\fB\-\fP\fB\-no\-\fP\&' to the match `\fB\-\fP\fB\-no\-foo\fP'\&. +.RE .RE +.TP +.PD 0 +\fBl:\fP\fIanchor\fP\fB||\fP\fIcoanchor\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD 0 +\fBL:\fP\fIanchor\fP\fB||\fP\fIcoanchor\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD 0 +\fBr:\fP\fIcoanchor\fP\fB||\fP\fIanchor\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD +\fBR:\fP\fIcoanchor\fP\fB||\fP\fIanchor\fP\fB=\fP\fImatch\-pat\fP +.RS .PP -allows one to complete words with abbreviations before any of the -characters in the square brackets\&. For example, to -complete \fBveryverylongfile\&.c\fP rather than \fBveryverylongheader\&.h\fP -with the above in effect, you can just type \fBvery\&.c\fP before attempting -completion\&. +For any two consecutive substrings of the current word that match \fIanchor\fP +and \fIcoanchor\fP, in the order given, insert the pattern \fImatch\-pat\fP +between their corresponding parts in the match pattern\&. .PP -The specifications with both a left and a right anchor are useful to -complete partial words whose parts are not separated by some -special character\&. For example, in some places strings have to be -completed that are formed `\fBLikeThis\fP\&' (i\&.e\&. the separate parts are -determined by a leading upper case letter) or maybe one has to -complete strings with trailing numbers\&. Here one could use the simple -form with only one anchor as in: +Note that, unlike \fIanchor\fP, the pattern \fIcoanchor\fP does not change what +`\fB*\fP\&' can match\&. .PP +.PD 0 +.TP +.PD +Examples: .RS -.nf -\fBcompadd \-M \&'r:|[[:upper:]0\-9]=* r:|=*' LikeTHIS FooHoo 5foo123 5bar234\fP -.fi -.RE .PP -But with this, the string `\fBH\fP\&' would neither complete to `\fBFooHoo\fP' -nor to `\fBLikeTHIS\fP\&' because in each case there is an upper case -letter before the `\fBH\fP\&' and that is matched by the anchor\&. Likewise, -a `\fB2\fP\&' would not be completed\&. In both cases this could be changed -by using `\fBr:|[[:upper:]0\-9]=**\fP\&', but then `\fBH\fP' completes to both -`\fBLikeTHIS\fP\&' and `\fBFooHoo\fP' and a `\fB2\fP' matches the other -strings because characters can be inserted before every upper case -letter and digit\&. To avoid this one would use: +`\fBr:?||[[:upper:]]=*\fP\&' will complete the current word `\fBfB\fP' to +`\fBfooBar\fP\&', but it will not complete it to `\fBfooHooBar\fP' (because `\fB*\fP' +here cannot match anything that includes a match for `\fB[[:upper:]]\fP), nor +will it complete `\fBB\fP\&' to `\fBfooBar\fP' (because there is no character in the +current word to match \fIcoanchor\fP)\&. .PP -.RS -.nf -\fBcompadd \-M \&'r:[^[:upper:]0\-9]||[[:upper:]0\-9]=** r:|=*' \e - LikeTHIS FooHoo foo123 bar234\fP -.fi +Given the current word `\fBpass\&.n\fP\&' and a completion `\fBpass\&.byname\fP', the +matcher `\fBL:\&.||[[:alpha:]]=by\fP\&' will produce the match `\fBpass\&.name\fP'\&. +.RE .RE +.TP +\fBx:\fP +.RS .PP -By using these two anchors, a `\fBH\fP\&' matches only upper case `\fBH\fP's that -are immediately preceded by something matching the left anchor -`\fB[^[:upper:]0\-9]\fP\&'\&. The effect is, of course, that `\fBH\fP' matches only -the string `\fBFooHoo\fP\&', a `\fB2\fP' matches only `\fBbar234\fP' and so on\&. +Ignore this matcher and all matchers to its right\&. .PP -When using the completion system (see -\fIzshcompsys\fP(1)), users can define match specifications that are to be used for -specific contexts by using the \fBmatcher\fP and \fBmatcher\-list\fP -styles\&. The values for the latter will be used everywhere\&. +This matcher is used to mark the end of a match specification\&. In a single +standalone list of matchers, this has no use, but where match specifications +are concatenated, as is often the case when using the +completion system (see \fIzshcompsys\fP(1)), it can allow one match specification to override another\&. +.RE .PP .SH "COMPLETION WIDGET EXAMPLE" .PP @@ -1267,5 +1302,5 @@ matches, e\&.g\&.: .fi .RE .PP -This function will complete files in the current directory matching the +This function will complete files in the current directory matching the current word\&. diff --git a/Doc/zshcontrib.1 b/Doc/zshcontrib.1 index 849d0865f..b6fb67bb6 100644 --- a/Doc/zshcontrib.1 +++ b/Doc/zshcontrib.1 @@ -1,4 +1,4 @@ -.TH "ZSHCONTRIB" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHCONTRIB" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zshcontrib \- user contributions to zsh .\" Yodl file: Zsh/contrib.yo @@ -41,7 +41,7 @@ distribution in your home directory, you would use the commands: .RS .nf \fBmkdir ~/zsh_help -perl ~/zsh\-5\&.8\&.1/Util/helpfiles ~/zsh_help\fP +perl ~/zsh\-5\&.8\&.1\&.2\-test/Util/helpfiles ~/zsh_help\fP .fi .RE .PP @@ -181,7 +181,7 @@ Run \fBzkbd\fP either as an autoloaded function, or as a shell script: .PP .RS .nf -\fBzsh \-f ~/zsh\-5\&.8\&.1/Functions/Misc/zkbd\fP +\fBzsh \-f ~/zsh\-5\&.8\&.1\&.2\-test/Functions/Misc/zkbd\fP .fi .RE .PP @@ -237,7 +237,7 @@ command and redirect the output into a file: .PP .RS .nf -\fB\&. ~/zsh\-5\&.8\&.1/Util/reporter > zsh\&.report\fP +\fB\&. ~/zsh\-5\&.8\&.1\&.2\-test/Util/reporter > zsh\&.report\fP .fi .RE .PP @@ -374,7 +374,7 @@ is added to the array of widgets to be invoked in the given hook context\&. Widgets are invoked in the order they were added, with .RS .nf -\fB\fBzle \fP\fIwidgetname\fP\fB \-Nw \-\- "$@"\fP\fP +\fB\fBzle \fP\fIwidgetname\fP\fB \-Nw \-f "nolast" \-\- "$@"\fP\fP .fi .RE .PP @@ -494,7 +494,7 @@ allows you to edit the list of directories, one per line\&. The list can be edited to any extent you like; no sanity checking is performed\&. Completion is available\&. No quoting is necessary (except for newlines, where I have in any case no sympathy); directories are in -unabbreviated from and contain an absolute path, i\&.e\&. they start with \fB/\fP\&. +unabbreviated form and contain an absolute path, i\&.e\&. they start with \fB/\fP\&. Usually the first entry should be left as the current directory\&. .TP \fB\-p \&'\fP\fIpattern\fP\fB'\fP @@ -647,7 +647,7 @@ changes to descendant directories; earlier directories on the list are not pruned\&. For example, changing from ~pws/yet/another to ~pws/some/other/dir does not cause ~pws to be pruned\&. .TP -\fBpattern:\fIpattern\fP\fP +\fBpattern:\fP\fIpattern\fP Gives a zsh pattern for directories that should not be added to the recent list (if not already there)\&. This element can be repeated to add different patterns\&. For example, @@ -705,7 +705,7 @@ more details\&. .PP The dynamic directory naming system is described in the subsection \fIDynamic named directories\fP of -the section \fIFilename Expansion\fP in \fIexpn\fP(1)\&. In this, a reference to +the section \fIFilename Expansion\fP in \fIzshexpn\fP(1)\&. In this, a reference to \fB~[\fP\fI\&.\&.\&.\fP\fB]\fP is expanded by a function found by the hooks mechanism\&. .PP @@ -754,7 +754,7 @@ Then arrange for the wrapper to be run as a zsh_directory_name hook: .PP .RS .nf -\fBautoload \-Uz add\-zsh\-hook zsh_diretory_name_generic zdn_mywrapper +\fBautoload \-Uz add\-zsh\-hook zsh_directory_name_generic zdn_mywrapper add\-zsh\-hook \-U zsh_directory_name zdn_mywrapper\fP .fi .RE @@ -1269,7 +1269,7 @@ This is used by the Perforce backend (\fBp4\fP) to decide if it should contact the Perforce server to find out if a directory is managed by Perforce\&. This is the only reliable way of doing this, but runs the risk of a delay if the server name cannot be found\&. If the -server (more specifically, the \fBhost\fP\fB:\fP\fBport\fP pair describing the +server (more specifically, the \fIhost\fP\fB:\fP\fIport\fP pair describing the server) cannot be contacted, its name is put into the associative array \fBvcs_info_p4_dead_servers\fP and is not contacted again during the session until it is removed by hand\&. If you do not set this style, the \fBp4\fP @@ -1288,7 +1288,7 @@ If there are two different ways of gathering information, you can select the simpler one by setting this style to true; the default is to use the not\-that\-simple code, which is potentially a lot slower but might be more accurate in all possible cases\&. This style is -used by the \fBbzr\fP and \fBhg\fP backends\&. In the case of \fBhg\fP it will invoke +used by the \fBbzr\fP, \fBhg\fP, and \fBgit\fP backends\&. In the case of \fBhg\fP it will invoke the external hexdump program to parse the binary dirstate cache file; this method will not return the local revision number\&. .TP @@ -1343,7 +1343,7 @@ This boolean style controls whether a backend should attempt to gather a list of unapplied patches (for example with Mercurial Queue patches)\&. .RS .PP -Used by the \fBquilt\fP and \fBhg\fP backends\&. +Used by the \fBquilt\fP, \fBhg\fP, and \fBgit\fP backends\&. .RE .PP The default values for these styles in all contexts are: @@ -1504,7 +1504,7 @@ The \fBquilt\fP `standalone\&' backend sets this expando to the same value as th \fB%Q\fP Quilt series information\&. When quilt is used (either in `addon\&' mode or as a `standalone' backend), -this expando is set to quilt series\&' \fBpatch\-format\fP string\&. +this expando is set to the quilt series\&' \fBpatch\-format\fP string\&. The \fBset\-patch\-format\fP hook and \fBnopatch\-format\fP style are honoured\&. .RS .PP @@ -1516,7 +1516,8 @@ In \fBbranchformat\fP these replacements are done: .PD 0 .TP \fB%b\fP -The branch name\&. +The branch name\&. For \fBhg\fP, the branch name can include a +topic name\&. .TP \fB%r\fP The current revision number or the \fBhgrevformat\fP style for @@ -1613,7 +1614,7 @@ a directory that holds quilt\&'s patches needs to be found\&. That directory is configurable via the `\fBQUILT_PATCHES\fP\&' environment variable\&. If that variable exists its value is used, otherwise the value `\fBpatches\fP\&' is assumed\&. The value from \fB$QUILT_PATCHES\fP can be overwritten using the -`\fBquilt\-patches\fP\&' style\&. (Note: you can use \fBvcs_info\fP to keep the value +`\fBquilt\-patch\-dir\fP\&' style\&. (Note: you can use \fBvcs_info\fP to keep the value of \fB$QUILT_PATCHES\fP correct all the time via the \fBpost\-quilt\fP hook)\&. .PP When the directory in question is found, quilt is assumed to be active\&. To @@ -1714,7 +1715,7 @@ See \fBHooks in vcs_info\fP below for details\&. .TP \fBvcs_info_lastmsg\fP -Outputs the last \fB${vcs_info_msg_*_}\fP value\&. +Outputs the current values of \fB${vcs_info_msg_*_}\fP\&. Takes into account the value of the \fBuse\-prompt\-escapes\fP style in \fB\&':vcs_info:formats:command:\-all\-'\fP\&. It also only prints \fBmax\-exports\fP values\&. @@ -1867,16 +1868,27 @@ is generated; the \fBuse\-quilt\fP zstyle must be true for \fBquilt\fP (the \fBm and \fBstgit\fP backends are active by default)\&. .RS .PP -This hook gets the names of all applied patches which \fBvcs_info\fP collected -so far in the opposite order, which means that the first argument is the +The arguments to this hook describe applied patches +in the opposite order, which means that the first argument is the top\-most patch and so forth\&. .PP +When the patches\&' log messages can be extracted, those are embedded +within each argument after a space, so each argument is of the form +`\fIpatch\-name\fP \fIfirst line of the log message\fP\&', where \fIpatch\-name\fP +contains no whitespace\&. The \fBmq\fP backend passes arguments of +the form `\fIpatch name\fP\&', with possible embedded spaces, but without +extracting the patch\&'s log message\&. +.PP When setting \fBret\fP to non\-zero, the string in \fB${hook_com[applied\-string]}\fP will be available as \fB%p\fP in the \fBpatch\-format\fP and \fBnopatch\-format\fP styles\&. This hook is, in concert with \fBset\-patch\-format\fP, responsible for \fB%\fP\-escaping that value for use in the prompt\&. (See the \fBOddities\fP section\&.) +.PP +The \fBquilt\fP backend passes to this hook the inputs +\fB${hook_com[quilt\-patches\-dir]}\fP and, if it has been +determined, \fB${hook_com[quilt\-pc\-dir]}\fP\&. .RE .TP \fBgen\-unapplied\-string\fP @@ -1886,15 +1898,21 @@ generated; the \fBget\-unapplied\fP style must be true\&. .RS .PP This hook gets the names of all unapplied patches which \fBvcs_info\fP -collected so far in order, which means that the first argument is +in order, which means that the first argument is the patch next\-in\-line to be applied and so forth\&. .PP +The format of each argument is as for \fBgen\-applied\-string\fP, above\&. +.PP When setting \fBret\fP to non\-zero, the string in \fB${hook_com[unapplied\-string]}\fP will be available as \fB%u\fP in the \fBpatch\-format\fP and \fBnopatch\-format\fP styles\&. This hook is, in concert with \fBset\-patch\-format\fP, responsible for \fB%\fP\-escaping that value for use in the prompt\&. (See the \fBOddities\fP section\&.) +.PP +The \fBquilt\fP backend passes to this hook the inputs +\fB${hook_com[quilt\-patches\-dir]}\fP and, if it has been +determined, \fB${hook_com[quilt\-pc\-dir]}\fP\&. .RE .TP \fBgen\-mqguards\-string\fP @@ -1993,6 +2011,10 @@ This hook is, in concert with the \fBgen\-applied\-string\fP or \fBgen\-unapplied\-string\fP hooks if they are defined, responsible for \fB%\fP\-escaping the final \fBpatch\-format\fP value for use in the prompt\&. (See the \fBOddities\fP section\&.) +.PP +The \fBquilt\fP backend passes to this hook the inputs +\fB${hook_com[quilt\-patches\-dir]}\fP and, if it has been +determined, \fB${hook_com[quilt\-pc\-dir]}\fP\&. .RE .TP \fBset\-message\fP @@ -2081,22 +2103,38 @@ Display the revision number in yellow for \fBbzr\fP and \fBsvn\fP: .RS .nf \fBzstyle \&':vcs_info:(svn|bzr):*' \e + branchformat \&'%b%%F{yellow}:%r'\fP +.fi +.RE +.PP +The doubled percent sign is explained in +the \fBOddities\fP section\&. +.PP +Alternatively, one can use the raw colour codes directly: +.PP +.RS +.nf +\fBzstyle \&':vcs_info:(svn|bzr):*' \e branchformat \&'%b%{'${fg[yellow]}'%}:%r'\fP .fi .RE .PP -If you want colors, make sure you enclose the color codes in \fB%{\fP\fI\&.\&.\&.\fP\fB%}\fP +Normally when a variable is interpolated into a format string, the variable +needs to be \fB%\fP\-escaped\&. In this example we skipped that because we assume +the value of \fB${fg[yellow]}\fP doesn\&'t contain any \fB%\fP signs\&. +.PP +Make sure you enclose the color codes in \fB%{\fP\fI\&.\&.\&.\fP\fB%}\fP if you want to use the string provided by \fBvcs_info\fP in prompts\&. .PP Here is how to print the VCS information as a command (not in a prompt): .RS .nf -\fBalias vcsi=\&'vcs_info command; vcs_info_lastmsg'\fP +\fBvcsi() { vcs_info interactive; vcs_info_lastmsg }\fP .fi .RE .PP This way, you can even define different formats for output via -\fBvcs_info_lastmsg\fP in the \&'\fB:vcs_info:*:command:*\fP' namespace\&. +\fBvcs_info_lastmsg\fP in the \&'\fB:vcs_info:*:interactive:*\fP' namespace\&. .PP Now as promised, some code that uses hooks: say, you\&'d like to replace the string `svn' by `subversion' in @@ -2210,7 +2248,7 @@ This concludes our guided tour through zsh\&'s \fBvcs_info\fP\&. .PP You should make sure all the functions from the \fBFunctions/Prompts\fP directory of the source distribution are available; they all begin with -the string `\fBprompt_\fP\&' except for the special function`\fBpromptinit\fP'\&. +the string `\fBprompt_\fP\&' except for the special function `\fBpromptinit\fP'\&. You also need the `\fBcolors\fP\&' and `\fBadd\-zsh\-hook\fP' functions from \fBFunctions/Misc\fP\&. All these functions may already be installed on your system; if not, @@ -2334,31 +2372,36 @@ setopts (\fBpromptbang\fP, etc\&.) are turned on, all other prompt\-related options are turned off\&. The \fBprompt_opts\fP array preserves setopts even beyond the scope of \fBlocaloptions\fP, should your function need that\&. .TP -Modify precmd and preexec -Use of \fBadd\-zsh\-hook\fP is recommended\&. The \fBprecmd\fP and \fBpreexec\fP -hooks are automatically adjusted if the prompt theme changes or is -disabled\&. +Modify hooks +Use of \fBadd\-zsh\-hook\fP and \fBadd\-zle\-hook\-widget\fP is recommended (see +the \fBManipulating Hook Functions\fP section above)\&. +All hooks that follow the naming pattern \fBprompt_\fP\fItheme\fP\fB_\fP\fIhook\fP +are automatically removed when the prompt theme changes or is disabled\&. .TP Declare cleanup If your function makes any other changes that should be undone when the theme is disabled, your setup function may call .RS +.PP +.RS .nf \fBprompt_cleanup \fIcommand\fP\fP .fi .RE +.PP where \fIcommand\fP should be suitably quoted\&. If your theme is ever disabled or replaced by another, \fIcommand\fP is executed with \fBeval\fP\&. You may declare more than one such cleanup hook\&. +.RE .TP Define preview -Define or autoload a function \fBprompt_\fIname\fP_preview\fP to display +Define or autoload a function \fBprompt_\fP\fIname\fP\fB_preview\fP to display a simulated version of your prompt\&. A simple default previewer is defined by \fBpromptinit\fP for themes that do not define their own\&. This preview function is called by `\fBprompt \-p\fP\&'\&. .TP Provide help -Define or autoload a function \fBprompt_\fIname\fP_help\fP to display +Define or autoload a function \fBprompt_\fP\fIname\fP\fB_help\fP to display documentation or help text for your theme\&. This help function is called by `\fBprompt \-h\fP\&'\&. .PP @@ -2669,7 +2712,7 @@ directly\&. .RE .TP \fBbracketed\-paste\-magic\fP -The \fBbracketed\-paste\fP widget (see subsection Miscellaneous in +The \fBbracketed\-paste\fP widget (see the subsection `Miscellaneous\&' in \fIzshzle\fP(1)) inserts pasted text literally into the editor buffer rather than interpret it as keystrokes\&. This disables some common usages where the self\-insert @@ -2857,6 +2900,16 @@ Edit the command line using your visual editor, as in \fBksh\fP\&. \fBbindkey \-M vicmd v edit\-command\-line\fP .fi .RE +.PP +The editor to be used can also be specified using the \fBeditor\fP style in +the context of the widget\&. It is specified as an array of command and +arguments: +.PP +.RS +.nf +\fBzstyle :zle:edit\-command\-line editor gvim \-f\fP +.fi +.RE .RE .TP \fBexpand\-absolute\-path\fP @@ -3811,7 +3864,7 @@ investigate the command word found\&. The default is \fBwhence \-c\fP\&. .TP \fBzcalc\-auto\-insert\fP This function is useful together with the \fBzcalc\fP function described in -the section Mathematical Functions\&. +the section `Mathematical Functions\&'\&. It should be bound to a key representing a binary operator such as `\fB+\fP\&', `\fB\-\fP', `\fB*\fP' or `\fB/\fP'\&. When running in zcalc, if the key occurs at the start of the line or immediately following @@ -4252,7 +4305,8 @@ Calling \fBzsh\-mime\-setup\fP with the option \fB\-v\fP causes verbose output to be shown during the setup operation\&. .PP The system respects the \fBmailcap\fP flags \fBneedsterminal\fP and -\fBcopiousoutput\fP, see \fImailcap\fP(4)\&. +\fBcopiousoutput\fP; see \fImailcap\fP(4) or \fImailcap\fP(5) +(the man page\&'s name varies across platforms)\&. .PP The functions use the following styles, which are defined with the \fBzstyle\fP builtin command (see \fIzshmodules\fP(1))\&. They should be defined @@ -4330,7 +4384,7 @@ types even if they are executable\&. As this example shows, the complete file name is matched against the pattern, regardless of how the file was passed to the handler\&. The file is resolved to a full path using the \fB:P\fP modifier described in -the subsection Modifiers in \fIzshexpn\fP(1); +the subsection `Modifiers\&' in \fIzshexpn\fP(1); this means that symbolic links are resolved where possible, so that links into other file systems behave in the correct fashion\&. .RE @@ -4995,6 +5049,11 @@ Same as \fBzed \-f\fP\&. This function does not appear in the zsh distribution, but can be created by linking \fBzed\fP to the name \fBfned\fP in some directory in your \fBfpath\fP\&. .TP +\fBhisted\fP [ [ \fIname\fP ] \fIsize\fP ] +Same as \fBzed \-h\fP\&. This function does not appear in the zsh +distribution, but can be created by linking \fBzed\fP to the name \fBhisted\fP +in some directory in your \fBfpath\fP\&. +.TP \fBis\-at\-least\fP \fIneeded\fP [ \fIpresent\fP ] Perform a greater\-than\-or\-equal\-to comparison of two strings having the format of a zsh version number; that is, a string of numbers and text with @@ -5031,7 +5090,7 @@ See also the \fBpager\fP, \fBprompt\fP and \fBrprompt\fP styles below\&. .TP \fBregexp\-replace\fP \fIvar\fP \fIregexp\fP \fIreplace\fP Use regular expressions to perform a global search and replace operation -on a variable\&. POSIX extended regular expressions are used, +on a variable\&. POSIX extended regular expressions (ERE) are used, unless the option \fBRE_MATCH_PCRE\fP has been set, in which case Perl\-compatible regular expressions are used (this requires the shell to be linked against the \fBpcre\fP @@ -5050,6 +5109,9 @@ and arithmetic expressions which will be replaced: in particular, a reference to \fB$MATCH\fP will be replaced by the text matched by the pattern\&. .PP The return status is 0 if at least one match was performed, else 1\&. +.PP +Note that if using POSIX EREs, the \fB^\fP or word boundary operators +(where available) may not work properly\&. .RE .TP \fBrun\-help\fP \fIcmd\fP @@ -5096,26 +5158,30 @@ your search path, in order to be found and used by \fBrun\-help\fP\&. .PD 0 .TP .PD 0 -run\-help\-git +\fBrun\-help\-btrfs\fP +.TP +.PD 0 +\fBrun\-help\-git\fP .TP .PD 0 -run\-help\-ip +\fBrun\-help\-ip\fP .TP .PD 0 -run\-help\-openssl +\fBrun\-help\-openssl\fP .TP .PD 0 -run\-help\-p4 +\fBrun\-help\-p4\fP .TP .PD 0 -run\-help\-sudo +\fBrun\-help\-sudo\fP .TP .PD 0 -run\-help\-svk +\fBrun\-help\-svk\fP .TP .PD \fBrun\-help\-svn\fP Assistant functions for the +\fBbtrfs\fP, \fBgit\fP, \fBip\fP, \fBopenssl\fP, @@ -5233,7 +5299,7 @@ counts the number of arguments passed to each execution of \fIcommand\fP, \fIincluding\fP any \fIarg\fP list\&. Also, any time \fB\-i\fP or \fB\-I\fP is used, each \fIinput\fP is processed separately as if by `\fB\-L\fP \fB1\fP\&'\&. .PP -For details of the other \fBzargs\fP options, see \fIxargs\fP(1) (but note +For details of the other \fBzargs\fP options, see the \fIxargs\fP(1) man page (but note the difference in function between \fBzargs\fP and \fBxargs\fP) or run \fBzargs\fP with the \fB\-\fP\fB\-help\fP option\&. .RE @@ -5241,6 +5307,9 @@ the difference in function between \fBzargs\fP and \fBxargs\fP) or run .PD 0 \fBzed\fP [ \fB\-f\fP [ \fB\-x\fP \fInum\fP ] ] \fIname\fP .TP +.PD 0 +\fBzed\fP [ \fB\-h\fP [ \fIname\fP ] \fIsize\fP ] +.TP .PD \fBzed \-b\fP This function uses the ZLE editor to edit a file or function\&. @@ -5257,7 +5326,14 @@ the given number of spaces; `\fB\-x 2\fP\&' is consistent with the layout of functions distributed with the shell\&. .PP Without \fB\-f\fP, \fIname\fP is the path name of the file to edit, which need -not exist; it is created on write, if necessary\&. +not exist; it is created on write, if necessary\&. With \fB\-h\fP, the file is +presumed to contain history events\&. +.PP +When no file name is provided for \fB\-h\fP the current shell history is edited +in place\&. The history is renumbered when zed exits successfully\&. +.PP +When editing history, multi\-line events must have a trailing backslash on +every line before the last\&. .PP While editing, the function sets the main keymap to \fBzed\fP and the vi command keymap to \fBzed\-vicmd\fP\&. These will be copied from the existing @@ -5273,16 +5349,19 @@ suitable for putting into a startup file\&. Note that, if rerun, this will overwrite the existing \fBzed\fP and \fBzed\-vicmd\fP keymaps\&. .PP Completion is available, and styles may be set with the context prefix -`\fB:completion:zed\fP\&'\&. -.PP -A zle widget \fBzed\-set\-file\-name\fP is available\&. This can be called by -name from within zed using `\fB\eex zed\-set\-file\-name\fP\&' (note, however, that -because of zed\&'s rebindings you will have to type \fB^j\fP at the end instead -of the return key), or can be bound to a key in either of the \fBzed\fP or -\fBzed\-vicmd\fP keymaps after `\fBzed \-b\fP\&' has been run\&. When the widget is -called, it prompts for a new name for the file being edited\&. When zed -exits the file will be written under that name and the original file will -be left alone\&. The widget has no effect with `\fBzed \-f\fP\&'\&. +`\fB:completion:zed:\fP\&'\&. +.PP +A zle widget \fBzed\-set\-file\-name\fP is available\&. This can be called +by name from within zed using `\fB\eex zed\-set\-file\-name\fP\&' or can be +bound to a key in either of the \fBzed\fP or \fBzed\-vicmd\fP keymaps after +`\fBzed \-b\fP\&' has been run\&. When the widget is called, it prompts for +a new name for the file being edited\&. When zed exits the file will be +written under that name and the original file will be left alone\&. The +widget has no effect when invoked from `\fBzed \-f\fP\&'\&. The completion +context is changed to `\fB:completion:zed\-set\-file\-name:\fP\&'\&. When editing +the current history with `\fBzed \-h\fP\&', the history is first updated and +then the file is written, but the global setting of \fBHISTFILE\fP is not +altered\&. .PP While \fBzed\-set\-file\-name\fP is running, zed uses the keymap \fBzed\-normal\-keymap\fP, which is linked from the main keymap in effect @@ -5332,7 +5411,7 @@ the same result, the destination was an existing regular file and \fB\-f\fP was not given) causes the entire function to abort without doing anything\&. .PP -In addition to pattern replacement, the variable \fB$f\fP can be referrred +In addition to pattern replacement, the variable \fB$f\fP can be referred to in the second (replacement) argument\&. This makes it possible to use variable substitution to alter the argument; see examples below\&. .PP diff --git a/Doc/zshexpn.1 b/Doc/zshexpn.1 index 9987820e8..9ec445400 100644 --- a/Doc/zshexpn.1 +++ b/Doc/zshexpn.1 @@ -1,4 +1,4 @@ -.TH "ZSHEXPN" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHEXPN" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zshexpn \- zsh expansion and substitution .\" Yodl file: Zsh/expn.yo @@ -66,7 +66,7 @@ EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1)) is the number that is to be a A history expansion begins with the first character of the \fBhistchars\fP parameter, which is `\fB!\fP\&' by default, and may occur anywhere on the command line, including inside double quotes (but not inside single quotes -\fB\&'\&.\&.\&.'\fP or C\-style quotes \fB$'\&.\&.\&.'\fP nor when escaped with a backslash)\&. +\fB\&'\&.\&.\&.'\fP or C\-style quotes \fB$'\&.\&.\&.'\fP nor when escaped with a backslash)\&. .PP The first character is followed by an optional event designator (see the section `Event Designators\&') and then an optional word @@ -277,8 +277,10 @@ expansion\&. .TP \fBP\fP Turn a file name into an absolute path, like \fBrealpath(3)\fP\&. -The resulting path will be absolute, have neither `\fB\&.\fP\&' nor `\fB\&.\&.\fP' components, -and refer to the same directory entry as the input filename\&. +The resulting path will be absolute, +will refer to the same directory entry as the input filename, +and none of its components will be symbolic links or equal to +`\fB\&.\fP\&' or `\fB\&.\&.\fP'\&. .RS .PP Unlike \fBrealpath(3)\fP, non\-existent trailing components are @@ -490,7 +492,7 @@ which treats \fIarg\fP as a file name and replaces it with the file\&'s contents\&. .PP The \fB=\fP form is useful as both the \fB/dev/fd\fP and the named pipe -implementation of \fB<(\fP\fI\&.\&.\&.\fP\fB)\fP have drawbacks\&. In +implementation of \fB<(\fP\fI\&.\&.\&.\fP\fB)\fP have drawbacks\&. In the former case, some programmes may automatically close the file descriptor in question before examining the file on the command line, particularly if this is necessary for security reasons such as when the @@ -507,8 +509,7 @@ efficiently written (provided the \fBMULTIOS\fP option is set) as: .PP .RS .nf -\fB\fBpaste <(cut \-f1\fP \fIfile1\fP\fB) <(cut \-f3\fP \fIfile2\fP\fB)\fP \e -\fB> >(\fP\fIprocess1\fP\fB) > >(\fP\fIprocess2\fP\fB)\fP\fP +\fB\fBpaste <(cut \-f1\fP \fIfile1\fP\fB) <(cut \-f3\fP \fIfile2\fP\fB)\fP \fB> >(\fP\fIprocess1\fP\fB) > >(\fP\fIprocess2\fP\fB)\fP\fP .fi .RE .PP @@ -943,7 +944,11 @@ of the string \fB$\-\fP and the array \fB$*\fP respectively\&. If the \fB#\fP to be treated in this fashion\&. .RE .TP +.PD 0 \fB${^\fP\fIspec\fP\fB}\fP +.TP +.PD +\fB${^^\fP\fIspec\fP\fB}\fP Turn on the \fBRC_EXPAND_PARAM\fP option for the evaluation of \fIspec\fP; if the `\fB^\fP\&' is doubled, turn it off\&. When this option is set, array expansions of the form @@ -965,7 +970,11 @@ happening later\&. If word splitting is also in effect the elements\&. .RE .TP +.PD 0 \fB${=\fP\fIspec\fP\fB}\fP +.TP +.PD +\fB${==\fP\fIspec\fP\fB}\fP Perform word splitting using the rules for \fBSH_WORD_SPLIT\fP during the evaluation of \fIspec\fP, but regardless of whether the parameter appears in double quotes; if the `\fB=\fP\&' is doubled, turn it off\&. @@ -979,7 +988,11 @@ of \fIspec\fP \fIbefore\fP the assignment to \fIname\fP is performed\&. This affects the result of array assignments with the \fBA\fP flag\&. .RE .TP +.PD 0 \fB${~\fP\fIspec\fP\fB}\fP +.TP +.PD +\fB${~~\fP\fIspec\fP\fB}\fP Turn on the \fBGLOB_SUBST\fP option for the evaluation of \fIspec\fP; if the `\fB~\fP\&' is doubled, turn it off\&. When this option is set, the string resulting from the expansion will be interpreted as a @@ -1030,9 +1043,10 @@ following flags are supported: .TP .PD \fB#\fP -Evaluate the resulting words as numeric expressions and output the -characters corresponding to the resulting integer\&. Note that this form is -entirely distinct from use of the \fB#\fP without parentheses\&. +Evaluate the resulting words as numeric expressions and interpret +these as character codes\&. Output the corresponding characters\&. Note +that this form is entirely distinct from use of the \fB#\fP without +parentheses\&. .RS .PP If the \fBMULTIBYTE\fP option is set and the number is greater than 127 @@ -1041,7 +1055,7 @@ If the \fBMULTIBYTE\fP option is set and the number is greater than 127 .TP \fB%\fP Expand all \fB%\fP escapes in the resulting words in the same way as in -prompts (see +prompts (see EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1))\&. If this flag is given twice, full prompt expansion is done on the resulting words, depending on the setting of the \fBPROMPT_PERCENT\fP, \fBPROMPT_SUBST\fP and \fBPROMPT_BANG\fP @@ -1171,22 +1185,31 @@ Convert all letters in the result to lower case\&. \fBn\fP Sort decimal integers numerically; if the first differing characters of two test strings are not digits, sorting -is lexical\&. Integers with more initial zeroes -are sorted before those with fewer or none\&. Hence the array `\fBfoo1 foo02 +is lexical\&. `\fB+\fP\&' and `\fB\-\fP' are not treated specially; they are treated as +any other non\-digit\&. Integers with more initial zeroes +are sorted before those with fewer or none\&. Hence the array `\fBfoo+24 foo1 foo02 foo2 foo3 foo20 foo23\fP\&' is sorted into the order shown\&. May be combined with `\fBi\fP\&' or `\fBO\fP'\&. .TP +\fB\-\fP +As \fBn\fP, but a leading minus sign indicates a negative decimal +integer\&. A leading minus sign not followed by an integer does not trigger +numeric sorting\&. +Note that `\fB+\fP\&' signs are not handled specially (this may change in the +future)\&. +.TP \fBo\fP Sort the resulting words in ascending order; if this appears on its own the sorting is lexical and case\-sensitive (unless the locale renders it case\-insensitive)\&. Sorting in ascending order is the default for other forms of sorting, so this is ignored if combined -with `\fBa\fP\&', `\fBi\fP' or `\fBn\fP'\&. +with `\fBa\fP\&', `\fBi\fP', `\fBn\fP' or `\fB\-\fP'\&. .TP \fBO\fP Sort the resulting words in descending order; `\fBO\fP\&' without `\fBa\fP', -`\fBi\fP\&' or `\fBn\fP' sorts in reverse lexical order\&. May be combined -with `\fBa\fP\&', `\fBi\fP' or `\fBn\fP' to reverse the order of sorting\&. +`\fBi\fP\&', `\fBn\fP' or `\fB\-\fP' sorts in reverse lexical order\&. May be +combined with `\fBa\fP\&', `\fBi\fP', `\fBn\fP' or `\fB\-\fP' to reverse the +order of sorting\&. .TP \fBP\fP This forces the value of the parameter \fIname\fP to be interpreted as a @@ -1277,6 +1300,11 @@ for readonly parameters \fBtag\fP for tagged parameters .TP +\fBtied\fP +for parameters tied to another parameter in the manner of \fBPATH\fP +(colon\-separated list) and \fBpath\fP (array), whether these are +special parameters or user\-defined with `\fBtypeset \-T\fP\&' +.TP \fBexport\fP for exported parameters .TP @@ -1487,17 +1515,32 @@ i\&.e\&. \fB"${(@s\&.:\&.)line}"\fP\&. \fBZ:\fP\fIopts\fP\fB:\fP As \fBz\fP but takes a combination of option letters between a following pair of delimiter characters\&. With no options the effect is identical -to \fBz\fP\&. \fB(Z+c+)\fP +to \fBz\fP\&. The following options are available: +.RS +.PP +.PD 0 +.TP +.PD +\fB(Z+c+)\fP causes comments to be parsed as a string and retained; any field in the resulting array beginning with an unquoted comment character is a -comment\&. \fB(Z+C+)\fP causes comments to be parsed +comment\&. +.TP +\fB(Z+C+)\fP +causes comments to be parsed and removed\&. The rule for comments is standard: anything between a word starting with the third character of \fB$HISTCHARS\fP, default \fB#\fP, up to -the next newline is a comment\&. \fB(Z+n+)\fP causes +the next newline is a comment\&. +.TP +\fB(Z+n+)\fP +causes unquoted newlines to be treated as ordinary whitespace, else they are treated as if they are shell code delimiters and converted to -semicolons\&. Options are combined within the same set of delimiters, +semicolons\&. +.PP +Options are combined within the same set of delimiters, e\&.g\&. \fB(Z+Cn+)\fP\&. +.RE .TP \fB_:\fP\fIflags\fP\fB:\fP The underscore (\fB_\fP) flag is reserved for future use\&. As of this @@ -1506,7 +1549,7 @@ underscore, other than an empty pair of delimiters, is treated as an error, and the flag itself has no effect\&. .PP The following flags are meaningful with the \fB${\fP\&.\&.\&.\fB#\fP\&.\&.\&.\fB}\fP or -\fB${\fP\&.\&.\&.\fB%\fP\&.\&.\&.\fB}\fP forms\&. The \fBS\fP and \fBI\fP flags may also be +\fB${\fP\&.\&.\&.\fB%\fP\&.\&.\&.\fB}\fP forms\&. The \fBS\fP, \fBI\fP, and \fB*\fP flags may also be used with the \fB${\fP\&.\&.\&.\fB/\fP\&.\&.\&.\fB}\fP forms\&. .PP .PD 0 @@ -1594,6 +1637,10 @@ form using `\fB%%\fP\&' will remove the same matches as for `\fB##\fP' in revers order\&. .RE .TP +\fB*\fP +Enable \fBEXTENDED_GLOB\fP for substitution via \fB${\fP\&.\&.\&.\fB/\fP\&.\&.\&.\fB}\fP or +\fB${\fP\&.\&.\&.\fB//\fP\&.\&.\&.\fB}\fP\&. +.TP \fBB\fP Include the index of the beginning of the match in the result\&. .TP @@ -1611,7 +1658,6 @@ Include the length of the match in the result\&. Include the unmatched portion in the result (the \fIR\fPest)\&. .PP .SS "Rules" -.PP Here is a summary of the rules for substitution; this assumes that braces are present around the substitution, i\&.e\&. \fB${\fP\fI\&.\&.\&.\fP\fB}\fP\&. Some particular examples are given below\&. Note that the Zsh Development Group accepts @@ -1840,7 +1886,7 @@ This produces the result \fBb\fP\&. First, the inner substitution \fB"${foo}"\fP, which has no array (\fB@\fP) flag, produces a single word result \fB"bar baz"\fP\&. The outer substitution \fB"${(@)\&.\&.\&.[1]}"\fP detects that this is a scalar, so that (despite the `\fB(@)\fP\&' flag) the subscript -picks the first character\&. +picks the first character\&. .TP \fB"${${(@)foo}[1]}"\fP This produces the result `\fBbar\fP\&'\&. In this case, the inner substitution @@ -1869,7 +1915,7 @@ empty string will then be elided, as it is not in double quotes\&. .PP .SH "COMMAND SUBSTITUTION" A command enclosed in parentheses preceded by a dollar sign, like -`\fB$(\fP\&.\&.\&.\fB)\fP\&', or quoted with grave +`\fB$(\fP\&.\&.\&.\fB)\fP\&', or quoted with grave accents, like `\fB`\fP\&.\&.\&.\fB`\fP\&', is replaced with its standard output, with any trailing newlines deleted\&. If the substitution is not enclosed in double quotes, the @@ -1952,7 +1998,7 @@ has similar effects\&. .PP To combine brace expansion with array expansion, see the \fB${^\fP\fIspec\fP\fB}\fP form described -in the section Parameter Expansion +in the section `Parameter Expansion\&' above\&. .PP .SH "FILENAME EXPANSION" @@ -1982,8 +2028,8 @@ The \fBPUSHD_MINUS\fP option exchanges the effects of `\fB~+\fP\&' and `\fB~\-\fP' where they are followed by a number\&. .PP -.SS "Dynamic named directories" .PP +.SS "Dynamic named directories" If the function \fBzsh_directory_name\fP exists, or the shell variable \fBzsh_directory_name_functions\fP exists and contains an array of function names, then the functions are used to implement dynamic @@ -2113,7 +2159,6 @@ exists by that name, the word is replaced by the full pathname of the command\&. .PP .SS "Notes" -.PP Filename expansion is performed on the right hand side of a parameter assignment, including those appearing after commands of the \fBtypeset\fP family\&. In this case, the right hand side will be treated @@ -2224,7 +2269,8 @@ is not sensitive to the locale: .PD \fB[:IDENT:]\fP The character is allowed to form part of a shell identifier, such -as a parameter name +as a parameter name; this test respects the \fBPOSIX_IDENTIFIERS\fP +option .TP \fB[:IFS:]\fP The character is used as an input field separator, i\&.e\&. is contained in the @@ -2558,7 +2604,7 @@ qualifiers are also not applied in ordinary pattern matching\&. .TP \fBu\fP Respect the current locale in determining the presence of multibyte -characters in a pattern, provided the shell was compiled with +characters in a pattern, provided the shell was compiled with \fBMULTIBYTE_SUPPORT\fP\&. This overrides the \fBMULTIBYTE\fP option; the default behaviour is taken from the option\&. Compare \fBU\fP\&. (Mnemonic: typically multibyte characters are from Unicode in the UTF\-8 @@ -2818,19 +2864,19 @@ expected, if combined with a `\fB=\fP\&', the value given must match the file\-modes exactly, with a `\fB+\fP\&', at least the bits in the given number must be set in the file\-modes, and with a `\fB\-\fP\&', the bits in the number must not be set\&. Giving a `\fB?\fP\&' instead of a -octal digit anywhere in the number ensures that the corresponding bits +octal digit anywhere in the number ensures that the corresponding bits in the file\-modes are not checked, this is only useful in combination with `\fB=\fP\&'\&. .RS .PP If the qualifier `\fBf\fP\&' is followed by any other character anything -up to the next matching character (`\fB[\fP\&', `\fB{\fP', and `\fB<\fP' match +up to the next matching character (`\fB[\fP\&', `\fB{\fP', and `\fB<\fP' match `\fB]\fP\&', `\fB}\fP', and `\fB>\fP' respectively, any other character matches itself) is taken as a list of comma\-separated \fIsub\-spec\fPs\&. Each \fIsub\-spec\fP may be either an octal number as described above or a list of any of the characters `\fBu\fP\&', `\fBg\fP', `\fBo\fP\&', and `\fBa\fP', followed by a `\fB=\fP', a `\fB+\fP', or a -`\fB\-\fP\&', followed by a list of any of the characters `\fBr\fP', `\fBw\fP', +`\fB\-\fP\&', followed by a list of any of the characters `\fBr\fP', `\fBw\fP', `\fBx\fP\&', `\fBs\fP', and `\fBt\fP', or an octal digit\&. The first list of characters specify which access rights are to be checked\&. If a `\fBu\fP\&' is given, those for the owner of the file are used, if a `\fBg\fP\&' is @@ -2839,7 +2885,7 @@ of other users, and the `\fBa\fP\&' says to test all three groups\&. The `\fB=\fP\&', `\fB+\fP', and `\fB\-\fP' again says how the modes are to be checked and have the same meaning as described for the first form above\&. The second list of characters finally says which access rights -are to be expected: `\fBr\fP\&' for read access, `\fBw\fP' for write access, +are to be expected: `\fBr\fP\&' for read access, `\fBw\fP' for write access, `\fBx\fP\&' for the right to execute the file (or to search a directory), `\fBs\fP\&' for the setuid and setgid bits, and `\fBt\fP' for the sticky bit\&. @@ -2848,7 +2894,7 @@ Thus, `\fB*(f70?)\fP\&' gives the files for which the owner has read, write, and execute permission, and for which other group members have no rights, independent of the permissions for other users\&. The pattern `\fB*(f\-100)\fP\&' gives all files for which the owner does not have -execute permission, and `\fB*(f:gu+w,o\-rx:)\fP\&' gives the files for which +execute permission, and `\fB*(f:gu+w,o\-rx:)\fP\&' gives the files for which the owner and the other members of the group have at least write permission, and for which other users don\&'t have read or execute permission\&. @@ -2981,7 +3027,9 @@ negates all qualifiers following it .TP \fB\-\fP toggles between making the qualifiers work on symbolic links (the -default) and the files they point to +default) and the files they point to, if any; any symbolic link for +whose target the `\fBstat\fP\&' system call fails (whatever the cause of the +failure) is treated as a file in its own right .TP \fBM\fP sets the \fBMARK_DIRS\fP option for the current pattern @@ -3009,22 +3057,50 @@ Implies \fBoN\fP when no \fBo\fP\fIc\fP qualifier is used\&. .RE .TP \fBo\fP\fIc\fP -specifies how the names of the files should be sorted\&. If \fIc\fP is -\fBn\fP they are sorted by name; if it is \fBL\fP they -are sorted depending on the size (length) of the files; if \fBl\fP -they are sorted by the number of links; if \fBa\fP, \fBm\fP, or \fBc\fP -they are sorted by the time of the last access, modification, or -inode change respectively; if \fBd\fP, files in subdirectories appear before +specifies how the names of the files should be sorted\&. The following values +of \fIc\fP sort in the following ways: +.RS +.PP +.PD 0 +.TP +\fBn\fP +By name\&. +.TP +\fBL\fP +By the size (length) of the files\&. +.TP +\fBl\fP +By number of links\&. +.TP +\fBa\fP +By time of last access, youngest first\&. +.TP +\fBm\fP +By time of last modification, youngest first\&. +.TP +\fBc\fP +By time of last inode change, youngest first\&. +.TP +\fBd\fP +By directories: files in subdirectories appear before those in the current directory at each level of the search \-\- this is best combined with other criteria, for example `\fBodon\fP\&' to sort on names for -files within the same directory; if \fBN\fP, no sorting is performed\&. -Note that \fBa\fP, \fBm\fP, and \fBc\fP compare -the age against the current time, hence the first name in the list is the -youngest file\&. Also note that the modifiers \fB^\fP and \fB\-\fP are used, +files within the same directory\&. +.TP +\fBN\fP +No sorting is performed\&. +.TP +.PD 0 +\fBe\fP\fIstring\fP +.TP +\fB+\fP\fIcmd\fP +Sort by shell code (see below)\&. +.PD +.PP +Note that the modifiers \fB^\fP and \fB\-\fP are used, so `\fB*(^\-oL)\fP\&' gives a list of all files sorted by file size in descending order, following any symbolic links\&. Unless \fBoN\fP is used, multiple order specifiers may occur to resolve ties\&. -.RS .PP The default sorting is \fBn\fP (by name) unless the \fBY\fP glob qualifier is used, in which case it is \fBN\fP (unsorted)\&. @@ -3041,9 +3117,10 @@ repeated, but note that the maximum number of sort operators of any kind that may appear in any glob expression is 12\&. .RE .TP +.PD \fBO\fP\fIc\fP -like `\fBo\fP\&', but sorts in descending order; i\&.e\&. `\fB*(^oc)\fP' is the -same as `\fB*(Oc)\fP\&' and `\fB*(^Oc)\fP' is the same as `\fB*(oc)\fP'; `\fBOd\fP' +like `\fBo\fP\&', but sorts in descending order; i\&.e\&. `\fB*(^o\fP\fIc\fP\fB)\fP' is the +same as `\fB*(O\fP\fIc\fP\fB)\fP\&' and `\fB*(^O\fP\fIc\fP\fB)\fP' is the same as `\fB*(o\fP\fIc\fP\fB)\fP'; `\fBOd\fP' puts files in the current directory before those in subdirectories at each level of the search\&. .TP @@ -3051,7 +3128,7 @@ level of the search\&. specifies which of the matched filenames should be included in the returned list\&. The syntax is the same as for array subscripts\&. \fIbeg\fP and the optional \fIend\fP may be mathematical -expressions\&. As in parameter subscripting they may be negative to make +expressions\&. As in parameter subscripting they may be negative to make them count from the last match backward\&. E\&.g\&.: `\fB*(\-OL[1,3])\fP\&' gives a list of the names of the three largest files\&. .TP diff --git a/Doc/zshmisc.1 b/Doc/zshmisc.1 index d0d1a21d9..e5396d1d8 100644 --- a/Doc/zshmisc.1 +++ b/Doc/zshmisc.1 @@ -1,4 +1,4 @@ -.TH "ZSHMISC" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHMISC" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zshmisc \- everything and then some .\" Yodl file: Zsh/grammar.yo @@ -256,7 +256,9 @@ for each selection until a break or end\-of\-file is encountered\&. .TP \fB(\fP \fIlist\fP \fB)\fP Execute \fIlist\fP in a subshell\&. Traps set by the \fBtrap\fP builtin -are reset to their default values while executing \fIlist\fP\&. +are reset to their default values while executing \fIlist\fP; an +exception is that ignored signals will continue to be ignored +if the option \fBPOSIXTRAPS\fP is set\&. .TP \fB{\fP \fIlist\fP \fB}\fP Execute \fIlist\fP\&. @@ -326,7 +328,7 @@ execution of \fIalways\-list\fP, just like \fBbreak\fP and \fBcontinue\fP\&. .RE .TP .PD 0 -\fBfunction\fP \fIword\fP \&.\&.\&. [ \fB()\fP ] [ \fIterm\fP ] \fB{\fP \fIlist\fP \fB}\fP +\fBfunction\fP [ \fB\-T\fP ] \fIword\fP \&.\&.\&. [ \fB()\fP ] [ \fIterm\fP ] \fB{\fP \fIlist\fP \fB}\fP .TP .PD 0 \fIword\fP \&.\&.\&. \fB()\fP [ \fIterm\fP ] \fB{\fP \fIlist\fP \fB}\fP @@ -341,6 +343,16 @@ The body of the function is the \fIlist\fP between the \fB{\fP and \fB}\fP\&. See the section `Functions\&'\&. .RS .PP +The options of \fBfunction\fP have the following meanings: +.PP +.PD 0 +.TP +.PD +\-T +Enable tracing for this function, as though with \fBfunctions \-T\fP\&. See the +documentation of the \fB\-f\fP option to the \fBtypeset\fP builtin, in +\fIzshbuiltins\fP(1)\&. +.PP If the option \fBSH_GLOB\fP is set for compatibility with other shells, then whitespace may appear between the left and right parentheses when there is a single \fIword\fP; otherwise, the parentheses will be treated as @@ -387,6 +399,8 @@ else the end of the test will not be recognized\&. For the \fBfor\fP, \fBrepeat\fP, \fBcase\fP and \fBselect\fP commands no such special form for the arguments is necessary, but the other condition (the special form of \fIsublist\fP or use of the \fBSHORT_LOOPS\fP option) still applies\&. +The \fBSHORT_REPEAT\fP option is available to enable the short version only +for the \fBrepeat\fP command\&. .PP .PD 0 .TP @@ -572,6 +586,11 @@ position (if it could be the first word of a simple command), or if the alias is global\&. If the replacement text ends with a space, the next word in the shell input is always eligible for purposes of alias expansion\&. +.PP +It is an error for the function name, \fIword\fP, in the sh\-compatible function +definition syntax `\fIword\fP \fB()\fP \&.\&.\&.\&' to be a word that resulted +from alias expansion, unless the \fBALIAS_FUNC_DEF\fP option is set\&. +.PP An alias is defined using the \fBalias\fP builtin; global aliases may be defined using the \fB\-g\fP option to that builtin\&. .PP @@ -608,6 +627,19 @@ word, e\&.g\&. \fB\efoo\fP\&. Any form of quoting works, although there is nothing to prevent an alias being defined for the quoted form such as \fB\efoo\fP as well\&. .PP +In particular, note that quoting must be used when using \fBunalias\fP to remove +global aliases: +.PP +.RS +.nf +\fB% alias \-g foo=bar +% unalias foo +unalias: no such hash table element: bar +% unalias \efoo +% \fP +.fi +.RE +.PP When \fBPOSIX_ALIASES\fP is set, only plain unquoted strings are eligible for aliasing\&. The \fBalias\fP builtin does not reject ineligible aliases, but they are not expanded\&. @@ -661,34 +693,6 @@ a problem in shell scripts, functions, and code executed with `\fBsource\fP\&' or `\fB\&.\fP\&'\&. Consequently, use of functions rather than aliases is recommended in non\-interactive code\&. .PP -Note also the unhelpful interaction of aliases and function definitions: -.PP -.RS -.nf -\fBalias func=\&'noglob func' -func() { - echo Do something with $* -}\fP -.fi -.RE -.PP -Because aliases are expanded in function definitions, this causes the -following command to be executed: -.PP -.RS -.nf -\fBnoglob func() { - echo Do something with $* -}\fP -.fi -.RE -.PP -which defines \fBnoglob\fP as well as \fBfunc\fP as functions with the -body given\&. To avoid this, either quote the name \fBfunc\fP or use the -alternative function definition form `\fBfunction func\fP\&'\&. Ensuring the -alias is defined after the function works but is problematic if the -code fragment might be re\-executed\&. -.PP .SH "QUOTING" A character may be \fIquoted\fP (that is, made to stand for itself) by preceding it with a `\fB\e\fP\&'\&. @@ -810,7 +814,8 @@ tabs are stripped from \fIword\fP and from the document\&. Perform shell expansion on \fIword\fP and pass the result to standard input\&. This is known as a \fIhere\-string\fP\&. Compare the use of \fIword\fP in here\-documents above, where \fIword\fP -does not undergo shell expansion\&. +does not undergo shell expansion\&. The result will have a trailing newline +after it\&. .TP .PD 0 \fB<&\fP \fInumber\fP @@ -1169,9 +1174,24 @@ is invoked as described in the section `Functions\&'\&. If there exists a shell builtin by that name, the builtin is invoked\&. .PP Otherwise, the shell searches each element of \fB$path\fP for a -directory containing an executable file by that name\&. If the -search is unsuccessful, the shell prints an error message and returns -a nonzero exit status\&. +directory containing an executable file by that name\&. +.PP +If execution fails: an error message is printed, and one of the +following values is returned\&. +.PP +.PD 0 +.TP +127 +The search was unsuccessful\&. The error message is +`\fBcommand not found:\fP \fIcmd\fP\&'\&. +.TP +126 +The executable file has insufficient permissions, is a +directory or special file, or is not a script and is in a format +unrecognized by the operating system\&. The exact conditions and error +message are operating system\-dependent; see +\fIexecve\fP(2)\&. +.PD .PP If execution fails because the file is not in executable format, and the file is not a directory, it is assumed to be a shell @@ -1184,13 +1204,9 @@ not handle this executable format in the kernel\&. If no external command is found but a function \fBcommand_not_found_handler\fP exists the shell executes this function with all command line arguments\&. The return status of the function becomes the -status of the command\&. If the function wishes to mimic the -behaviour of the shell when the command is not found, it should -print the message `\fBcommand not found:\fP \fIcmd\fP\&' to standard error -and return status 127\&. Note that the handler is executed in a +status of the command\&. Note that the handler is executed in a subshell forked to execute an external command, hence changes to directories, shell parameters, etc\&. have no effect on the main shell\&. -.PP .\" Yodl file: Zsh/func.yo .SH "FUNCTIONS" Shell functions are defined with the \fBfunction\fP reserved word or the @@ -1415,13 +1431,14 @@ Certain functions, if defined, have special meaning to the shell\&. For the functions below, it is possible to define an array that has the same name as the function with `\fB_functions\fP\&' 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 +in the same context and with the same arguments and same initial value of \fB$?\fP +as the basic function\&. For example, if \fB$chpwd_functions\fP is an array containing the values `\fBmychpwd\fP\&', `\fBchpwd_save_dirstack\fP', then the shell attempts to execute the functions `\fBchpwd\fP\&', `\fBmychpwd\fP' and `\fBchpwd_save_dirstack\fP\&', 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 +elsewhere as a \fIhook function\fP\&. An error in any function causes subsequent functions not to be run\&. Note further that an error in a \fBprecmd\fP hook causes an immediately following \fBperiodic\fP function not to run (though it may run at the next opportunity)\&. @@ -1475,7 +1492,7 @@ the history file\&. In case of a conflict, the first non\-zero status value is taken\&. .PP A hook function may call `\fBfc \-p\fP \fI\&.\&.\&.\fP\&' to switch the history -context so that the history is saved in a different file from the +context so that the history is saved in a different file from that in the global \fBHISTFILE\fP parameter\&. This is handled specially: the history context is automatically restored after the processing of the history line is finished\&. @@ -1723,7 +1740,7 @@ jobs will be terminated, and the running jobs will be sent a \fBSIGHUP\fP signal, if the \fBHUP\fP option is set\&. .PP To avoid having the shell terminate the running jobs, either -use the \fBnohup\fP command (see \fInohup\fP(1)) +use the \fInohup\fP(1) command or the \fBdisown\fP builtin\&. .SH "SIGNALS" The \fBINT\fP and \fBQUIT\fP signals for an invoked @@ -1759,7 +1776,7 @@ The \fBlet\fP builtin command takes arithmetic expressions as arguments; each is evaluated separately\&. Since many of the arithmetic operators, as well as spaces, require quoting, an alternative form is provided: for any command which begins with a `\fB((\fP\&', all the characters until a -matching `\fB))\fP\&' are treated as a quoted expression and +matching `\fB))\fP\&' are treated as a double\-quoted expression and arithmetic expansion performed as for an argument of \fBlet\fP\&. More precisely, `\fB((\fP\fI\&.\&.\&.\fP\fB))\fP\&' is equivalent to `\fBlet "\fP\fI\&.\&.\&.\fP\fB"\fP\&'\&. The return status is 0 if the arithmetic value diff --git a/Doc/zshmodules.1 b/Doc/zshmodules.1 index e6d696fb7..dd3bb4c39 100644 --- a/Doc/zshmodules.1 +++ b/Doc/zshmodules.1 @@ -1,4 +1,4 @@ -.TH "ZSHMODULES" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHMODULES" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zshmodules \- zsh loadable modules .\" Yodl file: Zsh/modules.yo @@ -105,6 +105,9 @@ Interface to the termcap database\&. \fBzsh/terminfo\fP Interface to the terminfo database\&. .TP +\fBzsh/watch\fP +Reporting of login and logout events\&. +.TP \fBzsh/zftp\fP A builtin FTP client\&. .TP @@ -972,7 +975,7 @@ input\&. This is only available with the ncurses library; mouse handling can be detected by checking for the exit status of `\fBzcurses mouse\fP\&' with no arguments\&. If a mouse button is clicked (or double\- or triple\-clicked, or pressed or released with -a configurable delay from being clicked) then \fBkparam\fP is set to the string +a configurable delay from being clicked) then \fIkparam\fP is set to the string \fBMOUSE\fP, and \fImparam\fP is set to an array consisting of the following elements: .PD 0 @@ -1100,10 +1103,10 @@ The \fBzsh/datetime\fP module makes available one builtin command: .PD 0 .TP .PD 0 -\fBstrftime\fP [ \fB\-s\fP \fIscalar\fP ] \fIformat\fP [ \fIepochtime\fP [ \fInanoseconds\fP ] ] +\fBstrftime\fP [ \fB\-s\fP \fIscalar\fP | \fB\-n\fP ] \fIformat\fP [ \fIepochtime\fP [ \fInanoseconds\fP ] ] .TP .PD -\fBstrftime\fP \fB\-r\fP [ \fB\-q\fP ] [ \fB\-s\fP \fIscalar\fP ] \fIformat\fP \fItimestring\fP +\fBstrftime\fP \fB\-r\fP [ \fB\-q\fP ] [ \fB\-s\fP \fIscalar\fP | \fB\-n\fP ] \fIformat\fP \fItimestring\fP Output the date in the \fIformat\fP specified\&. With no \fIepochtime\fP, the current system date/time is used; optionally, \fIepochtime\fP may be used to specify the number of seconds since the epoch, and \fInanoseconds\fP may @@ -1116,6 +1119,9 @@ the section EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1) are also available .PD 0 .TP .PD +\fB\-n\fP +Suppress printing a newline after the formatted string\&. +.TP \fB\-q\fP Run quietly; suppress printing of all error messages described below\&. Errors for invalid \fIepochtime\fP values are always printed\&. @@ -1541,7 +1547,7 @@ value is the content of the file\&. The value is treated identically to any other text coming from a parameter\&. The value may also be assigned to, in which case the file in question is written (whether or not it originally existed); or an element may be unset, which will delete the file in -question\&. For example, `\fBvared mapfile[myfile]\fP\&' works as expected, +question\&. For example, `\fBvared \&'mapfile[myfile]'\fP' works as expected, editing the file `\fBmyfile\fP\&'\&. .RS .PP @@ -1767,7 +1773,7 @@ The script supplied with the module invokes the shell function even if the \fBzsh/newuser\fP module is disabled\&. Note, however, that if the module is not installed the function will not be installed either\&. The function is documented in -the section User Configuration Functions in \fIzshcontrib\fP(1)\&. +the section `User Configuration Functions\&' in \fIzshcontrib\fP(1)\&. .SH "THE ZSH/PARAMETER MODULE" .\" Yodl file: Zsh/mod_parameter.yo @@ -1912,6 +1918,8 @@ The keys of the associative arrays are usually valid job numbers, and these are the values output with, for example, \fB${(k)jobdirs}\fP\&. Non\-numeric job references may be used when looking up a value; for example, \fB${jobdirs[%+]}\fP refers to the current job\&. +.PP +See the \fBjobs\fP builtin for how job information is provided in a subshell\&. .RE .TP \fBjobtexts\fP @@ -1921,6 +1929,8 @@ that were used to start the jobs\&. .PP Handling of the keys of the associative array is as described for \fBjobdirs\fP above\&. +.PP +See the \fBjobs\fP builtin for how job information is provided in a subshell\&. .RE .TP \fBjobstates\fP @@ -1938,6 +1948,8 @@ the \fIstate\fP describes the state of that process\&. .PP Handling of the keys of the associative array is as described for \fBjobdirs\fP above\&. +.PP +See the \fBjobs\fP builtin for how job information is provided in a subshell\&. .RE .TP \fBnameddirs\fP @@ -2113,12 +2125,16 @@ This module provides a single autoloaded builtin: .PD 0 .TP .PD -\fBprivate\fP [ {\fB+\fP|\fB\-\fP}\fBAHUahlprtux\fP ] [ {\fB+\fP|\fB\-\fP}\fBEFLRZi\fP [ \fIn\fP ] ] [ \fIname\fP[\fB=\fP\fIvalue\fP] \&.\&.\&. ] +\fBprivate\fP [ {\fB+\fP|\fB\-\fP}\fBAHUahlmrtux\fP ] [ {\fB+\fP|\fB\-\fP}\fBEFLRZi\fP [ \fIn\fP ] ] [ \fIname\fP[\fB=\fP\fIvalue\fP] \&.\&.\&. ] The \fBprivate\fP builtin accepts all the same options and arguments as \fBlocal\fP (\fIzshbuiltins\fP(1)) except for the `\fB\-\fP\fBT\fP\&' option\&. Tied parameters may not be made private\&. .RS .PP +The `\fB\-\fP\fBp\fP\&' option is presently a no\-op because the state of +private parameters cannot reliably be reloaded\&. This also applies +to printing private parameters with `\fBtypeset \-p\fP\&'\&. +.PP If used at the top level (outside a function scope), \fBprivate\fP creates a normal parameter in the same manner as \fBdeclare\fP or \fBtypeset\fP\&. A warning about this is printed if \fBWARN_CREATE_GLOBAL\fP is set @@ -2196,7 +2212,8 @@ Within any other function called by the declaring function, the private parameter does \fINOT\fP hide other parameters of the same name, so for example a global parameter of the same name is visible and may be assigned or unset\&. This includes calls to anonymous functions, although -that may also change in the future\&. +that may also change in the future\&. However, the private name may not be +created outside the local scope when it was not previously declared\&. .TP \(bu An exported private remains in the environment of inner scopes but @@ -2241,6 +2258,18 @@ automatically load this module as needed and will invoke the .PP If \fBBASH_REMATCH\fP is set, then the array \fBBASH_REMATCH\fP will be set instead of \fBMATCH\fP and \fBmatch\fP\&. +.PP +Note that the \fBzsh/regex\fP module logic relies on the host system\&. The +same \fIexpr\fP and \fIregex\fP pair could produce different results on different +platforms if a \fIregex\fP with non\-standard syntax is given\&. +.PP +For example, no syntax for matching a word boundary is defined in the POSIX +extended regular expression standard\&. GNU \fBlibc\fP and BSD \fBlibc\fP both provide +such syntaxes as extensions (\fB\eb\fP and \fB[[:<:]]\fP/\fB[[:>:]]\fP respectively), +but neither of these syntaxes is supported by both of these implementations\&. +.PP +Refer to the \fIregcomp\fP(3) and \fIre_format\fP(7) manual pages on your +system for locally\-supported syntax\&. .RE .SH "THE ZSH/SCHED MODULE" .\" Yodl file: Zsh/mod_sched.yo @@ -2520,6 +2549,8 @@ Supplies a \fBstrftime\fP (see \fIstrftime\fP(3)) string for the formatting of the time elements\&. The format string supports all of the zsh extensions described in the section EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1)\&. +In particular, \fB\-F %s\&.%N\fP can be used to show timestamps with nanosecond +precision if supported by the system\&. The \fB\-s\fP option is implied\&. .TP \fB\-g\fP @@ -2647,6 +2678,9 @@ suppress updating of the file atime \fBnofollow\fP fail if \fIfile\fP is a symbolic link .TP +\fBnonblock\fP +the file is opened in nonblocking mode +.TP \fBsync\fP request that writes wait until data has been physically written .TP @@ -2764,7 +2798,7 @@ the error that occurred\&. .RE .TP .PD 0 -\fBzsystem flock\fP [ \fB\-t\fP \fItimeout\fP ] [ \fB\-f\fP \fIvar\fP ] [\fB\-er\fP] \fIfile\fP +\fBzsystem flock\fP [ \fB\-t\fP \fItimeout\fP ] [ \fB\-i\fP \fIinterval\fP ] [ \fB\-f\fP \fIvar\fP ] [\fB\-er\fP] \fIfile\fP .TP .PD \fBzsystem flock \-u\fP \fIfd_expr\fP @@ -2797,9 +2831,16 @@ a safety check that the file descriptor is in use for file locking\&. .PP By default the shell waits indefinitely for the lock to succeed\&. The option \fB\-t\fP \fItimeout\fP specifies a timeout for the lock in -seconds; currently this must be an integer\&. The shell will attempt -to lock the file once a second during this period\&. If the attempt -times out, status 2 is returned\&. +seconds; fractional seconds are allowed\&. During this period, the +shell will attempt to lock the file every \fIinterval\fP seconds +if the \fB\-i\fP \fIinterval\fP option is given, otherwise once a second\&. +(This \fIinterval\fP is shortened before the last attempt if needed, +so that the shell waits only until the \fItimeout\fP and not longer\&.) +If the attempt times out, status 2 is returned\&. +.PP +(Note: \fItimeout\fP is limited to 2^30\-1 seconds (about 34 years), and +\fIinterval\fP to 0\&.999 * LONG_MAX microseconds (only about 35 minutes +on 32\-bit systems)\&.) .PP If the option \fB\-e\fP is given, the file descriptor for the lock is preserved when the shell uses \fBexec\fP to start a new process; @@ -2859,9 +2900,9 @@ Returns the process ID of the current process, even in subshells\&. Compare \fB$$\fP, which returns the process ID of the main shell process\&. .TP \fBppid\fP -Returns the process ID of the parent of the current process, even in -subshells\&. Compare \fB$PPID\fP, which returns the process ID of the parent -of the main shell process\&. +Returns the current process ID of the parent of the current process, even +in subshells\&. Compare \fB$PPID\fP, which returns the process ID of the +initial parent of the main shell process\&. .TP \fBprocsubstpid\fP Returns the process ID of the last process started for process @@ -3110,6 +3151,158 @@ The \fBzsh/terminfo\fP module makes available one parameter: \fBterminfo\fP An associative array that maps terminfo capability names to their values\&. +.SH "THE ZSH/WATCH MODULE" +.\" Yodl file: Zsh/mod_watch.yo + +The \fBzsh/watch\fP module can be used to report when specific users log in or +out\&. This is controlled via the following parameters\&. +.PP +.PD 0 +.TP +.PD +\fBLOGCHECK\fP +The interval in seconds between checks for login/logout activity +using the \fBwatch\fP parameter\&. +.TP +\fBwatch\fP <S> <Z> (\fBWATCH\fP <S>) +An array (colon\-separated list) of login/logout events to report\&. +.RS +.PP +If it contains the single word `\fBall\fP\&', then all login/logout events +are reported\&. If it contains the single word `\fBnotme\fP\&', then all +events are reported as with `\fBall\fP\&' except \fB$USERNAME\fP\&. +.PP +An entry in this list may consist of a username, +an `\fB@\fP\&' followed by a remote hostname, +and a `\fB%\fP\&' followed by a line (tty)\&. Any of these may +be a pattern (be sure to quote this during the assignment to +\fBwatch\fP so that it does not immediately perform file generation); +the setting of the \fBEXTENDED_GLOB\fP option is respected\&. +Any or all of these components may be present in an entry; +if a login/logout event matches all of them, +it is reported\&. +.PP +For example, with the \fBEXTENDED_GLOB\fP option set, the following: +.PP +.RS +.nf +\fBwatch=(\&'^(pws|barts)')\fP +.fi +.RE +.PP +causes reports for activity associated with any user other than \fBpws\fP +or \fBbarts\fP\&. +.RE +.TP +\fBWATCHFMT\fP +The format of login/logout reports if the \fBwatch\fP parameter is set\&. +Default is `\fB%n has %a %l from %m\fP\&'\&. +Recognizes the following escape sequences: +.RS +.PP +.PD 0 +.TP +.PD +\fB%n\fP +The name of the user that logged in/out\&. +.TP +\fB%a\fP +The observed action, i\&.e\&. "logged on" or "logged off"\&. +.TP +\fB%l\fP +The line (tty) the user is logged in on\&. +.TP +\fB%M\fP +The full hostname of the remote host\&. +.TP +\fB%m\fP +The hostname up to the first `\fB\&.\fP\&'\&. If only the +IP address is available or the utmp field contains +the name of an X\-windows display, the whole name is printed\&. +.RS +.PP +\fINOTE:\fP +The `\fB%m\fP\&' and `\fB%M\fP' escapes will work only if there is a host name +field in the utmp on your machine\&. Otherwise they are +treated as ordinary strings\&. +.RE +.TP +\fB%F{\fP\fIcolor\fP\fB}\fP (\fB%f\fP) +Start (stop) using a different foreground color\&. +.TP +\fB%K{\fP\fIcolor\fP\fB}\fP (\fB%k\fP) +Start (stop) using a different background color\&. +.TP +\fB%S\fP (\fB%s\fP) +Start (stop) standout mode\&. +.TP +\fB%U\fP (\fB%u\fP) +Start (stop) underline mode\&. +.TP +\fB%B\fP (\fB%b\fP) +Start (stop) boldface mode\&. +.TP +.PD 0 +\fB%t\fP +.TP +.PD +\fB%@\fP +The time, in 12\-hour, am/pm format\&. +.TP +\fB%T\fP +The time, in 24\-hour format\&. +.TP +\fB%w\fP +The date in `\fIday\fP\fB\-\fP\fIdd\fP\&' format\&. +.TP +\fB%W\fP +The date in `\fImm\fP\fB/\fP\fIdd\fP\fB/\fP\fIyy\fP\&' format\&. +.TP +\fB%D\fP +The date in `\fIyy\fP\fB\-\fP\fImm\fP\fB\-\fP\fIdd\fP\&' format\&. +.TP +\fB%D{\fP\fIstring\fP\fB}\fP +The date formatted as \fIstring\fP using the \fBstrftime\fP function, with +zsh extensions as described by +EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1)\&. +.TP +\fB%(\fP\fIx\fP\fB:\fP\fItrue\-text\fP\fB:\fP\fIfalse\-text\fP\fB)\fP +Specifies a ternary expression\&. +The character following the \fIx\fP is +arbitrary; the same character is used to separate the text +for the "true" result from that for the "false" result\&. +Both the separator and the right parenthesis may be escaped +with a backslash\&. +Ternary expressions may be nested\&. +.RS +.PP +The test character \fIx\fP may be any one of `\fBl\fP\&', `\fBn\fP', `\fBm\fP' +or `\fBM\fP\&', which indicate a `true' result if the corresponding +escape sequence would return a non\-empty value; or it may be `\fBa\fP\&', +which indicates a `true\&' result if the watched user has logged in, +or `false\&' if he has logged out\&. +Other characters evaluate to neither true nor false; the entire +expression is omitted in this case\&. +.PP +If the result is `true\&', then the \fItrue\-text\fP +is formatted according to the rules above and printed, +and the \fIfalse\-text\fP is skipped\&. +If `false\&', the \fItrue\-text\fP is skipped and the \fIfalse\-text\fP +is formatted and printed\&. +Either or both of the branches may be empty, but +both separators must be present in any case\&. +.RE +.RE +.PP +Furthermore, the \fBzsh/watch\fP module makes available one builtin +command: +.PP +.PD 0 +.TP +.PD +\fBlog\fP +List all users currently logged in who are affected by +the current setting of the \fBwatch\fP parameter\&. .SH "THE ZSH/ZFTP MODULE" .\" Yodl file: Zsh/mod_zftp.yo @@ -3827,7 +4020,7 @@ The \fBzselect\fP builtin is a front\-end to the `select\&' system call, which blocks until a file descriptor is ready for reading or writing, or has an error condition, with an optional timeout\&. If this is not available on your system, the command prints an error message and returns status 2 -(normal errors return status 1)\&. For more information, see your systems +(normal errors return status 1)\&. For more information, see your system\&'s documentation for \fIselect\fP(3)\&. Note there is no connection with the shell builtin of the same name\&. .RS @@ -3931,27 +4124,32 @@ the pattern that was defined first\&. .PP \fIExample\fP .PP -For example, to define your preferred form of precipitation depending on which -city you\&'re in, you might set the following in your \fBzshrc\fP: +For example, a fictional `\fBweather\fP\&' plugin might state in its documentation +that it looks up the \fBpreferred\-precipitation\fP style under the +`\fB:weather:\fP\fIcontinent\fP\fB:\fP\fIday\-of\-the\-week\fP\fB:\fP\fIphase\-of\-the\-moon\fP\&' context\&. +According to this, you might set the following in your \fBzshrc\fP: .PP .RS .nf \fBzstyle \&':weather:europe:*' preferred\-precipitation rain -zstyle \&':weather:europe:germany:* preferred\-precipitation none -zstyle \&':weather:europe:germany:*:munich' preferred\-precipitation snow\fP +zstyle \&':weather:*:Sunday:*' preferred\-precipitation snow\fP .fi .RE .PP -Then, the fictional `\fBweather\fP\&' plugin might run under the hood a command -such as +Then the plugin would run under the hood a command such as .PP .RS .nf -\fBzstyle \-s ":weather:${continent}:${country}:${county}:${city}" preferred\-precipitation REPLY\fP +\fBzstyle \-s ":weather:${continent}:${day_of_week}:${moon_phase}" preferred\-precipitation REPLY\fP .fi .RE .PP in order to retrieve your preference into the scalar variable \fB$REPLY\fP\&. +On Sundays \fB$REPLY\fP would be set to `\fBsnow\fP\&'; in Europe it would be set +to `\fBrain\fP\&'; and on Sundays in Europe it would be set to `\fBsnow\fP' again, +because the patterns `\fB:weather:europe:*\fP\&' and `\fB:weather:*:Sunday:*\fP' both +match the \fIcontext\fP argument to \fBzstyle \-s\fP, are equally specific, and the +latter is more specific (because it has more colon\-separated components)\&. .PP \fIUsage\fP .PP @@ -4063,9 +4261,12 @@ Match a value\&. Returns status zero if the .PD 0 \fBzformat \-f\fP \fIparam\fP \fIformat\fP \fIspec\fP \&.\&.\&. .TP +.PD 0 +\fBzformat \-F\fP \fIparam\fP \fIformat\fP \fIspec\fP \&.\&.\&. +.TP .PD \fBzformat \-a\fP \fIarray\fP \fIsep\fP \fIspec\fP \&.\&.\&. -This builtin provides two different forms of formatting\&. The first form +This builtin provides different forms of formatting\&. The first form is selected with the \fB\-f\fP option\&. In this case the \fIformat\fP string will be modified by replacing sequences starting with a percent sign in it with strings from the \fIspec\fPs\&. Each \fIspec\fP should be @@ -4114,7 +4315,13 @@ outputs "The answer is \&'yes'\&." to \fBREPLY\fP since the value for the format specifier \fBc\fP is 3, agreeing with the digit argument to the ternary expression\&. .PP -The second form, using the \fB\-a\fP option, can be used for aligning +With \fB\-F\fP instead of \fB\-f\fP, ternary expressions choose between the +`true\&' or `false' text on the basis of whether the format specifier is +present and non\-empty\&. A test number indicates a minimum width for the +value given in the format specifier\&. Negative numbers reverse this, +so the test is for whether the value exceeds a maximum width\&. +.PP +The form, using the \fB\-a\fP option, can be used for aligning strings\&. Here, the \fIspec\fPs are of the form `\fIleft\fP\fB:\fP\fIright\fP\&' where `\fIleft\fP' and `\fIright\fP' are arbitrary strings\&. These strings are modified by replacing the colons diff --git a/Doc/zshoptions.1 b/Doc/zshoptions.1 index fd10e8d29..c85c877ee 100644 --- a/Doc/zshoptions.1 +++ b/Doc/zshoptions.1 @@ -1,4 +1,4 @@ -.TH "ZSHOPTIONS" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHOPTIONS" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zshoptions \- zsh options .\" Yodl file: Zsh/options.yo @@ -34,6 +34,9 @@ will be treated just as `\fB\-f\fP\&', but the string `\fB\-f i\fP' is an error\ This is because many systems which implement the `\fB#!\fP\&' mechanism for calling scripts do not strip trailing whitespace\&. .PP +It is possible for options to be set within a function scope\&. See the +description of the option \fBLOCAL_OPTIONS\fP below\&. +.PP .SH "DESCRIPTION OF OPTIONS" In the following list, options set by default in all emulations are marked <D>; those set by default only in csh, ksh, sh, or zsh emulations are marked @@ -289,6 +292,19 @@ can match the directory \fBCVS\fP owing to the presence of the globbing flag Make regular expressions using the \fBzsh/regex\fP module (including matches with \fB=~\fP) sensitive to case\&. .TP +\fBCASE_PATHS\fP +If \fBCASE_PATHS\fP is not set (the default), \fBCASE_GLOB\fP affects the +interpretation of \fIevery\fP path component, whenever a special +character appears in \fIany\fP component\&. When \fBCASE_PATHS\fP is set, +file path components that do \fInot\fP contain special filename +generation characters are always sensitive to case, thus restricting +\fBNO_CASE_GLOB\fP to components that contain globbing characters\&. +.RS +.PP +Note that if the filesystem itself is not sensitive to case, then +\fBCASE_PATHS\fP has no effect\&. +.RE +.TP \fBCSH_NULL_GLOB\fP <C> If a pattern for filename generation has no matches, delete the pattern from the argument list; @@ -351,7 +367,7 @@ Substitutions using the \fB:s\fP and \fB:&\fP history modifiers are performed with pattern matching instead of string matching\&. This occurs wherever history modifiers are valid, including glob qualifiers and parameters\&. See -the section Modifiers in \fIzshexpn\fP(1)\&. +the section `Modifiers\&' in \fIzshexpn\fP(1)\&. .TP \fBIGNORE_BRACES\fP (\fB\-I\fP) <S> Do not perform brace expansion\&. For historical reasons this @@ -724,7 +740,7 @@ effect extends beyond the scope of the enclosing function; this is the most portable way to achieve this behaviour\&. .RE .TP -\fBGLOBAL_RCS\fP (\fB\-d\fP) <D> +\fBGLOBAL_RCS\fP (\fB+d\fP) <D> If this option is unset, the startup files \fB/etc/zprofile\fP, \fB/etc/zshrc\fP, \fB/etc/zlogin\fP and \fB/etc/zlogout\fP will not be run\&. It can be disabled and re\-enabled at any time, including inside local startup @@ -757,6 +773,18 @@ not set, `\fB>>!\fP\&' or `\fB>>|\fP' must be used to create a file\&. If either option is set, `\fB>>\fP\&' may be used\&. .RE .TP +\fBCLOBBER_EMPTY\fP +This option is only used if the option \fBCLOBBER\fP is not set: note that +it is set by default\&. +.RS +.PP +If this option is set, then regular files of zero length may be +ovewritten (`clobbered\&')\&. Note that it is possible another process +has written to the file between this test and use of the file by +the current process\&. This option should therefore not be used in +cases where files to be clobbered may be written to asynchronously\&. +.RE +.TP \fBCORRECT\fP (\fB\-0\fP) Try to correct the spelling of commands\&. Note that, when the \fBHASH_LIST_ALL\fP option is not set or when some @@ -881,6 +909,10 @@ avoided by expanding the `\fB*\fP\&' in ZLE (with tab)\&. Allow the short forms of \fBfor\fP, \fBrepeat\fP, \fBselect\fP, \fBif\fP, and \fBfunction\fP constructs\&. .TP +\fBSHORT_REPEAT\fP +Allow the short form \fBrepeat\fP as \fBSHORT_LOOPS\fP but without enabling +it for the other constructs\&. +.TP \fBSUN_KEYBOARD_HACK\fP (\fB\-L\fP) If a line ends with a backquote, and there are an odd number of backquotes on the line, ignore the trailing backquote\&. @@ -1247,6 +1279,12 @@ If the option is set, they will only be shown when parameters are selected with the `\fB\-m\fP\&' option\&. The option `\fB\-p\fP' is available whether or not the option is set\&. .TP +\fBTYPESET_TO_UNSET\fP <K> <S> +When declaring a new parameter with any of the `\fBtypeset\fP\&' family of +related commands, the parameter remains unset unless and until a +value is explicity assigned to it, either in the `\fBtypeset\fP\&' command +itself or as a later assignment statement\&. +.TP \fBVERBOSE\fP (\fB\-v\fP, ksh: \fB\-v\fP) Print shell input lines as they are read\&. .TP @@ -1463,7 +1501,8 @@ command found in the path\&. .PP Furthermore, the \fBgetopts\fP builtin behaves in a POSIX\-compatible fashion in that the associated variable \fBOPTIND\fP is not made -local to functions\&. +local to functions, and its value is calculated differently to match +other shells\&. .PP Moreover, the warning and special exit code from \fB[[ \-o \fP\fInon_existent_option\fP\fB ]]\fP are suppressed\&. @@ -1529,10 +1568,17 @@ When this option is set, the usual zsh behaviour of executing traps for \fBEXIT\fP on exit from shell functions is suppressed\&. In that case, manipulating \fBEXIT\fP traps always alters the global trap for exiting the shell; the \fBLOCAL_TRAPS\fP option is -ignored for the \fBEXIT\fP trap\&. Furthermore, a \fBreturn\fP statement -executed in a trap with no argument passes back from the function the -value from the surrounding context, not from code executed within the -trap\&. +ignored for the \fBEXIT\fP trap\&. +.RS +.PP +Also, a \fBreturn\fP statement executed in a trap with no argument passes +back from the function the value from the surrounding context, not from +code executed within the trap\&. +.PP +Furthermore, if a trap is set to be ignored, this state persists when +a subshell is entered\&. Without the option, the trap would be reset to +its default state at this point\&. +.RE .TP \fBSH_FILE_EXPANSION\fP <K> <S> Perform filename expansion (e\&.g\&., \fB~\fP expansion) \fIbefore\fP diff --git a/Doc/zshparam.1 b/Doc/zshparam.1 index 3ace5d3ab..8860fb8ac 100644 --- a/Doc/zshparam.1 +++ b/Doc/zshparam.1 @@ -1,4 +1,4 @@ -.TH "ZSHPARAM" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHPARAM" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zshparam \- zsh parameters .\" Yodl file: Zsh/params.yo @@ -97,7 +97,7 @@ may be in any order\&. Note that this syntax is strict: \fB[\fP and \fB]=\fP mu not be quoted, and \fIkey\fP may not consist of the unquoted string \fB]=\fP, but is otherwise treated as a simple string\&. The enhanced forms of subscript expression that may be used when directly subscripting a -variable name, described in the section Array Subscripts below, are not +variable name, described in the section `Array Subscripts\&' below, are not available\&. .PP The syntaxes with and without the explicit key may be mixed\&. An implicit @@ -459,12 +459,25 @@ is compared to the pattern, and the first matching key found is the result\&. On failure substitutes the length of the array plus one, as discussed under the description of `\fBr\fP\&', or the empty string for an associative array\&. +.RS +.PP +Note: Although `\fBi\fP\&' may be applied to a scalar substitution to find +the offset of a substring, the results are likely to be misleading when +searching within substitutions that yield an empty string, or when +searching for the empty substring\&. +.RE .TP \fBI\fP Like `\fBi\fP\&', but gives the index of the last match, or all possible matching keys in an associative array\&. On failure substitutes 0, or the empty string for an associative array\&. This flag is best when testing for values or keys that do not exist\&. +.RS +.PP +Note: If the option \fBKSH_ARRAYS\fP is in effect and no match is found, the +result is indistinguishable from the case when the first element of the array +matches\&. +.RE .TP \fBk\fP If used in a subscript on an associative array, this flag causes the keys @@ -690,6 +703,14 @@ In the parameter lists that follow, the mark `<S>\&' indicates that the parameter is special\&. `<Z>\&' indicates that the parameter does not exist when the shell initializes in \fBsh\fP or \fBksh\fP emulation mode\&. .PP +The parameters `\fB!\fP\&', `\fB#\fP', `\fB*\fP', `\fB\-\fP', `\fB?\fP', `\fB@\fP', +`\fB$\fP\&', `\fBARGC\fP', `\fBHISTCMD\fP', `\fBLINENO\fP', `\fBPPID\fP', +`\fBstatus\fP\&', `\fBTTYIDLE\fP', `\fBzsh_eval_context\fP', +`\fBZSH_EVAL_CONTEXT\fP\&', and `\fBZSH_SUBSHELL\fP' are read\-only and thus +cannot be restored by the user, so they are not output by +`\fBtypeset \-p\fP\&'\&. This also applies to many read\-only parameters loaded +from modules\&. +.PP The following parameters are automatically set by the shell: .PP .PD 0 @@ -710,10 +731,11 @@ the length of the parameter \fB\-\fP, q\&.v\&. Same as \fB#\fP\&. .TP \fB$\fP <S> -The process ID of this shell\&. Note that this indicates the original -shell started by invoking \fBzsh\fP; all processes forked from the shells -without executing a new program, such as subshells started by -\fB(\fP\fI\&.\&.\&.\fP\fB)\fP, substitute the same value\&. +The process ID of this shell, set when the shell initializes\&. Processes +forked from the shell without executing a new program, such as command +substitutions and commands grouped with \fB(\fP\fI\&.\&.\&.\fP\fB)\fP, +are subshells that duplicate the current shell, and thus substitute the +same value for \fB$$\fP as their parent shell\&. .TP \fB\-\fP <S> Flags supplied to the shell on invocation or by the \fBset\fP @@ -783,7 +805,7 @@ explicitly set locally\&. .RE .TP \fBERRNO\fP <S> -The value of errno (see \fIerrno\fP(3)) +The value of \fBerrno\fP (see \fIerrno\fP(3)) as set by the most recently failed system call\&. This value is system dependent and is intended for debugging purposes\&. It is also useful with the \fBzsh/system\fP module which @@ -854,9 +876,9 @@ command\&. The operating system, as determined at compile time\&. .TP \fBPPID\fP <S> -The process ID of the parent of the shell\&. As for \fB$$\fP, the -value indicates the parent of the original shell and does not -change in subshells\&. +The process ID of the parent of the shell, set when the shell initializes\&. +As with \fB$$\fP, the value does not change in subshells created as a +duplicate of the current shell\&. .TP \fBPWD\fP The present working directory\&. This is set when the shell initializes @@ -882,8 +904,9 @@ since the assignment\&. .RS .PP Unlike other special parameters, the type of the \fBSECONDS\fP parameter can -be changed using the \fBtypeset\fP command\&. Only integer and one of the -floating point types are allowed\&. For example, `\fBtypeset \-F SECONDS\fP\&' +be changed using the \fBtypeset\fP command\&. The type may be changed only +to one of the floating point types or back to integer\&. For example, +`\fBtypeset \-F SECONDS\fP\&' causes the value to be reported as a floating point number\&. The value is available to microsecond accuracy, although the shell may show more or fewer digits depending on the use of \fBtypeset\fP\&. See @@ -1325,10 +1348,6 @@ most as many lines as given by the absolute value\&. If set to zero, the shell asks only if the top of the listing would scroll off the screen\&. .TP -\fBLOGCHECK\fP -The interval in seconds between checks for login/logout activity -using the \fBwatch\fP parameter\&. -.TP \fBMAIL\fP If this parameter is set and \fBmailpath\fP is not set, the shell looks for mail in the specified file\&. @@ -1562,6 +1581,13 @@ if it is in the environment of the shell but not explicitly assigned to in the input line\&. This avoids running stty at every external command by accidentally exporting it\&. Also note that \fBSTTY\fP should not be used for window size specifications; these will not be local to the command\&. +.RS +.PP +If the parameter is set and empty, all of the above applies except +that \fBstty\fP is not run\&. This can be useful as a way to freeze the tty +around a single command, blocking its changes to tty settings, +similar to the \fBttyctl\fP builtin\&. +.RE .TP \fBTERM\fP <S> The type of terminal in use\&. This is used when looking up termcap @@ -1692,130 +1718,6 @@ to be interpreted as a file extension\&. The default is not to append any suffix, thus this parameter should be assigned only when needed and then unset again\&. .TP -\fBwatch\fP <S> <Z> (\fBWATCH\fP <S>) -An array (colon\-separated list) of login/logout events to report\&. -.RS -.PP -If it contains the single word `\fBall\fP\&', then all login/logout events -are reported\&. If it contains the single word `\fBnotme\fP\&', then all -events are reported as with `\fBall\fP\&' except \fB$USERNAME\fP\&. -.PP -An entry in this list may consist of a username, -an `\fB@\fP\&' followed by a remote hostname, -and a `\fB%\fP\&' followed by a line (tty)\&. Any of these may -be a pattern (be sure to quote this during the assignment to -\fBwatch\fP so that it does not immediately perform file generation); -the setting of the \fBEXTENDED_GLOB\fP option is respected\&. -Any or all of these components may be present in an entry; -if a login/logout event matches all of them, -it is reported\&. -.PP -For example, with the \fBEXTENDED_GLOB\fP option set, the following: -.PP -.RS -.nf -\fBwatch=(\&'^(pws|barts)')\fP -.fi -.RE -.PP -causes reports for activity associated with any user other than \fBpws\fP -or \fBbarts\fP\&. -.RE -.TP -\fBWATCHFMT\fP -The format of login/logout reports if the \fBwatch\fP parameter is set\&. -Default is `\fB%n has %a %l from %m\fP\&'\&. -Recognizes the following escape sequences: -.RS -.PP -.PD 0 -.TP -.PD -\fB%n\fP -The name of the user that logged in/out\&. -.TP -\fB%a\fP -The observed action, i\&.e\&. "logged on" or "logged off"\&. -.TP -\fB%l\fP -The line (tty) the user is logged in on\&. -.TP -\fB%M\fP -The full hostname of the remote host\&. -.TP -\fB%m\fP -The hostname up to the first `\fB\&.\fP\&'\&. If only the -IP address is available or the utmp field contains -the name of an X\-windows display, the whole name is printed\&. -.RS -.PP -\fINOTE:\fP -The `\fB%m\fP\&' and `\fB%M\fP' escapes will work only if there is a host name -field in the utmp on your machine\&. Otherwise they are -treated as ordinary strings\&. -.RE -.TP -\fB%S\fP (\fB%s\fP) -Start (stop) standout mode\&. -.TP -\fB%U\fP (\fB%u\fP) -Start (stop) underline mode\&. -.TP -\fB%B\fP (\fB%b\fP) -Start (stop) boldface mode\&. -.TP -.PD 0 -\fB%t\fP -.TP -.PD -\fB%@\fP -The time, in 12\-hour, am/pm format\&. -.TP -\fB%T\fP -The time, in 24\-hour format\&. -.TP -\fB%w\fP -The date in `\fIday\fP\fB\-\fP\fIdd\fP\&' format\&. -.TP -\fB%W\fP -The date in `\fImm\fP\fB/\fP\fIdd\fP\fB/\fP\fIyy\fP\&' format\&. -.TP -\fB%D\fP -The date in `\fIyy\fP\fB\-\fP\fImm\fP\fB\-\fP\fIdd\fP\&' format\&. -.TP -\fB%D{\fP\fIstring\fP\fB}\fP -The date formatted as \fIstring\fP using the \fBstrftime\fP function, with -zsh extensions as described by -EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1)\&. -.TP -\fB%(\fP\fIx\fP\fB:\fP\fItrue\-text\fP\fB:\fP\fIfalse\-text\fP\fB)\fP -Specifies a ternary expression\&. -The character following the \fIx\fP is -arbitrary; the same character is used to separate the text -for the "true" result from that for the "false" result\&. -Both the separator and the right parenthesis may be escaped -with a backslash\&. -Ternary expressions may be nested\&. -.RS -.PP -The test character \fIx\fP may be any one of `\fBl\fP\&', `\fBn\fP', `\fBm\fP' -or `\fBM\fP\&', which indicate a `true' result if the corresponding -escape sequence would return a non\-empty value; or it may be `\fBa\fP\&', -which indicates a `true\&' result if the watched user has logged in, -or `false\&' if he has logged out\&. -Other characters evaluate to neither true nor false; the entire -expression is omitted in this case\&. -.PP -If the result is `true\&', then the \fItrue\-text\fP -is formatted according to the rules above and printed, -and the \fIfalse\-text\fP is skipped\&. -If `false\&', the \fItrue\-text\fP is skipped and the \fIfalse\-text\fP -is formatted and printed\&. -Either or both of the branches may be empty, but -both separators must be present in any case\&. -.RE -.RE -.TP \fBWORDCHARS\fP <S> A list of non\-alphanumeric characters considered part of a word by the line editor\&. diff --git a/Doc/zshroadmap.1 b/Doc/zshroadmap.1 index b7b220d06..254c03bdd 100644 --- a/Doc/zshroadmap.1 +++ b/Doc/zshroadmap.1 @@ -1,4 +1,4 @@ -.TH "ZSHROADMAP" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHROADMAP" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zshroadmap \- informal introduction to the zsh manual .\" Yodl file: Zsh/roadmap.yo @@ -19,7 +19,7 @@ appear if your administrator has disabled the \fBzsh/newuser\fP module\&. The function is designed to be self\-explanatory\&. You can run it by hand with `\fBautoload \-Uz zsh\-newuser\-install; zsh\-newuser\-install \-f\fP\&'\&. See also -the section User Configuration Functions in \fIzshcontrib\fP(1)\&. +the section `User Configuration Functions\&' in \fIzshcontrib\fP(1)\&. .PP .SH "INTERACTIVE USE" .PP @@ -45,7 +45,7 @@ The shell now supports the UTF\-8 character set (and also others if supported by the operating system)\&. This is (mostly) handled transparently by the shell, but the degree of support in terminal emulators is variable\&. There is some discussion of this in the shell FAQ, -\fBhttp://www\&.zsh\&.org/FAQ/\fP\&. Note in particular that for combining +\fBhttps://www\&.zsh\&.org/FAQ/\fP\&. Note in particular that for combining characters to be handled the option \fBCOMBINING_CHARS\fP needs to be set\&. Because the shell is now more sensitive to the definition of the character set, note that if you are upgrading from an older version of diff --git a/Doc/zshtcpsys.1 b/Doc/zshtcpsys.1 index 62884fad0..21ef50ee9 100644 --- a/Doc/zshtcpsys.1 +++ b/Doc/zshtcpsys.1 @@ -1,4 +1,4 @@ -.TH "ZSHTCPSYS" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHTCPSYS" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zshtcpsys \- zsh tcp system .\" Yodl file: Zsh/tcpsys.yo diff --git a/Doc/zshzftpsys.1 b/Doc/zshzftpsys.1 index 7cb73b798..627d66564 100644 --- a/Doc/zshzftpsys.1 +++ b/Doc/zshzftpsys.1 @@ -1,4 +1,4 @@ -.TH "ZSHZFTPSYS" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHZFTPSYS" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zshzftpsys \- zftp function front\-end .\" Yodl file: Zsh/zftpsys.yo @@ -515,13 +515,11 @@ command `\fBzstyle \&':zftp:*'\fP \fIstyle\fP \fIvalue\fP \&.\&.\&.'\&. defines the \fIstyle\fP to have value \fIvalue\fP; more than one value may be given, although that is not useful in the cases described here\&. These values will then be used throughout the zftp function system\&. For more -precise control, the first argument, which gives a context in which the +precise control, the first argument, which gives a pattern that matches \fIcontexts\fP in which the style applies, can be modified to include a particular function, as for example `\fB:zftp:zfget\fP\&': the style will then have the given value only -in the \fBzfget\fP function\&. Values for the same style in different contexts -may be set; the most specific function will be used, where -strings are held to be more specific than patterns, and longer patterns and -shorter patterns\&. Note that only the top level function name, as called by +in the \fBzfget\fP function, and will override styles set under `\fB:zftp:*\fP\&'\&. +Note that only the top level function name, as called by the user, is used; calling of lower level functions is transparent to the user\&. Hence modifications to the title bar in \fBzftp_chpwd\fP use the contexts \fB:zftp:zfopen\fP, \fB:zftp:zfcd\fP, etc\&., depending where it was diff --git a/Doc/zshzle.1 b/Doc/zshzle.1 index bc685e553..c67d3fd34 100644 --- a/Doc/zshzle.1 +++ b/Doc/zshzle.1 @@ -1,4 +1,4 @@ -.TH "ZSHZLE" "1" "February 12, 2022" "zsh 5\&.8\&.1" +.TH "ZSHZLE" "1" "April 9, 2022" "zsh 5\&.8\&.1\&.2-test" .SH "NAME" zshzle \- zsh command line editor .\" Yodl file: Zsh/zle.yo @@ -101,6 +101,7 @@ In the `\fB\&.safe\fP\&' keymap, each single key is bound to \fBself\-insert\fP, except for ^J (line feed) and ^M (return) which are bound to \fBaccept\-line\fP\&. This is deliberately not pleasant to use; if you are using it, it means you deleted the main keymap, and you should put it back\&. +.PP .SS "Reading Commands" When ZLE is reading a command from the terminal, it may read a sequence that is bound to some command and is also a prefix of a longer bound string\&. @@ -129,6 +130,7 @@ without a real command being read\&. A key sequence typed by the user can be turned into a command name for use in user\-defined widgets with the \fBread\-command\fP widget, described in the subsection `Miscellaneous\&' of the section `Standard Widgets' below\&. +.PP .SS "Local Keymaps" While for normal editing a single keymap is used exclusively, in many modes a local keymap allows for some keys to be customised\&. For example, @@ -490,7 +492,7 @@ refer to a terminal an error is reported\&. \fBzle\fP \fB\-T\fP [ \fBtc\fP \fIfunction\fP | \fB\-r\fP \fBtc\fP | \fB\-L\fP ] .TP .PD -\fBzle\fP \fIwidget\fP [ \fB\-n\fP \fInum\fP ] [ \fB\-Nw\fP ] [ \fB\-K\fP \fIkeymap\fP ] \fIargs\fP \&.\&.\&. +\fBzle\fP \fIwidget\fP [ \fB\-n\fP \fInum\fP ] [ \fB\-f\fP \fIflag\fP ] [ \fB\-Nw\fP ] [ \fB\-K\fP \fIkeymap\fP ] \fIargs\fP \&.\&.\&. The \fBzle\fP builtin performs a number of different actions concerning ZLE\&. .RS @@ -578,8 +580,7 @@ For further information, see \fIzshcompwid\fP(1)\&. .TP \fB\-R\fP [ \fB\-c\fP ] [ \fIdisplay\-string\fP ] [ \fIstring\fP \&.\&.\&. ] -Redisplay the command line; this is to be called from within a user\-defined -widget to allow changes to become visible\&. If a \fIdisplay\-string\fP is +Redisplay the command line\&. If a \fIdisplay\-string\fP is given and not empty, this is shown in the status line (immediately below the line being edited)\&. .RS @@ -589,9 +590,9 @@ prompt in the same way as completion lists are printed\&. If no \fIstring\fPs are given but the \fB\-c\fP option is used such a list is cleared\&. .PP -Note that this option is only useful for widgets that do not exit -immediately after using it because the strings displayed will be erased -immediately after return from the widget\&. +Note that immediately after returning from running widgets, the command line +will be redisplayed and the strings displayed will be erased\&. Therefore, this +option is only useful for widgets that do not exit immediately after using it\&. .PP This command can safely be called outside user defined widgets; if zle is active, the display will be refreshed, while if zle is not active, the @@ -779,7 +780,7 @@ transformation is not applied to other non\-printing characters such as carriage returns and newlines\&. .RE .TP -\fIwidget\fP [ \fB\-n\fP \fInum\fP ] [ \fB\-Nw\fP ] [ \fB\-K\fP \fIkeymap\fP ] \fIargs\fP \&.\&.\&. +\fIwidget\fP [ \fB\-n\fP \fInum\fP ] [ \fB\-f\fP \fIflag\fP ] [ \fB\-Nw\fP ] [ \fB\-K\fP \fIkeymap\fP ] \fIargs\fP \&.\&.\&. Invoke the specified \fIwidget\fP\&. This can only be done when ZLE is active; normally this will be within a user\-defined widget\&. .RS @@ -799,6 +800,9 @@ appears as if the top\-level widget called by the user were still active\&. With the option \fB\-w\fP, \fBWIDGET\fP and related parameters are set to reflect the widget being executed by the \fBzle\fP call\&. .PP +Normally, when \fIwidget\fP returns the special parameter \fBLASTWIDGET\fP will +point to it\&. This can be inhibited by passing the option \fB\-f nolast\fP\&. +.PP Any further arguments will be passed to the widget; note that as standard argument handling is performed, any general argument list should be preceded by \fB\-\fP\fB\-\fP\&. If it is a shell @@ -821,13 +825,14 @@ it should call the \fBbeep\fP widget directly\&. .RE .RE .PP -.SH "WIDGETS" +.SH "ZLE WIDGETS" All actions in the editor are performed by `widgets\&'\&. A widget's job is simply to perform some small action\&. The ZLE commands that key sequences in keymaps are bound to are in fact widgets\&. Widgets can be user\-defined or built in\&. .PP -The standard widgets built into ZLE are listed in Standard Widgets below\&. +The standard widgets built into ZLE are listed in +the section `Standard Widgets\&' below\&. Other built\-in widgets can be defined by other modules (see \fIzshmodules\fP(1))\&. Each built\-in widget has two names: its normal canonical name, and the same name preceded by a `\fB\&.\fP\&'\&. The `\fB\&.\fP' name is special: it can't be @@ -839,6 +844,7 @@ as shell functions\&. When the widget is executed, the corresponding shell function is executed, and can perform editing (or other) actions\&. It is recommended that user\-defined widgets should not have names starting with `\fB\&.\fP\&'\&. +.PP .SH "USER\-DEFINED WIDGETS" User\-defined widgets, being implemented as shell functions, can execute any normal shell command\&. They can also run other widgets @@ -1053,7 +1059,7 @@ and \fBPOSTDISPLAY\fP are possible, but note that the \fBP\fP flag is needed for character indexing to include \fBPREDISPLAY\fP\&. .RS .PP -Each string consists of the following parts: +Each string consists of the following whitespace\-separated parts: .PP .PD 0 .TP @@ -1062,27 +1068,42 @@ Each string consists of the following parts: Optionally, a `\fBP\fP\&' to signify that the start and end offset that follow include any string set by the \fBPREDISPLAY\fP special parameter; this is needed if the predisplay string itself is to be highlighted\&. -Whitespace may follow the `\fBP\fP\&'\&. +Whitespace between the `\fBP\fP\&' and the start offset is optional\&. .TP \(bu -A start offset in the same units as \fBCURSOR\fP, terminated by -whitespace\&. +A start offset in the same units as \fBCURSOR\fP\&. .TP \(bu -An end offset in the same units as \fBCURSOR\fP, terminated by -whitespace\&. +An end offset in the same units as \fBCURSOR\fP\&. .TP \(bu A highlight specification in the same format as used for contexts in the parameter \fBzle_highlight\fP, see the section `Character Highlighting\&' below; -for example, \fBstandout\fP or \fBfg=red,bold\fP +for example, \fBstandout\fP or \fBfg=red,bold\fP\&. +.TP +\(bu +Optionally, a string of the form `\fBmemo=\fP\fItoken\fP\&'\&. +The \fItoken\fP consists of everything between the `\fB=\fP\&' and the next +whitespace, comma, NUL, or the end of the string\&. +The \fItoken\fP is preserved verbatim but not parsed in any way\&. +.RS +.PP +Plugins may use this to identify array elements they have added: for example, +a plugin might set \fItoken\fP to its (the plugin\&'s) name and then use +`\fBregion_highlight=( ${region_highlight:#*memo=\fP\fItoken\fP\fB} )\fP\&' +in order to remove array elements it have added\&. +.PP +(This example uses the `\fB${\fP\fIname\fP\fB:#\fP\fIpattern\fP\fB}\fP\&' array\-grepping +syntax described in +the section `Parameter Expansion\&' in \fIzshexpn\fP(1)\&.) +.RE .PP For example, .PP .RS .nf -\fBregion_highlight=("P0 20 bold")\fP +\fBregion_highlight=("P0 20 bold memo=foobar")\fP .fi .RE .PP @@ -1092,6 +1113,11 @@ any predisplay string should be highlighted in bold\&. Note that the effect of \fBregion_highlight\fP is not saved and disappears as soon as the line is accepted\&. .PP +Note that zsh 5\&.8 and older do not support the `\fBmemo=\fP\fItoken\fP\&' field +and may misparse the third (highlight specification) field when a memo +is given\&. + +.PP The final highlighting on the command line depends on both \fBregion_highlight\fP and \fBzle_highlight\fP; see the section CHARACTER HIGHLIGHTING below for details\&. @@ -2222,7 +2248,7 @@ a desired suffix\-preservation behavior\&. \fBbeep\fP Beep, unless the \fBBEEP\fP option is unset\&. .TP -\fBbracketed\-paste\fP +\fBbracketed\-paste\fP (\fB^[[200~\fP) (\fB^[[200~\fP) (\fB^[[200~\fP) This widget is invoked when text is pasted to the terminal emulator\&. It is not intended to be bound to actual keys but instead to the special sequence generated by the terminal emulator when text is pasted\&. diff --git a/Doc/ztexi.yo b/Doc/ztexi.yo index 7d52e6e91..c105c3e71 100644 --- a/Doc/ztexi.yo +++ b/Doc/ztexi.yo @@ -110,6 +110,7 @@ def(texiauthor)(1)(\ NOTRANS(@author )ARG1\ ) +COMMENT(Arguments are node identifiers: this, next, previous, up) def(texinode)(4)(\ NOTRANS(@node )ARG1, ARG2, ARG3, ARG4\ ) @@ -150,7 +151,7 @@ def(comment)(1)(\ COMMENT(--- cross-references ---) -def(manref)(2)(man page ARG1+LPAR()ARG2+RPAR()) +def(manref)(2)(ARG1+LPAR()ARG2+RPAR()) def(zmanref)(1)(manref(ARG1)(1)) def(noderef)(1)(\ NOTRANS(@ref{)ARG1+NOTRANS(})\ |