diff options
Diffstat (limited to 'Doc/Zsh/compctl.yo')
-rw-r--r-- | Doc/Zsh/compctl.yo | 526 |
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. +) |