GNU Info
(zsh.info)Builtin Commands
Builtin Commands
================
compadd [ -akqQfenUl12C ] [ -F ARRAY ]
[ -P PREFIX ] [ -S SUFFIX ]
[ -p HIDDEN-PREFIX ] [ -s HIDDEN-SUFFIX ]
[ -i IGNORED-PREFIX ] [ -I IGNORED-SUFFIX ]
[ -W FILE-PREFIX ] [ -d ARRAY ]
[ -J NAME ] [ -V NAME ] [ -X EXPLANATION ] [ -x MESSAGE ]
[ -r REMOVE-CHARS ] [ -R REMOVE-FUNC ]
[ -D ARRAY ] [ -O ARRAY ] [ -A ARRAY ]
[ -M MATCH-SPEC ] [ - ] [ WORDS ... ]
This builtin command can be used to add matches directly and
control all the information the completion code stores with each
possible match. The return value is zero if at least one match was
added and non-zero if no matches were added.
The completion code breaks the string to complete into seven
fields in the order:
<IPRE><APRE><HPRE><WORD><HSUF><ASUF><ISUF>
The first field is an ignored prefix taken from the command line,
the contents of the IPREFIX parameter plus the string given with
the -i option. With the -U option, only the string from the -i
option is used. The field <APRE> is an optional prefix string
given with the -P option. The <HPRE> field is a string that is
considered part of the match but that should not be shown when
listing completions, given with the -p option; for example,
functions that do filename generation might specify a common path
prefix this way. <WORD> is the part of the match that should
appear in the list of completions, i.e. one of the WORDS given at
the end of the compadd command line. The suffixes <HSUF>, <ASUF>
and <ISUF> correspond to the prefixes <HPRE>, <APRE> and <IPRE>
and are given by the options -s, -S and -I, respectively.
The supported flags are:
-P PREFIX
This gives a string to be inserted before the given WORDS.
The string given is not considered as part of the match and
any shell metacharacters in it will not be quoted when the
string is inserted.
-S SUFFIX
Like -P, but gives a string to be inserted after the match.
-p HIDDEN-PREFIX
This gives a string that should be inserted into the command
line before the match but that should not appear in the list
of matches. Unless the -U option is given, this string must
be matched as part of the string on the command line.
-s HIDDEN-SUFFIX
Like `-p', but gives a string to insert after the match.
-i IGNORED-PREFIX
This gives a string to insert into the command line just
before any string given with the `-P' option. Without `-P'
the string is inserted before the string given with `-p' or
directly before the match.
-I IGNORED-SUFFIX
Like -i, but gives an ignored suffix.
-a
With this flag the WORDS are taken as names of arrays and the
possible matches are their values. If only some elements of
the arrays are needed, the WORDS may also contain subscripts,
as in `foo[2,-1]'.
-k
With this flag the WORDS are taken as names of associative
arrays and the possible matches are their keys. As for -a,
the WORDS may also contain subscripts, as in `foo[(R)*bar*]'.
-d ARRAY
This adds per-match display strings. The ARRAY should contain
one element per WORD given. The completion code will then
display the first element instead of the first WORD, and so
on. The ARRAY may be given as the name of an array parameter
or directly as a space-separated list of words in parentheses.
If there are fewer display strings than WORDS, the leftover
WORDS will be displayed unchanged and if there are more
display strings than WORDS, the leftover display strings will
be silently ignored.
-l
This option only has an effect if used together with the -d
option. If it is given, the display strings are listed one
per line, not arrayed in columns.
-J NAME
Gives the name of the group of matches the words should be
stored in.
-V NAME
Like -J but naming a unsorted group. These are in a different
name space than groups created with the -J flag.
-1
If given together with the -V option, makes only consecutive
duplicates in the group be removed. If combined with the -J
option, this has no visible effect. Note that groups with and
without this flag are in different name spaces.
-2
If given together with the -J or -V option, makes all
duplicates be kept. Again, groups with and without this flag
are in different name spaces.
-X EXPLANATION
The EXPLANATION string will be printed with the list of
matches, above the group currently selected.
-x MESSAGE
Like -X, but the MESSAGE will be printed even if there are no
matches in the group.
-q
The suffix given with -S will be automatically removed if the
next character typed is a blank or does not insert anything,
or if the suffix consists of only one character and the next
character typed is the same character.
-r REMOVE-CHARS
This is a more versatile form of the -q option. The suffix
given with -S or the slash automatically added after
completing directories will be automatically removed if the
next character typed inserts one of the characters given in
the REMOVE-CHARS. This string is parsed as a characters
class and understands the backslash sequences used by the
print command. For example, `-r "a-z\t"' removes the suffix
if the next character typed inserts a lowercase character or
a TAB, and `-r "^0-9"' removes the suffix if the next
character typed inserts anything but a digit. One extra
backslash sequence is understood in this string: `\-' stands
for all characters that insert nothing. Thus `-S "=" -q' is
the same as `-S "=" -r "= \t\n\-"'.
-R REMOVE-FUNC
This is another form of the -r option. When a suffix has been
inserted and the completion accepted, the function
REMOVE-FUNC will be called after the next character typed.
It is passed the length of the suffix as an argument and can
use the special parameters available in ordinary
(non-completion) zle widgets (see Note: Zsh Line Editor) to
analyse and modify the command line.
-f
If this flag is given, all of the matches built from WORDS are
marked as being the names of files. They are not required to
be actual filenames, but if they are, and the option
LIST_TYPES is set, the characters describing the types of the
files in the completion lists will be shown. This also forces
a slash to be added when the name of a directory is completed.
-e
This flag can be used to tell the completion code that the
matches added are parameter names for a parameter expansion.
This will make the AUTO_PARAM_SLASH and AUTO_PARAM_KEYS
options be used for the matches.
-W FILE-PREFIX
This string is a pathname that will be prepended to each of
the matches formed by the given WORDS together with any
prefix specified by the -p option to form a complete filename
for testing. Hence it is only useful if combined with the -f
flag, as the tests will not otherwise be performed.
-F ARRAY
Specifies an array containing patterns. Words matching one of
these patterns are ignored, i.e. not considered to be
possible matches.
The ARRAY may be the name of an array parameter or a list of
literal patterns enclosed in parentheses and quoted, as in
`-F "(*?.o *?.h)"'. If the name of an array is given, the
elements of the array are taken as the patterns.
-Q
This flag instructs the completion code not to quote any
metacharacters in the words when inserting them into the
command line.
-M MATCH-SPEC
This gives local match specifications as described below in
Note: Matching Control. This option may be given more than
once. In this case all MATCH-SPECs given are concatenated
with spaces between them to form the specification string to
use. Note that they will only be used if the -U option is
not given.
-n
Specifies that the words added are to be used as possible
matches, but are not to appear in the completion listing.
-U
If this flag is given, all words given will be accepted and
no matching will be done by the completion code. Normally
this is used in functions that do the matching themselves.
-O ARRAY
If this option is given, the WORDS are _not_ added to the set
of possible completions. Instead, matching is done as usual
and all of the WORDS given as arguments that match the string
on the command line will be stored in the array parameter
whose name is given as ARRAY.
-A ARRAY
As the -O option, except that instead of those of the WORDS
which match being stored in ARRAY, the strings generated
internally by the completion code are stored. For example,
with a matching specification of `-M "L:|no="', the string
`nof' on the command line and the string `foo' as one of the
WORDS, this option stores the string `nofoo' in the array,
whereas the -O option stores the `foo' originally given.
-D ARRAY
As with -O, the WORDS are not added to the set of possible
completions. Instead, the completion code tests whether each
WORD in turn matches what is on the line. If the N'th WORD
does not match, the N'th element of the ARRAY is removed.
Elements for which the corresponding WORD is matched are
retained.
-C
This option adds a special match which expands to all other
matches when inserted into the line, even those that are
added after this option is used. Together with the -d option
it is possible to specify a string that should be displayed
in the list for this special match. If no string is given,
it will be shown as a string containing the strings that
would be inserted for the other matches, truncated to the
width of the screen.
-
--
This flag ends the list of flags and options. All arguments
after it will be taken as the words to use as matches even if
they begin with hyphens.
Except for the -M flag, if any of these flags is given more than
once, the first one (and its argument) will be used.
compset -p NUMBER
compset -P [ NUMBER ] PATTERN
compset -s NUMBER
compset -S [ NUMBER ] PATTERN
compset -n BEGIN [ END ]
compset -N BEG-PAT [ END-PAT ]
compset -q
This command simplifies modification of the special parameters,
while its return value allows tests on them to be carried out.
The options are:
-p NUMBER
If the contents of the PREFIX parameter is longer than NUMBER
characters, the first NUMBER characters are removed from it
and appended to the contents of the IPREFIX parameter.
-P [ NUMBER ] PATTERN
If the value of the PREFIX parameter begins with anything that
matches the PATTERN, the matched portion is removed from
PREFIX and appended to IPREFIX.
Without the optional NUMBER, the longest match is taken, but
if NUMBER is given, anything up to the NUMBER'th match is
moved. If the NUMBER is negative, the NUMBER'th longest
match is moved. For example, if PREFIX contains the string
`a=b=c', then compset -P '*\=' will move the string `a=b='
into the IPREFIX parameter, but compset -P 1 '*\=' will move
only the string `a='.
-s NUMBER
As -p, but transfer the last NUMBER characters from the value
of SUFFIX to the front of the value of ISUFFIX.
-S [ NUMBER ] PATTERN
As -P, but match the last portion of SUFFIX and transfer the
matched portion to the front of the value of ISUFFIX.
-n BEGIN [ END ]
If the current word position as specified by the parameter
CURRENT is greater than or equal to BEGIN, anything up to the
BEGIN'th word is removed from the words array and the value
of the parameter CURRENT is decremented by BEGIN.
If the optional END is given, the modification is done only if
the current word position is also less than or equal to END.
In this case, the words from position END onwards are also
removed from the words array.
Both BEGIN and END may be negative to count backwards from
the last element of the words array.
-N BEG-PAT [ END-PAT ]
If one of the elements of the words array before the one at
the index given by the value of the parameter CURRENT matches
the pattern BEG-PAT, all elements up to and including the
matching one are removed from the words array and the value
of CURRENT is changed to point to the same word in the
changed array.
If the optional pattern END-PAT is also given, and there is an
element in the words array matching this pattern, the
parameters are modified only if the index of this word is
higher than the one given by the CURRENT parameter (so that
the matching word has to be after the cursor). In this case,
the words starting with the one matching end-pat are also
removed from the words array. If words contains no word
matching END-PAT, the testing and modification is performed
as if it were not given.
-q
The word currently being completed is split on spaces into
separate words, respecting the usual shell quoting
conventions. The resulting words are stored in the words
array, and CURRENT, PREFIX, SUFFIX, QIPREFIX, and QISUFFIX
are modified to reflect the word part that is completed.
In all the above cases the return value is zero if the test
succeeded and the parameters were modified and non-zero otherwise.
This allows one to use this builtin in tests such as:
if compset -P '*\='; then ...
This forces anything up to and including the last equal sign to be
ignored by the completion code.
compcall [ -TD ]
This allows the use of completions defined with the compctl builtin
from within completion widgets. The list of matches will be
generated as if one of the non-widget completion function
(complete-word, etc.) had been called, except that only compctls
given for specific commands are used. To force the code to try
completions defined with the -T option of compctl and/or the
default completion (whether defined by compctl -D or the builtin
default) in the appropriate places, the -T and/or -D flags can be
passed to compcall.
The return value can be used to test if a matching compctl
definition was found. It is non-zero if a compctl was found and
zero otherwise.
Note that this builtin is defined by the zsh/compctl module.
automatically generated by info2www version 1.2.2.9