summaryrefslogtreecommitdiff
path: root/Doc/Zsh
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/Zsh')
-rw-r--r--Doc/Zsh/builtins.yo102
-rw-r--r--Doc/Zsh/compsys.yo204
-rw-r--r--Doc/Zsh/compwid.yo7
-rw-r--r--Doc/Zsh/cond.yo9
-rw-r--r--Doc/Zsh/contrib.yo229
-rw-r--r--Doc/Zsh/exec.yo15
-rw-r--r--Doc/Zsh/expn.yo65
-rw-r--r--Doc/Zsh/jobs.yo4
-rw-r--r--Doc/Zsh/mod_complist.yo4
-rw-r--r--Doc/Zsh/mod_curses.yo6
-rw-r--r--Doc/Zsh/mod_mathfunc.yo5
-rw-r--r--Doc/Zsh/mod_sched.yo5
-rw-r--r--Doc/Zsh/mod_zleparameter.yo16
-rw-r--r--Doc/Zsh/mod_zutil.yo10
-rw-r--r--Doc/Zsh/options.yo5
-rw-r--r--Doc/Zsh/params.yo64
-rw-r--r--Doc/Zsh/redirect.yo19
-rw-r--r--Doc/Zsh/restricted.yo10
-rw-r--r--Doc/Zsh/zle.yo109
19 files changed, 734 insertions, 154 deletions
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index fb630a713..7b04d0648 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -81,6 +81,10 @@ then commands are read from that file instead of var(file).
If any arguments var(arg) are given,
they become the positional parameters; the old positional
parameters are restored when the var(file) is done executing.
+However, if no arguments are given,
+the positional parameters remain those of the calling context,
+and no restoring is done.
+
If var(file) was not found the return status is 127; if var(file) was found
but contained a syntax error the return status is 126; else the return
status is the exit status of the last command executed.
@@ -566,7 +570,7 @@ with emulations to be set to their values in tt(sh). tt(fno) then
calls tt(fni); because tt(fni) is also marked for sticky tt(sh)
emulation, no option changes take place on entry to or exit from it.
Hence the option tt(cshnullglob), turned off by tt(sh) emulation, will
-be turned on within tt(fni) and remain on on return to tt(fno). On exit
+be turned on within tt(fni) and remain on return to tt(fno). On exit
from tt(fno), the emulation mode and all options will be restored to the
state they were in before entry to the temporary emulation.
@@ -652,7 +656,7 @@ An EOF condition will also cause the shell to exit, unless
the tt(IGNORE_EOF) option is set.
See notes at the end of
-ifzman(the section JOBS in in zmanref(zshmisc))\
+ifzman(the section JOBS in zmanref(zshmisc))\
ifnzman(noderef(Jobs & Signals)) for some possibly unexpected interactions
of the tt(exit) command with jobs.
)
@@ -693,7 +697,7 @@ specifies the most recent event beginning with the given string. All
substitutions var(old)tt(=)var(new), if any, are then performed on the
text of the events.
-In addition to the the number range,
+In addition to the number range,
startsitem()
sitem(tt(-I))(restricts to only internal events (not from tt($HISTFILE)))
sitem(tt(-L))(restricts to only local events (not from other shells, see
@@ -1079,6 +1083,7 @@ startsitem()
sitem(var(n)tt(h))(hours)
sitem(var(n)tt(k))(kilobytes (default))
sitem(var(n)tt(m))(megabytes or minutes)
+sitem(var(n)tt(g))(gigabytes)
sitem([var(mm)tt(:)]var(ss))(minutes and seconds)
endsitem()
@@ -1284,7 +1289,9 @@ required by the format than have been specified, the behaviour is as if
zero or an empty string had been specified as the argument.
The tt(-v) option causes the output to be stored as the value of the
-parameter var(name), instead of printed.
+parameter var(name), instead of printed. If var(name) is an array and
+the format string is reused when consuming arguments then one
+array element will be used for each use of the format string.
)
findex(pushd)
pindex(PUSHD_TO_HOME, use of)
@@ -1753,7 +1760,8 @@ xitem(SPACES()[ tt(+) | var(SCALAR)[tt(=)var(value)] var(array)[tt(=LPAR())var(v
item(tt(typeset) tt(-f) [ {tt(PLUS())|tt(-)}tt(TUkmtuz) ] [ tt(+) ] [ var(name) ... ])(
Set or display attributes and values for shell parameters.
-A parameter is created for each var(name) that does not already refer
+Except as noted below for control flags that change the behavior,
+a parameter is created for each var(name) that does not already refer
to one. When inside a function, a new parameter is created for every
var(name) (even those that already exist), and is unset again when the
function completes. See
@@ -1763,18 +1771,31 @@ ifnzman(noderef(Local Parameters))\
retain their special attributes when made local.
For each var(name)tt(=)var(value) assignment, the parameter
-var(name) is set to var(value). All forms of the command
-handle scalar assignment.
+var(name) is set to var(value).
+
+If the shell option tt(TYPESET_SILENT) is not set, for each remaining
+var(name) that refers to a parameter that is already set, the name and
+value of the parameter are printed in the form of an assignment.
+Nothing is printed for newly-created parameters, or when any attribute
+flags listed below are given along with the var(name). Using
+`tt(PLUS())' instead of minus to introduce an attribute turns it off.
-If any of the reserved words tt(declare), tt(export), tt(float),
+If no var(name) is present, the names and values of all parameters are
+printed. In this case the attribute flags restrict the display to only
+those parameters that have the specified attributes, and using `tt(PLUS())'
+rather than `tt(-)' to introduce the flag suppresses printing of the values
+of parameters when there is no parameter name.
+
+All forms of the command handle scalar assignment. Array assignment is
+possible if any of the reserved words tt(declare), tt(export), tt(float),
tt(integer), tt(local), tt(readonly) or tt(typeset) is matched when the
-line is parsed (N.B. not when it is executed) the shell will try to parse
-arguments as assignments, except that the `tt(+=)' syntax and the
-tt(GLOB_ASSIGN) option are not supported. This has two major differences
-from normal command line argument parsing: array assignment is possible,
-and scalar values after tt(=) are not split further into words even if
-expanded (regardless of the setting of the tt(KSH_TYPESET) option; this
-option is obsolete). Here is an example:
+line is parsed (N.B. not when it is executed). In this case the arguments
+are parsed as assignments, except that the `tt(+=)' syntax and the
+tt(GLOB_ASSIGN) option are not supported, and scalar values after tt(=)
+are em(not) split further into words, even if expanded (regardless of the
+setting of the tt(KSH_TYPESET) option; this option is obsolete).
+
+Examples of the differences between command and reserved word parsing:
example(# Reserved word parsing
typeset svar=$(echo one word) avar=(several words))
@@ -1791,7 +1812,7 @@ example(# Normal builtin interface
builtin typeset svar=$(echo two words))
The tt(builtin) keyword causes the above to use the standard builtin
-interface to tt(typeset) in which argument parsing is perfomed in the same
+interface to tt(typeset) in which argument parsing is performed in the same
way as for other commands. This example creates a scalar tt(svar)
containing the value tt(two) and another scalar parameter tt(words) with
no value. An array value in this case would either cause an error or be
@@ -1826,18 +1847,22 @@ reserved word interface for tt(typeset) may cause problems with the
output of `tt(typeset -p)', which assumes the reserved word interface is
available in order to restore array and associative array values.
-If the shell option tt(TYPESET_SILENT) is not set, for each remaining
-var(name) that refers to a parameter that is already set, the name and
-value of the parameter are printed in the form of an assignment.
-Nothing is printed for newly-created parameters, or when any attribute
-flags listed below are given along with the var(name). Using
-`tt(PLUS())' instead of minus to introduce an attribute turns it off.
+Unlike parameter assignment statements, tt(typeset)'s exit status on an
+assignment that involves a command substitution does not reflect the exit
+status of the command substitution. Therefore, to test for an error in
+a command substitution, separate the declaration of the parameter from its
+initialization:
-If no var(name) is present, the names and values of all parameters are
-printed. In this case the attribute flags restrict the display to only
-those parameters that have the specified attributes, and using `tt(PLUS())'
-rather than `tt(-)' to introduce the flag suppresses printing of the values
-of parameters when there is no parameter name.
+example(# WRONG
+typeset var1=$(exit 1) || echo "Trouble with var1"
+
+# RIGHT
+typeset var1 && var1=$(exit 1) || echo "Trouble with var1"
+)
+
+To initialize a parameter var(param) to a command output and mark it readonly,
+use tt(typeset -r )var(param) or tt(readonly )var(param) after the parameter
+assignment statement.
If no attribute flags are given, and either no var(name) arguments are
present or the flag tt(+m) is used, then each parameter name printed is
@@ -1892,15 +1917,9 @@ does not.
)
item(tt(-p))(
If the tt(-p) option is given, parameters and values are printed in the
-form of a typeset command and an assignment (which will be printed
-separately for arrays and associative arrays), regardless of other flags
+form of a typeset command with an assignment, regardless of other flags
and options. Note that the tt(-H) flag on parameters is respected; no
value will be shown for these parameters.
-
-As the intention of this option is to produce output that can restore
-the current state, readonly specials (whose values cannot be
-changed) are not shown and assignments to arrays are shown before
-the tt(typeset) rendering the array readonly.
)
item(tt(-T) [ var(scalar)[tt(=)var(value)] var(array)[tt(=LPAR())var(value) ...tt(RPAR())] [ var(sep) ] ])(
This flag has a different meaning when used with tt(-f); see below.
@@ -1980,6 +1999,11 @@ item(tt(-U))(
For arrays (but not for associative arrays), keep only the first
occurrence of each duplicated value. This may also be set for
colon-separated special parameters like tt(PATH) or tt(FIGNORE), etc.
+Note the flag takes effect on assignment, and the type of the
+variable being assigned to is determinative; for variables with
+shared values it is therefore recommended to set the flag for
+all interfaces, e.g. `tt(typeset -U PATH path)'.
+
This flag has a different meaning when used with tt(-f); see below.
)
item(tt(-Z) [ var(n) ])(
@@ -1992,16 +2016,18 @@ place in the output.
)
item(tt(-a))(
The names refer to array parameters. An array parameter may be
-created this way, but it may not be assigned to in the tt(typeset)
-statement. When displaying, both normal and associative arrays are
-shown.
+created this way, but it may be assigned to in the tt(typeset)
+statement only if the reserved word form of tt(typeset) is enabled
+(as it is by default). When displaying, both normal and associative
+arrays are shown.
)
item(tt(-f))(
The names refer to functions rather than parameters. No assignments
can be made, and the only other valid flags are tt(-t), tt(-T), tt(-k),
tt(-u), tt(-U) and tt(-z). The flag tt(-t) turns on execution tracing
for this function; the flag tt(-T) does the same, but turns off tracing
-on any function called from the present one, unless that function also
+for any named (not anonymous) function called from the present one,
+unless that function also
has the tt(-t) or tt(-T) flag. The tt(-u) and tt(-U) flags cause the
function to be marked for autoloading; tt(-U) also causes alias
expansion to be suppressed when the function is loaded. See the
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 2aa0740b8..60ef9ee2c 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -91,6 +91,7 @@ menu(Control Functions)
menu(Bindable Commands)
menu(Completion Functions)
menu(Completion Directories)
+menu(Completion System Variables)
endmenu()
texinode(Initialization)(Completion System Configuration)()(Completion System)
@@ -143,8 +144,8 @@ directory mentioned in the tt(fpath) parameter, and should be autoloaded
few utility functions, arrange for all the necessary shell functions to be
autoloaded, and will then re-define all widgets that do completion to use the
new system. If you use the tt(menu-select) widget, which is part of the
-tt(zsh/complist) module, you should make sure that that module is loaded
-before the call to tt(compinit) so that that widget is also
+tt(zsh/complist) module, you should make sure that the module is loaded
+before the call to tt(compinit) so that the widget is also
re-defined. If completion styles (see below) are set up to perform
expansion as well as completion by default, and the TAB key is bound to
tt(expand-or-complete), tt(compinit) will rebind it to tt(complete-word);
@@ -825,6 +826,10 @@ kindex(domains, completion tag)
item(tt(domains))(
for network domains
)
+kindex(email-*, completion tag)
+item(tt(email-)var(plugin))(
+for email addresses from the `tt(_email-)var(plugin)' backend of tt(_email_addresses)
+)
kindex(expansions, completion tag)
item(tt(expansions))(
used by the tt(_expand) completer for individual words (as opposed to
@@ -1110,14 +1115,14 @@ tt(default) tag. The most notable styles of this type are tt(menu),
tt(list-colors) and styles controlling completion listing such as
tt(list-packed) and tt(last-prompt). When tested for the tt(default)
tag, only the var(function) field of the context will be set so that
-a style using the default tag will normally be defined along the lines of:
+a style using the tt(default) tag will normally be defined along the lines of:
example(zstyle ':completion:*:default' menu ...)
startitem()
kindex(accept-exact, completion style)
item(tt(accept-exact))(
-This is tested for the default tag in addition to the tags valid for
+This is tested for the tt(default) tag in addition to the tags valid for
the current context. If it is set to `true' and any of the trial
matches is the same as the string on the command line, this match will
immediately be accepted (even if it would otherwise be considered
@@ -1554,7 +1559,8 @@ of the links themselves.
)
kindex(filter, completion style)
item(tt(filter))(
-This is used by the LDAP plugin for e-mail address completion to specify
+The tt(ldap) plugin of email address completion (see tt(_email_addresses)) uses
+this style to specify
the attributes to match against when filtering entries. So for example, if
the style is set to `tt(sn)', matching is done against surnames. Standard
LDAP filtering is used so normal completion matching is bypassed. If this
@@ -1841,6 +1847,15 @@ In the case of the tt(_match) completer, the style may also be set to
the string `tt(pattern)'. Then the pattern on the line is left
unchanged if it does not match unambiguously.
)
+kindex(gain-privileges, completion style)
+item(tt(gain-privileges))(
+If set to tt(true), this style enables the use of commands like tt(sudo)
+or tt(doas) to gain extra privileges when retrieving information for
+completion. This is only done when a command such as tt(sudo) appears on
+the command-line. To force the use of, e.g. tt(sudo) or to override any
+prefix that might be added due to tt(gain-privileges), the tt(command)
+style can be used with a value that begins with a hyphen.
+)
kindex(keep-prefix, completion style)
item(tt(keep-prefix))(
This style is used by the tt(_expand) completer. If it is `true', the
@@ -2022,8 +2037,9 @@ 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 tried before any match specifications given by the
-tt(matcher-list) style. It should be in the form described in
+context. Its value is placed before any match specifications given by the
+tt(matcher-list) style so can override them via the use of an tt(x:)
+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.
@@ -2976,6 +2992,21 @@ widgets to find out if the command line hasn't changed since the last
time completion was tried. Only then are the tt(_ignored),
tt(_correct) and tt(_approximate) completers called.
)
+findex(_canonical_paths)
+item(tt(_canonical_paths) [ tt(-A) var(var) ] [ tt(-N) ] [ tt(-MJV12nfX) ] var(tag) var(descr) [ var(paths) ... ])(
+This completion function completes all paths given to it, and also tries to
+offer completions which point to the same file as one of the paths given
+(relative path when an absolute path is given, and vice versa; when tt(..)'s
+are present in the word to be completed; and some paths got from symlinks).
+
+tt(-A), if specified, takes the paths from the array variable specified. Paths can
+also be specified on the command line as shown above. tt(-N), if specified,
+prevents canonicalizing the paths given before using them for completion, in
+case they are already so. The options tt(-M), tt(-J), tt(-V), tt(-1), tt(-2),
+tt(-n), tt(-F), tt(-X) are passed to tt(compadd).
+
+See tt(_description) for a description of var(tag) and var(descr).
+)
findex(_complete)
item(tt(_complete))(
This completer generates all possible completions in a context-sensitive
@@ -3221,6 +3252,7 @@ for the current context; remember that the context for completers is less
specific than that for contextual completion as the full context has not
yet been determined. Elements of the array may have one of the following
forms:
+
startsitem()
sitem(tt($)var(hash))(
var(hash) is the name of an associative array. Note this is not a full
@@ -3441,7 +3473,7 @@ emacs and vi respectively.
)
enditem()
-texinode(Completion Functions)(Completion Directories)(Bindable Commands)(Completion System)
+texinode(Completion Functions)(Completion System Variables)(Bindable Commands)(Completion System)
sect(Utility Functions)
cindex(completion system, utility functions)
@@ -3454,12 +3486,6 @@ generating matches all follow the convention of returning status zero if they
generated completions and non-zero if no matching completions could be
added.
-Two more features are offered by the tt(_main_complete) function. The
-arrays tt(compprefuncs) and tt(comppostfuncs) may contain
-names of functions that are to be called immediately before or after
-completion has been tried. A function will only be called once unless
-it explicitly reinserts itself into the array.
-
startitem()
findex(_absolute_command_paths)
item(tt(_absolute_command_paths))(
@@ -3589,8 +3615,9 @@ even if one or more of the options take
arguments. For example, if tt(-x) takes an argument, with no
tt(-s), `tt(-xy)' is considered as a single (unhandled) option; with
tt(-s), tt(-xy) is an option with the argument `tt(y)'; with both tt(-s)
-and tt(-w), tt(-xy) may be the option tt(-x) and the option tt(-y) with
-arguments still to come.
+and tt(-w), tt(-xy) is the option tt(-x) and the option tt(-y) with
+arguments to tt(-x) (and to tt(-y), if it takes arguments) still to come
+in subsequent words.
)
item(tt(-W))(
This option takes tt(-w) a stage further: it is possible to
@@ -3815,7 +3842,7 @@ form below, the var(action) will be executed by calling the
tt(_all_labels) function to process all tag labels. No special handling
of tags is needed unless a function call introduces a new one.
-The functions called to execute var(action)s will be called with the the
+The functions called to execute var(action)s will be called with the
elements of the array named by the `tt(-O) var(name)' option as arguments.
This can be used, for example, to pass the same set of options for the
tt(compadd) builtin to all var(action)s.
@@ -3930,8 +3957,8 @@ command line after the command name excluding all options and their
arguments. Options are stored in the associative array
`tt(opt_args)' with option names as keys and their arguments as
the values. For options that have more than one argument these are
-given as one string, separated by colons. All colons in the original
-arguments are preceded with backslashes.
+given as one string, separated by colons. All colons and backslashes
+in the original arguments are preceded with backslashes.
The parameter `tt(context)' is set when returning to the calling function
to perform an action of the form `tt(->)var(string)'. It is set to an
@@ -4155,7 +4182,7 @@ The return status of tt(_call_function) itself is zero if the function
var(name) exists and was called and non-zero otherwise.
)
findex(_call_program)
-item(tt(_call_program) var(tag) var(string) ...)(
+item(tt(_call_program) [ tt(-p) ] var(tag) var(string) ...)(
This function provides a mechanism for the user to override the use of an
external command. It looks up the tt(command) style with the supplied
var(tag). If the style is set, its value is used as the command to
@@ -4163,6 +4190,15 @@ execute. The var(string)s from the call to tt(_call_program), or from the
style if set, are concatenated with spaces between them and the resulting
string is evaluated. The return status is the return status of the command
called.
+
+If the option `tt(-p)' is supplied it indicates that the command
+output is influenced by the permissions it is run with. If the
+tt(gain-privileges) style is set to true, tt(_call_program) will make
+use of commands such as tt(sudo), if present on the command-line, to
+match the permissions to whatever the final command is likely to run
+under. When looking up the tt(gain-privileges) and tt(command) styles,
+the command component of the zstyle context will end with a slash
+(`tt(/)') followed by the command that would be used to gain privileges.
)
findex(_combination)
item(tt(_combination) [ tt(-s) var(pattern) ] var(tag) var(style) var(spec) ... var(field) var(opts) ...)(
@@ -4215,6 +4251,16 @@ This function completes words that are valid at command position: names of
aliases, builtins, hashed commands, functions, and so on. With the tt(-e)
flag, only hashed commands are completed. The tt(-) flag is ignored.
)
+findex(_completers)
+item(tt(_completers) [ tt(-p) ])(
+This function completes names of completers.
+
+startitem()
+item(tt(-p))(
+Include the leading underscore (`tt(_)') in the matches.
+)
+enditem()
+)
findex(_describe)
redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ @ @ ))ifnztexi( )))
xitem(tt(_describe )[tt(-12JVx)] [ tt(-oO) | tt(-t) var(tag) ] var(descr) var(name1) [ var(name2) ] [ var(opt) ... ])
@@ -4226,13 +4272,13 @@ different completion options var(opt)s.
The var(descr) is taken as a string to display above the matches if the
tt(format) style for the tt(descriptions) tag is set. This is followed by
one or two names of arrays followed by options to pass to tt(compadd). The
-first array contains the possible completions with their descriptions in
+array var(name1) contains the possible completions with their descriptions in
the form `var(completion)tt(:)var(description)'. Any literal colons in
-var(completion) must be quoted with a backslash. If a second array is
-given, it should have the same number of elements as the first; in this
+var(completion) must be quoted with a backslash. If a var(name2) is
+given, it should have the same number of elements as var(name1); in this
case the corresponding elements are added as possible completions instead
-of the var(completion) strings from the first array. The completion list
-will retain the descriptions from the first array. Finally, a set of
+of the var(completion) strings from var(name1). The completion list
+will retain the descriptions from var(name1). Finally, a set of
completion options can appear.
If the option `tt(-o)' appears before the first argument, the matches added
@@ -4316,6 +4362,21 @@ matches. Almost all calls to tt(compadd) within the completion system use
a similar format; this ensures that user-specified styles are correctly
passed down to the builtins which implement the internals of completion.
)
+findex(_dir_list)
+item(tt(_dir_list) [ tt(-s) var(sep) ] [ tt(-S) ])(
+Complete a list of directory names separated by colons
+(the same format as tt($PATH)).
+
+startitem()
+item(tt(-s) var(sep))(
+Use var(sep) as separator between items.
+var(sep) defaults to a colon (`tt(:)').
+)
+item(tt(-S))(
+Add var(sep) instead of slash (`tt(/)') as an autoremoveable suffix.
+)
+enditem()
+)
findex(_dispatch)
item(tt(_dispatch) var(context string) ...)(
This sets the current context to var(context) and looks for completion
@@ -4331,6 +4392,44 @@ tt($service) to the var(string) being tried, and sets
the var(context/command) field (the fourth) of the tt($curcontext)
parameter to the var(context) given as the first argument.
)
+findex(_email_addresses)
+item(tt(_email_addresses) [ tt(-c) ] [ tt(-n) var(plugin) ])(
+Complete email addresses. Addresses are provided by plugins.
+
+startitem()
+item(tt(-c))(
+Complete bare tt(localhost@domain.tld) addresses, without a name part or
+a comment.
+Without this option, RFC822 `var(Firstname Lastname) tt(<)var(address)tt(>)'
+strings are completed.
+)
+item(tt(-n) var(plugin))(
+Complete aliases from var(plugin).
+)
+COMMENT(Intentionally leaving tt(-s) undocumented: new code should use
+tt(_sequence) instead.)\
+enditem()
+
+The following plugins are available by default:
+tt(_email-ldap) (see the tt(filter) style),
+tt(_email-local) (completes var(user)tt(@)var(hostname) Unix addresses),
+tt(_email-mail) (completes aliases from tt(~/.mailrc)),
+tt(_email-mush),
+tt(_email-mutt),
+and
+tt(_email-pine).
+
+Addresses from the tt(_email-)var(foo) plugin are added under the
+tag `tt(email-)var(foo)'.
+
+em(Writing plugins)
+
+Plugins are written as separate functions with names starting with `tt(_email-)'.
+They are invoked with the tt(-c) option and tt(compadd) options.
+They should either do their own completion or
+set the tt($reply) array to a list of `var(alias)tt(:)var(address)' elements and return tt(300).
+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
@@ -4415,7 +4514,7 @@ the time this function is called, tt(compstate[insert]) is cleared, so
additional matches generated later are not inserted on the command line.
)
findex(_multi_parts)
-item(tt(_multi_parts) var(sep) var(array))(
+item(tt(_multi_parts) [ tt(-i) ] var(sep) var(array))(
The argument var(sep) is a separator character.
The var(array) may be either the
name of an array parameter or a literal array in the form
@@ -4915,12 +5014,18 @@ particular tag is to be tried, the tt(_requested) function should be
called (see above).
If `tt(-C) var(name)' is given, var(name) is temporarily stored in the
-argument field (the fifth) of the context in the tt(curcontext) parameter
+var(argument) field (the fifth) of the context in the tt(curcontext) parameter
during the call to tt(_tags); the field is restored on exit. This
allows tt(_tags) to use a more
specific context without having to change and reset the
tt(curcontext) parameter (which has the same effect).
)
+findex(_tilde_files)
+item(tt(_tilde_files))(
+Like tt(_files), but resolve leading tildes according to the rules of
+filename expansion, so the suggested completions don't start with
+a `tt(~)' even if the filename on the command-line does.
+)
findex(_values)
item(tt(_values) [ tt(-O) var(name) ] [ tt(-s) var(sep) ] [ tt(-S) var(sep) ] [ tt(-wC) ] var(desc) var(spec) ...)(
This is used to complete arbitrary keywords (values) and their arguments,
@@ -5043,9 +5148,52 @@ Like tt(_tags) this function supports the tt(-C) option to give a
different name for the argument context field. The tt(-x) option has
the same meaning as for tt(_description).
)
+findex(_widgets)
+item(tt(_widgets) [ tt(-g) var(pattern) ])(
+This function completes names of zle widgets (see
+ifzman(the section `Widgets' in zmanref(zshzle))\
+ifnzman(noderef(Zle Widgets))\
+). The var(pattern), if present, is matched against values of the tt($widgets)
+special parameter, documented in
+ifzman(the section `The zsh/zleparameter Module' in zmanref(zshmodules))\
+ifnzman(noderef(The zsh/zleparameter Module)).
+)
+enditem()
+
+texinode(Completion System Variables)(Completion Directories)(Completion Functions)(Completion System)
+sect(Completion System Variables)
+cindex(completion system, variables)
+
+There are some standard variables, initialised by the tt(_main_complete)
+function and then used from other functions.
+
+The standard variables are:
+
+startitem()
+item(tt(_comp_caller_options))(
+The completion system uses tt(setopt) to set a number of options. This
+allows functions to be written without concern for compatibility with
+every possible combination of user options. However, sometimes completion
+needs to know what the user's option preferences are. These are saved
+in the tt(_comp_caller_options) associative array. Option names, spelled
+in lowercase without underscores, are mapped to one or other of the
+strings `tt(on)' and `tt(off)'.
+)
+
+item(tt(_comp_priv_prefix))(
+Completion functions such as tt(_sudo) can set the tt(_comp_priv_prefix)
+array to a command prefix that may then be used by tt(_call_program) to
+match the privileges when calling programs to generate matches.
+)
enditem()
-texinode(Completion Directories)()(Completion Functions)(Completion System)
+Two more features are offered by the tt(_main_complete) function. The
+arrays tt(compprefuncs) and tt(comppostfuncs) may contain
+names of functions that are to be called immediately before or after
+completion has been tried. A function will only be called once unless
+it explicitly reinserts itself into the array.
+
+texinode(Completion Directories)()(Completion System Variables)(Completion System)
sect(Completion Directories)
cindex(completion system, directory structure)
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index c01763316..1cc94bf95 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -913,6 +913,13 @@ line and trial completion patterns are anchored on the right side.
Here an empty var(ranchor) and the tt(e) and tt(E) forms force the
match to the end of the command line or trial completion string.
)
+item(tt(x:))(
+This form is used to mark the end of matching specifications:
+subsequent specifications are ignored. In a single standalone list
+of specifications this has no use but where matching specifications
+are accumulated, such as from nested function calls, it can allow one
+function to override another.
+)
enditem()
Each var(lpat), var(tpat) or var(anchor) is either an empty string or
diff --git a/Doc/Zsh/cond.yo b/Doc/Zsh/cond.yo
index 3d369fb83..e08fc0d36 100644
--- a/Doc/Zsh/cond.yo
+++ b/Doc/Zsh/cond.yo
@@ -63,6 +63,9 @@ is open and associated with a terminal device.
item(tt(-u) var(file))(
true if var(file) exists and has its setuid bit set.
)
+item(tt(-v) var(varname))(
+true if shell variable var(varname) is set.
+)
item(tt(-w) var(file))(
true if var(file) exists and is writable by current process.
)
@@ -103,8 +106,10 @@ true if var(file1) and var(file2) exist and refer to the same file.
xitem(var(string) tt(=) var(pattern))
item(var(string) tt(==) var(pattern))(
true if var(string) matches var(pattern).
-The `tt(==)' form is the preferred one. The `tt(=)' form is for
-backward compatibility and should be considered obsolete.
+The two forms are exactly equivalent. The `tt(=)' form is
+the traditional shell syntax (and hence the only one generally used
+with the tt(test) and tt([) builtins); the `tt(==)' form provides
+compatibility with other sorts of computer language.
)
item(var(string) tt(!=) var(pattern))(
true if var(string) does not match var(pattern).
diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index 07a5eb08e..f764eb7c6 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -292,11 +292,11 @@ cindex(hook function utility)
startitem()
findex(add-zsh-hook)
-item(tt(add-zsh-hook) [ tt(-dD) ] [ tt(-Uzk) ] var(hook) var(function))(
+item(tt(add-zsh-hook) [ tt(-L) | tt(-dD) ] [ tt(-Uzk) ] var(hook) var(function))(
Several functions are special to the shell, as described in the section
ifnzman(Special Functions, noderef(Functions))\
ifzman(SPECIAL FUNCTIONS, see zmanref(zshmisc)),
-in that they are automatic called at a specific point during shell execution.
+in that they are automatically called at specific points during shell execution.
Each has an associated array consisting of names of functions to be
called at the same point; these are so-called `hook functions'.
The shell function tt(add-zsh-hook) provides a simple way of adding or
@@ -311,6 +311,10 @@ still be manipulated as a hook.
var(function) is name of an ordinary shell function. If no options
are given this will be added to the array of functions to be executed
in the given context.
+Functions are invoked in the order they were added.
+
+If the option tt(-L) is given, the current values for the hook arrays
+are listed with tt(typeset).
If the option tt(-d) is given, the var(function) is removed from
the array of functions to be executed.
@@ -323,6 +327,55 @@ The options tt(-U), tt(-z) and tt(-k) are passed as arguments to
tt(autoload) for var(function). For functions contributed with zsh, the
options tt(-Uz) are appropriate.
)
+findex(add-zle-hook-widget)
+item(tt(add-zle-hook-widget) [ tt(-L) | tt(-dD) ] [ tt(-Uzk) ] var(hook) var(widgetname))(
+Several widget names are special to the line editor, as described in the section
+ifnzman(Special Widgets, noderef(Zle Widgets))\
+ifzman(Special Widgets, see zmanref(zshzle)),
+in that they are automatically called at specific points during editing.
+Unlike function hooks, these do not use a predefined array of other names
+to call at the same point; the shell function tt(add-zle-hook-widget)
+maintains a similar array and arranges for the special widget to invoke
+those additional widgets.
+
+var(hook) is one of tt(isearch-exit), tt(isearch-update),
+tt(line-pre-redraw), tt(line-init), tt(line-finish), tt(history-line-set),
+or tt(keymap-select), corresponding to each of the special widgets
+tt(zle-isearch-exit), etc. The special widget names are also accepted
+as the var(hook) argument.
+
+var(widgetname) is the name of a ZLE widget. If no options are given this
+is added to the array of widgets to be invoked in the given hook context.
+Widgets are invoked in the order they were added, with
+example(tt(zle )var(widgetname)tt( -Nw -- "$@"))
+
+vindex(WIDGET, in hooks)
+Note that this means that the `tt(WIDGET)' special parameter tracks the
+var(widgetname) when the widget function is called, rather than tracking
+the name of the corresponding special hook widget.
+
+If the option tt(-d) is given, the var(widgetname) is removed from
+the array of widgets to be executed.
+
+If the option tt(-D) is given, the var(widgetname) is treated as a pattern
+and any matching names of widgets are removed from the array.
+
+If var(widgetname) does not name an existing widget when added to the
+array, it is assumed that a shell function also named var(widgetname) is
+meant to provide the implementation of the widget. This name is therefore
+marked for autoloading, and the options tt(-U), tt(-z) and tt(-k) are
+passed as arguments to tt(autoload) as with tt(add-zsh-hook). The
+widget is also created with `tt(zle -N )var(widgetname)' to cause the
+corresponding function to be loaded the first time the hook is called.
+
+The arrays of var(widgetname) are currently maintained in tt(zstyle)
+contexts, one for each var(hook) context, with a style of `tt(widgets)'.
+If the tt(-L) option is given, this set of styles is listed with
+`tt(zstyle -L)'. This implementation may change, and the special widgets
+that refer to the styles are created only if tt(add-zle-hook-widget) is
+called to add at least one widget, so if this function is used for any
+hooks, then all hooks should be managed only via this function.
+)
enditem()
texinode(Recent Directories)(Other Directory Functions)(Utilities)(User Contributions)
@@ -998,7 +1051,7 @@ tt(:vcs_info:-init-:*:-all-) context.
Say, tt(~/.zsh) is a directory under version control, in which you do
not want tt(vcs_info) to be active, do:
-example(zstyle ':vcs_info:*' disable-patterns "$HOME/.zsh+LPAR()|/*+RPAR()")
+example(zstyle ':vcs_info:*' disable-patterns "${+LPAR()b+RPAR()HOME}/.zsh+LPAR()|/*+RPAR()")
)
kindex(use-quilt)
item(tt(use-quilt))(
@@ -1017,7 +1070,7 @@ tt(Quilt Support) for details.
)
kindex(quiltcommand)
item(tt(quiltcommand))(
-When tt(quilt) itself is called in quilt support the value of this style
+When tt(quilt) itself is called in quilt support, the value of this style
is used as the command name.
)
kindex(check-for-changes)
@@ -1888,6 +1941,8 @@ tindex(transpose-words-match)
tindex(capitalize-word-match)
tindex(up-case-word-match)
tindex(down-case-word-match)
+tindex(delete-whole-word-match)
+tindex(select-word-match)
tindex(select-word-style)
tindex(match-word-context)
tindex(match-words-by-style)
@@ -1895,12 +1950,14 @@ xitem(tt(forward-word-match), tt(backward-word-match))
xitem(tt(kill-word-match), tt(backward-kill-word-match))
xitem(tt(transpose-words-match), tt(capitalize-word-match))
xitem(tt(up-case-word-match), tt(down-case-word-match))
+xitem(tt(delete-whole-word-match), tt(select-word-match))
item(tt(select-word-style), tt(match-word-context), tt(match-words-by-style))(
-The eight `tt(-match)' functions are drop-in replacements for the
+The first eight `tt(-match)' functions are drop-in replacements for the
builtin widgets without the suffix. By default they behave in a similar
way. However, by the use of styles and the function tt(select-word-style),
-the way words are matched can be altered. For comparison, the widgets
-described in ifzman(zmanref(zshzle) under Text Objects)\
+the way words are matched can be altered. tt(select-word-match) is intended
+to be used as a text object in vi mode but with custom word styles. For
+comparison, the widgets described in ifzman(zmanref(zshzle) under Text Objects)\
ifnzman(noderef(Text Objects)) use fixed definitions of words, compatible
with the tt(vim) editor.
@@ -1908,7 +1965,7 @@ The simplest way of configuring the functions is to use
tt(select-word-style), which can either be called as a normal function with
the appropriate argument, or invoked as a user-defined widget that will
prompt for the first character of the word style to be used. The first
-time it is invoked, the eight tt(-match) functions will automatically
+time it is invoked, the first eight tt(-match) functions will automatically
replace the builtin versions, so they do not need to be loaded explicitly.
The word styles available are as follows. Only the first character
@@ -2049,7 +2106,7 @@ Here are some examples of use of the tt(word-context) style to extend
the context.
example(zstyle ':zle:*' word-context \
- "*/*" file "[[:space:]]" whitespace
+ "*/*" filename "[[:space:]]" whitespace
zstyle ':zle:transpose-words:whitespace' word-style shell
zstyle ':zle:transpose-words:filename' word-style normal
zstyle ':zle:transpose-words:filename' word-chars '')
@@ -2076,6 +2133,17 @@ non-word characters following that word (7) the remainder of the line. Any
of the elements may be an empty string; the calling function should test
for this to decide whether it can perform its function.
+If the variable tt(matched_words) is defined by the caller to
+tt(match-words-by-style) as an associative array (tt(local -A
+matched_words)), then the seven values given above should be retrieved
+from it as elements named tt(start), tt(word-before-cursor),
+tt(ws-before-cursor), tt(ws-after-cursor), tt(word-after-cursor),
+tt(ws-after-word), and tt(end). In addition the element
+tt(is-word-start) is 1 if the cursor is on the start of a word or
+subword, or on white space before it (the cases can be distinguished by
+testing the tt(ws-after-cursor) element) and 0 otherwise. This form is
+recommended for future compatibility.
+
It is possible to pass options with arguments to tt(match-words-by-style)
to override the use of styles. The options are:
startsitem()
@@ -2094,7 +2162,7 @@ tt(match-word-context). This should not usually need to be called
directly.
)
tindex(bracketed-paste-magic)
-item(bracketed-paste-magic)(
+item(tt(bracketed-paste-magic))(
The tt(bracketed-paste) widget (see ifzman(subsection Miscellaneous in
zmanref(zshzle))ifnzman(noderef(Miscellaneous) in noderef(Zle Widgets)))
inserts pasted text literally into the editor buffer rather than interpret
@@ -2912,6 +2980,17 @@ and aliases `tt(globurl)' to `tt(noglob urlglobber)'. This function takes
a local URL apart, attempts to pattern-match the local file portion of the
URL path, and then puts the results back into URL format again.
)
+tindex(vi-pipe)
+item(tt(vi-pipe))(
+This function reads a movement command from the keyboard and then
+prompts for an external command. The part of the buffer covered by
+the movement is piped to the external command and then replaced by
+the command's output. If the movement command is bound to vi-pipe,
+the current line is used.
+
+The function serves as an example for reading a vi movement command
+from within a user-defined widget.
+)
tindex(which-command)
item(tt(which-command))(
This function is a drop-in replacement for the builtin widget
@@ -2941,6 +3020,9 @@ the variable tt(ZCALC_AUTO_INSERT_PREFIX).
Hence, for example, typing `tt(PLUS()12)' followed by return adds 12
to the previous result.
+If zcalc is in RPN mode (tt(-r) option) the effect of this binding is
+automatically suppressed as operators alone on a line are meaningful.
+
When not in zcalc, the key simply inserts the symbol itself.
)
enditem()
@@ -3396,7 +3478,7 @@ will ensure that any files found in that area will be executed as MIME
types even if they are executable. As this example shows, the complete
file name is matched against the pattern, regardless of how the file
was passed to the handler. The file is resolved to a full path using
-the tt(:A) modifier described in
+the tt(:P) modifier described in
ifzman(the subsection Modifiers in zmanref(zshexpn))\
ifnzman(noderef(Modifiers));
this means that symbolic links are resolved where possible, so that
@@ -3654,7 +3736,7 @@ sect(Mathematical Functions)
startitem()
findex(zcalc)
-item(tt(zcalc) [ tt(-ef) ] [ var(expression) ... ])(
+item(tt(zcalc) [ tt(-erf) ] [ var(expression) ... ])(
A reasonably powerful calculator based on zsh's arithmetic evaluation
facility. The syntax is similar to that of formulae in most programming
languages; see
@@ -3705,8 +3787,14 @@ first few positional parameters. A visual indication of this is given when
the calculator starts.
The constants tt(PI) (3.14159...) and tt(E) (2.71828...) are provided.
-Parameter assignment is possible, but note that all parameters will be put
-into the global namespace.
+Parameter assignment is possible, but note that all parameters will be
+put into the global namespace unless the tt(:local) special command is
+used. The function creates local variables whose names start with
+tt(_), so users should avoid doing so. The variables tt(ans) (the last
+answer) and tt(stack) (the stack in RPN mode) may be referred to
+directly; tt(stack) is an array but elements of it are numeric. Various
+other special variables are used locally with their standard meaning,
+for example tt(compcontext), tt(match), tt(mbegin), tt(mend), tt(psvar).
The output base can be initialised by passing the option `tt(-#)var(base)',
for example `tt(zcalc -#16)' (the `tt(#)' may have to be quoted, depending
@@ -3720,12 +3808,70 @@ If the option `tt(-f)' is set, all numbers are treated as floating
point, hence for example the expression `tt(3/4)' evaluates to 0.75
rather than 0. Options must appear in separate words.
+If the option `tt(-r)' is set, RPN (Reverse Polish Notation) mode is
+entered. This has various additional properties:
+startitem()
+item(Stack)(
+Evaluated values are maintained in a stack; this is contained in
+an array named tt(stack) with the most recent value in tt(${stack[1]}).
+)
+item(Operators and functions)(
+If the line entered matches an operator (tt(+), tt(-), tt(*),
+tt(/), tt(**), tt(^), tt(|) or tt(&)) or a function supplied by the
+tt(zsh/mathfunc) library, the bottom element or elements of the stack
+are popped to use as the argument or arguments. The higher elements
+of stack (least recent) are used as earlier arguments. The result is
+then pushed into tt(${stack[1]}).
+)
+item(Expressions)(
+Other expressions are evaluated normally, printed, and added to the
+stack as numeric values. The syntax within expressions on a single line
+is normal shell arithmetic (not RPN).
+)
+item(Stack listing)(
+If an integer follows the option tt(-r) with no space, then
+on every evaluation that many elements of the stack, where available,
+are printed instead of just the most recent result. Hence, for example,
+tt(zcalc -r4) shows tt($stack[4]) to tt($stack[1]) each time results
+are printed.
+)
+item(Duplication: tt(=))(
+The pseudo-operator tt(=) causes the most recent element of
+the stack to be duplicated onto the stack.
+)
+item(tt(pop))(
+The pseudo-function tt(pop) causes the most recent element of
+the stack to be popped. A `tt(>)' on its own has the same effect.
+)
+item(tt(>)var(ident))(
+The expression tt(>) followed (with no space) by a shell identifier
+causes the most recent element of the stack to be popped and
+assigned to the variable with that name. The variable is
+local to the tt(zcalc) function.
+)
+item(tt(<)var(ident))(
+The expression tt(<) followed (with no space) by a shell identifier
+causes the value of the variable with that name to be pushed
+onto the stack. var(ident) may be an integer, in which
+case the previous result with that number (as shown before
+the tt(>) in the standard tt(zcalc) prompt) is put on the stack.
+)
+item(Exchange: tt(xy))(
+The pseudo-function tt(xy) causes the most recent two elements of
+the stack to be exchanged. `tt(<>)' has the same effect.
+)
+enditem()
+
The prompt is configurable via the parameter tt(ZCALCPROMPT), which
undergoes standard prompt expansion. The index of the current entry is
stored locally in the first element of the array tt(psvar), which can be
referred to in tt(ZCALCPROMPT) as `tt(%1v)'. The default prompt is
`tt(%1v> )'.
+The variable tt(ZCALC_ACTIVE) is set within the function and can
+be tested by nested functions; it has the value tt(rpn) if RPN mode is
+active, else 1.
+
A few special commands are available; these are introduced by a colon.
For backward compatibility, the colon may be omitted for certain
commands. Completion is available if tt(compinit) has been run.
@@ -3765,8 +3911,7 @@ is executed in the context of the function, i.e. with local variables.
Space is optional after tt(:!).
)
item(tt(:local) var(arg) ...)(
-Declare variables local to the function. Note that certain variables
-are used by the function for its own purposes. Other variables
+Declare variables local to the function. Other variables
may be used, too, but they will be taken from or put into the global
scope.
)
@@ -3780,7 +3925,13 @@ Note that tt(zcalc) takes care of all quoting. Hence for example:
example(:f cube $1 * $1 * $1)
-defines a function to cube the sole argument.
+defines a function to cube the sole argument. Functions so defined, or
+indeed any functions defined directly or indirectly using tt(functions
+-M), are available to execute by typing only the name on the line in RPN
+mode; this pops the appropriate number of arguments off the stack
+to pass to the function, i.e. 1 in the case of the example tt(cube)
+function. If there are optional arguments only the mandatory
+arguments are supplied by this means.
)
item(tt([#)var(base)tt(]))(
This is not a special command, rather part of normal arithmetic
@@ -3792,10 +3943,31 @@ always specified in decimal. `tt([#])' restores the normal output format.
Note that setting an output base suppresses floating point output; use
`tt([#])' to return to normal operation.
)
+item(tt($)var(var))(
+Print out the value of var literally; does not affect the calculation.
+To use the value of var, omit the leading `tt($)'.
+)
enditem()
See the comments in the function for a few extra tips.
)
+findex(max)
+findex(min)
+findex(sum)
+findex(zmathfunc)
+xitem(tt(min+LPAR())var(arg)tt(, ...+RPAR()))
+xitem(tt(max+LPAR())var(arg)tt(, ...+RPAR()))
+xitem(tt(sum+LPAR())var(arg)tt(, ...+RPAR()))
+item(tt(zmathfunc))(
+The function tt(zmathfunc) defines the three mathematical functions
+tt(min), tt(max), and tt(sum). The functions tt(min) and tt(max) take
+one or more arguments. The function tt(sum) takes zero or more arguments.
+Arguments can be of different types (ints and floats).
+
+Not to be confused with the tt(zsh/mathfunc) module, described in
+ifzman(the section `The zsh/mathfunc Module' in zmanref(zshmodules))\
+ifnzman(noderef(The zsh/mathfunc Module)).
+)
findex(zmathfuncdef)
item(tt(zmathfuncdef) [ var(mathfunc) [ var(body) ] ])(
A convenient front end to tt(functions -M).
@@ -4030,12 +4202,29 @@ your search path, in order to be found and used by tt(run-help).
startitem()
findex(run-help-git)
+findex(run-help-ip)
+findex(run-help-openssl)
+findex(run-help-p4)
+findex(run-help-sudo)
findex(run-help-svk)
findex(run-help-svn)
-xitem(tt(run-help-git))
-xitem(tt(run-help-svk))
+xitem(run-help-git)
+xitem(run-help-ip)
+xitem(run-help-openssl)
+xitem(run-help-p4)
+xitem(run-help-sudo)
+xitem(run-help-svk)
item(tt(run-help-svn))(
-Assistant functions for the tt(git), tt(svk), and tt(svn) commands.
+Assistant functions for the
+tt(git),
+tt(ip),
+tt(openssl),
+tt(p4),
+tt(sudo),
+tt(svk),
+and
+tt(svn),
+commands.
)
enditem()
)
diff --git a/Doc/Zsh/exec.yo b/Doc/Zsh/exec.yo
index 30e4a61a2..5f79967de 100644
--- a/Doc/Zsh/exec.yo
+++ b/Doc/Zsh/exec.yo
@@ -28,10 +28,11 @@ not handle this executable format in the kernel.
If no external command is found but a function tt(command_not_found_handler)
exists the shell executes this function with all
-command line arguments. The function should return status zero if it
-successfully handled the command, or non-zero status if it failed.
-In the latter case the standard handling is applied: `command not
-found' is printed to standard error and the shell exits with status 127.
-Note that the handler is executed in a subshell forked to execute
-an external command, hence changes to directories, shell parameters,
-etc. have no effect on the main shell.
+command line arguments. The return status of the function becomes the
+status of the command. If the function wishes to mimic the
+behaviour of the shell when the command is not found, it should
+print the message `tt(command not found:) var(cmd)' to standard error
+and return status 127. Note that the handler is executed in a
+subshell forked to execute an external command, hence changes to
+directories, shell parameters, etc. have no effect on the main shell.
+
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index c6e7b6f16..87ca7905d 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -219,15 +219,28 @@ noted.
startitem()
item(tt(a))(
Turn a file name into an absolute path: prepends the current directory,
-if necessary, and resolves any use of `tt(..)' and `tt(.)' in the path.
-Note that the transformation takes place even if the file or any
-intervening directories do not exist.
+if necessary; remove `tt(.)' path segments; and remove `tt(..)' path segments
+and the segments that immediately precede them.
+
+This transformation is agnostic about what is in the filesystem, i.e. is
+on the logical, not the physical directory. It takes place in the same
+manner as when changing directories when neither of the options
+tt(CHASE_DOTS) or tt(CHASE_LINKS) is set. For example,
+`tt(/before/here/../after)' is always transformed to
+`tt(/before/after)', regardless of whether `tt(/before/here)' exists or what
+kind of object (dir, file, symlink, etc.) it is.
)
item(tt(A))(
-As `tt(a)', but also resolve use of symbolic links where possible.
-Note that resolution of `tt(..)' occurs em(before) resolution of symbolic
-links. This call is equivalent to tt(a) unless your system has the
-tt(realpath) system call (modern systems do).
+Turn a file name into an absolute path as the `tt(a)' modifier does, and
+em(then) pass the result through the tt(realpath+LPAR()3+RPAR()) library
+function to resolve symbolic links.
+
+Note: on systems that do not have a tt(realpath+LPAR()3+RPAR()) library
+function, symbolic links are not resolved, so on those systems `tt(a)' and
+`tt(A)' are equivalent.
+
+Note: tt(foo:A) and tt(realpath+LPAR()foo+RPAR()) are different on some inputs.
+For tt(realpath+LPAR()foo+RPAR()) semantics, see the `tt(P)` modifier.
)
item(tt(c))(
Resolve a command name into an absolute path by searching the command
@@ -253,6 +266,14 @@ item(tt(p))(
Print the new command but do not execute it. Only works with history
expansion.
)
+item(tt(P))(
+Turn a file name into an absolute path, like tt(realpath+LPAR()3+RPAR()).
+The resulting path will be absolute, have neither `tt(.)' nor `tt(..)' components,
+and refer to the same directory entry as the input filename.
+
+Unlike tt(realpath+LPAR()3+RPAR()), non-existent trailing components are
+permitted and preserved.
+)
item(tt(q))(
Quote the substituted words, escaping further substitutions. Works
with history expansion and parameter expansion, though for parameters
@@ -551,6 +572,18 @@ 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
+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(}))(
The value, if any, of the parameter var(name) is substituted.
@@ -724,7 +757,7 @@ character of tt($foo) if the substitution would otherwise return a scalar,
or the array starting at the fourth element if tt($foo) would return an
array. Note that with the option tt(KSH_ARRAYS) tt($foo) always returns
a scalar (regardless of the use of the offset syntax) and a form
-such as tt($foo[*]:3) is required to extract elements of an array named
+such as tt(${foo[*]:3}) is required to extract elements of an array named
tt(foo).
If var(offset) is negative, the tt(-) may not appear immediately
@@ -740,8 +773,8 @@ expression tt(${var: offs}) does work, retrieving the offset from
tt($offs).
For further compatibility with other shells there is a special case
-for array offset 0. This usually accesses to the
-first element of the array. However, if the substitution refers the
+for array offset 0. This usually accesses the
+first element of the array. However, if the substitution refers to the
positional parameter array, e.g. tt($@) or tt($*), then offset 0
instead refers to tt($0), offset 1 refers to tt($1), and so on. In
other words, the positional parameter array is effectively extended by
@@ -749,12 +782,14 @@ prepending tt($0). Hence tt(${*:0:1}) substitutes tt($0) and
tt(${*:1:1}) substitutes tt($1).
)
xitem(tt(${)var(name)tt(/)var(pattern)tt(/)var(repl)tt(}))
-item(tt(${)var(name)tt(//)var(pattern)tt(/)var(repl)tt(}))(
+xitem(tt(${)var(name)tt(//)var(pattern)tt(/)var(repl)tt(}))
+item(tt(${)var(name)tt(:/)var(pattern)tt(/)var(repl)tt(}))(
Replace the longest possible match of var(pattern) in the expansion of
parameter var(name) by string var(repl). The first form
-replaces just the first occurrence, the second form all occurrences.
+replaces just the first occurrence, the second form all occurrences,
+and the third form replaces only if var(pattern) matches the entire string.
Both var(pattern) and var(repl) are subject to double-quoted substitution,
-so that expressions like tt(${name/$opat/$npat}) will work, but note the
+so that expressions like tt(${name/$opat/$npat}) will work, but obey the
usual rule that pattern characters in tt($opat) are not treated specially
unless either the option tt(GLOB_SUBST) is set, or tt($opat) is instead
substituted as tt(${~opat}).
@@ -770,8 +805,8 @@ single backslash; this is not necessary if the
`tt(%)' and `tt(#%) are not active if they occur inside a substituted
parameter, even at the start.
-The first `tt(/)' may be preceded by a `tt(:)', in which case the match
-will only succeed if it matches the entire word. Note also the
+If, after quoting rules apply, tt(${)var(name)tt(}) expands to an array,
+the replacements act on each element individually. Note also the
effect of the tt(I) and tt(S) parameter expansion flags below; however,
the flags tt(M), tt(R), tt(B), tt(E) and tt(N) are not useful.
diff --git a/Doc/Zsh/jobs.yo b/Doc/Zsh/jobs.yo
index d9395010a..6262dd244 100644
--- a/Doc/Zsh/jobs.yo
+++ b/Doc/Zsh/jobs.yo
@@ -74,8 +74,8 @@ or by one of the following:
startsitem()
sitem(tt(%)var(number))(The job with the given number.)
-sitem(tt(%)var(string))(Any job whose command line begins with var(string).)
-sitem(tt(%?)var(string))(Any job whose command line contains var(string).)
+sitem(tt(%)var(string))(The last job whose command line begins with var(string).)
+sitem(tt(%?)var(string))(The last job whose command line contains var(string).)
sitem(tt(%%))(Current job.)
sitem(tt(%PLUS()))(Equivalent to `tt(%%)'.)
sitem(tt(%-))(Previous job.)
diff --git a/Doc/Zsh/mod_complist.yo b/Doc/Zsh/mod_complist.yo
index 164b5b03f..31aa656f1 100644
--- a/Doc/Zsh/mod_complist.yo
+++ b/Doc/Zsh/mod_complist.yo
@@ -150,8 +150,8 @@ containing the codes for ANSI terminals (see
ifzman(the section `Other Functions' in zmanref(zshcontrib))\
ifnzman(noderef(Other Functions))\
). For example, after loading tt(colors), one could use
-`tt($colors[red])' to get the code for foreground color red and
-`tt($colors[bg-green])' for the code for background color green.
+`tt($color[red])' to get the code for foreground color red and
+`tt($color[bg-green])' for the code for background color green.
If the completion system invoked by compinit is used, these
parameters should not be set directly because the system controls them
diff --git a/Doc/Zsh/mod_curses.yo b/Doc/Zsh/mod_curses.yo
index 8104572a6..72dc4094a 100644
--- a/Doc/Zsh/mod_curses.yo
+++ b/Doc/Zsh/mod_curses.yo
@@ -111,7 +111,11 @@ Each var(fg_col)tt(/)var(bg_col) attribute (to be read as
for character output. The color tt(default) is sometimes available
(in particular if the library is ncurses), specifying the foreground
or background color with which the terminal started. The color pair
-tt(default/default) is always available.
+tt(default/default) is always available. To use more than the 8 named
+colors (red, green, etc.) construct the var(fg_col)tt(/)var(bg_col)
+pairs where var(fg_col) and var(bg_col) are decimal integers, e.g
+tt(128/200). The maximum color value is 254 if the terminal supports
+256 colors.
tt(bg) overrides the color and other attributes of all characters in the
window. Its usual use is to set the background initially, but it will
diff --git a/Doc/Zsh/mod_mathfunc.yo b/Doc/Zsh/mod_mathfunc.yo
index 5239da5f8..8b72de3ab 100644
--- a/Doc/Zsh/mod_mathfunc.yo
+++ b/Doc/Zsh/mod_mathfunc.yo
@@ -36,6 +36,11 @@ that it is therefore only useful immediately after a call to tt(gamma) or
tt(lgamma). Note also that `tt(signgam+LPAR()RPAR())' and `tt(signgam)' are
distinct expressions.
+The functions tt(min), tt(max), and tt(sum) are defined not in this module
+but in the tt(zmathfunc) autoloadable function, described in
+ifzman(the section `Mathematical Functions' in zmanref(zshcontrib))\
+ifnzman(noderef(Mathematical Functions)).
+
The following functions take two floating point arguments: tt(copysign),
tt(fmod), tt(hypot), tt(nextafter).
diff --git a/Doc/Zsh/mod_sched.yo b/Doc/Zsh/mod_sched.yo
index 1350b9e4c..30b08a3ff 100644
--- a/Doc/Zsh/mod_sched.yo
+++ b/Doc/Zsh/mod_sched.yo
@@ -40,6 +40,11 @@ afterwards. This should be used with any scheduled event that produces
visible output to the terminal; it is not needed, for example, with
output that updates a terminal emulator's title bar.
+To effect changes to the editor buffer when an event executes, use the
+`tt(zle)' command with no arguments to test whether the editor is active,
+and if it is, then use `tt(zle )var(widget)' to access the editor via
+the named var(widget).
+
The tt(sched) builtin is not made available by default when the shell
starts in a mode emulating another shell. It can be made available
with the command `tt(zmodload -F zsh/sched b:sched)'.
diff --git a/Doc/Zsh/mod_zleparameter.yo b/Doc/Zsh/mod_zleparameter.yo
index 03d504724..76d23ba2a 100644
--- a/Doc/Zsh/mod_zleparameter.yo
+++ b/Doc/Zsh/mod_zleparameter.yo
@@ -15,14 +15,16 @@ This array contains the names of the keymaps currently defined.
)
vindex(widgets)
item(tt(widgets))(
-This associative array contains one entry per widget defined. The name
+This associative array contains one entry per widget. The name
of the widget is the key and the value gives information about the
-widget. It is either the string `tt(builtin)' for builtin widgets, a
-string of the form `tt(user:)var(name)' for user-defined widgets,
-where var(name) is the name of the shell function implementing the
-widget, or it is a string of the form
-`tt(completion:)var(type)tt(:)var(name)', for completion widgets. In
-the last case var(type) is the name of the builtin widgets the
+widget. It is either
+ the string `tt(builtin)' for builtin widgets,
+ a string of the form `tt(user:)var(name)' for user-defined widgets,
+ where var(name) is the name of the shell function implementing the widget,
+ a string of the form `tt(completion:)var(type)tt(:)var(name)'
+ for completion widgets,
+ or a null value if the widget is not yet fully defined.
+In the penultimate case, var(type) is the name of the builtin widget the
completion widget imitates in its behavior and var(name) is the name
of the shell function implementing the completion widget.
)
diff --git a/Doc/Zsh/mod_zutil.yo b/Doc/Zsh/mod_zutil.yo
index fd6f2f384..dc17161f1 100644
--- a/Doc/Zsh/mod_zutil.yo
+++ b/Doc/Zsh/mod_zutil.yo
@@ -179,13 +179,14 @@ item(tt(zregexparse))(
This implements some internals of the tt(_regex_arguments) function.
)
findex(zparseopts)
-item(tt(zparseopts) [ tt(-DKME) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] var(spec) ...)(
+item(tt(zparseopts) [ tt(-D) tt(-K) tt(-M) tt(-E) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] 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
described by var(opt) is found in the positional parameters it is copied
into the var(array) specified with the tt(-a) option; if the optional
-`tt(=)var(array)' is given, it is instead copied into that array.
+`tt(=)var(array)' is given, it is instead copied into that array, which
+should be declared as a normal array and never as an associative array.
Note that it is an error to give any var(spec) without an
`tt(=)var(array)' unless one of the tt(-a) or tt(-A) options is used.
@@ -232,7 +233,10 @@ first colon.
)
enditem()
-The options of tt(zparseopts) itself are:
+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)
+itself are:
startitem()
item(tt(-a) var(array))(
diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo
index 2fce10780..f68a945ec 100644
--- a/Doc/Zsh/options.yo
+++ b/Doc/Zsh/options.yo
@@ -1598,7 +1598,7 @@ skipped. The option is restored after the trap exits.
Exiting due to tt(ERR_EXIT) has certain interactions with asynchronous
jobs noted in
-ifzman(the section JOBS in in zmanref(zshmisc))\
+ifzman(the section JOBS in zmanref(zshmisc))\
ifnzman(noderef(Jobs & Signals)).
)
pindex(ERR_RETURN)
@@ -1929,7 +1929,8 @@ Emulate bf(ksh) array handling as closely as possible. If this option
is set, array elements are numbered from zero, an array parameter
without subscript refers to the first element instead of the whole array,
and braces are required to delimit a subscript (`tt(${path[2]})' rather
-than just `tt($path[2])').
+than just `tt($path[2])') or to apply modifiers to any parameter
+(`tt(${PWD:h})' rather than `tt($PWD:h)').
)
pindex(KSH_AUTOLOAD)
pindex(NO_KSH_AUTOLOAD)
diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index 672209267..905e92d22 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -933,6 +933,13 @@ tt(zsh/zutil) module.
)
enditem()
)
+vindex(ZSH_ARGZERO)
+item(tt(ZSH_ARGZERO))(
+If zsh was invoked to run a script, this is the name of the script.
+Otherwise, it is the name used to invoke the current shell. This is
+the same as the value of tt($0) when the tt(POSIX_ARGZERO) option is
+set, but is always available.
+)
vindex(ZSH_EXECUTION_STRING)
item(tt(ZSH_EXECUTION_STRING))(
If the shell was started with the option tt(-c), this contains
@@ -955,6 +962,11 @@ item(tt(zsh_scheduled_events))(
See ifzman(the section `The zsh/sched Module' in zmanref(zshmodules))\
ifnzman(noderef(The zsh/sched Module)).
)
+vindex(ZSH_SCRIPT)
+item(tt(ZSH_SCRIPT))(
+If zsh was invoked to run a script, this is the name of the script,
+otherwise it is unset.
+)
vindex(ZSH_SUBSHELL <S>)
item(tt(ZSH_SUBSHELL))(
Readonly integer. Initially zero, incremented each time the shell forks
@@ -1047,7 +1059,8 @@ If the tt(ENV) environment variable is set when zsh is invoked as tt(sh)
or tt(ksh), tt($ENV) is sourced after the profile scripts. The value of
tt(ENV) is subjected to parameter expansion, command substitution, and
arithmetic expansion before being interpreted as a pathname. Note that
-tt(ENV) is em(not) used unless zsh is emulating bf(sh) or bf(ksh).
+tt(ENV) is em(not) used unless the shell is interactive and zsh is
+emulating bf(sh) or bf(ksh).
)
vindex(FCEDIT)
item(tt(FCEDIT))(
@@ -1378,6 +1391,20 @@ item(tt(READNULLCMD) <S>)(
The command name to assume if a single input redirection
is specified with no command. Defaults to tt(more).
)
+vindex(REPORTMEMORY)
+item(tt(REPORTMEMORY))(
+If nonnegative, commands whose maximum resident set size (roughly
+speaking, main memory usage) in megabytes is greater than this
+value have timing statistics reported. The format used to output
+statistics is the value of the tt(TIMEFMT) parameter, which is the same
+as for the tt(REPORTTIME) variable and the tt(time) builtin; note that
+by default this does not output memory usage. Appending
+tt(" max RSS %M") to the value of tt(TIMEFMT) causes it to output the
+value that triggered the report. If tt(REPORTTIME) is also in use,
+at most a single report is printed for both triggers. This feature
+requires the tt(getrusage+LPAR()RPAR()) system call, commonly supported by
+modern Unix-like systems.
+)
vindex(REPORTTIME)
item(tt(REPORTTIME))(
If nonnegative, commands whose combined user and system execution times
@@ -1431,6 +1458,14 @@ The prompt used for spelling correction. The sequence
`tt(%R)' expands to the string which presumably needs spelling
correction, and `tt(%r)' expands to the proposed correction.
All other prompt escapes are also allowed.
+
+The actions available at the prompt are tt([nyae]):
+startsitem()
+sitem(tt(n) +LPAR()`no'+RPAR() +LPAR()default+RPAR())(Discard the correction and run the command.)
+sitem(tt(y) +LPAR()`yes'+RPAR())(Make the correction and run the command.)
+sitem(tt(a) +LPAR()`abort'+RPAR())(Discard the entire command line without running it.)
+sitem(tt(e) +LPAR()`edit'+RPAR())(Resume editing the command line.)
+endsitem()
)
vindex(STTY)
item(tt(STTY))(
@@ -1458,10 +1493,20 @@ take effect.
)
vindex(TERMINFO)
item(tt(TERMINFO) <S>)(
-A reference to a compiled description of the terminal, used by the
-`terminfo' library when the system has it; see manref(terminfo)(5).
-If set, this causes the shell to reinitialise the terminal, making
-the workaround `tt(TERM=$TERM)' unnecessary.
+A reference to your terminfo database, used by the `terminfo' library when the
+system has it; see manref(terminfo)(5).
+If set, this causes the shell to reinitialise the terminal, making the
+workaround `tt(TERM=$TERM)' unnecessary.
+)
+vindex(TERMINFO_DIRS)
+item(tt(TERMINFO_DIRS) <S>)(
+A colon-seprarated list of terminfo databases, used by the `terminfo' library
+when the system has it; see manref(terminfo)(5). This variable is only
+used by certain terminal libraries, in particular ncurses; see
+manref(terminfo)(5) to check support on your system. If set, this
+causes the shell to reinitialise the terminal, making the workaround
+`tt(TERM=$TERM)' unnecessary. Note that unlike other colon-separated
+arrays this is not tied to a zsh array.
)
vindex(TIMEFMT)
item(tt(TIMEFMT))(
@@ -1520,6 +1565,15 @@ A pathname prefix which the shell will use for all temporary files.
Note that this should include an initial part for the file name as
well as any directory names. The default is `tt(/tmp/zsh)'.
)
+vindex(TMPSUFFIX)
+item(tt(TMPSUFFIX))(
+A filename suffix which the shell will use for temporary files created
+by process substitutions (e.g., `tt(=LPAR()var(list)RPAR())').
+Note that the value should include a leading dot `tt(.)' if intended
+to be interpreted as a file extension. The default is not to append
+any suffix, thus this parameter should be assigned only when needed
+and then unset again.
+)
vindex(watch)
vindex(WATCH)
item(tt(watch) <S> <Z> (tt(WATCH) <S>))(
diff --git a/Doc/Zsh/redirect.yo b/Doc/Zsh/redirect.yo
index 35fa773fd..c793638b7 100644
--- a/Doc/Zsh/redirect.yo
+++ b/Doc/Zsh/redirect.yo
@@ -234,6 +234,25 @@ example(date >foo | cat)
writes the date to the file `tt(foo)', and also pipes it to cat.
+Note also that redirections are always expanded in order. This happens
+regardless of the setting of the tt(MULTIOS) option, but with the option
+in effect there are additional consequences. For example,
+the meaning of the expression tt(>&1) will change after a previous
+redirection:
+
+example(date >&1 >output)
+
+In the case above, the tt(>&1) refers to the standard output at the
+start of the line; the result is similar to the tt(tee) command.
+However, consider:
+
+example(date >output >&1)
+
+As redirections are evaluated in order, when the tt(>&1) is encountered
+the standard output is set to the file tt(output) and another copy of
+the output is therefore sent to that file. This is unlikely to be what
+is intended.
+
If the tt(MULTIOS)
option is set, the word after a redirection operator is also subjected
to filename generation (globbing). Thus
diff --git a/Doc/Zsh/restricted.yo b/Doc/Zsh/restricted.yo
index b56b50c6f..6cf9b36b5 100644
--- a/Doc/Zsh/restricted.yo
+++ b/Doc/Zsh/restricted.yo
@@ -10,11 +10,11 @@ restricted mode:
startitemize()
itemiz(changing directories with the tt(cd) builtin)
-itemiz(changing or unsetting the tt(PATH), tt(path), tt(MODULE_PATH),
-tt(module_path), tt(SHELL), tt(HISTFILE), tt(HISTSIZE), tt(GID), tt(EGID),
-tt(UID), tt(EUID), tt(USERNAME), tt(LD_LIBRARY_PATH),
-tt(LD_AOUT_LIBRARY_PATH), tt(LD_PRELOAD) and tt(LD_AOUT_PRELOAD)
-parameters)
+itemiz(changing or unsetting the tt(EGID), tt(EUID), tt(GID),
+tt(HISTFILE), tt(HISTSIZE), tt(IFS), tt(LD_AOUT_LIBRARY_PATH),
+tt(LD_AOUT_PRELOAD), tt(LD_LIBRARY_PATH), tt(LD_PRELOAD),
+tt(MODULE_PATH), tt(module_path), tt(PATH), tt(path), tt(SHELL),
+tt(UID) and tt(USERNAME) parameters)
itemiz(specifying command names containing tt(/))
itemiz(specifying command pathnames using tt(hash))
itemiz(redirecting output to files)
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index 414c8dd65..d68365b94 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -479,6 +479,13 @@ tt(kill) for indicating that text has been killed into the cutbuffer.
When repeatedly invoking a kill widget, text is appended to the cutbuffer
instead of replacing it, but when wrapping such widgets, it is necessary
to call `tt(zle -f kill)' to retain this effect.
+
+tt(vichange) for indicating that the widget represents a vi change that
+can be repeated as a whole with `tt(vi-repeat-change)'. The flag should be set
+early in the function before inspecting the value of tt(NUMERIC) or invoking
+other widgets. This has no effect for a widget invoked from insert mode. If
+insert mode is active when the widget finishes, the change extends until next
+returning to command mode.
)
cindex(completion widgets, creating)
item(tt(-C) var(widget) var(completion-widget) var(function))(
@@ -835,6 +842,20 @@ which always gives the number of the history line being added to the main
shell's history. tt(HISTNO) refers to the line being retrieved within
zle.
)
+vindex(ISEARCHMATCH_ACTIVE)
+vindex(ISEARCHMATCH_START)
+vindex(ISEARCHMATCH_END)
+xitem(tt(ISEARCHMATCH_ACTIVE) (integer))
+xitem(tt(ISEARCHMATCH_START) (integer))
+item(tt(ISEARCHMATCH_END) (integer))(
+tt(ISEARCHMATCH_ACTIVE) indicates whether a part of the tt(BUFFER) is
+currently matched by an incremental search pattern. tt(ISEARCHMATCH_START)
+and tt(ISEARCHMATCH_END) give the location of the matched part and are
+in the same units as tt(CURSOR). They are only valid for reading
+when tt(ISEARCHMATCH_ACTIVE) is non-zero.
+
+All parameters are read-only.
+)
vindex(KEYMAP)
item(tt(KEYMAP) (scalar))(
The name of the currently selected keymap; read-only.
@@ -882,7 +903,7 @@ vindex(MARK)
item(tt(MARK) (integer))(
Like tt(CURSOR), but for the mark. With vi-mode operators that wait for
a movement command to select a region of text, setting tt(MARK) allows
-the selection to extend in both directions from the the initial cursor
+the selection to extend in both directions from the initial cursor
position.
)
vindex(NUMERIC)
@@ -977,6 +998,25 @@ and tt(zle_highlight); see
ifzman(the section CHARACTER HIGHLIGHTING below)\
ifnzman(noderef(Character Highlighting)) for details.
)
+vindex(registers)
+item(tt(registers) (associative array))(
+The contents of each of the vi register buffers. These are
+typically set using tt(vi-set-buffer) followed by a delete, change or
+yank command.
+)
+vindex(SUFFIX_ACTIVE)
+vindex(SUFFIX_START)
+vindex(SUFFIX_END)
+xitem(tt(SUFFIX_ACTIVE) (integer))
+xitem(tt(SUFFIX_START) (integer))
+item(tt(SUFFIX_END) (integer))(
+tt(SUFFIX_ACTIVE) indicates whether an auto-removable completion suffix
+is currently active. tt(SUFFIX_START) and tt(SUFFIX_END) give the
+location of the suffix and are in the same units as tt(CURSOR). They are
+only valid for reading when tt(SUFFIX_ACTIVE) is non-zero.
+
+All parameters are read-only.
+)
vindex(UNDO_CHANGE_NO)
item(tt(UNDO_CHANGE_NO) (integer))(
A number representing the state of the undo history. The only use
@@ -1754,6 +1794,13 @@ tindex(down-case-word)
item(tt(down-case-word) (tt(ESC-L ESC-l)) (unbound) (unbound))(
Convert the current word to all lowercase and move past it.
)
+tindex(vi-down-case)
+item(tt(vi-down-case) (unbound) (tt(gu)) (unbound))(
+Read a movement command from the keyboard, and convert all characters
+from the cursor position to the endpoint of the movement to lowercase.
+If the movement command is tt(vi-down-case), swap the case of all
+characters on the current line.
+)
tindex(kill-word)
item(tt(kill-word) (tt(ESC-D ESC-d)) (unbound) (unbound))(
Kill the current word.
@@ -1914,11 +1961,27 @@ to the left.
tindex(transpose-words)
item(tt(transpose-words) (tt(ESC-T ESC-t)) (unbound) (unbound))(
Exchange the current word with the one before it.
+
+With a positive numeric argument em(N), the word around the cursor, or
+following it if the cursor is between words, is transposed with the
+preceding em(N) words. The cursor is put at the end of the resulting
+group of words.
+
+With a negative numeric argument em(-N), the effect is the same as using
+a positive argument em(N) except that the original cursor position is
+retained, regardless of how the words are rearranged.
)
tindex(vi-unindent)
item(tt(vi-unindent) (unbound) (tt(<)) (unbound))(
Unindent a number of lines.
)
+tindex(vi-up-case)
+item(tt(vi-up-case) (unbound) (tt(gU)) (unbound))(
+Read a movement command from the keyboard, and convert all characters
+from the cursor position to the endpoint of the movement to lowercase.
+If the movement command is tt(vi-up-case), swap the case of all
+characters on the current line.
+)
tindex(up-case-word)
item(tt(up-case-word) (tt(ESC-U ESC-u)) (unbound) (unbound))(
Convert the current word to all caps and move past it.
@@ -2125,10 +2188,18 @@ item(tt(bracketed-paste))(
This widget is invoked when text is pasted to the terminal emulator. It
is not intended to be bound to actual keys but instead to the special
sequence generated by the terminal emulator when text is pasted.
+
+When invoked interactively, the pasted text is inserted to the buffer
+and placed in the cutbuffer.
If a numeric argument is given, shell quoting will be applied to the
-pasted text before it is inserted. When called from a widget function,
-an argument can be given to specify a variable to which pasted text is
-assigned.
+pasted text before it is inserted.
+
+When a named buffer is specified with tt(vi-set-buffer) (tt("x)),
+the pasted text is stored in that named buffer but not inserted.
+
+When called from a widget function as `tt(bracketed-paste) var(name)`, the
+pasted text is assigned to the variable var(name) and no other processing is
+done.
See also the tt(zle_bracketed_paste) parameter.
)
@@ -2166,8 +2237,12 @@ point and mark are not swapped.
)
tindex(execute-named-cmd)
item(tt(execute-named-cmd) (tt(ESC-x)) (tt(:)) (unbound))(
-Read the name of an editor command and
-execute it. A restricted set of editing functions is available in the
+Read the name of an editor command and execute it. Aliasing this
+widget with `tt(zle -A)' or replacing it with `tt(zle -N)' has no
+effect when interpreting key bindings, but `tt(zle execute-named-cmd)'
+will invoke such an alias or replacement.
+
+A restricted set of editing functions is available in the
mini-buffer. Keys are looked up in the special
tt(command) keymap, and if not found there in the main keymap.
An interrupt signal, as defined by the stty setting, will
@@ -2208,7 +2283,8 @@ tindex(execute-last-named-cmd)
item(tt(execute-last-named-cmd) (tt(ESC-z)) (unbound) (unbound))(
Redo the last function executed with tt(execute-named-cmd).
-Currently this command may not be redefined or called by name.
+Like tt(execute-named-cmd), this command may not be redefined,
+but it may be called by name.
)
tindex(get-line)
item(tt(get-line) (tt(ESC-G ESC-g)) (unbound) (unbound))(
@@ -2354,7 +2430,7 @@ concerned replaces the previous contents of the specified buffer. If
a named buffer is specified using a capital, the newly cut text is
appended to the buffer instead of overwriting it. When using the tt("_)
buffer, nothing happens. This can be useful for deleting text without
-affecting the normal registers.
+affecting any buffers.
If no buffer is specified for a cut or change command, tt("1) is used, and
the contents of tt("1) to tt("8) are each shifted along one buffer;
@@ -2530,15 +2606,14 @@ When one of the incremental history search widgets is active, the
area of the command line matched by the search string or pattern.
)
item(tt(region))(
-The region between the cursor (point) and the mark as set with
-tt(set-mark-command). The region is only highlighted if it is active,
-which is the case if tt(set-mark-command) or tt(exchange-point-and-mark)
-has been called and the line has not been subsequently modified. The
-region can be deactivated by calling tt(set-mark-command) with a
-negative numeric argument, or reactivated by calling
-tt(exchange-point-and-mark) with a zero numeric argument. Note
-that whether or not the region is active has no effect on its
-use within widgets, it simply determines whether it is highlighted.
+The currently selected text. In emacs terminology, this is referred to as
+the region and is bounded by the cursor (point) and the mark. The region
+is only highlighted if it is active, which is the case after the mark
+is modified with tt(set-mark-command) or tt(exchange-point-and-mark).
+Note that whether or not the region is active has no effect on its
+use within emacs style widgets, it simply determines whether it is
+highlighted. In vi mode, the region corresponds to selected text in
+visual mode.
)
cindex(special characters, highlighting)
cindex(highlighting, special characters)
generated by cgit v1.2.3 (git 2.39.1) at 2025-06-09 01:24:50 +0000