aboutsummaryrefslogtreecommitdiff
path: root/Doc/Zsh/compctl.yo
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/Zsh/compctl.yo')
-rw-r--r--Doc/Zsh/compctl.yo110
1 files changed, 45 insertions, 65 deletions
diff --git a/Doc/Zsh/compctl.yo b/Doc/Zsh/compctl.yo
index 4fecce92f..48c7bf629 100644
--- a/Doc/Zsh/compctl.yo
+++ b/Doc/Zsh/compctl.yo
@@ -1,5 +1,5 @@
-texinode(Programmable Completion)(Completion Widgets)(Zsh Line Editor)(Top)
-chapter(Programmable Completion)
+texinode(Programmable Completion Using compctl)(Completion Widgets)(Zsh Line Editor)(Top)
+chapter(Programmable Completion Using compctl)
cindex(completion, programmable)
cindex(completion, controlling)
findex(compctl)
@@ -33,7 +33,7 @@ menu(Matching Control)
menu(Example)
endmenu()
-texinode(Command Flags)(Option Flags)()(Programmable Completion)
+texinode(Command Flags)(Option Flags)()(Programmable Completion Using compctl)
sect(Command Flags)
Completion of the arguments of a command may be different for each
command or may use the default. The behavior when completing the
@@ -56,7 +56,7 @@ from immediate expansion; for example the command string tt('foo*')
arranges for completion of the words of any command beginning with
tt(foo). When completion is attempted, all pattern completions are
tried in the reverse order of their definition until one matches. By
-default, completion then procedes as normal, i.e. the shell will try to
+default, completion then proceeds as normal, i.e. the shell will try to
generate more matches for the specific command on the command line; this
can be overridden by including tt(-tn) in the flags for the pattern
completion.
@@ -88,9 +88,7 @@ the standard behavior for all commands. For example, if your access
to the user database is too slow and/or it contains too many users (so
that completion after `tt(~)' is too slow to be usable), you can use
-indent(
-tt(compctl -T -x 's[~] C[0,[^/]#]' -k friends -S/ -tn)
-)
+example(compctl -T -x 's[~] C[0,[^/]#]' -k friends -S/ -tn)
to complete the strings in the array tt(friends) after a `tt(~)'.
The tt(C[...]) argument is necessary so that this form of ~-completion is
@@ -118,7 +116,7 @@ options specified by the tt(-D) flag.
The form with tt(-M) as the first and only option defines global
matching specifications, as described below in noderef(Matching Control).
-texinode(Option Flags)(Alternative Completion)(Command Flags)(Programmable Completion)
+texinode(Option Flags)(Alternative Completion)(Command Flags)(Programmable Completion Using compctl)
sect(Option Flags)
startlist()
list([ tt(-fcFBdeaRGovNAIOPZEnbjrzu/) ])
@@ -256,10 +254,8 @@ of space- or comma-separated values in parentheses, in which any
delimiter may be escaped with a backslash; in this case the argument
should be quoted. For example,
-indent(
-nofill(tt(compctl -k "(cputime filesize datasize stacksize
- coredumpsize resident descriptors)" limit))
-)
+example(compctl -k "(cputime filesize datasize stacksize
+ coredumpsize resident descriptors)" limit)
)
item(tt(-g) var(globstring))(
The var(globstring) is expanded using filename globbing; it should be
@@ -281,7 +277,7 @@ resulting files. Note that tt(-g) is faster for filenames.
)
item(tt(-K) var(function))(
Call the given function to get the completions. Unless the name
-starts with an underscode, the function is
+starts with an underscore, the function is
passed two arguments: the prefix and the suffix of the word on which
completion is to be attempted, in other words those characters before
the cursor position, and those from the cursor position onwards. The
@@ -293,10 +289,8 @@ should not be made local to the function. From such a function the
command line can be accessed with the tt(-c) and tt(-l) flags to
the tt(read) builtin. For example,
-indent(
-nofill(tt(function whoson { reply=(`users`); }
-compctl -K whoson talk))
-)
+example(function whoson { reply=(`users`); }
+compctl -K whoson talk)
completes only logged-on users after `tt(talk)'. Note that `tt(whoson)' must
return an array, so `tt(reply=`users`)' would be incorrect.
@@ -315,9 +309,7 @@ zero or negative the whole history is searched and if var(pattern) is
the empty string all words are taken (as with `tt(*)'). A typical
use is
-indent(
-tt(compctl -D -f PLUS() -H 0 '')
-)
+example(compctl -D -f PLUS() -H 0 '')
which forces completion to look back in the history list for a word if
no filename matches.
@@ -345,9 +337,7 @@ The var(prefix) is inserted just before the completed string; any
initial part already typed will be completed and the whole var(prefix)
ignored for completion purposes. For example,
-indent(
-tt(compctl -j -P "%" kill)
-)
+example(compctl -j -P "%" kill)
inserts a `%' after the kill command and then completes job names.
)
@@ -362,9 +352,7 @@ With directory var(file-prefix): for command, file, directory and
globbing completion (options tt(-c), tt(-f), tt(-/), tt(-g)), the file
prefix is implicitly added in front of the completion. For example,
-indent(
-tt(compctl -/ -W ~/Mail maildirs)
-)
+example(compctl -/ -W ~/Mail maildirs)
completes any subdirectories to any depth beneath the directory
tt(~/Mail), although that prefix does not appear on the command line.
@@ -393,9 +381,7 @@ option. If the var(cmd) string is empty the first word in the range
is instead taken as the command name, and command name completion
performed on the first word in the range. For example,
-indent(
-tt(compctl -x 'r[-exec,;]' -l '' -- find)
-)
+example(compctl -x 'r[-exec,;]' -l '' -- find)
completes arguments between `tt(-exec)' and the following `tt(;)' (or the end
of the command line if there is no such string) as if they were
@@ -419,7 +405,7 @@ tt(-K) option) which can examine the word components passed to it
use its own criteria to decide what matches. If there is no
completion, the original word is retained. Since the produced
possible completions seldom seldom have interesting common prefixes
-and suffixes, menucompletion is started immediatly if tt(AUTO_MENU) is
+and suffixes, menucompletion is started immediately if tt(AUTO_MENU) is
set and this flag is used.
)
item(tt(-y) var(func-or-var))(
@@ -499,9 +485,7 @@ group name are stored in that group.
This can be useful with non-exclusive alternative completions. For
example, in
-indent(
-tt(compctl -f -J files -t+ + -v -J variables foo)
-)
+example(compctl -f -J files -t+ + -v -J variables foo)
both files and variables are possible completions, as the tt(-t+) forces
both sets of alternatives before and after the tt(+) to be considered at
@@ -521,7 +505,7 @@ of the var(match-spec) string is described below in noderef(Matching Control).
)
enditem()
-texinode(Alternative Completion)(Extended Completion)(Option Flags)(Programmable Completion)
+texinode(Alternative Completion)(Extended Completion)(Option Flags)(Programmable Completion Using compctl)
sect(Alternative Completion)
startlist()
list(tt(compctl) [ tt(-CDT) ] var(options) tt(PLUS()) var(options) [ tt(PLUS()) ... ] \
@@ -536,7 +520,7 @@ up to that point, default completion is tried.
If the list of flags contains a tt(-t) with a tt(PLUS()) character, the next
list of flags is used even if the current list produced matches.
-texinode(Extended Completion)(Matching Control)(Alternative Completion)(Programmable Completion)
+texinode(Extended Completion)(Matching Control)(Alternative Completion)(Programmable Completion Using compctl)
sect(Extended Completion)
startlist()
list(nofill(tt(compctl) [ tt(-CDT) ] var(options) \
@@ -612,9 +596,7 @@ considered part of the completion, but the rest will. var(index) may
be negative to count from the end: in most cases, var(index) will be
1 or -1. For example,
-indent(
-tt(compctl -s '`users`' -x 'n[1,@]' -k hosts -- talk)
-)
+example(compctl -s '`users`' -x 'n[1,@]' -k hosts -- talk)
will usually complete usernames, but if you insert an tt(@) after the
name, names from the array var(hosts) (assumed to contain hostnames,
@@ -648,7 +630,7 @@ completion is done in backticks and var(str) starts with a `b'.
)
enditem()
-texinode(Matching Control)(Example)(Extended Completion)(Programmable Completion)
+texinode(Matching Control)(Example)(Extended Completion)(Programmable Completion Using compctl)
sect(Matching Control)
It is possible by use of the tt(-M) var(spec) flag to specify how the
@@ -732,10 +714,10 @@ following alters the matching rules so that the prefix tt(no) and any
underscore are ignored when trying to match the trial completions
generated and uppercase letters on the line match the corresponding
lowercase letters in the words:
-indent(
-nofill(tt(compctl -M 'L:|[nN][oO]= M:_= M:{A-Z}={a-z}' \
- -o setopt unsetopt))
-)
+
+example(compctl -M 'L:|[nN][oO]= M:_= M:{A-Z}={a-z}' \
+ -o setopt unsetopt)
+
The first part says that the pattern `tt([nN][oO])' at the beginning
(the empty anchor before the pipe symbol) of the string on the
line matches the empty string in the list of words generated by
@@ -752,14 +734,13 @@ The second example makes completion case insensitive. By using
tt(compctl) with the tt(-M) option alone this applies to every
completion. This is just the same as in the tt(setopt) example, except
here we wish to retain the characters in the list of completions:
-indent(
-tt(compctl -M 'm:{a-z}={A-Z}')
-)
+
+example(compctl -M 'm:{a-z}={A-Z}')
+
This makes lowercase letters match their uppercase counterparts.
To make uppercase letters match the lowercase forms as well:
-indent(
-tt(compctl -M 'm:{a-zA-Z}={A-Za-z}')
-)
+
+example(compctl -M 'm:{a-zA-Z}={A-Za-z}')
A nice example for the use of tt(*) patterns is partial word
completion. Sometimes you would like to make strings like tt(c.s.u)
@@ -770,10 +751,10 @@ however, that the case where each part of the word, i.e. tt(comp),
tt(source) and tt(unix) in this example, is to be completed separately
is a different problem to be solved by extended completion. The
example can be handled by:
-indent(
-nofill(tt(compctl -M 'r:|.=* r:|=*' \
- -k '(comp.sources.unix comp.sources.misc ...)' ngroups))
-)
+
+example(compctl -M 'r:|.=* r:|=*' \
+ -k '(comp.sources.unix comp.sources.misc ...)' ngroups)
+
The first specification says that tt(lpat) is the empty string, while
tt(anchor) is a dot; tt(tpat) is tt(*), so this can match anything
except for the `tt(.)' from the anchor in
@@ -795,9 +776,9 @@ empty string at the end of the string on the line matches any characters
at the end of the trial completion.
More generally, the specification
-indent(
-tt(compctl -M 'r:|[.,_-]=* r:|=*')
-)
+
+example(compctl -M 'r:|[.,_-]=* r:|=*')
+
allows one to complete words with abbreviations before any of the
characters in the square brackets in any completion. For example, to
complete tt(veryverylongfile.c) rather than tt(veryverylongheader.h)
@@ -817,9 +798,9 @@ the string on the command line as a substring, not just at the
beginning. Since this might produce more matches than we want,
we arrange for it to be tried only if the matchers described above don't
produce any matches:
-indent(
-tt(compctl -M 'r:|[.,_-]=* r:|=*' 'l:|=* r:|=*')
-)
+
+example(compctl -M 'r:|[.,_-]=* r:|=*' 'l:|=* r:|=*')
+
Here, if the string on the command line is tt(foo.bar), tt(compctl)
first tries matching tt(foo)var(anything)tt(.bar)var(anything), as
with the previous example. If that fails, the two descriptions in the
@@ -828,13 +809,12 @@ and end of the string on the command line can match any set of
characters at the beginning or end of the trial completion, so it will
look for var(anything)tt(foo.bar)var(anything).
-texinode(Example)()(Matching Control)(Programmable Completion)
+texinode(Example)()(Matching Control)(Programmable Completion Using compctl)
sect(Example)
-indent(
-nofill(
-tt(compctl -u -x 's[tt(PLUS())] c[-1,-f],s[-f+PLUS()]' \
- -g '~/Mail/*(:t)' - 's[-f],c[-1,-f]' -f -- mail))
-)
+
+example(compctl -u -x 's[tt(PLUS())] c[-1,-f],s[-f+PLUS()]' \
+ -g '~/Mail/*(:t)' - 's[-f],c[-1,-f]' -f -- mail)
+
This is to be interpreted as follows:
If the current command is tt(mail), then