diff options
Diffstat (limited to 'Doc/zshcompwid.1')
| -rw-r--r-- | Doc/zshcompwid.1 | 1271 |
1 files changed, 1271 insertions, 0 deletions
diff --git a/Doc/zshcompwid.1 b/Doc/zshcompwid.1 new file mode 100644 index 000000000..5caadc23d --- /dev/null +++ b/Doc/zshcompwid.1 @@ -0,0 +1,1271 @@ +.TH "ZSHCOMPWID" "1" "February 14, 2020" "zsh 5\&.8" +.SH "NAME" +zshcompwid \- zsh completion widgets +.\" Yodl file: Zsh/compwid.yo +.SH "DESCRIPTION" +The shell\&'s programmable completion mechanism can be manipulated in two +ways; here the low\-level features supporting the newer, function\-based +mechanism are defined\&. A complete set of shell functions based on these +features is described in +\fIzshcompsys\fP(1), +and users with no interest in adding to that system (or, potentially, +writing their own \-\- see dictionary entry for `hubris\&') should skip +the current section\&. The older system based on the \fBcompctl\fP builtin +command is described in +\fIzshcompctl\fP(1)\&. +.PP +Completion widgets are defined by the \fB\-C\fP option to the \fBzle\fP +builtin command provided by the \fBzsh/zle\fP module (see +\fIzshzle\fP(1))\&. For example, +.PP +.RS +.nf +\fBzle \-C complete expand\-or\-complete completer\fP +.fi +.RE +.PP +defines a widget named `\fBcomplete\fP\&'\&. The second argument is the name +of any of the builtin widgets that handle completions: +\fBcomplete\-word\fP, \fBexpand\-or\-complete\fP, +\fBexpand\-or\-complete\-prefix\fP, \fBmenu\-complete\fP, +\fBmenu\-expand\-or\-complete\fP, \fBreverse\-menu\-complete\fP, +\fBlist\-choices\fP, or \fBdelete\-char\-or\-list\fP\&. Note that this will still +work even if the widget in question has been re\-bound\&. +.PP +When this newly defined widget is bound to a key +using the \fBbindkey\fP builtin command defined in the \fBzsh/zle\fP module +(see \fIzshzle\fP(1)), typing that key will call the shell function `\fBcompleter\fP\&'\&. This +function is responsible for generating the possible matches using the +builtins described below\&. As with other ZLE widgets, the function is +called with its standard input closed\&. +.PP +Once the function returns, the completion code takes over control again +and treats the matches in the same manner as the specified builtin +widget, in this case \fBexpand\-or\-complete\fP\&. +.PP +.PP +.SH "COMPLETION SPECIAL PARAMETERS" +.PP +The parameters \fBZLE_REMOVE_SUFFIX_CHARS\fP and \fBZLE_SPACE_SUFFIX_CHARS\fP +are used by the completion mechanism, but are not special\&. See +\fIParameters Used By The Shell\fP in \fIzshparam\fP(1)\&. +.PP +Inside completion widgets, and any functions called from them, some +parameters have special meaning; outside these functions they are not +special to the shell in any way\&. These parameters are used to pass +information between the completion code and the completion widget\&. Some of +the builtin commands and the condition codes use or change the current +values of these parameters\&. Any existing values will be hidden during +execution of completion widgets; except for \fBcompstate\fP, the parameters +are reset on each function exit (including nested function calls from +within the completion widget) to the values they had when the function was +entered\&. +.PP +.PD 0 +.TP +.PD +\fBCURRENT\fP +This is the number of the current word, i\&.e\&. the word the cursor is +currently on in the \fBwords\fP array\&. Note that this value is only +correct if the \fBksharrays\fP option is not set\&. +.TP +\fBIPREFIX\fP +Initially this will be set to the empty string\&. This parameter functions +like \fBPREFIX\fP; it contains a string which precedes the one in \fBPREFIX\fP +and is not considered part of the list of matches\&. Typically, a string is +transferred from the beginning of \fBPREFIX\fP to the end of \fBIPREFIX\fP, for +example: +.RS +.PP +.RS +.nf +\fBIPREFIX=${PREFIX%%\e=*}= +PREFIX=${PREFIX#*=}\fP +.fi +.RE +.PP +causes the part of the prefix up to and including the first equal sign not +to be treated as part of a matched string\&. This can be done automatically +by the \fBcompset\fP builtin, see below\&. +.RE +.TP +\fBISUFFIX\fP +As \fBIPREFIX\fP, but for a suffix that should not be considered part +of the matches; note that the \fBISUFFIX\fP string follows the \fBSUFFIX\fP +string\&. +.TP +\fBPREFIX\fP +Initially this will be set to the part of the current word from the +beginning of the word up to the position of the cursor; it may be altered +to give a common prefix for all matches\&. +.TP +\fBQIPREFIX\fP +This parameter is read\-only and contains the quoted string up to the +word being completed\&. E\&.g\&. when completing `\fB"foo\fP\&', this parameter +contains the double quote\&. If the \fB\-q\fP option of \fBcompset\fP is used +(see below), and the original string was `\fB"foo bar\fP\&' with the +cursor on the `\fBbar\fP\&', this parameter contains `\fB"foo \fP'\&. +.TP +\fBQISUFFIX\fP +Like \fBQIPREFIX\fP, but containing the suffix\&. +.TP +\fBSUFFIX\fP +Initially this will be set to the part of the current word from the +cursor position to the end; it may be altered to give a common suffix for +all matches\&. It is most useful when the option \fBCOMPLETE_IN_WORD\fP is +set, as otherwise the whole word on the command line is treated as a +prefix\&. +.TP +\fBcompstate\fP +This is an associative array with various keys and values that the +completion code uses to exchange information with the completion widget\&. +The keys are: +.RS +.PP +.PD 0 +.TP +.PD +\fBall_quotes\fP +The \fB\-q\fP option of the \fBcompset\fP builtin command (see below) +allows a quoted string to be broken into separate words; if the cursor is +on one of those words, that word will be completed, possibly invoking +`\fBcompset \-q\fP\&' recursively\&. With this key it is possible to test the +types of quoted strings which are currently broken into parts in this +fashion\&. Its value contains one character for each quoting level\&. The +characters are a single quote or a double quote for strings quoted with +these characters, a dollars sign for strings quoted with +\fB$\&'\fP\fI\&.\&.\&.\fP\fB'\fP and a backslash for strings not starting with a +quote character\&. The first character in the value always corresponds to the +innermost quoting level\&. +.TP +\fBcontext\fP +This will be set by the completion code to the overall context +in which completion is attempted\&. Possible values are: +.RS +.PP +.PD 0 +.TP +.PD +\fBarray_value\fP +when completing inside the value of an array parameter assignment; in +this case the \fBwords\fP array contains the words inside the parentheses\&. +.TP +\fBbrace_parameter\fP +when completing the name of a parameter in a parameter expansion beginning +with \fB${\fP\&. This context will also be set when completing parameter +flags following \fB${(\fP; the full command line argument is presented +and the handler must test the value to be completed to ascertain that +this is the case\&. +.TP +\fBassign_parameter\fP +when completing the name of a parameter in a parameter assignment\&. +.TP +\fBcommand\fP +when completing for a normal command (either in command position or for +an argument of the command)\&. +.TP +\fBcondition\fP +when completing inside a `\fB[[\fP\&.\&.\&.\fB]]\fP\&' conditional expression; in +this case the \fBwords\fP array contains only the words inside the +conditional expression\&. +.TP +\fBmath\fP +when completing in a mathematical environment such as a +`\fB((\fP\&.\&.\&.\fB))\fP\&' construct\&. +.TP +\fBparameter\fP +when completing the name of a parameter in a parameter expansion beginning +with \fB$\fP but not \fB${\fP\&. +.TP +\fBredirect\fP +when completing after a redirection operator\&. +.TP +\fBsubscript\fP +when completing inside a parameter subscript\&. +.TP +\fBvalue\fP +when completing the value of a parameter assignment\&. +.RE +.TP +\fBexact\fP +Controls the behaviour when the \fBREC_EXACT\fP option is set\&. It will be +set to \fBaccept\fP if an exact match would be accepted, and will be unset +otherwise\&. +.RS +.PP +If it was set when at least one match equal to the string on the line +was generated, the match is accepted\&. +.RE +.TP +\fBexact_string\fP +The string of an exact match if one was found, otherwise unset\&. +.TP +\fBignored\fP +The number of words that were ignored because they matched one of the +patterns given with the \fB\-F\fP option to the \fBcompadd\fP builtin +command\&. +.TP +\fBinsert\fP +This controls the manner in which a match is inserted into the command +line\&. On entry to the widget function, if it is unset the command line is +not to be changed; if set to \fBunambiguous\fP, any prefix common to all +matches is to be inserted; if set to \fBautomenu\-unambiguous\fP, the +common prefix is to be inserted and the next invocation of the +completion code may start menu completion (due to the \fBAUTO_MENU\fP +option being set); if set to \fBmenu\fP or \fBautomenu\fP menu completion +will be started for the matches currently generated (in the +latter case this will happen because the \fBAUTO_MENU\fP is set)\&. The +value may also contain the string `\fBtab\fP\&' when the completion code +would normally not really do completion, but only insert the TAB +character\&. +.RS +.PP +On exit it may be set to any of the values above (where setting it to +the empty string is the same as unsetting it), or to a number, in which +case the match whose number is given will be inserted into the command line\&. +Negative numbers count backward from the last match (with `\fB\-1\fP\&' +selecting the last match) and out\-of\-range values are wrapped +around, so that a value of zero selects the last match and a value +one more than the maximum selects the first\&. Unless the value of this +key ends in a space, the match is inserted as in a menu completion, +i\&.e\&. without automatically appending a space\&. +.PP +Both \fBmenu\fP and \fBautomenu\fP may also specify the number of the +match to insert, given after a colon\&. For example, `\fBmenu:2\fP\&' says +to start menu completion, beginning with the second match\&. +.PP +Note that a value containing the substring `\fBtab\fP\&' makes the +matches generated be ignored and only the TAB be inserted\&. +.PP +Finally, it may also be set to \fBall\fP, which makes all matches +generated be inserted into the line\&. +.RE +.TP +\fBinsert_positions\fP +When the completion system inserts an unambiguous string into the +line, there may be multiple places where characters are missing or +where the character inserted differs from at least one match\&. The +value of this key contains a colon separated list of all these +positions, as indexes into the command line\&. +.TP +\fBlast_prompt\fP +If this is set to a non\-empty string for every match added, the +completion code will move the cursor back to the previous prompt after +the list of completions has been displayed\&. Initially this is set or +unset according to the \fBALWAYS_LAST_PROMPT\fP option\&. +.TP +\fBlist\fP +This controls whether or how the list of matches will be displayed\&. If it +is unset or empty they will never be listed; if its value begins with +\fBlist\fP, they will always be listed; if it begins with \fBautolist\fP +or \fBambiguous\fP, they will be listed when the \fBAUTO_LIST\fP or +\fBLIST_AMBIGUOUS\fP options respectively would normally cause them to +be\&. +.RS +.PP +If the substring \fBforce\fP appears in the value, this makes the +list be shown even if there is only one match\&. Normally, the list +would be shown only if there are at least two matches\&. +.PP +The value contains the substring \fBpacked\fP if the \fBLIST_PACKED\fP +option is set\&. If this substring is given for all matches added to a +group, this group will show the \fBLIST_PACKED\fP behavior\&. The same is +done for the \fBLIST_ROWS_FIRST\fP option with the substring \fBrows\fP\&. +.PP +Finally, if the value contains the string \fBexplanations\fP, only the +explanation strings, if any, will be listed and if it contains +\fBmessages\fP, only the messages (added with the \fB\-x\fP option of +\fBcompadd\fP) will be listed\&. If it contains both \fBexplanations\fP and +\fBmessages\fP both kinds of explanation strings will be listed\&. It +will be set appropriately on entry to a completion widget and may be +changed there\&. +.RE +.TP +\fBlist_lines\fP +This gives the number of lines that are needed to display the full +list of completions\&. Note that to calculate the total number of lines +to display you need to add the number of lines needed for the command +line to this value, this is available as the value of the \fBBUFFERLINES\fP +special parameter\&. +.TP +\fBlist_max\fP +Initially this is set to the value of the \fBLISTMAX\fP parameter\&. +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 \fBLISTMAX\fP\&. +.TP +\fBnmatches\fP +The number of matches generated and accepted by the completion code so +far\&. +.TP +\fBold_insert\fP +On entry to the widget this will be set to the number of the match of +an old list of completions that is currently inserted into the command +line\&. If no match has been inserted, this is unset\&. +.RS +.PP +As with \fBold_list\fP, the value of this key will only be used if it is the +string \fBkeep\fP\&. If it was set to this value by the widget and there was an +old match inserted into the command line, this match will be kept and if +the value of the \fBinsert\fP key specifies that another match should be +inserted, this will be inserted after the old one\&. +.RE +.TP +\fBold_list\fP +This is set to \fByes\fP if there is still a valid list of completions +from a previous completion at the time the widget is invoked\&. This will +usually be the case if and only if the previous editing operation was a +completion widget or one of the builtin completion functions\&. If there is a +valid list and it is also currently shown on the screen, the value of this +key is \fBshown\fP\&. +.RS +.PP +After the widget has exited the value of this key is only used if it +was set to \fBkeep\fP\&. In this case the completion code will continue +to use this old list\&. If the widget generated new matches, they will +not be used\&. +.RE +.TP +\fBparameter\fP +The name of the parameter when completing in a subscript or in the +value of a parameter assignment\&. +.TP +\fBpattern_insert\fP +Normally this is set to \fBmenu\fP, which specifies that menu completion will +be used whenever a set of matches was generated using pattern matching\&. If +it is set to any other non\-empty string by the user and menu completion is +not selected by other option settings, the code will instead insert any +common prefix for the generated matches as with normal completion\&. +.TP +\fBpattern_match\fP +Locally controls the behaviour given by the \fBGLOB_COMPLETE\fP option\&. +Initially it is set to `\fB*\fP\&' if and only if the option is set\&. +The completion widget may set it to this value, to an empty string +(which has the same effect as unsetting it), or to any +other non\-empty string\&. If it is non\-empty, unquoted metacharacters on the +command line will be treated as patterns; if it is `\fB*\fP\&', then +additionally a wildcard `\fB*\fP\&' is assumed at the cursor position; if +it is empty or unset, metacharacters will be treated literally\&. +.RS +.PP +Note that the matcher specifications given to the \fBcompadd\fP builtin +command are not used if this is set to a non\-empty string\&. +.RE +.TP +\fBquote\fP +When completing inside quotes, this contains the quotation character +(i\&.e\&. either a single quote, a double quote, or a backtick)\&. Otherwise it +is unset\&. +.TP +\fBquoting\fP +When completing inside single quotes, this is set to the string +\fBsingle\fP; inside double quotes, the string +\fBdouble\fP; inside backticks, the string \fBbacktick\fP\&. +Otherwise it is unset\&. +.TP +\fBredirect\fP +The redirection operator when completing in a redirection position, +i\&.e\&. one of \fB<\fP, \fB>\fP, etc\&. +.TP +\fBrestore\fP +This is set to \fBauto\fP before a function is entered, which forces the +special parameters mentioned above (\fBwords\fP, \fBCURRENT\fP, \fBPREFIX\fP, +\fBIPREFIX\fP, \fBSUFFIX\fP, and \fBISUFFIX\fP) to be restored to their +previous values when the function exits\&. If a function unsets it or +sets it to any other string, they will not be restored\&. +.TP +\fBto_end\fP +Specifies the occasions on which the cursor is moved to the end of a string +when a match is inserted\&. On entry to a widget function, it may be +\fBsingle\fP if this will happen when a single unambiguous match was inserted +or \fBmatch\fP if it will happen any time a match is inserted (for example, +by menu completion; this is likely to be the effect of the \fBALWAYS_TO_END\fP +option)\&. +.RS +.PP +On exit, it may be set to \fBsingle\fP as above\&. It may also be set to +\fBalways\fP, or to the empty string or unset; in those cases the cursor will +be moved to the end of the string always or never respectively\&. Any +other string is treated as \fBmatch\fP\&. +.RE +.TP +\fBunambiguous\fP +This key is read\-only and will always be set to the common (unambiguous) +prefix the completion code has generated for all matches added so far\&. +.TP +\fBunambiguous_cursor\fP +This gives the position the cursor would be placed at if the +common prefix in the \fBunambiguous\fP key were inserted, relative to +the value of that key\&. The cursor would be placed before the character +whose index is given by this key\&. +.TP +\fBunambiguous_positions\fP +This contains all positions where characters in the unambiguous string +are missing or where the character inserted differs from at least one +of the matches\&. The positions are given as indexes into the string +given by the value of the \fBunambiguous\fP key\&. +.TP +\fBvared\fP +If completion is called while editing a line using the \fBvared\fP +builtin, the value of this key is set to the name of the parameter +given as an argument to \fBvared\fP\&. This key is only set while a \fBvared\fP +command is active\&. +.RE +.TP +\fBwords\fP +This array contains the words present on the command line currently being +edited\&. +.PP +.SH "COMPLETION BUILTIN COMMANDS" +.PD 0 + +.TP +.PD 0 +\fBcompadd \fP[ \fB\-akqQfenUl12C\fP ] [ \fB\-F\fP \fIarray\fP ] +.TP +.PD 0 +\fB \fP[\fB\-P\fP \fIprefix\fP ] [ \fB\-S\fP \fIsuffix\fP ] +.TP +.PD 0 +\fB \fP[\fB\-p\fP \fIhidden\-prefix\fP ] [ \fB\-s\fP \fIhidden\-suffix\fP ] +.TP +.PD 0 +\fB \fP[\fB\-i\fP \fIignored\-prefix\fP ] [ \fB\-I\fP \fIignored\-suffix\fP ] +.TP +.PD 0 +\fB \fP[\fB\-W\fP \fIfile\-prefix\fP ] [ \fB\-d\fP \fIarray\fP ] +.TP +.PD 0 +\fB \fP[\fB\-J\fP \fIgroup\-name\fP ] [ \fB\-X\fP \fIexplanation\fP ] [ \fB\-x\fP \fImessage\fP ] +.TP +.PD 0 +\fB \fP[\fB\-V\fP \fIgroup\-name\fP ] [ \fB\-o\fP [ \fIorder\fP ] ] +.TP +.PD 0 +\fB \fP[\fB\-r\fP \fIremove\-chars\fP ] [ \fB\-R\fP \fIremove\-func\fP ] +.TP +.PD 0 +\fB \fP[\fB\-D\fP \fIarray\fP ] [ \fB\-O\fP \fIarray\fP ] [ \fB\-A\fP \fIarray\fP ] +.TP +.PD 0 +\fB \fP[\fB\-E\fP \fInumber\fP ] +.TP +.PD +\fB \fP[\fB\-M\fP \fImatch\-spec\fP ] [ \fB\-\fP\fB\-\fP ] [ \fIwords\fP \&.\&.\&. ] +.RS +.PP +This builtin command can be used to add matches directly and control +all the information the completion code stores with each possible +match\&. The return status is zero if at least one match was added and +non\-zero if no matches were added\&. +.PP +The completion code breaks the string to complete into seven fields in +the order: +.PP +.RS +.nf +\fI<ipre><apre><hpre><word><hsuf><asuf><isuf>\fP +.fi +.RE +.PP +The first field +is an ignored prefix taken from the command line, the contents of the +\fBIPREFIX\fP parameter plus the string given with the \fB\-i\fP +option\&. With the \fB\-U\fP option, only the string from the \fB\-i\fP +option is used\&. The field \fI<apre>\fP is an optional prefix string +given with the \fB\-P\fP option\&. The \fI<hpre>\fP field is a string +that is considered part of the match but that should not be shown when +listing completions, given with the \fB\-p\fP option; for example, +functions that do filename generation might specify +a common path prefix this way\&. \fI<word>\fP is the part of the match that +should appear in the list of completions, i\&.e\&. one of the \fIwords\fP given +at the end of the \fBcompadd\fP command line\&. The suffixes \fI<hsuf>\fP, +\fI<asuf>\fP and \fI<isuf>\fP correspond to the prefixes \fI<hpre>\fP, +\fI<apre>\fP and \fI<ipre>\fP and are given by the options \fB\-s\fP, \fB\-S\fP and +\fB\-I\fP, respectively\&. +.PP +The supported flags are: +.PP +.PD 0 +.TP +.PD +\fB\-P\fP \fIprefix\fP +This gives a string to be inserted before the given \fIwords\fP\&. The +string given is not considered as part of the match and any shell +metacharacters in it will not be quoted when the string is inserted\&. +.TP +\fB\-S\fP \fIsuffix\fP +Like \fB\-P\fP, but gives a string to be inserted after the match\&. +.TP +\fB\-p\fP \fIhidden\-prefix\fP +This gives a string that should be inserted into the command line before the +match but that should not appear in the list of matches\&. Unless the +\fB\-U\fP option is given, this string must be matched as part of the string +on the command line\&. +.TP +\fB\-s\fP \fIhidden\-suffix\fP +Like `\fB\-p\fP\&', but gives a string to insert after the match\&. +.TP +\fB\-i\fP \fIignored\-prefix\fP +This gives a string to insert into the command line just before any +string given with the `\fB\-P\fP\&' option\&. Without `\fB\-P\fP' the string is +inserted before the string given with `\fB\-p\fP\&' or directly before the +match\&. +.TP +\fB\-I\fP \fIignored\-suffix\fP +Like \fB\-i\fP, but gives an ignored suffix\&. +.TP +\fB\-a\fP +With this flag the \fIwords\fP are taken as names of arrays and the +possible matches are their values\&. If only some elements of the +arrays are needed, the \fIwords\fP may also contain subscripts, as in +`\fBfoo[2,\-1]\fP\&'\&. +.TP +\fB\-k\fP +With this flag the \fIwords\fP are taken as names of associative arrays +and the possible matches are their keys\&. As for \fB\-a\fP, the +\fIwords\fP may also contain subscripts, as in `\fBfoo[(R)*bar*]\fP\&'\&. +.TP +\fB\-d\fP \fIarray\fP +This adds per\-match display strings\&. The \fIarray\fP should contain one +element per \fIword\fP given\&. The completion code will then display the +first element instead of the first \fIword\fP, and so on\&. The +\fIarray\fP may be given as the name of an array parameter or directly +as a space\-separated list of words in parentheses\&. +.RS +.PP +If there are fewer display strings than \fIwords\fP, the leftover +\fIwords\fP will be displayed unchanged and if there are more display +strings than \fIwords\fP, the leftover display strings will be silently +ignored\&. +.RE +.TP +\fB\-l\fP +This option only has an effect if used together with the \fB\-d\fP +option\&. If it is given, the display strings are listed one per line, +not arrayed in columns\&. +.TP +\fB\-o\fP [ \fIorder\fP ] +This controls the order in which matches are sorted\&. \fIorder\fP is a +comma\-separated list comprising the following possible values\&. These values +can be abbreviated to their initial two or three characters\&. Note that the +order forms part of the group name space so matches with different orderings +will not be in the same group\&. +.RS +.PP +.PD 0 +.TP +.PD +\fBmatch\fP +If given, the order of the output is determined by the match strings; +otherwise it is determined by the display strings (i\&.e\&. the strings given +by the \fB\-d\fP option)\&. This is the default if `\fB\-o\fP\&' is specified but +the \fIorder\fP argument is omitted\&. +.TP +\fBnosort\fP +This specifies that the matches are pre\-sorted and their order should be +preserved\&. This value only makes sense alone and cannot be combined with any +others\&. +.TP +\fBnumeric\fP +If the matches include numbers, sort them numerically rather than +lexicographically\&. +.TP +\fBreverse\fP +Arrange the matches backwards by reversing the sort ordering\&. +.RE +.TP +\fB\-J\fP \fIgroup\-name\fP +Gives the name of the group of matches the words should be stored in\&. +.TP +\fB\-V\fP \fIgroup\-name\fP +Like \fB\-J\fP but naming an unsorted group\&. This option is identical to +the combination of \fB\-J\fP and \fB\-o nosort\fP\&. +.TP +\fB\-1\fP +If given together with the \fB\-V\fP option, makes +only consecutive duplicates in the group be removed\&. If combined with +the \fB\-J\fP option, this has no visible effect\&. Note that groups +with and without this flag are in different name spaces\&. +.TP +\fB\-2\fP +If given together with the \fB\-J\fP or \fB\-V\fP option, makes all +duplicates be kept\&. Again, groups with and without this flag are in +different name spaces\&. +.TP +\fB\-X\fP \fIexplanation\fP +The \fIexplanation\fP string will be printed with the list of matches, +above the group currently selected\&. +.RS +.PP +Within the \fIexplanation\fP, the following sequences may be used to +specify output attributes +as described in the section EXPANSION OF PROMPT SEQUENCES in +\fIzshmisc\fP(1): +`\fB%B\fP\&', `\fB%S\fP', `\fB%U\fP', `\fB%F\fP', `\fB%K\fP' and their lower case +counterparts, as well as `\fB%{\fP\&.\&.\&.\fB%}\fP\&'\&. `\fB%F\fP', `\fB%K\fP' and +`\fB%{\fP\&.\&.\&.\fB%}\fP\&' take arguments in the same form as prompt +expansion\&. (Note that the sequence `\fB%G\fP\&' is not available; an +argument to `\fB%{\fP\&' should be used instead\&.) The sequence `\fB%%\fP' +produces a literal `\fB%\fP\&'\&. +.PP +These sequences are most often employed by users when customising the +\fBformat\fP style +(see +\fIzshcompsys\fP(1)), +but they must also be taken into account when writing completion +functions, as passing descriptions with unescaped `\fB%\fP\&' characters +to utility functions such as \fB_arguments\fP and \fB_message\fP may +produce unexpected results\&. If arbitrary text is to be passed in a +description, it can be escaped using e\&.g\&. \fB${my_str//\e%/%%}\fP\&. +.RE +.TP +\fB\-x\fP \fImessage\fP +Like \fB\-X\fP, but the \fImessage\fP will be printed even if there are no +matches in the group\&. +.TP +\fB\-q\fP +The suffix given with \fB\-S\fP will be automatically removed if +the next character typed is a blank or does not insert anything, or if +the suffix consists of only one character and the next character typed +is the same character\&. +.TP +\fB\-r\fP \fIremove\-chars\fP +This is a more versatile form of the \fB\-q\fP option\&. +The suffix given with \fB\-S\fP or the slash automatically added after +completing directories will be automatically removed if +the next character typed inserts one of the characters given in the +\fIremove\-chars\fP\&. This string is parsed as a characters class and +understands the backslash sequences used by the \fBprint\fP command\&. For +example, `\fB\-r "a\-z\et"\fP\&' removes the suffix if the next character typed +inserts a lower case character or a TAB, and `\fB\-r "^0\-9"\fP\&' removes the +suffix if the next character typed inserts anything but a digit\&. One extra +backslash sequence is understood in this string: `\fB\e\-\fP\&' stands for +all characters that insert nothing\&. Thus `\fB\-S "=" \-q\fP\&' is the same +as `\fB\-S "=" \-r "= \et\en\e\-"\fP\&'\&. +.RS +.PP +This option may also be used without the \fB\-S\fP option; then any +automatically added space will be removed when one of the characters in the +list is typed\&. +.RE +.TP +\fB\-R\fP \fIremove\-func\fP +This is another form of the \fB\-r\fP option\&. When a suffix +has been inserted and the completion accepted, the function +\fIremove\-func\fP will be called after the next character typed\&. It is +passed the length of the suffix as an argument and can use the special +parameters available in ordinary (non\-completion) zle widgets (see +\fIzshzle\fP(1)) to analyse and modify the command line\&. +.TP +\fB\-f\fP +If this flag is given, all of the matches built from \fIwords\fP are +marked as being the names of files\&. They are not required to be actual +filenames, but if they are, and the option \fBLIST_TYPES\fP is set, the +characters describing the types of the files in the completion lists will +be shown\&. This also forces a slash to be added when the name of a +directory is completed\&. +.TP +\fB\-e\fP +This flag can be used to tell the completion code that the matches +added are parameter names for a parameter expansion\&. This will make +the \fBAUTO_PARAM_SLASH\fP and \fBAUTO_PARAM_KEYS\fP options be used for +the matches\&. +.TP +\fB\-W\fP \fIfile\-prefix\fP +This string is a pathname that will be +prepended to each of the matches formed by the given \fIwords\fP together +with any prefix specified by the \fB\-p\fP option to form a complete filename +for testing\&. Hence it is only useful if combined with the \fB\-f\fP flag, as +the tests will not otherwise be performed\&. +.TP +\fB\-F\fP \fIarray\fP +Specifies an array containing patterns\&. Words matching one of these +patterns are ignored, i\&.e\&. not considered to be possible matches\&. +.RS +.PP +The \fIarray\fP may be the name of an array parameter or a list of +literal patterns enclosed in parentheses and quoted, as in `\fB\-F "(*?\&.o +*?\&.h)"\fP\&'\&. If the name of an array is given, the elements of the array are +taken as the patterns\&. +.RE +.TP +\fB\-Q\fP +This flag instructs the completion +code not to quote any metacharacters in the words when inserting them +into the command line\&. +.TP +\fB\-M\fP \fImatch\-spec\fP +This gives local match specifications as described below in +the section `Completion Matching Control\&'\&. This option may be given more than once\&. +In this case all \fImatch\-spec\fPs given are concatenated with spaces +between them to form the specification string to use\&. +Note that they will only be used if the \fB\-U\fP option is not given\&. +.TP +\fB\-n\fP +Specifies that the words added are to be used as possible +matches, but are not to appear in the completion listing\&. +.TP +\fB\-U\fP +If this flag is given, all words given will be accepted and no matching +will be done by the completion code\&. Normally this is used in +functions that do the matching themselves\&. +.TP +\fB\-O\fP \fIarray\fP +If this option is given, the \fIwords\fP are \fInot\fP added to the set of +possible completions\&. Instead, matching is done as usual and all of the +\fIwords\fP given as arguments that match the string on the command line +will be stored in the array parameter whose name is given as \fIarray\fP\&. +.TP +\fB\-A\fP \fIarray\fP +As the \fB\-O\fP option, except that instead of those of the \fIwords\fP which +match being stored in \fIarray\fP, the strings generated internally by the +completion code are stored\&. For example, +with a matching specification of `\fB\-M "L:|no="\fP\&', the string `\fBnof\fP' +on the command line and the string `\fBfoo\fP\&' as one of the \fIwords\fP, this +option stores the string `\fBnofoo\fP\&' in the array, whereas the \fB\-O\fP +option stores the `\fBfoo\fP\&' originally given\&. +.TP +\fB\-D\fP \fIarray\fP +As with \fB\-O\fP, the \fIwords\fP are not added to the set of possible +completions\&. Instead, the completion code tests whether each \fIword\fP +in turn matches what is on the line\&. If the \fIn\fPth \fIword\fP does not +match, the \fIn\fPth element of the \fIarray\fP is removed\&. Elements +for which the corresponding \fIword\fP is matched are retained\&. +.TP +\fB\-C\fP +This option adds a special match which expands to all other matches +when inserted into the line, even those that are added after this +option is used\&. Together with the \fB\-d\fP option it is possible to +specify a string that should be displayed in the list for this special +match\&. If no string is given, it will be shown as a string containing +the strings that would be inserted for the other matches, truncated to +the width of the screen\&. +.TP +\fB\-E\fP \fInumber\fP +This option adds \fInumber\fP empty matches after the \fIwords\fP have +been added\&. An empty match takes up space in completion listings but +will never be inserted in the line and can\&'t be selected with menu +completion or menu selection\&. This makes empty matches only useful to +format completion lists and to make explanatory string be shown in +completion lists (since empty matches can be given display strings +with the \fB\-d\fP option)\&. And because all but one empty string would +otherwise be removed, this option implies the \fB\-V\fP and \fB\-2\fP +options (even if an explicit \fB\-J\fP option is given)\&. This can be +important to note as it affects the name space into which matches are +added\&. +.TP +.PD 0 +\fB\-\fP +.TP +.PD +\fB\-\fP\fB\-\fP +This flag ends the list of flags and options\&. All arguments after it +will be taken as the words to use as matches even if they begin with +hyphens\&. +.PP +Except for the \fB\-M\fP flag, if any of these flags is given more than +once, the first one (and its argument) will be used\&. +.RE +.TP +.PD 0 +\fBcompset \-p\fP \fInumber\fP +.TP +.PD 0 +\fBcompset \-P\fP [ \fInumber\fP ] \fIpattern\fP +.TP +.PD 0 +\fBcompset \-s\fP \fInumber\fP +.TP +.PD 0 +\fBcompset \-S\fP [ \fInumber\fP ] \fIpattern\fP +.TP +.PD 0 +\fBcompset \-n\fP \fIbegin\fP [ \fIend\fP ] +.TP +.PD 0 +\fBcompset \-N\fP \fIbeg\-pat\fP [ \fIend\-pat\fP ] +.TP +.PD +\fBcompset \-q\fP +This command simplifies modification of the special parameters, +while its return status allows tests on them to be carried out\&. +.RS +.PP +The options are: +.PP +.PD 0 +.TP +.PD +\fB\-p\fP \fInumber\fP +If the value of the \fBPREFIX\fP parameter is at least \fInumber\fP +characters long, the first \fInumber\fP characters are removed from it and +appended to the contents of the \fBIPREFIX\fP parameter\&. +.TP +\fB\-P\fP [ \fInumber\fP ] \fIpattern\fP +If the value of the \fBPREFIX\fP parameter begins with anything that +matches the \fIpattern\fP, the matched portion is removed from +\fBPREFIX\fP and appended to \fBIPREFIX\fP\&. +.RS +.PP +Without the optional \fInumber\fP, the longest match is taken, but +if \fInumber\fP is given, anything up to the \fInumber\fPth match is +moved\&. If the \fInumber\fP is negative, the \fInumber\fPth longest +match is moved\&. For example, if \fBPREFIX\fP contains the string +`\fBa=b=c\fP\&', then \fBcompset \-P '*\e='\fP will move the string `\fBa=b=\fP' +into the \fBIPREFIX\fP parameter, but \fBcompset \-P 1 \&'*\e='\fP will move only +the string `\fBa=\fP\&'\&. +.RE +.TP +\fB\-s\fP \fInumber\fP +As \fB\-p\fP, but transfer the last \fInumber\fP characters from the +value of \fBSUFFIX\fP to the front of the value of \fBISUFFIX\fP\&. +.TP +\fB\-S\fP [ \fInumber\fP ] \fIpattern\fP +As \fB\-P\fP, but match the last portion of \fBSUFFIX\fP and transfer the +matched portion to the front of the value of \fBISUFFIX\fP\&. +.TP +\fB\-n\fP \fIbegin\fP [ \fIend\fP ] +If the current word position as specified by the parameter \fBCURRENT\fP +is greater than or equal to \fIbegin\fP, anything up to the +\fIbegin\fPth word is removed from the \fBwords\fP array and the value +of the parameter \fBCURRENT\fP is decremented by \fIbegin\fP\&. +.RS +.PP +If the optional \fIend\fP is given, the modification is done only if +the current word position is also less than or equal to \fIend\fP\&. In +this case, the words from position \fIend\fP onwards are also removed from +the \fBwords\fP array\&. +.PP +Both \fIbegin\fP and \fIend\fP may be negative to count backwards +from the last element of the \fBwords\fP array\&. +.RE +.TP +\fB\-N\fP \fIbeg\-pat\fP [ \fIend\-pat\fP ] +If one of the elements of the \fBwords\fP array before the one at the +index given by the value of the parameter \fBCURRENT\fP matches the +pattern \fIbeg\-pat\fP, all elements up to and including the matching one are +removed from the \fBwords\fP array and the value of \fBCURRENT\fP is changed to +point to the same word in the changed array\&. +.RS +.PP +If the optional pattern \fIend\-pat\fP is also given, and there is an +element in the \fBwords\fP array matching this pattern, the parameters +are modified only if the index of this word is higher than the one +given by the \fBCURRENT\fP parameter (so that the matching word has +to be after the cursor)\&. In this case, the words starting with the one +matching \fBend\-pat\fP are also removed from the \fBwords\fP +array\&. If \fBwords\fP contains no word matching \fIend\-pat\fP, the +testing and modification is performed as if it were not given\&. +.RE +.TP +\fB\-q\fP +The word +currently being completed is split on spaces into separate words, +respecting the usual shell quoting conventions\&. The +resulting words are stored in the \fBwords\fP array, and \fBCURRENT\fP, +\fBPREFIX\fP, \fBSUFFIX\fP, \fBQIPREFIX\fP, and \fBQISUFFIX\fP are modified to +reflect the word part that is completed\&. +.PP +In all the above cases the return status is zero if the test succeeded +and the parameters were modified and non\-zero otherwise\&. This allows +one to use this builtin in tests such as: +.PP +.RS +.nf +\fBif compset \-P \&'*\e='; then \&.\&.\&.\fP +.fi +.RE +.PP +This forces anything up to and including the last equal sign to be +ignored by the completion code\&. +.RE +.TP +\fBcompcall\fP [ \fB\-TD\fP ] +This allows the use of completions defined with the \fBcompctl\fP builtin +from within completion widgets\&. The list of matches will be generated as +if one of the non\-widget completion functions (\fBcomplete\-word\fP, etc\&.) +had been called, except that only \fBcompctl\fPs given for specific commands +are used\&. To force the code to try completions defined with the \fB\-T\fP +option of \fBcompctl\fP and/or the default completion (whether defined by +\fBcompctl \-D\fP or the builtin default) in the appropriate places, the +\fB\-T\fP and/or \fB\-D\fP flags can be passed to \fBcompcall\fP\&. +.RS +.PP +The return status can be used to test if a matching \fBcompctl\fP +definition was found\&. It is non\-zero if a \fBcompctl\fP was found and +zero otherwise\&. +.PP +Note that this builtin is defined by the \fBzsh/compctl\fP module\&. +.RE +.PP +.SH "COMPLETION CONDITION CODES" +.PP +The following additional condition codes for use within the \fB[[\fP \fI\&.\&.\&.\fP \fB]]\fP +construct are available in completion widgets\&. These work on the special +parameters\&. All of these tests can also be performed by the \fBcompset\fP +builtin, but in the case of the condition codes the contents of the special +parameters are not modified\&. +.PP +.PD 0 +.TP +.PD +\fB\-prefix\fP [ \fInumber\fP ] \fIpattern\fP +true if the test for the \fB\-P\fP option of \fBcompset\fP would succeed\&. +.TP +\fB\-suffix\fP [ \fInumber\fP ] \fIpattern\fP +true if the test for the \fB\-S\fP option of \fBcompset\fP would succeed\&. +.TP +\fB\-after\fP \fIbeg\-pat\fP +true if the test of the \fB\-N\fP option with only the \fIbeg\-pat\fP given +would succeed\&. +.TP +\fB\-between\fP \fIbeg\-pat end\-pat\fP +true if the test for the \fB\-N\fP option with both patterns would succeed\&. +.PP +.SH "COMPLETION MATCHING CONTROL" +.PP +It is possible by use of the +\fB\-M\fP option of the \fBcompadd\fP builtin command to specify how the +characters in the string to be completed (referred to here as the +command line) map onto the characters in the list of matches produced by +the completion code (referred to here as the trial completions)\&. Note +that this is not used if the command line contains a glob pattern and +the \fBGLOB_COMPLETE\fP option is set or the \fBpattern_match\fP of the +\fBcompstate\fP special association is set to a non\-empty string\&. +.PP +The \fImatch\-spec\fP given as the argument to the \fB\-M\fP option (see +`Completion Builtin Commands\&' above) consists of one or more matching descriptions separated by +whitespace\&. Each description consists of a letter followed by a colon +and then the patterns describing which character sequences on the line match +which character sequences in the trial completion\&. Any sequence of +characters not handled in this fashion must match exactly, as usual\&. +.PP +The forms of \fImatch\-spec\fP understood are as follows\&. In each case, the +form with an upper case initial character retains the string already +typed on the command line as the final result of completion, while with +a lower case initial character the string on the command line is changed +into the corresponding part of the trial completion\&. +.PP +.PD 0 +.TP +.PD 0 +\fBm:\fP\fIlpat\fP\fB=\fP\fItpat\fP +.TP +.PD +\fBM:\fP\fIlpat\fP\fB=\fP\fItpat\fP +Here, \fIlpat\fP is a pattern that matches on the command line, +corresponding to \fItpat\fP which matches in the trial completion\&. +.TP +.PD 0 +\fBl:\fP\fIlanchor\fP\fB|\fP\fIlpat\fP\fB=\fP\fItpat\fP +.TP +.PD 0 +\fBL:\fP\fIlanchor\fP\fB|\fP\fIlpat\fP\fB=\fP\fItpat\fP +.TP +.PD 0 +\fBl:\fP\fIlanchor\fP\fB||\fP\fIranchor\fP\fB=\fP\fItpat\fP +.TP +.PD 0 +\fBL:\fP\fIlanchor\fP\fB||\fP\fIranchor\fP\fB=\fP\fItpat\fP +.TP +.PD 0 +\fBb:\fP\fIlpat\fP\fB=\fP\fItpat\fP +.TP +.PD +\fBB:\fP\fIlpat\fP\fB=\fP\fItpat\fP +These letters are for patterns that are anchored by another pattern on +the left side\&. Matching for \fIlpat\fP and \fItpat\fP is as for \fBm\fP and +\fBM\fP, but the pattern \fIlpat\fP matched on the command line must be +preceded by the pattern \fIlanchor\fP\&. The \fIlanchor\fP can be blank to +anchor the match to the start of the command line string; otherwise the +anchor can occur anywhere, but must match in both the command line and +trial completion strings\&. +.RS +.PP +If no \fIlpat\fP is given but a \fIranchor\fP is, this matches the gap +between substrings matched by \fIlanchor\fP and \fIranchor\fP\&. Unlike +\fIlanchor\fP, the \fIranchor\fP only needs to match the trial +completion string\&. +.PP +The \fBb\fP and \fBB\fP forms are similar to \fBl\fP and \fBL\fP with an empty +anchor, but need to match only the beginning of the word on the command line +or trial completion, respectively\&. +.RE +.TP +.PD 0 +\fBr:\fP\fIlpat\fP\fB|\fP\fIranchor\fP\fB=\fP\fItpat\fP +.TP +.PD 0 +\fBR:\fP\fIlpat\fP\fB|\fP\fIranchor\fP\fB=\fP\fItpat\fP +.TP +.PD 0 +\fBr:\fP\fIlanchor\fP\fB||\fP\fIranchor\fP\fB=\fP\fItpat\fP +.TP +.PD 0 +\fBR:\fP\fIlanchor\fP\fB||\fP\fIranchor\fP\fB=\fP\fItpat\fP +.TP +.PD 0 +\fBe:\fP\fIlpat\fP\fB=\fP\fItpat\fP +.TP +.PD +\fBE:\fP\fIlpat\fP\fB=\fP\fItpat\fP +As \fBl\fP, \fBL\fP, \fBb\fP and \fBB\fP, with the difference that the command +line and trial completion patterns are anchored on the right side\&. +Here an empty \fIranchor\fP and the \fBe\fP and \fBE\fP forms force the +match to the end of the command line or trial completion string\&. +.TP +\fBx:\fP +This form is used to mark the end of matching specifications: +subsequent specifications are ignored\&. In a single standalone list +of specifications this has no use but where matching specifications +are accumulated, such as from nested function calls, it can allow one +function to override another\&. +.PP +Each \fIlpat\fP, \fItpat\fP or \fIanchor\fP is either an empty string or +consists of a 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\&. +.PP +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 \fB!\fP and \fB^\fP 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 `\fBm:{a\-z}={A\-Z}\fP\&' +(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 \fB=\fP 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\&. +.PP +The standard `\fB[:\fP\fIname\fP\fB:]\fP\&' forms described for standard shell +patterns (see +the section FILENAME GENERATION in \fIzshexpn\fP(1)) +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 +\fB[:upper:]\fP, \fB[:lower:]\fP\&. 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 `\fBm:{[:lower:]}={[:upper:]}\fP\&'\&. 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 +`\fB[:\fP\fIname\fP\fB:]\fP\&' 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\&. +.PP +The pattern \fItpat\fP may also be one or two stars, `\fB*\fP\&' or +`\fB**\fP\&'\&. 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 \fIanchor\fP 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\&. +.PP +Examples: +.PP +The keys of the \fBoptions\fP association defined by the \fBparameter\fP +module are the option names in all\-lower\-case form, without +underscores, and without the optional \fBno\fP at the beginning even +though the builtins \fBsetopt\fP and \fBunsetopt\fP understand option names +with upper case letters, underscores, and the optional \fBno\fP\&. The +following alters the matching rules so that the prefix \fBno\fP 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: +.PP +.RS +.nf +\fBcompadd \-M \&'L:|[nN][oO]= M:_= M:{[:upper:]}={[:lower:]}' \- \e + ${(k)options} \fP +.fi +.RE +.PP +The first part says that the pattern `\fB[nN][oO]\fP\&' 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 (\fBL\fP and \fBM\fP) guarantees that what has +already been typed on the command line (in particular the prefix +\fBno\fP) will not be deleted\&. +.PP +Note that the use of \fBL\fP 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 `\fB_NO_f\fP\&' would not be +completed to `\fB_NO_foo\fP\&', nor would `\fBNONO_f\fP' be completed to +`\fBNONO_foo\fP\&' because of the leading underscore or the second +`\fBNO\fP\&' on the line which makes the pattern fail even though they are +otherwise ignored\&. To fix this, one would use `\fBB:[nN][oO]=\fP\&' +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 \fImatch\-spec\fPs\&. +.PP +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: +.PP +.RS +.nf +\fBcompadd \-M \&'m:{[:lower:]}={[:upper:]}' \&.\&.\&. \fP +.fi +.RE +.PP +This makes lower case letters match their upper case counterparts\&. +To make upper case letters match the lower case forms as well: +.PP +.RS +.nf +\fBcompadd \-M \&'m:{[:lower:][:upper:]}={[:upper:][:lower:]}' \&.\&.\&. \fP +.fi +.RE +.PP +A nice example for the use of \fB*\fP patterns is partial word +completion\&. Sometimes you would like to make strings like `\fBc\&.s\&.u\fP\&' +complete to strings like `\fBcomp\&.source\&.unix\fP\&', 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\&. `\fBcomp\fP\&', +`\fBsource\fP\&' and `\fBunix\fP' 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: +.PP +.RS +.nf +\fBcompadd \-M \&'r:|\&.=* r:|=*' \e + \- comp\&.sources\&.unix comp\&.sources\&.misc \&.\&.\&.\fP +.fi +.RE +.PP +The first specification says that \fIlpat\fP is the empty string, while +\fIanchor\fP is a dot; \fItpat\fP is \fB*\fP, so this can match anything +except for the `\fB\&.\fP\&' from the anchor in +the trial completion word\&. So in `\fBc\&.s\&.u\fP\&', the matcher sees `\fBc\fP', +followed by the empty string, followed by the anchor `\fB\&.\fP\&', and +likewise for the second dot, and replaces the empty strings before the +anchors, giving `\fBc\fP[\fBomp\fP]\fB\&.s\fP[\fBources\fP]\fB\&.u\fP[\fBnix\fP]\&', where +the last part of the completion is just as normal\&. +.PP +With the pattern shown above, the string `\fBc\&.u\fP\&' could not be +completed to `\fBcomp\&.sources\&.unix\fP\&' because the single star means +that no dot (matched by the anchor) can be skipped\&. By using two stars +as in `\fBr:|\&.=**\fP\&', however, `\fBc\&.u\fP' could be completed to +`\fBcomp\&.sources\&.unix\fP\&'\&. 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\&. +.PP +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 +\fBCOMPLETE_IN_WORD\fP 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 `\fBnix\fP\&' 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\&. +.PP +More generally, the specification +.PP +.RS +.nf +\fBcompadd \-M \&'r:|[\&.,_\-]=* r:|=*' \&.\&.\&. \fP +.fi +.RE +.PP +allows one to complete words with abbreviations before any of the +characters in the square brackets\&. For example, to +complete \fBveryverylongfile\&.c\fP rather than \fBveryverylongheader\&.h\fP +with the above in effect, you can just type \fBvery\&.c\fP before attempting +completion\&. +.PP +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 `\fBLikeThis\fP\&' (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: +.PP +.RS +.nf +\fBcompadd \-M \&'r:|[[:upper:]0\-9]=* r:|=*' LikeTHIS FooHoo 5foo123 5bar234\fP +.fi +.RE +.PP +But with this, the string `\fBH\fP\&' would neither complete to `\fBFooHoo\fP' +nor to `\fBLikeTHIS\fP\&' because in each case there is an upper case +letter before the `\fBH\fP\&' and that is matched by the anchor\&. Likewise, +a `\fB2\fP\&' would not be completed\&. In both cases this could be changed +by using `\fBr:|[[:upper:]0\-9]=**\fP\&', but then `\fBH\fP' completes to both +`\fBLikeTHIS\fP\&' and `\fBFooHoo\fP' and a `\fB2\fP' matches the other +strings because characters can be inserted before every upper case +letter and digit\&. To avoid this one would use: +.PP +.RS +.nf +\fBcompadd \-M \&'r:[^[:upper:]0\-9]||[[:upper:]0\-9]=** r:|=*' \e + LikeTHIS FooHoo foo123 bar234\fP +.fi +.RE +.PP +By using these two anchors, a `\fBH\fP\&' matches only upper case `\fBH\fP's that +are immediately preceded by something matching the left anchor +`\fB[^[:upper:]0\-9]\fP\&'\&. The effect is, of course, that `\fBH\fP' matches only +the string `\fBFooHoo\fP\&', a `\fB2\fP' matches only `\fBbar234\fP' and so on\&. +.PP +When using the completion system (see +\fIzshcompsys\fP(1)), users can define match specifications that are to be used for +specific contexts by using the \fBmatcher\fP and \fBmatcher\-list\fP +styles\&. The values for the latter will be used everywhere\&. +.PP +.SH "COMPLETION WIDGET EXAMPLE" +.PP +The first step is to define the widget: +.PP +.RS +.nf +\fBzle \-C complete complete\-word complete\-files\fP +.fi +.RE +.PP +Then the widget can be bound to a key using the \fBbindkey\fP builtin +command: +.PP +.RS +.nf +\fBbindkey \&'^X\et' complete\fP +.fi +.RE +.PP +After that the shell function \fBcomplete\-files\fP will be invoked +after typing control\-X and TAB\&. The function should then generate the +matches, e\&.g\&.: +.PP +.RS +.nf +\fBcomplete\-files () { compadd \- * }\fP +.fi +.RE +.PP +This function will complete files in the current directory matching the +current word\&. |