mirrors/zsh
1
0
Fork 0
mirror of git://git.code.sf.net/p/zsh/code synced 2025-01-17 10:20:55 +01:00
Code Releases Activity

Changes from 4.1 which need to be backported

Browse source
This commit is contained in:
Peter Stephenson 2001-10-16 13:07:17 +00:00
parent 8923b5ab55
commit fb8b49bcae
6 changed files with 799 additions and 233 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

21
ChangeLog
View file

@ -240,6 +240,11 @@
* users/4092: Src/hist.c: Don't lose the last history line
when a signal causes us to rewrite the history file.
2001-08-07 Peter Stephenson <pws@csr.com>
* 15583: Config/installfns.sh: ignore CVS directories for
all function installations, not just with subdirectories.
2001-08-06 Oliver Kiddle <opk@zsh.org>
* 15574: Completion/Unix/Command/_cvs, Completion/Unix/Type/_users,
@ -259,6 +264,17 @@
* 15551: Completion/Unix/Command/_gzip: handle -l and -t
as done for -d; only complete presumably compressed files.
2001-07-27 Peter Stephenson <pws@csr.com>
* 15508: Completion/Unix/Command/_cvs: cvs tag told you it was
going to complete a tag, but then didn't.
2001-07-26 Peter Stephenson <pws@csr.com>
* 15498: Doc/Zsh/builtins.yo, Doc/Zsh/zle.yo: fix cross-refs
for zle builtins and add extra texinfo nodes for zle keymaps,
builtins and widgets.
2001-07-26 Oliver Kiddle <opk@zsh.org>
* 15503: Test/E01options.ztst: fix posixbuiltins test so that it
@ -316,6 +332,11 @@
* 15308: Src/builtin.c: Fix infinite loop on `r OLD=NEW' when OLD
is the empty string, by rejecting replacements with an empty OLD.
2001-07-06 Peter Stephenson <pws@csr.com>
* 15279: Doc/Zsh/expn.yo: describe those ${(S)...%%...} things
so that even I understand what the code does.
2001-07-06 Oliver Kiddle <opk@zsh.org>
* 15252 (and Akinori Musha: 15245): Completion/BSD/Command/_kld,

6
Completion/Unix/Command/_cvs
View file

@ -348,7 +348,7 @@ _cvs_history () {
'*-n+[in module]:module:_cvs_modules' \
'*-p+[in repository]:repository:' \
'-r+[since revision]:rev:' \
'-t+[since tag]:tag:' \
'-t+[since tag]:tag:_cvs_revisions' \
'*-u+[specify user]:user name:' \
'-x+[specify type]:type:_cvs_history_x' \
'-X+[debugging]:arg:' \
@ -497,7 +497,7 @@ _cvs_rtag () {
'(-d)-b[create branch]' \
'-D+[specify date]:date:_cvs_D' \
'-r+[specify revision]:tag:_cvs_revisions' \
':tag:' \
':tag:_cvs_revisions' \
'*:module:_cvs_modules'
}
@ -524,7 +524,7 @@ _cvs_tag () {
'(-d)-f[force a head revision]' \
'-r+[specify revision]:tag:_cvs_revisions' \
'-D+[specify date]:date:_cvs_D' \
':tag:' \
':tag:_cvs_revisions' \
'*:file:_cvs_files'
}

49
Config/installfns.sh
View file

@ -2,32 +2,39 @@
fndir=$DESTDIR$fndir
$sdir_top/mkinstalldirs $fndir || exit 1;
/bin/sh $sdir_top/mkinstalldirs $fndir || exit 1;
# If the source directory is somewhere else, we need to force
# the shell to expand it in that directory, then strip it off.
install=
for file in $FUNCTIONS_INSTALL; do
if test -f "$sdir/$file"; then
install="$install $file"
else
install="$install `echo '' $sdir/$file | sed -e \"s% $sdir/% %g\"`"
fi
done
allfuncs="`grep ' functions=.' ${dir_top}/config.modules |
sed -e '/^#/d' -e '/ link=no/d' -e 's/^.* functions=//'`"
for file in $install; do
if test -f $sdir/$file; then
allfuncs="`cd $sdir_top; echo ${allfuncs}`"
# We now have a list of files, but we need to use `test -f' to check
# (1) the glob got expanded (2) we are not looking at directories.
for file in $allfuncs; do
if test -f $sdir_top/$file; then
case "$file" in
*/CVS/*) continue;;
esac
if test x$FUNCTIONS_SUBDIRS != x -a x$FUNCTIONS_SUBDIRS != xno; then
subfile="$file"
subdir="`echo $file | sed -e 's%/[^/]*$%%'`"
instdir="$fndir/$subdir"
case "$file" in
Completion/comp*)
subdir="`echo $file | sed -e 's%/[^/]*/[^/]*$%%'`"
instdir="$fndir/Completion"
;;
Completion/*)
subdir="`echo $file | sed -e 's%/[^/]*/[^/]*$%%'`"
instdir="$fndir/$subdir"
;;
*)
subdir="`echo $file | sed -e 's%/[^/]*$%%' -e 's%^Functions/%%'`"
instdir="$fndir/$subdir"
;;
esac
else
subfile="`echo $file | sed -e 's%^.*/%%'`"
instdir="$fndir"
fi
$sdir_top/mkinstalldirs $instdir || exit 1
$INSTALL_DATA $sdir/$file $instdir || exit 1
test -d $instdir || /bin/sh $sdir_top/mkinstalldirs $instdir || exit 1
$INSTALL_DATA $sdir_top/$file $instdir || exit 1
fi
done
exit 0

16
Doc/Zsh/builtins.yo
View file

@ -23,6 +23,12 @@ See ifzman(the section `The ARG2 Module' in zmanref(zshmodules))\
ifnzman(noderef(The ARG2 Module)).
)\
)\
def(zlecmd)(1)(\
item(tt(ARG1))(
See ifzman(the section `Zle Builtins' in zmanref(zshzle))\
ifnzman(noderef(Zle Builtins)).
)\
)\
startitem()
prefix(-)
findex(.)
@ -119,7 +125,7 @@ item(var(job) ... tt(&))(
Put each specified var(job) in the background,
or the current job if none is specified.
)
module(bindkey)(zsh/zle)
zlecmd(bindkey)
findex(break)
cindex(exiting loops)
cindex(loops, exiting)
@ -649,8 +655,8 @@ tt(-R); all other arguments and options are printed.
item(tt(-b))(
Recognize all the escape sequences defined for the tt(bindkey) command,
see
ifzman(zmanref(zshmodules))\
ifnzman(noderef(The zsh/zle Module))\
ifzman(zmanref(zshzle))\
ifnzman(noderef(Zle Builtins))\
.
)
item(tt(-m))(
@ -1303,7 +1309,7 @@ If the tt(-m) flag is given the arguments are taken as patterns
(which should be quoted to preserve them from being interpreted as glob
patterns), and all options with names matching these patterns are unset.
)
module(vared)(zsh/zle)
zlecmd(vared)
findex(wait)
cindex(waiting for jobs)
cindex(jobs, waiting for)
@ -1487,7 +1493,7 @@ ifzman(enditem())
)
module(zformat)(zsh/zutil)
module(zftp)(zsh/zftp)
module(zle)(zsh/zle)
zlecmd(zle)
findex(zmodload)
cindex(modules, loading)
cindex(loading modules)

442
Doc/Zsh/expn.yo
View file

