summaryrefslogtreecommitdiff
path: root/Doc/Zsh
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/Zsh')
-rw-r--r--Doc/Zsh/builtins.yo56
-rw-r--r--Doc/Zsh/compsys.yo87
-rw-r--r--Doc/Zsh/compwid.yo73
-rw-r--r--Doc/Zsh/cond.yo2
-rw-r--r--Doc/Zsh/contrib.yo52
-rw-r--r--Doc/Zsh/expn.yo130
-rw-r--r--Doc/Zsh/grammar.yo40
-rw-r--r--Doc/Zsh/intro.yo3
-rw-r--r--Doc/Zsh/mod_files.yo34
-rw-r--r--Doc/Zsh/mod_mapfile.yo2
-rw-r--r--Doc/Zsh/mod_parameter.yo2
-rw-r--r--Doc/Zsh/mod_socket.yo6
-rw-r--r--Doc/Zsh/mod_system.yo11
-rw-r--r--Doc/Zsh/mod_zpty.yo2
-rw-r--r--Doc/Zsh/mod_zutil.yo113
-rw-r--r--Doc/Zsh/options.yo22
-rw-r--r--Doc/Zsh/params.yo6
-rw-r--r--Doc/Zsh/redirect.yo11
-rw-r--r--Doc/Zsh/restricted.yo45
-rw-r--r--Doc/Zsh/zle.yo13
20 files changed, 514 insertions, 196 deletions
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index cc9832379..ada69c99a 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -39,11 +39,11 @@ 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
+option letter or after white space, for example `tt(print -C3 {1..9})' or
+`tt(print -C 3 {1..9})' 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
+word, for example `tt(print -rca -- *)' and `tt(print -r -c -a -- *)' are
equivalent.
Some shell builtin commands also take options that begin with `tt(+)'
@@ -54,14 +54,14 @@ 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(-)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(-)tt(-)' is recommended.
+All builtin commands other than `tt(echo)' and precommand modifiers,
+even those that have no options, can be given the argument `tt(-)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 (including `tt(echo)') also
+recognize a single `tt(-)' in a separate word for this purpose; note
+that this is less standard and use of `tt(-)tt(-)' is recommended.
startitem()
prefix(-)
@@ -114,9 +114,9 @@ var(text) is any non-empty string, it is replaced by the text
a literal string, not a pattern. A trailing space in var(value) is not
special in this case. For example,
-example(alias -s ps=gv)
+example(alias -s ps='gv --')
-will cause the command `tt(*.ps)' to be expanded to `tt(gv *.ps)'. As
+will cause the command `tt(*.ps)' to be expanded to `tt(gv -- *.ps)'. As
alias expansion is carried out earlier than globbing, the `tt(*.ps)' will
then be expanded. Suffix aliases constitute a different name space from
other aliases (so in the above example it is still possible
@@ -290,6 +290,8 @@ of the list shown by the tt(dirs) command, starting with zero.
An argument of the form `tt(-)var(n)' counts from the right.
If the tt(PUSHD_MINUS) option is set, the meanings of `tt(PLUS())'
and `tt(-)' in this context are swapped.
+If the tt(POSIX_CD) option is set, this form of tt(cd) is not recognised
+and will be interpreted as the first form.
If the tt(-q) (quiet) option is specified, the hook function tt(chpwd)
and the functions in the array tt(chpwd_functions) are not called.
@@ -768,8 +770,8 @@ However, if the current event has added entries to the history with
includes all new history entries since the current event began.
When the tt(-l) flag is given, the resulting events are listed on
-standard output. Otherwise the editor program var(ename) is invoked on a
-file containing these history events. If var(ename) is not given, the
+standard output. Otherwise the editor program specified by tt(-e) var(ename)
+is invoked on a file containing these history events. If tt(-e) is not given, the
value of the parameter tt(FCEDIT) is used; if that is not set the value of
the parameter tt(EDITOR) is used; if that is not set a builtin default,
usually `tt(vi)' is used. If var(ename) is `tt(-)', no editor is invoked.
@@ -858,10 +860,11 @@ point numbers are not permitted.
)
findex(functions)
xitem(tt(functions) [ {tt(PLUS())|tt(-)}tt(UkmtTuWz) ] [ tt(-x) var(num) ] [ var(name) ... ])
+xitem(tt(functions -c) var(oldfn) var(newfn))
xitem(tt(functions -M) [tt(-s)] var(mathfn) [ var(min) [ var(max) [ var(shellfn) ] ] ])
xitem(tt(functions -M) [ tt(-m) var(pattern) ... ])
item(tt(functions +M) [ tt(-m) ] var(mathfn) ... )(
-Equivalent to tt(typeset -f), with the exception of the tt(-x),
+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.
@@ -875,6 +878,14 @@ function or functions only. The option is turned off at the start of
nested functions (apart from anonoymous functions) unless the called
function also has the tt(-W) attribute.
+The tt(-c) option causes var(oldfn) to be copied to var(newfn). The
+copy is efficiently handled internally by reference counting. If
+var(oldfn) was marked for autoload it is first loaded and if this
+fails the copy fails. Either function may subsequently be redefined
+without affecting the other. A typical idiom is that var(oldfn) is the
+name of a library shell function which is then redefined to call
+tt(newfn), thereby installing a modified version of the function.
+
Use of the tt(-M) option may not be combined with any of the options
handled by tt(typeset -f).
@@ -988,6 +999,10 @@ 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.
+
Given no arguments, and neither the tt(-r) or tt(-f) options,
the selected hash table will be listed in full.
@@ -1243,7 +1258,10 @@ If given together with tt(-o) or tt(-O), sorting is performed
case-independently.
)
item(tt(-l))(
-Print the arguments separated by newlines instead of spaces.
+Print the arguments separated by newlines instead of spaces. Note: if
+the list of arguments is empty, tt(print -l) will still output one empty
+line. To print a possibly-empty list of arguments one per line, use
+tt(print -C1), as in `tt(print -rC1 -- "$list[@]")'.
)
item(tt(-m))(
Take the first argument as a pattern (should be quoted), and remove
@@ -1254,7 +1272,9 @@ item(tt(-n))(
Do not add a newline to the output.
)
item(tt(-N))(
-Print the arguments separated and terminated by nulls.
+Print the arguments separated and terminated by nulls. Again,
+tt(print -rNC1 -- "$list[@]") is a canonical way to print an
+arbitrary list as null-delimited records.
)
item(tt(-o))(
Print the arguments sorted in ascending order.
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index ba49fe298..c2d20ca40 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -1609,16 +1609,12 @@ item(tt(format))(
If this is set for the tt(descriptions) tag, its value is used as a
string to display above matches in completion lists. The sequence
`tt(%d)' in this string will be replaced with a short description of
-what these matches are. This string may also contain the following
-sequences to specify output attributes
-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
-`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.
+what these matches are. This string may also contain the output
+attribute sequences understood by tt(compadd -X)
+(see
+ifzman(zmanref(zshcompwid))\
+ifnzman(noderef(Completion Widgets))\
+).
The style is tested with each tag valid for the current completion
before it is tested for the tt(descriptions) tag. Hence different format
@@ -2064,6 +2060,9 @@ specification. The value should be in the form described in
ifzman(the section `Completion Matching Control' in zmanref(zshcompwid))\
ifnzman(noderef(Completion Matching Control))\
. For examples of this, see the description of the tt(tag-order) style.
+
+For notes comparing the use of this and the tt(matcher-list) style, see
+under the description of the tt(tag-order) style.
)
kindex(matcher-list, completion style)
item(tt(matcher-list))(
@@ -2128,6 +2127,9 @@ If there is no current matcher or it is empty, and the option
tt(NO_CASE_GLOB) is in effect, the matching for files is performed
case-insensitively in any case. However, any matcher must
explicitly specify case-insensitive matching if that is required.
+
+For notes comparing the use of this and the tt(matcher) style, see
+under the description of the tt(tag-order) style.
)
kindex(max-errors, completion style)
item(tt(max-errors))(
@@ -2534,20 +2536,20 @@ is started, making it easy to select either of them.
)
kindex(sort, completion style)
item(tt(sort))(
-Many completion widgets call tt(_description) at some point which
-decides whether the matches are added sorted or unsorted (often
-indirectly via tt(_wanted) or tt(_requested)). This style can be set
-explicitly to one of the usual `true' or `false' values as an override.
-If it is not set for the context, the standard behaviour of the
-calling widget is used.
+This allows the standard ordering of matches to be overridden.
+
+If its value is `tt(true)' or `tt(false)', sorting is enabled or disabled.
+Additionally the values associated with the `tt(-o)' option to tt(compadd) can
+also be listed: tt(match), tt(nosort), tt(numeric), tt(reverse). If it is not
+set for the context, the standard behaviour of the calling widget is used.
The style is tested first against the full context including the tag, and
if that fails to produce a value against the context without the tag.
-If the calling widget explicitly requests unsorted matches, this is usually
-honoured. However, the default (unsorted) behaviour of completion
-for the command history may be overridden by setting the style to
-`true'.
+In many cases where a calling widget explicitly selects a particular ordering
+in lieu of the default, a value of `tt(true)' is not honoured. An example of
+where this is not the case is for command history where the default of sorting
+matches chronologically may be overridden by setting the style to `true'.
In the tt(_expand) completer, if it is set to
`true', the expansions generated will always be sorted. If it is set
@@ -4404,11 +4406,11 @@ convention is not enforced). The description for the corresponding set
of matches is passed to the function in var(descr).
The styles tested are: tt(format), tt(hidden), tt(matcher),
-tt(ignored-patterns) and tt(group-name). The tt(format) style is first
-tested for the given var(tag) and then for the tt(descriptions) tag if
-no value was found, while the remainder are only tested for the tag
-given as the first argument. The function also calls tt(_setup)
-which tests some more styles.
+tt(ignore-line), tt(ignored-patterns), tt(group-name) and tt(sort).
+The tt(format) style is first tested for the given var(tag) and then for
+the tt(descriptions) tag if no value was found, while the remainder are
+only tested for the tag given as the first argument. The function also
+calls tt(_setup) which tests some more styles.
The string returned by the tt(format) style (if any) will be modified so
that the sequence `tt(%d)' is replaced by the var(descr) given as the third
@@ -4518,9 +4520,12 @@ New plugins will be picked up and run automatically.
)
findex(_files)
item(tt(_files))(
-The function tt(_files) calls tt(_path_files) with all the arguments it
-was passed except for tt(-g) and tt(-/). The use of these two options
-depends on the setting of the tt(file-patterns) style.
+The function tt(_files) is a wrapper around tt(_path_files). It supports
+all of the same functionality, with some enhancements DASH()- notably, it
+respects the tt(list-dirs-first) style, and it allows users to override
+the behaviour of the tt(-g) and tt(-/) options with the tt(file-patterns)
+style. tt(_files) should therefore be preferred over tt(_path_files) in
+most cases.
This function accepts the full set of options allowed by
tt(_path_files), described below.
@@ -4585,7 +4590,9 @@ not set with the former.
If the tt(-r) option is given, no style is used; the var(descr) is
taken literally as the string to display. This is most useful
when the var(descr) comes from a pre-processed argument list
-which already contains an expanded description.
+which already contains an expanded description. Note that this
+option does not disable the `tt(%)'-sequence parsing done by
+tt(compadd).
The tt(-12VJ) options and the var(group) are passed to tt(compadd) and
hence determine the group the message string is added to.
@@ -4658,7 +4665,7 @@ fi
return ret)
)
findex(_normal)
-item(tt(_normal))(
+item(tt(_normal) [ tt(-P) | tt(-p) var(precommand) ])(
This is the standard function called to handle completion outside
any special tt(-)var(context)tt(-). It is called both to complete the command
word and also the arguments for a command. In the second case,
@@ -4668,10 +4675,22 @@ there is none it uses the completion for the tt(-default-) context.
A second use is to reexamine the command line specified by the tt($words)
array and the tt($CURRENT) parameter after those have been modified.
For example, the function tt(_precommand), which
-completes after pre-command specifiers such as tt(nohup), removes the
+completes after precommand specifiers such as tt(nohup), removes the
first word from the tt(words) array, decrements the tt(CURRENT) parameter,
-then calls tt(_normal) again. The effect is that `tt(nohup) var(cmd ...)'
-is treated in the same way as `var(cmd ...)'.
+then calls `tt(_normal -p $service)'. The effect is that
+`tt(nohup) var(cmd ...)' is treated in the same way as `var(cmd ...)'.
+
+startitem()
+item(tt(-P))(
+Reset the list of precommands. This option should be used if completing
+a command line which allows internal commands (e.g. builtins and
+functions) regardless of prior precommands (e.g. `tt(zsh -c)').
+)
+item(tt(-p) var(precommand))(
+Append var(precommand) to the list of precommands. This option should be
+used in nearly all cases in which tt(-P) is not applicable.
+)
+enditem()
If the command name matches one of the patterns given by one of the
options tt(-p) or tt(-P) to tt(compdef), the corresponding completion
@@ -5135,7 +5154,7 @@ which values are already present on the command line and hence are not
to be completed again. If the tt(-w) option is given, other arguments
are examined as well.
-The first non-option argument is used as a string to print as a
+The first non-option argument, var(desc), is used as a string to print as a
description before listing the values.
All other arguments describe the possible values and their
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index 1cc94bf95..0b98d07b2 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -446,12 +446,13 @@ startitem()
findex(compadd)
cindex(completion widgets, adding specified matches)
redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ ))ifnztexi( )))
-xitem(tt(compadd )[ tt(-akqQfenUlo12C) ] [ tt(-F) var(array) ])
+xitem(tt(compadd )[ tt(-akqQfenUl12C) ] [ tt(-F) var(array) ])
xitem(SPACES()[tt(-P) var(prefix) ] [ tt(-S) var(suffix) ])
xitem(SPACES()[tt(-p) var(hidden-prefix) ] [ tt(-s) var(hidden-suffix) ])
xitem(SPACES()[tt(-i) var(ignored-prefix) ] [ tt(-I) var(ignored-suffix) ])
xitem(SPACES()[tt(-W) var(file-prefix) ] [ tt(-d) var(array) ])
-xitem(SPACES()[tt(-J) var(name) ] [ tt(-V) var(name) ] [ tt(-X) var(explanation) ] [ tt(-x) var(message) ])
+xitem(SPACES()[tt(-J) var(group-name) ] [ tt(-X) var(explanation) ] [ tt(-x) var(message) ])
+xitem(SPACES()[tt(-V) var(group-name) ] [ tt(-o) [ var(order) ] ])
xitem(SPACES()[tt(-r) var(remove-chars) ] [ tt(-R) var(remove-func) ])
xitem(SPACES()[tt(-D) var(array) ] [ tt(-O) var(array) ] [ tt(-A) var(array) ])
xitem(SPACES()[tt(-E) var(number) ])
@@ -540,18 +541,40 @@ This option only has an effect if used together with the tt(-d)
option. If it is given, the display strings are listed one per line,
not arrayed in columns.
)
-item(tt(-o))(
-This option only has an effect if used together with the tt(-d)
-option. If it is given, the order of the output is determined by the
-match strings; otherwise it is determined by the display strings
-(i.e. the strings given by the tt(-d) option).
+item(tt(-o) [ var(order) ])(
+This controls the order in which matches are sorted. var(order) is a
+comma-separated list comprising the following possible values. These values
+can be abbreviated to their initial two or three characters. Note that the
+order forms part of the group name space so matches with different orderings
+will not be in the same group.
+
+startitem()
+item(tt(match))(
+If given, the order of the output is determined by the match strings;
+otherwise it is determined by the display strings (i.e. the strings given
+by the tt(-d) option). This is the default if `tt(-o)' is specified but
+the var(order) argument is omitted.
+)
+item(tt(nosort))(
+This specifies that the matches are pre-sorted and their order should be
+preserved. This value only makes sense alone and cannot be combined with any
+others.
+)
+item(tt(numeric))(
+If the matches include numbers, sort them numerically rather than
+lexicographically.
+)
+item(tt(reverse))(
+Arrange the matches backwards by reversing the sort ordering.
)
-item(tt(-J) var(name))(
+enditem()
+)
+item(tt(-J) var(group-name))(
Gives the name of the group of matches the words should be stored in.
)
-item(tt(-V) var(name))(
-Like tt(-J) but naming an unsorted group. These are in a different name
-space than groups created with the tt(-J) flag.
+item(tt(-V) var(group-name))(
+Like tt(-J) but naming an unsorted group. This option is identical to
+the combination of tt(-J) and tt(-o nosort).
)
item(tt(-1))(
If given together with the tt(-V) option, makes
@@ -567,6 +590,30 @@ different name spaces.
item(tt(-X) var(explanation))(
The var(explanation) string will be printed with the list of matches,
above the group currently selected.
+
+Within the var(explanation), the following sequences may be used to
+specify output attributes
+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
+`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(%%)'
+produces a literal `tt(%)'.
+
+These sequences are most often employed by users when customising the
+tt(format) style
+(see
+ifzman(zmanref(zshcompsys))\
+ifnzman(noderef(Completion System))\
+),
+but they must also be taken into account when writing completion
+functions, as passing descriptions with unescaped `tt(%)' characters
+to utility functions such as tt(_arguments) and tt(_message) may
+produce unexpected results. If arbitrary text is to be passed in a
+description, it can be escaped using e.g. tt(${my_str//\%/%%}).
)
item(tt(-x) var(message))(
Like tt(-X), but the var(message) will be printed even if there are no
@@ -728,8 +775,8 @@ The options are:
startitem()
item(tt(-p) var(number))(
-If the contents of the tt(PREFIX) parameter is longer than var(number)
-characters, the first var(number) characters are removed from it and
+If the value of the tt(PREFIX) parameter is at least var(number)
+characters long, the first var(number) characters are removed from it and
appended to the contents of the tt(IPREFIX) parameter.
)
item(tt(-P) [ var(number) ] var(pattern))(
diff --git a/Doc/Zsh/cond.yo b/Doc/Zsh/cond.yo
index 4ca132a26..000e576d0 100644
--- a/Doc/Zsh/cond.yo
+++ b/Doc/Zsh/cond.yo
@@ -138,7 +138,7 @@ tt(match) is set to the substrings that matched parenthesised
subexpressions and the arrays tt(mbegin) and tt(mend) to the indices of
the start and end positions, respectively, of the substrings within
var(string). The arrays are not set if there were no parenthesised
-subexpresssions. For example, if the string `tt(a short string)' is matched
+subexpressions. For example, if the string `tt(a short string)' is matched
against the regular expression `tt(s+LPAR()...RPAR()t)', then (assuming the
option tt(KSH_ARRAYS) is not set) tt(MATCH), tt(MBEGIN)
and tt(MEND) are `tt(short)', tt(3) and tt(7), respectively, while tt(match),
diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index d32ba018d..c6bf745b7 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -677,7 +677,7 @@ As an example, ~[g:p:s] might specify:
startitem()
item(tt(g))(
The top level directory for your git area. This first component
-has to match, or the function will retrun indicating another
+has to match, or the function will return indicating another
directory name hook function should be tried.
)
item(tt(p))(
@@ -1343,11 +1343,11 @@ endsitem()
In tt(patch-format) and tt(nopatch-format) these replacements are done:
startsitem()
-sitem(tt(%p))(The name of the top-most applied patch (tt(applied-string)).)
-sitem(tt(%u))(The number of unapplied patches (tt(unapplied-string)).)
+sitem(tt(%p))(The name of the top-most applied patch; may be overridden by the tt(applied-string) hook.)
+sitem(tt(%u))(The number of unapplied patches; may be overridden by the tt(unapplied-string) hook.)
sitem(tt(%n))(The number of applied patches.)
sitem(tt(%c))(The number of unapplied patches.)
-sitem(tt(%a))(The number of all patches.)
+sitem(tt(%a))(The number of all patches (tt(%a = %n + %c)).)
sitem(tt(%g))(The names of active tt(mq) guards (tt(hg) backend).)
sitem(tt(%G))(The number of active tt(mq) guards (tt(hg) backend).)
endsitem()
@@ -2227,7 +2227,20 @@ is set in the context tt(:zle:*) to tt(true) if the word style is
tt(bash) and tt(false) otherwise. It may be overridden by setting it in
the more specific context tt(:zle:forward-word*).
-Here are some examples of use of the styles, actually taken from the
+It is possible to create widgets with specific behaviour by defining
+a new widget implemented by the appropriate generic function, then
+setting a style for the context of the specific widget. For example,
+the following defines a widget tt(backward-kill-space-word) using
+tt(backward-kill-word-match), the generic widget implementing
+tt(backward-kill-word) behaviour, and ensures that the new widget
+always implements space-delimited behaviour.
+
+example(zle -N backward-kill-space-word backward-kill-word-match
+zstyle :zle:backward-kill-space-word word-style space)
+
+The widget tt(backward-kill-space-word) can now be bound to a key.
+
+Here are some further examples of use of the styles, actually taken from the
simplified interface in tt(select-word-style):
example(zstyle ':zle:*' word-style standard
@@ -4284,9 +4297,10 @@ See also the tt(pager), tt(prompt) and tt(rprompt) styles below.
findex(regexp-replace)
item(tt(regexp-replace) var(var) var(regexp) var(replace))(
Use regular expressions to perform a global search and replace operation
-on a variable. If the option tt(RE_MATCH_PCRE) is not set, POSIX
-extended regular expressions are used, else Perl-compatible regular
-expressions (this requires the shell to be linked against the tt(pcre)
+on a variable. POSIX extended regular expressions are used,
+unless the option tt(RE_MATCH_PCRE) has been set, in which case
+Perl-compatible regular expressions are used
+(this requires the shell to be linked against the tt(pcre)
library).
var(var) is the name of the variable containing the string to be matched.
@@ -4417,24 +4431,28 @@ the elements from the tt(input) list in each run. If no var(command) is
provided, then no var(arg) list may be provided, and in that event the
default command is `tt(print)' with arguments `tt(-r -)tt(-)'.
-For example, to get a long tt(ls) listing of all plain files in the
-current directory or its subdirectories:
+For example, to get a long tt(ls) listing of all non-hidden plain files
+in the current directory or its subdirectories:
example(autoload -U zargs
-zargs -- **/*(.) -- ls -l)
+zargs -- **/*(.) -- ls -ld --)
+
+The first and third occurrences of `tt(-)tt(-)' are used to mark the end
+of options for tt(zargs) and tt(ls) respectively to guard against
+filenames starting with `tt(-)', while the second is used to separate the
+list of files from the command to run (`tt(ls -ld --)').
+
+The first `tt(-)tt(-)' would also be needed if there was a chance the
+list might be empty as in:
-Note that `tt(-)tt(-)' is used both to mark the end of the var(option)
-list and to mark the end of the var(input) list, so it must appear twice
-whenever the var(input) list may be empty. If there is guaranteed to be
-at least one var(input) and the first var(input) does not begin with a
-`tt(-)', then the first `tt(-)tt(-)' may be omitted.
+example(zargs -r -- ./*.back+LPAR()#qN+RPAR() -- rm -f)
In the event that the string `tt(-)tt(-)' is or may be an var(input), the
tt(-e) option may be used to change the end-of-inputs marker. Note that
this does em(not) change the end-of-options marker. For example, to use
`tt(..)' as the marker:
-example(zargs -e.. -- **/*(.) .. ls -l)
+example(zargs -e.. -- **/*(.) .. ls -ld --)
This is a good choice in that example because no plain file can be named
`tt(..)', but the best end-marker depends on the circumstances.
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index a212d742d..c129b4228 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -260,9 +260,23 @@ see the definition of the filename extension in the description of the
tt(r) modifier below. Note that according to that definition the result
will be empty if the string ends with a `tt(.)'.
)
-item(tt(h))(
-Remove a trailing pathname component, leaving the head. This works
-like `tt(dirname)'.
+item(tt(h) [ var(digits) ])(
+Remove a trailing pathname component, shortening the path by one
+directory level: this is the `head' of the pathname. This works like
+`tt(dirname)'. If the tt(h) is followed immediately (with no spaces or
+other separator) by any number of decimal digits, and the value of the
+resulting number is non-zero, that number of leading components is
+preserved instead of the final component being removed. In an
+absolute path the leading `tt(/)' is the first component, so,
+for example, if tt(var=/my/path/to/something), then tt(${var:h3})
+substitutes tt(/my/path). Consecutive `/'s are treated the same as
+a single `/'. In parameter substitution, digits may only be
+used if the expression is in braces, so for example the short form
+substitution tt($var:h2) is treated as tt(${var:h}2), not as
+tt(${var:h2}). No restriction applies to the use of digits in history
+substitution or globbing qualifiers. If more components are requested
+than are present, the entire path is substituted (so this does not
+trigger a `failed modifier' error in history expansion).
)
item(tt(l))(
Convert the words to all lowercase.
@@ -316,9 +330,12 @@ 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))(
-Remove all leading pathname components, leaving the tail. This works
-like `tt(basename)'.
+item(tt(t) [ var(digits) ])(
+Remove all leading pathname components, leaving the final component (tail).
+This works like `tt(basename)'. Any trailing slashes are first removed.
+Decimal digits are handled as described above for (h), but in this
+case that number of trailing components is preserved instead of
+the default 1; 0 is treated the same as 1.
)
item(tt(u))(
Convert the words to all uppercase.
@@ -383,7 +400,7 @@ backslashes.
For example, the following piece of filename generation code
with the tt(EXTENDED_GLOB) option:
-example(print *.c+LPAR()#q:s/#%+LPAR()#b+RPAR()s+LPAR()*+RPAR().c/'S${match[1]}.C'/+RPAR())
+example(print -r -- *.c+LPAR()#q:s/#%+LPAR()#b+RPAR()s+LPAR()*+RPAR().c/'S${match[1]}.C'/+RPAR())
takes the expansion of tt(*.c) and applies the glob qualifiers in the
tt(LPAR()#q)var(...)tt(RPAR()) expression, which consists of a substitution
@@ -565,7 +582,25 @@ and subscript notation to access individual array elements.
Note in particular the fact that words of unquoted parameters are not
automatically split on whitespace unless the option tt(SH_WORD_SPLIT) is
set; see references to this option below for more details. This is an
-important difference from other shells.
+important difference from other shells. However, as in other shells,
+null words are elided from unquoted parameters' expansions.
+
+With default options, after the assignments:
+
+example(array=("first word" "" "third word")
+scalar="only word")
+
+then tt($array) substitutes two words, `tt(first word)' and `tt(third
+word)', and tt($scalar) substitutes a single word `tt(only word)'. Note
+that second element of tt(array) was elided. Scalar parameters can
+be elided too if their value is null (empty). To avoid elision, use quoting as
+follows: tt("$scalar") for scalars and tt("${array[@]}") or tt("${(@)array}")
+for arrays. (The last two forms are equivalent.)
+
+Parameter expansions can involve em(flags), as in `tt(${(@kv)aliases})',
+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.
In the expansions discussed below that require a pattern, the form of
the pattern is the same as that used for filename generation;
@@ -577,17 +612,8 @@ noderef(Modifiers) in noderef(History Expansion) can be
applied: for example, tt(${i:s/foo/bar/}) performs string
substitution on the expansion of parameter tt($i).
-In the following descriptions, `word' refers to a single word
+In the following descriptions, `var(word)' refers to a single word
substituted on the command line, not necessarily a space delimited word.
-With default options, after the assignments:
-
-example(array=("first word" "second word")
-scalar="only word")
-
-then tt($array) substitutes two words, `tt(first word)' and `tt(second
-word)', and tt($scalar) substitutes a single word `tt(only word)'. This
-may be modified by explicit or implicit word-splitting, however. The
-full rules are complicated and are noted at the end.
startitem()
item(tt(${)var(name)tt(}))(
@@ -1122,7 +1148,7 @@ form of single quoting is used that only quotes the string if needed to
protect special characters. Typically this form gives the most readable
output.
-If a tt(q+) is given, an extended form of minmal quoting is used that
+If a tt(q+) is given, an extended form of minimal quoting is used that
causes unprintable characters to be rendered using tt($')var(...)tt(').
This quoting is similar to that used by the output of values by the
tt(typeset) family of commands.
@@ -1377,11 +1403,40 @@ used with the tt(${)...tt(/)...tt(}) forms.
startitem()
item(tt(S))(
-Search substrings as well as beginnings or ends; with tt(#) start
-from the beginning and with tt(%) start from the end of the string.
+With tt(#) or tt(##), search for the match that starts closest to the start of
+the string (a `substring match'). Of all matches at a particular position,
+tt(#) selects the shortest and tt(##) the longest:
+
+example(% str="aXbXc"
+% echo ${+LPAR()S+RPAR()str#X*}
+abXc
+% echo ${+LPAR()S+RPAR()str##X*}
+a
+% )
+
+With tt(%) or tt(%%), search for the match that starts closest to the end of
+the string:
+
+example(% str="aXbXc"
+% echo ${+LPAR()S+RPAR()str%X*}
+aXbc
+% echo ${+LPAR()S+RPAR()str%%X*}
+aXb
+% )
+
+(Note that tt(%) and tt(%%) don't search for the match that ends closest to the
+end of the string, as one might expect.)
+
With substitution via tt(${)...tt(/)...tt(}) or
tt(${)...tt(//)...tt(}), specifies non-greedy matching, i.e. that the
-shortest instead of the longest match should be replaced.
+shortest instead of the longest match should be replaced:
+
+example(% str="abab"
+% echo ${str/*b/_}
+_
+% echo ${+LPAR()S+RPAR()str/*b/_}
+_ab
+% )
)
item(tt(I:)var(expr)tt(:))(
Search the var(expr)th match (where var(expr) evaluates to a number).
@@ -2247,12 +2302,13 @@ parentheses can be referenced.
For example,
-example(foo="a string with a message"
-if [[ $foo = (a|an)' '(#b)(*)' '* ]]; then
+example(foo="a_string_with_a_message"
+if [[ $foo = (a|an)_(#b)(*) ]]; then
print ${foo[$mbegin[1],$mend[1]]}
fi)
-prints `tt(string with a)'. Note that the first parenthesis is before the
+prints `tt(string_with_a_message)'.
+Note that the first set of parentheses is before the
tt((#b)) and does not create a backreference.
Backreferences work with all forms of pattern matching other than filename
@@ -2475,11 +2531,11 @@ therefore matches files in the current directory as well as
subdirectories.
Thus:
-example(ls (*/)#bar)
+example(ls -ld -- (*/)#bar)
or
-example(ls **/bar)
+example(ls -ld -- **/bar)
does a recursive directory search for files named `tt(bar)' (potentially
including the file `tt(bar)' in the current directory). This form does not
@@ -2494,11 +2550,11 @@ they are treated as if both a tt(/) plus a further tt(*) are present.
Hence:
example(setopt GLOBSTARSHORT
-ls **.c)
+ls -ld -- **.c)
is equivalent to
-example(ls **/*.c)
+example(ls -ld -- **/*.c)
subsect(Glob Qualifiers)
cindex(globbing, qualifiers)
cindex(qualifiers, globbing)
@@ -2690,7 +2746,7 @@ appropriate test. For example,
example(nt+LPAR()RPAR() { [[ $REPLY -nt $NTREF ]] }
NTREF=reffile
-ls -l *(+nt))
+ls -ld -- *(+nt))
lists all files in the directory that have been modified more recently than
tt(reffile).
@@ -2881,36 +2937,36 @@ is performed, although note that the presence of the parentheses
causes the entire expression to be subjected to any global pattern matching
options such as tt(NULL_GLOB). Thus:
-example(ls *(-/))
+example(ls -ld -- *(-/))
lists all directories and symbolic links that point to directories,
and
-example(ls *(-@))
+example(ls -ld -- *(-@))
lists all broken symbolic links, and
-example(ls *(%W))
+example(ls -ld -- *(%W))
lists all world-writable device files in the current directory, and
-example(ls *(W,X))
+example(ls -ld -- *(W,X))
lists all files in the current directory that are
world-writable or world-executable, and
-example(echo /tmp/foo*(u0^@:t))
+example(print -rC1 /tmp/foo*(u0^@:t))
outputs the basename of all root-owned files beginning with the string
`tt(foo)' in tt(/tmp), ignoring symlinks, and
-example(ls *.*~(lex|parse).[ch](^D^l1))
+example(ls -ld -- *.*~(lex|parse).[ch](^D^l1))
lists all files having a link count of one whose names contain a dot
(but not those starting with a dot, since tt(GLOB_DOTS) is explicitly
switched off) except for tt(lex.c), tt(lex.h), tt(parse.c) and tt(parse.h).
-example(print b*.pro+LPAR()#q:s/pro/shmo/+RPAR()(#q.:s/builtin/shmiltin/))
+example(print -rC1 b*.pro+LPAR()#q:s/pro/shmo/+RPAR()(#q.:s/builtin/shmiltin/))
demonstrates how colon modifiers and other qualifiers may be chained
together. The ordinary qualifier `tt(.)' is applied first, then the colon
diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo
index d30c9d2d7..e028c8512 100644
--- a/Doc/Zsh/grammar.yo
+++ b/Doc/Zsh/grammar.yo
@@ -297,11 +297,11 @@ findex(always)
cindex(always blocks)
cindex(try blocks)
item(tt({) var(try-list) tt(} always {) var(always-list) tt(}))(
-First execute var(try-list). Regardless of errors, or tt(break),
-tt(continue), or tt(return) commands encountered within var(try-list),
+First execute var(try-list). Regardless of errors, or tt(break) or
+tt(continue) commands encountered within var(try-list),
execute var(always-list). Execution then continues from the
result of the execution of var(try-list); in other words, any error,
-or tt(break), tt(continue), or tt(return) command is treated in the
+or tt(break) or tt(continue) command is treated in the
normal way, as if var(always-list) were not present. The two
chunks of code are referred to as the `try block' and the `always block'.
@@ -313,23 +313,23 @@ An `error' in this context is a condition such as a syntax error which
causes the shell to abort execution of the current function, script, or
list. Syntax errors encountered while the shell is parsing the
code do not cause the var(always-list) to be executed. For example,
-an erroneously constructed tt(if) block in tt(try-list) would cause the
-shell to abort during parsing, so that tt(always-list) would not be
+an erroneously constructed tt(if) block in var(try-list) would cause the
+shell to abort during parsing, so that var(always-list) would not be
executed, while an erroneous substitution such as tt(${*foo*}) would
-cause a run-time error, after which tt(always-list) would be executed.
+cause a run-time error, after which var(always-list) would be executed.
An error condition can be tested and reset with the special integer
-variable tt(TRY_BLOCK_ERROR). Outside an tt(always-list) the value is
-irrelevant, but it is initialised to tt(-1). Inside tt(always-list), the
-value is 1 if an error occurred in the tt(try-list), else 0. If
-tt(TRY_BLOCK_ERROR) is set to 0 during the tt(always-list), the error
-condition caused by the tt(try-list) is reset, and shell execution
-continues normally after the end of tt(always-list). Altering the value
-during the tt(try-list) is not useful (unless this forms part of an
+variable tt(TRY_BLOCK_ERROR). Outside an var(always-list) the value is
+irrelevant, but it is initialised to tt(-1). Inside var(always-list), the
+value is 1 if an error occurred in the var(try-list), else 0. If
+tt(TRY_BLOCK_ERROR) is set to 0 during the var(always-list), the error
+condition caused by the var(try-list) is reset, and shell execution
+continues normally after the end of var(always-list). Altering the value
+during the var(try-list) is not useful (unless this forms part of an
enclosing tt(always) block).
-Regardless of tt(TRY_BLOCK_ERROR), after the end of tt(always-list) the
-normal shell status tt($?) is the value returned from tt(try-list).
+Regardless of tt(TRY_BLOCK_ERROR), after the end of var(always-list) the
+normal shell status tt($?) is the value returned from var(try-list).
This will be non-zero if there was an error, even if tt(TRY_BLOCK_ERROR)
was set to zero.
@@ -345,10 +345,16 @@ example({
}
# The error condition has been reset.)
-An tt(exit) command (or a tt(return) command executed at the outermost
-function level of a script) encountered in tt(try-list) does em(not) cause
+When a tt(try) block occurs outside of any function,
+a tt(return) or a tt(exit) encountered in var(try-list) does em(not) cause
the execution of var(always-list). Instead, the shell exits immediately
after any tt(EXIT) trap has been executed.
+Otherwise, a tt(return) command encountered in var(try-list) will cause the
+execution of var(always-list), just like tt(break) and tt(continue).
+
+COMMENT(The semantics of calling 'exit' in try-list inside a function are
+deliberately left unspecified, because historically there was a mismatch between
+the documented and implemented behaviours. Cf. 20076, 21734/21735, 45075.)
)
findex(function)
xitem(tt(function) var(word) ... [ tt(()) ] [ var(term) ] tt({) var(list) tt(}))
diff --git a/Doc/Zsh/intro.yo b/Doc/Zsh/intro.yo
index a7a2f3248..75d25ce27 100644
--- a/Doc/Zsh/intro.yo
+++ b/Doc/Zsh/intro.yo
@@ -15,6 +15,9 @@ startlist()
ifzshone(\
list(em(zsh) Zsh overview (this section))
)\
+ifzshall(\
+list(em(zsh) Zsh overview)
+)\
list(em(zshroadmap) Informal introduction to the manual)
list(em(zshmisc) Anything not fitting into the other sections)
list(em(zshexpn) Zsh command and parameter expansion)
diff --git a/Doc/Zsh/mod_files.yo b/Doc/Zsh/mod_files.yo
index 90e988474..9f9634c86 100644
--- a/Doc/Zsh/mod_files.yo
+++ b/Doc/Zsh/mod_files.yo
@@ -23,6 +23,26 @@ item(tt(chgrp) [ tt(-hRs) ] var(group) var(filename) ...)(
Changes group of files specified. This is equivalent to tt(chown) with
a var(user-spec) argument of `tt(:)var(group)'.
)
+findex(chmod)
+item(tt(chmod) [ tt(-Rs) ] var(mode) var(filename) ...)(
+Changes mode of files specified.
+
+The specified var(mode) must be in octal.
+
+The tt(-R) option causes tt(chmod) to recursively descend into directories,
+changing the mode of all files in the directory after
+changing the mode of the directory itself.
+
+The tt(-s) option is a zsh extension to tt(chmod) functionality. It enables
+paranoid behaviour, intended to avoid security problems involving
+a tt(chmod) being tricked into affecting files other than the ones
+intended. It will refuse to follow symbolic links, so that (for example)
+``tt(chmod 600 /tmp/foo/passwd)'' can't accidentally chmod tt(/etc/passwd)
+if tt(/tmp/foo) happens to be a link to tt(/etc). It will also check
+where it is after leaving directories, so that a recursive chmod of
+a deep directory tree can't end up recursively chmoding tt(/usr) as
+a result of directories being moved up the tree.
+)
findex(chown)
item(tt(chown) [ tt(-hRs) ] var(user-spec) var(filename) ...)(
Changes ownership and group of files specified.
@@ -124,15 +144,15 @@ fall back on copying and removing files; if this behaviour is desired,
use tt(cp) and tt(rm) manually. This may change in a future version.
)
findex(rm)
-item(tt(rm) [ tt(-dfirs) ] var(filename) ...)(
+item(tt(rm) [ tt(-dfiRrs) ] var(filename) ...)(
Removes files and directories specified.
-Normally, tt(rm) will not remove directories (except with the tt(-r)
-option). The tt(-d) option causes tt(rm) to try removing directories
+Normally, tt(rm) will not remove directories (except with the tt(-R) or tt(-r)
+options). The tt(-d) option causes tt(rm) to try removing directories
with tt(unlink) (see manref(unlink)(2)), the same method used for files.
Typically only the super-user can actually succeed in unlinking
directories in this way.
-tt(-d) takes precedence over tt(-r).
+tt(-d) takes precedence over tt(-R) and tt(-r).
By default, the user will be queried before removing any file
that the user cannot write to, but writable files will be silently
@@ -142,9 +162,9 @@ any files. The tt(-f) option causes files to be
silently deleted, without querying, and suppresses all error indications.
tt(-f) takes precedence.
-The tt(-r) option causes tt(rm) to recursively descend into directories,
-deleting all files in the directory before removing the directory with
-the tt(rmdir) system call (see manref(rmdir)(2)).
+The tt(-R) and tt(-r) options cause tt(rm) to recursively descend into
+directories, deleting all files in the directory before removing the directory
+with the tt(rmdir) system call (see manref(rmdir)(2)).
The tt(-s) option is a zsh extension to tt(rm) functionality. It enables
paranoid behaviour, intended to avoid common security problems involving
diff --git a/Doc/Zsh/mod_mapfile.yo b/Doc/Zsh/mod_mapfile.yo
index 96e056816..640beeb12 100644
--- a/Doc/Zsh/mod_mapfile.yo
+++ b/Doc/Zsh/mod_mapfile.yo
@@ -18,7 +18,7 @@ editing the file `tt(myfile)'.
When the array is accessed as a whole, the keys are the names of files in
the current directory, and the values are empty (to save a huge overhead in
-memory). Thus tt(${(k)mapfile}) has the same affect as the glob operator
+memory). Thus tt(${(k)mapfile}) has the same effect as the glob operator
tt(*(D)), since files beginning with a dot are not special. Care must be
taken with expressions such as tt(rm ${(k)mapfile}), which will delete
every file in the current directory without the usual `tt(rm *)' test.
diff --git a/Doc/Zsh/mod_parameter.yo b/Doc/Zsh/mod_parameter.yo
index 942e4c5b6..2e3011e44 100644
--- a/Doc/Zsh/mod_parameter.yo
+++ b/Doc/Zsh/mod_parameter.yo
@@ -55,7 +55,7 @@ For any other function, including any defined at an interactive prompt or
an autoload function whose path has not yet been resolved, this is
the empty string. However, the hash element is reported as defined
just so long as the function is present: the keys to this hash are
-the same as those to tt($funcions).
+the same as those to tt($functions).
)
vindex(dis_functions_source)
item(tt(dis_functions_source))(
diff --git a/Doc/Zsh/mod_socket.yo b/Doc/Zsh/mod_socket.yo
index 867f6081f..78d9254e8 100644
--- a/Doc/Zsh/mod_socket.yo
+++ b/Doc/Zsh/mod_socket.yo
@@ -43,7 +43,8 @@ startitem()
item(tt(zsocket) tt(-l) [ tt(-v) ] [ tt(-d) var(fd) ] var(filename))(
tt(zsocket -l) will open a socket listening on var(filename).
The shell parameter tt(REPLY) will be set to the file descriptor
-associated with that listener.
+associated with that listener. The file descriptor remains open in subshells
+and forked external executables.
If tt(-d) is specified, its argument
will be taken as the target file descriptor for
@@ -56,7 +57,8 @@ tt(zsocket -a) will accept an incoming connection
to the socket associated with var(listenfd).
The shell parameter tt(REPLY) will
be set to the file descriptor associated with
-the inbound connection.
+the inbound connection. The file descriptor remains open in subshells
+and forked external executables.
If tt(-d) is specified, its argument
will be taken as the target file descriptor for the
diff --git a/Doc/Zsh/mod_system.yo b/Doc/Zsh/mod_system.yo
index a27bab47f..6292af071 100644
--- a/Doc/Zsh/mod_system.yo
+++ b/Doc/Zsh/mod_system.yo
@@ -45,7 +45,9 @@ specified as a comma-separated list. The following is a list of possible
options. Note that, depending on the system, some may not be available.
startitem()
item(tt(cloexec))(
-mark file to be closed when other programs are executed
+mark file to be closed when other programs are executed (else
+the file descriptor remains open in subshells and forked external
+executables)
)
xitem(tt(create))
item(tt(creat))(
@@ -177,8 +179,11 @@ locked by opening a file descriptor to the file and applying a lock to
the file descriptor. The lock terminates when the shell process that
created the lock exits; it is therefore often convenient to create file
locks within subshells, since the lock is automatically released when
-the subshell exits. Status 0 is returned if the lock succeeds, else
-status 1.
+the subshell exits. Note that use of the tt(print) builtin with the
+tt(-u) option will, as a side effect, release the lock, as will redirection
+to the file in the shell holding the lock. To work around this use a
+subshell, e.g. `tt((print message) >> )var(file)'. Status 0 is
+returned if the lock succeeds, else status 1.
In the second form the file descriptor given by the arithmetic
expression var(fd_expr) is closed, releasing a lock. The file descriptor
diff --git a/Doc/Zsh/mod_zpty.yo b/Doc/Zsh/mod_zpty.yo
index 6f20c4b75..3ca031c01 100644
--- a/Doc/Zsh/mod_zpty.yo
+++ b/Doc/Zsh/mod_zpty.yo
@@ -25,7 +25,7 @@ monitored with ZLE descriptor handlers (see ifzman(zmanref(zshzle))\
ifnzman(noderef(Zle Builtins))) or manipulated with tt(sysread) and
tt(syswrite) (see ifzman(THE ZSH/SYSTEM MODULE in zmanref(zshmodules))\
ifnzman(noderef(The zsh/system Module))). em(Warning): Use of tt(sysread)
-and tt(syswrite) is em(not) recommended, use tt(zpty -r) and tt(zpty -w)
+and tt(syswrite) is em(not) recommended; use tt(zpty -r) and tt(zpty -w)
unless you know exactly what you are doing.
)
item(tt(zpty) tt(-d) [ var(name) ... ])(
diff --git a/Doc/Zsh/mod_zutil.yo b/Doc/Zsh/mod_zutil.yo
index 15f6ed365..24aebdfaf 100644
--- a/Doc/Zsh/mod_zutil.yo
+++ b/Doc/Zsh/mod_zutil.yo
@@ -7,7 +7,7 @@ The tt(zsh/zutil) module only adds some builtins:
startitem()
findex(zstyle)
-xitem(tt(zstyle) [ tt(-L) [ var(pattern) [ var(style) ] ] ])
+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) ] ])
@@ -17,35 +17,56 @@ item(tt(zstyle -m) var(context) var(style) var(pattern))(
This builtin command is used to define and lookup styles. Styles are
pairs of names and values, where the values consist of any number of
strings. They are stored together with patterns and lookup is done by
-giving a string, called the `context', which is compared to the
-patterns. The definition stored for the first matching pattern will be
-returned.
+giving a string, called the `em(context)', which is matched against the
+patterns. The definition stored for the most specific pattern that matches
+will be returned.
-For ordering of comparisons, patterns are searched from most specific to
-least specific, and patterns that are equally specific keep the order in
-which they were defined. A pattern is considered to be more specific
+A pattern is considered to be more specific
than another if it contains more components (substrings separated by
colons) or if the patterns for the components are more specific, where
simple strings are considered to be more specific than patterns and
complex patterns are considered to be more specific than the pattern
-`tt(*)'.
+`tt(*)'. A `tt(*)' in the pattern will match zero or more characters
+in the context; colons are not treated specially in this regard.
+If two patterns are equally specific, the tie is broken in favour of
+the pattern that was defined first.
-The first form (without arguments) lists the definitions. Styles
+em(Example)
+
+For example, to define your preferred form of precipitation depending on which
+city you're in, you might set the following in your tt(zshrc):
+
+example(zstyle ':weather:europe:*' preferred-precipitation rain
+zstyle ':weather:europe:germany:* preferred-precipitation none
+zstyle ':weather:europe:germany:*:munich' preferred-precipitation snow)
+
+Then, the fictional `tt(weather)' plugin might run under the hood a command
+such as
+
+example(zstyle -s ":weather:${continent}:${country}:${county}:${city}" preferred-precipitation REPLY)
+
+in order to retrieve your preference into the scalar variable tt($REPLY).
+
+em(Usage)
+
+The forms that operate on patterns are the following.
+
+startitem()
+item(tt(zstyle) [ tt(-L) [ var(metapattern) [ var(style) ] ] ])(
+Without arguments, lists style definitions. Styles
are shown in alphabetic order and patterns are shown in the order
tt(zstyle) will test them.
If the tt(-L) option is given, listing is done in the form of calls to
-tt(zstyle). The optional first argument is a pattern which will be matched
-against the string supplied as the pattern for the context; note that
+tt(zstyle). The optional first argument, var(metapattern), is a pattern which
+will be matched against the string supplied as var(pattern) when the style was
+defined. Note:
this means, for example, `tt(zstyle -L ":completion:*")' will
match any supplied pattern beginning `tt(:completion:)', not
-just tt(":completion:*"): use tt(":completion:\*") to match that.
+just tt(":completion:*"): use tt(':completion:\*') to match that.
The optional second argument limits the output to a specific var(style) (not a
pattern). tt(-L) is not compatible with any other options.
-
-The other forms are the following:
-
-startitem()
+)
item(tt(zstyle) [ tt(-) | tt(-)tt(-) | tt(-e) ] var(pattern) var(style) var(string) ...)(
vindex(reply, use of)
Defines the given var(style) for the var(pattern) with the var(string)s as
@@ -74,24 +95,30 @@ combination is returned.
)
enditem()
-The other forms can be used to look up or test patterns.
+The other forms can be used to look up or test styles for a given context.
startitem()
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
spaces (or with the var(sep) string if that is given) between them.
+
+Return tt(0) if the style is set, tt(1) otherwise.
)
item(tt(zstyle -b) var(context) var(style) var(name))(
The value is stored in var(name) as a boolean, i.e. as the string
`tt(yes)' if the value has only one string and that string is equal to one
of `tt(yes)', `tt(true)', `tt(on)', or `tt(1)'. If the value is any other
string or has more than one string, the parameter is set to `tt(no)'.
+
+Return tt(0) if var(name) is set to `tt(yes)', tt(1) otherwise.
)
item(tt(zstyle -a) var(context) var(style) var(name))(
The value is stored in var(name) as an array. If var(name) is declared
as an associative array, the first, third, etc. strings are used as the
keys and the other strings are used as the values.
+
+Return tt(0) if the style is set, tt(1) otherwise.
)
xitem(tt(zstyle -t) var(context) var(style) [ var(string) ... ])
item(tt(zstyle -T) var(context) var(style) [ var(string) ... ])(
@@ -180,7 +207,7 @@ item(tt(zregexparse))(
This implements some internals of the tt(_regex_arguments) function.
)
findex(zparseopts)
-item(tt(zparseopts) [ tt(-D) tt(-K) tt(-M) tt(-E) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] [ tt(-) ] var(spec) ...)(
+item(tt(zparseopts) [ tt(-D) tt(-E) tt(-F) tt(-K) tt(-M) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] [ tt(-) ] var(spec) ...)(
This builtin simplifies the parsing of options in positional parameters,
i.e. the set of arguments given by tt($*). Each var(spec) describes one
option and must be of the form `var(opt)[tt(=)var(array)]'. If an option
@@ -195,7 +222,7 @@ Note that it is an error to give any var(spec) without an
Unless the tt(-E) option is given, parsing stops at the first string
that isn't described by one of the var(spec)s. Even with tt(-E),
parsing always stops at a positional parameter equal to `tt(-)' or
-`tt(-)tt(-)'.
+`tt(-)tt(-)'. See also tt(-F).
The var(opt) description must be one of the following. Any of the special
characters can appear in the option name provided it is preceded by a
@@ -234,9 +261,23 @@ first colon.
)
enditem()
+In all cases, option-arguments must appear either immediately following the
+option in the same positional parameter or in the next one. Even an optional
+argument may appear in the next parameter, unless it begins with a `tt(-)'.
+There is no special handling of `tt(=)' as with GNU-style argument parsers;
+given the var(spec) `tt(-foo:)', the positional parameter `tt(-)tt(-foo=bar)'
+is parsed as `tt(-)tt(-foo)' with an argument of `tt(=bar)'.
+
+When the names of two options that take no arguments overlap, the longest one
+wins, so that parsing for the var(spec)s `tt(-foo -foobar)' (for example) is
+unambiguous. However, due to the aforementioned handling of option-arguments,
+ambiguities may arise when at least one overlapping var(spec) takes an
+argument, as in `tt(-foo: -foobar)'. In that case, the last matching
+var(spec) wins.
+
The options of tt(zparseopts) itself cannot be stacked because, for
example, the stack `tt(-DEK)' is indistinguishable from a var(spec) for
-the GNU-style long option `tt(--DEK)'. The options of tt(zparseopts)
+the GNU-style long option `tt(-)tt(-DEK)'. The options of tt(zparseopts)
itself are:
startitem()
@@ -252,8 +293,29 @@ as the values.
item(tt(-D))(
If this option is given, all options found are removed from the positional
parameters of the calling shell or shell function, up to but not including
-any not described by the var(spec)s. This is similar to using the tt(shift)
-builtin.
+any not described by the var(spec)s. If the first such parameter is `tt(-)'
+or `tt(-)tt(-)', it is removed as well. This is similar to using the
+tt(shift) builtin.
+)
+item(tt(-E))(
+This changes the parsing rules to em(not) stop at the first string
+that isn't described by one of the var(spec)s. It can be used to test
+for or (if used together with tt(-D)) extract options and their
+arguments, ignoring all other options and arguments that may be in the
+positional parameters. As indicated above, parsing still stops at the
+first `tt(-)' or `tt(-)tt(-)' not described by a var(spec), but it is not
+removed when used with tt(-D).
+)
+item(tt(-F))(
+If this option is given, tt(zparseopts) immediately stops at the first
+option-like parameter not described by one of the var(spec)s, prints an
+error message, and returns status 1. Removal (tt(-D)) and extraction
+(tt(-E)) are not performed, and option arrays are not updated. This
+provides basic validation for the given options.
+
+Note that the appearance in the positional parameters of an option without
+its required argument always aborts parsing and returns an error as described
+above regardless of whether this option is used.
)
item(tt(-K))(
With this option, the arrays specified with the tt(-a) option and with the
@@ -272,13 +334,6 @@ is found, the values are stored as usual. This changes only the way the
values are stored, not the way tt($*) is parsed, so results may be
unpredictable if the `var(name)tt(+)' specifier is used inconsistently.
)
-item(tt(-E))(
-This changes the parsing rules to em(not) stop at the first string
-that isn't described by one of the var(spec)s. It can be used to test
-for or (if used together with tt(-D)) extract options and their
-arguments, ignoring all other options and arguments that may be in the
-positional parameters.
-)
enditem()
For example,
diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo
index bc182eb7b..fdea51412 100644
--- a/Doc/Zsh/options.yo
+++ b/Doc/Zsh/options.yo
@@ -88,6 +88,21 @@ tt(AUTO_CD) option set) is not a directory, and does not begin with a
slash, try to expand the expression as if it were preceded by a `tt(~)' (see
noderef(Filename Expansion)).
)
+pindex(CD_SILENT)
+pindex(NO_CD_SILENT)
+pindex(CDSILENT)
+pindex(NOCDSILENT)
+cindex(cd, silencing)
+cindex(autocd, silencing)
+item(tt(CD_SILENT))(
+Never print the working directory after a tt(cd) (whether explicit or
+implied with the tt(AUTO_CD) option set). tt(cd) normally prints the
+working directory when the argument given to it was tt(-), a stack entry, or
+the name of a directory found under tt(CDPATH). Note that this is distinct
+from tt(pushd)'s stack-printing behaviour, which is controlled by
+tt(PUSHD_SILENT). This option overrides the printing-related effects of
+tt(POSIX_CD).
+)
pindex(CHASE_DOTS)
pindex(NO_CHASE_DOTS)
pindex(CHASEDOTS)
@@ -133,7 +148,8 @@ ifzman(zmanref(zshbuiltins))\
ifnzman(noderef(Shell Builtin Commands)).
If the option is set, the shell does not test for directories beneath
the local directory (`tt(.)') until after all directories in tt(cdpath)
-have been tested.
+have been tested, and the tt(cd) and tt(chdir) commands do not recognise
+arguments of the form `{tt(PLUS())|tt(-)}var(n)' as directory stack entries.
Also, if the option is set, the conditions under which the shell
prints the new directory after changing to it are modified. It is
@@ -2318,7 +2334,9 @@ cindex(sh, field splitting style)
item(tt(SH_WORD_SPLIT) (tt(-y)) <K> <S>)(
Causes field splitting to be performed on unquoted parameter expansions.
Note that this option has nothing to do with word splitting.
-(See noderef(Parameter Expansion).)
+(See
+ifzman(zmanref(zshexpn))\
+ifnzman(noderef(Parameter Expansion)).)
)
pindex(TRAPS_ASYNC)
pindex(NO_TRAPS_ASYNC)
diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index 9ad228679..8daf33d5e 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -129,7 +129,7 @@ both var(key) and var(value) undergo all forms of expansion
allowed for single word shell expansions (this does not include filename
generation); these are as performed by the parameter expansion flag
tt(LPAR()e+RPAR()) as described in
-ifzman(zmanref(zshparam))\
+ifzman(zmanref(zshexpn))\
ifnzman(noderef(Parameter Expansion)).
Nested parentheses may surround var(value) and are included as part of the
value, which is joined into a plain string; this differs from ksh which
@@ -629,7 +629,7 @@ startitem()
vindex(!)
item(tt(!) <S>)(
The process ID of the last command started in the background with tt(&),
-or put into the background with the tt(bg) builtin.
+put into the background with the tt(bg) builtin, or spawned with tt(coproc).
)
vindex(#)
item(tt(#) <S>)(
@@ -1674,7 +1674,7 @@ For example, with the tt(EXTENDED_GLOB) option set, the following:
example(watch=('^(pws|barts)'))
-causes reports for activity assoicated with any user other than tt(pws)
+causes reports for activity associated with any user other than tt(pws)
or tt(barts).
)
vindex(WATCHFMT)
diff --git a/Doc/Zsh/redirect.yo b/Doc/Zsh/redirect.yo
index 7e38cd0c3..2b48974b4 100644
--- a/Doc/Zsh/redirect.yo
+++ b/Doc/Zsh/redirect.yo
@@ -42,18 +42,18 @@ otherwise, it is truncated to zero length.
xitem(tt(>|) var(word))
item(tt(>!) var(word))(
Same as tt(>), except that the file is truncated to zero length
-if it exists, even if tt(CLOBBER) is unset.
+if it exists, regardless of tt(CLOBBER).
)
item(tt(>>) var(word))(
Open file var(word) for writing in append mode as standard output.
-If the file does not exist, and the tt(CLOBBER)
-option is unset, this causes an error;
+If the file does not exist, and the tt(CLOBBER) and tt(APPEND_CREATE)
+options are both unset, this causes an error;
otherwise, the file is created.
)
xitem(tt(>>|) var(word))
item(tt(>>!) var(word))(
Same as tt(>>), except that the file is created if it does not
-exist, even if tt(CLOBBER) is unset.
+exist, regardless of tt(CLOBBER) and tt(APPEND_CREATE).
)
item(tt(<<)[tt(-)] var(word))(
The shell input is read up to a line that is the same as
@@ -182,7 +182,8 @@ indent(... tt({myfd}>&1))
This opens a new file descriptor that is a duplicate of file descriptor
1 and sets the parameter tt(myfd) to the number of the file descriptor,
which will be at least 10. The new file descriptor can be written to using
-the syntax tt(>&$myfd).
+the syntax tt(>&$myfd). The file descriptor remains open in subshells
+and forked external executables.
The syntax tt({)var(varid)tt(}>&-), for example tt({myfd}>&-), may be used
to close a file descriptor opened in this fashion. Note that the
diff --git a/Doc/Zsh/restricted.yo b/Doc/Zsh/restricted.yo
index 6cf9b36b5..33dfc96c6 100644
--- a/Doc/Zsh/restricted.yo
+++ b/Doc/Zsh/restricted.yo
@@ -37,3 +37,48 @@ Restricted mode can also be activated any time by setting the
tt(RESTRICTED) option. This immediately enables all the restrictions
described above even if the shell still has not processed all startup
files.
+
+A shell em(Restricted Mode) is an outdated way to restrict what users may
+do: modern systems have better, safer and more reliable ways to
+confine user actions, such as em(chroot jails), em(containers) and
+em(zones).
+
+A restricted shell is very difficult to implement safely. The feature
+may be removed in a future version of zsh.
+
+It is important to realise that the restrictions only apply to the shell,
+not to the commands it runs (except for some shell builtins). While a
+restricted shell can only run the restricted list of commands accessible
+via the predefined `tt(PATH)' variable, it does not prevent those
+commands from running any other command.
+
+As an example, if `tt(env)' is among the list of em(allowed) commands,
+then it allows the user to run any command as `tt(env)' is not a shell
+builtin command and can run arbitrary executables.
+
+So when implementing a restricted shell framework it is important to be
+fully aware of what actions each of the em(allowed) commands or features
+(which may be regarded as em(modules)) can perform.
+
+Many commands can have their behaviour affected by environment
+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
+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
+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.
+
+Bear in mind that, contrary to some other shells, `tt(readonly)' is not a
+security feature in zsh as it can be undone and so cannot be used to
+mitigate the above.
+
+A restricted shell only works if the allowed commands are few
+and carefully written so as not to grant more access to users than
+intended. It is also important to restrict what zsh module the user may
+load as some of them, such as `tt(zsh/system)', `tt(zsh/mapfile)' and
+`tt(zsh/files)', allow bypassing most of the restrictions.
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index c2b9f5430..c928b8ca2 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -2415,9 +2415,12 @@ directory, or changes to the value of variables referred to by the
prompt).
Otherwise, the prompt is only expanded each time zle starts, and
-when the display as been interrupted by output from another part of the
+when the display has been interrupted by output from another part of the
shell (such as a job notification) which causes the command line to be
reprinted.
+
+tt(reset-prompt) doesn't alter the special parameter tt(LASTWIDGET).
+
)
tindex(send-break)
item(tt(send-break) (tt(^G ESC-^G)) (unbound) (unbound))(
@@ -2726,10 +2729,10 @@ limited to 256 (i.e. the range 0 to 255).
Some modern terminal emulators have support for 24-bit true colour (16
million colours). In this case, the hex triplet format can be used. This
-consists of either a three or six digit hexadecimal number describing
-the red, green and blue components of the colour. Hex triplets can also
-be used with 88 and 256 colour terminals via the tt(zsh/nearcolor)
-module (see ifzman(zmanref(zshmodules))\
+consists of a `tt(#)' followed by either a three or six digit hexadecimal
+number describing the red, green and blue components of the colour. Hex
+triplets can also be used with 88 and 256 colour terminals via the
+tt(zsh/nearcolor) module (see ifzman(zmanref(zshmodules))\
ifnzman(noderef(The zsh/nearcolor Module))\
).
generated by cgit v1.2.3 (git 2.39.1) at 2025-08-02 13:59:43 +0000