diff options
Diffstat (limited to 'Doc/Zsh/compsys.yo')
| -rw-r--r-- | Doc/Zsh/compsys.yo | 145 |
1 files changed, 78 insertions, 67 deletions
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 58f985021..9b00bf1a2 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -177,7 +177,7 @@ functions will probably ignore it. If the tt(#compdef) line contains one of the options tt(-p) or tt(-P), the words following are taken to be patterns. The function will be -called when completion is attempt for a command or context that matches +called when completion is attempted for a command or context that matches one of the patterns. The options tt(-p) and tt(-P) are used to specify patterns to be tried before or after other completions respectively. Hence tt(-P) may be used to specify default actions. @@ -206,7 +206,7 @@ can be bound to any other keys using tt(bindkey) as usual. ) item(tt(#compdef -K) var(widget-name) var(style) var(key-sequences) ...)( This is similar to tt(-k) except that only one var(key-sequences) -argument may be given for each var(widget-name) var(style) parir. +argument may be given for each var(widget-name) var(style) pair. However, the entire set of three arguments may be repeated with a different set of arguments. Note in particular that the var(widget-name) must be distinct in each set. If it does not begin with @@ -263,7 +263,7 @@ an `tt(=)' ) kindex(-command-, completion context) item(tt(-command-))( -A word In command position +A word in command position ) kindex(-condition-, completion context) item(tt(-condition-))( @@ -317,13 +317,13 @@ enditem() Default implementations are supplied for each of these contexts. In most cases the context tt(-)var(context)tt(-) is -implemented by the function tt(_)var(context), for example the context -`tt(-tilde-)' and the function `tt(_tilde)'). +implemented by a corresponding function tt(_)var(context), for example +the context `tt(-tilde-)' and the function `tt(_tilde)'). The contexts tt(-redirect-) and tt(-value-) allow extra context-specific information. (Internally, this is handled by the functions for each context calling the function tt(_dispatch).) The extra -information is added separate by commas. +information is added separated by commas. For the tt(-redirect-) context, the extra information is in the form `tt(-redirect-,)var(op)tt(,)var(command)', where var(op) is the @@ -334,7 +334,7 @@ field will be empty. For the tt(-value-) context, the form is `tt(-value-,)var(name)tt(,)var(command)', where var(name) is the name of the parameter. In the case of elements of an associative array, for -example `tt(assoc=LPAR()key <TAB>)', var(name) is eexpanded to +example `tt(assoc=LPAR()key <TAB>)', var(name) is expanded to `var(name)tt(-)var(key)'. In certain special contexts, such as completing after `tt(make CFLAGS=)', the var(command) part gives the name of the command, here tt(make); otherwise it is empty. @@ -530,7 +530,7 @@ As an example, the context name example(tt(:completion::complete:dvips:option-o-1:files)) -says that normal completion was attempted as the first arguement to the +says that normal completion was attempted as the first argument to the option tt(-o) of the command tt(dvips): example(tt(dvips -o ...)) @@ -544,7 +544,7 @@ likes, but a list of the more common ones is given below. Usually completion will be tried by all possible tags in an order given by the completion function. However, this can be altered by using the -tt(tag-order) style. Completion is then limited to the list of given +tt(tag-order) style. Completion is then restricted to the list of given tags in the given order. The tt(_complete_help) bindable command shows all the contexts and tags @@ -610,7 +610,7 @@ example(zstyle -e ':completion:*' completer ' uses the value `tt(_complete)' for the tt(completer) style in most contexts, but the value `tt(_complete _approximate)' when the first word -on the command line is `tt(cvs)'. This is probably more conviently done +on the command line is `tt(cvs)'. This is probably more conveniently done by specifying the style for two different contexts. This form can be slow and should be avoided for commonly examined styles such as tt(menu) and tt(list-rows-first). @@ -1104,13 +1104,12 @@ function below. ) kindex(call-command, completion style) item(tt(call-command))( -Currently this is only used by the function completing tt(make) -targets. If it is set to `true' and the installed version of the -tt(make) command allows it, tt(make) is called in such a way as to -generate all possible targets. The default value of this style is `false' -since calling tt(make) can potentially take a very long time and in -some cases may even cause actions from the makefile be executed -despite the options passed to tt(make). +This style is used in the function for commands such as tt(make) and +tt(ant) where calling the command directly to generate matches suffers +problems such as being slow or, as in the case of tt(make) can +potentially causes actions in the makefile to be executed. If it is set +to `true' the command is called to generate matches. The default value +of this style is `false'. ) kindex(command, completion style) item(tt(command))( @@ -1232,13 +1231,13 @@ However, menu completion can be used to cycle through all matches. kindex(fake, completion style) item(tt(fake))( This style may be set for any completion context. It -specifies additional strings that may always be completed in that +specifies additional strings that will always be completed in that context. The form of each string is `var(value)tt(:)var(description)'; the colon and description may be omitted, but any literal colons in var(value) must be quoted with a backslash. Any var(description) provided is shown alongside the value in completion listings. -It is important to use a sufficiently restricted context when specifying +It is important to use a sufficiently restrictive context when specifying fake strings. Note that the styles tt(fake-files) and tt(fake-parameters) provide additional features when completing files or parameters. ) @@ -1282,7 +1281,7 @@ which are not used. Its value consists of elements of the form such specifications separated by spaces. The var(pattern) is a pattern that is to be used to generate filenames. -Any occurence of the sequence `tt(%p)' is replaced by any pattern(s) +Any occurrence of the sequence `tt(%p)' is replaced by any pattern(s) passed by the function calling tt(_files). Colons in the pattern must be preceded by a backslash to make them distinguishable from the colon before the var(tag). If more than one pattern is needed, the patterns @@ -1436,8 +1435,8 @@ named tt(-default-). ) kindex(group-order, completion style) item(tt(group-order))( -This style is additional the tt(group-name) style to put the groups -defined by that style into order for display (compare tt(tag-order), +This style is additional to the tt(group-name) style to specify the +order for display of the groups defined by that style (compare tt(tag-order), which determines which completions appear at all). The groups named are shown in the given order; any other groups are shown in the order defined by the completion function. @@ -1535,7 +1534,7 @@ completed, not when completing names of files. enditem() Excluded values act in a similar fashion to values of the -tt(ignored-patterns) style, so they can be restored to consideratoin by +tt(ignored-patterns) style, so they can be restored to consideration by the tt(_ignored) completer. ) kindex(ignored-patterns, completion style) @@ -1567,10 +1566,10 @@ style is set explicitly to `tt(menu)') the name will be converted immediately to a set of possible IDs, and menu completion will be started to cycle through them. -If the value of the style is `tt(single)' +If the value of the style is `tt(single)', the shell will wait until the user has typed enough to make the command unique before converting the name to an ID; attempts at completion will -be unsuccessul until that point. If the value is any other +be unsuccessful until that point. If the value is any other string, menu completion will be started when the string typed by the user is longer than the common prefix to the corresponding IDs. ) @@ -1597,9 +1596,9 @@ tt(vared) builtin command where it is `false'. kindex(insert-unambiguous, completion style) item(tt(insert-unambiguous))( This is used by the tt(_match) and tt(_approximate) completers. -These styles are often used with menu completion since the word typed +These completers are often used with menu completion since the word typed may bear little resemblance to the final completion. -However, if this the style is `true', the completer will start menu +However, if this style is `true', the completer will start menu completion only if it could find no unambiguous initial string at least as long as the original string typed by the user. @@ -1666,7 +1665,7 @@ use group names specified explicitly by the tt(group-name) tag together withe the `tt((group))' syntax allowed by the tt(ZLS_COLORS) and tt(ZLS_COLOURS) parameters and simply using the tt(default) tag. -It is possible to use any color specifications alrady set up for the GNU +It is possible to use any color specifications already set up for the GNU version of the tt(ls) command: example(zstyle ':completion:*:default' list-colors ${(s.:.)LS_COLORS}) @@ -1781,8 +1780,8 @@ ifnzman(noderef(Matching Control))\ ) kindex(matcher-list, completion style) item(tt(matcher-list))( -This style is a list of match specifications that are valid everywhere. -Match specifications are described in +This style can be set to a list of match specifications that are to +be applied everywhere. Match specifications are described in ifzman(the section `Matching Control' in zmanref(zshcompwid))\ ifnzman(noderef(Matching Control))\ . @@ -1829,7 +1828,7 @@ one element. Where multiple specifications are useful, note that the em(entire) completion is done for each element of tt(matcher-list), which can -quickly reduce the shell's performance. As a rough rule of thum, +quickly reduce the shell's performance. As a rough rule of thumb, one to three strings will give acceptable performance. On the other hand, putting multiple space-separated values into the same string does not have an appreciable impact on performance. @@ -1892,9 +1891,9 @@ tt(MENU_COMPLETE) option and other settings. In the form `tt(yes=)var(num)', where `tt(yes)' may be any of the true values (`tt(yes)', `tt(true)', `tt(on)' and `tt(1)'), -menu completion will be turned on if there at least var(num) matches. +menu completion will be turned on if there are at least var(num) matches. In the form `tt(yes=long)', menu completion will be turned on -if the list does not fit onto the screen. This does not activate menu +if the list does not fit on the screen. This does not activate menu completion if the widget normally only lists completions, but menu completion can be activated in that case with the value `tt(yes=long-list)' (Typically, the value `tt(select=long-list)' described later is more @@ -1905,9 +1904,9 @@ completion will em(not) be used if there are var(num) or more matches. The value of this widget also controls menu selection, as implemented by the tt(zsh/complist) module. The following values may appear either -alongside or instead of the values bbavoe. +alongside or instead of the values above. -If the value contains the string `tt(select)', menu selection (as +If the value contains the string `tt(select)', menu selection will be started unconditionally. In the form `tt(select=)var(num)', menu selection will only be started if @@ -1923,7 +1922,7 @@ matches does not fit on the screen by using the value only performs listing, use the value `tt(select=long-list)'. To turn on menu completion or menu selection when a there are a certain -number of matches em(or) the list of matches does not fit onto the +number of matches em(or) the list of matches does not fit on the screen, both of `tt(yes=)' and `tt(select=)' may be given twice, once with a number and once with `tt(long)' or `tt(long-list)'. @@ -1983,7 +1982,7 @@ kindex(old-matches, completion style) item(tt(old-matches))( This is used by the tt(_all_matches) completer to decide if an old list of matches should be used if one exists. This is selected by one of -the `true' values or to the string `tt(only)'. If +the `true' values or by the string `tt(only)'. If the value is `tt(only)', tt(_all_matches) will only use an old list and won't have any effect on the list of matches currently being generated. @@ -2048,7 +2047,7 @@ defaults to `tt(~/mail)'. ) kindex(ports, completion style) item(tt(ports))( -A a list of Internet service names (network ports) to complete. If this is +A list of Internet service names (network ports) to complete. If this is not set, service names are taken from the file `tt(/etc/services)'. ) kindex(prefix-hidden, completion style) @@ -2146,6 +2145,9 @@ manual pages. If it is `true', entries for different sections are added separately using tag names of the form `tt(manual.)var(X)', where var(X) is the section number. When the tt(group-name) style is also in effect, pages from different sections will appear separately. +This style is also used similarly with the tt(words) style when +completing words for the dict command. It allows words from different +dictionary databases to be added separately. The default for this style is `false'. ) kindex(single-ignored, completion style) @@ -2355,7 +2357,7 @@ command to specify conditions for the use of particular tags. For example: example(zstyle -e '*:-command-:*' tag-order ' - if [[ -n $PREFIX ]]; then + if [[ -n $PREFIX$SUFFIX ]]; then reply=( ) else reply=( - ) @@ -2626,13 +2628,15 @@ tt(-)var(context)tt(-) are handled specifically. These are all mentioned above as possible arguments to the tt(#compdef) tag. Before trying to find a function for a specific context, tt(_complete) -checks if the parameter `tt(compcontext)' is set. If it is set to an -array, the elements are taken to be the possible matches which will be -completed using the tag `tt(values)' and the description -`tt(value)'. If it is set to an associative array, the keys are used -as the possible completions and the values (if non-empty) are used as -descriptions for the matches. If `tt(compcontext)' is set to a string -containing colons, it should be of +checks if the parameter `tt(compcontext)' is set. Setting +`tt(compcontext)' allows the usual completion dispatching to be +overridden which is useful in places such as a function that uses +tt(vared) for input. If it is set to an array, the elements are taken +to be the possible matches which will be completed using the tag +`tt(values)' and the description `tt(value)'. If it is set to an +associative array, the keys are used as the possible completions and +the values (if non-empty) are used as descriptions for the matches. If +`tt(compcontext)' is set to a string containing colons, it should be of the form `var(tag)tt(:)var(descr)tt(:)var(action)'. In this case the var(tag) and var(descr) give the tag and description to use and the var(action) indicates what should be completed in one of the forms @@ -3077,7 +3081,7 @@ Like tt(_tags) this function supports the tt(-C) option to give a different name for the argument context field. ) findex(_arguments) -item(tt(_arguments) [ tt(-ACS) ] [ tt(-O) var(name) ] [ tt(-M) var(matchspec) ] [ tt(:) ] var(spec) ...)( +item(tt(_arguments) [ tt(-swWACRS) ] [ tt(-O) var(name) ] [ tt(-M) var(matchspec) ] [ tt(:) ] var(spec) ...)( This function can be used to give a complete specification for completion for a command whose arguments follow standard UNIX option and argument conventions. The following forms specify individual sets of @@ -3088,7 +3092,7 @@ startitem() xitem(var(n)tt(:)var(message)tt(:)var(action)) item(var(n)tt(::)var(message)tt(:)var(action))( This describes the var(n)'th normal argument. The var(message) will be -printed above the matches generated and the var(action) indiciates what can +printed above the matches generated and the var(action) indicates what can be completed in this position (see below). If there are two colons before the var(message) the argument is optional. If the var(message) contains only white space, nothing will be printed above @@ -3241,8 +3245,9 @@ Any literal colon in an var(optname), var(message), or var(action) must be preceded by a backslash, `tt(\:)'. Each of the forms above may be preceded by a list in parentheses -of option names and argument numbers. If the given option is completed, -the options and arguments indicated will not be offered. For example, +of option names and argument numbers. If the given option is on +the command line, the options and arguments indicated in parentheses +will not be offered. For example, `tt((-two -three 1)-one:...)' completes the option `tt(-one)'; if this appears on the command line, the options tt(-two) and tt(-three) and the first ordinary argument will not be completed after it. @@ -3296,7 +3301,7 @@ Note the backslash before the colon. For example, example(tt(:foo:LPAR()LPAR()a\:bar b\:baz)tt(RPAR()RPAR())) The matches will be listed together with their descriptions if the -tt(description) style is set in the context with the tt(values) tag. +tt(description) style is set with the tt(values) tag in the context. ) item(tt(->)var(string))( vindex(context, use of) @@ -3308,20 +3313,22 @@ state of processing; the calling function then makes its own arrangements for generating completions. For example, functions that implement a state machine can use this type of action. -If tt(_arguments) handles the completion by itself, it returns status -zero. Otherwise, it returns a non-zero status; if this was because it -encountered a `tt(->)var(string)' action, it will strip all leading and -trailing whitespace from var(string) and set the array tt(state) to the set -of all var(strings)s for which the action is to be performed. Hence -tt($state) must be tested to determine whether actions need to be handled. - -If the tt(-R) option is given to tt(_arguments), the function will instead -return a status of 300 to indicate that tt($state) is valid. In this case -it also sets the global parameters `tt(context)', `tt(line)' and -`tt(opt_args)' as described below, and does not reset any changes made to -the special parameters such as tt(PREFIX) and tt(words). This gives the -calling function the choice of resetting these parameters or propagating -changes in them. +Where tt(_arguments) encounters a `tt(->)var(string)', it will strip +all leading and trailing whitespace from var(string) and set the array +tt(state) to the set of all var(strings)s for which an action is to be +performed. + +By default and in common with all other well behaved completion +functions, _arguments returns zero if it was able to add matches and +non-zero otherwise. However, if the tt(-R) option is given, +tt(_arguments) will instead return a status of 300 to indicate that +tt($state) is to be handled. + +In addition to tt($state), tt(_arguments) also sets the global +parameters `tt(context)', `tt(line)' and `tt(opt_args)' as described +below, and does not reset any changes made to the special parameters +such as tt(PREFIX) and tt(words). This gives the calling function the +choice of resetting these parameters or propagating changes in them. A function calling tt(_arguments) with at least one action containing a `tt(->)var(string)' therefore must declare @@ -3473,12 +3480,16 @@ can be completed to `tt(-foo-bar)'. The option tt(-C) tells tt(_arguments) to modify the tt(curcontext) parameter for an action of the form `tt(->)var(state)'. This is the standard parameter used to keep track of -the current context. Here it should be made local to the calling function +the current context. Here it (and not the tt(context) array) should be +made local to the calling function to avoid passing back the modified value and should be initialised to the current value at the start of the function: example(local curcontext="$curcontext") +This is useful where it is not possible for multiple states to be valid +together. + The option `tt(--)' allows tt(_arguments) to work out the names of long options that support the `tt(-)tt(-help)' option which is standard in many GNU commands. The command word is called with the argument @@ -3655,7 +3666,7 @@ the functions for the fields if they are called. ) findex(_describe) item(tt(_describe) [ tt(-o) | tt(-t) var(tag) ] var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)( -This option associates completions with descriptions. +This function associates completions with descriptions. Multiple groups separated by tt(-)tt(-) can be supplied, potentially with different completion options var(opts). |