Initial revision

1 files changed, 428 insertions, 0 deletions

diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
new file mode 100644
index 000000000..2cb12e2c2
--- /dev/null
+++ b/Doc/Zsh/compwid.yo
@@ -0,0 +1,428 @@
+texinode(Completion Widgets)(Zsh Modules)(Programmable Completion)(Top)
+chapter(Completion Widgets)
+cindex(completion, widgets)
+cindex(completion, programmable)
+cindex(completion, controlling)
+sect(Description)
+Completion widgets are defined using the tt(-C) option to the tt(zle)
+builtin command provided by the tt(zle) module (see
+ifzman(zmanref(zshzle))\
+ifnzman(noderef(The zle Module))\
+). For example, the invocation:
+
+indent(nofill(
+tt(zle -C complete expand-or-complete completer)))
+
+defines a widget named tt(complete). If this widget is bound to a key
+using the tt(bindkey) builtin command defined in the tt(zle) module
+(see 
+ifzman(zmanref(zshzle))\
+ifnzman(noderef(Zsh Line Editor))\
+) typing that key will make the completion code call the shell
+function tt(completer). This function is responsible for generating
+the possible matches using the builtins described below. Once the
+function returns, the completion code takes over control again and
+treats the matches the way the builtin widget tt(expand-or-complete)
+would do it. For this second argument, the name of any of the builtin
+widgets that handle completions can be given, i.e. it may be any of
+tt(complete-word), tt(expand-or-complete),
+tt(expand-or-complete-prefix), tt(menu-complete),
+tt(menu-expand-or-complete), tt(reverse-menu-complete),
+tt(list-choices), or tt(delete-char-or-list).
+
+startmenu()
+menu(Special Parameters)
+menu(Builtin Commands)
+menu(Condition Codes)
+menu(Examples)
+endmenu()
+
+texinode(Special Parameters)(Builtin Commands)()(Completion Widgets)
+sect(Special Parameters)
+
+Inside completion widgets some parameters have special meaning. They
+will be used inside the widget function and other shell functions
+called from it. Outside of these function they are not special to the
+shell in any way.
+
+The parameters are used to give information about the internal state
+from the completion code to the completion widget and can be set to
+give information to the completion code from the completion
+widget. Some of the builtin commands and the condition codes use or
+change the current values of these parameters. While the completion
+widget is active, these parameters are reseton each function exit to
+the values they had when the function was entered.
+
+startitem()
+item(tt(argv))(
+The positional parameters are set to the arguments on the command line
+when the widget function is invoked from the completion code.
+)
+item(tt(CURRENT))(
+This is the number of the current word, i.e. the word the cursor is
+currently on in the tt(argv) array.
+)
+item(tt(CONTEXT))(
+This will be set by the completion code to the overall context
+completion is attempted in. Possible values are:
+
+startitem()
+item(tt(command))(
+when completing in a command position, e.g. in the first word on the
+command line
+)
+item(tt(argument))(
+when completing an argument for a command
+)
+item(tt(redirect))(
+when completing after a redirection operator; in this case the
+positional parameters contain not only the arguments but also the
+command name itself as the first element
+)
+item(tt(condition))(
+when completing inside a `tt([[)...tt(]])' conditional expressing; in
+this case the positional parameters are set to the words inside the
+conditional expressions
+)
+item(tt(math))(
+when completing in a mathematical environment such as a
+`tt(LPAR()LPAR())...tt(RPAR()RPAR())' construct
+)
+item(tt(value))(
+when completing the value of a parameter assignment; in case of an
+array value the positional parameters are set to the words in
+parentheses
+)
+item(tt(subscript))(
+when completing inside a parameter expansion subscript
+)
+enditem()
+)
+item(tt(COMMAND))(
+In most cases this is set to name of the command for which completion
+is tried. When completing after a redirection operator it contains the 
+string forming that operator. Also, when completing in the value of a
+parameter assignment or in a parameter subscript it is set to the name
+of the parameter.
+)
+item(tt(PREFIX))(
+This should be set to that part of the current word that should be
+taken as the string every possible match has to begin with. 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. When 
+)
+item(tt(IPREFIX))(
+When a part of the current word should not be considered part of the
+matches, this part should be taken from the tt(PREFIX) parameter and
+appended to this parameter. This will initially be set to the empty
+string when called from the completion code.
+)
+item(tt(SUFFIX))(
+This should be set to that part of the current word that should be
+taken as the string every possible match has to end with. The
+completion code sets this to the part of the current word from the
+cursor position to the end.
+)
+item(tt(NMATCHES))(
+This is always set to the number of matches generated and accepted by
+the completion code so far.
+)
+item(tt(MATCHER))(
+When completion is used with a global match specification (i.e. a
+tt(compctl) with only a tt(-M) option), this parameter is set to the
+number of the specification string which is currently used.
+)
+enditem()
+
+texinode(Builtin Commands)(Condition Codes)(Special Parameters)(Completion Widgets)
+sect(Builtin Commands)
+startitem()
+findex(complist)
+item(tt(complist) var(flags ...))(
+
+Generate matches according to the given var(flags) which can be any of 
+the option flags supported by the tt(compctl) builtin command (see
+ifzman(zmanref(zshcompctl))\
+ifnzman(noderef(Programmable Completion))\
+) except for the tt(-t) and tt(-l) flags. Also, when using the tt(-K)
+flag, the function given as argument to it can not access the command
+line with the tt(read) builtin command.
+
+The matches will be generated in the same way as if the completion code
+generated them directly from a tt(compctl)-definition with the same
+flags. The completion code will consider only those matches as
+possible completions that match the prefix and suffix from the special 
+parameters desribed above. These strings will be compared with the
+generated matches using the normal matching rules and any matching
+specifications given with the tt(-M) flag to tt(complist) and the
+global matching specifications given to the tt(compctl) builtin
+command.
+)
+xitem(tt(compadd) [ tt(-qQfnUam) ] [ tt(-F) var(array) ])
+xitem([ tt(-P) var(prefix) ] [ tt(-S) var(suffix) ])
+xitem([ tt(-p) var(hidden-prefix) ] [ tt(-s) var(hidden-suffix) ])
+xitem([ tt(-i) var(ignored-prefix) ] [ tt(-W) var(file-prefix) ])
+xitem([ tt(-J) var(name) ] [ tt(-V) var(name) ])
+xitem([ tt(-r) var(remove-chars) ] [ tt(-R) var(remove-func) ])
+item([ tt(-M) var(match-spec) ] [ tt(--) ] [ var(words) ... ])(
+
+This builtin command can be used to add matches and directly control
+all the information the completion code stores with each possible
+match.
+
+The supported flags are:
+
+startitem()
+item(tt(-P) var(prefix))(
+The same as for tt(compctl) and tt(complist), it gives a string that
+should be inserted before the given words when they are completed. The
+string given is not considered to be part of the match.
+)
+item(tt(-S) var(suffix))(
+Like tt(-P) but gives a string that has to be inserted after the match.
+)
+item(tt(-p) var(hidden-prefix))(
+This gives a string that should be 
+...
+)
+item(tt(-s) var(hidden-suffix))(
+...
+)
+item(tt(-i) var(ignored-prefix))(
+...
+)
+item(tt(-J) var(name))(
+As for tt(compctl) and tt(complist) this gives the name of the group
+of matches the words should be stored in.
+)
+item(tt(-V) var(name))(
+Like tt(-J) but naming a unsorted group.
+)
+item(tt(-q))(
+This flag has the same meaning as for tt(compctl) and tt(complist),
+too. It makes the suffix given with tt(-S) 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.
+)
+item(tt(-r) var(remove-chars))(
+This makes the suffix given with tt(-S) be automatically removed if
+the next character typed inserts one of the characters given in the
+var(remove-chars). This string is parsed as a characters class with
+the usual backslash-sequences understood, e.g. using `tt(-r "a-z\t")'
+removes the suffix if the next character typed inserts one of the
+lower case letters or a TAB, and `tt(-r "^0-9")' removes the suffix if 
+the next character typed inserts anything but a digit. One extra
+backslash sequence is understood in this string: `tt(\-)' stands for
+all characters that insert nothing. Thus `tt(-S "=" -q)' is the same
+as `tt(-S "=" -r "= \t\n\-")'.
+)
+item(tt(-R) var(remove-func))(
+For the cases where one wants to remove suffix and the tt(-r) option
+does not give enough control, this option can be used. It stores the
+name of the shell function var(remove-func) in the matches. If one of
+the matches is finally accepted and the tt(-S)-suffix inserted, this
+function will be called after the next character typed. It gets the
+length of the suffix as its argument and can use the special
+parameters available in zle widgets (see
+ifzman(zmanref(zshzle))\
+ifnzman(noderef(Zsh Line Editor))\
+) to analyse and modify the command line.
+)
+item(tt(-f))(
+If this flag is given, the matches build are marked as being the names 
+of files. They need not be actual filenames, though. But if they are
+and the option tt(LIST_TYPES) is set, the characters describing the
+types of the files in the completion lists will be shown. This also
+makes a slash automatically be added when the name of a directory is
+completed.
+)
+item(tt(-W) var(file-prefix))(
+This option has the same meaning as for the tt(compctl) and
+tt(complist) builtin commands. Here, however, only one string may be
+given, not an array. This string is used as a pathname that will be
+prepended to the given words and the prefix given with the tt(-p)
+option to perform the file-tests when showing completion
+listings. Hence it is only useful if combined with the tt(-f) flag,
+since the tests will only be performed if that flag is given.
+)
+item(tt(-a))(
+When used by tt(compctl) or tt(complist) the completion code normally
+builds two sets of matches: the normal one where words with one of the 
+suffixes in the array parameter tt(fignore) are not considered
+possible matches, and the alternate set where the words excluded
+from the first set are stored. Normally only the matches in the first
+set are used. But if this set is empty, the words from the alternate
+set are used.
+
+The tt(compadd) builtin does not use tt(fignore) parameter and
+normally stores all words in the first set. With the tt(-a)-flag
+given, however, they are all stored in the alternate set unless this
+flag is overridden by the tt(-F) option.
+)
+item(tt(-F) var(array))(
+This can be used to give an array containing suffixes like the
+tt(fignore) parameter. Words with one of these suffixes are stored in
+the alternate set of matches and words without one of these suffixes
+are stored in the normal set.
+
+The var(array) may be the name of an array parameter or a list of
+literal suffixes enclosed in parentheses as in `tt(-F "(.o .h)")'. If
+the name of an array is given, the elements of the array are taken as
+the suffixes.
+)
+item(tt(-Q))(
+As for tt(compctl) and tt(complist) this flag instructs the completion 
+code not to quote any metacharacters in the words when inserting them
+in the command line.
+)
+item(tt(-m))(
+Normally the matches added by tt(compadd) will not be compared with
+what is already on the line. If this flag is given, this comparison is 
+performed as usual and the match specifications given with the tt(-M)
+option to tt(compadd) and the global match specifications defined with 
+tt(compctl) will be used. This means that probably not all the word
+given will be stored as matches since some of them may not match the
+string on the line.
+)
+item(tt(-M) var(match-spec))(
+This option allows one to give local match specifications with the
+same meaning and format as for the tt(compctl) and tt(complist)
+builtin commands. Note that they will only be used if the tt(-m) is
+given, too.
+)
+item(tt(-n))(
+Words added with tt(compadd) with this flag will be used as possible
+matches as usual but they not appear in the completion listing.
+)
+item(tt(-U))(
+If this flag is given to one of the calls to tt(compadd) and the
+option tt(AUTO_MENU) is set, the completion code will immediatly
+switch to menucompletion.
+)
+item(tt(-), tt(--))(
+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.
+)
+enditem()
+)
+item(tt(compcall) [ tt(-TD) ])(
+
+This allows one to use completion definitions given with the
+tt(compctl) builtin from within completion widgets. It makes
+completion code complete the current word according to the
+tt(compctl)s defined. Normally only tt(compctl)s given for specific
+commands are used. To make the code use the completion flags given to
+the tt(-T) option of tt(compctl), one can give the tt(-T) flag to
+tt(compctl). Likewise, the tt(-D) flag to tt(compcall) makes the
+default completion flags given to tt(compctl) with the tt(-D) option
+be used.
+)
+enditem()
+
+texinode(Condition Codes)(Examples)(Builtin Commands)(Completion Widgets)
+sect(Condition Codes)
+
+Inside completion widgets not only the builtin commands described
+above can be used, but also some additional condition codes. These
+work on the special parameters and can be used to easily build
+completion functions that generate different matches depending on the
+strings on the line.
+
+The following condition codes are made available inside completion
+widgets:
+
+startitem()
+item(tt(-prefix) var(string))(
+true if the content of tt(PREFIX) starts with var(string)
+)
+item(tt(-iprefix) var(string))(
+like tt(-prefix), but the var(string) is removed from tt(PREFIX) and
+added to tt(IPREFIX)
+)
+item(tt(-position) var(beg) [ var(end) ])(
+true if tt(CURRENT) is equal to var(beg) or, if var(end) is given,
+equal to or greater than var(beg) and equal to or less than var(end);
+both of var(beg) and var(end) may be arithmetic expressions, if they
+are less than zero the number of words in tt(argv) are added to them
+before comparing them to tt(CURRENT); thus, tt(-1) is the last word,
+tt(-2) is the word before that and so on
+)
+item(tt(-word) var(index) var(string))(
+true if the word number var(index) in tt(argv) is equal to
+var(string); again, var(index) may be negative, counting backwards
+)
+item(tt(-mword) var(index) var(pattern))(
+like tt(-word) but using pattern matching
+)
+item(tt(-current) var(offset) var(string))(
+like tt(-word) but var(offset) is relative to the value of
+tt(CURRENT)
+)
+item(tt(-mcurrent) var(offset) var(pattern))(
+like tt(-current) but using pattern matching
+)
+item(tt(-string) [ var(number) ] var(string))(
+true if the current word contains var(string); anything up to the last 
+occurrence of this string will be ingnored by removing it from
+tt(PREFIX) and adding it to tt(IPREFIX); if var(number) is given,
+anything up to the var(number)'th occurrence of the var(string) will
+be ignored; again, var(nmuber) may be any arithmetic expression and
+negative values count backward
+)
+item(tt(-class) [ var(number) ] var(class))(
+like tt(-string) but the var(class) is used as a character class so
+that anything up to and including the last or the var(number)'th
+occurrence of any character from the string var(class) is ignored
+)
+item(tt(-words) var(min) [ var(max) ])(
+true if the number of words is equal to var(min); if var(max) is
+given, it is true if the number of words is equal to or greater than
+var(min) and equal to or less than var(max)
+)
+item(tt(-after) var(string))(
+true if the cursor is after a word that is equal to var(string)
+)
+item(tt(-mafter) var(pattern))(
+like tt(-after) but using pattern matching
+)
+item(tt(-between) var(string1) var(string2))(
+true if the cursor is after a word that is equal to var(string1), if
+there is also a word that is equal to va(string2), this is true only
+if the cursor is before it
+)
+item(tt(-mbetween) var(pattern1) var(pattern2))(
+like tt(-between) but using pattern matching
+)
+item(tt(-nmatches) var(number))(
+true if the the value of tt(NMATCHES) is equal to var(number)
+)
+item(tt(-matcher) var(number))(
+true if the value of tt(MATCHER) is equal to var(number)
+)
+enditem()
+
+texinode(Examples)()(Condition Codes)(Completion Widgets)
+sect(Examples)
+
+The first step is to define the widget:
+
+indent(nofill(
+tt(zle -C complete complete-word complete-history)))
+
+Then the widget can be bound to a key using the tt(bindkey) builtin
+command:
+
+indent(nofill(
+tt(bindkey '^X\t' complete)))
+
+After that the shell function tt(complete-history) will be invoked
+after typing control-X and TAB. The function should then generte the
+matches, e.g.:
+
+indent(nofill(
+tt(complete-history LPAR()RPAR() { complist -H 0 '' })))
+
+In this the function will complete words from the history matching the 
+current word.