summaryrefslogtreecommitdiff
path: root/Doc/Zsh
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/Zsh')
-rw-r--r--Doc/Zsh/arith.yo21
-rw-r--r--Doc/Zsh/builtins.yo20
-rw-r--r--Doc/Zsh/calsys.yo21
-rw-r--r--Doc/Zsh/compat.yo2
-rw-r--r--Doc/Zsh/compsys.yo34
-rw-r--r--Doc/Zsh/cond.yo37
-rw-r--r--Doc/Zsh/contrib.yo158
-rw-r--r--Doc/Zsh/expn.yo81
-rw-r--r--Doc/Zsh/grammar.yo61
-rw-r--r--Doc/Zsh/mod_pcre.yo11
-rw-r--r--Doc/Zsh/mod_regex.yo1
-rw-r--r--Doc/Zsh/mod_sched.yo2
-rw-r--r--Doc/Zsh/mod_zutil.yo10
-rw-r--r--Doc/Zsh/options.yo90
-rw-r--r--Doc/Zsh/params.yo37
-rw-r--r--Doc/Zsh/prompt.yo40
-rw-r--r--Doc/Zsh/roadmap.yo1
-rw-r--r--Doc/Zsh/tcpsys.yo4
-rw-r--r--Doc/Zsh/zle.yo87
19 files changed, 541 insertions, 177 deletions
diff --git a/Doc/Zsh/arith.yo b/Doc/Zsh/arith.yo
index 2674c7817..96dc2dc68 100644
--- a/Doc/Zsh/arith.yo
+++ b/Doc/Zsh/arith.yo
@@ -76,6 +76,27 @@ have output base 16, while tt(x) (assuming it does not already exist) is
implicitly typed by the arithmetic evaluation, where it acquires the output
base 8.
+The var(base) may be replaced or followed by an underscore, which may
+itself be followed by a positive integer (if it is missing the value 3
+is used). This indicates that underscores should be inserted into the
+output string, grouping the number for visual clarity. The following
+integer specifies the number of digits to group together. For example:
+
+example(setopt cbases
+print $(( [#16_4] 65536 ** 2 )))
+
+outputs `tt(0x1_0000_0000)'.
+
+The feature can be used with floating
+point numbers, in which case the base must be omitted; grouping
+is away from the decimal point. For example,
+
+example(zmodload zsh/mathfunc
+print $(( [#_] sqrt+LPAR()1e7+RPAR() )))
+
+outputs `tt(3_162.277_660_168_379_5)' (the number of decimal places
+shown may vary).
+
pindex(C_BASES, use of)
pindex(OCTAL_ZEROES, use of)
If the tt(C_BASES) option is set, hexadecimal numbers in the standard C
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 8c7bc85ea..f709f5020 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -3,8 +3,6 @@ chapter(Shell Builtin Commands)
ifzman(\
sect(Shell Builtin Commands)
)\
-cindex(builtin commands)
-cindex(commands, builtin)
def(prefix)(1)(\
item(tt(ARG1) var(simple command))(
See noderef(Precommand Modifiers).
@@ -29,6 +27,8 @@ ifnzman(noderef(Zle Builtins)).
)\
)\
+cindex(builtin commands)
+cindex(commands, builtin)
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
@@ -653,7 +653,7 @@ cindex(history, editing)
cindex(editing history)
xitem(tt(fc) [ tt(-e) var(ename) ] [ tt(-m) var(match) ] [ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ])
xitem(tt(fc) tt(-l) [ tt(-nrdfEiD) ] [ tt(-t) var(timefmt) ] [ tt(-m) var(match) ])
-xitem( [ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ])
+xitem(tt( )[ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ])
xitem(tt(fc) tt(-p) [ tt(-a) ] [ var(filename) [ var(histsize) [ var(savehistsize) ] ] ])
xitem(tt(fc) tt(-P))
item(tt(fc) tt(-ARWI) [ var(filename) ])(
@@ -683,6 +683,9 @@ If var(first) is not specified, it will be set to -1 (the most recent
event), or to -16 if the tt(-l) flag is given.
If var(last) is not specified, it will be set to var(first),
or to -1 if the tt(-l) flag is given.
+However, if the current event has added entries to the history with
+`tt(print -s)' or `tt(fc -R)', then the default var(last) for tt(-l)
+includes all new history entries since the current event began.
The flag tt(-r) reverses the order of the commands and the
flag tt(-n) suppresses command numbers when listing.
@@ -1285,8 +1288,7 @@ continuation and backslashes in the line don't quote the following
character and are not removed.
)
item(tt(-s))(
-Don't echo back characters if reading from the terminal. Currently does
-not work with the tt(-q) option.
+Don't echo back characters if reading from the terminal.
)
item(tt(-q))(
Read only one character from the terminal and set var(name) to
@@ -1500,12 +1502,15 @@ POSIX standard, but tt(setopt) is not.
)
findex(shift)
cindex(parameters, positional)
-item(tt(shift) [ var(n) ] [ var(name) ... ])(
+item(tt(shift) [ tt(-p) ] [ var(n) ] [ var(name) ... ])(
The positional parameters tt(${)var(n)PLUS()1tt(}) ... are renamed
to tt($1) ..., where var(n) is an arithmetic expression that
defaults to 1.
If any var(name)s are given then the arrays with these names are
shifted instead of the positional parameters.
+
+If the option tt(-p) is given arguments are instead removed (popped)
+from the end rather than the start of the array.
)
findex(source)
item(tt(source) var(file) [ var(arg) ... ])(
@@ -1934,6 +1939,9 @@ 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(-r))(Maximum real time priority. On some systems where this
+is not available, such as NetBSD, this has the same effect as tt(-T)
+for compatibility with tt(sh).)
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.)
diff --git a/Doc/Zsh/calsys.yo b/Doc/Zsh/calsys.yo
index 7dc51ab11..0d7abbf86 100644
--- a/Doc/Zsh/calsys.yo
+++ b/Doc/Zsh/calsys.yo
@@ -547,35 +547,36 @@ and status 2 if the wrong number of arguments were passed; it also sets the
parameter tt(reply) to an empty associative array. Otherwise,
it returns status 0 and sets elements of the associative
array tt(reply) as follows:
+
startsitem()
-sitem(time)(The time as a string of digits in the same units as
+sitem(tt(time))(The time as a string of digits in the same units as
tt($EPOCHSECONDS))
-sitem(schedtime)(The regularly scheduled time. This may differ from
+sitem(tt(schedtime))(The regularly scheduled time. This may differ from
the actual event time tt(time) if this is a recurring event and the next
occurrence has been rescheduled. Then tt(time) gives the actual time
and tt(schedtime) the time of the regular recurrence before modification.)
-sitem(text1)(The text from the line not including the date and time of the
+sitem(tt(text1))(The text from the line not including the date and time of the
event, but including any tt(WARN) or tt(RPT) keywords and values.)
-sitem(warntime)(Any warning time given by the tt(WARN) keyword as a string
+sitem(tt(warntime))(Any warning time given by the tt(WARN) keyword as a string
of digits containing the time at which to warn in the same units as
tt($EPOCHSECONDS). (Note this is an absolute time, not the relative time
passed down.) Not set no tt(WARN) keyword and value were
matched.)
-sitem(warnstr)(The raw string matched after the tt(WARN) keyword, else unset.)
-sitem(rpttime)(Any recurrence time given by the tt(RPT) keyword as a string
+sitem(tt(warnstr))(The raw string matched after the tt(WARN) keyword, else unset.)
+sitem(tt(rpttime))(Any recurrence time given by the tt(RPT) keyword as a string
of digits containing the time of the recurrence in the same units
as tt($EPOCHSECONDS). (Note this is an absolute time.) Not set if
no tt(RPT) keyword and value were matched.)
-sitem(schedrpttime)(The next regularly scheduled occurrence of a recurring
+sitem(tt(schedrpttime))(The next regularly scheduled occurrence of a recurring
event before modification. This may differ from tt(rpttime), which is the
actual time of the event that may have been rescheduled from the regular
time.)
-sitem(rptstr)(The raw string matched after the tt(RPT) keyword, else unset.)
-sitem(text2)(The text from the line after removal of the date and any
+sitem(tt(rptstr))(The raw string matched after the tt(RPT) keyword, else unset.)
+sitem(tt(text2))(The text from the line after removal of the date and any
keywords and values.)
)
endsitem()
-)
+
findex(calendar_showdate)
item(tt(calendar_showdate) [ tt(-r) ] [ tt(-f) var(fmt) ] var(date-spec ...))(
The given var(date-spec) is interpreted and the corresponding date and
diff --git a/Doc/Zsh/compat.yo b/Doc/Zsh/compat.yo
index bf97fe2ae..f1be15fee 100644
--- a/Doc/Zsh/compat.yo
+++ b/Doc/Zsh/compat.yo
@@ -6,7 +6,7 @@ cindex(ksh compatibility)
Zsh tries to emulate bf(sh) or bf(ksh) when it is invoked as
tt(sh) or tt(ksh) respectively; more precisely, it looks at the first
letter of the name by which it was invoked, excluding any initial `tt(r)'
-(assumed to stand for `restricted'), and if that is `tt(s)' or `tt(k)' it
+(assumed to stand for `restricted'), and if that is `tt(b)', `tt(s)' or `tt(k)' it
will emulate bf(sh) or bf(ksh). Furthermore, if invoked as tt(su) (which
happens on certain systems when the shell is executed by the tt(su)
command), the shell will try to find an alternative name from the tt(SHELL)
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index b9038cfa5..8a9f47db1 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -1995,11 +1995,11 @@ only be performed with the `tt(*)' inserted.
kindex(matcher, completion style)
item(tt(matcher))(
This style is tested separately for each tag valid in the current
-context. Its value is added to any match specifications given by the
+context. Its value is tried before any match specifications given by the
tt(matcher-list) style. It 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.
)
kindex(matcher-list, completion style)
item(tt(matcher-list))(
@@ -2019,12 +2019,14 @@ specification is prefixed with tt(+), it is added to the existing list.
Hence it is possible to create increasingly general specifications
without repetition:
-example(zstyle ':completion:*' matcher-list '' '+m{a-z}={A-Z}' '+m{A-Z}={a-z}')
+example(zstyle ':completion:*' matcher-list '' '+m:{a-z}={A-Z}' '+m:{A-Z}={a-z}')
It is possible to create match specifications valid for particular
-completers by using the third field of the context. For example, to
-use the completers tt(_complete) and tt(_prefix) but only allow
-case-insensitive completion with tt(_complete):
+completers by using the third field of the context. This applies only
+to completers that override the global matcher-list, which as of this
+writing includes only tt(_prefix) and tt(_ignored). For example, to
+use the completers tt(_complete) and tt(_prefix) but allow
+case-insensitive completion only with tt(_complete):
example(zstyle ':completion:*' completer _complete _prefix
zstyle ':completion:*:complete:*' matcher-list \
@@ -2344,7 +2346,7 @@ This is used by the tt(_history) completer and the
tt(_history_complete_word) bindable command to decide which words
should be completed.
-If it is a singe number, only the last var(N) words from the history
+If it is a single number, only the last var(N) words from the history
will be completed.
If it is a range of the form `var(max)tt(:)var(slice)',
@@ -2440,6 +2442,15 @@ completing words for the dict command. It allows words from different
dictionary databases to be added separately.
The default for this style is `false'.
)
+kindex(show-ambiguity, completion style)
+item(tt(show-ambiguity))(
+If the tt(zsh/complist) module is loaded, this style can be used to
+highlight the first ambiguous character in completion lists. The
+value is either a color indication such as those supported by the
+tt(list-colors) style or, with a value of tt(true), a default of
+underlining is selected. The highlighting is only applied if the
+completion display strings correspond to the actual matches.
+)
kindex(show-completer, completion style)
item(tt(show-completer))(
Tested whenever a new completer is tried. If it is true, the completion
@@ -3038,6 +3049,15 @@ This function is also a bindable command, see
ifzman(the section `Bindable Commands' below)\
ifnzman(noderef(Bindable Commands)).
)
+findex(_extensions)
+item(tt(_extensions))(
+If the cursor follows the string `tt(*.)', filename extensions are
+completed. The extensions are taken from files in current directory or a
+directory specified at the beginning of the current word. For exact matches,
+completion continues to allow other completers such as tt(_expand) to
+expand the pattern. The standard tt(add-space) and tt(prefix-hidden)
+styles are observed.
+)
findex(_history)
item(tt(_history))(
Complete words from the shell's command history. This completer
diff --git a/Doc/Zsh/cond.yo b/Doc/Zsh/cond.yo
index 9f8a7d820..d04ceb258 100644
--- a/Doc/Zsh/cond.yo
+++ b/Doc/Zsh/cond.yo
@@ -186,11 +186,44 @@ true if either var(exp1) or var(exp2) is true.
)
enditem()
+For compatibility, if there is a single argument that is not
+syntactically significant, typically a variable, the condition is
+treated as a test for whether the expression expands as a string of
+non-zero length. In other words, tt([[ $var ]]) is the same as tt([[ -n
+$var ]]). It is recommended that the second, explicit, form be used
+where possible.
+
Normal shell expansion is performed on the var(file), var(string) and
var(pattern) arguments, but the result of each expansion is constrained to
be a single word, similar to the effect of double quotes.
-Filename generation is not performed on any form of argument to conditions.
-However, pattern metacharacters are active for the var(pattern) arguments;
+
+Filename generation is not performed on any form of argument to
+conditions. However, it can be forced in any case where normal shell
+expansion is valid and when the option tt(EXTENDED_GLOB) is in effect by
+using an explicit glob qualifier of the form tt(LPAR()#q+RPAR()) at the
+end of the string. A normal glob qualifier expression may appear
+between the `tt(q)' and the closing parenthesis; if none appears the
+expression has no effect beyond causing filename generation. The
+results of filename generation are joined together to form a single
+word, as with the results of other forms of expansion.
+
+This special use of filename generation is only available with the
+tt([[) syntax. If the condition occurs within the tt([) or tt(test)
+builtin commands then globbing occurs instead as part of normal command
+line expansion before the condition is evaluated. In this case it may
+generate multiple words which are likely to confuse the syntax of the
+test command.
+
+For example,
+
+tt([[ -n file*(#qN) ]])
+
+produces status zero if and only if there is at least one file in the
+current directory beginning with the string `tt(file)'. The globbing
+qualifier tt(N) ensures that the expression is empty if there is
+no matching file.
+
+Pattern metacharacters are active for the var(pattern) arguments;
the patterns are the same as those used for filename generation, see
ifzman(\
zmanref(zshexpn)\
diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index bb6613ece..1c1a66a3b 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -45,9 +45,8 @@ shell features as well. The autoloadable tt(run-help) function, found in
tt(Functions/Misc), searches for these helpfiles and performs several
other tests to produce the most complete help possible for the command.
-There may already be a directory of help files on your system; look in
-tt(/usr/share/zsh) or tt(/usr/local/share/zsh) and subdirectories below
-those, or ask your system administrator.
+Help files are installed by default to a subdirectory of tt(/usr/share/zsh)
+or tt(/usr/local/share/zsh).
To create your own help files with tt(helpfiles), choose or create a
directory where the individual command help files will reside. For
@@ -55,22 +54,22 @@ example, you might choose tt(~/zsh_help). If you unpacked the zsh
distribution in your home directory, you would use the commands:
example(mkdir ~/zsh_help
-cd ~/zsh_help
-man zshall | colcrt - | \
-perl ~/zsh-version()/Util/helpfiles)
+perl ~/zsh-version()/Util/helpfiles ~/zsh_help)
+
+vindex(HELPDIR)
+The tt(HELPDIR) parameter tells tt(run-help) where to look for the help
+files. When unset, it uses the default installation path.
+To use your own set of help files, set this to the appropriate path
+in one of your startup files:
+
+example(HELPDIR=~/zsh_help)
findex(run-help, use of)
-Next, to use the tt(run-help) function, you need to add lines something
+To use the tt(run-help) function, you need to add lines something
like the following to your tt(.zshrc) or equivalent startup file:
example(unalias run-help
-autoload run-help
-HELPDIR=~/zsh_help)
-
-vindex(HELPDIR)
-The tt(HELPDIR) parameter tells tt(run-help) where to look for the help
-files. If your system already has a help file directory installed, set
-tt(HELPDIR) to the path of that directory instead.
+autoload run-help)
Note that in order for `tt(autoload run-help)' to work, the tt(run-help)
file must be in one of the directories named in your tt(fpath) array (see
@@ -827,17 +826,32 @@ item(tt(check-for-changes))(
If enabled, this style causes the tt(%c) and tt(%u) format escapes to show
when the working directory has uncommitted changes. The strings displayed by
these escapes can be controlled via the tt(stagedstr) and tt(unstagedstr)
-styles. The only backends that currently support this option are tt(git) and
-tt(hg) (tt(hg) only supports unstaged).
+styles. The only backends that currently support this option are tt(git),
+tt(hg), and tt(bzr) (the latter two only support unstaged).
For this style to be evaluated with the tt(hg) backend, the tt(get-revision)
style needs to be set and the tt(use-simple) style needs to be unset. The
latter is the default; the former is not.
+With the tt(bzr) backend, em(lightweight checkouts) only honor this style if
+the tt(use-server) style is set.
+
Note, the actions taken if this style is enabled are potentially expensive
(read: they may be slow, depending on how big the current repository is).
Therefore, it is disabled by default.
)
+kindex(check-for-staged-changes)
+item(tt(check-for-staged-changes))(
+This style is like tt(check-for-changes), but it never checks the worktree
+files, only the metadata in the tt(.${vcs}) dir. Therefore,
+this style initializes only the tt(%c) escape (with tt(stagedstr)) but
+not the tt(%u) escape. This style is faster than tt(check-for-changes).
+
+In the tt(git) backend, this style checks for changes in the index.
+Other backends do not currently implement this style.
+
+This style is disabled by default.
+)
kindex(stagedstr)
item(tt(stagedstr))(
This string will be used in the tt(%c) escape if there are staged changes in
@@ -863,7 +877,7 @@ when this style is looked up.
For example, this style can be used to use binaries from non-default
installation directories. Assume, tt(git) is installed in /usr/bin but
-your sysadmin installed a newer version in /usr/bin/local. Instead of
+your sysadmin installed a newer version in /usr/local/bin. Instead of
changing the order of your tt($PATH) parameter, you can do this:
example(zstyle ':vcs_info:git:*:-all-' command /usr/local/bin/git)
)
@@ -881,6 +895,9 @@ backend is only usable if you have set the environment variable
tt(P4CONFIG) to a file name and have corresponding files in the root
directories of each Perforce client. See comments in the function
tt(VCS_INFO_detect_p4) for more detail.
+
+The Bazaar backend (tt(bzr)) uses this to permit contacting the server
+about lightweight checkouts, see the tt(check-for-changes) style.
)
kindex(use-simple)
item(tt(use-simple))(
@@ -942,6 +959,7 @@ sitem(tt(enable))(ALL)
sitem(tt(disable))((empty list))
sitem(tt(disable-patterns))((empty list))
sitem(tt(check-for-changes))(false)
+sitem(tt(check-for-staged-changes))(false)
sitem(tt(stagedstr))((string: "S"))
sitem(tt(unstagedstr))((string: "U"))
sitem(tt(command))((empty string))
@@ -1321,6 +1339,11 @@ This hooks is called when no version control system was detected.
The `hook_com' parameter is not used.
)
+item(tt(post-backend))(
+Called as soon as the backend has finished collecting information.
+
+The `tt(hook_com)' keys available are as for the tt(set-message) hook.
+)
item(tt(post-quilt))(
Called after the tt(quilt) support is done. The following information
is passed as arguments to the hook: 1. the quilt-support mode (`addon' or
@@ -1481,22 +1504,15 @@ function +vi-hgbookmarks+LPAR()RPAR() {
# This makes the bookmarks string use only those
# bookmarks. If there's more than one, it
# concatenates them using commas.
- local s i
# The bookmarks returned by `hg' are available in
- # the functions positional parameters.
- (( $# == 0 )) && return 0
- for i in "$@"; do
- if [[ $i == sh/* ]]; then
- [[ -n $s ]] && s=$s,
- s=${s}$i
- fi
- done
+ # the function's positional parameters.
+ local s="${(Mj:,:)@:#sh/*}"
# Now, the communication with the code that calls
# the hook functions is done via the hook_com[]
- # hash. The key, at which the `gen-hg-bookmark-string'
- # hook looks at is `hg-bookmark-string'. So:
+ # hash. The key at which the `gen-hg-bookmark-string'
+ # hook looks is `hg-bookmark-string'. So:
hook_com[hg-bookmark-string]=$s
- # And to signal, that we want to use the sting we
+ # And to signal that we want to use the string we
# just generated, set the special variable `ret' to
# something other than the default zero:
ret=1
@@ -1874,6 +1890,12 @@ Edit the command line using your visual editor, as in tt(ksh).
example(bindkey -M vicmd v edit-command-line)
)
+tindex(expand-absolute-path)
+item(tt(expand-absolute-path))(
+Expand the file name under the cursor to an absolute path, resolving
+symbolic links. Where possible, the initial path segment is turned
+into a named directory or reference to a user's home directory.
+)
tindex(history-beginning-search-backward-end)
tindex(history-beginning-search-forward-end)
item(tt(history-search-end))(
@@ -2306,6 +2328,32 @@ The name is a slight misnomer, as in fact the shell's own minibuffer is
not used. Hence it is still possible to call tt(executed-named-cmd) and
similar functions while reading a value.
)
+tindex(replace-argument)
+tindex(replace-argument-edit)
+item(tt(replace-argument), tt(replace-argument-edit))
+(
+The function tt(replace-argument) can be used to replace a command
+line argument in the current command line or, if the current command
+line is empty, in the last command line executed (the new command line
+is not executed). Arguments are as delimited by standard shell syntax,
+
+If a numeric argument is given, that specifies the argument to be
+replaced. 0 means the command name, as in history expansion.
+A negative numeric argument counts backward from the last word.
+
+If no numeric argument is given, the current argument is replaced;
+this is the last argument if the previous history line is being used.
+
+The function prompts for a replacement argument.
+
+If the widget contains the string tt(edit), for example is defined as
+
+example(zle -N replace-argument-edit replace-argument)
+
+then the function presents the current value of the argument for
+editing, otherwise the editing buffer for the replacement is
+initially empty.
+)
tindex(replace-string)
tindex(replace-string-again)
tindex(replace-pattern)
@@ -2444,6 +2492,25 @@ The style tt(whence) is available in the context tt(:zle:$WIDGET); this
may be set to an array to give the command and options that will be used to
investigate the command word found. The default is tt(whence -c).
)
+tindex(zcalc-auto-insert)
+item(tt(zcalc-auto-insert))(
+This function is useful together with the tt(zcalc) function described in
+ifzman(the section Mathematical Functions)\
+ifnzman(noderef(Mathematical Functions)).
+It should be bound to a key representing a binary operator such
+as `tt(PLUS())', `tt(-)', `tt(*)' or `tt(/)'. When running in zcalc,
+if the key occurs at the start of the line or immediately following
+an open parenthesis, the text tt("ans ") is inserted before the
+representation of the key itself. This allows easy use of the
+answer from the previous calculation in the current line. The
+text to be inserted before the symbol typed can be modified by setting
+the variable tt(ZCALC_AUTO_INSERT_PREFIX).
+
+Hence, for example, typing `tt(PLUS()12)' followed by return adds 12
+to the previous result.
+
+When not in zcalc, the key simply inserts the symbol itself.
+)
enditem()
subsect(Utility Functions)
@@ -2899,7 +2966,7 @@ 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)));
+ifnzman(noderef(Modifiers));
this means that symbolic links are resolved where possible, so that
links into other file systems behave in the correct fashion.
)
@@ -3370,21 +3437,22 @@ by the prompt theme system (ifzman(see above)\
ifnzman(noderef(Prompt Themes))). You seldom should need to run
tt(colors) more than once.
-The eight base colors are: black, red, green, yellow, blue, magenta, cyan,
-and white. Each of these has codes for foreground and background. In
-addition there are eight intensity attributes: bold, faint, standout,
-underline, blink, reverse, and conceal. Finally, there are six codes used
-to negate attributes: none (reset all attributes to the defaults), normal
-(neither bold nor faint), no-standout, no-underline, no-blink, and
-no-reverse.
+The eight base colors are: tt(black), tt(red), tt(green), tt(yellow),
+tt(blue), tt(magenta), tt(cyan), and tt(white). Each of these has codes for
+foreground and background. In addition there are seven intensity attributes:
+tt(bold), tt(faint), tt(standout), tt(underline), tt(blink), tt(reverse),
+and tt(conceal). Finally, there are seven codes used to negate attributes:
+tt(none) (reset all attributes to the defaults), tt(normal)
+(neither bold nor faint), tt(no-standout), tt(no-underline), tt(no-blink),
+tt(no-reverse), and tt(no-conceal).
Some terminals do not support all combinations of colors and intensities.
The associative arrays are:
startitem()
-xitem(color)
-item(colour)(
+xitem(tt(color))
+item(tt(colour))(
Map all the color names to their integer codes, and integer codes to the
color names. The eight base names map to the foreground color codes, as
do names prefixed with `tt(fg-)', such as `tt(fg-red)'. Names prefixed
@@ -3395,16 +3463,16 @@ and the tt(bg-) form for backgrounds.
Although it is a misnomer to call them `colors', these arrays also map the
other fourteen attributes from names to codes and codes to names.
)
-xitem(fg)
-xitem(fg_bold)
-item(fg_no_bold)(
+xitem(tt(fg))
+xitem(tt(fg_bold))
+item(tt(fg_no_bold))(
Map the eight basic color names to ANSI terminal escape sequences that set
the corresponding foreground text properties. The tt(fg) sequences change
the color without changing the eight intensity attributes.
)
-xitem(bg)
-xitem(bg_bold)
-item(bg_no_bold)(
+xitem(tt(bg))
+xitem(tt(bg_bold))
+item(tt(bg_no_bold))(
Map the eight basic color names to ANSI terminal escape sequences that set
the corresponding background properties. The tt(bg) sequences change the
color without changing the eight intensity attributes.
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index 5ba3e21af..d01d804d2 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -1,7 +1,7 @@
texinode(Expansion)(Parameters)(Prompt Expansion)(Top)
chapter(Expansion)
-cindex(expansion)
ifnztexi(sect(Description))
+cindex(expansion)
The following types of expansions are performed in the indicated order in
five steps:
@@ -636,6 +636,30 @@ Similar to the preceding subsitution, but in the opposite sense,
so that entries present in both the original substitution and as
elements of var(arrayname) are retained and others removed.
)
+xitem(tt(${)var(name)tt(:^)var(arrayname)tt(}))
+item(tt(${)var(name)tt(:^^)var(arrayname)tt(}))(
+Zips two arrays, such that the output array is twice as long as the
+shortest (longest for `tt(:^^)') of tt(name) and tt(arrayname), with
+the elements alternatingly being picked from them. For `tt(:^)', if one
+of the input arrays is longer, the output will stop when the end of the
+shorter array is reached. Thus,
+
+example(a=(1 2 3 4); b=(a b); print ${a:^b})
+
+will output `tt(1 a 2 b)'. For `tt(:^^)', then the input is repeated
+until all of the longer array has been used up and the above will output
+`tt(1 a 2 b 3 a 4 b)'.
+
+Either or both inputs may be a scalar, they will be treated as an array
+of length 1 with the scalar as the only element. If either array is empty,
+the other array is output with no extra elements inserted.
+
+Currently the following code will output `tt(a b)' and `tt(1)' as two separate
+elements, which can be unexpected. The second print provides a workaround which
+should continue to work if this is changed.
+
+example(a=(a b); b=(1 2); print -l "${a:^b}"; print -l "${${a:^b}}")
+)
xitem(tt(${)var(name)tt(:)var(offset)tt(}))
item(tt(${)var(name)tt(:)var(offset)tt(:)var(length)tt(}))(
This syntax gives effects similar to parameter subscripting
@@ -1407,16 +1431,21 @@ item(tt(19.) em(Ordering))(
If the result is still an array and one of the `tt((o))' or `tt((O))' flags
was present, the array is reordered.
)
-item(tt(20.) em(Re-evaluation))(
+item(tt(20.) tt(RC_EXPAND_PARAM))(
+At this point the decision is made whether any resulting array elements
+are to be combined element by element with surrounding text, as given
+by either the tt(RC_EXPAND_PARAM) option or the `tt(^)' flag.
+)
+item(tt(21.) em(Re-evaluation))(
Any `tt((e))' flag is applied to the value, forcing it to be re-examined
for new parameter substitutions, but also for command and arithmetic
substitutions.
)
-item(tt(21.) em(Padding))(
+item(tt(22.) em(Padding))(
Any padding of the value by the `tt(LPAR()l.)var(fill)tt(.RPAR())' or
`tt(LPAR()r.)var(fill)tt(.RPAR())' flags is applied.
)
-item(tt(22.) em(Semantic joining))(
+item(tt(23.) em(Semantic joining))(
In contexts where expansion semantics requires a single word to
result, all words are rejoined with the first character of tt(IFS)
between. So in `tt(${LPAR()P)tt(RPAR()${LPAR()f)tt(RPAR()lines}})'
@@ -1425,7 +1454,7 @@ joined again before the tt(P) flag can be applied.
If a single word is not required, this rule is skipped.
)
-item(tt(23.) em(Empty argument removal))(
+item(tt(24.) em(Empty argument removal))(
If the substitution does not appear in double quotes, any resulting
zero-length argument, whether from a scalar or an element of an array,
is elided from the list of arguments inserted into the command line.
@@ -1539,6 +1568,16 @@ specified in any of the three numbers, specifying it in the third can be useful
to pad for example `tt({-99..100..01})' which is not possible to specify by putting a
0 on either of the first two numbers (i.e. pad to two characters).
+An expression of the form `tt({)var(c1)tt(..)var(c2)tt(})', where
+var(c1) and var(c2) are single characters (which may be multibyte
+characters), is expanded to every character in the range from var(c1) to
+var(c2) in whatever character sequence is used internally. For
+characters with code points below 128 this is US ASCII (this is the only
+case most users will need). If any intervening character is not
+printable, appropriate quotation is used to render it printable.
+If the character sequence is reversed, the output is in reverse
+order, e.g. `tt({d..a})' is substituted as `tt(d c b a)'.
+
If a brace expression matches none of the above forms, it is left
unchanged, unless the option tt(BRACE_CCL) (an abbreviation for `brace
character class') is set.
@@ -1962,7 +2001,7 @@ except that recursive directory searching is not supported.)
)
item(tt(PLUS()LPAR())...tt(RPAR()))(
Match at least one occurrence. (Like `tt(LPAR())...tt(RPAR()##)',
-except that recursive directory searching is not supported..)
+except that recursive directory searching is not supported.)
)
item(tt(?LPAR())...tt(RPAR()))(
Match zero or one occurrence. (Like `tt(LPAR()|)...tt(RPAR())'.)
@@ -2295,7 +2334,13 @@ contained within it are balanced; appearance of `tt(|)', `tt(LPAR())' or
recognised in this form even if a bare glob qualifier exists at the end of
the pattern, for example `tt(*(#q*)(.))' will recognise executable regular
files if both options are set; however, mixed syntax should probably be
-avoided for the sake of clarity.
+avoided for the sake of clarity. Note that within conditions using the
+`tt([[)' form the presence of a parenthesised expression
+tt(LPAR()#q...+RPAR()) at the end of a string indicates that globbing
+should be performed; the expression may include glob qualifiers, but
+it is also valid if it is simply tt(LPAR()#q+RPAR()). This does
+not apply to the right hand side of pattern match operators as the
+syntax already has special significance.
A qualifier may be any one of the following:
@@ -2511,10 +2556,12 @@ item(tt(L)[tt(PLUS())|tt(-)]var(n))(
files less than var(n) bytes (tt(-)), more than var(n) bytes (tt(PLUS())), or
exactly var(n) bytes in length.
-If this flag is directly followed by a `tt(k)' (`tt(K)'), `tt(m)'
-(`tt(M)'), or `tt(p)' (`tt(P)') (e.g. `tt(Lk-50)') the check is performed
-with kilobytes, megabytes, or blocks (of 512 bytes) instead. In this
-case a file is regarded as "exactly" the size if the file size rounded up
+If this flag is directly followed by a em(size specifier) `tt(k)' (`tt(K)'),
+`tt(m)' (`tt(M)'), or `tt(p)' (`tt(P)') (e.g. `tt(Lk-50)') the check is
+performed with kilobytes, megabytes, or blocks (of 512 bytes) instead.
+(On some systems additional specifiers are available for gigabytes,
+`tt(g)' or `tt(G)', and terabytes, `tt(t)' or `tt(T)'.) If a size specifier
+is used a file is regarded as "exactly" the size if the file size rounded up
to the next unit is equal to the test size. Hence `tt(*LPAR()Lm1+RPAR())'
matches files from 1 byte up to 1 Megabyte inclusive. Note also that
the set of files "less than" the test size only includes files that would
@@ -2548,9 +2595,16 @@ item(tt(n))(
sets the tt(NUMERIC_GLOB_SORT) option for the current pattern
pindex(NUMERIC_GLOB_SORT, setting in pattern)
)
+item(tt(Y)var(n))(
+enables short-circuit mode: the pattern will expand to at most var(n)
+filenames. If more than var(n) matches exist, only the first var(n)
+matches in directory traversal order will be considered.
+
+Implies tt(oN) when no tt(o)var(c) qualifier is used.
+)
item(tt(o)var(c))(
specifies how the names of the files should be sorted. If var(c) is
-tt(n) they are sorted by name (the default); if it is tt(L) they
+tt(n) they are sorted by name; if it is tt(L) they
are sorted depending on the size (length) of the files; if tt(l)
they are sorted by the number of links; if tt(a), tt(m), or tt(c)
they are sorted by the time of the last access, modification, or
@@ -2565,6 +2619,9 @@ so `tt(*(^-oL))' gives a list of all files sorted by file size in descending
order, following any symbolic links. Unless tt(oN) is used, multiple order
specifiers may occur to resolve ties.
+The default sorting is tt(n) (by name) unless the tt(Y) glob qualifier is used,
+in which case it is tt(N) (unsorted).
+
tt(oe) and tt(o+) are special cases; they are each followed by shell code,
delimited as for the tt(e) glob qualifier and the tt(+) glob qualifier
respectively (see above). The code is executed for each matched file with
diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo
index b452e4cc9..77f0098e3 100644
--- a/Doc/Zsh/grammar.yo
+++ b/Doc/Zsh/grammar.yo
@@ -19,7 +19,11 @@ cindex(simple commands)
cindex(commands, simple)
A em(simple command) is a sequence of optional parameter
assignments followed by blank-separated words,
-with optional redirections interspersed.
+with optional redirections interspersed. For a description
+of assignment, see the beginning of
+ifnzman(noderef(Parameters))\
+ifzman(zmanref(zshparam)).
+
The first word is the command to be executed, and the remaining
words, if any, are arguments to the command.
If a command name is given, the parameter assignments modify
@@ -312,7 +316,7 @@ during the tt(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(always-list).
+normal shell status tt($?) is the value returned from tt(try-list).
This will be non-zero if there was an error, even if tt(TRY_BLOCK_ERROR)
was set to zero.
@@ -465,37 +469,38 @@ shell constructs such as loops or conditions; this somewhat illogical
behaviour can be recovered by setting the option tt(CONTINUE_ON_ERROR).
Fatal errors found in non-interactive shells include:
-startlist()
-list(Failure to parse shell options passed when invoking the shell)
-list(Failure to change options with the tt(set) builtin)
-list(Parse errors of all sorts, including failures to parse
+
+startitemize()
+itemiz(Failure to parse shell options passed when invoking the shell)
+itemiz(Failure to change options with the tt(set) builtin)
+itemiz(Parse errors of all sorts, including failures to parse
mathematical expressions)
-list(Failures to set or modify variable behaviour with tt(typeset),
+itemiz(Failures to set or modify variable behaviour with tt(typeset),
tt(local), tt(declare), tt(export), tt(integer), tt(float))
-list(Execution of incorrectly positioned loop control structures
+itemiz(Execution of incorrectly positioned loop control structures
(tt(continue), tt(break)))
-list(Attempts to use regular expression with no regular expression
+itemiz(Attempts to use regular expression with no regular expression
module available)
-list(Disallowed operations when the tt(RESTRICTED) options is set)
-list(Failure to create a pipe needed for a pipeline)
-list(Failure to create a multio)
-list(Failure to autoload a module needed for a declared shell feature)
-list(Errors creating command or process substitutions)
-list(Syntax errors in glob qualifiers)
-list(File generation errors where not caught by the option tt(BAD_PATTERN))
-list(All bad patterns used for matching within case statements)
-list(File generation failures where not caused by tt(NO_MATCH) or
-list(All file generation errors where the pattern was used to create a
-multio)
-list(Memory errors where detected by the shell)
-list(Invalid subscripts to shell variables)
-list(Attempts to assign read-only variables)
-list(Logical errors with variables such as assignment to the wrong type)
-list(Use of invalid variable names)
-list(Errors in variable substitution syntax)
-list(Failure to convert characters in tt($')...tt(') expressions)
+itemiz(Disallowed operations when the tt(RESTRICTED) options is set)
+itemiz(Failure to create a pipe needed for a pipeline)
+itemiz(Failure to create a multio)
+itemiz(Failure to autoload a module needed for a declared shell feature)
+itemiz(Errors creating command or process substitutions)
+itemiz(Syntax errors in glob qualifiers)
+itemiz(File generation errors where not caught by the option tt(BAD_PATTERN))
+itemiz(All bad patterns used for matching within case statements)
+itemiz(File generation failures where not caused by tt(NO_MATCH) or
similar options)
-endlist()
+itemiz(All file generation errors where the pattern was used to create a
+multio)
+itemiz(Memory errors where detected by the shell)
+itemiz(Invalid subscripts to shell variables)
+itemiz(Attempts to assign read-only variables)
+itemiz(Logical errors with variables such as assignment to the wrong type)
+itemiz(Use of invalid variable names)
+itemiz(Errors in variable substitution syntax)
+itemiz(Failure to convert characters in tt($')...tt(') expressions)
+enditemize()
If the tt(POSIX_BUILTINS) option is set, more errors associated with
shell builtin commands are treated as fatal, as specified by the POSIX
diff --git a/Doc/Zsh/mod_pcre.yo b/Doc/Zsh/mod_pcre.yo
index 9b8d9d6a7..faada28de 100644
--- a/Doc/Zsh/mod_pcre.yo
+++ b/Doc/Zsh/mod_pcre.yo
@@ -72,6 +72,7 @@ print -l $accum
enditem()
The tt(zsh/pcre) module makes available the following test condition:
+
startitem()
findex(pcre-match)
item(expr tt(-pcre-match) pcre)(
@@ -79,6 +80,14 @@ Matches a string against a perl-compatible regular expression.
For example,
-[[ "$text" -pcre-match ^d+$ ]] && print text variable contains only "d's".
+example([[ "$text" -pcre-match ^d+$ ]] &&
+print text variable contains only "d's".)
+
+pindex(REMATCH_PCRE)
+pindex(NO_CASE_MATCH)
+If the tt(REMATCH_PCRE) option is set, the tt(=~) operator is equivalent to
+tt(-pcre-match), and the tt(NO_CASE_MATCH) option may be used. Note that
+tt(NO_CASE_MATCH) never applies to the tt(pcre_match) builtin, instead use
+the tt(-i) switch of tt(pcre_compile).
)
enditem()
diff --git a/Doc/Zsh/mod_regex.yo b/Doc/Zsh/mod_regex.yo
index 4081810ed..f20451664 100644
--- a/Doc/Zsh/mod_regex.yo
+++ b/Doc/Zsh/mod_regex.yo
@@ -4,6 +4,7 @@ Interface to the POSIX regex library.
cindex(regular expressions)
cindex(regex)
The tt(zsh/regex) module makes available the following test condition:
+
startitem()
findex(regex-match)
item(var(expr) tt(-regex-match) var(regex))(
diff --git a/Doc/Zsh/mod_sched.yo b/Doc/Zsh/mod_sched.yo
index 948001baf..2d8d77c7a 100644
--- a/Doc/Zsh/mod_sched.yo
+++ b/Doc/Zsh/mod_sched.yo
@@ -48,7 +48,7 @@ enditem()
startitem()
vindex(zsh_scheduled_events)
-item(zsh_scheduled_events)(
+item(tt(zsh_scheduled_events))(
A readonly array corresponding to the events scheduled by the
tt(sched) builtin. The indices of the array correspond to the numbers
shown when tt(sched) is run with no arguments (provided that the
diff --git a/Doc/Zsh/mod_zutil.yo b/Doc/Zsh/mod_zutil.yo
index 726b0f055..ee9ec3adf 100644
--- a/Doc/Zsh/mod_zutil.yo
+++ b/Doc/Zsh/mod_zutil.yo
@@ -251,10 +251,12 @@ any not described by the var(specs). This is similar to using the tt(shift)
builtin.
)
item(tt(-K))(
-With this option, the arrays specified with the tt(-a) and tt(-A)
-options and with the `tt(=)var(array)' forms are kept unchanged when none
-of the var(specs) for them is used. This allows assignment of default
-values to them before calling tt(zparseopts).
+With this option, the arrays specified with the tt(-a) option and with the
+`tt(=)var(array)' forms are kept unchanged when none of the var(specs) for
+them is used. Otherwise the entire array is replaced when any of the
+var(specs) is used. Individual elements of associative arrays specified
+with the tt(-A) option are preserved by tt(-K). This allows assignment of
+default values to arrays before calling tt(zparseopts).
)
item(tt(-M))(
This changes the assignment rules to implement a map among equivalent
diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo
index 3c6ea63b8..ec1f1645a 100644
--- a/Doc/Zsh/options.yo
+++ b/Doc/Zsh/options.yo
@@ -971,6 +971,23 @@ The file will still be periodically re-written to trim it when the
number of lines grows 20% beyond the value specified by
tt($SAVEHIST) (see also the HIST_SAVE_BY_COPY option).
)
+pindex(INC_APPEND_HISTORY_TIME)
+pindex(NO_INC_APPEND_HISTORY_TIME)
+pindex(INCAPPENDHISTORYTIME)
+pindex(NOINCAPPENDHISTORYTIME)
+cindex(history, incremental appending to a file with time)
+item(tt(INC_APPEND_HISTORY_TIME))(
+This option is a variant of tt(INC_APPEND_HISTORY) in which, where
+possible, the history entry is written out to the file after the
+command is finished, so that the time taken by the command is recorded
+correctly in the history file in tt(EXTENDED_HISTORY) format. This
+means that the history entry will not be available immediately from
+other instances of the shell that are using the same history file.
+
+This option is only useful if tt(INC_APPEND_HISTORY) and
+tt(SHARE_HISTORY) are turned off. The three options should be
+considered mutually exclusive.
+)
pindex(SHARE_HISTORY)
pindex(NO_SHARE_HISTORY)
pindex(SHAREHISTORY)
@@ -981,10 +998,10 @@ item(tt(SHARE_HISTORY) <K>)(
This option both imports new commands from the history file, and also
causes your typed commands to be appended to the history file (the
-latter is like specifying tt(INC_APPEND_HISTORY)).
-The history lines are also output with timestamps ala
-tt(EXTENDED_HISTORY) (which makes it easier to find the spot where
-we left off reading the file after it gets re-written).
+latter is like specifying tt(INC_APPEND_HISTORY), which should be turned
+off if this option is in effect). The history lines are also output
+with timestamps ala tt(EXTENDED_HISTORY) (which makes it easier to find
+the spot where we left off reading the file after it gets re-written).
By default, history movement commands visit the imported lines as
well as the local lines, but you can toggle this on and off with the
@@ -994,8 +1011,9 @@ some include them.
If you find that you want more control over when commands
get imported, you may wish to turn tt(SHARE_HISTORY) off,
-tt(INC_APPEND_HISTORY) on, and then manually import
-commands whenever you need them using `tt(fc -RI)'.
+tt(INC_APPEND_HISTORY) or tt(INC_APPEND_HISTORY_TIME) (see above) on,
+and then manually import commands whenever you need them using `tt(fc
+-RI)'.
)
enditem()
@@ -1098,6 +1116,9 @@ pindex(CORRECTALL)
pindex(NOCORRECTALL)
item(tt(CORRECT_ALL) (tt(-O)))(
Try to correct the spelling of all arguments in a line.
+
+The shell variable tt(CORRECT_IGNORE_FILE) may be set to a pattern to
+match file names that will never be offered as corrections.
)
pindex(DVORAK)
pindex(NO_DVORAK)
@@ -1174,7 +1195,7 @@ pindex(NOHASHEXECUTABLESONLY)
cindex(hashing, of executables)
cindex(executables, hashing)
item(tt(HASH_EXECUTABLES_ONLY))(
-When hashing commands because of tt(HASH_COMMANDS), check that the
+When hashing commands because of tt(HASH_CMDS), check that the
file to be hashed is actually an executable. This option
is unset by default as if the path contains a large number of commands,
or consists of many remote files, the additional tests can take
@@ -1202,7 +1223,7 @@ Thus if `tt(/usr/local/bin)' is in the user's path, and he or she types
(assuming it exists).
Commands explicitly beginning with `tt(/)', `tt(./)' or `tt(../)'
are not subject to the path search.
-This also applies to the `tt(.)' builtin.
+This also applies to the `tt(.)' and tt(source) builtins.
Note that subdirectories of the current directory are always searched for
executables specified in this form. This takes place before any search
@@ -1605,7 +1626,25 @@ pindex(NOFUNCTIONARGZERO)
cindex($0, setting)
item(tt(FUNCTION_ARGZERO) <C> <Z>)(
When executing a shell function or sourcing a script, set tt($0)
-temporarily to the name of the function/script.
+temporarily to the name of the function/script. Note that toggling
+tt(FUNCTION_ARGZERO) from on to off (or off to on) does not change the
+current value of tt($0). Only the state upon entry to the function or
+script has an effect. Compare tt(POSIX_ARGZERO).
+)
+pindex(LOCAL_LOOPS)
+pindex(NO_LOCAL_LOOPS)
+pindex(LOCALLOOPS)
+pindex(NOLOCALLOOPS)
+cindex(break, inside function)
+cindex(continue, inside function)
+cindex(function, scope of break and continue)
+item(tt(LOCAL_LOOPS))(
+When this option is not set, the effect of tt(break) and tt(continue)
+commands may propagate outside function scope, affecting loops in
+calling functions. When the option is set in a calling function, a
+tt(break) or a tt(continue) that is not caught within a called function
+(regardless of the setting of the option within that function)
+produces a warning and the effect is cancelled.
)
pindex(LOCAL_OPTIONS)
pindex(NO_LOCAL_OPTIONS)
@@ -1615,10 +1654,10 @@ item(tt(LOCAL_OPTIONS) <K>)(
If this option is set at the point of return from a shell function,
most options (including this one) which were in force upon entry to
the function are restored; options that are not restored are
-tt(PRIVILEGED) and tt(RESTRICTED). Otherwise, only this option and the
-tt(XTRACE) and tt(PRINT_EXIT_VALUE) options are restored. Hence
-if this is explicitly unset by a shell function the other options in
-force at the point of return will remain so.
+tt(PRIVILEGED) and tt(RESTRICTED). Otherwise, only this option,
+and the tt(LOCAL_LOOPS), tt(XTRACE) and tt(PRINT_EXIT_VALUE) options are
+restored. Hence if this is explicitly unset by a shell function the
+other options in force at the point of return will remain so.
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).
@@ -1942,6 +1981,26 @@ as one unit, so aliases defined within the argument are not available even
in later lines. If in doubt, avoid use of aliases in non-interactive
code.
)
+pindex(POSIX_ARGZERO)
+pindex(NO_POSIX_ARGZERO)
+pindex(POSIXARGZERO)
+pindex(NOPOSIXARGZERO)
+cindex($0, using)
+item(tt(POSIX_ARGZERO))(
+This option may be used to temporarily disable tt(FUNCTION_ARGZERO) and
+thereby restore the value of tt($0) to the name used to invoke the shell
+(or as set by the tt(-c) command line option). For compatibility with
+previous versions of the shell, emulations use tt(NO_FUNCTION_ARGZERO)
+instead of tt(POSIX_ARGZERO), which may result in unexpected scoping of
+tt($0) if the emulation mode is changed inside a function or script.
+To avoid this, explicitly enable tt(POSIX_ARGZERO) in the tt(emulate)
+command:
+
+example(emulate sh -o POSIX_ARGZERO)
+
+Note that tt(NO_POSIX_ARGZERO) has no effect unless tt(FUNCTION_ARGZERO)
+was already enabled upon entry to the function or script.
+)
pindex(POSIX_BUILTINS)
pindex(NO_POSIX_BUILTINS)
pindex(POSIXBUILTINS)
@@ -2037,7 +2096,10 @@ When the is option is set, the usual zsh behaviour of executing
traps for tt(EXIT) on exit from shell functions is suppressed.
In that case, manipulating tt(EXIT) traps always alters the global
trap for exiting the shell; the tt(LOCAL_TRAPS) option is
-ignored for the tt(EXIT) trap.
+ignored for the tt(EXIT) trap. Furthermore, a tt(return) statement
+executed in a trap with no argument passes back from the function the
+value from the surrounding context, not from code executed within the
+trap.
)
pindex(SH_FILE_EXPANSION)
pindex(NO_SH_FILE_EXPANSION)
diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index 935fd5d86..dbac51182 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -21,14 +21,20 @@ indent(var(name)tt(=)var(value))
If the integer attribute, tt(-i), is set for var(name), the var(value)
is subject to arithmetic evaluation. Furthermore, by replacing `tt(=)'
-with `tt(+=)', a parameter can be added or appended to. See
+with `tt(+=)', a parameter can be added or appended to.
+
+In scalar assignment, var(value) is expanded as a single string, in
+which the elements of arrays are joined together; filename expansion is
+not performed unless the option tt(GLOB_ASSIGN) is set. See
noderef(Array Parameters) for additional forms of assignment.
To refer to the value of a parameter, write `tt($)var(name)' or
`tt(${)var(name)tt(})'. See
ifzman(em(Parameter Expansion) in zmanref(zshexpn))\
ifnzman(noderef(Parameter Expansion))
-for complete details.
+for complete details. This section also explains the effect
+of the difference between scalar and array assignment on parameter
+expansion.
In the parameter lists that follow, the mark `<S>' indicates that the
parameter is special.
@@ -541,9 +547,11 @@ The exit status returned by the last command.
)
vindex(0)
item(tt(0) <S>)(
-The name used to invoke the current shell. If the tt(FUNCTION_ARGZERO) option
-is set, this is set temporarily within a shell function to the name of the
-function, and within a sourced script to the name of the script.
+The name used to invoke the current shell, or as set by the tt(-c) command
+line option upon invocation. If the tt(FUNCTION_ARGZERO) option is set,
+tt($0) is set upon entry to a shell function to the name of the function,
+and upon entry to a sourced script to the name of the script, and reset to
+its previous value when the function or script returns.
)
vindex(status)
item(tt(status) <S> <Z>)(
@@ -599,9 +607,10 @@ group ID by `tt(LPAR()GID=)var(gid)tt(; command+RPAR())'
)
vindex(HISTCMD)
item(tt(HISTCMD))(
-The current history line number in an interactive shell, in other
-words the line number for the command that caused tt($HISTCMD)
-to be read.
+The current history event number in an interactive shell, in other
+words the event number for the command that caused tt($HISTCMD)
+to be read. If the current history event modifies the history,
+tt(HISTCMD) changes to the new maximum history event number.
)
vindex(HOST)
item(tt(HOST))(
@@ -620,7 +629,9 @@ item(tt(LOGNAME))(
If the corresponding variable is not set in the environment of the
shell, it is initialized to the login name corresponding to the
current login session. This parameter is exported by default but
-this can be disabled using the tt(typeset) builtin.
+this can be disabled using the tt(typeset) builtin. The value
+is set to the string returned by the manref(getlogin)(3) system call
+if that is available.
)
vindex(MACHTYPE)
item(tt(MACHTYPE))(
@@ -914,6 +925,14 @@ of file names, as applied by the tt(CORRECT_ALL) option (so with the
example just given files beginning with `tt(_)' in the current
directory would still be completed).
)
+vindex(CORRECT_IGNORE_FILE)
+item(tt(CORRECT_IGNORE_FILE))(
+If set, is treated as a pattern during spelling correction of file names.
+Any file name that matches the pattern is never offered as a correction.
+For example, if the value is `tt(.*)' then dot file names will never be
+offered as spelling corrections. This is useful with the
+tt(CORRECT_ALL) option.
+)
vindex(DIRSTACKSIZE)
item(tt(DIRSTACKSIZE))(
The maximum size of the directory stack, by default there is no limit. If the
diff --git a/Doc/Zsh/prompt.yo b/Doc/Zsh/prompt.yo
index eab15d29d..0ed52b580 100644
--- a/Doc/Zsh/prompt.yo
+++ b/Doc/Zsh/prompt.yo
@@ -185,6 +185,13 @@ sitem(tt(%K))(the hour of the day on the 24-hour clock)
sitem(tt(%L))(the hour of the day on the 12-hour clock)
endsitem()
+In addition, if the system supports the POSIX tt(gettimeofday) system
+call, tt(%.) provides decimal fractions of a second since the epoch with
+leading zeroes. By default three decimal places are provided, but a
+number of digits up to 6 may be given following the tt(%); hence tt(%6.)
+outputs microseconds. A typical example of this is the format
+`tt(%D{%H:%M:%S.%.})'.
+
The GNU extension that a `tt(-)' between the tt(%) and the
format character causes a leading zero or space to be stripped
is handled directly by the shell for the format characters tt(d), tt(f),
@@ -273,7 +280,8 @@ and var(false-text) may both contain arbitrarily-nested escape
sequences, including further ternary expressions.
The left parenthesis may be preceded or followed by a positive integer var(n),
-which defaults to zero. A negative integer will be multiplied by -1.
+which defaults to zero. A negative integer will be multiplied by -1, except
+as noted below for `tt(l)'.
The test character var(x) may be any of the following:
startsitem()
@@ -295,7 +303,9 @@ sitem(tt(g))(True if the effective gid of the current process is var(n).)
sitem(tt(j))(True if the number of jobs is at least var(n).)
sitem(tt(L))(True if the tt(SHLVL) parameter is at least var(n).)
sitem(tt(l))(True if at least var(n) characters have already been
-printed on the current line.)
+printed on the current line. When var(n) is negative, true if at least
+tt(abs)tt(LPAR())var(n)tt(RPAR()) characters remain before the opposite
+margin (thus the left margin for tt(RPROMPT)).)
sitem(tt(S))(True if the tt(SECONDS) parameter is at least var(n).)
sitem(tt(T))(True if the time in hours is equal to var(n).)
sitem(tt(t))(True if the time in minutes is equal to var(n).)
@@ -311,13 +321,21 @@ item(tt(%[)var(xstring)tt(]))(
Specifies truncation behaviour for the remainder of the prompt string.
The third, deprecated, form is equivalent to `tt(%)var(xstringx)',
i.e. var(x) may be `tt(<)' or `tt(>)'.
-The numeric argument, which in the third form may appear immediately
-after the `tt([)', specifies the maximum permitted length of
-the various strings that can be displayed in the prompt.
The var(string) will be displayed in
place of the truncated portion of any string; note this does not
undergo prompt expansion.
+The numeric argument, which in the third form may appear immediately
+after the `tt([)', specifies the maximum permitted length of
+the various strings that can be displayed in the prompt.
+In the first two forms, this numeric argument may be negative, in which
+case the truncation length is determined by subtracting the absolute
+value of the numeric argument from the number of character positions
+remaining on the current prompt line. If this results in a zero or
+negative length, a length of 1 is used. In other words, a negative
+argument arranges that after truncation at least var(n) characters
+remain before the right margin (left margin for tt(RPROMPT)).
+
The forms with `tt(<)' truncate at the left of the string,
and the forms with `tt(>)' truncate at the right of the string.
For example, if the current directory is `tt(/home/pike)',
@@ -337,11 +355,19 @@ string, or to the end of the next enclosing group of the `tt(%LPAR())'
construct, or to the next truncation encountered at the same grouping
level (i.e. truncations inside a `tt(%LPAR())' are separate), which
ever comes first. In particular, a truncation with argument zero
-(e.g. `tt(%<<)') marks the end of the range of the string to be
+(e.g., `tt(%<<)') marks the end of the range of the string to be
truncated while turning off truncation from there on. For example, the
prompt '%10<...<%~%<<%# ' will print a truncated representation of the
current directory, followed by a `tt(%)' or `tt(#)', followed by a
space. Without the `tt(%<<)', those two characters would be included
-in the string to be truncated.
+in the string to be truncated. Note that `tt(%-0<<)' is a distinct
+
+Truncation applies only within each individual line of the prompt, as
+delimited by embedded newlines (if any). If the total length of any line
+of the prompt after truncation is greater than the terminal width, or if
+the part to be truncated contains embedded newlines, truncation behavior
+is undefined and may change in a future version of the shell. Use
+`tt(%-var(n)LPAR()l.var(true-text).var(false-text)RPAR())' to remove parts
+of the prompt when the available space is less than var(n).
)
enditem()
diff --git a/Doc/Zsh/roadmap.yo b/Doc/Zsh/roadmap.yo
index fd87c74ab..ba598e5ea 100644
--- a/Doc/Zsh/roadmap.yo
+++ b/Doc/Zsh/roadmap.yo
@@ -1,7 +1,6 @@
texinode(Roadmap)(Invocation)(Introduction)(Top)
chapter(Roadmap)
cindex(roadmap)
-
The Zsh Manual, like the shell itself, is large and often complicated.
This section of the manual provides some pointers to areas of the shell
that are likely to be of particular interest to new users, and indicates
diff --git a/Doc/Zsh/tcpsys.yo b/Doc/Zsh/tcpsys.yo
index 599335bc9..1e26054ce 100644
--- a/Doc/Zsh/tcpsys.yo
+++ b/Doc/Zsh/tcpsys.yo
@@ -666,6 +666,10 @@ expression `tt(%c)' expands to 1 if the session being read is the current
session, else 0; this is most useful in ternary expressions such as
`tt(%LPAR()c.-.PLUS()RPAR())' which outputs `tt(PLUS())' if the session is
the current one, else `tt(-)'.
+
+If the prompt starts with tt(%P), this is stripped and the complete
+result of the previous stage is passed through standard prompt tt(%)-style
+formatting before being output.
)
vindex(TCP_READ_DEBUG)
item(tt(TCP_READ_DEBUG))(
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index 2d7756859..2a907c52c 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -252,6 +252,9 @@ Bind each var(in-string) to each var(out-string).
When var(in-string) is typed, var(out-string) will be
pushed back and treated as input to the line editor.
When tt(-R) is also used, interpret the var(in-string)s as ranges.
+
+Note that both var(in-string) and var(out-string) are subject to the same
+form of interpretation, as described below.
)
item(var(in-string command) ...)(
Bind each var(in-string) to each var(command).
@@ -492,26 +495,35 @@ Only available if your system supports one of the `poll' or `select' system
calls; most modern systems do.
Installs var(handler) (the name of a shell function) to handle input from
-file descriptor var(fd). When zle is attempting to read data, it will
-examine both the terminal and the list of handled var(fd)'s. If data
-becomes available on a handled var(fd), zle will call var(handler) with
-the fd which is ready for reading as the only argument. If the handler
-produces output to the terminal, it should call `tt(zle -I)' before doing
-so (see below). The handler should not attempt to read from the terminal.
-Note that zle makes no attempt to check whether this fd is actually
+file descriptor var(fd). Installing a handler for an var(fd) which is
+already handled causes the existing handler to be replaced. Any number of
+handlers for any number of readable file descriptors may be installed.
+Note that zle makes no attempt to check whether this var(fd) is actually
readable when installing the handler. The user must make their own
arrangements for handling the file descriptor when zle is not active.
-If the option tt(-w) is also given, the var(handler) is instead a
-line editor widget, typically a shell function made into a widget using
-tt(zle -N). In that case var(handler) can use all the facilities of
-zle to update the current editing line. Note, however, that as handling
-var(fd) takes place at a low level changes to the display will not
-automatically appear; the widget should call tt(zle -R) to force redisplay.
-
-Any number of handlers for any number of readable file descriptors may be
-installed. Installing a handler for an var(fd) which is already handled
-causes the existing handler to be replaced.
+When zle is attempting to read data, it will examine both the terminal and
+the list of handled var(fd)'s. If data becomes available on a handled
+var(fd), zle calls var(handler) with the fd which is ready for reading
+as the first argument. Under normal circumstances this is the only
+argument, but if an error was detected, a second argument provides
+details: `tt(hup)' for a disconnect, `tt(nval)' for a closed or otherwise
+invalid descriptor, or `tt(err)' for any other condition. Systems that
+support only the `select' system call always use `tt(err)'.
+
+If the option tt(-w) is also given, the var(handler) is instead a line
+editor widget, typically a shell function made into a widget using
+`tt(zle -N)'. In that case var(handler) can use all the facilities of zle
+to update the current editing line. Note, however, that as handling var(fd)
+takes place at a low level changes to the display will not automatically
+appear; the widget should call `tt(zle -R)' to force redisplay. As of this
+writing, widget handlers only support a single argument and thus are never
+passed a string for error state, so widgets must be prepared to test the
+descriptor themselves.
+
+If either type of handler produces output to the terminal, it should call
+`tt(zle -I)' before doing so (see below). Handlers should not attempt to
+read from the terminal.
If no var(handler) is given, but an var(fd) is present, any handler for
that var(fd) is removed. If there is none, an error message is printed
@@ -526,7 +538,8 @@ silently return status 1.
Note that this feature should be used with care. Activity on one of the
var(fd)'s which is not properly handled can cause the terminal to become
-unusable.
+unusable. Removing an var(fd) handler from within a signal trap may cause
+unpredictable behavior.
Here is a simple example of using this feature. A connection to a remote
TCP port is created using the ztcp command; see
@@ -536,6 +549,7 @@ which simply prints out any data which arrives on this connection. Note
that `select' will indicate that the file descriptor needs handling
if the remote side has closed the connection; we handle that by testing
for a failed read.
+
example(if ztcp pwspc 2811; then
tcpfd=$REPLY
handler+LPAR()RPAR() {
@@ -716,17 +730,18 @@ vindex(CONTEXT)
item(tt(CONTEXT) (scalar))(
The context in which zle was called to read a line; read-only. One of
the values:
+
startitem()
-item(start)(
+item(tt(start))(
The start of a command line (at prompt tt(PS1)).
)
-item(cont)(
+item(tt(cont))(
A continuation to a command line (at prompt tt(PS2)).
)
-item(select)(
+item(tt(select))(
In a tt(select) loop.
)
-item(vared)(
+item(tt(vared))(
Editing a variable in tt(vared).
)
enditem()
@@ -863,21 +878,21 @@ is needed for character indexing to include tt(PREDISPLAY).
Each string consists of the following parts:
-startlist()
-list(Optionally, a `tt(P)' to signify that the start and end offset that
+startitemize()
+itemiz(Optionally, a `tt(P)' to signify that the start and end offset that
follow include any string set by the tt(PREDISPLAY) special parameter;
this is needed if the predisplay string itself is to be highlighted.
Whitespace may follow the `tt(P)'.)
-list(A start offset in the same units as tt(CURSOR), terminated by
+itemiz(A start offset in the same units as tt(CURSOR), terminated by
whitespace.)
-list(An end offset in the same units as tt(CURSOR), terminated by
+itemiz(An end offset in the same units as tt(CURSOR), terminated by
whitespace.)
-list(A highlight specification in the same format as
+itemiz(A highlight specification in the same format as
used for contexts in the parameter tt(zle_highlight),
ifnzman(noderef(Character Highlighting))\
ifzman(see Character Highlighting below);
for example, tt(standout) or tt(fg=red,bold)).
-endlist()
+enditemize()
For example,
@@ -1293,8 +1308,11 @@ item(tt(redisplay))(
Redisplay the command line, remaining in incremental search mode.
)
item(tt(vi-cmd-mode))(
-Toggle between the `tt(main)' and `tt(vicmd)' keymaps;
+Select the `tt(vicmd)' keymap;
the `tt(main)' keymap (insert mode) will be selected initially.
+
+In addition, the modifications that were made while in vi insert mode are
+merged to form a single undo event.
)
xitem(tt(vi-repeat-search))
item(tt(vi-rev-repeat-search))(
@@ -2191,6 +2209,13 @@ tindex(spell-word)
item(tt(spell-word) (ESC-$ ESC-S ESC-s) (unbound) (unbound))(
Attempt spelling correction on the current word.
)
+tindex(split-undo)
+item(tt(split-undo))(
+Breaks the undo sequence at the current change. This is useful in vi mode as
+changes made in insert mode are coalesced on entering command mode. Similarly,
+tt(undo) will normally revert as one all the changes made by a user-defined
+widget.
+)
tindex(undefined-key)
item(tt(undefined-key))(
This command is executed when a key sequence that is not bound to any
@@ -2202,6 +2227,10 @@ Incrementally undo the last text modification. When called from a
user-defined widget, takes an optional argument indicating a previous state
of the undo history as returned by the tt(UNDO_CHANGE_NO) variable;
modifications are undone until that state is reached.
+
+Note that when invoked from vi command mode, the full prior change made in
+insert mode is reverted, the changes having been merged when command mode was
+selected.
)
tindex(redo)
item(tt(redo))(
generated by cgit v1.2.3 (git 2.39.1) at 2025-06-16 04:18:10 +0000