Initial revision

1 files changed, 526 insertions, 0 deletions

diff --git a/Doc/Zsh/compctl.yo b/Doc/Zsh/compctl.yo
new file mode 100644
index 000000000..a78a18fa9
--- /dev/null
+++ b/Doc/Zsh/compctl.yo
@@ -0,0 +1,526 @@
+texinode(Programmable Completion)(Zsh Modules)(Zsh Line Editor)(Top)
+chapter(Programmable Completion)
+cindex(completion, programmable)
+cindex(completion, controlling)
+findex(compctl)
+sect(Description)
+startlist()
+list(tt(compctl) [ tt(-CDT) ] var(options) [ var(command) ... ])
+list(tt(compctl) [ tt(-CDT) ] var(options) \
+  [ tt(-x) var(pattern) var(options) tt(-) ... tt(--) ] \
+  [ tt(PLUS()) var(options) [ tt(-x) ... tt(--) ] ... [tt(PLUS())] ] \
+  [ var(command) ... ])
+list(tt(compctl) tt(-L) [ tt(-CDT) ] [ var(command) ... ])
+list(tt(compctl) tt(PLUS()) var(command) ...)
+endlist()
+
+Control the editor's completion behavior according to the supplied set
+of var(options).  Various editing commands, notably
+tt(expand-or-complete-word), usually bound to tab, will
+attempt to complete a word typed by the user, while others, notably
+tt(delete-char-or-list), usually bound to ^D in EMACS editing
+mode, list the possibilities; tt(compctl) controls what those
+possibilities are.  They may for example be filenames (the most common
+case, and hence the default), shell variables, or words from a
+user-specified list.
+startmenu()
+menu(Command Flags)
+menu(Option Flags)
+menu(Alternative Completion)
+menu(Extended Completion)
+menu(Example)
+endmenu()
+texinode(Command Flags)(Option Flags)()(Programmable Completion)
+sect(Command Flags)
+Completion of the arguments of a command may be different for each
+command or may use the default.  The behavior when completing the
+command word itself may also be separately specified.  These
+correspond to the following flags and arguments, all of which (except
+for tt(-L)) may be combined with any combination of the
+var(options) described subsequently in noderef(Option Flags):
+
+startitem()
+item(var(command) ...)(
+controls completion for the named commands, which must be listed last
+on the command line.  If completion is attempted for a command with a
+pathname containing slashes and no completion definition is found, the
+search is retried with the last pathname component.  Note that aliases
+are expanded before the command name is determined unless the
+tt(COMPLETE_ALIASES) option is set.  Commands should not be combined
+with the tt(-C), tt(-D) or tt(-T) flags.
+)
+item(tt(-C))(
+controls completion when the command word itself is being completed.
+If no tt(compctl -C) command has been issued,  the names of any
+executable command (whether in the path or specific to the shell, such
+as aliases or functions) are completed.
+)
+item(tt(-D))(
+controls default completion behavior for the arguments of commands not
+assigned any special behavior.  If no tt(compctl -D) command has
+been issued, filenames are completed.
+)
+item(tt(-T))(
+supplies completion flags to be used before any other processing is
+done, even those given to specific commands with other compctl
+definitions.  This is only useful when combined with extended
+completion (the tt(-x) flag, see noderef(Extended Completion) below).
+Using this flag you can define default behavior
+which will apply to all commands without exception, or you can alter
+the standard behavior for all commands.  For example, if your access
+to the user database is too slow and/or it contains too many users (so
+that completion after `tt(~)' is too slow to be usable), you can use
+
+nofill(tt(compctl -Tx  'C[0,*/*]' -f - 's[~]' -k friends -S/))
+
+to complete the strings in the array tt(friends) after a `tt(~)'.
+The first argument is necessary so that this form of ~-completion is
+not tried after the directory name is finished.
+)
+item(tt(-L))(
+lists the existing completion behavior in a manner suitable for
+putting into a start-up script; the existing behavior is not changed.
+Any combination of the above forms may be specified, otherwise all
+defined completions are listed.  Any other flags supplied
+are ignored.
+)
+item(em(no argument))(
+If no argument is given, tt(compctl) lists all defined completions
+in an abbreviated form;  with a list of var(options), all completions
+with those flags set (not counting extended completion) are listed.
+)
+endlist()
+
+If the tt(PLUS()) flag is alone and followed immediately by the var(command)
+list, the completion behavior for all the commands in the list is reset to
+the default.  In other words, completion will subsequently use the
+options specified by the tt(-D) flag.
+texinode(Option Flags)(Alternative Completion)(Command Flags)(Programmable Completion)
+sect(Option Flags)
+startlist()
+list([ tt(-fcFBdeaRGovNAIOPZEnbjrzu/) ])
+list([ tt(-k) var(array) ] [ tt(-g) var(globstring) ] \
+  [ tt(-s) var(subststring) ])
+list([ tt(-K) var(function) ] [ tt(-H) var(num pattern) ])
+list([ tt(-Q) ] [ tt(-P) var(prefix) ] [ tt(-S) var(suffix) ])
+list([ tt(-W) var(file-prefix) ])
+list([ tt(-q) ] [ tt(-X) var(explanation) ] [ tt(-Y) var(explanation) ])
+list([ tt(-y) var(func-or-var) ] [ tt(-l) var(cmd) ] [ tt(-U) ])
+endlist()
+
+The remaining var(options) specify the type of command arguments
+to look for during completion.  Any combination of these flags may be
+specified; the result is a sorted list of all the possibilities.  The
+options are as follows.
+startmenu()
+menu(Simple Flags)
+menu(Flags with Arguments)
+menu(Control Flags)
+endmenu()
+texinode(Simple Flags)(Flags with Arguments)()(Option Flags)
+subsect(Simple Flags)
+These produce completion lists made up by the shell itself:
+
+startitem()
+item(tt(-f))(
+Filenames and filesystem paths.
+)
+item(tt(-/))(
+Just filesystem paths.
+)
+item(tt(-c))(
+Command names, including aliases, shell functions, builtins
+and reserved words.
+)
+item(tt(-F))(
+Function names.
+)
+item(tt(-B))(
+Names of builtin commands.
+)
+item(tt(-m))(
+Names of external commands.
+)
+item(tt(-w))(
+Reserved words.
+)
+item(tt(-a))(
+Alias names.
+)
+item(tt(-R))(
+Names of regular (non-global) aliases.
+)
+item(tt(-G))(
+Names of global aliases.
+)
+item(tt(-d))(
+This can be combined with tt(-F), tt(-B), tt(-w),
+tt(-a), tt(-R) and tt(-G) to get names of disabled
+functions, builtins, reserved words or aliases.
+)
+item(tt(-e))(
+This option (to show enabled commands) is in effect by default, but
+may be combined with tt(-d); tt(-de) in combination with
+tt(-F), tt(-B), tt(-w), tt(-a), tt(-R) and tt(-G)
+will complete names of functions, builtins, reserved words or aliases
+whether or not they are disabled.
+)
+item(tt(-o))(
+Names of shell options (see
+ifzman(zmanref(zshoptions))\
+ifnzman(noderef(Options))\
+).
+)
+item(tt(-v))(
+Names of any variable defined in the shell.
+)
+item(tt(-N))(
+Names of scalar (non-array) parameters.
+)
+item(tt(-A))(
+Array names.
+)
+item(tt(-I))(
+Names of integer variables.
+)
+item(tt(-O))(
+Names of read-only variables.
+)
+item(tt(-p))(
+Names of parameters used by the shell (including special parameters).
+)
+item(tt(-Z))(
+Names of shell special parameters.
+)
+item(tt(-E))(
+Names of environment variables.
+)
+item(tt(-n))(
+Named directories.
+)
+item(tt(-b))(
+Key binding names.
+)
+item(tt(-j))(
+Job names:  the first word of the job leader's command line.  This is useful
+with the tt(kill) builtin.
+)
+item(tt(-r))(
+Names of running jobs.
+)
+item(tt(-z))(
+Names of suspended jobs.
+)
+item(tt(-u))(
+User names.
+)
+enditem()
+texinode(Flags with Arguments)(Control Flags)(Simple Flags)(Option Flags)
+subsect(Flags with Arguments)
+These have user supplied arguments to determine how the list of
+completions is to be made up:
+
+startitem()
+item(tt(-k) var(array))(
+Names taken from the elements of tt($)var(array) (note that the `tt($)'
+does not appear on the command line).
+Alternatively, the argument var(array) itself may be a set
+of space- or comma-separated values in parentheses, in which any
+delimiter may be escaped with a backslash; in this case the argument
+should be quoted.  For example,
+
+nofill(tt(compctl -k "(cputime filesize datasize stacksize
+    coredumpsize resident descriptors)" limit))
+)
+item(tt(-g) var(globstring))(
+The var(globstring) is expanded using filename globbing; it should be
+quoted to protect it from immediate expansion. The resulting
+filenames are taken as the possible completions.  Use `tt(*(/))' instead of
+`tt(*/)' for directories.  The tt(fignore) special parameter is not
+applied to the resulting files.  More than one pattern may be given
+separated by blanks. (Note that brace expansion is em(not) part of
+globbing.  Use the syntax `tt((either|or))' to match alternatives.)
+)
+item(tt(-s) var(subststring))(
+The var(subststring) is split into words and these words are than
+expanded using all shell expansion mechanisms (see
+ifzman(zmanref(zshexpn))\
+ifnzman(noderef(Expansion))\
+).  The resulting words are taken as possible
+completions.  The tt(fignore) special parameter is not applied to the
+resulting files.  Note that tt(-g) is faster for filenames.
+)
+item(tt(-K) var(function))(
+Call the given function to get the completions.  The function is
+passed two arguments: the prefix and the suffix of the word on which
+completion is to be attempted, in other words those characters before
+the cursor position, and those from the cursor position onwards.  The
+whole command line can be accessed with the tt(-c) and tt(-l) flags
+of the tt(read) builtin.  The
+function should set the variable tt(reply) to an array containing
+the completions (one completion per element); note that tt(reply)
+should not be made local to the function.  From such a function the
+command line can be accessed with the tt(-c) and tt(-l) flags to
+the tt(read) builtin.  For example,
+
+nofill(tt(function whoson { reply=(`users`); }
+compctl -K whoson talk))
+
+completes only logged-on users after `tt(talk)'.  Note that `tt(whoson)' must
+return an array, so `tt(reply=`users`)' would be incorrect.
+)
+item(tt(-H) var(num pattern))(
+The possible completions are taken from the last var(num) history
+lines.  Only words matching var(pattern) are taken.  If var(num) is
+zero or negative the whole history is searched and if var(pattern) is
+the empty string all words are taken (as with `tt(*)').  A typical
+use is
+
+nofill(tt(compctl -D -f PLUS() -H 0 ''))
+
+which forces completion to look back in the history list for a word if
+no filename matches.
+)
+enditem()
+texinode(Control Flags)()(Flags with Arguments)(Option Flags)
+subsect(Control Flags)
+These do not directly specify types of name to be completed, but
+manipulate the options that do:
+
+startitem()
+item(tt(-Q))(
+This instructs the shell not to quote any metacharacters in the possible
+completions.  Normally the results of a completion are inserted into
+the command line with any metacharacters quoted so that they are
+interpreted as normal characters.  This is appropriate for filenames
+and ordinary strings.  However, for special effects, such as inserting
+a backquoted expression from a completion array (tt(-k)) so that
+the expression will not be evaluated until the complete line is
+executed, this option must be used.
+)
+item(tt(-P) var(prefix))(
+The var(prefix) is inserted just before the completed string; any
+initial part already typed will be completed and the whole var(prefix)
+ignored for completion purposes.  For example,
+
+nofill(tt(compctl -j -P "%" kill))
+
+inserts a `%' after the kill command and then completes job names.
+)
+item(tt(-S) var(suffix))(
+When a completion is found the var(suffix) is inserted after
+the completed string.  In the case of menu completion the suffix is
+inserted immediately, but it is still possible to cycle through the
+list of completions by repeatedly hitting the same key.
+)
+item(tt(-W) var(file-prefix))(
+With directory var(file-prefix):  for command, file, directory and
+globbing completion (options tt(-c), tt(-f), tt(-/), tt(-g)), the file
+prefix is implicitly added in front of the completion.  For example,
+
+nofill(tt(compctl -/ -W ~/Mail maildirs))
+
+completes any subdirectories to any depth beneath the directory
+tt(~/Mail), although that prefix does not appear on the command line.
+)
+item(tt(-q))(
+If used with a suffix as specified by the tt(-S) option, this
+causes the suffix to be removed if the next character typed is a blank
+or does not insert anything (the same rule as used for the
+tt(AUTO_REMOVE_SLASH) option).  The option is most useful for list
+separators (comma, colon, etc.).
+)
+item(tt(-l) var(cmd))(
+This option cannot be combined with any other.  It restricts the range
+of command line words that are considered to be arguments.  If
+combined with one of the extended completion patterns `tt(p[)...tt(])',
+`tt(r[)...tt(])', or `tt(R[)...tt(])'  (see noderef(Extended Completion)
+below) the range is restricted to the range of arguments
+specified in the brackets.  Completion is then performed as if these
+had been given as arguments to the var(cmd) supplied with the
+option. If the var(cmd) string is empty the first word in the range
+is instead taken as the command name, and command name completion
+performed on the first word in the range.  For example,
+
+nofill(tt(compctl -x 'r[-exec,;]' -l '' -- find))
+
+completes arguments between `tt(-exec)' and the following `tt(;)' (or the end
+of the command line if there is no such string) as if they were
+a separate command line.
+)
+item(tt(-U))(
+Use the whole list of possible completions, whether or not they
+actually match the word on the command line.  The word typed so far
+will be deleted.  This is most useful with a function (given by the
+tt(-K) option) which can examine the word components passed to it
+(or via the tt(read) builtin's tt(-c) and tt(-l) flags) and
+use its own criteria to decide what matches.  If there is no
+completion, the original word is retained.
+)
+item(tt(-y) var(func-or-var))(
+The list provided by var(func-or-var) is displayed instead of the list
+of completions whenever a listing is required; the actual completions
+to be inserted are not affected.  It can be provided in two
+ways. Firstly, if var(func-or-var) begins with a tt($) it defines a
+variable, or if it begins with a left parenthesis a literal
+array, which contains the list.  A variable may have been set by a
+call to a function using the tt(-K) option.  Otherwise it contains the
+name of a function which will be executed to create the list.  The
+function will be passed as an argument list all matching completions,
+including prefixes and suffixes expanded in full, and should set the
+array var(reply) to the result.  In both cases, the display list will
+only be retrieved after a complete list of matches has been created.
+
+Note that the returned list does not have to correspond, even in
+length, to the original set of matches, and may be passed as a scalar
+instead of an array.  No special formatting of characters is
+performed on the output in this case; in particular, newlines are
+printed literally and if they appear output in columns is suppressed.
+)
+item(tt(-X) var(explanation))(
+Print var(explanation) when trying completion on the current set of
+options. A `tt(%n)' in this string is replaced by the number of matches.
+The explanation only appears if completion was tried and there was
+no unique match, or when listing completions.
+)
+item(tt(-Y) var(explanation))(
+Identical to tt(-X), except that the var(explanation) first undergoes
+expansion following the usual rules for strings in double quotes.
+The expansion will be carried out after any functions are called for
+the tt(-K) or tt(-y) options, allowing them to set variables.
+)
+enditem()
+texinode(Alternative Completion)(Extended Completion)(Option Flags)(Programmable Completion)
+sect(Alternative Completion)
+startlist()
+list(tt(compctl) [ tt(-CDT) ] var(options) tt(PLUS()) var(options) [ tt(PLUS()) ... ] \
+[ tt(PLUS()) ] var(command) ...)
+endlist()
+
+The form with `tt(PLUS())' specifies alternative options. Completion is
+tried with the options before the first `tt(PLUS())'. If this produces no
+matches completion is tried with the flags after the `tt(PLUS())' and so on. If
+there are no flags after the last `tt(PLUS())' and a match has not been found
+up to that point, default completion is tried.
+texinode(Extended Completion)(Example)(Alternative Completion)(Programmable Completion)
+sect(Extended Completion)
+startlist()
+list(tt(compctl) [ tt(-CDT) ] var(options) \
+tt(-x) var(pattern) var(options) tt(-) ... tt(--) \
+[ var(command) ... ])
+list(tt(compctl) [ tt(-CDT) ] var(options) \
+[ tt(-x) var(pattern) var(options) tt(-) ... tt(--) ] \
+[ tt(PLUS()) var(options) [ tt(-x) ... tt(--) ] ... [tt(PLUS())] ] \
+[ var(command) ... ])
+endlist()
+
+The form with `tt(-x)' specifies extended completion for the
+commands given; as shown, it may be combined with alternative
+completion using `tt(PLUS())'.  Each var(pattern) is examined in turn; when a
+match is found, the corresponding var(options), as described in
+noderef(Option Flags) above, are used to generate possible
+completions.  If no var(pattern) matches, the var(options) given
+before the tt(-x) are used.
+
+Note that each pattern should be supplied as a single argument and
+should be quoted to prevent expansion of metacharacters by the
+shell.
+
+A var(pattern) is built of sub-patterns separated by commas; it
+matches if at least one of these sub-patterns matches (they are
+`or'ed). These sub-patterns are in turn composed of other
+sub-patterns separated by white spaces which match if all of the
+sub-patterns match (they are `and'ed).  An element of the
+sub-patterns is of the form `var(c)tt([)...tt(][)...tt(])', where the pairs of
+brackets may be repeated as often as necessary, and matches if any of
+the sets of brackets match (an `or').  The example below makes this
+clearer.
+
+The elements may be any of the following:
+
+startitem()
+item(tt(s[)var(string)tt(])...)(
+Matches if the current word on the command line starts with
+one of the strings given in brackets.  The var(string) is not removed
+and is not part of the completion.
+)
+item(tt(S[)var(string)tt(])...)(
+Like tt(s[)var(string)tt(]) except that the var(string) is part of the
+completion.
+)
+item(tt(p[)var(from)tt(,)var(to)tt(])...)(
+Matches if the number of the current word is between one of
+the var(from) and var(to) pairs inclusive. The comma and var(to)
+are optional; var(to) defaults to the same value as var(from).  The
+numbers may be negative: tt(-)var(n) refers to the var(n)'th last word
+on the line.
+)
+item(tt(c[)var(offset)tt(,)var(string)tt(])...)(
+Matches if the var(string) matches the word offset by
+var(offset) from the current word position.  Usually var(offset)
+will be negative.
+)
+item(tt(C[)var(offset)tt(,)var(pattern)tt(])...)(
+Like tt(c) but using pattern matching instead.
+)
+item(tt(w[)var(index)tt(,)var(string)tt(])...)(
+Matches if the word in position var(index) is equal
+to the corresponding var(string).  Note that the word count is made
+after any alias expansion.
+)
+item(tt(W[)var(index)tt(,)var(pattern)tt(])...)(
+Like tt(w) but using pattern matching instead.
+)
+item(tt(n[)var(index)tt(,)var(string)tt(])...)(
+Matches if the current word contains var(string).  Anything up to and
+including the var(index)th occurrence of this string will not be
+considered part of the completion, but the rest will.  var(index) may
+be negative to count from the end: in most cases, var(index) will be
+1 or -1.  For example,
+
+nofill(tt(compctl -s '`users`' -x 'n[1,@]' -k hosts -- talk))
+
+will usually complete usernames, but if you insert an tt(@) after the
+name, names from the array var(hosts) (assumed to contain hostnames,
+though you must make the array yourself) will be completed.  Other
+commands such as tt(rcp) can be handled similarly.
+)
+item(tt(N[)var(index)tt(,)var(string)tt(])...)(
+Like tt(n) except that the string will be
+taken as a character class.  Anything up to and including the
+var(index)th occurrence of any of the characters in var(string)
+will not be considered part of the completion.
+)
+item(tt(m[)var(min)tt(,)var(max)tt(])...)(
+Matches if the total number of words lies between var(min) and
+var(max) inclusive.
+)
+item(tt(r[)var(str1)tt(,)var(str2)tt(])...)(
+Matches if the cursor is after a word with prefix var(str1).  If there
+is also a word with prefix var(str2) on the command line it matches
+only if the cursor is before this word.
+)
+item(tt(R[)var(str1)tt(,)var(str2)tt(])...)(
+Like tt(r) but using pattern matching instead.
+)
+enditem()
+texinode(Example)()(Extended Completion)(Programmable Completion)
+sect(Example)
+nofill(tt(compctl -u -x 's[tt(PLUS())] c[-1,-f],s[-f+PLUS()]' -g '~/Mail/*(:t)' \ 
+    - 's[-f],c[-1,-f]' -f -- mail))
+
+This is to be interpreted as follows:
+
+If the current command is tt(mail), then
+
+indent(
+if ((the current word begins with tt(PLUS()) and the previous word is tt(-f))
+or (the current word begins with tt(-f+PLUS()))), then complete the
+non-directory part (the `tt(:t)' glob modifier) of files in the directory
+tt(~/Mail); else
+
+if the current word begins with tt(-f) or the previous word was tt(-f), then
+complete any file; else
+
+complete user names.
+)