diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/Makefile.in | 8 | ||||
| -rw-r--r-- | Doc/Zsh/arith.yo | 5 | ||||
| -rw-r--r-- | Doc/Zsh/builtins.yo | 149 | ||||
| -rw-r--r-- | Doc/Zsh/compsys.yo | 137 | ||||
| -rw-r--r-- | Doc/Zsh/compwid.yo | 9 | ||||
| -rw-r--r-- | Doc/Zsh/contrib.yo | 125 | ||||
| -rw-r--r-- | Doc/Zsh/expn.yo | 306 | ||||
| -rw-r--r-- | Doc/Zsh/files.yo | 2 | ||||
| -rw-r--r-- | Doc/Zsh/func.yo | 39 | ||||
| -rw-r--r-- | Doc/Zsh/grammar.yo | 20 | ||||
| -rw-r--r-- | Doc/Zsh/mod_hlgroup.yo | 25 | ||||
| -rw-r--r-- | Doc/Zsh/mod_ksh93.yo | 243 | ||||
| -rw-r--r-- | Doc/Zsh/mod_parameter.yo | 17 | ||||
| -rw-r--r-- | Doc/Zsh/mod_pcre.yo | 19 | ||||
| -rw-r--r-- | Doc/Zsh/mod_private.yo | 15 | ||||
| -rw-r--r-- | Doc/Zsh/mod_stat.yo | 2 | ||||
| -rw-r--r-- | Doc/Zsh/mod_system.yo | 19 | ||||
| -rw-r--r-- | Doc/Zsh/mod_watch.yo | 6 | ||||
| -rw-r--r-- | Doc/Zsh/mod_zselect.yo | 2 | ||||
| -rw-r--r-- | Doc/Zsh/mod_zutil.yo | 7 | ||||
| -rw-r--r-- | Doc/Zsh/options.yo | 118 | ||||
| -rw-r--r-- | Doc/Zsh/params.yo | 137 | ||||
| -rw-r--r-- | Doc/Zsh/prompt.yo | 8 | ||||
| -rw-r--r-- | Doc/Zsh/redirect.yo | 3 | ||||
| -rw-r--r-- | Doc/Zsh/restricted.yo | 4 | ||||
| -rw-r--r-- | Doc/Zsh/zle.yo | 41 |
26 files changed, 1211 insertions, 255 deletions
diff --git a/Doc/Makefile.in b/Doc/Makefile.in index 23e5fc7e2..d9be182e9 100644 --- a/Doc/Makefile.in +++ b/Doc/Makefile.in @@ -43,6 +43,7 @@ TEXI2DVI = @TEXI2DVI@ DVIPS = dvips TEXI2PDF = @TEXI2PDF@ TEXI2HTML = @TEXI2HTML@ +SET_TEXI2ANY_VAR = @SET_TEXI2ANY_VAR@ PAPERSIZE = @PAPERSIZE@ .SUFFIXES: .yo .1 @@ -62,8 +63,9 @@ Zsh/mod_attr.yo Zsh/mod_cap.yo Zsh/mod_clone.yo \ Zsh/mod_compctl.yo Zsh/mod_complete.yo Zsh/mod_complist.yo \ Zsh/mod_computil.yo Zsh/mod_curses.yo \ Zsh/mod_datetime.yo Zsh/mod_db_gdbm.yo Zsh/mod_deltochar.yo \ -Zsh/mod_example.yo Zsh/mod_files.yo Zsh/mod_langinfo.yo \ -Zsh/mod_mapfile.yo Zsh/mod_mathfunc.yo \ +Zsh/mod_example.yo Zsh/mod_files.yo \ +Zsh/mod_hlgroup.yo Zsh/mod_langinfo.yo \ +Zsh/mod_ksh93.yo Zsh/mod_mapfile.yo Zsh/mod_mathfunc.yo \ Zsh/mod_nearcolor.yo Zsh/mod_newuser.yo \ Zsh/mod_parameter.yo Zsh/mod_pcre.yo Zsh/mod_private.yo \ Zsh/mod_regex.yo Zsh/mod_sched.yo Zsh/mod_socket.yo \ @@ -266,7 +268,7 @@ texi2html.conf: $(sdir_top)/Config/version.mk d=`echo $(VERSION_DATE)`; \ v="<font size=\"-1\">Zsh version $(VERSION), released on $$d.</font>"; \ case '$(TEXI2HTML)' in \ - *texi2any*) echo "set_from_init_file('PRE_BODY_CLOSE','$$v');" ;; \ + *texi2any*) echo "$(SET_TEXI2ANY_VAR)('PRE_BODY_CLOSE','$$v');" ;; \ *) echo "\$$PRE_BODY_CLOSE = '$$v';" ;; \ esac > $@ diff --git a/Doc/Zsh/arith.yo b/Doc/Zsh/arith.yo index bc3e35ad5..9f5298821 100644 --- a/Doc/Zsh/arith.yo +++ b/Doc/Zsh/arith.yo @@ -206,6 +206,11 @@ example, example(((val2 = val1 * 2))) assigns twice the value of tt($val1) to the parameter named tt(val2). +If the expansion of tt($val1) is text rather than a number, then when +tt(val1) is referenced that text is itself evaluated as a math expression +as if surrounded by parentheses `tt(LPAR()$val1)tt(RPAR())'. Expansion +continues until there are no more parameter references, a number has +resulted, or an expression error occurs. An internal integer representation of a named parameter can be specified with the tt(integer) builtin. diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index 733d8f185..7a9684ac8 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -683,6 +683,7 @@ the same as if the commands had been executed directly by the shell; if there are no var(args) or they contain no commands (i.e. are an empty string or whitespace) the return status is zero. ) +findex(exec) item(tt(exec) [ tt(-cl) ] [ tt(-a) var(argv0) ] [ var(command) [ var(arg) ... ] ])( Replace the current shell with var(command) rather than forking. If var(command) is a shell builtin command or a shell function, @@ -756,15 +757,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 @@ -873,7 +875,8 @@ xitem(tt(functions -M) [ tt(-m) var(pattern) ... ]) item(tt(functions +M) [ tt(-m) ] var(mathfn) ... )( Equivalent to tt(typeset -f), with the exception of the tt(-c), tt(-x), tt(-M) and tt(-W) options. For tt(functions -u) and tt(functions -U), -see tt(autoload), which provides additional options. +see tt(autoload), which provides additional options. For tt(functions -t) +and tt(functions -T), see tt(typeset -f). The tt(-x) option indicates that any functions output will have each leading tab for indentation, added by the shell to show syntactic @@ -1050,9 +1053,11 @@ The choice of hash table to work on is determined by the tt(-d) option; without the option the command hash table is used, and with the option the named directory hash table is used. -A command var(name) starting with a tt(/) is never hashed, whether by -explicit use of the tt(hash) command or otherwise. Such a command -is always found by direct look up in the file system. +A command var(name) starting with a tt(/) or with a relative path +starting with tt(./) or tt(../) is never executed by lookup in +the command hash table, and these can only be added to the table by +explicit use of the tt(hash) command. Such a command is always +found by direct look up in the file system. Given no arguments, and neither the tt(-r) or tt(-f) options, the selected hash table will be listed in full. @@ -1061,9 +1066,11 @@ The tt(-r) option causes the selected hash table to be emptied. It will be subsequently rebuilt in the normal fashion. The tt(-f) option causes the selected hash table to be fully rebuilt immediately. For the command hash table this hashes -all the absolute directories in the tt(PATH), -and for the named directory hash table this adds all users' home directories. +all (and em(only)) the absolute directories in the tt(PATH), +and for the named directory hash table this adds all users' home +directories. These two options cannot be used with any arguments. +Both options remove any explicitly-added elements. The tt(-m) option causes the arguments to be taken as patterns (which should be quoted) and the elements of the hash table @@ -1113,13 +1120,32 @@ 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) cindex(jobs, killing) xitem(tt(kill) [ tt(-s) var(signal_name) | tt(-n) var(signal_number) | \ -tt(-)var(sig) ] var(job) ...) -item(tt(kill) tt(-l) [ var(sig) ... ])( +tt(-)var(sig) ] [ tt(-q) var(value) ] var(job) ...) +xitem(tt(kill) tt(-l) [ var(sig) ... ]) +item(tt(kill) tt(-L))( Sends either tt(SIGTERM) or the specified signal to the given jobs or processes. Signals are given by number or by names, with or without the `tt(SIG)' @@ -1133,7 +1159,8 @@ specified the signal names are listed. Otherwise, for each var(sig) that is a name, the corresponding signal number is listed. For each var(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. +stopped by a signal the name of the signal is printed. The final +form with tt(-L) lists each signal name with its corresponding number. On some systems, alternative signal names are allowed for a few signals. Typical examples are tt(SIGCHLD) and tt(SIGCLD) or tt(SIGPOLL) and @@ -1145,6 +1172,9 @@ tt(kill -IO) and tt(kill -POLL) have the same effect. Many systems will allow process IDs to be negative to kill a process group or zero to kill the current process group. + +The tt(-q) option allows an integer value to be sent with the signal +on systems that support tt(sigqueue+LPAR()RPAR()). ) findex(let) item(tt(let) var(arg) ...)( @@ -1565,7 +1595,8 @@ Input is read from the coprocess. ) item(tt(-d) var(delim))( Input is terminated by the first character of var(delim) instead of -by newline. +by newline. For compatibility with other shells, if var(delim) is an +empty string, input is terminated at the first NUL. ) item(tt(-t) [ var(num) ])( Test if input is available before attempting to read. If var(num) @@ -1608,6 +1639,7 @@ cancels both tt(-p) and tt(-u). The tt(-c) or tt(-l) flags cancel any and all of tt(-kpquz). ) +findex(readonly) cindex(parameters, marking readonly) item(tt(readonly))( Same as tt(typeset -r). With the tt(POSIX_BUILTINS) option set, same @@ -1619,7 +1651,9 @@ 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). +an arithmetic expression var(n). Also causes a non-interctive +shell to exit, allowing files containing shell code to be used +both as scripts and as autoloadable shell functions. For example, the following prints `tt(42)': example(() { integer foo=40; return "foo + 2" } @@ -1885,7 +1919,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) ...)( @@ -1898,6 +1933,8 @@ redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ ))ifnztexi( ))) xitem(tt(typeset )[ {tt(PLUS())|tt(-)}tt(AHUaghlmrtux) ] \ [ {tt(PLUS())|tt(-)}tt(EFLRZip) [ var(n) ] ]) xitem(SPACES()[ tt(+) ] [ var(name)[tt(=)var(value)] ... ]) +xitem(tt(typeset ){tt(PLUS())|tt(-)}tt(n) [ tt(-g) ] \ +[ {tt(PLUS())|tt(-)}tt(r) ] [ var(name)[tt(=)var(value)] ... ]) xitem(tt(typeset )tt(-T) [ {tt(PLUS())|tt(-)}tt(Uglrux) ] [ {tt(PLUS())|tt(-)}tt(LRZp) [ var(n) ] ]) xitem(SPACES()[ tt(+) | var(SCALAR)[tt(=)var(value)] var(array)[tt(=LPAR())var(value) ...tt(RPAR())] [ var(sep) ] ]) item(tt(typeset) tt(-f) [ {tt(PLUS())|tt(-)}tt(TUkmtuz) ] [ tt(+) ] [ var(name) ... ])( @@ -1915,7 +1952,7 @@ retain their special attributes when made local. For each var(name)tt(=)var(value) assignment, the parameter 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 +does em(not) refer to an existing parameter, a new parameter is initialized 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. @@ -2011,6 +2048,36 @@ To initialize a parameter var(param) to a command output and mark it readonly, use tt(typeset -r )var(param) or tt(readonly )var(param) after the parameter assignment statement. +cindex(named reference) +cindex(reference, named) +The flag tt(-n) creates a em(named reference) to another parameter. +The second parameter need not exist at the time the reference is +created. Only tt(-g), tt(-u), and tt(-r) may be used in conjunction with +tt(-n). The var(name) so created may not be an array element nor use +a subscript, but the var(value) assigned may be any valid parameter +name syntax, even a subscripted array element (including an associative +array element) or an array slice, which is evaluated when the named +reference is expanded. It is an error for a named reference to refer +to itself, even indirectly through a chain of references. When tt(-u) +is applied to a named reference, the parameter identified by var(value) +is always found in the calling function scope rather than the current +local scope. In this case, if there is no such parameter in the calling +scope, assignments to the named reference may fail, setting tt($?) to 1. +See ifzman(zmanref(zshexpn))ifnzman(noderef(Parameter Expansion)) and +ifzman(zmanref(zshparam))ifnzman(noderef(Parameters)) for details of the +behavior of named references. + +Local function scoping rules for `tt(typeset)' do apply with `tt(-n)', +so a declaration within a function persists only until the end of the +function unless `tt(-g -n)' is specified, and any local parameter (of +any type) with the same var(name) supplants a named reference from a +surrounding scope. + +A scalar parameter, including an existing named reference, may be +converted to a new named reference by `tt(typeset -n )var(name)', so +the `tt(-p)' option must be included to display the value of a +specific named reference var(name). + If no attribute flags are given, and either no var(name) arguments are present or the flag tt(+m) is used, then each parameter name printed is preceded by a list of the attributes of that parameter (tt(array), @@ -2026,8 +2093,9 @@ startitem() item(tt(PLUS()))( If `tt(PLUS())' appears by itself in a separate word as the last option, then the names of all parameters (functions with tt(-f)) are printed, but -the values (function bodies) are not. No var(name) arguments may appear, -and it is an error for any other options to follow `tt(PLUS())'. The +the values (function bodies) are not. If var(name) arguments appear, +both those names and their values are printed in the form of assignments. +It is an error for any other options to follow `tt(PLUS())', but the effect of `tt(PLUS())' is as if all attribute flags which precede it were given with a `tt(PLUS())' prefix. For example, `tt(typeset -U PLUS())' is equivalent to `tt(typeset +U)' and displays the names of all arrays having @@ -2054,13 +2122,15 @@ is not used in this case). If the tt(+g) flag is combined with tt(-m), a new local parameter is created for every matching parameter that is not already local. Otherwise -tt(-m) applies all other flags or assignments to the existing parameters. +tt(-m) applies all other flags or assignments to the existing parameters, +except that the tt(-n) option cannot create named references in this way. Except when assignments are made with var(name)tt(=)var(value), using tt(+m) forces the matching parameters and their attributes to be printed, even inside a function. Note that tt(-m) is ignored if no patterns are given, so `tt(typeset -m)' displays attributes but `tt(typeset -a +m)' -does not. +does not. Ordinary scalar string parameters have no attributes, so for +those tt(+m) prints only the names. ) item(tt(-p) [ var(n) ])( If the tt(-p) option is given, parameters and values are printed in the @@ -2072,6 +2142,14 @@ tt(-p) may be followed by an optional integer argument. Currently only the value tt(1) is supported. In this case arrays and associative arrays are printed with newlines between indented elements for readability. + +The names and values of readonly special parameters +(most of the parameters marked `<S>' in +ifzman(zmanref(zshparam))ifnzman(noderef(Parameters Set By The Shell)), +except those documented as settable) +are not printed with `tt(-)tt(p)' because to execute those typeset commands +would cause errors. However, these parameters are printed when they +have been made local to the scope where `tt(typeset -p)' is run. ) item(tt(-T) [ var(scalar)[tt(=)var(value)] var(array)[tt(=LPAR())var(value) ...tt(RPAR())] [ var(sep) ] ])( This flag has a different meaning when used with tt(-f); see below. @@ -2214,9 +2292,9 @@ automatically given the tt(-h) attribute to avoid name clashes. item(tt(-H))( Hide value: specifies that tt(typeset) will not display the value of the parameter when listing parameters; the display for such parameters is -always as if the `tt(PLUS())' flag had been given. Use of the parameter is -in other respects normal, and the option does not apply if the parameter is -specified by name, or by pattern with the tt(-m) option. This is on by +always as if the `tt(PLUS())' flag were given, but use of the parameter is +in other respects normal. This effect does not apply when the parameter is +specified by name or by pattern with the tt(-m) option. This is on by default for the parameters in the tt(zsh/parameter) and tt(zsh/mapfile) modules. Note, however, that unlike the tt(-h) flag this is also useful for non-special parameters. @@ -2263,8 +2341,10 @@ readonly). Special variables that have been made readonly retain their value and readonly attribute when made local. ) item(tt(-t))( -Tags the named parameters. Tags have no special meaning to the shell. -This flag has a different meaning when used with tt(-f); see above. +Tags the named parameters. Tags only exist to flag the parameter for +the user's own purposes --- the list of tagged parameters can be queried +using `tt(typeset -t)'. Tags have no other use. Note that the tt(-t) +flag has a different meaning when used with tt(-f); see above. ) item(tt(-u))( Convert the result to upper case whenever the parameter is expanded. @@ -2354,6 +2434,7 @@ 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. ) +findex(unalias) cindex(aliases, removing) item(tt(unalias) [ tt(-ams) ] var(name) ...)( Removes aliases. This command works the same as tt(unhash -a), except that @@ -2395,7 +2476,7 @@ with the command `tt(zmodload -F zsh/rlimits b:unlimit)'. ) findex(unset) cindex(parameters, unsetting) -item(tt(unset) [ tt(-fmv) ] var(name) ...)( +item(tt(unset) [ tt(-fmv) ] [ tt(-n) ] var(name) ...)( Each named parameter is unset. Local parameters remain local even if unset; they appear unset within scope, but the previous value will still reappear when the scope ends. @@ -2409,10 +2490,13 @@ be quoted) and all parameters with matching names are unset. Note that this cannot be used when unsetting associative array elements, as the subscript will be treated as part of the pattern. -The tt(-v) flag specifies that var(name) refers to parameters. This is the -default behaviour. +The tt(-v) flag specifies that var(name) refers to parameters. This is +the default behaviour. If the tt(-n) option is supplied, and +var(name) is a a named reference, var(name) will be unset rather than +the variable it references. -tt(unset -f) is equivalent to tt(unfunction). +tt(unset -f) is equivalent to tt(unfunction). The tt(-n) option has +no effect with tt(-f). ) findex(unsetopt) cindex(options, unsetting) @@ -2500,11 +2584,14 @@ item(tt(-a))( Do a search for all occurrences of var(name) throughout the command path. Normally only the first occurrence is printed. +When combined with tt(-m), only names appearing in the command hash +table are searched, but all occurrences of those names are printed. ) item(tt(-m))( The arguments are taken as patterns (pattern characters should be -quoted), and the information is displayed for each command matching one -of these patterns. +quoted), and the information is displayed for each entry in the command +hash table matching one of these patterns. The hash table is first +refilled, in case of changes to tt(PATH). ) item(tt(-s))( If a pathname contains symlinks, print the symlink-free pathname as well. diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index f85293ac7..f75298a1b 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -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 @@ -891,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 @@ -922,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) @@ -1389,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 @@ -1652,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 @@ -1798,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 @@ -1900,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 @@ -1924,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. @@ -1935,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. @@ -2023,8 +2023,8 @@ position shown as a percentage of the total length otherwise. In each case the form with the uppercase letter will be replaced by a string of fixed width, padded to the right with spaces, while the lowercase form will be replaced by a variable width string. As in other prompt strings, the -escape sequences `tt(%S)', `tt(%s)', `tt(%B)', `tt(%b)', `tt(%U)', -`tt(%u)' for entering and leaving the display modes +escape sequence `tt(%H)` along with `tt(%S)', `tt(%s)', `tt(%B)', `tt(%b)', +`tt(%U)', `tt(%u)' for entering and leaving the display modes standout, bold and underline, and `tt(%F)', `tt(%f)', `tt(%K)', `tt(%k)' for changing the foreground background colour, are also available, as is the form `tt(%{)...tt(%})' for enclosing escape sequences which display with zero @@ -2039,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 @@ -2046,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 @@ -5227,6 +5227,57 @@ the group name. This function is called automatically from tt(_description) and hence is not normally called explicitly. ) +findex(_shadow) +findex(_unshadow) +xitem(tt(_shadow) [ tt(-s) var(suffix) ] [ -- ] var(command_name) ...) +item(tt(_unshadow))( +The tt(_shadow) function creates a copy of each of the shell functions +in the var(command_name) arguments. The original functions can then +be replaced by new implementations. A later call to tt(_unshadow) +removes the new implementations, if any, and restores the originals. + +Recommended usage is to pair tt(_shadow) and tt(_unshadow) calls by +use of an `tt(always)' block: +example({ + _shadow fname + function fname { + # Do your new thing + } + # Invoke callers of fname +} always { + _unshadow +}) + +The var(suffix), if supplied, is prepended by an `tt(@)' character and +then appended to each var(command_name) to create the copy. Thus +example(_shadow -s XX foo) +creates a function named `tt(foo@XX)'. This provides a well-known +name for the original implementation if the new implementation needs +to call it as a wrapper. If a nested call to tt(_shadow) uses the +same var(suffix), em(no new copy is made). The presumption thus is +that suffixes and new implementations correspond one to one. + +If var(command_name) is a builtin or external command, and there has been +no preceding tt(_shadow) replacement made, the function so created calls +the shadowed name prefixed by the tt(builtin) or tt(command) keywords as +appropriate. +example({ + _shadow -s wrap compadd + compadd LPAR()RPAR() { + # compadd@wrap runs builtin compadd + compadd@wrap -O tmparr "$@" } +} always { + _unshadow +}) + +When no var(suffix) argument is present, tt(_shadow) creates a unique +suffix to avoid name collisions. + +Arguments of tt(_unshadow) are ignored. Every listed var(command_name) +for the most recent call to tt(_shadow) is removed. This differs from +an early implementation that required tt(_unshadow) to receive the +same var(suffix) and var(command_name) list as tt(_shadow). +) findex(_store_cache) item(tt(_store_cache) var(cache_identifier) var(param) ...)( This function, together with tt(_retrieve_cache) and diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo index d32a0702f..b0c9b0a5f 100644 --- a/Doc/Zsh/compwid.yo +++ b/Doc/Zsh/compwid.yo @@ -112,7 +112,7 @@ vindex(QIPREFIX) item(tt(QIPREFIX))( This parameter is read-only and contains the quoted string up to the word being completed. E.g. when completing `tt("foo)', this parameter -contains the double quote. If the tt(-q) option of tt(compset) is used +contains the double quote. If the tt(-q) option of tt(compset) is used (see below), and the original string was `tt("foo bar)' with the cursor on the `tt(bar)', this parameter contains `tt("foo )'. ) @@ -597,7 +597,8 @@ ifnzman((see noderef(Prompt Expansion)))\ ifzman(as described in the section EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc)): `tt(%B)', `tt(%S)', `tt(%U)', `tt(%F)', `tt(%K)' and their lower case -counterparts, as well as `tt(%{)...tt(%})'. `tt(%F)', `tt(%K)' and +counterparts, as well as `tt(%H)' and `tt(%{)...tt(%})'. `tt(%F)', +`tt(%K)', `tt(%H)' and `tt(%{)...tt(%})' take arguments in the same form as prompt expansion. (Note that the sequence `tt(%G)' is not available; an argument to `tt(%{)' should be used instead.) The sequence `tt(%%)' @@ -1082,8 +1083,8 @@ 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))( +xitem(tt(r:)var(word-pat)tt(|)tt(=)var(match-pat)) +item(tt(R:)var(word-pat)tt(|)tt(=)var(match-pat))( 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 diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index 0800fa52b..c1bea6022 100644 --- a/Doc/Zsh/contrib.yo +++ b/Doc/Zsh/contrib.yo @@ -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) @@ -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. @@ -1404,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 @@ -1669,6 +1669,11 @@ 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 @@ -1687,6 +1692,11 @@ 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 @@ -1769,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. @@ -2433,6 +2448,33 @@ history is restricted, so cursor motions, etc., may not pass outside of the pasted content. Text assigned to tt(BUFFER) by the active widgets is copied back into tt(PASTED) before tt(paste-finish). ) +tindex(bracketed-paste-url-magic) +item(tt(bracketed-paste-url-magic))( +This widget is a simpler version of using tt(bracketed-paste-magic) +to enable tt(quote-url-magic). Rather than re-interpreting everything as +keystrokes, it simply handles quoting of pasted urls itself, and all other +text is handled like the default bracketed-paste widget. + +It limits the quoting to pastes that consist of a single url, but you +can also enable or disable quoting explicitly for a paste by setting +NUMERIC to 1 or 2 respectively (ie, by pressing alt-1 or alt-2 before +pasting). + +It is also possible to customize the list of schemas used to +decide if something is a url by setting the tt(schema) style in the +tt(:bracketed-paste-url-magic) context, for example: +ifzman() +example(zstyle :bracketed-paste-url-magic schema http:// myspecialschema:) + +The default list of schemas is tt(http:// https:// ftp:// ftps:// file:// \ + ssh:// sftp:// magnet:). + +The widget itself is installed in a similar way as +tt(bracketed-paste-magic) above, by +ifzman() +example(autoload -Uz bracketed-paste-url-magic +zle -N bracketed-paste bracketed-paste-url-magic) +) tindex(copy-earlier-word) item(tt(copy-earlier-word))( This widget works like a combination of tt(insert-last-word) and @@ -2578,12 +2620,33 @@ zle -N history-pattern-search-forward history-pattern-search) tindex(incarg) vindex(incarg, use of) item(tt(incarg))( -Typing the keystrokes for this widget with the cursor placed on or to the -left of an integer causes that integer to be incremented by one. With a -numeric argument, the number is incremented by the amount of the -argument (decremented if the numeric argument is negative). The shell -parameter tt(incarg) may be set to change the default increment to -something other than one. +This widget allows you to increment integers on the current line. In addition +to decimals, it can handle hexadecimals prefixed with tt(0x), binaries with +tt(0b), and octals with tt(0o). + +By default, the target integer will be incremented by one. With a numeric +argument, the integer is incremented by the amount of the argument. The shell +parameter tt(incarg) may be set to change the default increment to something +other than one. + +The behavior of this widget changes depending on the widget name. + +When the widget is named tt(incarg), the widget will increment an integer +placed under the cursor placed or just to the left of it. tt(decarg), on the +other hand, decrements the integer. When the name is prefixed with tt(vi), +the cursor will jump to the nearest integer after the cursor before incrementing +it. The tt(vi) prefix can also be combined with a tt(backward-) prefix to make +the widget search backwards for numbers. + +There's also a tt(sync-) prefix that can be added to the widget name. This +variant is used for creating a sequence of numbers on split terminals with +synchronized key input. The first pane won't increment the integer at all, but +each pane after that will have the integer incremented once more than the +previous pane. It currently supports tmux and iTerm2. + +The prefixes tt(vi), tt(backward-), and tt(sync-) can be combined, for example, +into tt(vim-sync-) or tt(vim-backward-sync-). The tt(vi) prefix needs to be +at the very beginning. example(bindkey '^X+' incarg) ) @@ -3957,8 +4020,11 @@ calculation is stored. For example, the result of the calculation on the line preceded by `tt(4> )' is available as tt($4). The last value calculated is available as tt(ans). Full command line editing, including the history of previous calculations, is available; the history is saved in -the file tt(~/.zcalc_history). To exit, enter a blank line or type `tt(:q)' -on its own (`tt(q)' is allowed for historical compatibility). +the file tt($ZCALC_HISTFILE). If tt($ZCALC_HISTFILE) is unset, +tt($ZDOTDIR/.zcalc_history) is used instead, which in turn falls backs to +tt($HOME/.zcalc_history) if tt($ZDOTDIR) is unset. To exit, enter a blank +line or type `tt(:q)' on its own (`tt(q)' is allowed for historical +compatibility). A line ending with a single backslash is treated in the same fashion as it is in command line editing: the backslash is removed, the @@ -4247,13 +4313,17 @@ tt(colors) more than once. The eight base colors are: tt(black), tt(red), tt(green), tt(yellow), tt(blue), tt(magenta), tt(cyan), and tt(white). Each of these has codes for foreground and background. In addition there are seven intensity attributes: -tt(bold), tt(faint), tt(standout), tt(underline), tt(blink), tt(reverse), +tt(bold), tt(faint), tt(italic), tt(underline), tt(blink), tt(reverse), and tt(conceal). Finally, there are seven codes used to negate attributes: tt(none) (reset all attributes to the defaults), tt(normal) -(neither bold nor faint), tt(no-standout), tt(no-underline), tt(no-blink), +(neither bold nor faint), tt(no-italic), tt(no-underline), tt(no-blink), tt(no-reverse), and tt(no-conceal). Some terminals do not support all combinations of colors and intensities. +Prior to zsh tt(5.8.1) the intensity tt(standout) was provided. It has +been replaced by the more specific tt(italic) and tt(reverse) to match +the specification, but some terminals may swap these or make one of them +produce blinking text even if the tt(blink) code is not usable. The associative arrays are: @@ -4318,6 +4388,27 @@ example(is-at-least 3.1.6-15 && setopt NO_GLOBAL_RCS is-at-least 3.1.0 && setopt HIST_REDUCE_BLANKS is-at-least 2.6-17 || print "You can't use is-at-least here.") ) +findex(mkshadow) +findex(rmshadow) +xitem(tt(mkshadow) [ tt(-s) var(suffix) ] [ -- ] var(command_name) ...) +item(tt(rmshadow))( +These functions are an interface to the tt(_shadow) and tt(_unshadow) +completion utilities to make them more easily accessible in other +contexts. Usage is exactly as for the completion utility: +example({ + mkshadow fname + function fname { + # Do your new thing + } + # Invoke callers of fname +} always { + rmshadow +}) + +Upon return, the value of tt($REPLY) is the suffix used to create a +copy of the original var(command_name), so var(command_name)tt(@$REPLY) +invokes that original. +) findex(nslookup) item(tt(nslookup) [ var(arg) ... ])( This wrapper function for the tt(nslookup) command requires the @@ -4602,10 +4693,10 @@ renames `tt(foo.lis)' to `tt(foo.txt)', `tt(my.old.stuff.lis)' to The pattern is always treated as an tt(EXTENDED_GLOB) pattern. Any file whose name is not changed by the substitution is simply ignored. Any -error (a substitution resulted in an empty string, two substitutions gave -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. +error (no files matched the var(srcpat), substitution resulted in an empty +string, two substitutions gave 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 referred to in the second (replacement) argument. This makes it possible to diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo index 753e5a008..7eade4a11 100644 --- a/Doc/Zsh/expn.yo +++ b/Doc/Zsh/expn.yo @@ -312,7 +312,8 @@ zero) that are neither `tt(.)' nor `tt(/)' and that continue to the end of the string. For example, the extension of `tt(foo.orig.c)' is `tt(.c)', and `tt(dir.c/foo)' has no extension. ) -item(tt(s/)var(l)tt(/)var(r)[tt(/)])( +xitem(tt(s/)var(l)tt(/)var(r)[tt(/)]) +item(tt(S/)var(l)tt(/)var(r)[tt(/)])( Substitute var(r) for var(l) as described below. The substitution is done only for the first string that matches var(l). For arrays and for filename @@ -324,13 +325,17 @@ perform global substitution, i.e. substitute every occurrence of var(r) for var(l). Note that the tt(g) or tt(:G) must appear in exactly the position shown. +The use of tt(S) instead of tt(s) is identical except that +the source is treated as a pattern, just as if the option +tt(HIST_SUBST_PATTERN) were set. + See further notes on this form of substitution below. ) item(tt(&))( -Repeat the previous tt(s) substitution. Like tt(s), may be preceded -immediately by a tt(g). In parameter expansion the tt(&) must appear -inside braces, and in filename generation it must be quoted with a -backslash. +Repeat the previous tt(s) or tt(S) substitution, whichever was most +recent. Like tt(s) and tt(S), may be preceded immediately by a tt(g). +In parameter expansion the tt(&) must appear inside braces, and in +filename generation it must be quoted with a backslash. ) item(tt(t) [ var(digits) ])( Remove all leading pathname components, leaving the final component (tail). @@ -377,7 +382,8 @@ substitutions or expansions are performed once at the time the qualifier is parsed, even before the `tt(:s)' expression itself is divided into var(l) and var(r) sides. -If the option tt(HIST_SUBST_PATTERN) is set, var(l) is treated as +If the option tt(HIST_SUBST_PATTERN) is set or the original substitution +was started with a capital tt(S), var(l) is treated as a pattern of the usual form described in ifzman(the section FILENAME GENERATION below)\ ifnzman(noderef(Filename Generation)). This can be used in @@ -604,6 +610,16 @@ and other operators, such as `tt(${PREFIX:-"/usr/local"})'. Parameter expansions can also be nested. These topics will be introduced below. The full rules are complicated and are noted at the end. +cindex(namespace) +Parameter expansions may optionally include a em(namespace) prefix in +the format `tt(.)var(identifier)tt(.)' This currently has no special +meaning to the shell, but provides a convenient means of grouping +related parameters. Expansions using a namespace em(must) include +braces (tt({) and tt(})) as shown in the descriptions below, and +only one namespace prefix is allowed. Note that, for support of +possible future features, the first `tt(.)' is optional, but omitting +it is discouraged. + In the expansions discussed below that require a pattern, the form of the pattern is the same as that used for filename generation; see noderef(Filename Generation). Note that these patterns, along with @@ -616,6 +632,8 @@ substitution on the expansion of parameter tt($i). In the following descriptions, `var(word)' refers to a single word substituted on the command line, not necessarily a space delimited word. +The reference to `var(name)' in each description presumes any optional +namespace prefix. startitem() item(tt(${)var(name)tt(}))( @@ -665,7 +683,9 @@ item(tt(${)var(name)tt(:?)var(word)tt(}))( In the first form, if var(name) is set, or in the second form if var(name) is both set and non-null, then substitute its value; otherwise, print var(word) and exit from the shell. Interactive shells instead return to -the prompt. If var(word) is omitted, then a standard message is printed. +the prompt. If var(word) is omitted, then a standard message is +printed. Note that var(word) is expanded even though its value +is not substituted onto the command line. ) enditem() @@ -967,10 +987,16 @@ means the same thing as the more readable `(tt(%%qqq))'. The following flags are supported: startitem() +item(tt(!))( +When the parameter being expanded is a named reference, the reference +itself is examined and thus is em(not) resolved to its referent. In +ksh emulation, the parens around this flag are optional. +) 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. @@ -1092,7 +1118,7 @@ tt(KSH_ARRAYS) option a subscript `tt([*])' or `tt([@])' is needed to operate on the whole array, as usual. ) item(tt(L))( -Convert all letters in the result to lower case. +Convert all letters in the result to lower case, like `tt(typeset -l)'. ) item(tt(n))( Sort decimal integers numerically; if the first differing @@ -1176,46 +1202,56 @@ of the parameter would usually appear. This string consists of keywords separated by hyphens (`tt(-)'). The first keyword in the string describes the main type, it can be one of `tt(scalar)', `tt(array)', `tt(integer)', `tt(float)' or `tt(association)'. The other keywords describe the type in -more detail: +more detail, in most cases corresponding to options of the `tt(typeset)' +command: startitem() item(tt(local))( for local parameters ) item(tt(left))( -for left justified parameters +for left justified parameters (tt(-L)) ) item(tt(right_blanks))( -for right justified parameters with leading blanks +for right justified parameters with leading blanks (tt(-R)) ) item(tt(right_zeros))( -for right justified parameters with leading zeros +for right justified parameters with leading zeros (tt(-Z)) ) item(tt(lower))( for parameters whose value is converted to all lower case when it is -expanded +expanded (tt(-l)) ) item(tt(upper))( for parameters whose value is converted to all upper case when it is -expanded +expanded (tt(-u)) ) item(tt(readonly))( -for readonly parameters +for readonly parameters (tt(-r)) ) item(tt(tag))( -for tagged parameters +for tagged parameters (tt(-t)) +) +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 +for exported parameters (tt(-x) or `tt(export)') ) item(tt(unique))( -for arrays which keep only the first occurrence of duplicated values +for arrays which keep only the first occurrence of duplicated values (tt(-U)) ) item(tt(hide))( -for parameters with the `hide' flag +for parameters with the `hide' flag (tt(-h)) ) item(tt(hideval))( -for parameters with the `hideval' flag +for parameters with the `hideval' flag (tt(-H)) +) +item(tt(nameref))( +for named references (tt(typeset -n)) either having an empty value or +when combined with `tt(!)' as in `tt(${LPAR()!t)tt(RPAR()var(rname)})' ) item(tt(special))( for special parameters defined by the shell @@ -1223,10 +1259,10 @@ for special parameters defined by the shell enditem() ) item(tt(u))( -Expand only the first occurrence of each unique word. +Expand only the first occurrence of each unique word, like `tt(typeset -U)'. ) item(tt(U))( -Convert all letters in the result to upper case. +Convert all letters in the result to upper case, like `tt(typeset -u)'. ) item(tt(v))( Used with tt(k), substitute (as two consecutive words) both the key @@ -1492,8 +1528,9 @@ form using `tt(%%)' will remove the same matches as for `tt(##)' in reverse order. ) item(tt(*))( +pindex(EXTENDED_GLOB, enable) Enable tt(EXTENDED_GLOB) for substitution via tt(${)...tt(/)...tt(}) or -tt(${)...tt(//)...tt(}). +tt(${)...tt(//)...tt(}). Note that `tt(**)' does not disable extendedglob. ) item(tt(B))( Include the index of the beginning of the match in the result. @@ -1513,6 +1550,103 @@ Include the unmatched portion in the result (the em(R)est). ) enditem() +subsect(Named References) +cindex(named references) +cindex(namerefs) +cindex(reference variables) +cindex(parameters, nameref) +The command +ifzman() +indent(tt(typeset -n )var(pname)tt(=)var(rname)) + +initializes a parameter var(pname) as a reference to a second +parameter var(rname). With the few exceptions described here, when +var(pname) is used in any of the expansion forms described above, the +parameter var(rname) is expanded instead. This is similar to the +action of the `tt((P))' expansion flag, but when var(rname) has itself +been declared a named reference, that third parameter referenced by +var(pname) is also expanded, and so on. With `tt((P))' this must be +done explicitly, so for example +tt(${LPAR()P)tt(RPAR()${LPAR()P)tt(RPAR())var(name)tt(}}). + +Unlike `tt((P))', named references in substitutions that perform +assignment, such as tt(${)var(pname)tt(::=)var(word)tt(}), do not +create new arrays when var(rname) is in the form of an array element +or slice and no such array (or associative array) is presently set. +This includes arrays declared, but not initialized, when the option +tt(TYPESET_TO_UNSET) is in effect. The var(word) is substituted but +no assignment occurs. + +Also unlike `tt((P))' named references always expand parameters at +the scope in which var(rname) existed when `tt(typeset -n)' was +called. This can be used to expand or assign parameters from an +earlier scope even if a local of the same name has been declared at +a later scope. Example: +ifzman() +example(tt(caller=OUTER) +tt(func LPAR()RPAR() {) +tt( print before local: $caller) +tt( typeset -n outer=$1) +tt( local caller=INNER) +tt( print by reference: $outer) +tt( outer=RESULT) +tt(}) +tt(func caller) +tt(print after func: $caller)) + +displays the output +ifzman() +example(tt(before local: OUTER) +tt(by reference: OUTER) +tt(after func: RESULT)) + +To force a named reference to refer to the outer scope, even if a local +has already been declared, add the tt(-u) option when declaring the +named reference. In this case var(rname) should already exist in the +outer scope, otherwise the behavior of assignment through var(pname) +is not defined and may change the scope of the reference or fail with +a status of 1. Example of correct usage: +ifzman() +example(tt(caller=OUTER) +tt(func LPAR()RPAR() {) +tt( print before local: $caller) +tt( local caller=INNER) +tt( print after local: $caller) +tt( typeset -n -u outer=$1) +tt( print by reference: $outer) +tt( outer=RESULT) +tt(}) +tt(func caller) +tt(print after func: $caller)) + +Note, however, that named references to em(special) parameters acquire +the behavior of the special parameter, regardless of the scope where +the reference is declared. + +When var(rname) includes an array subscript, the subscript expression +is interpreted at the time tt(${)var(pname)tt(}) is expanded. Any +form of subscript is allowed, including those that select individual +elements, substrings of scalar strings, or multiple elements as with +array slices or the `tt((i))', `tt((I))', `tt((r))', `tt((R))' and +`tt((w))' subscript flags. However, the subscript is evaluated with +the tt(NO_EXEC) option in effect, so command substitution and other +similar constructs produce no output, although are not syntactically +excluded. + +When var(rname) is an array (but not an array element or slice), the +named reference may also be used in substitutions requiring an +var(arrayname), so these are equivalent: +ifzman() +example(tt(${)var(name)tt(:|)var(rname)tt(}) +tt(${)var(name)tt(:|)var(pname)tt(})) + +Expansions of the form `tt(${LPAR()t)tt(RPAR())var(pname)tt(})' expand +the type information of var(rname), unless var(rname) is empty, in which +case the expansion is `tt(nameref)', or when no variable var(rname) +exists, in which case the expansion is empty. + +See also ifzman(zmanref(zshparam))ifnzman(noderef(Parameters)). + subsect(Rules) cindex(parameter expansion rules) cindex(rules, parameter expansion) @@ -1535,12 +1669,16 @@ substitutions; the nested substitution will return either a scalar or an array as determined by the flags, possibly adjusted for quoting. All the following steps take place where applicable at all levels of substitution. -Note that, unless the `tt((P))' flag is present, the flags and any +Note that, unless the `tt((P))' flag or a named reference is present, +the flags and any subscripts apply directly to the value of the nested substitution; for example, the expansion tt(${${foo}}) behaves exactly the same as -tt(${foo}). When the `tt((P))' flag is present in a nested substitution, +tt(${foo}). When a named reference or the `tt((P))' flag is used in a +nested substitution, the other substitution rules are applied to the value em(before) it is interpreted as a name, so tt(${${(P)foo}}) may differ from tt(${(P)foo}). +When both a named reference and the `tt((P))' flag appear, the named +reference is resolved before `tt((P))' is applied. At each nested level of substitution, the substituted words undergo all forms of single-word substitution (i.e. not filename generation), including @@ -1766,23 +1904,65 @@ 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 -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 -output is broken into words using the tt(IFS) parameter. +`tt($LPAR())...tt(RPAR())', or quoted with grave accents, like +`tt(`)...tt(`)', is executed in a subshell and replaced by its +standard output, with any trailing newlines deleted. If the +substitution is not enclosed in double quotes, the output is broken +into words using the tt(IFS) parameter. vindex(IFS, use of) The substitution `tt($LPAR()cat) var(foo)tt(RPAR())' may be replaced by the faster `tt($LPAR()<)var(foo)tt(RPAR())'. In this case var(foo) undergoes single word shell expansions (em(parameter expansion), em(command substitution) and em(arithmetic expansion)), but not -filename generation. +filename generation. No subshell is created. If the option tt(GLOB_SUBST) is set, the result of any unquoted command substitution, including the special form just mentioned, is eligible for filename generation. +A command with a leading pipe character, enclosed in braces prefixed by +a dollar sign, as in `tt(${|)...tt(})', is executed in the current shell +context, rather than in a subshell, and is replaced by the value of the +parameter tt(REPLY) at the end of the command. There em(must not) be +any whitespace between the opening brace and the pipe character. Any +prior value of tt($REPLY) is saved and restored around this substitution, +in the manner of a function local parameter. Other parameters declared +within the substitution also behave as locals, as if in a function, +unless `tt(typeset -g)' is used. Trailing newlines are em(not) deleted +from the final replacement in this case, and it is subject to filename +generation in the same way as `tt($LPAR())...tt(RPAR())' but is em(not) +split on tt(IFS) unless the tt(SH_WORD_SPLIT) option is set. + +cindex(substitution, command, current shell) +cindex(substitution, command, non forking) +cindex(substitution, nofork) +Substitutions of the form `tt(${{)var(param)tt(}) ...tt(})' are similar, +except that the substitution is replaced by the value of the parameter +named by var(param). No implicit save or restore applies to var(param) +and var(param) should em(not) be declared within the command. No space +is allowed within `tt(${{)' and space or newline is required after +`tt({)var(param)tt(})'. The var(param) may include a subscript, and if, +after evaluating the expression, var(param) names an array, then array +expansion rules apply to the final substitution. + +A command enclosed in braces preceded by a dollar sign, and set off from +the braces by whitespace, like `tt(${ )...tt( })', is replaced by its +standard output. Like `tt(${|)...tt(})' and unlike +`tt($LPAR())...tt(RPAR())', the command executes in the current shell +context with function local behaviors and does not create a subshell. +Word splitting does not apply unless tt(SH_WORD_SPLIT) is set, but a +single trailing newline is stripped unless the substitution is enclosed +in double quotes. + +Note that because `tt(${|)...tt(})' and the two related substitutions +must be parsed at once as both string tokens and commands, all other +braces (`tt({)' or `tt(})') within the command either must be quoted, +or must appear in syntactically valid pairs, such as around complex +commands, function bodies, or parameter references. Furthermore, +comments are always recognized, even when tt(NO_INTERACTIVE_COMMENTS) +is in effect. + texinode(Arithmetic Expansion)(Brace Expansion)(Command Substitution)(Expansion) sect(Arithmetic Expansion) cindex(arithmetic expansion) @@ -1892,6 +2072,13 @@ 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) @@ -1956,34 +2143,24 @@ tt(/home/pws/perforce). In this simple case a static name for the directory would be just as effective. example(zsh_directory_name+LPAR()RPAR() { - emulate -L zsh - setopt extendedglob + emulate -L zsh -o extendedglob local -a match mbegin mend - if [[ $1 = d ]]; then - # turn the directory into a name - if [[ $2 = (#b)(/home/pws/perforce/)([^/]##)* ]]; then - typeset -ga reply - reply=(p:$match[2] $(( ${#match[1]} + ${#match[2]} )) ) - else - return 1 - fi - elif [[ $1 = n ]]; then - # turn the name into a directory - [[ $2 != (#b)p:(?*) ]] && return 1 - typeset -ga reply - reply=(/home/pws/perforce/$match[1]) - elif [[ $1 = c ]]; then - # complete names - local expl - local -a dirs - dirs=(/home/pws/perforce/*(/:t)) - dirs=(p:${^dirs}) - _wanted dynamic-dirs expl 'dynamic directory' compadd -S\] -a dirs - return - else - return 1 - fi - return 0 + local base=/home/pws/perforce + case $1 in + ( d ) # Turn the directory into a name. + [[ $2 == (#b)($base/)([^/]##)* ]] && + reply=( p:$match[2] $(( $#match[1] + $#match[2] )) ) + ;; + ( n ) # Turn the name into a directory. + [[ $2 == (#b)p:(?*) ]] && + reply=( $base/$match[1] ) + ;; + ( c ) # Complete names. + local -a dirs=( $base/*(/:t) ) + # Completion system populates $expl with flags for compadd. + compadd "$expl[@]" p:$^dirs + ;; + esac }) texinode(Static named directories)(`=' expansion)(Dynamic named directories)(Filename Expansion) @@ -2973,9 +3150,10 @@ so both can be used on the same glob expression; for example by writing ) enditem() -More than one of these lists can be combined, separated by commas. The -whole list matches if at least one of the sublists matches (they are -`or'ed, the qualifiers in the sublists are `and'ed). Some qualifiers, +Multiple consecutive qualifiers are joined into a list by implicit logical AND. +More than one of these lists can be combined using comma `tt(,)' as logical OR. +The whole list matches if at least one of the sublists matches. +Some qualifiers, however, affect all matches generated, independent of the sublist in which they are given. These are the qualifiers `tt(M)', `tt(T)', `tt(N)', `tt(D)', `tt(n)', `tt(o)', `tt(O)' and the subscripts given diff --git a/Doc/Zsh/files.yo b/Doc/Zsh/files.yo index 65debe044..c6c7da307 100644 --- a/Doc/Zsh/files.yo +++ b/Doc/Zsh/files.yo @@ -14,7 +14,7 @@ cindex(zshenv) Commands are first read from tt(zshenv()); this cannot be overridden. Subsequent behaviour is modified by the tt(RCS) and tt(GLOBAL_RCS) options; the former affects all startup files, while the -second only affects global startup files (those shown here with an +second only affects global startup files (those shown here with a path starting with a tt(/)). If one of the options is unset at any point, any subsequent startup file+LPAR()s+RPAR() of the corresponding diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo index 7edad7f23..7b71e34e9 100644 --- a/Doc/Zsh/func.yo +++ b/Doc/Zsh/func.yo @@ -13,6 +13,43 @@ Functions are executed like commands with the arguments passed as positional parameters. (See noderef(Command Execution).) +Parameters declared by any of the `tt(typeset)' family of commands +during the execution of a function become em(local) to the function +unless the `tt(-g)' option is used. This is the em(scope) of the +parameter, which extends dynamically to any other functions called by +the declaring function. In most cases, local parameters take the +place of any other parameter having the same name that was assigned or +declared in an earlier function scope. +(See noderef(Local Parameters).) + +A named parameter declared with the `tt(-n)' option to any of the +`tt(typeset)' commands becomes a reference to a parameter in scope at +the time of assignment to the named reference, which may be at a +different call level than the declaring function. For this reason, +it is good practice to declare a named reference as soon as the +referent parameter is in scope, and as early as possible in the +function if the reference is to a parameter in a calling scope. + +A typical use of named references is to pass the name +of the referent as a positional parameter. In this case it is +good practice to use the tt(-u) option to reference the calling +scope. For example, +ifzman() +example(pop+LPAR()RPAR() { + local -nu ref=$1 + local last=$ref[$#ref] + ref[$#ref]=LPAR()RPAR() + print -r -- $last +} +array=LPAR() a list of five values RPAR() +pop array) + +prints the word `tt(values)' and shortens `tt($array)' to +`tt(LPAR() a list of five RPAR())'. With tt(-nu), `tt(ref)' becomes a +reference to `tt(array)' in the caller. There are no local parameters in +tt(pop) at the time `tt(ref=$1)' is assigned, so in this example tt(-u) +could have been omitted, but it makes the intention clear. + Functions execute in the same process as the caller and share all files and present working directory with the @@ -276,7 +313,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 f8f4ada86..b80f9750c 100644 --- a/Doc/Zsh/grammar.yo +++ b/Doc/Zsh/grammar.yo @@ -100,14 +100,15 @@ More generally, a list can be seen as a set of any shell commands whatsoever, including the complex commands below; this is implied wherever the word `list' appears in later descriptions. For example, the commands in a shell function form a special sort of list. + texinode(Precommand Modifiers)(Complex Commands)(Simple Commands & Pipelines)(Shell Grammar) sect(Precommand Modifiers) cindex(precommand modifiers) cindex(modifiers, precommand) -A simple command may be preceded by a em(precommand modifier), -which will alter how the command is interpreted. These modifiers are -shell builtin commands with the exception of tt(nocorrect) which is -a reserved word. +With the exception of tt(nocorrect), which is a reserved word that +affects further parsing when it is found in command position, each +of the following builtin commands is a em(precommand modifier) which +may precede a simple command to alter how that command is interpreted. startitem() findex(-) @@ -158,8 +159,7 @@ before any parsing is done. It has no effect in non-interactive shells. ) findex(noglob) item(tt(noglob))( -Filename generation (globbing) is not performed on any of -the words. +Filename generation (globbing) is not performed on any of the words. ) enditem() texinode(Complex Commands)(Alternate Forms For Complex Commands)(Precommand Modifiers)(Shell Grammar) @@ -187,6 +187,12 @@ Expand the list of var(word)s, and set the parameter var(name) to each of them in turn, executing var(list) each time. If the `tt(in) var(word)' is omitted, use the positional parameters instead of the var(word)s. +If any var(name) has been declared as a named reference, +the corresponding var(word) is treated as the name of a +parameter and var(name) is made a reference to that. +Note that for the positional parameters, this treats the +value of each positional as parameter name rather than +creating a reference to the position. The var(term) consists of one or more newline or tt(;) which terminate the var(word)s, and are optional when the @@ -536,7 +542,7 @@ itemiz(Errors creating command or process substitutions) itemiz(Syntax errors in glob qualifiers) itemiz(File generation errors where not caught by the option tt(BAD_PATTERN)) itemiz(All bad patterns used for matching within case statements) -itemiz(File generation failures where not caused by tt(NO_MATCH) or +itemiz(File generation failures where not caused by tt(NOMATCH) or similar options) itemiz(All file generation errors where the pattern was used to create a multio) diff --git a/Doc/Zsh/mod_hlgroup.yo b/Doc/Zsh/mod_hlgroup.yo new file mode 100644 index 000000000..efe8934a1 --- /dev/null +++ b/Doc/Zsh/mod_hlgroup.yo @@ -0,0 +1,25 @@ +COMMENT(!MOD!zsh/hlgroup +Alternative views of highlighting groups +!MOD!) +The tt(zsh/hlgroup) module defines special parameters that represent +highlighting groups in different forms to ease the use of the groups when +configuring other tools. + +In each case, these are readonly associative arrays where accessing elements +uses values from the underlying tt(.zle.hlgroups) variable. + +startitem() +vindex(.zle.esc) +item(tt(.zle.esc))( +This associative array contains the literal escape sequences used to apply the +highlighting for each group. An example use would be when setting the +tt(LESS_TERMCAP_xx) environment variables for the tt(less) pager. +) +vindex(.zle.sgr) +item(tt(.zle.sgr))( +Where highlighting makes use of CSI escape sequences, this parameter contains +the "Select Graphic Rendition" number sequence. This is useful with, for +example the tt(GREP_COLORS) and tt(LSCOLORS) environment variables and the +tt(list-colors) style. +) +enditem() diff --git a/Doc/Zsh/mod_ksh93.yo b/Doc/Zsh/mod_ksh93.yo new file mode 100644 index 000000000..7508758aa --- /dev/null +++ b/Doc/Zsh/mod_ksh93.yo @@ -0,0 +1,243 @@ +COMMENT(!MOD!zsh/ksh93 +Extended ksh93 compatibility for "emulate ksh" +!MOD!) +cindex(ksh93) +The tt(zsh/ksh93) module provides one builtin and several parameters to +improve compatibility with ksh93. As of this writing, several ksh93 +features are still missing. + +subsect(Ksh Builtins) +The single builtin provided by this module is: + +startitem() +findex(nameref) +cindex(named references, creating) +item(tt(nameref) [ tt(-gur) ] var(pname)[tt(=)var(rname)])( +Equivalent to tt(typeset -n )var(pname)tt(=)var(rname) + +However, tt(nameref) is a builtin command rather than a reserved word, +so when var(rname) uses subscript syntax it must be quoted against +globbing. Subscripts in referenced parameters are not supported in +ksh93, so this is not a significant compatibility issue. +) +enditem() + +subsect(Ksh Parameters) +cindex(parameters, ksh) +Parameters supplied by this module that are marked with `<K>' below +are available only when ksh emulation is active before entry to the +shell function, that is, `tt(emulate ksh)' locally to a function does +not populate these parameters for that function. + +startitem() +vindex(.sh.command) +item(tt(.sh.command))( +A named reference to `tt(ZSH_DEBUG_CMD)' +) +vindex(.sh.edchar) +item(tt(.sh.edchar) <K>)( +In a ZLE widget, equivalent to the `tt(KEYS)' special parameter. In a +future release, assignments to this parameter will affect the input +stream seen by ZLE. +) +vindex(.sh.edcol) +item(tt(.sh.edcol))( +A named reference to the ZLE special parameter `tt(CURSOR)'. +) +vindex(.sh.edmode) +item(tt(.sh.edmode) <K>)( +In a ZLE widget, this parameter has the value tt(ESC) (tt($'\e')) if the +tt(VI) option is set and the `tt(main)' keymap is selected. This is +intended for use with vi-mode key bindings (`tt(bindkey -v)'). In a +future revision, assigning `tt(.sh.edchar=${.sh.edmode})' is expected +to initiate `tt(vicmd)' mode when `tt(viins)' is active, and do +nothing when `tt(vicmd)' is already active. +) +vindex(.sh.edtext) +item(tt(.sh.edtext))( +A named reference to the `tt(BUFFER)' special ZLE parameter. +) +vindex(.sh.file) +item(tt(.sh.file))( +A named reference to the `tt(ZSH_SCRIPT)' parameter. +) +vindex(.sh.fun) +item(tt(.sh.fun) <K>)( +In a shell function, the function's name. Usually the same as `tt($0)', +but not affected by tt(POSIX_ARGZERO) or tt(FUNCTION_ARGZERO) options. +) +vindex(.sh.level) +item(tt(.sh.level) <K>)( +In a shell function, initially set to the depth of the call stack. This +may be assigned to change the apparent depth. However, such assignment +does not affect the scope of local parameters. +) +vindex(.sh.lineno) +item(tt(.sh.lineno))( +A named reference to the `tt(LINENO)' special parameter. +) +vindex(.sh.match) +item(tt(.sh.match))( +An array equivalent to the `tt(match)' parameter as assigned by the +`tt(LPAR()#b)tt(RPAR())' extended globbing flag. When the +tt(KSH_ARRAYS) option is set, `tt(${.sh.match[0]})' gives the value of +the `tt(MATCH)' parameter as set by the `tt(LPAR()#m)tt(RPAR())' extended +globbing flag. Currently, the tt(EXTENDED_GLOB) option must be enabled +and those flags must be explicitly used in a pattern in order for these +values of `tt(.sh.match)' to be set. +) +vindex(.sh.name) +item(tt(.sh.name) <K>)( +When the `tt(vared)' command is used, this parameter may be used in +user-defined ZLE widgets to get the name of the variable being edited. +A future release is expected to use this parameter in the implementation +of "discipline functions". +) +vindex(.sh.subscript) +item(tt(.sh.subscript) <K>)( +When `tt(vared)' has been used on an array element, this parameter holds +the array index (either a number, or an associative array key). +) +vindex(.sh.subshell) +item(tt(.sh.subshell))( +A named reference to the `tt(ZSH_SUBSHELL)' parameter. +) +vindex(.sh.value) +item(tt(.sh.value) <K>)( +In `tt(vared)' this is a named reference to the ZLE special `tt(BUFFER)'. +A future release is expected to use this parameter in the implementation +of "discipline functions". +) +vindex(.sh.version) +item(tt(.sh.version))( +A named reference to `tt(ZSH_PATCHLEVEL)'. +) +enditem() + +subsect(Future Compatibility) + +The following features of ksh93 are not currently supported but may be +available in a future release. + +startitem() +item(tt(namespace )var(ident)tt( { )var(list)tt( }))( +This reserved word executes the current shell compound command +tt({ )var(list)tt( }), with the special behavior that all functions +and parameters `var(name)' declared within var(list) are implicitly +prefixed to become `tt(.)var(ident)tt(.)var(name)', and similarly any +reference to a function or parameter `var(name)' is searched for as +`tt(.)var(ident)tt(.)var(name)' before falling back to `var(name)'. + +em(THIS FEATURE IS NOT YET IMPLEMENTED.) +) +item(tt(.sh.math) <K>)( +This parameter is more accurately considered a namespace. A function +defintion of the form +ifzman() +indent(tt(function .sh.math.)var(name)tt( )var(ident)tt( ... { )var(list)tt( })) + +is equivalent to the native zsh definition +ifzman() +example(tt(function )var(name)tt( {) +tt( local )var(ident)tt(=$1 ...) +tt( )var(list) +tt(}) +tt(functions -M )var(name)tt( 1 3)) +ifzman() +Up to 3 var(ident) arguments, interpreted as floating point numbers, +may be provided for a function defined with tt(.sh.math) in this way. +The names (but not definitions) of all such functions are available +via tt(${.sh.math[@]}). + +em(THIS FEATURE IS NOT YET IMPLEMENTED.) +) +item(tt(var(name)tt(.get)))( +A shell function having this name, if defined, is invoked whenever the +parameter tt(${)var(name)tt(}) is referenced, including by commands +such as `tt(typeset -p)'. If the special variable `tt(.sh.value)' is +assigned by the function, that value is substituted instead of the +true value of var(name). This does not change the value of var(name), +but there is no way to access the actual value without first removing +the function. + +Additionally, an explicit reference to tt(${)var(name)tt(.get}) +calls the function var(name)tt(.get) even if there is no parameter +`var(name)' and substitutes the standard output of the function. + +em(THIS FEATURE IS NOT YET IMPLEMENTED.) +) +xitem(tt(var(name)tt(.set))) +item(tt(var(name)tt(.append)))( +Shell functions having these names are invoked when the parameter +var(name) is assigned or (for array types) has a new field appended. +The function may change the result of the operation by assigning to +the `tt(.sh.value)' special parameter, or block the change by +unsetting `tt(.sh.value)'. + +Explicit reference to tt(${)var(name)tt(.set}) or tt(${)var(name)tt(.append}) +substitutes the standard output of the function. + +em(THIS FEATURE IS NOT YET IMPLEMENTED.) +) +item(tt(var(name)tt(.unset)))( +When a function of this name is defined, it is called whenever the +parameter var(name) would be unset. The function must explicitly +`tt(unset )var(name)', otherwise the variable remains set. + +em(THIS FEATURE IS NOT YET IMPLEMENTED.) +) +item(tt(typeset -C )var(name)[tt(=)var(values)tt( ...)])( +Creates a em(compound variable). + +em(THIS FEATURE IS NOT YET IMPLEMENTED, and the syntax of var(values) +is unlikely to be fully ksh compatible.) +) +enditem() + +subsect(Other Differences) + +The following features of ksh93 are not currently supported and there are +no plans to implement them. + +startitem() +item(var(pathdir)tt(/.paths))( +Each directory var(pathdir) in the tt(PATH) parameter may contain a +text file `tt(.paths)' which may define additional directories to +be searched for function definitions (tt(FPATH)), external executables +(tt(PATH)), and plugin files (similar to tt(MODULE_PATH)). + +em(THIS FEATURE IS UNLIKELY EVER TO BE IMPLEMENTED.) +) +item(tt(builtin -f )var(file))( +Installs a new shell builtin command dynamically linked from var(file), +where var(file) is found by a path search and the base name of the file +is the name of the builtin to be added. + +Similar to `tt(zmodload -F zsh/)var(file)tt( +b:)var(file)'. + +em(THIS FEATURE IS UNLIKELY EVER TO BE IMPLEMENTED.) +) +item(tt(typeset -H )var(name)[tt(=)var(value)])( +Used for em(host-name file mapping) on some operating systems. + +em(THIS FEATURE IS UNLIKELY EVER TO BE IMPLEMENTED.) +) +item(tt(typeset ){tt(PLUS()|-)}tt(M )var(mapname)tt( )var(name)[tt(=)var(value)])( +Declares a character translation var(mapname) for values assigned to var(name). +) +xitem(tt(typeset -S)) +xitem(tt(typeset -T ) [tt(-f)] [ var(tname)tt(=LPAR())var(values)tt(RPAR()) ]) +item(tt(typeset -h )var(str))( +Used to define em(typed variables) and properties of their em(sub-variables). +The tt(-T) and tt(-h) options conflict with existing zsh usage. +) +item(tt(typeset -X )var(name)[tt(=)var(value)])( +Declares a floating-point variable displayed in hexadecimal format. +) +item(tt(typeset -b )var(name)[tt(=)var(value)])( +Declares a parameter stored in em(base64) format. +) +item(tt(typeset -m )var(newname)tt(=)var(oldname))( +em(Moves) var(oldname) to var(newname). Conflicts with native zsh usage. +) +enditem() diff --git a/Doc/Zsh/mod_parameter.yo b/Doc/Zsh/mod_parameter.yo index 2e3011e44..3defef2b7 100644 --- a/Doc/Zsh/mod_parameter.yo +++ b/Doc/Zsh/mod_parameter.yo @@ -125,7 +125,16 @@ zmanref(zshexpn) ifnzman(\ noderef(Parameter Expansion) )\ -. +. The value may also be `tt(undefined)' indicating a parameter that +may be autoloaded from a module but has not yet been referenced. +When the key is the name of a named reference, the value is +`tt(nameref-)' prepended to the type of the referenced parameter, +for example +ifzman() +example(tt(% typeset -n parms=parameters) +tt(% print -r ${parameters[parms]}) +tt(nameref-association-readonly-hide-hideval-special)) + Setting or unsetting keys in this array is not possible. ) vindex(modules) @@ -165,6 +174,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 +184,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 +202,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_pcre.yo b/Doc/Zsh/mod_pcre.yo index c2817f519..41fab4475 100644 --- a/Doc/Zsh/mod_pcre.yo +++ b/Doc/Zsh/mod_pcre.yo @@ -20,12 +20,12 @@ including those that indicate newline. ) findex(pcre_study) item(tt(pcre_study))( -Studies the previously-compiled PCRE which may result in faster -matching. +Requests JIT compilation for the previously-compiled PCRE which +may result in faster matching. ) findex(pcre_match) item(tt(pcre_match) [ tt(-v) var(var) ] [ tt(-a) var(arr) ] \ -[ tt(-n) var(offset) ] [ tt(-b) ] var(string))( +[ tt(-A) var(assoc) ] [ tt(-n) var(offset) ] [ tt(-bd) ] var(string))( Returns successfully if tt(string) matches the previously-compiled PCRE. @@ -36,7 +36,9 @@ substrings, unless the tt(-a) option is given, in which case it will set the array var(arr). Similarly, the variable tt(MATCH) will be set to the entire matched portion of the string, unless the tt(-v) option is given, in which case the variable -var(var) will be set. +var(var) will be set. Furthermore, any named captures will +be stored in the associative array tt(.pcre.match) unless an +alternative is given with tt(-A). No variables are altered if there is no successful match. A tt(-n) option starts searching for a match from the byte var(offset) position in var(string). If the tt(-b) option is given, @@ -67,6 +69,15 @@ print -l $accum) ) enditem() +If the regular expression contains callouts, these are executed as shell code. +During the execution of the callout, the string the regular expression is +matching against is available in the parameter tt(.pcre.subject). If there is a +non-zero return status from the shell code, the callout does not match. + +The option tt(-d) uses the alternative breadth-first DFA search algorithm of +pcre. This sets tt(match), or the array given with tt(-a), to all the matches +found from the same start point in the subject. + The tt(zsh/pcre) module makes available the following test condition: startitem() diff --git a/Doc/Zsh/mod_private.yo b/Doc/Zsh/mod_private.yo index 184fa2be8..24c099f38 100644 --- a/Doc/Zsh/mod_private.yo +++ b/Doc/Zsh/mod_private.yo @@ -16,9 +16,10 @@ 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)'. +The `tt(-)tt(p)' option is presently disabled because the state of +private parameters cannot reliably be reloaded. When `tt(typeset -)tt(p)' +outputs a private parameter, it is treated as a local with the +`tt(-)tt(h)' (hide) option enabled. 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 @@ -84,6 +85,14 @@ 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.) +itemiz(Current shell command substitutions such as `tt(${|)...tt(})', +`tt(${|)var(var)tt(|)...tt(})' and `tt(${ )...tt( })' may read and assign +private parameters from the enclosing function.) +itemiz(Declaring a private parameter in a current shell command substitution +limits that parameter to the scope of the command substitution, just as if +the parameter were declared in a function. This also prevents access by +any enclosed current shell command substitutions, but other substitutions +may use the private parameter because those have the same calling scope.) enditemize() Note that this differs from the static scope defined by compiled languages 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 399b6fe03..e25201faa 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 ) @@ -71,6 +74,11 @@ truncate file to size 0 ) enditem() +A return status of 0 indicates the descriptor was successfully opened, +otherwise an error message is printed, and 1 is returned for an error +in the parameters to the command, or 2 is returned for a system error. +The parameter tt(ERRNO) is nonzero for system errors. + To close the file, use one of the following: example(tt(exec {)var(fd)tt(}<&-) @@ -120,11 +128,11 @@ error for which a message is printed to standard error. ) item(2)( There was an error on the read, or on polling the input file descriptor -for a timeout. The parameter tt(ERRNO) gives the error. +for a timeout. The parameter tt(ERRNO) identifies the error. ) item(3)( Data were successfully read, but there was an error writing them -to var(outfd). The parameter tt(ERRNO) gives the error. +to var(outfd). The parameter tt(ERRNO) identifies the error. ) item(4)( The attempt to read timed out. Note this does not set tt(ERRNO) as this @@ -144,6 +152,11 @@ expression. The tt(-u) option allows the file descriptor to be specified. By default the offset is specified relative to the start or the file but, with the tt(-w) option, it is possible to specify that the offset should be relative to the current position or the end of the file. + +The return status may be 0 for success, 1 for an error in the parameters +to the command, or 2 for an error on the seek; no error message is +printed in the last case, but the parameter tt(ERRNO) reflects +the error that occurred. ) item(tt(syswrite) [ tt(-c) var(countvar) ] [ tt(-o) var(outfd) ] var(data))( The data (a single string of bytes) are written to the file descriptor @@ -163,7 +176,7 @@ returning early. The return status may be 0 for success, 1 for an error in the parameters 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 +printed in the last case, but the parameter tt(ERRNO) reflects the error that occurred. ) xitem(tt(zsystem flock) [ tt(-t) var(timeout) ] [ tt(-i) var(interval) ] [ tt(-f) var(var) ] [tt(-er)] var(file)) diff --git a/Doc/Zsh/mod_watch.yo b/Doc/Zsh/mod_watch.yo index 4eea89e23..d97a41d13 100644 --- a/Doc/Zsh/mod_watch.yo +++ b/Doc/Zsh/mod_watch.yo @@ -65,6 +65,12 @@ 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. ) diff --git a/Doc/Zsh/mod_zselect.yo b/Doc/Zsh/mod_zselect.yo index faf59c165..42287f116 100644 --- a/Doc/Zsh/mod_zselect.yo +++ b/Doc/Zsh/mod_zselect.yo @@ -13,7 +13,7 @@ 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 system's -documentation for manref(select)(3). Note there is no connection with the +documentation for manref(select)(2). Note there is no connection with the shell builtin of the same name. Arguments and options may be intermingled in any order. Non-option diff --git a/Doc/Zsh/mod_zutil.yo b/Doc/Zsh/mod_zutil.yo index 3cf9e5028..9946618d6 100644 --- a/Doc/Zsh/mod_zutil.yo +++ b/Doc/Zsh/mod_zutil.yo @@ -11,6 +11,7 @@ xitem(tt(zstyle) [ tt(-L) [ var(metapattern) [ var(style) ] ] ]) xitem(tt(zstyle) [ tt(-e) | tt(-) | tt(-)tt(-) ] var(pattern) var(style) var(string) ...) xitem(tt(zstyle -d) [ var(pattern) [ var(style) ... ] ]) xitem(tt(zstyle -g) var(name) [ var(pattern) [ var(style) ] ]) +xitem(tt(zstyle -q) var(context) var(style)) xitem(tt(zstyle -){tt(a)|tt(b)|tt(s)} var(context) var(style) var(name) [ var(sep) ]) xitem(tt(zstyle -){tt(T)|tt(t)} var(context) var(style) [ var(string) ... ]) item(tt(zstyle -m) var(context) var(style) var(pattern))( @@ -105,6 +106,12 @@ enditem() The other forms can be used to look up or test styles for a given context. startitem() +item(tt(zstyle -q) var(context) var(style))( +Return tt(0) if var(style) is defined in var(context). This does not +evaluate expressions defined by tt(zstyle -e) and does not examine any +values set by var(style). The expected use is to test whether a style +has been defined for var(context) before asserting a new style. +) item(tt(zstyle -s) var(context) var(style) var(name) [ var(sep) ])( The parameter var(name) is set to the value of the style interpreted as a string. If the value contains several strings they are concatenated with diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo index cf4600769..c3af8dd33 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) @@ -1211,6 +1214,9 @@ Note that, when the tt(HASH_LIST_ALL) option is not set or when some directories in the path are not readable, this may falsely report spelling errors the first time some commands are used. +Refer to the shell variable tt(SPROMPT) for an explanation of the +`tt([nyae])' (no/yes/abort/edit) prompt that is offered. + The shell variable tt(CORRECT_IGNORE) may be set to a pattern to match words that will never be offered as corrections. ) @@ -1219,7 +1225,10 @@ pindex(NO_CORRECT_ALL) pindex(CORRECTALL) pindex(NOCORRECTALL) item(tt(CORRECT_ALL) (tt(-O)))( -Try to correct the spelling of all arguments in a line. +Try to correct the spelling of all arguments in a line, in order from +left to right, treating each as a file name. Answering `tt(a)' or +`tt(e)' at any prompt stops all corrections, otherwise every correction +is prompted for. The shell variable tt(CORRECT_IGNORE_FILE) may be set to a pattern to match file names that will never be offered as corrections. @@ -1720,27 +1729,38 @@ pindex(NOERREXIT) cindex(exit status, trapping) item(tt(ERR_EXIT) (tt(-e), ksh: tt(-e)))( If a command has a non-zero exit status, execute the tt(ZERR) -trap, if set, and exit. This is disabled while running initialization -scripts. - -The behaviour is also disabled inside tt(DEBUG) traps. In this -case the option is handled specially: it is unset on entry to -the trap. If the option tt(DEBUG_BEFORE_CMD) is set, -as it is by default, and the option tt(ERR_EXIT) is found to have been set -on exit, then the command for which the tt(DEBUG) trap is being executed is -skipped. The option is restored after the trap exits. - -Non-zero status in a command list containing tt(&&) or tt(||) is ignored -for commands not at the end of the list. Hence - -example(false && true) - -does not trigger exit. +trap, if set, and exit. + +The option is ignored when executing the commands following tt(while), +tt(until), tt(if), or tt(elif), a pipeline beginning with tt(!), or +any command other than the last in command list containing tt(&&) or +tt(||). Hence neither `tt(if foo; then true; fi)', nor `tt(foo && +true)' trigger exit when tt(foo) returns with a non-zero exit status. +Note that if tt(foo) is a function, the option is also ignored during +its whole execution. + +The option is also ignored when executing a complex command (tt(if), +tt(for), tt(while), tt(until), tt(repeat), tt(case), tt(select), +tt(always), or a list in braces) if its exit status comes from a +command executed while the option is ignored. Hence, the tt(if) +command in `tt(if true; then false && true; fi)' does not trigger +exit. + +Finally, the option is also ignored while running initialization +scripts and inside tt(DEBUG) traps. In the latter case, the option is +handled specially: it is unset on entry to the trap. If the option +tt(DEBUG_BEFORE_CMD) is set, as it is by default, and the option +tt(ERR_EXIT) is found to have been set on exit, then the command for +which the tt(DEBUG) trap is being executed is skipped. The option is +restored after the trap exits. Exiting due to tt(ERR_EXIT) has certain interactions with asynchronous jobs noted in ifzman(the section JOBS in zmanref(zshmisc))\ ifnzman(noderef(Jobs & Signals)). + +Note this behaviour is not disabled in interactive shells --- +a non-zero status on the command line causes the shell to exit. ) pindex(ERR_RETURN) pindex(NO_ERR_RETURN) @@ -1749,26 +1769,29 @@ pindex(NOERRRETURN) cindex(function return, on error) cindex(return from function, on error) item(tt(ERR_RETURN))( -If a command has a non-zero exit status, return immediately from the -enclosing function. The logic is similar to that for tt(ERR_EXIT), -except that an implicit tt(return) statement is executed instead of an -tt(exit). This will trigger an exit at the outermost level of a -non-interactive script. - -Normally this option inherits the behaviour of tt(ERR_EXIT) that -code followed by `tt(&&)' `tt(||)' does not trigger a return. Hence -in the following: - -example(summit || true) -no return is forced as the combined effect always has a zero return -status. - -Note. however, that if tt(summit) in the above example is itself a -function, code inside it is considered separately: it may force a return -from tt(summit) (assuming the option remains set within tt(summit)), but -not from the enclosing context. This behaviour is different from -tt(ERR_EXIT) which is unaffected by function scope. +If a command has a non-zero exit status, return immediately from the +enclosing function. Except as explained below, an implicit tt(return) +statement is executed following the same logic described for +tt(ERR_EXIT). This will trigger an exit at the outermost level of a +non-interactive script. At the top level of an interactive shell, it +will trigger a return to the command prompt; in other words, the +sequence of commands typed by the user may be thought of as a function +for this purpose. + +Unlike for tt(ERR_EXIT), when a function is called while the option is +being ignored, the option is NOT ignored during the execution of the +function. Hence, if tt(foo) in `tt(foo && true)' is a function, code +inside it is considered separately: it may force a return from tt(foo) +(assuming the option remains set within tt(foo)). + +Like for tt(ERR_EXIT), the option is ignored inside tt(DEBUG) traps +but it's not unset on entry to the trap and setting or unsetting it +inside the trap has no special effect. + +If tt(ERR_RETURN) and tt(ERR_EXIT) are both set, it may happen that +both exit and return should be triggered. In that case only exit is +triggered. ) pindex(EVAL_LINENO) pindex(NO_EVAL_LINENO) @@ -1881,6 +1904,11 @@ fn2)var(...)tt(LPAR()RPAR())'; if the option is not set, this causes a parse error. Definition of multiple functions with the tt(function) keyword is always allowed. Multiple function definitions are not often used and can cause obscure errors. + +Note that no error is raised if multiple functions are defined as a +result of a set of names that were originally read as a single word on +the command line, for example `tt(TRAP{INT,QUIT})'. Although there are +no plans to change this behaviour at present, it is not guaranteed. ) pindex(MULTIOS) pindex(NO_MULTIOS) @@ -1949,7 +1977,7 @@ 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 +value is explicitly assigned to it, either in the `tt(typeset)' command itself or as a later assignment statement. ) pindex(VERBOSE) @@ -2542,10 +2570,12 @@ pindex(NO_EMACS) pindex(NOEMACS) item(tt(EMACS))( If ZLE is loaded, turning on this option has the equivalent effect -of `tt(bindkey -e)'. In addition, the VI option is unset. +of `tt(bindkey -e)'. In addition, the tt(VI) option is unset. Turning it off has no effect. The option setting is -not guaranteed to reflect the current keymap. This option is -provided for compatibility; tt(bindkey) is the recommended interface. +not guaranteed to reflect the current keymap, and the tt(LOCALOPTIONS) +option does not work correctly. This option is provided only for +compatibility, and its use is highly discouraged. tt(bindkey) is the +recommended interface. ) pindex(OVERSTRIKE) pindex(NO_OVERSTRIKE) @@ -2574,10 +2604,12 @@ pindex(NO_VI) pindex(NOVI) item(tt(VI))( If ZLE is loaded, turning on this option has the equivalent effect -of `tt(bindkey -v)'. In addition, the EMACS option is unset. +of `tt(bindkey -v)'. In addition, the tt(EMACS) option is unset. Turning it off has no effect. The option setting is -not guaranteed to reflect the current keymap. This option is -provided for compatibility; tt(bindkey) is the recommended interface. +not guaranteed to reflect the current keymap, and the tt(LOCALOPTIONS) +option does not work correctly. This option is provided only for +compatibility, and its use is highly discouraged. tt(bindkey) is the +recommended interface. ) pindex(ZLE) pindex(NO_ZLE) diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo index 6b52d3b1c..02ce796a9 100644 --- a/Doc/Zsh/params.yo +++ b/Doc/Zsh/params.yo @@ -52,6 +52,20 @@ cindex(assignment) ifzman() indent(var(name)tt(=)var(value)) +cindex(namespace) +The var(name) in an assignment may optionally include a em(namespace) +prefix: +ifzman() +indent(tt(.)var(namespace)tt(.)var(parameter)tt(=)var(value)) + +Namespaces have no special meaning to the shell except that parameters +with a `tt(.)' prefix are not listed by the `tt(set)' builtin, nor +shown by the `tt(typeset)' builtin unless explicitly named or the +`tt(-m)' option is used. They provide a convenient way to group +related variables. Note that, for support of possible future features, +the first `tt(.)' is optional, but omitting it is discouraged. Unlike +ksh, a namespace need not be declared before it is referenced. + In scalar assignment, var(value) is expanded as a single string, in which the elements of arrays are joined together; filename expansion is not performed unless the option tt(GLOB_ASSIGN) is set. @@ -70,7 +84,8 @@ change its type to integer or float, and with tt(GLOB_ASSIGN) assigning a pattern to a variable may change its type to an array. To reference the value of a parameter, write `tt($)var(name)' or -`tt(${)var(name)tt(})'. See +`tt(${)var(name)tt(})'. The latter form is required when var(name) +includes a namespace prefix. See ifzman(em(Parameter Expansion) in zmanref(zshexpn))\ ifnzman(noderef(Parameter Expansion)) for complete details. That section also explains the effect @@ -80,10 +95,13 @@ startmenu() menu(Array Parameters) menu(Positional Parameters) menu(Local Parameters) +menu(Named References) menu(Parameters Set By The Shell) menu(Parameters Used By The Shell) endmenu() texinode(Array Parameters)(Positional Parameters)()(Parameters) +cindex(array parameters) +cindex(parameters, array) sect(Array Parameters) To assign an array value, write one of: findex(set, use of) @@ -566,6 +584,8 @@ entire second parameter concatenated with the filename generation pattern `tt([3,5])'. texinode(Positional Parameters)(Local Parameters)(Array Parameters)(Parameters) +cindex(positional parameters) +cindex(parameters, positional) sect(Positional Parameters) The positional parameters provide access to the command-line arguments of a shell function, shell script, or the shell itself; see @@ -592,7 +612,9 @@ array assignment of the form `var(n)tt(=LPAR())var(value) ...tt(RPAR())' is allowed, and has the effect of shifting all the values at positions greater than var(n) by as many positions as necessary to accommodate the new values. -texinode(Local Parameters)(Parameters Set By The Shell)(Positional Parameters)(Parameters) +texinode(Local Parameters)(Named References)(Positional Parameters)(Parameters) +cindex(local parameters) +cindex(parameters, local) sect(Local Parameters) Shell function executions delimit scopes for shell parameters. (Parameters are dynamically scoped.) The tt(typeset) builtin, and its @@ -626,7 +648,53 @@ find the programs in tt(/new/directory) inside a function. Note that the restriction in older versions of zsh that local parameters were never exported has been removed. -texinode(Parameters Set By The Shell)(Parameters Used By The Shell)(Local Parameters)(Parameters) +texinode(Named References)(Parameters Set By The Shell)(Local Parameters)(Parameters) +cindex(named references) +cindex(references, named) +sect(Named References) +Zsh supports two different mechanisms for indirect parameter referencing: +ifzman() +example(tt(typeset )var(name)tt(=)var(rname) +tt(print -r -- ${LPAR()P)tt(RPAR())var(name)tt(})) +ifzman() +example(tt(typeset -n )var(pname)tt(=)var(rname) +tt(print -r -- ${)var(pname)tt(})) + +The `tt((P))' flag method is older and should be used when a script +needs to be backwards-compatible. This is described fully in +the Parameter Expansion Flags section of +ifzman(zmanref(zshexpn))ifnzman(noderef(Parameter Expansion)). Zsh +versions em(greater than) tt(5.9.0) are required for `tt(typeset -n)'. +This manual was generated with Zsh tt(version()). + +When a em(named reference) is created with `tt(typeset -n)', all uses +of var(pname) in assignments and expansions instead assign to or +expand var(rname). This also applies to `tt(unset )var(pname)' and to +most subsequent uses of `tt(typeset)' with the exceptions of declaring +a local in a called function, or updating a current-scope parameter with +`tt(typeset -n)' or `tt(typeset +n)'. Thus to remove a named reference, +use either `tt(unset -n )var(pname)' (preferred) or one of: +ifzman() +example(tt(typeset -n )var(pname=) +tt(typeset +n )var(pname)) + +followed by +ifzman() +indent(tt(unset )var(pname)) + +An empty reference such as one of +ifzman() +example(tt(typeset -n )var(pname) +tt(typeset -n )var(pname)tt(=) +tt(typeset -n )var(pname)tt(="")) + +acts as a placeholder. The first non-empty assignment to var(pname) +initializes the reference, and subsequently any expansions of, or +assignments to, var(pname) act on the referenced parameter. This +is explained in the Named References section of +ifzman(zmanref(zshexpn))ifnzman(noderef(Parameter Expansion)). + +texinode(Parameters Set By The Shell)(Parameters Used By The Shell)(Named References)(Parameters) sect(Parameters Set By The Shell) In the parameter lists that follow, the mark `<S>' indicates that the parameter is special. `<Z>' indicates that the parameter does not exist @@ -681,9 +749,13 @@ vindex(argv) item(tt(argv) <S> <Z>)( Same as tt(*). Assigning to tt(argv) changes the local positional parameters, but tt(argv) is em(not) itself a local parameter. -Deleting tt(argv) with tt(unset) in any function deletes it everywhere, -although only the innermost positional parameter array is deleted (so -tt(*) and tt(@) in other scopes are not affected). +Deleting tt(argv) with tt(unset) in any function deletes it everywhere. +This can be avoided by declaring `tt(local +h argv)' before unsetting. +Even when not so declared, only the innermost positional parameter +array is deleted (so tt(*) and tt(@) in other scopes are not affected). + +A named reference to tt(argv) em(does not) permit a called function to +access the positional parameters of its caller. ) vindex(@) item(tt(@) <S>)( @@ -712,7 +784,10 @@ last pipeline. ) vindex(_) item(tt(_) <S>)( -The last argument of the previous command. +Initially, if tt(_) exists in the environment, then this parameter is set to +its value. This value may be the full pathname of the current zsh +executable or the script command file. +Later, this parameter is set to the last argument of the previous command. Also, this parameter is set in the environment of every command executed to the full pathname of the command. ) @@ -750,6 +825,9 @@ 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 allows the number to be turned into a name or message. + +To use this parameter, it must first be assigned a value (typically +0 (zero)). It is initially unset for scripting compatibility. ) vindex(FUNCNEST) item(tt(FUNCNEST) <S>)( @@ -876,7 +954,10 @@ has index 1, the signals are offset by 1 from the signal number used by the operating system. For example, on typical Unix-like systems tt(HUP) is signal number 1, but is referred to as tt($signals[2]). This is because of tt(EXIT) at position 1 in the array, which is used -internally by zsh but is not known to the operating system. +internally by zsh but is not known to the operating system. On many systems +there is a block of reserved or unused signal numbers before the POSIX +real-time signals so the array index can't be used as an accurate indicator +of their signal number. Use, for example, tt(kill -l SIGRTMIN) instead. ) vindex(TRY_BLOCK_ERROR) item(tt(TRY_BLOCK_ERROR) <S>)( @@ -950,11 +1031,12 @@ Code specified by the tt(-c) option to the command line that invoked the shell. ) item(tt(cmdsubst))( -Command substitution using the tt(`)var(...)tt(`) or -tt($+LPAR())var(...)tt(RPAR()) construct. +Command substitution using of the tt(`)var(...)tt(`), +tt($+LPAR())var(...)tt(RPAR()),tt(${{)var(name)tt(}) var(...)tt(}), +tt(${|)var(...)tt(}), or tt(${ )var(...)tt( }) constructs. ) item(tt(equalsubst))( -File substitution using the tt(=+LPAR())var(...)tt(RPAR()) construct. +The tt(=+LPAR())var(...)tt(RPAR()) form of process substitution. ) item(tt(eval))( Code executed by the tt(eval) builtin. @@ -982,13 +1064,13 @@ item(tt(globsort))( Code executed to order files by the tt(o) glob qualifier. ) item(tt(insubst))( -File substitution using the tt(<LPAR())var(...)tt(RPAR()) construct. +The tt(<LPAR())var(...)tt(RPAR()) form of process substitution. ) item(tt(loadautofunc))( Code read directly from a file to define an autoloaded function. ) item(tt(outsubst))( -File substitution using the tt(>LPAR())var(...)tt(RPAR()) construct. +The tt(>LPAR())var(...)tt(RPAR()) form of process substitution. ) item(tt(sched))( Code executed by the tt(sched) builtin. @@ -1039,6 +1121,10 @@ item(tt(ZSH_EXECUTION_STRING))( If the shell was started with the option tt(-c), this contains the argument passed to the option. Otherwise it is not set. ) +vindex(ZSH_EXEPATH) +item(tt(ZSH_EXEPATH))( +Full pathname of the executable file of the current zsh process. +) vindex(ZSH_NAME) item(tt(ZSH_NAME))( Expands to the basename of the command used to invoke this instance @@ -1248,15 +1334,18 @@ Internal field separators (by default space, tab, newline and NUL), that are used to separate words which result from command or parameter expansion and words read by the tt(read) builtin. Any characters from the set space, tab and -newline that appear in the IFS are called em(IFS white space). +newline that appear in the tt(IFS) are called em(IFS white space). One or more IFS white space characters or one non-IFS white space character together with any adjacent IFS white space character delimit a field. If an IFS white space character appears twice consecutively -in the IFS, this character is treated as if it were not an IFS white +in the tt(IFS), this character is treated as if it were not an IFS white space character. If the parameter is unset, the default is used. Note this has a different effect from setting the parameter to an empty string. + +If tt(MULTIBYTE) option is on and tt(IFS) contains invalid characters in +the current locale, it is reset to the default. ) vindex(KEYBOARD_HACK) item(tt(KEYBOARD_HACK))( @@ -1411,6 +1500,7 @@ An array (colon-separated list) of directories to search for commands. When this parameter is set, each directory is scanned and all files found are put in a hash table. +Directories named by relative path are not scanned for hashing. ) vindex(POSTEDIT) item(tt(POSTEDIT) <S>)( @@ -1550,9 +1640,13 @@ All other prompt escapes are also allowed. The actions available at the prompt are tt([nyae]): startsitem() -sitem(tt(n) +LPAR()`no'+RPAR() +LPAR()default+RPAR())(Discard the correction and run the command.) -sitem(tt(y) +LPAR()`yes'+RPAR())(Make the correction and run the command.) -sitem(tt(a) +LPAR()`abort'+RPAR())(Discard the entire command line without running it.) +sitem(tt(n) +LPAR()`no'+RPAR() +LPAR()default+RPAR())(Discard the correction. +If there are no more corrections, accept the command line, else (with +tt(CORRECT_ALL)) prompt for the next.) +sitem(tt(y) +LPAR()`yes'+RPAR())(Make the correction. If there are no more +corrections, accept the command line.) +sitem(tt(a) +LPAR()`abort'+RPAR())(Place the entire command line in the +history for later edit, but without accepting it.) sitem(tt(e) +LPAR()`edit'+RPAR())(Resume editing the command line.) endsitem() ) @@ -1570,6 +1664,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>)( @@ -1659,7 +1758,7 @@ well as any directory names. The default is `tt(/tmp/zsh)'. vindex(TMPSUFFIX) item(tt(TMPSUFFIX))( A filename suffix which the shell will use for temporary files created -by process substitutions (e.g., `tt(=LPAR()var(list)RPAR())'). +by process substitutions (e.g., `tt(=LPAR())var(list)tt(RPAR())'). Note that the value should include a leading dot `tt(.)' if intended to be interpreted as a file extension. The default is not to append any suffix, thus this parameter should be assigned only when needed diff --git a/Doc/Zsh/prompt.yo b/Doc/Zsh/prompt.yo index 909012c8e..de988ab7c 100644 --- a/Doc/Zsh/prompt.yo +++ b/Doc/Zsh/prompt.yo @@ -246,6 +246,14 @@ item(tt(%K) LPAR()tt(%k)RPAR())( Start (stop) using a different bacKground colour. The syntax is identical to that for tt(%F) and tt(%f). ) +item(tt(%H))( +Change all character visual attributes using a highlighting specification from +the tt(.zle.hlgroups) associative array. The key is specified in following +braces so, for example tt(%H{error}) will use the highlighting specification +for the `error' group. If the key is not found in the associative array then +it has no effect. Highlighting specifications are in the same format as for +the tt(zle_highlight) parameter. +) item(tt(%{)...tt(%}))( Include a string as a literal escape sequence. The string within the braces should not change the cursor 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/restricted.yo b/Doc/Zsh/restricted.yo index 33dfc96c6..a84fd28ea 100644 --- a/Doc/Zsh/restricted.yo +++ b/Doc/Zsh/restricted.yo @@ -65,10 +65,10 @@ variables. Except for the few listed above, zsh does not restrict the setting of environment variables. If a `tt(perl)', `tt(python)', `tt(bash)', or other general purpose -interpreted script it treated as a restricted +interpreted script is treated as a restricted command, the user can work around the restriction by setting specially crafted `tt(PERL5LIB)', `tt(PYTHONPATH)', -`tt(BASHENV)' (etc.) environment variables. On GNU systems, any +`tt(BASH_ENV)' (etc.) environment variables. On GNU systems, any command can be made to run arbitrary code when performing character set conversion (including zsh itself) by setting a `tt(GCONV_PATH)' environment variable. Those are only a few examples. diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo index f0165c7c1..31eb3f3ba 100644 --- a/Doc/Zsh/zle.yo +++ b/Doc/Zsh/zle.yo @@ -376,7 +376,7 @@ If the tt(-p) flag is given, the following string will be taken as the prompt to display at the left. If the tt(-r) flag is given, the following string gives the prompt to display at the right. If the tt(-h) flag is specified, the history can be accessed from ZLE. If the -tt(-e) flag is given, typing tt(^D) (Control-D) on an empty line +tt(-e) flag is given, typing tt(^D) (Control-D) in an empty buffer causes tt(vared) to exit immediately with a non-zero return value. The tt(-M) option gives a keymap to link to the tt(main) keymap during @@ -733,7 +733,7 @@ enditem() enditem() texinode(Zle Widgets)(User-Defined Widgets)(Zle Builtins)(Zsh Line Editor) -sect(Widgets) +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 @@ -2470,10 +2470,11 @@ command. tt(run-help) is normally aliased to tt(man). tindex(vi-set-buffer) item(tt(vi-set-buffer) (unbound) (tt(")) (unbound))( Specify a buffer to be used in the following command. -There are 37 buffers that can be specified: +There are 39 buffers that can be specified: the 26 `named' buffers tt("a) to tt("z), the `yank' buffer tt("0), -the nine `queued' buffers tt("1) to tt("9) and the `black hole' buffer -tt("_). The named buffers can also be specified as tt("A) to tt("Z). +the nine `queued' buffers tt("1) to tt("9), the `black hole' buffer +tt("_) and the system selection tt("*) and clipboard tt("+). +The named buffers can also be specified as tt("A) to tt("Z). When a buffer is specified for a cut, change or yank command, the text concerned replaces the previous contents of the specified buffer. If @@ -2482,6 +2483,10 @@ appended to the buffer instead of overwriting it. When using the tt("_) buffer, nothing happens. This can be useful for deleting text without affecting any buffers. +Updating the system clipboard relies on specific support from the terminal. +Reading it is not possible so a paste command with tt("*) or tt("+) will do +nothing. + If no buffer is specified for a cut or change command, tt("1) is used, and the contents of tt("1) to tt("8) are each shifted along one buffer; the contents of tt("9) is lost. If no buffer is specified for a yank @@ -2627,7 +2632,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) @@ -2686,6 +2691,9 @@ for different completions. item(tt(paste))( Following a command to paste text, the characters that were inserted. ) +item(tt(ellipsis))( +Markers used to indicate where the text doesn't fit within the terminal. +) enditem() When tt(region_highlight) is set, the contexts that describe a region DASH()- @@ -2775,9 +2783,13 @@ This works similarly to the foreground colour, except the background is not usually affected by the bold attribute. ) item(tt(bold))( -The characters in the given context are shown in a bold font. +The characters in the given context are shown with a bold font weight. Not all terminals distinguish bold fonts. ) +item(tt(faint))( +The characters in the given context are shown with a faint font weight. +Not all terminals distinguish faint fonts. +) item(tt(standout))( The characters in the given context are shown in the terminal's standout mode. The actual effect is specific to the terminal; on many terminals it @@ -2791,6 +2803,21 @@ The characters in the given context are shown underlined. Some terminals show the foreground in a different colour instead; in this case whitespace will not be highlighted. ) +item(tt(italic))( +The characters in the given context are shown in a italic font. +Not all terminals support italic fonts. +) +item(tt(hl=)var(group))( +Use the specified highlighting group. The var(group) is used as a key into +the associative array tt(.zle.hlgroups) to determine the actual highlighting. +) +item(tt(layer=)var(layer))( +The layer is used to determine precedence when multiple highlighting regions +overlap. The var(layer) is a decimal integer, with higher numbers taking +precedence over lower numbers. The default layer is 10 with 30 used as the +default for tt(special), 20 for tt(region) and tt(isearch) and 15 for +tt(paste). +) enditem() The characters described above as `special' are as follows. The |