"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "Doc/zsh.info-3" between
zsh-5.8.1-doc.tar.xz and zsh-5.9-doc.tar.xz

About: Zsh is a powerful UNIX command interpreter (shell). Documentation.

[ To the main zsh (doc) source changes report ]

zsh.info-3  (zsh-5.8.1-doc.tar.xz):zsh.info-3  (zsh-5.9-doc.tar.xz)
This is zsh.info, produced by makeinfo version 4.8 from ./zsh.texi. This is zsh.info, produced by makeinfo version 4.8 from ./zsh.texi.
INFO-DIR-SECTION Utilities INFO-DIR-SECTION Utilities
START-INFO-DIR-ENTRY START-INFO-DIR-ENTRY
* ZSH: (zsh). The Z Shell Manual. * ZSH: (zsh). The Z Shell Manual.
END-INFO-DIR-ENTRY END-INFO-DIR-ENTRY
 
File: zsh.info, Node: History Control, Next: Modifying Text, Prev: Movement, Up: Zle Widgets File: zsh.info, Node: History Control, Next: Modifying Text, Prev: Movement, Up: Standard Widgets
18.6.2 History Control 18.6.2 History Control
---------------------- ----------------------
beginning-of-buffer-or-history (ESC-<) (gg) (unbound) beginning-of-buffer-or-history (ESC-<) (gg) (unbound)
Move to the beginning of the buffer, or if already there, move to Move to the beginning of the buffer, or if already there, move to
the first event in the history list. the first event in the history list.
beginning-of-line-hist beginning-of-line-hist
Move to the beginning of the line. If already at the beginning of Move to the beginning of the line. If already at the beginning of
skipping to change at line 322 skipping to change at line 322
line up to the cursor. This leaves the cursor in its original line up to the cursor. This leaves the cursor in its original
position. position.
set-local-history set-local-history
By default, history movement commands visit the imported lines as By default, history movement commands visit the imported lines as
well as the local lines. This widget lets you toggle this on and well as the local lines. This widget lets you toggle this on and
off, or set it with the numeric argument. Zero for both local and off, or set it with the numeric argument. Zero for both local and
imported lines and nonzero for only local lines. imported lines and nonzero for only local lines.
 
File: zsh.info, Node: Modifying Text, Next: Arguments, Prev: History Control, Up: Zle Widgets File: zsh.info, Node: Modifying Text, Next: Arguments, Prev: History Control, Up: Standard Widgets
18.6.3 Modifying Text 18.6.3 Modifying Text
--------------------- ---------------------
vi-add-eol (unbound) (A) (unbound) vi-add-eol (unbound) (A) (unbound)
Move to the end of the line and enter insert mode. Move to the end of the line and enter insert mode.
vi-add-next (unbound) (a) (unbound) vi-add-next (unbound) (a) (unbound)
Enter insert mode after the current cursor position, without Enter insert mode after the current cursor position, without
changing lines. changing lines.
skipping to change at line 585 skipping to change at line 585
vi-yank-whole-line (unbound) (Y) (unbound) vi-yank-whole-line (unbound) (Y) (unbound)
Copy the current line into the kill buffer. Copy the current line into the kill buffer.
vi-yank-eol vi-yank-eol
Copy the region from the cursor position to the end of the line Copy the region from the cursor position to the end of the line
into the kill buffer. Arguably, this is what Y should do in vi, into the kill buffer. Arguably, this is what Y should do in vi,
but it isn't what it actually does. but it isn't what it actually does.
 
File: zsh.info, Node: Arguments, Next: Completion, Prev: Modifying Text, Up: Zle Widgets File: zsh.info, Node: Arguments, Next: Completion, Prev: Modifying Text, Up: Standard Widgets
18.6.4 Arguments 18.6.4 Arguments
---------------- ----------------
digit-argument (ESC-0..ESC-9) (1-9) (unbound) digit-argument (ESC-0..ESC-9) (1-9) (unbound)
Start a new numeric argument, or add to the current one. See also Start a new numeric argument, or add to the current one. See also
vi-digit-or-beginning-of-line. This only works if bound to a key vi-digit-or-beginning-of-line. This only works if bound to a key
sequence ending in a decimal digit. sequence ending in a decimal digit.
Inside a widget function, a call to this function treats the last Inside a widget function, a call to this function treats the last
skipping to change at line 633 skipping to change at line 633
The function can be used with a command argument inside a The function can be used with a command argument inside a
user-defined widget. The following code sets the base to 16 and user-defined widget. The following code sets the base to 16 and
lets the user input a hexadecimal argument until a key out of the lets the user input a hexadecimal argument until a key out of the
digit range is typed: digit range is typed:
zle argument-base 16 zle argument-base 16
zle universal-argument zle universal-argument
 
File: zsh.info, Node: Completion, Next: Miscellaneous, Prev: Arguments, Up: Zle Widgets File: zsh.info, Node: Completion, Next: Miscellaneous, Prev: Arguments, Up: Standard Widgets
18.6.5 Completion 18.6.5 Completion
----------------- -----------------
accept-and-menu-complete accept-and-menu-complete
In a menu completion, insert the current completion into the In a menu completion, insert the current completion into the
buffer, and advance to the next possible completion. buffer, and advance to the next possible completion.
complete-word complete-word
Attempt completion on the current word. Attempt completion on the current word.
skipping to change at line 692 skipping to change at line 692
reverse-menu-complete reverse-menu-complete
Perform menu completion, like menu-complete, except that if a menu Perform menu completion, like menu-complete, except that if a menu
completion is already in progress, move to the _previous_ completion is already in progress, move to the _previous_
completion rather than the next. completion rather than the next.
end-of-list end-of-list
When a previous completion displayed a list below the prompt, this When a previous completion displayed a list below the prompt, this
widget can be used to move the prompt below the list. widget can be used to move the prompt below the list.
 
