New upstream version 5.8

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\&.