@ -1,4 +1,4 @@
texinode(Expansion)(Parameters)(Restricted Shell)(Top)
texinode(Expansion)(Parameters)(Prompt Expansion)(Top)
chapter(Expansion)
cindex(expansion)
sect(Description)
@ -49,36 +49,91 @@ cindex(expansion, history)
History expansion allows you to use words from previous command
lines in the command line you are typing. This simplifies spelling
corrections and the repetition of complicated commands or arguments.
Command lines are saved in the history list, the size of which
is controlled by the tt(HISTSIZE)
vindex(HISTSIZE, use of)
parameter. The most recent command is retained in any case.
A history expansion begins with the first character of the
tt(histchars) parameter which is `tt(!)'
by default and may occur anywhere on the command line; history
expansions do not nest. The `tt(!)' can be escaped with `tt(\)'
or can be enclosed between a pair of single quotes (tt('')) to suppress
its special meaning. Double quotes will em(not) work for this.
Immediately before execution, each command is saved in the history list,
the size of which is controlled by the tt(HISTSIZE) parameter. The one
most recent command is always retained in any case. Each saved command in
the history list is called a history em(event) and is assigned a number,
beginning with 1 (one) when the shell starts up. The history number that
you may see in your prompt (see noderef(Prompt Expansion)) is the number
that is to be assigned to the em(next) command.
Input lines containing history expansions are echoed on the
terminal after being expanded, but before any other
expansions take place or the command gets executed.
startmenu()
menu(Overview)
menu(Event Designators)
menu(Word Designators)
menu(Modifiers)
endmenu()
texinode(Event Designators)(Word Designators)()(History Expansion)
texinode(Overview)(Event Designators)()(History Expansion)
subsect(Overview)
vindex(histchars, use of)
A history expansion begins with the first character of the tt(histchars)
parameter, which is `tt(!)' by default, and may occur anywhere on the
command line; history expansions do not nest. The `tt(!)' can be escaped
with `tt(\)' or can be enclosed between a pair of single quotes (tt(''))
to suppress its special meaning. Double quotes will em(not) work for
this. Following this history character is an optional event designator
(ifzman(see )noderef(Event Designators)) and then an optional word
designator (noderef(Word Designators)); if neither of these designators is
present, no history expansion occurs.
Input lines containing history expansions are echoed after being expanded,
but before any other expansions take place and before the command is
executed. It is this expanded form that is recorded as the history event
for later references.
By default, a history reference with no event designator refers to the
same event as any preceding history reference on that command line; if it
is the only history reference in a command, it refers to the previous
command.
pindex(CSH_JUNKIE_HISTORY, use of)
However, if the option tt(CSH_JUNKIE_HISTORY) is set, then every history
reference with no event specification em(always) refers to the previous
command.
For example, `tt(!)' is the event designator for the previous command, so
`tt(!!:1)' always refers to the first word of the previous command, and
`tt(!!$)' always refers to the last word of the previous command. With
tt(CSH_JUNKIE_HISTORY) set, then `tt(!:1)' and `tt(!$)' function in the
same manner as `tt(!!:1)' and `tt(!!$)', respectively. Conversely, if
tt(CSH_JUNKIE_HISTORY) is unset, then `tt(!:1)' and `tt(!$)' refer to the
first and last words, respectively, of the same event referenced by the
nearest other history reference preceding them on the current command
line, or to the previous command if there is no preceding reference.
The character sequence `tt(^)var(foo)tt(^)var(bar)' (where `tt(^)' is
actually the second character of the tt(histchars) parameter)
repeats the last command, replacing the string var(foo) with var(bar).
More precisely, the sequence `tt(^)var(foo)tt(^)var(bar)tt(^)' is
synonymous with `tt(!!:s)tt(^)var(foo)tt(^)var(bar)tt(^)', hence other
modifiers (see noderef(Modifiers)) may follow the final `tt(^)'.
If the shell encounters the character sequence `tt(!")'
in the input, the history mechanism is temporarily disabled until
the current list (see
ifzman(zmanref(zshmisc))\
ifnzman(noderef(Shell Grammar))\
) is fully parsed. The `tt(!")' is removed from the input, and any
subsequent `tt(!)' characters have no special significance.
findex(fc, use of)
A less convenient but more comprehensible form of command history support
is provided by the tt(fc) builtin.
texinode(Event Designators)(Word Designators)(Overview)(History Expansion)
subsect(Event Designators)
cindex(history event designators)
cindex(event designators, history)
An event designator is a reference to a command-line entry in
the history list.
An event designator is a reference to a command-line entry in the history
list. In the list below, remember that the initial tt(`!') in each item
may be changed to another character by setting the tt(histchars)
parameter.
startitem()
item(tt(!))(
Start a history expansion, except when followed by a blank, newline,
`tt(=)' or `tt(LPAR())'.
`tt(=)' or `tt(LPAR())'. If followed immediately by a word designator
(ifzman(see )noderef(Word Designators)), this forms a history reference
with no event designator (ifzman(see )noderef(Overview)).
)
item(tt(!!))(
Refer to the previous command.
@ -95,7 +150,9 @@ item(tt(!)var(str))(
Refer to the most recent command starting with var(str).
)
item(tt(!?)var(str)[tt(?)])(
Refer to the most recent command containing var(str).
Refer to the most recent command containing var(str). The trailing
`tt(?)' is necessary if this reference is to be followed by a modifier or
followed by any text that is not to be considered part of var(str).
)
item(tt(!#))(
Refer to the current command line typed in so far. The line is
@ -110,10 +167,10 @@ texinode(Word Designators)(Modifiers)(Event Designators)(History Expansion)
subsect(Word Designators)
cindex(history word designators)
cindex(word designators, history)
A word designator indicates which word or words of a given command line will
be included in a history reference. A `tt(:)'
A word designator indicates which word or words of a given command line are
to be included in a history reference. A `tt(:)' usually
separates the event specification from the word designator.
It can be omitted if the word designator begins with a
It may be omitted only if the word designator begins with a
`tt(^)', `tt($)', `tt(*)', `tt(-)' or `tt(%)'.
Word designators include:
@ -129,9 +186,9 @@ sitem(var(x)tt(*))(Abbreviates `var(x)tt(-$)'.)
sitem(var(x)tt(-))(Like `var(x)tt(*)' but omitting word tt($).)
endsitem()
Note that a `tt(%)' word designator will only work when used as
`tt(!%)', `tt(!:%)' or `tt(!?)var(str)tt(?:%)',
and only when used after a tt(!?) expansion. Anything else will result
Note that a `tt(%)' word designator works only when used in one of
`tt(!%)', `tt(!:%)' or `tt(!?)var(str)tt(?:%)', and only when used after a
tt(!?) expansion (possibly in an earlier command). Anything else results
in an error, although the error may not be the most obvious one.
texinode(Modifiers)()(Word Designators)(History Expansion)
subsect(Modifiers)
@ -145,16 +202,19 @@ noted.
startitem()
item(tt(h))(
Remove a trailing pathname component, leaving the head.
Remove a trailing pathname component, leaving the head. This works
like `tt(dirname)'.
)
item(tt(r))(
Remove a trailing suffix of the form `tt(.)var(xxx)', leaving the basename.
Remove a filename extension of the form `tt(.)var(xxx)', leaving
the root name.
)
item(tt(e))(
Remove all but the suffix.
Remove all but the extension.
)
item(tt(t))(
Remove all leading pathname components, leaving the tail.
Remove all leading pathname components, leaving the tail. This works
like `tt(basename)'.
)
item(tt(p))(
Print the new command but do not execute it. Only works with history
@ -162,15 +222,16 @@ expansion.
)
item(tt(q))(
Quote the substituted words, escaping further substitutions. Works
with history expansion and parameter expansion, though in the second
case it is only useful if the resulting text is to be re-evaluated
such as by tt(eval).
with history expansion and parameter expansion, though for parameters
it is only useful if the resulting text is to be re-evaluated such as
by tt(eval).
)
item(tt(Q))(
Remove one level of quotes from the substituted words.
)
item(tt(x))(
Like tt(q), but break into words at each blank.
Like tt(q), but break into words at each blank. Does not work with
parameter expansion.
)
item(tt(l))(
Convert the words to all lowercase.
@ -178,30 +239,6 @@ Convert the words to all lowercase.
item(tt(u))(
Convert the words to all uppercase.
)
item(tt(f))(
(This and the following
tt(F), tt(w) and tt(W) modifier only work with parameter expansion and
filename generation.)
Repeats the immediately (without a colon) following modifier until the
resulting word doesn't change any more.
)
item(tt(F:)var(expr)tt(:))(
Like tt(f), but repeats only var(n) times if the expression
var(expr) evaluates to var(n). Any character can be used instead of
the `tt(:)'; if `tt(LPAR())', `tt([)', or `tt({)'
is used as the opening delimiter,
the closing delimiter should be 'tt(RPAR())', `tt(])', or `tt(})',
respectively.
)
item(tt(w))(
Makes the immediately following modifier work on each word in the
string.
)
item(tt(W:)var(sep)tt(:))(
Like tt(w) but words are considered to be the parts of the string
that are separated by var(sep). Any character can be used instead of
the `tt(:)'; opening parentheses are handled specially, see above.
)
item(tt(s/)var(l)tt(/)var(r)[tt(/)])(
Substitute var(r) for var(l) as described below.
Unless preceded immediately by a tt(g), with no colon between,
@ -230,43 +267,33 @@ the rightmost `tt(?)' in a context scan can similarly be omitted.
Note the same record of the last var(l) and var(r) is maintained
across all forms of expansion.
By default, a history reference with no event specification refers to the same
line as the previous history reference on that command line, unless it is the
first history reference in a command. In that case, a history reference
with no event specification always refers to the previous command. However,
if the option tt(CSH_JUNKIE_HISTORY) is set,
pindex(CSH_JUNKIE_HISTORY, use of)
then history reference with no
event specification will em(always) refer to the previous command.
The following tt(f), tt(F), tt(w) and tt(W) modifiers work only with
parameter expansion and filename generation. They are listed here to
provide a single point of reference for all modifiers.
For example, `tt(!!:1)'
will always refer to the first word of the previous command, and `tt(!!$)'
will always refer to the last word of the previous command. And with
tt(CSH_JUNKIE_HISTORY) set, then `tt(!:1)' and `tt(!$)'
will function in the same manner as `tt(!!:1)' and `tt(!!$)',
respectively. However, if tt(CSH_JUNKIE_HISTORY) is unset, then
`tt(!:1)' and `tt(!$)'
will refer to the first and last words respectively, of the last command
referenced on the current command line. However, if they are the first history
reference on the command line, then they refer to the previous command.
The character sequence `tt(^)var(foo)tt(^)var(bar)' (where `tt(^)' is
actually the second charcter of the tt(histchars) parameter)
repeats the last command, replacing the string var(foo) with var(bar).
More precisely, the sequence `tt(^)var(foo)tt(^)var(bar)tt(^)' is
synonymous with `tt(!!:s)tt(^)var(foo)tt(^)var(bar)tt(^)', hence other
modifiers may follow the final `tt(^)'.
If the shell encounters the character sequence `tt(!")'
in the input, the history mechanism is temporarily disabled until
the current list is fully parsed. The `tt(!")'
is removed from the input, and any subsequent `tt(!)'
characters have no special significance.
A less convenient but more comprehensible
form of command history support
is provided by the tt(fc) builtin.
findex(fc, use of)
startitem()
item(tt(f))(
Repeats the immediately (without a colon) following modifier until the
resulting word doesn't change any more.
)
item(tt(F:)var(expr)tt(:))(
Like tt(f), but repeats only var(n) times if the expression
var(expr) evaluates to var(n). Any character can be used instead of
the `tt(:)'; if `tt(LPAR())', `tt([)', or `tt({)'
is used as the opening delimiter,
the closing delimiter should be 'tt(RPAR())', `tt(])', or `tt(})',
respectively.
)
item(tt(w))(
Makes the immediately following modifier work on each word in the
string.
)
item(tt(W:)var(sep)tt(:))(
Like tt(w) but words are considered to be the parts of the string
that are separated by var(sep). Any character can be used instead of
the `tt(:)'; opening parentheses are handled specially, see above.
)
enditem()
texinode(Process Substitution)(Parameter Expansion)(History Expansion)(Expansion)
sect(Process Substitution)
cindex(process substitution)
@ -276,14 +303,14 @@ Each command argument of the form
`tt(>LPAR())var(list)tt(RPAR())' or
`tt(=LPAR())var(list)tt(RPAR())'
is subject to process substitution.
In the case of the tt(<) or tt(>) forms, the shell will run process
var(list) asynchronously, connected to a named pipe (FIFO).
The name of this pipe will become the argument to the command.
If the form with tt(>)
is selected then writing on this file will provide input for var(list).
If tt(<) is used, then the file passed as an argument will
be a named pipe connected to the output of the var(list) process.
For example,
In the case of the tt(<) or tt(>) forms, the shell runs process
var(list) asynchronously. If the system supports the tt(/dev/fd)
mechanism, the command argument is the name of the device file
corresponding to a file descriptor; otherwise, if the system supports named
pipes (FIFOs), the command argument will be a named pipe. If the form with
tt(>) is selected then writing on this special file will provide input for
var(list). If tt(<) is used, then the file passed as an argument will
be connected to the output of the var(list) process. For example,
nofill(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR() |
tee >LPAR())var(process1)tt(RPAR() >LPAR())var(process2)tt(RPAR() >/dev/null))
@ -291,9 +318,19 @@ tee >LPAR())var(process1)tt(RPAR() >LPAR())var(process2)tt(RPAR() >/dev/null))
cuts fields 1 and 3 from the files var(file1) and var(file2) respectively,
pastes the results together, and sends it to the processes
var(process1) and var(process2).
Note that the file, which is passed as an argument to the command,
is a system pipe, so programs that expect to lseek (see manref(lseek)(2))
on the file will not work.
Both the tt(/dev/fd) and the named pipe implementation have drawbacks. In
the former case, some programmes may automatically close the file
descriptor in question before examining the file on the command line,
particularly if this is necessary for security reasons such as when the
programme is running setuid. In the second case, if the
programme does not actually open the file the subshell attempting to read
from or write to the pipe will (in a typical implementation, different
operating systems may have different behaviour) block for ever and have to
be killed explicitly. In both cases, the shell actually supplies the
information using a pipe, so that programmes that expect to lseek
(see manref(lseek)(2)) on the file will not work.
Also note that the previous example can be more compactly and
efficiently written (provided the tt(MULTIOS) option is set) as:
@ -422,13 +459,21 @@ 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.
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
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}).
The var(pattern) may begin with a `tt(#)', in which case the
var(pattern) must match at the start of the string, or `tt(%)', in
which case it must match at the end of the string. The var(repl) may
be an empty string, in which case the final `tt(/)' may also be omitted.
To quote the final `tt(/)' in other cases it should be preceded by two
backslashes (i.e., a quoted backslash); this is not necessary if the
`tt(/)' occurs inside a substituted parameter.
`tt(/)' occurs inside a substituted parameter. Note also that 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
@ -511,11 +556,15 @@ possible to perform nested operations: tt(${${foo#head}%tail})
substitutes the value of tt($foo) with both `tt(head)' and `tt(tail)'
deleted. The form with tt($LPAR())...tt(RPAR()) is often useful in
combination with the flags described next; see the examples below.
Each var(name) or nested tt(${)...tt(}) in a parameter expansion may
also be followed by a subscript expression as described in
ifzman(em(Array Parameters) in zmanref(zshparam))\
ifnzman(noderef(Array Parameters)).
Note that double quotes may appear around nested substitutions, in which
Note that double quotes may appear around nested expressions, in which
case only the part inside is treated as quoted; for example,
tt(${(f)"$(foo)"}) quotes the result of tt($(foo)), but the flag `tt((f))'
(see below) is applied using the rules for unquoted substitutions. Note
(see below) is applied using the rules for unquoted expansions. Note
further that quotes are themselves nested in this context; for example, in
tt("${(@f)"$(foo)"}"), there are two sets of quotes, one surrounding the
whole expression, the other (redundant) surrounding the tt($(foo)) as
@ -534,19 +583,19 @@ in place of the colon as delimiters. The following flags are supported:
startitem()
item(tt(A))(
Create an array parameter with tt(${)...tt(=)...tt(}),
tt(${)...tt(:=)...tt(}) or tt(${)...tt(::=)...tt(}).
If this flag is repeated (as in tt(AA)), create an associative
Create an array parameter with `tt(${)...tt(=)...tt(})',
`tt(${)...tt(:=)...tt(})' or `tt(${)...tt(::=)...tt(})'.
If this flag is repeated (as in `tt(AA)'), create an associative
array parameter. Assignment is made before sorting or padding.
The var(name) part may be a subscripted range for ordinary
arrays; the var(word) part em(must) be converted to an array, for
example by using tt(${(AA)=)var(name)tt(=)...tt(}) to activate word
example by using `tt(${(AA)=)var(name)tt(=)...tt(})' to activate word
splitting, when creating an associative array.
)
item(tt(@))(
In double quotes, array elements are put into separate words.
E.g., tt("${(@)foo}") is equivalent to tt("${foo[@]}") and
tt("${(@)foo[1,2]}") is the same as tt("$foo[1]" "$foo[2]").
E.g., `tt("${(@)foo}")' is equivalent to `tt("${foo[@]}")' and
`tt("${(@)foo[1,2]}")' is the same as `tt("$foo[1]" "$foo[2]")'.
)
item(tt(e))(
Perform em(parameter expansion), em(command substitution) and
@ -588,7 +637,7 @@ item(tt(q))(
Quote the resulting words with backslashes. If this flag is given
twice, the resulting words are quoted in single quotes and if it is
given three times, the words are quoted in double quotes. If it is
given four times, the words are quoted in single quotes preceded a tt($).
given four times, the words are quoted in single quotes preceded by a tt($).
)
item(tt(Q))(
Remove one level of quotes from the resulting words.
@ -601,7 +650,7 @@ setting of the tt(PROMPT_PERCENT), tt(PROMPT_SUBST) and
tt(PROMPT_BANG) options.
)
item(tt(X))(
With this flag parsing errors occuring with the tt(Q) flag or the
With this flag parsing errors occurring with the tt(Q) and tt(e) flags or the
pattern matching forms such as `tt(${)var(name)tt(#)var(pattern)tt(})'
are reported. Without the flag they are silently ignored.
)
@ -665,13 +714,22 @@ item(tt(f))(
Split the result of the expansion to lines. This is a shorthand
for `tt(ps:\n:)'.
)
item(tt(z))(
Split the result of the expansion into words using shell parsing to
find the words, i.e. taking into account any quoting in the value.
Note that this is done very late, as for the `tt((s))' flag. So to
access single words in the result, one has to use nested expansions as
in `tt(${${(z)foo}[2]})'. Likewise, to remove the quotes in the
resulting words one would do: `tt(${(Q)${(z)foo}})'.
)
item(tt(t))(
Use a string describing the type of the parameter where the value
of the parameter would usually appear. This string consists of keywords
separated by hyphens (`tt(-)'). The first keyword in the string describes
the main type, it can be one of `tt(scalar)', `tt(array)', `tt(integer)',
or `tt(association)'. The other keywords describe the type in more
detail:
`tt(float)' or `tt(association)'. The other keywords describe the type in
more detail:
startitem()
item(tt(local))(
@ -733,10 +791,26 @@ Search the var(expr)th match (where var(expr) evaluates to a number).
This only applies when searching for substrings, either with the tt(S)
flag, or with tt(${)...tt(/)...tt(}) (only the var(expr)th match is
substituted) or tt(${)...tt(//)...tt(}) (all matches from the
var(expr)th on are substituted). The var(expr)th match is counted
such that there is either one or zero matches from each starting
position in the string, although for global substitution matches
overlapping previous replacements are ignored.
var(expr)th on are substituted). The default is to take the first match.
The var(expr)th match is counted such that there is either one or zero
matches from each starting position in the string, although for global
substitution matches overlapping previous replacements are ignored. With
the tt(${)...tt(%)...tt(}) and tt(${)...tt(%%)...tt(}) forms, the starting
position for the match moves backwards from the end as the index increases,
while with the other forms it moves forward from the start.
Hence with the string
example(which switch is the right switch for Ipswich?)
substitutions of the form
tt(${)LPAR()tt(SI:)var(N)tt(:)RPAR()tt(string#w*ch}) as var(N) increases
from 1 will match and remove `tt(which)', `tt(witch)', `tt(witch)' and
`tt(wich)'; the form using `tt(##)' will match and remove `tt(which switch
is the right switch for Ipswich)', `tt(witch is the right switch for
Ipswich)', `tt(witch for Ipswich)' and `tt(wich)'. The form using `tt(%)'
will remove the same matches as for `tt(#)', but in reverse order, and the
form using `tt(%%)' will remove the same matches as for `tt(##)' in reverse
order.
)
item(tt(M))(
Include the matched portion in the result.
@ -824,7 +898,7 @@ Note that the `tt((F))' flag implicitly supplies a string for joining in this
manner.
)
item(tt(8.) em(Forced Splitting))(
If one of the `tt((s))' or `tt((f))' flags are present, or the `tt(=)'
If one of the `tt((s))', `tt((f))' or `tt((z))' flags are present, or the `tt(=)'
specifier was present (e.g. tt(${=)var(var)tt(})), the word is split on
occurrences of the specified string, or (for tt(=) with neither of the two
flags present) any of the characters in tt($IFS).
@ -833,7 +907,7 @@ item(tt(9.) em(Shell Word Splitting))(
If no `tt((s))', `tt((f))' or `tt(=)' was given, but the word is not
quoted and the option tt(SH_WORD_SPLIT) is set, the word is split on
occurrences of any of the characters in tt($IFS). Note this step, too,
take place at all levels of a nested substitution.
takes place at all levels of a nested substitution.
)
item(tt(10.) em(Re-Evaluation))(
Any `tt((e))' flag is applied to the value, forcing it to be re-examined
@ -867,7 +941,7 @@ that this is a scalar, so that (despite the `tt((@))' flag) the subscript
picks the first character.
)
item(tt("${${(@)foo}[1]}"))(
The produces the result `tt(bar)'. In this case, the inner substitution
This produces the result `tt(bar)'. In this case, the inner substitution
tt("${(@)foo}") produces the array `tt(LPAR()bar baz)tt(RPAR())'. The outer
substitution tt("${...[1]}") detects that this is an array and picks the
first word. This is similar to the simple case tt("${foo[1]}").
@ -1068,6 +1142,7 @@ Matches any of the enclosed characters. Ranges of characters
can be specified by separating two characters by a `tt(-)'.
A `tt(-)' or `tt(])' may be matched by including it as the
first character in the list.
cindex(character classes)
There are also several named classes of characters, in the form
`tt([:)var(name)tt(:])' with the following meanings: `tt([:alnum:])'
alphanumeric, `tt([:alpha:])' alphabetic,
@ -1096,6 +1171,14 @@ Matches any number in the range var(x) to var(y), inclusive.
Either of the numbers may be omitted to make the range open-ended;
hence `tt(<->)' matches any number. To match individual digits, the
tt([)...tt(]) form is more efficient.
Be careful when using other wildcards adjacent to patterns of this form;
for example, tt(<0-9>*) will actually match any number whatsoever at the
start of the string, since the `tt(<0-9>)' will match the first digit, and
the `tt(*)' will match any others. This is a trap for the unwary, but is
in fact an inevitable consequence of the rule that the longest possible
match always succeeds. Expressions such as `tt(<0-9>[^[:digit:]]*)' can be
used instead.
)
item(tt(LPAR())...tt(RPAR()))(
Matches the enclosed pattern. This is used for grouping.
@ -1186,7 +1269,7 @@ The precedence of the operators given above is (highest) `tt(^)', `tt(/)',
`tt(~)', `tt(|)' (lowest); the
remaining operators are simply treated from left to right as part of a
string, with `tt(#)' and `tt(##)' applying to the shortest possible
preceeding unit (i.e. a character, `tt(?)', `tt([)...tt(])',
preceding unit (i.e. a character, `tt(?)', `tt([)...tt(])',
`tt(<)...tt(>)', or a parenthesised expression). As mentioned
above, a `tt(/)' used as a directory separator may not appear inside
parentheses, while a `tt(|)' must do so; in patterns used in other contexts
@ -1298,6 +1381,31 @@ item(tt(a)var(num))(
Approximate matching: var(num) errors are allowed in the string matched by
the pattern. The rules for this are described in the next subsection.
)
item(tt(s), tt(e))(
Unlike the other flags, these have only a local effect, and each must
appear on its own: `tt((#s))' and `tt((#e))' are the only valid forms.
The `tt((#s))' flag succeeds only at the start of the test string, and the
`tt((#e))' flag succeeds only at the end of the test string; they
correspond to `tt(^)' and `tt($)' in standard regular expressions. They
are useful for matching path segments in patterns other than those in
filename generation (where path segments are in any case treated
separately). For example, `tt(*((#s)|/)test((#e)|/)*)' matches a path
segment `tt(test)' in any of the following strings: tt(test),
tt(test/at/start), tt(at/end/test), tt(in/test/middle).
Another use is in parameter substitution; for example
`tt(${array/(#s)A*Z(#e)})' will remove only elements of an array which
match the complete pattern `tt(A*Z)'. There are other ways of performing
many operations of this type, however the combination of the substitution
operations `tt(/)' and `tt(//)' with the `tt((#s))' and `tt((#e))' flags
provides a single simple and memorable method.
Note that assertions of the form `tt((^(#s)))' also work, i.e. match
anywhere except at the start of the string, although this actually means
`anything except a zero-length portion at the start of the string'; you
need to use `tt((""~(#s)))' to match a zero-length portion of the string
not at the start.
)
enditem()
For example, the test string tt(fooxx) can be matched by the pattern
@ -1374,6 +1482,13 @@ crucial one for establishing whether to use approximation; for example,
tt((#a1)abc(#a0)xyz) will not match tt(abcdxyz), because the error occurs
at the `tt(x)', where approximation is turned off.
Entire path segments may be matched approximately, so that
`tt((#a1)/foo/d/is/available/at/the/bar)' allows one error in any path
segment. This is much less efficient than without the tt((#a1)), however,
since every directory in the path must be scanned for a possible
approximate match. It is best to place the tt((#a1)) after any path
segments which are known to be correct.
subsect(Recursive Globbing)
A pathname component of the form `tt(LPAR())var(foo)tt(/RPAR()#)'
matches a path consisting of zero or more directories
@ -1391,10 +1506,11 @@ or
example(ls **/bar)
does a recursive directory search for files named `tt(bar)' (potentially
including the file `tt(bar)' in the current directory), not following
symbolic links. To follow links, use `tt(***/)'. Neither of these can be
combined with other forms of globbing within the same filename segment; in
that case, the `tt(*)' operators revert to their usual effect.
including the file `tt(bar)' in the current directory). This form does not
follow symbolic links; the alternative form `tt(***/)' does, but is
otherwise identical. Neither of these can be combined with other forms of
globbing within the same path segment; in that case, the `tt(*)'
operators revert to their usual effect.
subsect(Glob Qualifiers)
cindex(globbing, qualifiers)
cindex(qualifiers, globbing)
@ -1409,7 +1525,8 @@ containing no `tt(|)' or `tt(LPAR())' characters (or `tt(~)' if it is special)
is taken as a set of
glob qualifiers. A glob subexpression that would normally be taken as glob
qualifiers, for example `tt((^x))', can be forced to be treated as part of
the glob pattern by doubling the parentheses, for example `tt(((^x)))'.
the glob pattern by doubling the parentheses, in this case producing
`tt(((^x)))'.
A qualifier may be any one of the following:
@ -1521,29 +1638,35 @@ permission, and for which other users don't have read or execute
permission.
)
item(tt(e)var(string))(
The var(string) will be executed and the return value determines if the
filename should be included in the list (if it is zero) or not (if it
is non-zero). The first character after the `tt(e)' will be used as a
separator and anything up to the next matching separator will be taken
as the var(string) (`tt([)', `tt({)', and `tt(<)' match `tt(])',
`tt(})', and `tt(>)' respectively, any other character matches
itself). Note that expansions have to be quoted in the var(string) to
prevent them from being expanded before globbing is done.
The var(string) will be executed as shell code. The filename will be
included in the list if and only if the code returns a zero status (usually
the status of the last command). The first character after the `tt(e)'
will be used as a separator and anything up to the next matching separator
will be taken as the var(string); `tt([)', `tt({)', and `tt(<)' match
`tt(])', `tt(})', and `tt(>)', respectively, while any other character
matches itself. Note that expansions must be quoted in the var(string)
to prevent them from being expanded before globbing is done.
During the execution of var(string) the parameter tt(REPLY) is set to
the filename currently being tested. It may also be set to any string
to make this string be inserted into the list instead of the original
filename. Also, the parameter tt(reply) may be set to an array or a
string and if it is, these strings will be inserted instead of the
value of the tt(REPLY) parameter. For security reasons, tt(reply)
will be unset by the shell before the var(string) is executed.
vindex(REPLY, use of)
vindex(reply, use of)
During the execution of var(string) the filename currently being tested is
available in the parameter tt(REPLY); the parameter may be altered to
a string to be inserted into the list instead of the original
filename. In addition, the parameter tt(reply) may be set to an array or a
string, which overrides the value of tt(REPLY). If set to an array, the
latter is inserted into the command line word by word.
For example, suppose a directory contains a single file `tt(lonely)'. Then
the expression `tt(*(e:'reply=(${REPLY}{1,2})':))' will cause the words
`tt(lonely1 lonely2)' to be inserted into the command line. Note the
quotation marks.
)
item(tt(d)var(dev))(
files on the device var(dev)
)
item(tt(l)[tt(-)|tt(PLUS())]var(ct))(
files having a link count less than var(ct) (tt(-)), greater than
var(ct) (tt(PLUS())), or is equal to var(ct)
var(ct) (tt(PLUS())), or equal to var(ct)
)
item(tt(U))(
files owned by the effective user ID
@ -1618,19 +1741,24 @@ pindex(NUMERIC_GLOB_SORT, setting in pattern)
)
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
are sorted depending on the size (length) of the files, if tt(l)
they are sorted by the number of links, and if tt(a), tt(m), and tt(c)
tt(n) they are sorted by name (the default); 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
inode change respectively. Note that tt(a), tt(m), and tt(c) compare
the age against the current time, hence the first name in the list is the
the youngest file. Also note that the modifiers tt(^) and tt(-) are
used, so `tt(*(^-oL))' gives a list of all files sorted by file size in
descending order, following any symbolic links.
inode change respectively; if var(d), files in subdirectories appear before
those in the current directory at each level of the search --- this is best
combined with other criteria, for example `tt(odon)' to sort on names for
files within the same directory. Note that tt(a), tt(m), and tt(c) compare
the age against the current time, hence the first name in the list is the
youngest file. Also note that the modifiers tt(^) and tt(-) are used,
so `tt(*(^-oL))' gives a list of all files sorted by file size in descending
order, following any symbolic links.
)
item(tt(O)var(c))(
like `tt(o)', but sorts in descending order; i.e. `tt(*(^oc))' is the
same as `tt(*(Oc))' and `tt(*(^Oc))' is the same as `tt(*(oc))'
same as `tt(*(Oc))' and `tt(*(^Oc))' is the same as `tt(*(oc))'; `tt(Od)'
puts files in the current directory before those in subdirectories at each
level of the search.
)
item(tt([)var(beg)[tt(,)var(end)]tt(]))(
specifies which of the matched filenames should be included in the
@ -1644,7 +1772,11 @@ enditem()
More than one of these lists can be combined, separated by commas. The
whole list matches if at least one of the sublists matches (they are
`or'ed, the qualifiers in the sublists are `and'ed).
`or'ed, the qualifiers in the sublists are `and'ed). Some qualifiers,
however, affect all matches generated, independent of the sublist in
which they are given. These are the qualifiers `tt(M)', `tt(T)',
`tt(N)', `tt(D)', `tt(n)', `tt(o)', `tt(O)' and the subscripts given
in brackets (`tt([...])').
If a `tt(:)' appears in a qualifier list, the remainder of the expression in
parenthesis is interpreted as a modifier (see noderef(Modifiers)

498
Doc/Zsh/zle.yo
View file

@ -2,6 +2,7 @@ texinode(Zsh Line Editor)(Completion Widgets)(Shell Builtin Commands)(Top)
chapter(Zsh Line Editor)
cindex(line editor)
cindex(editor, line)
cindex(ZLE)
sect(Description)
pindex(ZLE, use of)
If the tt(ZLE) option is set (which it is by default in interactive shells)
@ -19,6 +20,14 @@ cindex(editor ksh style)
This mode
is similar to bf(ksh), and uses no termcap sequences. If tt(TERM) is
"emacs", the tt(ZLE) option will be unset by default.
startmenu()
menu(Keymaps)
menu(Zle Builtins)
menu(Zle Widgets)
endmenu()
texinode(Keymaps)(Zle Builtins)()(Zsh Line Editor)
sect(Keymaps)
cindex(keymaps)
cindex(key bindings)
@ -77,6 +86,372 @@ and the command reading process starts again using these fake keystrokes.
This input can itself invoke further replacement strings, but in order to
detect loops the process will be stopped if there are twenty such replacements
without a real command being read.
texinode(Zle Builtins)(Zle Widgets)(Keymaps)(Zsh Line Editor)
sect(Zle Builtins)
cindex(zle, builtin commands)
The ZLE module contains three related builtin commands. The tt(bindkey)
command manipulates keymaps and key bindings; the tt(vared) command invokes
ZLE on the value of a shell parameter; and the tt(zle) command manipulates
editing widgets and allows command line access to ZLE commands from within
shell functions.
startitem()
findex(bindkey)
cindex(keys, rebinding)
cindex(rebinding keys)
cindex(keys, binding)
cindex(binding keys)
cindex(keymaps)
xitem(tt(bindkey) [ var(options) ] tt(-l))
xitem(tt(bindkey) [ var(options) ] tt(-d))
xitem(tt(bindkey) [ var(options) ] tt(-D) var(keymap) ...)
xitem(tt(bindkey) [ var(options) ] tt(-A) var(old-keymap new-keymap))
xitem(tt(bindkey) [ var(options) ] tt(-N) var(new-keymap) [ var(old-keymap) ])
xitem(tt(bindkey) [ var(options) ] tt(-m))
xitem(tt(bindkey) [ var(options) ] tt(-r) var(in-string) ...)
xitem(tt(bindkey) [ var(options) ] tt(-s) var(in-string out-string) ...)
xitem(tt(bindkey) [ var(options) ] var(in-string command) ...)
item(tt(bindkey) [ var(options) ] [ var(in-string) ])(
tt(bindkey)'s options can be divided into three categories: keymap selection,
operation selection, and others. The keymap selection options are:
startitem()
item(tt(-e))(
Selects keymap `tt(emacs)', and also links it to `tt(main)'.
)
item(tt(-v))(
Selects keymap `tt(viins)', and also links it to `tt(main)'.
)
item(tt(-a))(
Selects keymap `tt(vicmd)'.
)
item(tt(-M))(
The first non-option argument is used as a keymap name,
and does not otherwise count as an argument.
)
enditem()
If a keymap selection is required and none of the options above are used, the
`tt(main)' keymap is used. Some operations do not permit a keymap to be
selected, namely:
startitem()
item(tt(-l))(
List all existing keymap names. If the tt(-L)
option is also used, list in the form of tt(bindkey)
commands to create the keymaps.
)
item(tt(-d))(
Delete all existing keymaps and reset to the default state.
)
item(tt(-D) var(keymap) ...)(
Delete the named var(keymap)s.
)
item(tt(-A) var(old-keymap new-keymap))(
Make the var(new-keymap) name an alias for var(old-keymap), so that
both names refer to the same keymap. The names have equal standing;
if either is deleted, the other remains. If there is already a keymap
with the var(new-keymap) name, it is deleted.
)
item(tt(-N) var(new-keymap) [ var(old-keymap) ])(
Create a new keymap, named var(new-keymap). If a keymap already has that
name, it is deleted. If an var(old-keymap) name is given, the new keymap
is initialized to be a duplicate of it, otherwise the new keymap will
be empty.
)
enditem()
To use a newly created keymap, it should be linked to tt(main). Hence
the sequence of commands to create and use a new keymap `tt(mymap)'
initialized from the tt(emacs) keymap (which remains unchanged) is:
example(bindkey -N mymap emacs
bindkey -A mymap main)
Note that while `tt(bindkey -A) var(newmap) tt(main)' will work when
var(newmap) is tt(emacs) or tt(viins), it will not work for tt(vicmd), as
switching from vi insert to command mode becomes impossible.
The following operations act on the `tt(main)' keymap if no keymap
selection option was given:
startitem()
item(tt(-m))(
Add the built-in set of meta-key bindings to the selected keymap.
Only keys that are unbound or bound to tt(self-insert) are affected.
)
item(tt(-r) var(in-string) ...)(
Unbind the specified var(in-string)s in the selected keymap.
This is exactly equivalent to binding the strings to tt(undefined-key).
When tt(-R) is also used, interpret the var(in-string)s as ranges.
When tt(-p) is also used, the var(in-string)s specify prefixes. Any
binding that has the given var(in-string) as a prefix, not including the
binding for the var(in-string) itself, if any, will be removed. For
example,
example(bindkey -rpM viins '^[')
will remove all bindings in the vi-insert keymap beginning with an escape
character (probably cursor keys), but leave the binding for the escape
character itself (probably tt(vi-cmd-mode)). This is incompatible with the
option tt(-R).
)
item(tt(-s) var(in-string out-string) ...)(
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.
)
item(var(in-string command) ...)(
Bind each var(in-string) to each var(command).
When tt(-R) is used, interpret the var(in-string)s as ranges.
)
item([ var(in-string) ])(
List key bindings. If an var(in-string) is specified, the binding of
that string in the selected keymap is displayed. Otherwise, all key
bindings in the selected keymap are displayed. (As a special case,
if the tt(-e) or tt(-v) option is used alone, the keymap is em(not)
displayed - the implicit linking of keymaps is the only thing that
happens.)
When the option tt(-p) is used, the var(in-string) must be present.
The listing shows all bindings which have the given key sequence as a
prefix, not including any bindings for the key sequence itself.
When the tt(-L) option is used, the list is in the form of tt(bindkey)
commands to create the key bindings.
)
enditem()
When the tt(-R) option is used as noted above, a valid range consists of
two characters, with an optional `tt(-)' between them. All characters
between the two specified, inclusive, are bound as specified.
For either var(in-string) or var(out-string), the following
escape sequences are recognised:
startsitem()
sitem(tt(\a))(bell character)
sitem(tt(\b))(backspace)
sitem(tt(\e), tt(\E))(escape)
sitem(tt(\f))(form feed)
sitem(tt(\n))(linefeed (newline))
sitem(tt(\r))(carriage return)
sitem(tt(\t))(horizontal tab)
sitem(tt(\v))(vertical tab)
sitem(tt(\)var(NNN))(character code in octal)
sitem(tt(\x)var(NN))(character code in hexadecimal)
sitem(tt(\M)[tt(-)]var(X))(character with meta bit set)
sitem(tt(\C)[tt(-)]var(X))(control character)
sitem(tt(^)var(X))(control character)
endsitem()
In all other cases, `tt(\)' escapes the following character. Delete is
written as `tt(^?)'. Note that `tt(\M^?)' and `tt(^\M?)' are not the same,
and that (unlike emacs), the bindings `tt(\M-)var(X)' and `tt(\e)var(X)'
are entirely distinct, although they are initialized to the same bindings
by `tt(bindkey -m)'.
)
findex(vared)
cindex(parameters, editing)
cindex(editing parameters)
item(tt(vared) [ tt(-Aache) ] [ tt(-p) var(prompt) ] [ tt(-r) var(rprompt) ] var(name))(
The value of the parameter var(name) is loaded into the edit
buffer, and the line editor is invoked. When the editor exits,
var(name) is set to the string value returned by the editor.
When the tt(-c) flag is given, the parameter is created if it doesn't
already exist. The tt(-a) flag may be given with tt(-c) to create
an array parameter, or the tt(-A) flag to create an associative array.
If the type of an existing parameter does not match the type to be
created, the parameter is unset and recreated.
If an array or array slice is being edited, separator characters as defined
in tt($IFS) will be shown quoted with a backslash, as will backslashes
themselves. Conversely, when the edited text is split into an array, a
backslash quotes an immediately following separator character or backslash;
no other special handling of backslashes, or any handling of quotes, is
performed.
Individual elements of existing array or associative array parameters
may be edited by using subscript syntax on var(name). New elements are
created automatically, even without tt(-c).
If the tt(-p) flag is given, the following string will be taken as
the prompt to display at the left. If the tt(-r) flag is given,
the following string gives the prompt to display at the right. If the
tt(-h) flag is specified, the history can be accessed from ZLE. If the
tt(-e) flag is given, typing tt(^D) (Control-D) on an empty line
causes tt(vared) to exit immediately with a non-zero return value.
)
findex(zle)
cindex(widgets, rebinding)
cindex(rebinding widgets)
cindex(widgets, binding)
cindex(binding widgets)
cindex(widgets, invoking)
cindex(invoking widgets)
cindex(widgets, calling)
cindex(calling widgets)
cindex(widgets, defining)
cindex(defining widgets)
xitem(tt(zle) tt(-l) [ tt(-L) | tt(-a) ] [ var(string) ... ])
xitem(tt(zle) tt(-D) var(widget) ...)
xitem(tt(zle) tt(-A) var(old-widget) var(new-widget))
xitem(tt(zle) tt(-N) var(widget) [ var(function) ])
xitem(tt(zle) tt(-C) var(widget) var(completion-widget) var(function))
xitem(tt(zle) tt(-R) [ tt(-c) ] [ var(display-string) ] [ var(string) ... ])
xitem(tt(zle) tt(-M) var(string))
xitem(tt(zle) tt(-U) var(string))
xitem(tt(zle) tt(-I))
xitem(tt(zle) var(widget) tt([ -n) var(num) tt(]) tt([ -N ]) var(args) ...)
item(tt(zle))(
The tt(zle) builtin performs a number of different actions concerning
ZLE. Which operation it performs depends on its options:
startitem()
item(tt(-l) [ tt(-L) | tt(-a) ])(
List all existing user-defined widgets. If the tt(-L)
option is used, list in the form of tt(zle)
commands to create the widgets.
When combined with the tt(-a) option, all widget names are listed,
including the builtin ones. In this case the tt(-L) option is ignored.
If at least one var(string) is given, nothing will be printed but the
return status will be zero if all var(string)s are names of existing
widgets (or of user-defined widgets if the tt(-a) flag is not given)
and non-zero if at least one var(string) is not a name of an defined
widget.
)
item(tt(-D) var(widget) ...)(
Delete the named var(widget)s.
)
item(tt(-A) var(old-widget) var(new-widget))(
Make the var(new-widget) name an alias for var(old-widget), so that
both names refer to the same widget. The names have equal standing;
if either is deleted, the other remains. If there is already a widget
with the var(new-widget) name, it is deleted.
)
item(tt(-N) var(widget) [ var(function) ])(
Create a user-defined widget. If there is already a widget with the
specified name, it is overwritten. When the new
widget is invoked from within the editor, the specified shell var(function)
is called. If no function name is specified, it defaults to
the same name as the widget. For further information, see the section
em(Widgets) in
ifzman(zmanref(zshzle))\
ifnzman(noderef(Zsh Line Editor))\
.
)
cindex(completion widgets, creating)
item(tt(-C) var(widget) var(completion-widget) var(function))(
Create a user-defined completion widget named var(widget). The
completion widget will behave like the built-in completion-widget
whose name is given as var(completion-widget). To generate the
completions, the shell function var(function) will be called.
For further information, see
ifzman(zmanref(zshcompwid))\
ifnzman(noderef(Completion Widgets))\
.
)
item(tt(-R) [ tt(-c) ] [ var(display-string) ] [ var(string) ... ])(
Redisplay the command line; this is to be called from within a user-defined
widget to allow changes to become visible. If a var(display-string) is
given and not empty, this is shown in the status line (immediately
below the line being edited).
If the optional var(string)s are given they are listed below the
prompt in the same way as completion lists are printed. If no
var(string)s are given but the tt(-c) option is used such a list is
cleared.
Note that this option is only useful for widgets that do not exit
immediately after using it because the strings displayed will be erased
immediately after return from the widget.
This command can safely be called outside user defined widgets; if zle is
active, the display will be refreshed, while if zle is not active, the
command has no effect. In this case there will usually be no other
arguments. The status is zero if zle was active, else one.
)
item(tt(-M) var(string))(
As with the tt(-R) option, the var(string) will be displayed below the
command line; unlike the tt(-R) option, the string will not be put into
the status line but will instead be printed normally below the
prompt. This means that the var(string) will still be displayed after
the widget returns (until it is overwritten by subsequent commands).
)
item(tt(-U) var(string))(
This pushes the characters in the var(string) onto the input stack of
ZLE. After the widget currently executed finishes ZLE will behave as
if the characters in the var(string) were typed by the user.
As ZLE uses a stack, if this option is used repeatedly
the last string pushed onto the stack will be processed first. However,
the characters in each var(string) will be processed in the order in which
they appear in the string.
)
item(tt(-I))(
Unusually, this option is only useful em(outside) ordinary widget functions.
It invalidates the current zle display in preparation for output; usually
this will be from a trap function. It has no effect if zle is not
active. When a trap exits, the shell checks to see if the display needs
restoring, hence the following will print output in such a way as not to
disturb the line being edited:
example(TRAPUSR1() {
# Invalidate zle display
zle -I
# Show output
print Hello
})
Note that there are better ways of manipulating the display from within zle
widgets. In general, the trap function may need to test whether zle is
loaded before using this method; if it is not, there is no point in loading
it specially since the line editor will not be active.
The status is zero if zle was active, else one.
)
item(var(widget) tt([ -n) var(num) tt(]) tt([ -N ]) var(args) ...)(
Invoke the specified widget. This can only be done when ZLE is
active; normally this will be within a user-defined widget.
With the options tt(-n) and tt(-N), the current numerical argument will be
saved and then restored after the call to tt(widget); `tt(-n) var(num)'
sets the numerical argument temporarily to var(num), while `tt(-N)' sets it
to the default, i.e. as if there were none.
Any further arguments will be passed to the widget. If it is a shell
function, these are passed down as positional parameters; for builtin
widgets it is up to the widget in question what it does with them.
Currently arguments are only handled by the incremental-search commands,
the tt(history-search-forward) and tt(-backward) and the corresponding
functions prefixed by tt(vi-), and by tt(universal-argument). No error is
flagged if the command does not use the arguments, or only uses some of
them.
The return status reflects the success or failure of the operation carried
out by the widget, or if it is a user-defined widget the return status of
the shell function.
A non-zero return status causes the shell to beep when the widget exits,
unless the tt(BEEP) options was unset or the widget was called via the
tt(zle) command. Thus if a user defined widget requires an immediate beep,
it should call the tt(beep) widget directly.
)
enditem()
With no options and no arguments, only the return status will be
set. It is zero if ZLE is currently active and widgets could be
invoked using this builtin command and non-zero if ZLE is not active.
)
enditem()
texinode(Zle Widgets)()(Zle Builtins)(Zsh Line Editor)
sect(Widgets)
cindex(widgets)
All actions in the editor are performed by `widgets'. A widget's job is
@ -103,8 +478,10 @@ cindex(widgets, user-defined)
User-defined widgets, being implemented as shell functions,
can execute any normal shell command. They can also run other widgets
(whether built-in or user-defined) using the tt(zle) builtin command.
They can use tt(read -k) or tt(read -q) to read characters from standard
input. Finally, they can examine and edit the ZLE buffer being edited by
The standard input of the function is closed to prevent external commands
from unintentionally blocking ZLE by reading from the terminal, but
tt(read -k) or tt(read -q) can be used to read characters. Finally,
they can examine and edit the ZLE buffer being edited by
reading and setting the special parameters described below.
cindex(parameters, editor)
@ -125,6 +502,12 @@ The entire contents of the edit buffer. If it is written to, the
cursor remains at the same offset, unless that would put it outside the
buffer.
)
vindex(BUFFERLINES)
item(tt(BUFFERLINES))(
The number of screen lines needed for the edit buffer currently
displayed on screen (i.e. without any changes to the preceding
parameters done after the last redisplay).
)
vindex(CURSOR)
item(tt(CURSOR) (integer))(
The offset of the cursor, within the edit buffer. This is in the range
@ -132,9 +515,17 @@ The offset of the cursor, within the edit buffer. This is in the range
Attempts to move the cursor outside the buffer will result in the
cursor being moved to the appropriate end of the buffer.
)
vindex(MARK)
item(tt(MARK) (integer))(
Like tt(CURSOR), but for the mark.
vindex(HISTNO)
item(tt(HISTNO) (integer))(
The current history number.
)
vindex(KEYS)
item(tt(KEYS) (scalar))(
The keys typed to invoke this widget, as a literal string.
)
vindex(LASTWIDGET)
item(tt(LASTWIDGET) (scalar))(
The name of the last widget that was executed.
)
vindex(LBUFFER)
item(tt(LBUFFER) (scalar))(
@ -142,35 +533,9 @@ The part of the buffer that lies to the left of the cursor position.
If it is assigned to, only that part of the buffer is replaced, and the
cursor remains between the new tt($LBUFFER) and the old tt($RBUFFER).
)
vindex(RBUFFER)
item(tt(RBUFFER) (scalar))(
The part of the buffer that lies to the right of the cursor position.
If it is assigned to, only that part of the buffer is replaced, and the
cursor remains between the old tt($LBUFFER) and the new tt($RBUFFER).
)
vindex(BUFFERLINES)
item(tt(BUFFERLINES))(
The number of screen lines needed for the edit buffer currently
displayed on screen (i.e. without any changes to the preceding
parameters done after the last redisplay).
)
vindex(PREBUFFER)
item(tt(PREBUFFER) (scalar))(
In a multi-line input at the secondary prompt, this read-only parameter
contains the contents of the lines before the one the cursor is
currently in.
)
vindex(WIDGET)
item(tt(WIDGET) (scalar))(
The name of the widget currently being executed.
)
vindex(LASTWIDGET)
item(tt(LASTWIDGET) (scalar))(
The name of the last widget that was executed.
)
vindex(KEYS)
item(tt(KEYS) (scalar))(
The keys typed to invoke this widget, as a literal string.
vindex(MARK)
item(tt(MARK) (integer))(
Like tt(CURSOR), but for the mark.
)
vindex(NUMERIC)
item(tt(NUMERIC) (integer))(
@ -180,9 +545,28 @@ called with the tt(zle) builtin command will use the value
assigned. If it is unset inside a widget function, builtin widgets
called behave as if no numeric argument was given.
)
vindex(HISTNO)
item(tt(HISTNO) (integer))(
The current history number.
vindex(PENDING)
item(tt(PENDING) (integer))(
The number of bytes pending for input, i.e. the number of bytes which have
already been typed and can immediately be read. On systems where the shell
is not able to get this information, this parameter will always have a
value of zero.
)
vindex(PREBUFFER)
item(tt(PREBUFFER) (scalar))(
In a multi-line input at the secondary prompt, this read-only parameter
contains the contents of the lines before the one the cursor is
currently in.
)
vindex(RBUFFER)
item(tt(RBUFFER) (scalar))(
The part of the buffer that lies to the right of the cursor position.
If it is assigned to, only that part of the buffer is replaced, and the
cursor remains between the old tt($LBUFFER) and the new tt($RBUFFER).
)
vindex(WIDGET)
item(tt(WIDGET) (scalar))(
The name of the widget currently being executed.
)
enditem()
sect(Standard Widgets)
@ -191,6 +575,16 @@ The following is a list of all the standard widgets,
and their default bindings in emacs mode,
vi command mode and vi insert mode
(the `tt(emacs)', `tt(vicmd)' and `tt(viins)' keymaps, respectively).
Note that cursor keys are bound to movement keys in all three keymaps;
the shell assumes that the cursor keys send the key sequences reported
by the terminal-handling library (termcap or terminfo). The key sequences
shown in the list are those based on the VT100, common on many modern
terminals, but in fact these are not necessarily bound. In the case of the
tt(viins) keymap, the initial escape character of the sequences serves also
to return to the tt(vicmd) keymap: whether this happens is determined by
the tt(KEYTIMEOUT) parameter, see ifzman(zmanref(zshparam))\
ifnzman(noderef(Parameters)).
startmenu()
menu(Movement)
menu(History Control)
@ -199,7 +593,7 @@ menu(Arguments)
menu(Completion)
menu(Miscellaneous)
endmenu()
texinode(Movement)(History Control)()(Zsh Line Editor)
texinode(Movement)(History Control)()(Zle Widgets)
subsect(Movement)
startitem()
tindex(vi-backward-blank-word)
@ -212,7 +606,7 @@ item(tt(backward-char) (^B ESC-[D) (unbound) (unbound))(
Move backward one character.
)
tindex(vi-backward-char)
item(tt(vi-backward-char) (unbound) (^H h ^?) (unbound))(
item(tt(vi-backward-char) (unbound) (^H h ^?) (ESC-[D))(
Move backward one character, without changing lines.
)
tindex(backward-word)
@ -263,7 +657,7 @@ item(tt(forward-char) (^F ESC-[C) (unbound) (unbound))(
Move forward one character.
)
tindex(vi-forward-char)
item(tt(vi-forward-char) (unbound) (space l) (unbound))(
item(tt(vi-forward-char) (unbound) (space l) (ESC-[C))(
Move forward one character.
)
tindex(vi-find-next-char)
@ -329,7 +723,7 @@ item(tt(vi-rev-repeat-find) (unbound) (,) (unbound))(
Repeat the last tt(vi-find) command in the opposite direction.
)
enditem()
texinode(History Control)(Modifying Text)(Movement)(Zsh Line Editor)
texinode(History Control)(Modifying Text)(Movement)(Zle Widgets)
subsect(History Control)
startitem()
tindex(beginning-of-buffer-or-history)
@ -347,7 +741,7 @@ item(tt(beginning-of-history))(
Move to the first event in the history list.
)
tindex(down-line-or-history)
item(tt(down-line-or-history) (^N ESC-[B) (j) (unbound))(
item(tt(down-line-or-history) (^N ESC-[B) (j) (ESC-[B))(
Move down a line in the buffer, or if already at the bottom line,
move to the next event in the history list.
)
@ -536,7 +930,7 @@ item(tt(vi-rev-repeat-search) (unbound) (N) (unbound))(
Repeat the last vi history search, but in reverse.
)
tindex(up-line-or-history)
item(tt(up-line-or-history) (^P ESC-[A) (k) (unbound))(
item(tt(up-line-or-history) (^P ESC-[A) (k) (ESC-[A))(
Move up a line in the buffer, or if already at the top line,
move to the previous event in the history list.
)
@ -567,7 +961,7 @@ line up to the cursor.
This leaves the cursor in its original position.
)
enditem()
texinode(Modifying Text)(Arguments)(History Control)(Zsh Line Editor)
texinode(Modifying Text)(Arguments)(History Control)(Zle Widgets)
subsect(Modifying Text)
startitem()
tindex(vi-add-eol)
@ -630,7 +1024,13 @@ Copy the area from the cursor to the mark to the kill buffer.
)
tindex(copy-prev-word)
item(tt(copy-prev-word) (ESC-^_) (unbound) (unbound))(
Duplicate the word behind the cursor.
Duplicate the word to the left of the cursor.
)
tindex(copy-prev-shell-word)
item(tt(copy-prev-shell-word) (ESC-^_) (unbound) (unbound))(
Like tt(copy-prev-word), but the word is found by using shell parsing,
whereas tt(copy-prev-word) looks for blanks. This makes a difference
when the word is quoted and contains spaces.
)
tindex(vi-delete)
item(tt(vi-delete) (unbound) (d) (unbound))(
@ -845,7 +1245,7 @@ into the kill buffer.
Arguably, this is what Y should do in vi, but it isn't what it actually does.
)
enditem()
texinode(Arguments)(Completion)(Modifying Text)(Zsh Line Editor)
texinode(Arguments)(Completion)(Modifying Text)(Zle Widgets)
subsect(Arguments)
startitem()
tindex(digit-argument)
@ -876,7 +1276,7 @@ universal-argument) var(num)', the numerical argument will be set to
var(num); this is equivalent to `tt(NUMERIC=)var(num)'.
)
enditem()
texinode(Completion)(Miscellaneous)(Arguments)(Zsh Line Editor)
texinode(Completion)(Miscellaneous)(Arguments)(Zle Widgets)
subsect(Completion)
startitem()
tindex(accept-and-menu-complete)
@ -951,7 +1351,7 @@ When a previous completion displayed a list below the prompt, this
widget can be used to move the prompt below the list.
)
enditem()
texinode(Miscellaneous)()(Completion)(Zsh Line Editor)
texinode(Miscellaneous)()(Completion)(Zle Widgets)
subsect(Miscellaneous)
startitem()
tindex(accept-and-hold)
@ -1099,7 +1499,7 @@ tindex(run-help)
item(tt(run-help) (ESC-H ESC-h) (unbound) (unbound))(
Push the buffer onto the buffer stack, and execute the
command `tt(run-help) var(cmd)', where var(cmd) is the current
command. tt(run-help) is normally aliased to var(man).
command. tt(run-help) is normally aliased to tt(man).
)
tindex(vi-set-buffer)
item(tt(vi-set-buffer) (unbound) (") (unbound))(