File: zsh.info, Node: Miscellaneous, Next: Text Objects, Prev: Completion, U p: Zle Widgets File: zsh.info, Node: Miscellaneous, Next: Text Objects, Prev: Completion, U p: Standard Widgets
18.6.6 Miscellaneous 18.6.6 Miscellaneous
-------------------- --------------------
accept-and-hold (ESC-A ESC-a) (unbound) (unbound) accept-and-hold (ESC-A ESC-a) (unbound) (unbound)
Push the contents of the buffer on the buffer stack and execute it. Push the contents of the buffer on the buffer stack and execute it.
accept-and-infer-next-history accept-and-infer-next-history
Execute the contents of the buffer. Then search the history list Execute the contents of the buffer. Then search the history list
for a line matching the current one and push the event following for a line matching the current one and push the event following
skipping to change at line 734 skipping to change at line 734
word on the command line, force it to be preserved. Otherwise do word on the command line, force it to be preserved. Otherwise do
nothing. Retaining the suffix ends any active menu completion or nothing. Retaining the suffix ends any active menu completion or
menu selection. menu selection.
This widget is intended to be called from user-defined widgets to This widget is intended to be called from user-defined widgets to
enforce a desired suffix-preservation behavior. enforce a desired suffix-preservation behavior.
beep beep
Beep, unless the BEEP option is unset. Beep, unless the BEEP option is unset.
bracketed-paste bracketed-paste (^[[200~) (^[[200~) (^[[200~)
This widget is invoked when text is pasted to the terminal This widget is invoked when text is pasted to the terminal
emulator. It is not intended to be bound to actual keys but emulator. It is not intended to be bound to actual keys but
instead to the special sequence generated by the terminal emulator instead to the special sequence generated by the terminal emulator
when text is pasted. when text is pasted.
When invoked interactively, the pasted text is inserted to the When invoked interactively, the pasted text is inserted to the
buffer and placed in the cutbuffer. If a numeric argument is buffer and placed in the cutbuffer. If a numeric argument is
given, shell quoting will be applied to the pasted text before it given, shell quoting will be applied to the pasted text before it
is inserted. is inserted.
skipping to change at line 1035 skipping to change at line 1035
which-command (ESC-?) (unbound) (unbound) which-command (ESC-?) (unbound) (unbound)
Push the buffer onto the buffer stack, and execute the command Push the buffer onto the buffer stack, and execute the command
`which-command CMD'. where CMD is the current command. `which-command CMD'. where CMD is the current command.
which-command is normally aliased to whence. which-command is normally aliased to whence.
vi-digit-or-beginning-of-line (unbound) (0) (unbound) vi-digit-or-beginning-of-line (unbound) (0) (unbound)
If the last command executed was a digit as part of an argument, If the last command executed was a digit as part of an argument,
continue the argument. Otherwise, execute vi-beginning-of-line. continue the argument. Otherwise, execute vi-beginning-of-line.
 
File: zsh.info, Node: Text Objects, Prev: Miscellaneous, Up: Zle Widgets File: zsh.info, Node: Text Objects, Prev: Miscellaneous, Up: Standard Widgets
18.6.7 Text Objects 18.6.7 Text Objects
------------------- -------------------
Text objects are commands that can be used to select a block of text Text objects are commands that can be used to select a block of text
according to some criteria. They are a feature of the vim text editor according to some criteria. They are a feature of the vim text editor
and so are primarily intended for use with vi operators or from visual and so are primarily intended for use with vi operators or from visual
selection mode. However, they can also be used from vi-insert or emacs selection mode. However, they can also be used from vi-insert or emacs
mode. Key bindings listed below apply to the viopp and visual keymaps. mode. Key bindings listed below apply to the viopp and visual keymaps.
skipping to change at line 1075 skipping to change at line 1075
select-in-shell-word (ia) select-in-shell-word (ia)
Select the current command argument applying the normal rules for Select the current command argument applying the normal rules for
quoting. If the argument begins and ends with matching quote quoting. If the argument begins and ends with matching quote
characters, these are not included in the selection. characters, these are not included in the selection.
select-in-word (iw) select-in-word (iw)
Select a word, using the normal vi-style word definition. With a Select a word, using the normal vi-style word definition. With a
numeric argument, multiple words will be selected. numeric argument, multiple words will be selected.
 
File: zsh.info, Node: Character Highlighting, Prev: Zle Widgets, Up: Zsh Line Editor File: zsh.info, Node: Character Highlighting, Prev: Standard Widgets, Up: Zsh Line Editor
18.7 Character Highlighting 18.7 Character Highlighting
=========================== ===========================
The line editor has the ability to highlight characters or regions of The line editor has the ability to highlight characters or regions of
the line that have a particular significance. This is controlled by the line that have a particular significance. This is controlled by
the array parameter zle_highlight, if it has been set by the user. the array parameter zle_highlight, if it has been set by the user.
If the parameter contains the single entry none all highlighting is If the parameter contains the single entry none all highlighting is
turned off. Note the parameter is still expected to be an array. turned off. Note the parameter is still expected to be an array.
skipping to change at line 1314 skipping to change at line 1314
defines a widget named `complete'. The second argument is the name of defines a widget named `complete'. The second argument is the name of
any of the builtin widgets that handle completions: complete-word, any of the builtin widgets that handle completions: complete-word,
expand-or-complete, expand-or-complete-prefix, menu-complete, expand-or-complete, expand-or-complete-prefix, menu-complete,
menu-expand-or-complete, reverse-menu-complete, list-choices, or menu-expand-or-complete, reverse-menu-complete, list-choices, or
delete-char-or-list. Note that this will still work even if the widget delete-char-or-list. Note that this will still work even if the widget
in question has been re-bound. in question has been re-bound.
When this newly defined widget is bound to a key using the bindkey When this newly defined widget is bound to a key using the bindkey
builtin command defined in the zsh/zle module (*Note Zsh Line builtin command defined in the zsh/zle module (*Note Zsh Line
Editor::), typing that key will call the shell function `completer'. Editor::), typing that key will call the shell function `completer'.
This function is responsible for generating the possible matches using This function is responsible for generating completion matches using the
the builtins described below. As with other ZLE widgets, the function builtins described below. As with other ZLE widgets, the function is
is called with its standard input closed. called with its standard input closed.
Once the function returns, the completion code takes over control again Once the function returns, the completion code takes over control again
and treats the matches in the same manner as the specified builtin and treats the matches in the same manner as the specified builtin
widget, in this case expand-or-complete. widget, in this case expand-or-complete.
* Menu: * Menu:
* Completion Special Parameters:: * Completion Special Parameters::
* Completion Builtin Commands:: * Completion Builtin Commands::
* Completion Condition Codes:: * Completion Condition Codes::
skipping to change at line 1476 skipping to change at line 1476
and will be unset otherwise. and will be unset otherwise.
If it was set when at least one match equal to the string on If it was set when at least one match equal to the string on
the line was generated, the match is accepted. the line was generated, the match is accepted.
exact_string exact_string
The string of an exact match if one was found, otherwise The string of an exact match if one was found, otherwise
unset. unset.
ignored ignored
The number of words that were ignored because they matched The number of completions that were ignored because they
one of the patterns given with the -F option to the compadd matched one of the patterns given with the -F option to the
builtin command. compadd builtin command.
insert insert
This controls the manner in which a match is inserted into This controls the manner in which a match is inserted into
the command line. On entry to the widget function, if it is the command line. On entry to the widget function, if it is
unset the command line is not to be changed; if set to unset the command line is not to be changed; if set to
unambiguous, any prefix common to all matches is to be unambiguous, any prefix common to all matches is to be
inserted; if set to automenu-unambiguous, the common prefix inserted; if set to automenu-unambiguous, the common prefix
is to be inserted and the next invocation of the completion is to be inserted and the next invocation of the completion
code may start menu completion (due to the AUTO_MENU option code may start menu completion (due to the AUTO_MENU option
being set); if set to menu or automenu menu completion will being set); if set to menu or automenu menu completion will
skipping to change at line 1570 skipping to change at line 1570
number of lines to display you need to add the number of number of lines to display you need to add the number of
lines needed for the command line to this value, this is lines needed for the command line to this value, this is
available as the value of the BUFFERLINES special parameter. available as the value of the BUFFERLINES special parameter.
list_max list_max
Initially this is set to the value of the LISTMAX parameter. Initially this is set to the value of the LISTMAX parameter.
It may be set to any other value; when the widget exits this It may be set to any other value; when the widget exits this
value will be used in the same way as the value of LISTMAX. value will be used in the same way as the value of LISTMAX.
nmatches nmatches
The number of matches generated and accepted by the The number of matches added by the completion code so far.
completion code so far.
old_insert old_insert
On entry to the widget this will be set to the number of the On entry to the widget this will be set to the number of the
match of an old list of completions that is currently match of an old list of completions that is currently
inserted into the command line. If no match has been inserted into the command line. If no match has been
inserted, this is unset. inserted, this is unset.
As with old_list, the value of this key will only be used if As with old_list, the value of this key will only be used if
it is the string keep. If it was set to this value by the it is the string keep. If it was set to this value by the
widget and there was an old match inserted into the command widget and there was an old match inserted into the command
skipping to change at line 1607 skipping to change at line 1606
will continue to use this old list. If the widget generated will continue to use this old list. If the widget generated
new matches, they will not be used. new matches, they will not be used.
parameter parameter
The name of the parameter when completing in a subscript or The name of the parameter when completing in a subscript or
in the value of a parameter assignment. in the value of a parameter assignment.
pattern_insert pattern_insert
Normally this is set to menu, which specifies that menu Normally this is set to menu, which specifies that menu
completion will be used whenever a set of matches was completion will be used whenever a set of matches was
generated using pattern matching. If it is set to any other generated using pattern_match (see below). If it is set to
non-empty string by the user and menu completion is not any other non-empty string by the user and menu completion is
selected by other option settings, the code will instead not selected by other option settings, the code will instead
insert any common prefix for the generated matches as with insert any common prefix for the generated matches as with
normal completion. normal completion.
pattern_match pattern_match
Locally controls the behaviour given by the GLOB_COMPLETE Locally controls the behaviour given by the GLOB_COMPLETE
option. Initially it is set to `*' if and only if the option option. Initially it is set to `*' if and only if the option
is set. The completion widget may set it to this value, to is set. The completion widget may set it to this value, to
an empty string (which has the same effect as unsetting it), an empty string (which has the same effect as unsetting it),
or to any other non-empty string. If it is non-empty, or to any other non-empty string. If it is non-empty,
unquoted metacharacters on the command line will be treated unquoted metacharacters on the command line will be treated
as patterns; if it is `*', then additionally a wildcard `*' as patterns; if it is `*', then additionally a wildcard `*'
is assumed at the cursor position; if it is empty or unset, is assumed at the cursor position; if it is empty or unset,
metacharacters will be treated literally. metacharacters will be treated literally.
Note that the matcher specifications given to the compadd Note that the match specifications given to the compadd
builtin command are not used if this is set to a non-empty builtin command are not used if this is set to a non-empty
string. string.
quote quote
When completing inside quotes, this contains the quotation When completing inside quotes, this contains the quotation
character (i.e. either a single quote, a double quote, or a character (i.e. either a single quote, a double quote, or a
backtick). Otherwise it is unset. backtick). Otherwise it is unset.
quoting quoting
When completing inside single quotes, this is set to the When completing inside single quotes, this is set to the
skipping to change at line 1709 skipping to change at line 1708
compadd [ -akqQfenUl12C ] [ -F ARRAY ] compadd [ -akqQfenUl12C ] [ -F ARRAY ]
[-P PREFIX ] [ -S SUFFIX ] [-P PREFIX ] [ -S SUFFIX ]
[-p HIDDEN-PREFIX ] [ -s HIDDEN-SUFFIX ] [-p HIDDEN-PREFIX ] [ -s HIDDEN-SUFFIX ]
[-i IGNORED-PREFIX ] [ -I IGNORED-SUFFIX ] [-i IGNORED-PREFIX ] [ -I IGNORED-SUFFIX ]
[-W FILE-PREFIX ] [ -d ARRAY ] [-W FILE-PREFIX ] [ -d ARRAY ]
[-J GROUP-NAME ] [ -X EXPLANATION ] [ -x MESSAGE ] [-J GROUP-NAME ] [ -X EXPLANATION ] [ -x MESSAGE ]
[-V GROUP-NAME ] [ -o [ ORDER ] ] [-V GROUP-NAME ] [ -o [ ORDER ] ]
[-r REMOVE-CHARS ] [ -R REMOVE-FUNC ] [-r REMOVE-CHARS ] [ -R REMOVE-FUNC ]
[-D ARRAY ] [ -O ARRAY ] [ -A ARRAY ] [-D ARRAY ] [ -O ARRAY ] [ -A ARRAY ]
[-E NUMBER ] [-E NUMBER ]
[-M MATCH-SPEC ] [ -- ] [ WORDS ... ] [-M MATCH-SPEC ] [ -- ] [ COMPLETIONS ... ]
This builtin command can be used to add matches directly and This builtin command can be used to add matches directly and
control all the information the completion code stores with each control all the information the completion code stores with each
possible match. The return status is zero if at least one match possible completion. The return status is zero if at least one
was added and non-zero if no matches were added. match was added and non-zero if no matches were added.
The completion code breaks the string to complete into seven The completion code breaks each match into seven fields in the
fields in the order: order:
<IPRE><APRE><HPRE><WORD><HSUF><ASUF><ISUF> <IPRE><APRE><HPRE><BODY><HSUF><ASUF><ISUF>
The first field is an ignored prefix taken from the command line, The first field is an ignored prefix taken from the command line,
the contents of the IPREFIX parameter plus the string given with the contents of the IPREFIX parameter plus the string given with
the -i option. With the -U option, only the string from the -i the -i option. With the -U option, only the string from the -i
option is used. The field <APRE> is an optional prefix string option is used. The field <APRE> is an optional prefix string
given with the -P option. The <HPRE> field is a string that is 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 considered part of the match but that should not be shown when
listing completions, given with the -p option; for example, listing completions, given with the -p option; for example,
functions that do filename generation might specify a common path functions that do filename generation might specify a common path
prefix this way. <WORD> is the part of the match that should prefix this way. <BODY> is the part of the match that should
appear in the list of completions, i.e. one of the WORDS given at appear in the list of matches shown to the user. The suffixes
the end of the compadd command line. The suffixes <HSUF>, <ASUF> <HSUF>, <ASUF> and <ISUF> correspond to the prefixes <HPRE>,
and <ISUF> correspond to the prefixes <HPRE>, <APRE> and <IPRE> <APRE> and <IPRE> and are given by the options -s, -S and -I,
and are given by the options -s, -S and -I, respectively. respectively.
The supported flags are: The supported flags are:
-P PREFIX -P PREFIX
This gives a string to be inserted before the given WORDS. This gives a string to be inserted before each match. The
The string given is not considered as part of the match and string given is not considered as part of the match and any
any shell metacharacters in it will not be quoted when the shell metacharacters in it will not be quoted when the string
string is inserted. is inserted.
-S SUFFIX -S SUFFIX
Like -P, but gives a string to be inserted after the match. Like -P, but gives a string to be inserted after each match.
-p HIDDEN-PREFIX -p HIDDEN-PREFIX
This gives a string that should be inserted into the command This gives a string that should be inserted before each match
line before the match but that should not appear in the list but that should not appear in the list of matches. Unless the
of matches. Unless the -U option is given, this string must -U option is given, this string must be matched as part of
be matched as part of the string on the command line. the string on the command line.
-s HIDDEN-SUFFIX -s HIDDEN-SUFFIX
Like `-p', but gives a string to insert after the match. Like `-p', but gives a string to insert after each match.
-i IGNORED-PREFIX -i IGNORED-PREFIX
This gives a string to insert into the command line just This gives a string to insert just before any string given
before any string given with the `-P' option. Without `-P' with the `-P' option. Without `-P' the string is inserted
the string is inserted before the string given with `-p' or before the string given with `-p' or directly before each
directly before the match. match.
-I IGNORED-SUFFIX -I IGNORED-SUFFIX
Like -i, but gives an ignored suffix. Like -i, but gives an ignored suffix.
-a -a
With this flag the WORDS are taken as names of arrays and the With this flag the COMPLETIONS are taken as names of arrays
possible matches are their values. If only some elements of and the actual completions are their values. If only some
the arrays are needed, the WORDS may also contain subscripts, elements of the arrays are needed, the COMPLETIONS may also
as in `foo[2,-1]'. contain subscripts, as in `foo[2,-1]'.
-k -k
With this flag the WORDS are taken as names of associative With this flag the COMPLETIONS are taken as names of
arrays and the possible matches are their keys. As for -a, associative arrays and the actual completions are their keys.
the WORDS may also contain subscripts, as in `foo[(R)*bar*]'. As for -a, the WORDS may also contain subscripts, as in
`foo[(R)*bar*]'.
-d ARRAY -d ARRAY
This adds per-match display strings. The ARRAY should contain This adds per-completion display strings. The ARRAY should
one element per WORD given. The completion code will then contain one element per COMPLETION given. The completion code
display the first element instead of the first WORD, and so will then display the first element instead of the first
on. The ARRAY may be given as the name of an array parameter COMPLETION, and so on. The ARRAY may be given as the name of
or directly as a space-separated list of words in parentheses. 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 If there are fewer display strings than COMPLETIONS, the
display strings than WORDS, the leftover display strings will leftover COMPLETIONS will be displayed unchanged and if there
be silently ignored. are more display strings than COMPLETIONS, the leftover
display strings will be silently ignored.
-l -l
This option only has an effect if used together with the -d This option only has an effect if used together with the -d
option. If it is given, the display strings are listed one option. If it is given, the display strings are listed one
per line, not arrayed in columns. per line, not arrayed in columns.
-o [ ORDER ] -o [ ORDER ]
This controls the order in which matches are sorted. ORDER is This controls the order in which matches are sorted. ORDER is
a comma-separated list comprising the following possible a comma-separated list comprising the following possible
values. These values can be abbreviated to their initial two values. These values can be abbreviated to their initial two
skipping to change at line 1807 skipping to change at line 1808
be in the same group. be in the same group.
match match
If given, the order of the output is determined by the If given, the order of the output is determined by the
match strings; otherwise it is determined by the display match strings; otherwise it is determined by the display
strings (i.e. the strings given by the -d option). This strings (i.e. the strings given by the -d option). This
is the default if `-o' is specified but the ORDER is the default if `-o' is specified but the ORDER
argument is omitted. argument is omitted.
nosort nosort
This specifies that the matches are pre-sorted and their This specifies that the COMPLETIONS are pre-sorted and
order should be preserved. This value only makes sense their order should be preserved. This value only makes
alone and cannot be combined with any others. sense alone and cannot be combined with any others.
numeric numeric
If the matches include numbers, sort them numerically If the matches include numbers, sort them numerically
rather than lexicographically. rather than lexicographically.
reverse reverse
Arrange the matches backwards by reversing the sort Arrange the matches backwards by reversing the sort
ordering. ordering.
-J GROUP-NAME -J GROUP-NAME
Gives the name of the group of matches the words should be Gives the name of the group that the matches should be stored
stored in. in.
-V GROUP-NAME -V GROUP-NAME
Like -J but naming an unsorted group. This option is Like -J but naming an unsorted group. This option is
identical to the combination of -J and -o nosort. identical to the combination of -J and -o nosort.
-1 -1
If given together with the -V option, makes only consecutive If given together with the -V option, makes only consecutive
duplicates in the group be removed. If combined with the -J duplicates in the group be removed. If combined with the -J
option, this has no visible effect. Note that groups with and option, this has no visible effect. Note that groups with and
without this flag are in different name spaces. without this flag are in different name spaces.
skipping to change at line 1890 skipping to change at line 1891
character typed inserts anything but a digit. One extra character typed inserts anything but a digit. One extra
backslash sequence is understood in this string: `\-' stands backslash sequence is understood in this string: `\-' stands
for all characters that insert nothing. Thus `-S "=" -q' is for all characters that insert nothing. Thus `-S "=" -q' is
the same as `-S "=" -r "= \t\n\-"'. the same as `-S "=" -r "= \t\n\-"'.
This option may also be used without the -S option; then any This option may also be used without the -S option; then any
automatically added space will be removed when one of the automatically added space will be removed when one of the
characters in the list is typed. characters in the list is typed.
-R REMOVE-FUNC -R REMOVE-FUNC
This is another form of the -r option. When a suffix has been This is another form of the -r option. When a match has been
inserted and the completion accepted, the function accepted and a suffix has been inserted, the function
REMOVE-FUNC will be called after the next character typed. REMOVE-FUNC will be called after the next character typed.
It is passed the length of the suffix as an argument and can It is passed the length of the suffix as an argument and can
use the special parameters available in ordinary use the special parameters available in ordinary
(non-completion) zle widgets (see *Note Zsh Line Editor::) to (non-completion) zle widgets (see *Note Zsh Line Editor::) to
analyse and modify the command line. analyse and modify the command line.
-f -f
If this flag is given, all of the matches built from WORDS are If this flag is given, all of the matches built from the
marked as being the names of files. They are not required to COMPLETIONS are marked as being the names of files. They are
be actual filenames, but if they are, and the option not required to be actual filenames, but if they are, and the
LIST_TYPES is set, the characters describing the types of the option LIST_TYPES is set, the characters describing the types
files in the completion lists will be shown. This also forces of the files in the completion lists will be shown. This also
a slash to be added when the name of a directory is completed. forces a slash to be added when the name of a directory is
completed.
-e -e
This flag can be used to tell the completion code that the This flag can be used to tell the completion code that the
matches added are parameter names for a parameter expansion. matches added are parameter names for a parameter expansion.
This will make the AUTO_PARAM_SLASH and AUTO_PARAM_KEYS This will make the AUTO_PARAM_SLASH and AUTO_PARAM_KEYS
options be used for the matches. options be used for the matches.
-W FILE-PREFIX -W FILE-PREFIX
This string is a pathname that will be prepended to each of This string is a pathname that will be prepended to each
the matches formed by the given WORDS together with any match together with any prefix specified by the -p option to
prefix specified by the -p option to form a complete filename form a complete filename for testing. Hence it is only
for testing. Hence it is only useful if combined with the -f useful if combined with the -f flag, as the tests will not
flag, as the tests will not otherwise be performed. otherwise be performed.
-F ARRAY -F ARRAY
Specifies an array containing patterns. Words matching one of Specifies an array containing patterns. COMPLETIONS that
these patterns are ignored, i.e. not considered to be match one of these patterns are ignored, that is, not
possible matches. considered to be matches.
The ARRAY may be the name of an array parameter or a list of The ARRAY may be the name of an array parameter or a list of
literal patterns enclosed in parentheses and quoted, as in literal patterns enclosed in parentheses and quoted, as in
`-F "(*?.o *?.h)"'. If the name of an array is given, the `-F "(*?.o *?.h)"'. If the name of an array is given, the
elements of the array are taken as the patterns. elements of the array are taken as the patterns.
-Q -Q
This flag instructs the completion code not to quote any This flag instructs the completion code not to quote any
metacharacters in the words when inserting them into the metacharacters in the matches when inserting them into the
command line. command line.
-M MATCH-SPEC -M MATCH-SPEC
This gives local match specifications as described below in This gives local match specifications as described below in
*Note Completion Matching Control::. This option may be given *Note Completion Matching Control::. This option may be given
more than once. In this case all MATCH-SPECs given are more than once. In this case all MATCH-SPECs given are
concatenated with spaces between them to form the concatenated with spaces between them to form the
specification string to use. Note that they will only be specification string to use. Note that they will only be
used if the -U option is not given. used if the -U option is not given.
-n -n
Specifies that the words added are to be used as possible Specifies that matching COMPLETIONS are to be added to the
matches, but are not to appear in the completion listing. set of matches, but are not to be listed to the user.
-U -U
If this flag is given, all words given will be accepted and If this flag is given, all COMPLETIONS are added to the set
no matching will be done by the completion code. Normally of matches and no matching will be done by the completion
this is used in functions that do the matching themselves. code. Normally this is used in functions that do the matching
themselves.
-O ARRAY -O ARRAY
If this option is given, the WORDS are _not_ added to the set If this option is given, the COMPLETIONS are _not_ added to
of possible completions. Instead, matching is done as usual the set of matches. Instead, matching is done as usual and
and all of the WORDS given as arguments that match the string all of the COMPLETIONS that match will be stored in the array
on the command line will be stored in the array parameter parameter whose name is given as ARRAY.
whose name is given as ARRAY.
-A ARRAY -A ARRAY
As the -O option, except that instead of those of the WORDS As the -O option, except that instead of those of the
which match being stored in ARRAY, the strings generated COMPLETIONS which match being stored in ARRAY, the strings
internally by the completion code are stored. For example, generated internally by the completion code are stored. For
with a matching specification of `-M "L:|no="', the string example, with a match specification of `-M "L:|no="', a
`nof' on the command line and the string `foo' as one of the current word of `nof' and COMPLETIONS of `foo', this option
WORDS, this option stores the string `nofoo' in the array, stores the string `nofoo' in the array, whereas the -O option
whereas the -O option stores the `foo' originally given. stores the `foo' originally given.
-D ARRAY -D ARRAY
As with -O, the WORDS are not added to the set of possible As with -O, the COMPLETIONS are not added to the set of
completions. Instead, the completion code tests whether each matches. Instead, whenever the Nth COMPLETION does not
WORD in turn matches what is on the line. If the Nth WORD match, the Nth element of the ARRAY is removed. Elements for
does not match, the Nth element of the ARRAY is removed. which the corresponding COMPLETION matches are retained.
Elements for which the corresponding WORD is matched are This option can be used more than once to remove elements
retained. from multiple arrays.
-C -C
This option adds a special match which expands to all other This option adds a special match which expands to all other
matches when inserted into the line, even those that are matches when inserted into the line, even those that are
added after this option is used. Together with the -d option added after this option is used. Together with the -d option
it is possible to specify a string that should be displayed it is possible to specify a string that should be displayed
in the list for this special match. If no string is given, in the list for this special match. If no string is given,
it will be shown as a string containing the strings that it will be shown as a string containing the strings that
would be inserted for the other matches, truncated to the would be inserted for the other matches, truncated to the
width of the screen. width of the screen.
-E NUMBER -E NUMBER
This option adds NUMBER empty matches after the WORDS have This option adds NUMBER empty matches after matching
been added. An empty match takes up space in completion COMPLETIONS have been added. An empty match takes up space
listings but will never be inserted in the line and can't be in completion listings but will never be inserted in the line
selected with menu completion or menu selection. This makes and can't be selected with menu completion or menu selection.
empty matches only useful to format completion lists and to This makes empty matches only useful to format completion
make explanatory string be shown in completion lists (since lists and to make explanatory string be shown in completion
empty matches can be given display strings with the -d lists (since empty matches can be given display strings with
option). And because all but one empty string would the -d option). And because all but one empty string would
otherwise be removed, this option implies the -V and -2 otherwise be removed, this option implies the -V and -2
options (even if an explicit -J option is given). This can be options (even if an explicit -J option is given). This can be
important to note as it affects the name space into which important to note as it affects the name space into which
matches are added. matches are added.
- -
-- --
This flag ends the list of flags and options. All arguments 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 after it will be taken as the COMPLETIONS even if they begin
they begin with hyphens. with hyphens.
Except for the -M flag, if any of these flags is given more than Except for the -M flag, if any of these flags is given more than
once, the first one (and its argument) will be used. once, the first one (and its argument) will be used.
compset -p NUMBER compset -p NUMBER
compset -P [ NUMBER ] PATTERN compset -P [ NUMBER ] PATTERN
compset -s NUMBER compset -s NUMBER
compset -S [ NUMBER ] PATTERN compset -S [ NUMBER ] PATTERN
compset -n BEGIN [ END ] compset -n BEGIN [ END ]
compset -N BEG-PAT [ END-PAT ] compset -N BEG-PAT [ END-PAT ]
skipping to change at line 2143 skipping to change at line 2145
-between BEG-PAT END-PAT -between BEG-PAT END-PAT
true if the test for the -N option with both patterns would true if the test for the -N option with both patterns would
succeed. succeed.
 
File: zsh.info, Node: Completion Matching Control, Next: Completion Widget Exa mple, Prev: Completion Condition Codes, Up: Completion Widgets File: zsh.info, Node: Completion Matching Control, Next: Completion Widget Exa mple, Prev: Completion Condition Codes, Up: Completion Widgets
19.5 Completion Matching Control 19.5 Completion Matching Control
================================ ================================
It is possible by use of the -M option of the compadd builtin command When the user invokes completion, the current _word_ on the command line
to specify how the characters in the string to be completed (referred (that is, the word the cursor is currently on) is used to generate a
to here as the command line) map onto the characters in the list of _match pattern_. Only those _completions_ that match the pattern are
matches produced by the completion code (referred to here as the trial offered to the user as _matches_.
completions). Note that this is not used if the command line contains a
glob pattern and the GLOB_COMPLETE option is set or the pattern_match The default match pattern is generated from the current word by either
of the compstate special association is set to a non-empty string.
* appending a `*' (matching any number of characters in a completion)
The MATCH-SPEC given as the argument to the -M option (see *Note _or,_
Completion Builtin Commands::) consists of one or more matching
descriptions separated by whitespace. Each description consists of a * if the shell option COMPLETE_IN_WORD is set, inserting a `*' at the
letter followed by a colon and then the patterns describing which cursor position.
character sequences on the line match which character sequences in the
trial completion. Any sequence of characters not handled in this This narrow pattern can be broadened selectively by passing a _match
fashion must match exactly, as usual. specification_ to the compadd builtin command through its -M option (see
*Note Completion Builtin Commands::). A match specification consists
The forms of MATCH-SPEC understood are as follows. In each case, the of one or more MATCHERS separated by whitespace. Matchers in a match
form with an upper case initial character retains the string already specification are applied one at a time, from left to right. Once all
typed on the command line as the final result of completion, while with matchers have been applied, completions are compared to the final match
a lower case initial character the string on the command line is changed pattern and non-matching ones are discarded.
into the corresponding part of the trial completion.
* Note that the -M option is ignored if the current word contains a
m:LPAT=TPAT glob pattern and the shell option GLOB_COMPLETE is set or if the
M:LPAT=TPAT pattern_match key of the special associative array compstate is
Here, LPAT is a pattern that matches on the command line, set to a non-empty value (see *Note Completion Special
corresponding to TPAT which matches in the trial completion. Parameters::).
l:LANCHOR|LPAT=TPAT * Users of the *Note Completion System:: should generally not use
L:LANCHOR|LPAT=TPAT the -M option directly, but rather use the matcher-list and
l:LANCHOR||RANCHOR=TPAT matcher styles (see the subsection _Standard Styles_ in *Note
L:LANCHOR||RANCHOR=TPAT Completion System Configuration::).
b:LPAT=TPAT
B:LPAT=TPAT Each matcher consists of
These letters are for patterns that are anchored by another
pattern on the left side. Matching for LPAT and TPAT is as for m * a case-sensitive letter
and M, but the pattern LPAT matched on the command line must be
preceded by the pattern LANCHOR. The LANCHOR can be blank to * a `:',
anchor the match to the start of the command line string;
otherwise the anchor can occur anywhere, but must match in both * one or more patterns separated by pipes (`|'),
the command line and trial completion strings.
* an equals sign (`='), and
If no LPAT is given but a RANCHOR is, this matches the gap between
substrings matched by LANCHOR and RANCHOR. Unlike LANCHOR, the * another pattern.
RANCHOR only needs to match the trial completion string.
The patterns before the `=' are used to match substrings of the current
The b and B forms are similar to l and L with an empty anchor, but word. For each matched substring, the corresponding part of the match
need to match only the beginning of the word on the command line pattern is broadened with the pattern after the `=', by means of a
or trial completion, respectively. logical OR.
r:LPAT|RANCHOR=TPAT Each pattern in a matcher cosists of either
R:LPAT|RANCHOR=TPAT
r:LANCHOR||RANCHOR=TPAT * the empty string or
R:LANCHOR||RANCHOR=TPAT
e:LPAT=TPAT * a sequence of
E:LPAT=TPAT
As l, L, b and B, with the difference that the command line and * literal characters (which may be quoted with a `\'),
trial completion patterns are anchored on the right side. Here an
empty RANCHOR and the e and E forms force the match to the end of * question marks (`?'),
the command line or trial completion string.
* bracket expressions (`[...]'; see the subsection _Glob
Operators_ in *Note Filename Generation::), and/or
* brace expressions (see below).
Other shell patterns are not allowed.
A brace expression, like a bracket expression, consists of a list of
* literal characters,
* ranges (`0-9'), and/or
* character classes (`[:NAME:]').
However, they differ from each other as follows:
* A brace expression is delimited by a pair of braces (`{...}').
* Brace expressions do not support negations. That is, an initial
`!' or `^' has no special meaning and will be interpreted as a
literal character.
* When a character in the current word matches the Nth pattern in a
brace expression, the corresponding part of the match pattern is
broadened only with the Nth pattern of the brace expression on the
other side of the `=', if there is one; if there is no brace
expression on the other side, then this pattern is the empty
string. However, if either brace expression has more elements
than the other, then the excess entries are simply ignored. When
comparing indexes, each literal character or character class
counts as one element, but each range is instead expanded to the
full list of literal characters it represents. Additionally, if
on _both_ sides of the `=', the Nth pattern is `[:upper:]' or
`[:lower:]', then these are expanded as ranges, too.
Note that, although the matching system does not yet handle multibyte
characters, this is likely to be a future extension. Hence, using
`[:upper:]' and `[:lower:]' is recommended over `A-Z' and `a-z'.
Below are the different forms of matchers supported. Each _uppercase_
form behaves exactly like its lowercase counterpart, but adds an
additional step _after_ the match pattern has filtered out non-matching
completions: Each of a match's substrings that was matched by a
subpattern from an uppercase matcher is replaced with the corresponding
substring of the current word. However, patterns from _lowercase_
matchers have higher weight: If a substring of the current word was
matched by patterns from both a lowercase and an uppercase matcher,
then the lowercase matcher's pattern wins and the corresponding part of
the match is not modified.
Unless indicated otherwise, each example listed assumes
COMPLETE_IN_WORD to be unset (as it is by default).
m:WORD-PAT=MATCH-PAT
M:WORD-PAT=MATCH-PAT
For each substring of the current word that matches WORD-PAT,
broaden the corresponding part of the match pattern to
additionally match MATCH-PAT.
Examples:
m:{[:lower:]}={[:upper:]} lets any lower case character in
the current word be completed to itself or its uppercase
counterpart. So, the completions `foo', `FOO' and `Foo' will
are be considered matches for the word `fo'.
M:_= inserts every underscore from the current word into each
match, in the same relative position, determined by matching
the substrings around it. So, given a completion `foo', the
word `f_o' will be completed to the match `f_oo', even though
the latter was not present as a completion.
b:WORD-PAT=MATCH-PAT
B:WORD-PAT=MATCH-PAT
e:WORD-PAT=MATCH-PAT
E:WORD-PAT=MATCH-PAT
For each consecutive substring at the b:eginning or e:nd of the
current word that matches WORD-PAT, broaden the corresponding part
of the match pattern to additionally match MATCH-PAT.
Examples:
`b:-=+' lets any number of minuses at the start of the
current word be completed to a minus or a plus.
`B:0=' adds all zeroes at the beginning of the current word
to the beginning of each match.
l:|WORD-PAT=MATCH-PAT
L:|WORD-PAT=MATCH-PAT
R:WORD-PAT|=MATCH-PAT
r:WORD-PAT|=MATCH-PAT
If there is a substring at the l:eft or r:ight edge of the current
word that matches WORD-PAT, then broaden the corresponding part of
the match pattern to additionally match MATCH-PAT.
For each l:, L:, r: and R: matcher (including the ones below), the
pattern MATCH-PAT may also be a `*'. This matches any number of
characters in a completion.
Examples:
`r:|=*' appends a `*' to the match pattern, even when
COMPLETE_IN_WORD is set and the cursor is not at the end of
the current word.
If the current word starts with a minus, then `L:|-=' will
prepend it to each match.
l:ANCHOR|WORD-PAT=MATCH-PAT
L:ANCHOR|WORD-PAT=MATCH-PAT
r:WORD-PAT|ANCHOR=MATCH-PAT
R:WORD-PAT|ANCHOR=MATCH-PAT
For each substring of the current word that matches WORD-PAT and
has on its l:eft or r:ight another substring matching ANCHOR,
broaden the corresponding part of the match pattern to
additionally match MATCH-PAT.
Note that these matchers (and the ones below) modify only what is
matched by WORD-PAT; they do not change the matching behavior of
what is matched by ANCHOR (or COANCHOR; see the matchers below).
Thus, unless its corresponding part of the match pattern has been
modified, the anchor in the current word has to match literally in
each completion, just like any other substring of the current word.
If a matcher includes at least one anchor (which includes the
matchers with two anchors, below), then MATCH-PAT may also be `*'
or `**'. `*' can match any part of a completion that does not
contain any substrings matching ANCHOR, whereas a `**' can match
any part of a completion, period. (Note that this is different
from the behavior of `*' in the anchorless forms of `l:' and `r:'
and and also different from `*' and `**' in glob expressions.)
Examples:
`r:|.=*' makes the completion `comp.sources.unix' a match for
the word `..u' -- but _not_ for the word `.u'.
Given a completion `--foo', the matcher `L:-|no-=' will
complete the word `--no-' to the match `--no-foo'.
l:ANCHOR||COANCHOR=MATCH-PAT
L:ANCHOR||COANCHOR=MATCH-PAT
r:COANCHOR||ANCHOR=MATCH-PAT
R:COANCHOR||ANCHOR=MATCH-PAT
For any two consecutive substrings of the current word that match
ANCHOR and COANCHOR, in the order given, insert the pattern
MATCH-PAT between their corresponding parts in the match pattern.
Note that, unlike ANCHOR, the pattern COANCHOR does not change what
`*' can match.
Examples:
`r:?||[[:upper:]]=*' will complete the current word `fB' to
`fooBar', but it will not complete it to `fooHooBar' (because
`*' here cannot match anything that includes a match for
`[[:upper:]]), nor will it complete `B' to `fooBar' (because
there is no character in the current word to match COANCHOR).
Given the current word `pass.n' and a completion
`pass.byname', the matcher `L:.||[[:alpha:]]=by' will produce
the match `pass.name'.
x: x:
This form is used to mark the end of matching specifications: Ignore this matcher and all matchers to its right.
subsequent specifications are ignored. In a single standalone list
of specifications this has no use but where matching specifications This matcher is used to mark the end of a match specification. In
are accumulated, such as from nested function calls, it can allow a single standalone list of matchers, this has no use, but where
one function to override another. match specifications are concatenated, as is often the case when
using the *Note Completion System::, it can allow one match
Each LPAT, TPAT or ANCHOR is either an empty string or consists of a specification to override another.
sequence of literal characters (which may be quoted with a backslash),
question marks, character classes, and correspondence classes; ordinary
shell patterns are not used. Literal characters match only themselves,
question marks match any character, and character classes are formed as
for globbing and match any character in the given set.
Correspondence classes are defined like character classes, but with two
differences: they are delimited by a pair of braces, and negated classes
are not allowed, so the characters ! and ^ have no special meaning
directly after the opening brace. They indicate that a range of
characters on the line match a range of characters in the trial
completion, but (unlike ordinary character classes) paired according to
the corresponding position in the sequence. For example, to make any
ASCII lower case letter on the line match the corresponding upper case
letter in the trial completion, you can use `m:{a-z}={A-Z}' (however,
see below for the recommended form for this). More than one pair of
classes can occur, in which case the first class before the =
corresponds to the first after it, and so on. If one side has more
such classes than the other side, the superfluous classes behave like
normal character classes. In anchor patterns correspondence classes
also behave like normal character classes.
The standard `[:NAME:]' forms described for standard shell patterns (see
*Note Filename Generation::) may appear in correspondence classes as
well as normal character classes. The only special behaviour in
correspondence classes is if the form on the left and the form on the
right are each one of [:upper:], [:lower:]. In these cases the
character in the word and the character on the line must be the same up
to a difference in case. Hence to make any lower case character on the
line match the corresponding upper case character in the trial
completion you can use `m:{[:lower:]}={[:upper:]}'. Although the
matching system does not yet handle multibyte characters, this is likely
to be a future extension, at which point this syntax will handle
arbitrary alphabets; hence this form, rather than the use of explicit
ranges, is the recommended form. In other cases `[:NAME:]' forms are
allowed. If the two forms on the left and right are the same, the
characters must match exactly. In remaining cases, the corresponding
tests are applied to both characters, but they are not otherwise
constrained; any matching character in one set goes with any matching
character in the other set: this is equivalent to the behaviour of
ordinary character classes.
The pattern TPAT may also be one or two stars, `*' or `**'. This means
that the pattern on the command line can match any number of characters
in the trial completion. In this case the pattern must be anchored (on
either side); in the case of a single star, the ANCHOR then determines
how much of the trial completion is to be included -- only the
characters up to the next appearance of the anchor will be matched.
With two stars, substrings matched by the anchor can be matched, too.
Examples:
The keys of the options association defined by the parameter module are
the option names in all-lower-case form, without underscores, and
without the optional no at the beginning even though the builtins
setopt and unsetopt understand option names with upper case letters,
underscores, and the optional no. The following alters the matching
rules so that the prefix no and any underscore are ignored when trying
to match the trial completions generated and upper case letters on the
line match the corresponding lower case letters in the words:
compadd -M 'L:|[nN][oO]= M:_= M:{[:upper:]}={[:lower:]}' - \
${(k)options}
The first part says that the pattern `[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 completion, so it
will be ignored if present. The second part does the same for an
underscore anywhere in the command line string, and the third part uses
correspondence classes so that any upper case letter on the line
matches the corresponding lower case letter in the word. The use of the
upper case forms of the specification characters (L and M) guarantees
that what has already been typed on the command line (in particular the
prefix no) will not be deleted.
Note that the use of L in the first part means that it matches only
when at the beginning of both the command line string and the trial
completion. I.e., the string `_NO_f' would not be completed to
`_NO_foo', nor would `NONO_f' be completed to `NONO_foo' because of the
leading underscore or the second `NO' on the line which makes the
pattern fail even though they are otherwise ignored. To fix this, one
would use `B:[nN][oO]=' instead of the first part. As described above,
this matches at the beginning of the trial completion, independent of
other characters or substrings at the beginning of the command line
word which are ignored by the same or other MATCH-SPECs.
The second example makes completion case insensitive. This is just the
same as in the option example, except here we wish to retain the
characters in the list of completions:
compadd -M 'm:{[:lower:]}={[:upper:]}' ...
This makes lower case letters match their upper case counterparts. To
make upper case letters match the lower case forms as well:
compadd -M 'm:{[:lower:][:upper:]}={[:upper:][:lower:]}' ...
A nice example for the use of * patterns is partial word completion.
Sometimes you would like to make strings like `c.s.u' complete to
strings like `comp.source.unix', i.e. the word on the command line
consists of multiple parts, separated by a dot in this example, where
each part should be completed separately -- note, however, that the
case where each part of the word, i.e. `comp', `source' and `unix' in
this example, is to be completed from separate sets of matches is a
different problem to be solved by the implementation of the completion
widget. The example can be handled by:
compadd -M 'r:|.=* r:|=*' \
- comp.sources.unix comp.sources.misc ...
The first specification says that LPAT is the empty string, while
ANCHOR is a dot; TPAT is *, so this can match anything except for the
`.' from the anchor in the trial completion word. So in `c.s.u', the
matcher sees `c', followed by the empty string, followed by the anchor
`.', and likewise for the second dot, and replaces the empty strings
before the anchors, giving `c[omp].s[ources].u[nix]', where the last
part of the completion is just as normal.
With the pattern shown above, the string `c.u' could not be completed
to `comp.sources.unix' because the single star means that no dot
(matched by the anchor) can be skipped. By using two stars as in
`r:|.=**', however, `c.u' could be completed to `comp.sources.unix'.
This also shows that in some cases, especially if the anchor is a real
pattern, like a character class, the form with two stars may result in
more matches than one would like.
The second specification is needed to make this work when the cursor is
in the middle of the string on the command line and the option
COMPLETE_IN_WORD is set. In this case the completion code would
normally try to match trial completions that end with the string as
typed so far, i.e. it will only insert new characters at the cursor
position rather than at the end. However in our example we would like
the code to recognise matches which contain extra characters after the
string on the line (the `nix' in the example). Hence we say that the
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
compadd -M 'r:|[.,_-]=* r:|=*' ...
allows one to complete words with abbreviations before any of the
characters in the square brackets. For example, to complete
veryverylongfile.c rather than veryverylongheader.h with the above in
effect, you can just type very.c before attempting completion.
The specifications with both a left and a right anchor are useful to
complete partial words whose parts are not separated by some special
character. For example, in some places strings have to be completed
that are formed `LikeThis' (i.e. the separate parts are determined by a
leading upper case letter) or maybe one has to complete strings with
trailing numbers. Here one could use the simple form with only one
anchor as in:
compadd -M 'r:|[[:upper:]0-9]=* r:|=*' LikeTHIS FooHoo 5foo123 5bar234
But with this, the string `H' would neither complete to `FooHoo' nor to
`LikeTHIS' because in each case there is an upper case letter before
the `H' and that is matched by the anchor. Likewise, a `2' would not be
completed. In both cases this could be changed by using
`r:|[[:upper:]0-9]=**', but then `H' completes to both `LikeTHIS' and
`FooHoo' and a `2' matches the other strings because characters can be
inserted before every upper case letter and digit. To avoid this one
would use:
compadd -M 'r:[^[:upper:]0-9]||[[:upper:]0-9]=** r:|=*' \
LikeTHIS FooHoo foo123 bar234
By using these two anchors, a `H' matches only upper case `H's that are
immediately preceded by something matching the left anchor
`[^[:upper:]0-9]'. The effect is, of course, that `H' matches only the
string `FooHoo', a `2' matches only `bar234' and so on.
When using the completion system (see *Note Completion System::), users
can define match specifications that are to be used for specific
contexts by using the matcher and matcher-list styles. The values for
the latter will be used everywhere.
 
File: zsh.info, Node: Completion Widget Example, Prev: Completion Matching Con trol, Up: Completion Widgets File: zsh.info, Node: Completion Widget Example, Prev: Completion Matching Con trol, Up: Completion Widgets
19.6 Completion Widget Example 19.6 Completion Widget Example
============================== ==============================
The first step is to define the widget: The first step is to define the widget:
zle -C complete complete-word complete-files zle -C complete complete-word complete-files
skipping to change at line 2590 skipping to change at line 2574
not already in the function search path. not already in the function search path.
For security reasons compinit also checks if the completion system For security reasons compinit also checks if the completion system
would use files not owned by root or by the current user, or files in would use files not owned by root or by the current user, or files in
directories that are world- or group-writable or that are not owned by directories that are world- or group-writable or that are not owned by
root or by the current user. If such files or directories are found, root or by the current user. If such files or directories are found,
compinit will ask if the completion system should really be used. To compinit will ask if the completion system should really be used. To
avoid these tests and make all files found be used without asking, use avoid these tests and make all files found be used without asking, use
the option -u, and to make compinit silently ignore all insecure files the option -u, and to make compinit silently ignore all insecure files
and directories use the option -i. This security check is skipped and directories use the option -i. This security check is skipped
entirely when the -C option is given. entirely when the -C option is given, provided the dumpfile exists.
The security check can be retried at any time by running the function The security check can be retried at any time by running the function
compaudit. This is the same check used by compinit, but when it is compaudit. This is the same check used by compinit, but when it is
executed directly any changes to fpath are made local to the function executed directly any changes to fpath are made local to the function
so they do not persist. The directories to be checked may be passed as so they do not persist. The directories to be checked may be passed as
arguments; if none are given, compaudit uses fpath and _compdir to find arguments; if none are given, compaudit uses fpath and _compdir to find
completion system directories, adding missing ones to fpath as completion system directories, adding missing ones to fpath as
necessary. To force a check of exactly the directories currently named necessary. To force a check of exactly the directories currently named
in fpath, set _compdir to an empty string before calling compaudit or in fpath, set _compdir to an empty string before calling compaudit or
compinit. compinit.
skipping to change at line 2712 skipping to change at line 2696
The # is part of the tag name and no white space is allowed after it. The # is part of the tag name and no white space is allowed after it.
The #compdef tags use the compdef function described below; the main The #compdef tags use the compdef function described below; the main
difference is that the name of the function is supplied implicitly. difference is that the name of the function is supplied implicitly.
The special contexts for which completion functions can be defined are: The special contexts for which completion functions can be defined are:
-array-value- -array-value-
The right hand side of an array-assignment (`NAME=(...)') The right hand side of an array-assignment (`NAME=(...)')
-brace-parameter-
The name of a parameter expansion within braces (`${...}')
-assign-parameter- -assign-parameter-
The name of a parameter in an assignment, i.e. on the left hand The name of a parameter in an assignment, i.e. on the left hand
side of an `=' side of an `='
-brace-parameter-
The name of a parameter expansion within braces (`${...}')
-command- -command-
A word in command position A word in command position
-condition- -condition-
A word inside a condition (`[[...]]') A word inside a condition (`[[...]]')
-default- -default-
Any word for which no other completion is defined Any word for which no other completion is defined
-equal- -equal-
skipping to change at line 3012 skipping to change at line 2996
tags in the given order. tags in the given order.
The _complete_help bindable command shows all the contexts and tags The _complete_help bindable command shows all the contexts and tags
available for completion at a particular point. This provides an easy available for completion at a particular point. This provides an easy
way of finding information for tag-order and other styles. It is way of finding information for tag-order and other styles. It is
described in *Note Bindable Commands::. described in *Note Bindable Commands::.
When looking up styles the completion system uses full context names, When looking up styles the completion system uses full context names,
including the tag. Looking up the value of a style therefore consists including the tag. Looking up the value of a style therefore consists
of two things: the context, which is matched to the most specific (best of two things: the context, which is matched to the most specific (best
fitting) style pattern, and the name of the style itself, which must be fitting) pattern, and the name of the style itself, which must be
matched exactly. The following examples demonstrate that style patterns matched exactly. The following examples demonstrate that patterns may
may be loosely defined for styles that apply broadly, or as tightly be loosely defined for styles that apply broadly, or as tightly defined
defined as desired for styles that apply in narrower circumstances. as desired for styles that apply in narrower circumstances.
For example, many completion functions can generate matches in a simple For example, many completion functions can generate matches in a simple
and a verbose form and use the verbose style to decide which form and a verbose form and use the verbose style to decide which form
should be used. To make all such functions use the verbose form, put should be used. To make all such functions use the verbose form, put
zstyle ':completion:*' verbose yes zstyle ':completion:*' verbose yes
in a startup file (probably .zshrc). This gives the verbose style the in a startup file (probably .zshrc). This gives the verbose style the
value yes in every context inside the completion system, unless that value yes in every context inside the completion system, unless that
context has a more specific definition. It is best to avoid giving the context has a more specific definition. It is best to avoid giving the
context as `*' in case the style has some meaning outside the pattern as `*' in case the style has some meaning outside the
completion system. completion system.
Many such general purpose styles can be configured simply by using the Many such general purpose styles can be configured simply by using the
compinstall function. compinstall function.
A more specific example of the use of the verbose style is by the A more specific example of the use of the verbose style is by the
completion for the kill builtin. If the style is set, the builtin completion for the kill builtin. If the style is set, the builtin
lists full job texts and process command lines; otherwise it shows the lists full job texts and process command lines; otherwise it shows the
bare job numbers and PIDs. To turn the style off for this use only: bare job numbers and PIDs. To turn the style off for this use only:
skipping to change at line 3060 skipping to change at line 3044
This forces the value of the hosts style to be read from the variable This forces the value of the hosts style to be read from the variable
myhosts each time a host name is needed; this is useful if the value of myhosts each time a host name is needed; this is useful if the value of
myhosts can change dynamically. For another useful example, see the myhosts can change dynamically. For another useful example, see the
example in the description of the file-list style below. This form can example in the description of the file-list style below. This form can
be slow and should be avoided for commonly examined styles such as menu be slow and should be avoided for commonly examined styles such as menu
and list-rows-first. and list-rows-first.
Note that the order in which styles are _defined_ does not matter; the Note that the order in which styles are _defined_ does not matter; the
style mechanism uses the most specific possible match for a particular style mechanism uses the most specific possible match for a particular
style to determine the set of values. More precisely, strings are style to determine the set of values. Strings are preferred over
preferred over patterns (for example, `:completion::complete:::foo' is patterns (for example, `:completion::complete:::foo' is more specific
more specific than `:completion::complete:::*'), and longer patterns are than `:completion::complete:::*'), and longer patterns are preferred
preferred over shorter patterns. over the pattern `*'. See *Note The zsh/zutil Module:: for details.
A good rule of thumb is that any completion style pattern that needs to Context patterns that use something other than a wildcard (*) to match
include more than one wildcard (*) and that does not end in a tag name, the middle parts of the context -- the COMPLETER, COMMAND, and ARGUMENT
should include all six colons (:), possibly surrounding additional in :completion:FUNCTION:COMPLETER:COMMAND:ARGUMENT:TAG -- should
wildcards. include all six colons (:) explicitly. Without this, a pattern such as
:completion:*:foo:* could match foo against a component other than the
intended one (for example, against COMPLETER when a match against
COMMAND was intended).
Style names like those of tags are arbitrary and depend on the Style names like those of tags are arbitrary and depend on the
completion function. However, the following two sections list some of completion function. However, the following two sections list some of
the most common tags and styles. the most common tags and styles.
20.3.2 Standard Tags 20.3.2 Standard Tags
-------------------- --------------------
Some of the following are only used when looking up particular styles Some of the following are only used when looking up particular styles
and do not refer to a type of match. and do not refer to a type of match.
skipping to change at line 3203 skipping to change at line 3190
history-words history-words
for words from the history for words from the history
hosts hosts
for hostnames for hostnames
indexes indexes
for array indexes for array indexes
jobs
for jobs (as listed by the `jobs' builtin)
interfaces interfaces
for network interfaces for network interfaces
jobs
for jobs (as listed by the `jobs' builtin)
keymaps keymaps
for names of zsh keymaps for names of zsh keymaps
keysyms keysyms
for names of X keysyms for names of X keysyms
libraries libraries
for names of system libraries for names of system libraries
limits limits
for system limits for system limits
local-directories local-directories
for names of directories that are subdirectories of the current for names of directories that are subdirectories of the current
working directory when completing arguments of cd and related working directory when completing arguments of cd and related
builtin commands (compare path-directories) -- when the cdpath builtin commands (compare path-directories) -- when the cdpath
array is unset, directories is used instead array is unset, directories is used instead
manuals
for names of manual pages
mailboxes mailboxes
for e-mail folders for e-mail folders
manuals
for names of manual pages
maps maps
for map names (e.g. NIS maps) for map names (e.g. NIS maps)
messages messages
used to look up the format style for messages used to look up the format style for messages
modifiers modifiers
for names of X modifiers for names of X modifiers
modules modules
skipping to change at line 3270 skipping to change at line 3257
options options
for command options for command options
original original
used by the _approximate, _correct and _expand completers when used by the _approximate, _correct and _expand completers when
offering the original string as a match offering the original string as a match
other-accounts other-accounts
used to look up the users-hosts style used to look up the users-hosts style
other-files
for the names of any non-directory files. This is used instead of
all-files when the list-dirs-first style is in effect.
packages packages
for packages (e.g. rpm or installed Debian packages) for packages (e.g. rpm or installed Debian packages)
parameters parameters
for names of parameters for names of parameters
path-directories path-directories
for names of directories found by searching the cdpath array when for names of directories found by searching the cdpath array when
completing arguments of cd and related builtin commands (compare completing arguments of cd and related builtin commands (compare
local-directories) local-directories)
skipping to change at line 3634 skipping to change at line 3617
If one of its values is the string `prefix', the partially typed If one of its values is the string `prefix', the partially typed
word from the line will be expanded as far as possible even if word from the line will be expanded as far as possible even if
trailing parts cannot be completed. trailing parts cannot be completed.
If one of its values is the string `suffix', matching names for If one of its values is the string `suffix', matching names for
components after the first ambiguous one will also be added. This components after the first ambiguous one will also be added. This
means that the resulting string is the longest unambiguous string means that the resulting string is the longest unambiguous string
possible. However, menu completion can be used to cycle through possible. However, menu completion can be used to cycle through
all matches. all matches.
extra-verbose
If set, the completion listing is more verbose at the cost of a
probable decrease in completion speed. Completion performance
will suffer if this style is set to `true'.
fake fake
This style may be set for any completion context. It specifies This style may be set for any completion context. It specifies
additional strings that will always be completed in that context. additional strings that will always be completed in that context.
The form of each string is `VALUE:DESCRIPTION'; the colon and The form of each string is `VALUE:DESCRIPTION'; the colon and
description may be omitted, but any literal colons in VALUE must description may be omitted, but any literal colons in VALUE must
be quoted with a backslash. Any DESCRIPTION provided is shown be quoted with a backslash. Any DESCRIPTION provided is shown
alongside the value in completion listings. alongside the value in completion listings.
It is important to use a sufficiently restrictive context when It is important to use a sufficiently restrictive context when
specifying fake strings. Note that the styles fake-files and specifying fake strings. Note that the styles fake-files and
skipping to change at line 3761 skipping to change at line 3749
patterns can be given inside braces, separated by commas. patterns can be given inside braces, separated by commas.
The TAGs of all strings in the value will be offered by _files and The TAGs of all strings in the value will be offered by _files and
used when looking up other styles. Any TAGs in the same word will used when looking up other styles. Any TAGs in the same word will
be offered at the same time and before later words. If no `:TAG' be offered at the same time and before later words. If no `:TAG'
is given the `files' tag will be used. is given the `files' tag will be used.
The TAG may also be followed by an optional second colon and a The TAG may also be followed by an optional second colon and a
description, which will be used for the `%d' in the value of the description, which will be used for the `%d' in the value of the
format style (if that is set) instead of the default description format style (if that is set) instead of the default description
supplied by the completion function. If the description given supplied by the completion function. The inclusion of a
here contains itself a `%d', that is replaced with the description description also gives precedence to associated options such as
supplied by the completion function. for completion grouping so it can be used where files should be
separated.
For example, to make the rm command first complete only names of For example, to make the rm command first complete only names of
object files and then the names of all files if there is no object files and then the names of all files if there is no
matching object file: matching object file:
zstyle ':completion:*:*:rm:*:*' file-patterns \ zstyle ':completion:*:*:rm:*:*' file-patterns \
'*.o:object-files' '%p:all-files' '*.o:object-files' '%p:all-files'
To alter the default behaviour of file completion -- offer files To alter the default behaviour of file completion -- offer files
matching a pattern and directories on the first attempt, then all matching a pattern and directories on the first attempt, then all
skipping to change at line 3785 skipping to change at line 3774
directories, and finally all files: directories, and finally all files:
zstyle ':completion:*' file-patterns \ zstyle ':completion:*' file-patterns \
'%p:globbed-files' '*(-/):directories' '*:all-files' '%p:globbed-files' '*(-/):directories' '*:all-files'
This works even where there is no special pattern: _files matches This works even where there is no special pattern: _files matches
all files using the pattern `*' at the first step and stops when it all files using the pattern `*' at the first step and stops when it
sees this pattern. Note also it will never try a pattern more sees this pattern. Note also it will never try a pattern more
than once for a single completion attempt. than once for a single completion attempt.
To separate directories into a separate group from the files but
still complete them at the first attempt, a description needs to
be given. Note that directories need to be explicitly excluded
from the globbed-files because `*' will match directories. For
grouping, it is also necessary to set the group-name style.
zstyle ':completion:*' file-patterns \
'%p(^-/):globbed-files *(-/):directories:location'
During the execution of completion functions, the EXTENDED_GLOB During the execution of completion functions, the EXTENDED_GLOB
option is in effect, so the characters `#', `~' and `^' have option is in effect, so the characters `#', `~' and `^' have
special meanings in the patterns. special meanings in the patterns.
file-sort file-sort
The standard filename completion function uses this style without The standard filename completion function uses this style without
a tag to determine in which order the names should be listed; menu a tag to determine in which order the names should be listed; menu
completion will cycle through them in the same order. The possible completion will cycle through them in the same order. The possible
values are: `size' to sort by the size of the file; `links' to values are: `size' to sort by the size of the file; `links' to
sort by the number of links to the file; `modification' (or `time' sort by the number of links to the file; `modification' (or `time'
skipping to change at line 3868 skipping to change at line 3866
use when no matches could be generated at all. In this case the use when no matches could be generated at all. In this case the
`%d' is replaced with the descriptions for the matches that were `%d' is replaced with the descriptions for the matches that were
expected separated by spaces. The sequence `%D' is replaced with expected separated by spaces. The sequence `%D' is replaced with
the same descriptions separated by newlines. the same descriptions separated by newlines.
It is possible to use printf-style field width specifiers with `%d' It is possible to use printf-style field width specifiers with `%d'
and similar escape sequences. This is handled by the zformat and similar escape sequences. This is handled by the zformat
builtin command from the zsh/zutil module, see *Note The zsh/zutil builtin command from the zsh/zutil module, see *Note The zsh/zutil
Module::. Module::.
gain-privileges
If set to true, this style enables the use of commands like sudo
or doas to gain extra privileges when retrieving information for
completion. This is only done when a command such as sudo appears
on the command-line. To force the use of, e.g. sudo or to override
any prefix that might be added due to gain-privileges, the command
style can be used with a value that begins with a hyphen.
glob glob
This is used by the _expand completer. If it is set to `true' This is used by the _expand completer. If it is set to `true'
(the default), globbing will be attempted on the words resulting (the default), globbing will be attempted on the words resulting
from a previous substitution (see the substitute style) or else from a previous substitution (see the substitute style) or else
the original string from the line. the original string from the line.
global global
If this is set to `true' (the default), the _expand_alias If this is set to `true' (the default), the _expand_alias
completer and bindable command will try to expand global aliases. completer and bindable command will try to expand global aliases.
skipping to change at line 3904 skipping to change at line 3910
If the name given is the empty string the name of the tag for the If the name given is the empty string the name of the tag for the
matches will be used as the name of the group. So, to have all matches will be used as the name of the group. So, to have all
different types of matches displayed separately, one can just set: different types of matches displayed separately, one can just set:
zstyle ':completion:*' group-name '' zstyle ':completion:*' group-name ''
All matches for which no group name is defined will be put in a All matches for which no group name is defined will be put in a
group named -default-. group named -default-.
To display the group name in the output, see the format style
(q.v.) under the descriptions tag.
group-order group-order
This style is additional to the group-name style to specify the This style is additional to the group-name style to specify the
order for display of the groups defined by that style (compare order for display of the groups defined by that style (compare
tag-order, which determines which completions appear at all). The tag-order, which determines which completions appear at all). The
groups named are shown in the given order; any other groups are groups named are shown in the given order; any other groups are
shown in the order defined by the completion function. shown in the order defined by the completion function.
For example, to have names of builtin commands, shell functions and For example, to have names of builtin commands, shell functions and
external commands appear in that order when completing in command external commands appear in that order when completing in command
position: position:
skipping to change at line 3996 skipping to change at line 4005
line contains the substring `../'. line contains the substring `../'.
directory directory
Ignore the specified directories only when names of Ignore the specified directories only when names of
directories are completed, not when completing names of files. directories are completed, not when completing names of files.
Excluded values act in a similar fashion to values of the Excluded values act in a similar fashion to values of the
ignored-patterns style, so they can be restored to consideration by ignored-patterns style, so they can be restored to consideration by
the _ignored completer. the _ignored completer.
extra-verbose
If set, the completion listing is more verbose at the cost of a
probable decrease in completion speed. Completion performance
will suffer if this style is set to `true'.
ignored-patterns ignored-patterns
A list of patterns; any trial completion matching one of the A list of patterns; any trial completion matching one of the
patterns will be excluded from consideration. The _ignored patterns will be excluded from consideration. The _ignored
completer can appear in the list of completers to restore the completer can appear in the list of completers to restore the
ignored matches. This is a more configurable version of the shell ignored matches. This is a more configurable version of the shell
parameter $fignore. parameter $fignore.
Note that the EXTENDED_GLOB option is set during the execution of Note that the EXTENDED_GLOB option is set during the execution of
completion functions, so the characters `#', `~' and `^' have completion functions, so the characters `#', `~' and `^' have
special meanings in the patterns. special meanings in the patterns.
skipping to change at line 4033 skipping to change at line 4037
set of possible IDs, and menu completion will be started to cycle set of possible IDs, and menu completion will be started to cycle
through them. through them.
If the value of the style is `single', the shell will wait until If the value of the style is `single', the shell will wait until
the user has typed enough to make the command unique before the user has typed enough to make the command unique before
converting the name to an ID; attempts at completion will be converting the name to an ID; attempts at completion will be
unsuccessful until that point. If the value is any other string, unsuccessful until that point. If the value is any other string,
menu completion will be started when the string typed by the user menu completion will be started when the string typed by the user
is longer than the common prefix to the corresponding IDs. is longer than the common prefix to the corresponding IDs.
insert-sections
This style is used with tags of the form `manuals.X' when
completing names of manual pages. If set and the X in the tag name
matches the section number of the page being completed, the
section number is inserted along with the page name. For example,
given
zstyle ':completion:*:manuals.*' insert-sections true
man ssh_<TAB> may be completed to man 5 ssh_config.
The value may also be set to one of `prepend', or `suffix'.
`prepend' behaves the same as `true' as in the above example, while
`suffix' would complete man ssh_<TAB> as man ssh_config.5.
This is especially useful in conjunction with separate-sections, as
it ensures that the page requested of man corresponds to the one
displayed in the completion listing when there are multiple pages
with the same name (e.g., printf(1) and printf(3)).
The default for this style is `false'.
insert-tab insert-tab
If this is set to `true', the completion system will insert a TAB If this is set to `true', the completion system will insert a TAB
character (assuming that was used to start completion) instead of character (assuming that was used to start completion) instead of
performing completion when there is no non-blank character to the performing completion when there is no non-blank character to the
left of the cursor. If it is set to `false', completion will be left of the cursor. If it is set to `false', completion will be
done even there. done even there.
The value may also contain the substrings `pending' or The value may also contain the substrings `pending' or
`pending=VAL'. In this case, the typed character will be inserted `pending=VAL'. In this case, the typed character will be inserted
instead of starting completion when there is unprocessed input instead of starting completion when there is unprocessed input
skipping to change at line 4070 skipping to change at line 4096
In the case of the _approximate completer, the completer field in In the case of the _approximate completer, the completer field in
the context will already have been set to one of correct-NUM or the context will already have been set to one of correct-NUM or
approximate-NUM, where NUM is the number of errors that were approximate-NUM, where NUM is the number of errors that were
accepted. accepted.
In the case of the _match completer, the style may also be set to In the case of the _match completer, the style may also be set to
the string `pattern'. Then the pattern on the line is left the string `pattern'. Then the pattern on the line is left
unchanged if it does not match unambiguously. unchanged if it does not match unambiguously.
gain-privileges
If set to true, this style enables the use of commands like sudo
or doas to gain extra privileges when retrieving information for
completion. This is only done when a command such as sudo appears
on the command-line. To force the use of, e.g. sudo or to override
any prefix that might be added due to gain-privileges, the command
style can be used with a value that begins with a hyphen.
keep-prefix keep-prefix
This style is used by the _expand completer. If it is `true', the This style is used by the _expand completer. If it is `true', the
completer will try to keep a prefix containing a tilde or parameter completer will try to keep a prefix containing a tilde or parameter
expansion. Hence, for example, the string `~/f*' would be expansion. Hence, for example, the string `~/f*' would be
expanded to `~/foo' instead of `/home/user/foo'. If the style is expanded to `~/foo' instead of `/home/user/foo'. If the style is
set to `changed' (the default), the prefix will only be left set to `changed' (the default), the prefix will only be left
unchanged if there were other changes between the expanded words unchanged if there were other changes between the expanded words
and the original word from the command line. Any other value and the original word from the command line. Any other value
forces the prefix to be expanded unconditionally. forces the prefix to be expanded unconditionally.
The behaviour of _expand when this style is `true' is to cause The behaviour of _expand when this style is `true' is to cause
_expand to give up when a single expansion with the restored _expand to give up when a single expansion with the restored
prefix is the same as the original; hence any remaining completers prefix is the same as the original; hence any remaining completers
may be called. may be called.
known-hosts-files
This style should contain a list of files to search for host names
and (if the use-ip style is set) IP addresses in a format
compatible with ssh known_hosts files. If it is not set, the files
/etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts are used.
last-prompt last-prompt
This is a more flexible form of the ALWAYS_LAST_PROMPT option. If This is a more flexible form of the ALWAYS_LAST_PROMPT option. If
it is `true', the completion system will try to return the cursor it is `true', the completion system will try to return the cursor
to the previous command line after displaying a completion list. to the previous command line after displaying a completion list.
It is tested for all tags valid for the current completion, then It is tested for all tags valid for the current completion, then
the default tag. The cursor will be moved back to the previous the default tag. The cursor will be moved back to the previous
line if this style is `true' for all types of match. Note that line if this style is `true' for all types of match. Note that
unlike the ALWAYS_LAST_PROMPT option this is independent of the unlike the ALWAYS_LAST_PROMPT option this is independent of the
numeric argument. numeric argument.
known-hosts-files
This style should contain a list of files to search for host names
and (if the use-ip style is set) IP addresses in a format
compatible with ssh known_hosts files. If it is not set, the files
/etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts are used.
list list
This style is used by the _history_complete_word bindable command. This style is used by the _history_complete_word bindable command.
If it is set to `true' it has no effect. If it is set to `false' If it is set to `true' it has no effect. If it is set to `false'
matches will not be listed. This overrides the setting of the matches will not be listed. This overrides the setting of the
options controlling listing behaviour, in particular AUTO_LIST. options controlling listing behaviour, in particular AUTO_LIST.
The context always starts with `:completion:history-words'. The context always starts with `:completion:history-words'.
list-colors list-colors
If the zsh/complist module is loaded, this style can be used to set If the zsh/complist module is loaded, this style can be used to set
color specifications. This mechanism replaces the use of the color specifications. This mechanism replaces the use of the
skipping to change at line 4143 skipping to change at line 4161
It is possible to use any color specifications already set up for It is possible to use any color specifications already set up for
the GNU version of the ls command: the GNU version of the ls command:
zstyle ':completion:*:default' list-colors \ zstyle ':completion:*:default' list-colors \
${(s.:.)LS_COLORS} ${(s.:.)LS_COLORS}
The default colors are the same as for the GNU ls command and can The default colors are the same as for the GNU ls command and can
be obtained by setting the style to an empty string (i.e. ''). be obtained by setting the style to an empty string (i.e. '').
list-dirs-first list-dirs-first
This is used by file completion. If set, directories to be This is used by file completion and corresponds to a particular
completed are listed separately from and before completion for setting of the file-patterns style. If set, the default
other files, regardless of tag ordering. In addition, the tag directories to be completed are listed separately from and before
other-files is used in place of all-files for the remaining files, completion for other files.
to indicate that no directories are presented with that tag.
list-grouped list-grouped
If this style is `true' (the default), the completion system will If this style is `true' (the default), the completion system will
try to make certain completion listings more compact by grouping try to make certain completion listings more compact by grouping
matches. For example, options for commands that have the same matches. For example, options for commands that have the same
description (shown when the verbose style is set to `true') will description (shown when the verbose style is set to `true') will
appear as a single entry. However, menu selection can be used to appear as a single entry. However, menu selection can be used to
cycle through all the matches. cycle through all the matches.
list-packed list-packed
skipping to change at line 4195 skipping to change at line 4212
(or, with a numeric argument, some other) width. (or, with a numeric argument, some other) width.
After deleting this prompt the variable LISTPROMPT should be unset After deleting this prompt the variable LISTPROMPT should be unset
for the removal to take effect. for the removal to take effect.
list-rows-first list-rows-first
This style is tested in the same way as the list-packed style and This style is tested in the same way as the list-packed style and
determines whether matches are to be listed in a rows-first determines whether matches are to be listed in a rows-first
fashion as if the LIST_ROWS_FIRST option were set. fashion as if the LIST_ROWS_FIRST option were set.
list-separator
The value of this style is used in completion listing to separate
the string to complete from a description when possible (e.g. when
completing options). It defaults to `--' (two hyphens).
list-suffixes list-suffixes
This style is used by the function that completes filenames. If This style is used by the function that completes filenames. If
it is `true', and completion is attempted on a string containing it is `true', and completion is attempted on a string containing
multiple partially typed pathname components, all ambiguous multiple partially typed pathname components, all ambiguous
components will be shown. Otherwise, completion stops at the components will be shown. Otherwise, completion stops at the
first ambiguous component. first ambiguous component.
list-separator
The value of this style is used in completion listing to separate
the string to complete from a description when possible (e.g. when
completing options). It defaults to `--' (two hyphens).
local local
This is for use with functions that complete URLs for which the This is for use with functions that complete URLs for which the
corresponding files are available directly from the file system. corresponding files are available directly from the file system.
Its value should consist of three strings: a hostname, the path to Its value should consist of three strings: a hostname, the path to
the default web pages for the server, and the directory name used the default web pages for the server, and the directory name used
by a user placing web pages within their home area. by a user placing web pages within their home area.
For example: For example:
zstyle ':completion:*' local toast \ zstyle ':completion:*' local toast \
skipping to change at line 4609 skipping to change at line 4626
completion by prepending the word on the command line with each completion by prepending the word on the command line with each
directory in the expansion of **/*(/) in turn. Typically the directory in the expansion of **/*(/) in turn. Typically the
elements of the style will be set to restrict the number of elements of the style will be set to restrict the number of
directories beneath the current one to a manageable number, for directories beneath the current one to a manageable number, for
example `*/.git/*'. example `*/.git/*'.
For example, For example,
zstyle ':completion:*' recursive-files '*/zsh/*' zstyle ':completion:*' recursive-files '*/zsh/*'
If the current directory is /home/pws/zsh/Src, then zle_tr_TAB_ If the current directory is /home/pws/zsh/Src, then zle_tr<TAB>
can be completed to Zle/zle_tricky.c. can be completed to Zle/zle_tricky.c.
regular regular
This style is used by the _expand_alias completer and bindable This style is used by the _expand_alias completer and bindable
command. If set to `true' (the default), regular aliases will be command. If set to `true' (the default), regular aliases will be
expanded but only in command position. If it is set to `false', expanded but only in command position. If it is set to `false',
regular aliases will never be expanded. If it is set to `always', regular aliases will never be expanded. If it is set to `always',
regular aliases will be expanded even if not in command position. regular aliases will be expanded even if not in command position.
rehash rehash
skipping to change at line 4660 skipping to change at line 4677
style above) when the completion list does not fit on the screen style above) when the completion list does not fit on the screen
as a whole. If the value is `0' (zero), the list is scrolled by as a whole. If the value is `0' (zero), the list is scrolled by
half-screenfuls; if it is a positive integer, the list is scrolled half-screenfuls; if it is a positive integer, the list is scrolled
by the given number of lines; if it is a negative number, the list by the given number of lines; if it is a negative number, the list
is scrolled by a screenful minus the absolute value of the given is scrolled by a screenful minus the absolute value of the given
number of lines. The default is to scroll by single lines. number of lines. The default is to scroll by single lines.
separate-sections separate-sections
This style is used with the manuals tag when completing names of This style is used with the manuals tag when completing names of
manual pages. If it is `true', entries for different sections are manual pages. If it is `true', entries for different sections are
added separately using tag names of the form `manual.X', where X added separately using tag names of the form `manuals.X', where X
is the section number. When the group-name style is also in is the section number. When the group-name style is also in
effect, pages from different sections will appear separately. effect, pages from different sections will appear separately.
This style is also used similarly with the words style when This style is also used similarly with the words style when
completing words for the dict command. It allows words from completing words for the dict command. It allows words from
different dictionary databases to be added separately. The different dictionary databases to be added separately. See also
default for this style is `false'. insert-sections.
The default for this style is `false'.
show-ambiguity show-ambiguity
If the zsh/complist module is loaded, this style can be used to If the zsh/complist module is loaded, this style can be used to
highlight the first ambiguous character in completion lists. The highlight the first ambiguous character in completion lists. The
value is either a color indication such as those supported by the value is either a color indication such as those supported by the
list-colors style or, with a value of `true', a default of list-colors style or, with a value of `true', a default of
underlining is selected. The highlighting is only applied if the underlining is selected. The highlighting is only applied if the
completion display strings correspond to the actual matches. completion display strings correspond to the actual matches.
show-completer show-completer
 End of changes. 69 change blocks. 
424 lines changed or deleted 443 lines changed or added
To the Data Files section of the zsh (doc) source changes report or the top of this page
Mainly generated by pkgdiff using rfcdiff
Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)