diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/Zsh/builtins.yo | 158 | ||||
| -rw-r--r-- | Doc/Zsh/calsys.yo | 17 | ||||
| -rw-r--r-- | Doc/Zsh/compsys.yo | 170 | ||||
| -rw-r--r-- | Doc/Zsh/contrib.yo | 82 | ||||
| -rw-r--r-- | Doc/Zsh/expn.yo | 54 | ||||
| -rw-r--r-- | Doc/Zsh/func.yo | 24 | ||||
| -rw-r--r-- | Doc/Zsh/jobs.yo | 15 | ||||
| -rw-r--r-- | Doc/Zsh/mod_curses.yo | 6 | ||||
| -rw-r--r-- | Doc/Zsh/mod_mapfile.yo | 9 | ||||
| -rw-r--r-- | Doc/Zsh/mod_mathfunc.yo | 2 | ||||
| -rw-r--r-- | Doc/Zsh/mod_parameter.yo | 8 | ||||
| -rw-r--r-- | Doc/Zsh/options.yo | 44 | ||||
| -rw-r--r-- | Doc/Zsh/params.yo | 18 | ||||
| -rw-r--r-- | Doc/Zsh/prompt.yo | 9 | ||||
| -rw-r--r-- | Doc/Zsh/zle.yo | 5 | ||||
| -rw-r--r-- | Doc/zmacros.yo | 1 | ||||
| -rw-r--r-- | Doc/ztexi.yo | 6 |
17 files changed, 496 insertions, 132 deletions
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index f3a7f6a97..b23ce3083 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -28,6 +28,40 @@ See ifzman(the section `Zle Builtins' in zmanref(zshzle))\ ifnzman(noderef(Zle Builtins)). )\ )\ + +Some shell builtin commands take options as described in individual +entries; these are often referred to in the list below as `tt(flags)' to +avoid confusion with shell options, which may also have an effect on the +behaviour of builtin commands. In this introductory section, +`tt(option)' always has the meaning of an option to a command that should +be familiar to most command line users. + +Typically, options are single letters preceded by a hyphen (tt(-)). +Options that take an argument accept it either immediately following the +option letter or after white space, for example `tt(print -C3 *)' or +`tt(print -C 3 *)' are equivalent. Arguments to options are not the +same as arguments to the command; the documentation indicates which is +which. Options that do not take an argument may be combined in a single +word, for example `tt(print -ca *)' and `tt(print -c -a *)' are +equivalent. + +Some shell builtin commands also take options that begin with `tt(+)' +instead of `tt(-)'. The list below makes clear which commands these +are. + +Options (together with their individual arguments, if any) must appear +in a group before any non-option arguments; once the first non-option +argument has been found, option processing is terminated. + +All builtin commands other than precommand modifiers, even those that +have no options, can be given the argument `tt(--)' to terminate option +processing. This indicates that the following words are non-option +arguments, but is otherwise ignored. This is useful in cases where +arguments to the command may begin with `tt(-)'. For historical +reasons, most builtin commands also recognize a single `tt(-)' in a +separate word for this purpose; note that this is less standard and +use of `tt(--) is recommended. + startitem() prefix(-) findex(.) @@ -68,7 +102,7 @@ to be checked for alias expansion. If the tt(-g) flag is present, define a global alias; global aliases are expanded even if they do not occur in command position. -If the tt(-s) flags is present, define a suffix alias: if the command +If the tt(-s) flag is present, define a suffix alias: if the command word on a command line is in the form `var(text)tt(.)var(name)', where var(text) is any non-empty string, it is replaced by the text `var(value) var(text)tt(.)var(name)'. Note that var(name) is treated as @@ -277,7 +311,9 @@ item(tt(-c))( clear the directory stack. ) item(tt(-l))( -print directory names in full instead of using of using tt(~) expressions. +print directory names in full instead of using of using tt(~) expressions (\ +ifzman(see em(Dynamic) and em(Static named directories) in zmanref(zshexpn))\ +ifnzman(noderef(Filename Expansion))). ) item(tt(-p))( print directory entries one per line. @@ -291,8 +327,8 @@ enditem() findex(disable) cindex(disabling commands) cindex(commands, disabling) -item(tt(disable) [ tt(-afmrs) ] var(name) ...)( -Temporarily disable the var(name)d hash table elements. The default +item(tt(disable) [ tt(-afmprs) ] var(name) ...)( +Temporarily disable the var(name)d hash table elements or patterns. The default is to disable builtin commands. This allows you to use an external command with the same name as a builtin command. The tt(-a) option causes tt(disable) to act on regular or global aliases. The tt(-s) @@ -305,6 +341,80 @@ quoted to prevent them from undergoing filename expansion), and all hash table elements from the corresponding hash table matching these patterns are disabled. Disabled objects can be enabled with the tt(enable) command. + +With the option tt(-p), var(name) ... refer to elements of the +shell's pattern syntax as described in noderef(Filename Generation). +Certain elements can be disabled separately, as given below. + +Note that patterns +not allowed by the current settings for the options tt(EXTENDED_GLOB), +tt(KSH_GLOB) and tt(SH_GLOB) are never enabled, regardless of the +setting here. For example, if tt(EXTENDED_GLOB) is not active, +the pattern tt(^) is ineffective even if `tt(disable -p "^")' has +not been issued. The list below indicates any option settings +that restrict the use of the pattern. It should be noted that +setting tt(SH_GLOB) has a wider effect then merely disabling patterns +as certain expressions, in particular those involving parentheses, +are parsed differently. + +The following patterns may be disabled; all +the strings need quoting on the command line to prevent them from +being interpreted immediately as patterns and the patterns are +shown below in single quotes as a reminder. +startitem() +item(tt('?'))( +The pattern character tt(?) wherever it occurs, including when preceding +a parenthesis with tt(KSH_GLOB). +) +item(tt('*'))( +The pattern character tt(*) wherever it occurs, including recursive +globbing and when preceding a parenthesis with tt(KSH_GLOB). +) +item('LSQUARE()')( +Character classes. +) +item(tt('<') (tt(NO_SH_GLOB)))( +Numeric ranges. +) +item(tt('|') (tt(NO_SH_GLOB)))( +Alternation in grouped patterns, case statements, or KSH_GLOB +parenthesised expressions. +) +item(tt('LPAR()') (tt(NO_SH_GLOB)))( +Grouping using single parentheses. Disabling this does not disable the +use of parentheses for tt(KSH_GLOB) where they are introduced by a +special character, nor for glob qualifiers (use `tt(setopt +NO_BARE_GLOB_QUAL)' to disable glob qualifiers that use parentheses +only). +) +item(tt('~') (tt(EXTENDED_GLOB)))( +Exclusion in the form var(A)tt(~)var(B). +) +item(tt('^') (tt(EXTENDED_GLOB)))( +Exclusion in the form var(A)tt(^)var(B). +) +item(tt('#') (tt(EXTENDED_GLOB)))( +The pattern character tt(#) wherever it occurs, both for +repetition of a previous pattern and for indicating globbing flags. +) +item(tt('?LPAR()') (tt(KSH_GLOB)))( +The grouping form tt(?LPAR())var(...)tt(RPAR()). Note this is also +disabled if tt('?') is disabled. +) +item(tt('*LPAR()') (tt(KSH_GLOB)))( +The grouping form tt(*LPAR())var(...)tt(RPAR()). Note this is also +disabled if tt('*') is disabled. +) +item(tt('PLUS()LPAR()') (tt(KSH_GLOB)))( +The grouping form tt(PLUS()LPAR())var(...)tt(RPAR()). +) +item(tt('!LPAR()') (tt(KSH_GLOB)))( +The grouping form tt(!LPAR())var(...)tt(RPAR()). +) +item(tt('@LPAR()') (tt(KSH_GLOB)))( +The grouping form tt(@LPAR())var(...)tt(RPAR()). +) +enditem() ) findex(disown) cindex(jobs, disowning) @@ -376,7 +486,9 @@ the section COMPATIBILITY in zmanref(zsh) ifnzman(\ noderef(Compatibility) )\ -. +. In addition to setting shell options, the command also restores +the pristine state of pattern enables, as if all patterns had been +enabled using tt(enable -p). If the tt(emulate) command occurs inside a function that has been marked for execution tracing with tt(functions -t) then the tt(xtrace) @@ -390,9 +502,11 @@ are reset to their default value corresponding to the specified emulation mode, except for certain options describing the interactive environment; otherwise, only those options likely to cause portability problems in scripts and functions are altered. If the tt(-L) switch is given, -the options tt(LOCAL_OPTIONS) and tt(LOCAL_TRAPS) will be set as -well, causing the effects of the tt(emulate) command and any tt(setopt) and -tt(trap) commands to be local to the immediately surrounding shell +the options tt(LOCAL_OPTIONS), tt(LOCAL_PATTERNS) and tt(LOCAL_TRAPS) +will be set as +well, causing the effects of the tt(emulate) command and any tt(setopt), +tt(disable -p) or tt(enable -p), and tt(trap) commands to be local to +the immediately surrounding shell function, if any; normally these options are turned off in all emulation modes except tt(ksh). The tt(-L) switch is mutually exclusive with the use of tt(-c) in var(flags). @@ -414,7 +528,8 @@ Use of tt(-c) enables `sticky' emulation mode for functions defined within the evaluated expression: the emulation mode is associated thereafter with the function so that whenever the function is executed the emulation (respecting the tt(-R) switch, if present) and all -options are set before entry to the function, and restored after exit. +options are set (and pattern disables cleared) +before entry to the function, and the state is restored after exit. If the function is called when the sticky emulation is already in effect, either within an `tt(emulate) var(shell) tt(-c)' expression or within another function with the same sticky emulation, entry and exit @@ -471,7 +586,7 @@ endsitem() findex(enable) cindex(enabling commands) cindex(commands, enabling) -item(tt(enable) [ tt(-afmrs) ] var(name) ...)( +item(tt(enable) [ tt(-afmprs) ] var(name) ...)( Enable the var(name)d hash table elements, presumably disabled earlier with tt(disable). The default is to enable builtin commands. The tt(-a) option causes tt(enable) to act on regular or global aliases. @@ -483,6 +598,13 @@ printed. With the tt(-m) flag the arguments are taken as patterns (should be quoted) and all hash table elements from the corresponding hash table matching these patterns are enabled. Enabled objects can be disabled with the tt(disable) builtin command. + +tt(enable -p) reenables patterns disabled with tt(disable -p). Note +that it does not override globbing options; for example, `tt(enable -p +"~")' does not cause the pattern character tt(~) to be active unless +the tt(EXTENDED_GLOB) option is also set. To enable all possible +patterns (so that they may be invidually disabled with tt(disable -p)), +use `tt(setopt EXTENDED_GLOB KSH_GLOB NO_SH_GLOB)'. ) findex(eval) cindex(evaluating arguments as commands) @@ -507,6 +629,11 @@ is specified, use the exit status from the last command executed. pindex(IGNORE_EOF, use of) An EOF condition will also cause the shell to exit, unless the tt(IGNORE_EOF) option is set. + +See notes at the end of +ifzman(the section JOBS in in zmanref(zshmisc))\ +ifnzman(noderef(Jobs & Signals)) for some possibly unexpected interactions +of the tt(exit) command with jobs. ) findex(export) item(tt(export) [ var(name)[tt(=)var(value)] ... ])( @@ -876,15 +1003,19 @@ sitem(tt(cputime))(Maximum CPU seconds per process.) sitem(tt(datasize))(Maximum data size (including stack) for each process.) sitem(tt(descriptors))(Maximum value for a file descriptor.) sitem(tt(filesize))(Largest single file allowed.) +sitem(tt(kqueues))(Maximum number of kqueues allocated.) sitem(tt(maxproc))(Maximum number of processes.) sitem(tt(maxpthreads))(Maximum number of threads per process.) sitem(tt(memorylocked))(Maximum amount of memory locked in RAM.) sitem(tt(memoryuse))(Maximum resident set size.) sitem(tt(msgqueue))(Maximum number of bytes in POSIX message queues.) +sitem(tt(posixlocks))(Maximum number of POSIX locks per user.) +sitem(tt(pseudoterminals))(Maximum number of pseudo-terminals.) sitem(tt(resident))(Maximum resident set size.) sitem(tt(sigpending))(Maximum number of pending signals.) sitem(tt(sockbufsize))(Maximum size of all socket buffers.) sitem(tt(stacksize))(Maximum stack size for each process.) +sitem(tt(swapsize))(Maximum amount of swap used.) sitem(tt(vmemorysize))(Maximum amount of virtual memory.) endsitem() @@ -1766,7 +1897,7 @@ enditem() findex(ulimit) cindex(resource limits) cindex(limits, resource) -item(tt(ulimit) [ [ tt(-SHacdfilmnpqrstvx) | tt(-N) var(resource) [ var(limit) ] ... ])( +item(tt(ulimit) [ [ tt(-SHacdfiklmnpqsTtvwx) | tt(-N) var(resource) [ var(limit) ] ... ])( Set or display resource limits of the shell and the processes started by the shell. The value of var(limit) can be a number in the unit specified below or one of the values `tt(unlimited)', which removes the limit on the @@ -1797,16 +1928,19 @@ sitem(tt(-c))(512-byte blocks on the size of core dumps.) sitem(tt(-d))(Kilobytes on the size of the data segment.) sitem(tt(-f))(512-byte blocks on the size of files written.) sitem(tt(-i))(The number of pending signals.) +sitem(tt(-k))(The number of kqueues allocated.) sitem(tt(-l))(Kilobytes on the size of locked-in memory.) sitem(tt(-m))(Kilobytes on the size of physical memory.) sitem(tt(-n))(open file descriptors.) +sitem(tt(-p))(The number of pseudo-terminals.) sitem(tt(-q))(Bytes in POSIX message queues.) sitem(tt(-s))(Kilobytes on the size of the stack.) +sitem(tt(-T))(The number of simultaneous threads available to the user.) sitem(tt(-t))(CPU seconds to be used.) -sitem(tt(-r))(The number of simultaneous threads available to the user.) sitem(tt(-u))(The number of processes available to the user.) sitem(tt(-v))(Kilobytes on the size of virtual memory. On some systems this refers to the limit called `address space'.) +sitem(tt(-w))(Kilobytes on the size of swapped out memory.) sitem(tt(-x))(The number of locks on files.) endsitem() diff --git a/Doc/Zsh/calsys.yo b/Doc/Zsh/calsys.yo index 259eb23b3..7dc51ab11 100644 --- a/Doc/Zsh/calsys.yo +++ b/Doc/Zsh/calsys.yo @@ -651,16 +651,29 @@ date specification must be quoted to ensure tt(age) receives the correct arguments, hence the use of the additional colon to separate the date and time. -example(AGEREF1=2006/10/04:10:15 +example(AGEREF=2006/10/04:10:15 AGEREF2=2006/10/04:10:45 print *+LPAR()PLUS()age+RPAR()) This shows the same example before using another form of argument -passing. The dates and times in the parameters tt(AGEREF1) and tt(AGEREF2) +passing. The dates and times in the parameters tt(AGEREF) and tt(AGEREF2) stay in effect until unset, but will be overridden if any argument is passed as an explicit argument to age. Any explicit argument causes both parameters to be ignored. +Instead of an explicit date and time, it's possible to use the +modification time of a file as the date and time for either argument +by introducing the file name with a colon: + +example(print *+LPAR()e-age :file1-+RPAR()) + +matches all files created on the same day (24 hours starting from +midnight) as tt(file1). + +example(print *+LPAR()e-age :file1 :file2-+RPAR()) + +matches all files modified no earlier than tt(file1) and +no later than tt(file2); precision here is to the nearest second. texinode(Calendar Styles)(Calendar Utility Functions)(Calendar System User Functions)(Calendar Function System) sect(Styles) diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 2991c1f4a..d42ad9779 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -3470,14 +3470,26 @@ Like tt(_tags) this function supports the tt(-C) option to give a different name for the argument context field. ) findex(_arguments) -item(tt(_arguments) [ tt(-nswWACRS) ] [ tt(-O) var(name) ] [ tt(-M) var(matchspec) ] [ tt(:) ] var(spec) ...)( -This function can be used to give a complete specification for -completion for a command whose arguments follow standard UNIX option and -argument conventions. The following forms specify individual sets of -options and arguments; to avoid ambiguity, these may be separated from the -options to tt(_arguments) itself by a single colon. Options to -tt(_arguments) itself must be in separate words, i.e. tt(-s -w), not -tt(-sw). +xitem(tt(_arguments) [ tt(-nswWCRS) ] [ tt(-A) var(pat) ] [ tt(-O) var(name) ] [ tt(-M) var(matchspec) ] [ tt(:) ] var(spec)...) +item(tt(_arguments) [ var(opts)... ] tt(-)tt(-) [ -i var(pats) ] [ tt(-s) var(pair) ] [ var(helpspec)... ])( +This function can be used to give a complete specification for completion +for a command whose arguments follow standard UNIX option and argument +conventions. Options to tt(_arguments) itself must be in separate words, +i.e. tt(-s -w), not tt(-sw). + +When calling tt(_arguments), all var(spec)s that describe options of the +analyzed command line must precede all var(spec)s that describe non-option +(aka "normal") arguments of the analyzed line. To avoid ambiguity, all +options to tt(_arguments) itself may be separated from the var(spec) forms +by a single colon. + +The tt(-s -w -W -A) and tt(-S) options describe how parsing of the command +line should proceed, and are discussed in context below. The `tt(-)tt(-)' +form is used to intuit var(spec) forms from the help output of the command +being analyzed, and is described in detail below. The var(opts) for the +`tt(-)tt(-)' form are otherwise the same options as the first form. Note +that `tt(-s)' following `tt(-)tt(-)' has a distinct meaning from `tt(-s)' +preceding `tt(-)tt(-)', and both may appear. With the option tt(-n), tt(_arguments) sets the parameter tt(NORMARG) to the position of the first normal argument in the tt($words) array, @@ -3486,6 +3498,17 @@ has not been reached, tt(NORMARG) is set to tt(-1). The caller should declare `tt(integer NORMARG)' if the tt(-n) option is passed; otherwise the parameter is not used. +The option `tt(-M) var(matchspec)' sets a match specification to use to +completion option names and values. The default var(matchspec) is: + +example(tt(r:|[_-]=* r:|=*)) + +This allows partial word completion after `tt(_)' and `tt(-)', for example +`-f-b' can be completed to `tt(-foo-bar)'. + +Each of the following forms is a var(spec) describing individual sets of +options or arguments on the command line being analyzed. + startitem() xitem(var(n)tt(:)var(message)tt(:)var(action)) item(var(n)tt(::)var(message)tt(:)var(action))( @@ -3530,10 +3553,10 @@ suitable for standard GNU options. The combination of tt(-s) with tt(-w) allows single-letter options to be combined in a single word even if one or more of the options take -arguments. For example, if tt(-a) takes an argument, with no -tt(-s) `tt(-ab)' is considered as a single (unhandled) option; with -tt(-s) tt(-ab) is an option with the argument `tt(b)'; with both tt(-s) -and tt(-w), tt(-ab) may be the option tt(-a) and the option tt(-b) with +arguments. For example, if tt(-x) takes an argument, with no +tt(-s) `tt(-xy)' is considered as a single (unhandled) option; with +tt(-s) tt(-xy) is an option with the argument `tt(y)'; with both tt(-s) +and tt(-w), tt(-xy) may be the option tt(-x) and the option tt(-y) with arguments still to come. The option tt(-W) takes this a stage further: it is possible to @@ -3603,6 +3626,23 @@ enditem() It is possible for options with a literal `PLUS()' or `tt(=)' to appear, but that character must be quoted, for example `tt(-\+)'. +The options tt(-S) and tt(-A) are available to simplify the specifications +for commands with standard option parsing. With tt(-S), no option will be +completed after a `tt(-)tt(-)' appearing on its own on the line; this +argument will otherwise be ignored; hence in the line + +example(foobar -x -- -y) + +the `tt(-x)' is considered an option but the `tt(-y)' is considered an +argument, while the `tt(-)tt(-)' is considered to be neither. + +With tt(-A), no options will be completed after the first non-option +argument on the line. The tt(-A) must be followed by a pattern matching +all strings which are not to be taken as arguments. For example, to make +tt(_arguments) stop completing options after the first normal argument, but +ignoring all strings starting with a hyphen even if they are not described +by one of the var(optspec)s, the form is `tt(-A "-*")'. + Each var(optarg) following an var(optspec) must take one of the following forms: @@ -3676,6 +3716,11 @@ form below, the var(action) will be executed by calling the tt(_all_labels) function to process all tag labels. No special handling of tags is needed unless a function call introduces a new one. +The option `tt(-O) var(name)' specifies the name of an array whose elements +will be passed as arguments to functions called to execute var(action)s. +For example, this can be used to pass the same set of options for the +tt(compadd) builtin to all var(action)s. + The forms for var(action) are as follows. startitem() @@ -3804,6 +3849,18 @@ Furthermore, during the evaluation of the var(action) the context name in the tt(curcontext) parameter is altered to append the same string that is stored in the tt(context) parameter. +The option tt(-C) tells tt(_arguments) to modify the tt(curcontext) +parameter for an action of the form `tt(->)var(state)'. This is the +standard parameter used to keep track of the current context. Here it +(and not the tt(context) array) should be made local to the calling +function to avoid passing back the modified value and should be +initialised to the current value at the start of the function: + +example(local curcontext="$curcontext") + +This is useful where it is not possible for multiple states to be valid +together. + It is possible to specify multiple sets of options and arguments with the sets separated by single hyphens. The specifications before the first hyphen (if any) are shared by all the remaining sets. @@ -3850,47 +3907,6 @@ A useful alternative is often an option specification with rest-arguments (as in `tt(-foo:*:...)'); here the option tt(-foo) swallows up all remaining arguments as described by the var(optarg) definitions. -The options tt(-S) and tt(-A) are available to simplify the specifications -for commands with standard option parsing. With tt(-S), no option will be -completed after a `tt(-)tt(-)' appearing on its own on the line; this -argument will otherwise be ignored; hence in the line - -example(foobar -a -- -b) - -the `tt(-a)' is considered an option but the `tt(-b)' is considered an -argument, while the `tt(-)tt(-)' is considered to be neither. - -With tt(-A), no options will be completed after the first non-option -argument on the line. The tt(-A) must be followed by a pattern matching -all strings which are not to be taken as arguments. For example, to make -tt(_arguments) stop completing options after the first normal argument, but -ignoring all strings starting with a hyphen even if they are not described -by one of the var(optspec)s, the form is `tt(-A "-*")'. - -The option `tt(-O) var(name)' specifies the name of an array whose elements -will be passed as arguments to functions called to execute var(actions). -For example, this can be used to pass the same set of options for the -tt(compadd) builtin to all var(action)s. - -The option `tt(-M) var(spec)' sets a match specification to use to -completion option names and values. It must appear before the first -argument specification. The default is `tt(r:|[_-]=* r:|=*)': this allows -partial word completion after `tt(_)' and `tt(-)', for example `-f-b' -can be completed to `tt(-foo-bar)'. - -The option tt(-C) tells tt(_arguments) to modify -the tt(curcontext) parameter for an action of the form -`tt(->)var(state)'. This is the standard parameter used to keep track of -the current context. Here it (and not the tt(context) array) should be -made local to the calling function -to avoid passing back the modified value and should be initialised to the -current value at the start of the function: - -example(local curcontext="$curcontext") - -This is useful where it is not possible for multiple states to be valid -together. - The option `tt(-)tt(-)' allows tt(_arguments) to work out the names of long options that support the `tt(-)tt(-help)' option which is standard in many GNU commands. The command word is called with the argument @@ -3901,11 +3917,16 @@ the behaviour of the command is unspecified. In addition to options, `tt(_arguments -)tt(-)' will try to deduce the types of arguments available for options when the form `tt(-)tt(-)var(opt)=var(val)' is valid. It is also possible to provide -hints by examining the help text of the command and adding specifiers of -the form `var(pattern)tt(:)var(message)tt(:)var(action)'; note that normal -tt(_arguments) specifiers are not used. The var(pattern) is matched +hints by examining the help text of the command and adding var(helpspec) of +the form `var(pattern)tt(:)var(message)tt(:)var(action)'; note that other +tt(_arguments) var(spec) forms are not used. The var(pattern) is matched against the help text for an option, and if it matches the var(message) and -var(action) are used as for other argument specifiers. For example: +var(action) are used as for other argument specifiers. The special case +of `tt(*:)' means both var(message) and var(action) are empty, which has +the effect of causing options having no description in the help output to +be ordered in listings ahead of options that have a description. + +For example: example(_arguments -- '*\*:toggle:(yes no)' \ '*=FILE*:file:_files' \ @@ -3947,12 +3968,23 @@ will cause completion to ignore the options useful with GNU tt(configure)). The `tt(_arguments -)tt(-)' form can also be followed by the option `tt(-s) -var(pair)' to describe option aliases. Each var(pair) consists of a -pattern and a replacement. For example, some tt(configure)-scripts -describe options only as `tt(-)tt(-enable-foo)', but also accept +var(pair)' to describe option aliases. The var(pair) consists of a list +of alternating patterns and corresponding replacements, enclosed in parens +and quoted so that it forms a single argument word in the tt(_arguments) +call. + +For example, some tt(configure)-script help output describes options only +as `tt(-)tt(-enable-foo)', but the script also accepts the negated form `tt(-)tt(-disable-foo)'. To allow completion of the second form: -example(_arguments -- -s "LPAR()#-tt(-enable- -)tt(-disable-RPAR()")) +example(tt(_arguments -- -s "LPAR()#-)tt(-enable- -)tt(-disable-RPAR()")) + +Finally, note that tt(_arguments) generally expects to be the primary +function handling any completion for which it is used. It may have side +effects which change the treatment of any matches added by other functions +called after it. To combine tt(_arguments) with other functions, those +functions should be called either before tt(_arguments), as an var(action) +within a var(spec), or in handlers for `tt(->)var(state)' actions. Here is a more general example of the use of tt(_arguments): @@ -4251,11 +4283,14 @@ which already contains an expanded description. The tt(-12VJ) options and the var(group) are passed to tt(compadd) and hence determine the group the message string is added to. -The second form gives a description for completions with the tag -var(tag) to be shown even if there are no matches for that tag. The tag -can be omitted and if so the tag is taken from the parameter -tt($curtag); this is maintained by the completion system and so is -usually correct. +The second tt(-e) form gives a description for completions with the tag +var(tag) to be shown even if there are no matches for that tag. This form +is called by tt(_arguments) in the event that there is no action for an +option specification. The tag can be omitted and if so the tag is taken +from the parameter tt($curtag); this is maintained by the completion +system and so is usually correct. Note that if there are no matches at +the time this function is called, tt(compstate[insert]) is cleared, so +additional matches generated later are not inserted on the command line. ) findex(_multi_parts) item(tt(_multi_parts) var(sep) var(array))( @@ -4414,8 +4449,7 @@ tt(ambiguous), tt(special-dirs), tt(list-suffixes) and tt(file-sort) described above. ) findex(_pick_variant) -xitem(tt(_pick_variant) [ tt(-b) var(builtin-label) ] [ tt(-c) -var(command) ] [ tt(-r) var(name) ]) +xitem(tt(_pick_variant) [ tt(-b) var(builtin-label) ] [ tt(-c) var(command) ] [ tt(-r) var(name) ]) item( var(label)tt(=)var(pattern) ... var(label) [ var(args) ... ])( This function is used to resolve situations where a single command name requires more than one type of handling, either because it diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index 8dbc095fd..9d3fc7562 100644 --- a/Doc/Zsh/contrib.yo +++ b/Doc/Zsh/contrib.yo @@ -619,7 +619,7 @@ To load tt(vcs_info): example(autoload -Uz vcs_info) It can be used in any existing prompt, because it does not require any -tt($psvar) entries to be left available. +specific tt($psvar) entries to be available. subsect(Quickstart) @@ -2477,15 +2477,22 @@ See the function tt(modify-current-argument), described below, for an example of how to call this function. ) tindex(modify-current-argument) -item(tt(modify-current-argument) var(expr-using-)tt($ARG))( +item(tt(modify-current-argument) [ var(expr-using-)tt($ARG) | var(func) ])( This function provides a simple method of allowing user-defined widgets to modify the command line argument under the cursor (or immediately to the -left of the cursor if the cursor is between arguments). The argument -should be an expression which when evaluated operates on the shell +left of the cursor if the cursor is between arguments). + +The argument can be an expression which when evaluated operates on the shell parameter tt(ARG), which will have been set to the command line argument under the cursor. The expression should be suitably quoted to prevent it being evaluated too early. +Alternatively, if the argument does not contain the string tt(ARG), it +is assumed to be a shell function, to which the current command line +argument is passed as the only argument. The function should set the +variable tt(REPLY) to the new value for the command line argument. +If the function returns non-zero status, so does the calling function. + For example, a user-defined widget containing the following code converts the characters in the argument under the cursor into all upper case: @@ -2497,6 +2504,18 @@ or one of the styles of quotes), and replaces it with single quoting throughout: example(modify-current-argument '${(qq)${(Q)ARG}}') + +The following performs directory expansion on the command line +argument and replaces it by the absolute path: + +example(expand-dir+LPAR()RPAR() { + REPLY=${~1} + REPLY=${REPLY:a} +} +modify-current-argument expand-dir) + +In practice the function tt(expand-dir) would probably not be defined +within the widget where tt(modify-current-argument) is called. ) enditem() @@ -2842,6 +2861,14 @@ question is run using the tt(eval) builtin instead of by starting a new tt(sh) process. This is more efficient, but may not work in the occasional cases where the mailcap handler uses strict POSIX syntax. ) +kindex(disown, MIME style) +item(tt(disown))( +If this boolean style is true, mailcap handlers started in the +background will be disowned, i.e. not subject to job control within +the parent shell. Such handlers nearly always produce their own +windows, so the only likely harmful side effect of setting the style is +that it becomes harder to kill jobs from within the shell. +) kindex(execute-as-is, MIME style) item(tt(execute-as-is))( This style gives a list of patterns to be matched against files @@ -2854,6 +2881,28 @@ hence executable files are executed directly and not passed to a handler, and the option tt(AUTO_CD) may be used to change to directories that happen to have MIME suffixes. ) +kindex(execute-never, MIME style) +item(tt(execute-never))( +This style is useful in combination with tt(execute-as-is). It is +set to an array of patterns corresponding to full paths to files that +should never be treated as executable, even if the file passed to +the MIME handler matches tt(execute-as-is). This is useful for file +systems that don't handle execute permission or that contain executables +from another operating system. For example, if tt(/mnt/windows) is a +Windows mount, then + +example(zstyle ':mime:*' execute-never '/mnt/windows/*') + +will ensure that any files found in that area will be executed as MIME +types even if they are executable. As this example shows, the complete +file name is matched against the pattern, regardless of how the file +was passed to the handler. The file is resolved to a full path using +the tt(:A) modifier described in +ifzman(the subsection Modifers in zmanref(zshexpn))\ +ifnzman(noderef(Modifiers))); +this means that symbolic links are resolved where possible, so that +links into other file systems behave in the correct fashion. +) kindex(file-path, MIME style) item(tt(file-path))( Used if the style tt(find-file-in-path) is true for the same context. @@ -3127,6 +3176,13 @@ 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). +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 +function prompts for more input (the prompt is preceded by `tt(...)' +to indicate this), and the lines are combined into one to get the final +result. In addition, if the input so far contains more open than +close parentheses tt(zcalc) will prompt for more input. + If arguments are given to tt(zcalc) on start up, they are used to prime the first few positional parameters. A visual indication of this is given when the calculator starts. @@ -3139,6 +3195,10 @@ The output base can be initialised by passing the option `tt(-#)var(base)', for example `tt(zcalc -#16)' (the `tt(#)' may have to be quoted, depending on the globbing options set). +If the option `tt(-f)' is set, all numbers are treated as floating +point, hence for example the expression `tt(3/4)' evaluates to 0.75 +rather than 0. Options must appear in separate words. + The prompt is configurable via the parameter tt(ZCALCPROMPT), which undergoes standard prompt expansion. The index of the current entry is stored locally in the first element of the array tt(psvar), which can be @@ -3191,11 +3251,13 @@ scope. ) item(tt(:function) var(name) [ var(body) ])( Define a mathematical function or (with no var(body)) delete it. +tt(:function) may be abbreviated to tt(:func) or simply tt(:f). +The var(name) may contain the same characters as a shell function name. The function is defined using tt(zmathfuncdef), see below. Note that tt(zcalc) takes care of all quoting. Hence for example: -example(function cube $1 * $1 * $1) +example(:f cube $1 * $1 * $1) defines a function to cube the sole argument. ) @@ -3586,7 +3648,7 @@ ifzman(above)\ ifnzman((noderef(Utilities))). ) findex(zmv) -item(tt(zmv) [ tt(-finqQsvwW) ] [ -C | -L | -M | -p var(program) ] [ -o var(optstring) ] var(srcpat) var(dest) )( +item(tt(zmv) [ tt(-finqQsvwW) ] [ -C | -L | -M | -[pP] var(program) ] [ -o var(optstring) ] var(srcpat) var(dest) )( Move (usually, rename) files matching the pattern var(srcpat) to corresponding files having names of the form given by var(dest), where var(srcpat) contains parentheses surrounding patterns which will be @@ -3631,7 +3693,13 @@ sitem(tt(-p) var(program))(Call var(program) instead of tt(cp), tt(ln) or tt(mv). Whatever it does, it should at least understand the form ifzman(`var(program) tt(-)tt(-) var(oldname) var(newname)')\ ifnzman(example(var(program) tt(-)tt(-) var(oldname) var(newname))) -where var(oldname) and var(newname) are filenames generated by tt(zmv).) +where var(oldname) and var(newname) are filenames generated by tt(zmv). +var(program) will be split into words, so might be e.g. the name +of an archive tool plus a copy or rename subcommand.) +sitem(tt(-P) var(program))(As tt(-p) var(program), except that +var(program) does not accept a following tt(-)tt(-) to indicate the +end of options. In this case filenames must already be in a sane +form for the program in question.) sitem(tt(-o) var(optstring))(The var(optstring) is split into words and passed down verbatim to the tt(cp), tt(ln) or tt(mv) command called to perform the work. It should probably begin with a `tt(-)'.) diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo index da68b4ff7..5ba3e21af 100644 --- a/Doc/Zsh/expn.yo +++ b/Doc/Zsh/expn.yo @@ -57,6 +57,7 @@ cindex(expansion, history) History expansion allows you to use words from previous command lines in the command line you are typing. This simplifies spelling corrections and the repetition of complicated commands or arguments. + vindex(HISTSIZE, use of) Immediately before execution, each command is saved in the history list, the size of which is controlled by the tt(HISTSIZE) parameter. The one @@ -748,6 +749,8 @@ If var(spec) is one of the above substitutions, substitute the length in characters of the result instead of the result itself. If var(spec) is an array expression, substitute the number of elements of the result. +This has the side-effect that joining is skipped even in quoted +forms, which may affect other sub-expressions in var(spec). Note that `tt(^)', `tt(=)', and `tt(~)', below, must appear to the left of `tt(#)' when these forms are combined. ) @@ -870,11 +873,12 @@ item(tt(A))( Create an array parameter with `tt(${)...tt(=)...tt(})', `tt(${)...tt(:=)...tt(})' or `tt(${)...tt(::=)...tt(})'. If this flag is repeated (as in `tt(AA)'), create an associative -array parameter. Assignment is made before sorting or padding. -The var(name) part may be a subscripted range for ordinary -arrays; the var(word) part em(must) be converted to an array, for -example by using `tt(${(AA)=)var(name)tt(=)...tt(})' to activate -field splitting, when creating an associative array. +array parameter. Assignment is made before sorting or padding; +if field splitting is active, the var(word) part is split before +assignment. The var(name) part may be a subscripted range for +ordinary arrays; the var(word) part em(must) be converted to +an array, for example by using `tt(${(AA)=)var(name)tt(=)...tt(})' +to activate field splitting, when creating an associative array. ) item(tt(a))( Sort in array index order; when combined with `tt(O)' sort in reverse @@ -884,7 +888,9 @@ order. ) item(tt(c))( With tt(${#)var(name)tt(}), count the total number of characters in an array, -as if the elements were concatenated with spaces between them. +as if the elements were concatenated with spaces between them. This is not +a true join of the array, so other expressions used with this flag may have +an effect on the elements of the array before it is counted. ) item(tt(C))( Capitalize the resulting words. `Words' in this case refers to sequences @@ -1308,7 +1314,8 @@ subscripts apply to the scalar or array value yielded by the previous subscript. Thus if tt(var) is an array, tt(${var[1][2]}) is the second character of the first word, but tt(${var[2,4][2]}) is the entire third word (the second word of the range of words two through four of the -original array). Any number of subscripts may appear. +original array). Any number of subscripts may appear. Flags such as +tt((k)) and tt((v)) which alter the result of subscripting are applied. ) item(tt(4.) em(Parameter name replacement))( The effect of any tt((P)) flag, which treats the value so far as a @@ -1316,11 +1323,12 @@ parameter name and replaces it with the corresponding value, is applied. ) item(tt(5.) em(Double-quoted joining))( If the value after this process is an array, and the substitution -appears in double quotes, and no tt((@)) flag is present at the current -level, the words of the value are joined with the first character of the -parameter tt($IFS), by default a space, between each word (single word -arrays are not modified). If the tt((j)) flag is present, that is used for -joining instead of tt($IFS). +appears in double quotes, and neither an tt((@)) flag nor a tt(#) +length operator is present at the current level, then words of the +value are joined with the first character of the parameter tt($IFS), +by default a space, between each word (single word arrays are not +modified). If the tt((j)) flag is present, that is used for joining +instead of tt($IFS). ) item(tt(6.) em(Nested subscripting))( Any remaining subscripts (i.e. of a nested substitution) are evaluated at @@ -1700,14 +1708,14 @@ Note that trailing slashes will be removed from the path to the directory It is also possible to define directory names using the tt(-d) option to the tt(hash) builtin. -In certain circumstances (in prompts, for instance), when the shell -prints a path, the path is checked to see if it has a named -directory as its prefix. If so, then the prefix portion -is replaced with a `tt(~)' followed by the name of the directory. -The shortest way of referring to the directory is used, -with ties broken in favour of using a named directory, -except when the directory is tt(/) itself. The parameters tt($PWD) and -tt($OLDPWD) are never abbreviated in this fashion. +When the shell prints a path (e.g. when expanding tt(%~) in prompts or when +printing the directory stack), the path is checked to see if it has a named +directory as its prefix. If so, then the prefix portion is replaced with a +`tt(~)' followed by the name of the directory. +The shorter of the two ways of referring to the directory is used, +i.e. either the directory name or the full path; the name is used +if they are the same length. +The parameters tt($PWD) and tt($OLDPWD) are never abbreviated in this fashion. subsect(`=' expansion) @@ -1949,10 +1957,12 @@ item(tt(@LPAR())...tt(RPAR()))( Match the pattern in the parentheses. (Like `tt(LPAR())...tt(RPAR())'.) ) item(tt(*LPAR())...tt(RPAR()))( -Match any number of occurrences. (Like `tt(LPAR())...tt(RPAR()#)'.) +Match any number of occurrences. (Like `tt(LPAR())...tt(RPAR()#)', +except that recursive directory searching is not supported.) ) item(tt(PLUS()LPAR())...tt(RPAR()))( -Match at least one occurrence. (Like `tt(LPAR())...tt(RPAR()##)'.) +Match at least one occurrence. (Like `tt(LPAR())...tt(RPAR()##)', +except that recursive directory searching is not supported..) ) item(tt(?LPAR())...tt(RPAR()))( Match zero or one occurrence. (Like `tt(LPAR()|)...tt(RPAR())'.) diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo index 7c391f80d..6e9cfeee9 100644 --- a/Doc/Zsh/func.yo +++ b/Doc/Zsh/func.yo @@ -264,9 +264,16 @@ Executed when a history line has been read interactively, but before it is executed. The sole argument is the complete history line (so that any terminating newline will still be present). -If any of the hook functions return a non-zero value the history -line will not be saved, although it lingers in the history until the -next line is executed allow you to reuse or edit it immediately. +If any of the hook functions returns status 1 (or any non-zero value +other than 2, though this is not guaranteed for future versions of the +shell) the history line will not be saved, although it lingers in the +history until the next line is executed, allowing you to reuse or edit +it immediately. + +If any of the hook functions returns status 2 the history line +will be saved on the internal history list, but not written to +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 @@ -274,10 +281,13 @@ 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. -The following example function first adds the history line to the normal -history with the newline stripped, which is usually the correct behaviour. -Then it switches the history context so that the line will -be written to a history file in the current directory. +The following example function works with one of the options +tt(INC_APPEND_HISTORY) or tt(SHARE_HISTORY) set, in order that the line +is written out immediately after the history entry is added. It first +adds the history line to the normal history with the newline stripped, +which is usually the correct behaviour. Then it switches the history +context so that the line will be written to a history file in the +current directory. example(zshaddhistory+LPAR()RPAR() { print -sr -- ${1%%$'\n'} diff --git a/Doc/Zsh/jobs.yo b/Doc/Zsh/jobs.yo index 3baf77f20..d9395010a 100644 --- a/Doc/Zsh/jobs.yo +++ b/Doc/Zsh/jobs.yo @@ -115,3 +115,18 @@ The shell itself always ignores the tt(QUIT) signal. Otherwise, signals have the values inherited by the shell from its parent (but see the tt(TRAP)var(NAL) special functions in noderef(Functions)). + +cindex(exiting shell, and asynchronous jobs) +cindex(asynchronous jobs, and exiting shell) +cindex(jobs, asynchronous, and exiting shell) +Certain jobs are run asynchronously by the shell other than those +explicitly put into the background; even in cases where the shell +would usually wait for such jobs, an explicit tt(exit) command +or exit due to the option tt(ERR_EXIT) will cause the shell to +exit without waiting. Examples of such asynchronous jobs are +process substitution, see +ifzman(the section PROCESS SUBSTITUTION in the zmanref(zshexpn) manual page)\ +ifnzman(noderef(Process Substitution)), and the handler processes for +multios, see +ifzman(the section MULTIOS in the zmanref(zshmisc) manual page)\ +ifnzman(the section Multios in noderef(Redirection)). diff --git a/Doc/Zsh/mod_curses.yo b/Doc/Zsh/mod_curses.yo index d3f8ad22e..7ad772adb 100644 --- a/Doc/Zsh/mod_curses.yo +++ b/Doc/Zsh/mod_curses.yo @@ -84,11 +84,11 @@ The subcommand tt(position) writes various positions associated with var(targetwin) into the array named var(array). These are, in order: startsitem() -sitem()(The y and x coordinates of the cursor relative to the top left +sitem(-)(The y and x coordinates of the cursor relative to the top left of var(targetwin)) -sitem()(The y and x coordinates of the top left of var(targetwin) on the +sitem(-)(The y and x coordinates of the top left of var(targetwin) on the screen) -sitem()(The size of var(targetwin) in y and x dimensions.) +sitem(-)(The size of var(targetwin) in y and x dimensions.) endsitem() Outputting characters and strings are achieved by tt(char) and tt(string) diff --git a/Doc/Zsh/mod_mapfile.yo b/Doc/Zsh/mod_mapfile.yo index 98114aea2..96e056816 100644 --- a/Doc/Zsh/mod_mapfile.yo +++ b/Doc/Zsh/mod_mapfile.yo @@ -28,9 +28,12 @@ referenced may not be written or deleted. A file may conveniently be read into an array as one line per element with the form -`var(array)tt(=LPAR()"${(f)mapfile[)var(filename)tt(]}"RPAR())'. -The double quotes are necessary to prevent empty lines from being -removed. +`var(array)tt(=LPAR()"${(f@)mapfile[)var(filename)tt(]}"RPAR())'. +The double quotes and the `tt(@)' are necessary to prevent empty lines +from being removed. Note that if the file ends with a newline, +the shell will split on the final newline, generating an additional +empty field; this can be suppressed by using +`var(array)tt(=LPAR()"${(f@)${mapfile[)var(filename)tt(]%$'\n'}}"RPAR())'. ) enditem() diff --git a/Doc/Zsh/mod_mathfunc.yo b/Doc/Zsh/mod_mathfunc.yo index dda4f36fd..5239da5f8 100644 --- a/Doc/Zsh/mod_mathfunc.yo +++ b/Doc/Zsh/mod_mathfunc.yo @@ -33,7 +33,7 @@ returns an integer. The function tt(signgam) takes no arguments, and returns an integer, which is the C variable of the same name, as described in manref(gamma)(3). Note that it is therefore only useful immediately after a call to tt(gamma) or -tt(lgamma). Note also that `tt(signgam+LPAR()RPAR)' and `tt(signgam)' are +tt(lgamma). Note also that `tt(signgam+LPAR()RPAR())' and `tt(signgam)' are distinct expressions. The following functions take two floating point arguments: tt(copysign), diff --git a/Doc/Zsh/mod_parameter.yo b/Doc/Zsh/mod_parameter.yo index 5948d74f2..32d4796f7 100644 --- a/Doc/Zsh/mod_parameter.yo +++ b/Doc/Zsh/mod_parameter.yo @@ -57,6 +57,14 @@ vindex(dis_reswords) item(tt(dis_reswords))( Like tt(reswords) but for disabled reserved words. ) +vindex(patchars) +item(tt(patchars))( +This array contains the enabled pattern characters. +) +vindex(dis_patchars) +item(tt(dis_patchars))( +Like tt(patchars) but for disabled pattern characters. +) vindex(aliases) item(tt(aliases))( This maps the names of the regular aliases currently enabled to their diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo index 6c8d423cb..3c6ea63b8 100644 --- a/Doc/Zsh/options.yo +++ b/Doc/Zsh/options.yo @@ -485,6 +485,17 @@ Treat the `tt(#)', `tt(~)' and `tt(^)' characters as part of patterns for filename generation, etc. (An initial unquoted `tt(~)' always produces named directory expansion.) ) +pindex(FORCE_FLOAT) +pindex(NO_FORCE_FLOAT) +pindex(FORCEFLOAT) +pindex(NOFORCEFLOAT) +cindex(floating point, forcing use of) +cindex(forcing use of floating point) +item(tt(FORCE_FLOAT))( +Constants in arithmetic evaluation will be treated as floating point +even without the use of a decimal point. Integers in any base +will be converted. +) pindex(GLOB) pindex(NO_GLOB) pindex(NOGLOB) @@ -1229,6 +1240,7 @@ pindex(NOPRINTEXITVALUE) cindex(exit status, printing) item(tt(PRINT_EXIT_VALUE) (tt(-1)))( Print the exit value of programs with non-zero exit status. +This is only available at the command line in interactive shells. ) pindex(RC_QUOTES) pindex(NO_RC_QUOTES) @@ -1541,6 +1553,11 @@ 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 in zmanref(zshmisc))\ +ifnzman(noderef(Jobs & Signals)). ) pindex(ERR_RETURN) pindex(NO_ERR_RETURN) @@ -1606,6 +1623,19 @@ A shell function can also guarantee itself a known shell configuration with a formulation like `tt(emulate -L zsh)'; the tt(-L) activates tt(LOCAL_OPTIONS). ) +pindex(LOCAL_PATTERNS) +pindex(NO_LOCAL_PATTERNS) +pindex(LOCALPATTERNS) +pindex(NOLOCALPATTERNS) +item(tt(LOCAL_PATTERNS))( +If this option is set at the point of return from a shell function, +the state of pattern disables, as set with the builtin command +`tt(disable -p)', is restored to what it was when the function was +entered. The behaviour of this option is similar to the effect +of tt(LOCAL_OPTIONS) on options; hence `tt(emulate -L sh)' (or +indeed any other emulation with the tt(-L) option) activates +tt(LOCAL_PATTERNS). +) pindex(LOCAL_TRAPS) pindex(NO_LOCAL_TRAPS) pindex(LOCALTRAPS) @@ -1658,6 +1688,20 @@ Sequences of digits indicating a numeric base such as the `tt(08)' component in `tt(08#77)' are always interpreted as decimal, regardless of leading zeroes. ) +pindex(PIPE_FAIL) +pindex(NO_PIPE_FAIL) +pindex(PIPEFAIL) +pindex(NOPIPEFAIL) +cindex(exit status from pipeline) +cindex(status, on exit from pipeline) +cindex(pipeline, exit status from) +item(tt(PIPE_FAIL))( +By default, when a pipeline exits the exit status recorded by the shell +and returned by the shell variable tt($?) reflects that of the +rightmost element of a pipeline. If this option is set, the exit status +instead reflects the status of the rightmost element of the pipeline +that was non-zero, or zero if all elements exited with zero status. +) pindex(SOURCE_TRACE) pindex(NO_SOURCE_TRACE) pindex(SOURCETRACE) diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo index b7b7750ff..9d951bb38 100644 --- a/Doc/Zsh/params.yo +++ b/Doc/Zsh/params.yo @@ -431,9 +431,15 @@ of a shell function, shell script, or the shell itself; see noderef(Invocation), and also noderef(Functions). The parameter var(n), where var(n) is a number, is the var(n)th positional parameter. +The parameter `tt($0)' is a special case, see +noderef(Parameters Set By The Shell). + The parameters tt(*), tt(@) and tt(argv) are arrays containing all the positional parameters; thus `tt($argv[)var(n)tt(])', etc., is equivalent to simply `tt($)var(n)'. +Note that the options tt(KSH_ARRAYS) or tt(KSH_ZERO_SUBSCRIPT) apply +to these arrays as well, so with either of those options set, +`tt(${argv[0]})' is equivalent to `tt($1)' and so on. Positional parameters may be changed after the shell or function starts by using the tt(set) builtin, by assigning to the tt(argv) array, or by direct @@ -967,6 +973,16 @@ item(tt(HISTFILE))( The file to save the history in when an interactive shell exits. If unset, the history is not saved. ) +vindex(HISTORY_IGNORE) +item(tt(HISTORY_IGNORE))( +If set, is treated as a pattern at the time history files are written. +Any potential history entry that matches the pattern is skipped. For +example, if the value is `tt(fc *)' then commands that invoke the +interactive history editor are never written to the history file (compare +the tt(HIST_NO_STORE) option or the tt(zshaddhistory) hook, either of +which would prevent such commands from being added to the interactive +history at all). +) vindex(HISTSIZE) item(tt(HISTSIZE) <S>)( The maximum number of events stored in the internal history list. @@ -1215,7 +1231,7 @@ In sh or ksh emulation, the default is `tt(PLUS() )'. vindex(psvar) vindex(PSVAR) item(tt(psvar) <S> <Z> (tt(PSVAR) <S>))( -An array (colon-separated list) whose first nine values can be used in +An array (colon-separated list) whose elements can be used in tt(PROMPT) strings. Setting tt(psvar) also sets tt(PSVAR), and vice versa. ) diff --git a/Doc/Zsh/prompt.yo b/Doc/Zsh/prompt.yo index 8d7979546..eab15d29d 100644 --- a/Doc/Zsh/prompt.yo +++ b/Doc/Zsh/prompt.yo @@ -100,10 +100,13 @@ directory to show; zero means the whole path. A negative integer specifies leading components, i.e. tt(%-1d) specifies the first component. ) item(tt(%~))( -As tt(%d) and tt(%/), but if the current working directory has a named +As tt(%d) and tt(%/), but if the current working directory starts with +tt($HOME), that part is replaced by a `tt(~)'. Furthermore, if it has a named directory as its prefix, that part is replaced by a `tt(~)' followed by -the name of the directory. If it starts with tt($HOME), that part is -replaced by a `tt(~)'. +the name of the directory, but only if the result is shorter than +the full path; +ifzman(see em(Dynamic) and em(Static named directories) in zmanref(zshexpn))\ +ifnzman(noderef(Filename Expansion)). ) xitem(tt(%h)) item(tt(%!))( diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo index 3e8c25a90..614924bfb 100644 --- a/Doc/Zsh/zle.yo +++ b/Doc/Zsh/zle.yo @@ -308,6 +308,7 @@ cindex(parameters, editing) cindex(editing parameters) xitem(tt(vared) [ tt(-Aache) ] [ tt(-p) var(prompt) ] [ tt(-r) var(rprompt) ]) xitem( [ tt(-M) var(main-keymap) ] [ tt(-m) var(vicmd-keymap) ]) +xitem( [ tt(-i) var(init-widget) ] [ tt(-f) var(finish-widget) ]) item( [ tt(-t) var(tty) ] var(name))( The value of the parameter var(name) is loaded into the edit buffer, and the line editor is invoked. When the editor exits, @@ -343,6 +344,10 @@ to override tt(viins) and tt(vicmd). For emacs-style editing, only tt(-M) is normally needed but the tt(-m) option may still be used. On exit, the previous keymaps will be restored. +tt(Vared) calls the usual `tt(zle-line-init)' and `tt(zle-line-finish)' +hooks before and after it takes control. Using the tt(-i) and tt(-f) +options, it is possible to replace these with other custom widgets. + If `tt(-t) var(tty)' is given, var(tty) is the name of a terminal device to be used instead of the default tt(/dev/tty). If var(tty) does not refer to a terminal an error is reported. diff --git a/Doc/zmacros.yo b/Doc/zmacros.yo index 19506d222..aed5bd8a7 100644 --- a/Doc/zmacros.yo +++ b/Doc/zmacros.yo @@ -33,6 +33,7 @@ DEFINEMACRO(RQUOTE)(0)(CHAR(39)) DEFINEMACRO(LPAR)(0)(CHAR(40)) DEFINEMACRO(RPAR)(0)(CHAR(41)) DEFINEMACRO(PLUS)(0)(CHAR(43)) +DEFINEMACRO(LSQUARE)(0)(CHAR(91)) DEFINEMACRO(DASH)(0)(ifztexi(--)ifnztexi(-)) diff --git a/Doc/ztexi.yo b/Doc/ztexi.yo index ed0236bde..e58ff3902 100644 --- a/Doc/ztexi.yo +++ b/Doc/ztexi.yo @@ -71,7 +71,7 @@ def(texinfo)(2)(\ NOTRANS(@ifinfo)+NL()\ NOTRANS(@dircategory Utilities)+NL()\ NOTRANS(@direntry)+NL()\ - NOTRANS( * ZSH: (zsh). The Z Shell Manual.)+NL()\ + NOTRANS(* ZSH: (zsh). The Z Shell Manual.)+NL()\ NOTRANS(@end direntry)+NL()\ NOTRANS(@end ifinfo)+NL()\ ) @@ -193,8 +193,8 @@ def(startlist)(0)(\ startitem()\ ) def(endlist)(0)(\ - NOTRANS(@item)+NL()\ - enditem()\ + enditem()+NL()\ + NOTRANS(@sp 1)\ ) def(list)(1)(\ item(ARG1)()\ |