diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/Zsh/compsys.yo | 537 |
1 files changed, 299 insertions, 238 deletions
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index c2ae6f7af..ba863cfe8 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -264,179 +264,77 @@ texinode(Completion System Configuration)(Control Functions)(Initialization)(Com sect(Completion System Configuration) cindex(completion system, configuration) -The completion system allows users to configure many aspects of how -and when matches are generated. After a short overview of how the -completion system works, this section describes how this can be done. +This section gives a short overview of how the completion system works, +and then more detail on how users can configure how and when matches are +generated. subsect(Overview) When completion is attempted somewhere on a command line the completion system first tries to find out the context where completion -was tried. Such a context depends, for example, on the name of the -command when completing an argument. Or it may depend on both the name -of a command and the name of an option when completing after one that -takes arguments. - -The completion system represents such a context as a hierarchical name -with components separated by colons. For example the name -tt(:complete::dvips::-o-1) is used when completing the first argument of -the tt(-o) option of the tt(dvips) command. The tt(:complete) at the -beginning just says that we are currently trying completion as opposed -to, say, correction, which can also be done using the function based -completion system (see +was tried. The context depends on such things as the name of the +command when completing an argument, and possibily also +the name of an option when completing an argument to that option. + +The completion system represents contexts as hierarchical name s +with components separated by colons. For example, take the context +`tt(:complete::dvips::-o-1)'. The tt(:complete) at the +beginning is the `completer', which is in overall control of how completion +is to be performed; `tt(complete)' is the basic one for +ordinary completion, but completers may perform various related tasks +such as correction, or modify the behaviour of a later completer (see ifzman(the section `Control Functions' below)\ ifnzman(noderef(Control Functions)) -for more information). The tt(::dvips:) shows that we are -completing arguments for the tt(dvips) command. Such a doubled colon +for more information). Strictly, the completer is `tt(_complete)', but the +underscore is omitted from the context; this is also true of `tt(correct)', +`tt(approximate)', etc. The tt(::dvips:) shows that we are +completing arguments for the tt(dvips) command. The doubled colon will appear only before and after the name of the command, but note -that the second colon after the command name is really only added when +that the second colon after the command name is only added when there is at least one more component (otherwise the whole name ends in -a colon). +a colon, e.g. `tt(...dvips:)'). Finally, the string tt(-o-1) says that we +are completing the first argument of the option `tt(-o)' to the command. +Note that the existence of a context like this does not necessarily mean it +is handled specially by the completion system; this is determined by trying +to match the context as specifically as possible, as described below. In many of the possible contexts the completion system can generate -matches, and often it can generate multiple types of matches. Whenever -a completion function is about to generate such matches it first calls -a utility function, telling it what types of matches can be -generated. These types are represented as simple names called -`tags'. This utility function in turn calls another function -(tt(_sort_tags)) and gives the list of tags to it as -arguments. The function tt(_sort_tags) can then say in which order the -tags are to be used by the completion function. The function will -only generate those types of matches whose tags were selected by the -user's implementation of the tt(_sort_tags) function. And it will -try to generate the different types of matches in the order in which -they were specified by tt(_sort_tags). - -Inside the tt(_sort_tags) function the name of the current context can -be accessed using the tt(curcontext) parameter. For example, the -function generating file names (called tt(_files)) in the completion -system is often called to generate only filenames matching a given -glob pattern and then uses the tags tt(globbed-files), -tt(directories), and tt(all-files). This means that the function -offers to generate filenames matching the pattern, names of -directories or all filenames as possible matches. Example: - -example(_sort_tags() { - case $curcontext in - (*::dvips:*) - comptry globbed-files directories - comptry all-files - ;; - (*) - comptry globbed-files - comptry directories - comptry all-files - ;; - esac -}) - -Every call to the tt(comptry) function (well, it's actually a builtin -command defined by the tt(computil) module, but never mind) gives a -set of tags to use. So, the first call says which tags are to be used -first. If there are no matches for those tags, the tags from the -second call to tt(comptry) will be tried, and so on. In the example -this means that for the tt(dvips) command on the first attempt the -names of DVI files and directories will be generated (first call to -tt(comptry)). If none of those names match the string from the command -line the completion function will generate all filenames as -possible matches (second call to tt(comptry)). - -For all other context names the second case-pattern matches, so that -normally the completion functions will only try the filenames matching -the glob pattern (if any glob pattern is used). If that doesn't yield -any matches, names of directories are generated, and if that doesn't -yield any matching names either, all filenames will be generated. - -In every context the tt(_sort_tags) function may call tt(comptry) as -often as it wants. Also, every string may be given as argument, even -if no tag with such a name was offered by the completion -function. This allows one to give a preferred ordering for some common -tag sets without having to worry about sensible patterns for context -names. For example, many completion functions can generate both -arguments and option names for commands. These functions normally use -the tags tt(arguments) and tt(options). Depending on your preference -you may write in your tt(_sort_tags) function: - -example(_sort_tags() { - comptry arguments options - case $curcontext in - ... - esac -}) - -or - -example(_sort_tags() { - comptry arguments - comptry options - case $curcontext in - ... - esac -}) - -The former always adds both the matches for the argument and the -option names as possible matches. The latter makes the matches for the -arguments be preferred. In this case option names are only generated -as matches if the string on the line matches no possible completion -for the argument, which normally means that you have to type the -hyphen the option names start with yourself to see the list of option -names that can be completed. - -Since the completion functions are free to choose the tag names they -use, there can't be a complete list. So to make sure that all types of -matches are eventually tried as completions, one should use a call to -tt(comptry) with all arguments at the end of tt(_sort_tags). For those -contexts where one really wants to make sure that certain tags are -never used one can then use a call to tt(return) to circumvent that -last tt(comptry). For example: - -example(_sort_tags() { - ... - case $curcontext in - (*::kill:*) - comptry processes - return - ;; - esac - comptry "$@" -}) - -The completion function for the tt(kill) builtin command offers the -tags tt(jobs) and tt(processes) which represent job references -(e.g. `tt(%1)') and process identifiers respectively. The function -above makes sure that for this builtin command only process -identifiers are generated as possible matches by using only the -tt(processes) tag in a call to tt(comptry). The immediate call to -tt(return) then makes sure that the default tt(comptry) at the end is -not executed. +matches, often multiple types of matches. These types are represented as +simple names called `tags'. The completion system will decide internally +what sort of tags are allowed; a list of the standard possibilities is given +below. The list of tags is passed as the arguments of the function +(tt(_sort_tags)), which can then determine the order in which the tags are +to be used by the completion function. Only those types of matches whose +tags were selected by the tt(_sort_tags) function will be produced, and in +the order given. Instead of altering tt(_sort_tags), you may define +a `tt(sort-tags)' style for the appropriate context, as described in the +list of standard styles below. The tt(_complete_help) bindable command described in ifzman(the section `Bindable Commands' below)\ ifnzman(noderef(Bindable Commands)) -can be used to find out the contexts and tag names used by completion -functions. If it is invoked, it shows a list of context names and the +can be invoked to find out the context and tag names used at a particular +point in completion. It shows a list of context names and the tag names used in those contexts if completion were tried at the -current cursor position. This allows one to easily find out all the -information needed to change the tt(_sort_tags) function when one -wants to change the way matches are generated for that context. +current cursor position. Hence one can easily find out all the +information needed to change the behaviour of the tt(_sort_tags) function +or the tt(sort_tags) style for a particular context. -But the completion system can not only be configured by supplying a -specialized tt(_sort_tags) function. It also uses `styles' defined -with the tt(zstyle) builtin command (see +Completion behaviour can be modified by various other +`styles' defined with the tt(zstyle) builtin command +(see ifzman(zmanref(zshmodules))\ -ifnzman(noderef(The zutil Module))\ -) using the prefix `tt(:completion)' and the context name when testing -and retrieving values. - -For some tags the completion functions look up the definition of -certain styles set for the current context. These styles can have any -number of strings as their values and specify, for example, how the -matches are generated. The tt(zstyle) builtin command defines mappings -between patterns and style names with their values. Whenever a -completion function looks up the value of a style it uses the name of -the current context followed by a colon and the name of a tag. This -combined name and the name of a style is then compared to all patterns -and the value of the style for the first matching pattern is used. +ifnzman(noderef(The zutil Module))). +The full context used in looking up styles is the prefix `tt(:completion)' +followed by the context as described above, followed by another colon and +the name of the tag currently being tried for completion. + +Styles determine such things as how the matches are generated; some of them +correspond to shell options (for example, the use of menu completion), but +styles provide more specific control. They can have any number of strings as +their value. Looking up the value of a style therefore consists of two +things: the context, which may be matched as a pattern, and the name of +the style itself, which must be given exactly. For example, many completion functions can generate matches in a simple and a verbose form and use the tt(verbose) style to decide @@ -447,29 +345,32 @@ example(zstyle ':completion:*' verbose yes) in one of the startup files like tt(.zshrc). This definition simply means that the tt(verbose) style has tt(yes) as its value in every -context. +context inside the completion system. If the pattern were `tt(*)', it +would mean that the verbose style had this value anywhere the style +mechanism is used. -The completion function for the tt(kill) builtin command uses this -style to decide if jobs and processes are listed only as job numbers -and process identifiers or if they are listed with the full job texts -and the command lines of the processes (the latter is achieved by -calling the tt(ps) command). To make this builtin list the matches -only as numbers one could call: +As a more specific example, the completion function for the tt(kill) +builtin command uses the tt(verbose) style to decide if jobs and processes +are listed only as job numbers and process identifiers or if they are +listed with the full job texts and the command lines of the processes (the +latter is achieved by calling the tt(ps) command). To make this builtin +list the matches only as numbers one could call: example(zstyle ':completion:*::kill:*' verbose no) -And if one wants to see the command lines for processes but not the +Furhtermore, if one wanted to see the command lines for processes but not the job texts one could use the fact that the tag name is appended to the -context name when styles are looked up and instead of the previous -call use (remember that the function for the tt(kill) builtin command -uses the tags tt(jobs) and tt(processes)): +context name when styles are looked up. As the function for the tt(kill) +builtin command uses the tags tt(jobs) and tt(processes), we have: example(zstyle ':completion:*::kill:*:jobs' verbose no) -Due to the ordering tt(zstyle) does with the patterns defined, the -last two examples could be defined after the first one because both -`tt(*::kill:*)' and `tt(*::kill:*:jobs)' are considered to be more -specific then the pattern `tt(*)' from the first example. +Note that the order in which styles are em(defined) does not matter; the +style mechanism uses the most specific possible match for a particular +style to determine the set of values. More precisely, strings are +preferred over patterns (for example, `tt(:completion:complete:foo)' is +more specific than `tt(:completion:complete:*')), and longer patterns are +preferred over shorter patterns. As for tags, completion functions can use any number of styles, so there can't be a complete list. However, the following two sections @@ -480,8 +381,8 @@ subsect(Standard Tags) cindex(completion system, tags) Here are the tags currently used by the completion system. Note that -some of these tags are not really used when generating mathes but -instead are only used by some completion functions when looking up +some of these tags are not actually used while generating matches, +but are only used by some completion functions when looking up styles. startitem() @@ -523,7 +424,8 @@ for names of external commands and names of sub-commands (used by some commands like tt(cvs)) ) item(tt(corrections))( -used by the tt(_approximate) completer for the possible corrections +used by the tt(_approximate) and tt(_correct) completers for the possible +corrections ) item(tt(cursors))( for cursor names used by X programs @@ -630,8 +532,8 @@ item(tt(options))( for command options ) item(tt(original))( -used by the tt(_approximate) and tt(_expand) completers when adding -the original string +used by the tt(_approximate), tt(_correct) and tt(_expand) completers when +adding the original string ) item(tt(other-accounts))( used to look up the tt(users-hosts) style @@ -730,7 +632,7 @@ startitem() item(tt(accept-exact))( This is tested for the default tag and the tags used when generating matches. If it is set to `true' for at least one match which is the -same as the string on the line, this match will immediatly be +same as the string on the line, this match will immediately be accepted. ) item(tt(arguments))( @@ -787,8 +689,8 @@ item(tt(condition))( This style is used by the tt(_list) completer function. If it is not set or set to the empty string, the insertion of -matches will be delayed unconditionally. If this value is set, it -should be set to an expression usable inside a `tt($((...)))' +matches will be delayed unconditionally. If it is set, the value +should be an expression usable inside a `tt($((...)))' arithmetical expression. In this case, delaying will be done if the expression evaluates to `tt(1)'. For example, with @@ -910,15 +812,15 @@ the file `tt(/etc/group)' will be used. ) item(tt(hidden))( If this is set to one of the `true' values, the matches for the tags -for which this is set will not appear in the list, only the +for which this is set will not appear in the list; only the description for the matches as set with the tt(format) style will be shown. If this is set to tt(all), not even the description will be displayed. Note that the matches will still be completed, they are just not shown -in the list. To avoid having some matches to be considered possible -completions one can modify the tt(_sort_tags) function as described -above. +in the list. To avoid having matches considered as possible +completions at all the tt(_sort_tags) function can be modified as described +below. ) item(tt(hosts))( A style holding the names of hosts that should be completed. If this @@ -939,7 +841,8 @@ containing strings of the form `var(host)tt(:)var(port)tt(:)var(user)'. item(tt(ignored-suffixes))( This style is used with the tt(files) tag and gives suffixes of filenames to ignore. The matches ignored will only be completed when -there are no other matches. +there are no other matches. It it is a more configurable version +of the shell parameter tt($fignore). ) item(tt(insert-unambiguous))( This is used by the tt(_match) and tt(_approximate) completer @@ -958,9 +861,10 @@ this is independent of the numeric argument -- unlike the tt(ALWAYS_LAST_PROMPT) option. ) item(tt(list))( -This is used by the tt(_oldlist) completer, the -tt(_history_complete_word) bindable command and by the -tt(incremental-complete-word) widget. +This is used by the tt(_oldlist) completer (context +`tt(:completion:oldlist)'), the tt(_history_complete_word) bindable command +(context `tt(:completion:history-words)') and by the +tt(incremental-complete-word) widget (context `tt(:completion:incremental)). For tt(_oldlist), if this is set to tt(always), then standard widgets which perform listing will retain the current list of matches, @@ -1042,9 +946,9 @@ directory name used by a user placing web pages within their home area. ) item(tt(max-errors))( -This is used by the tt(_approximate) completer function to determine -the maximum number of errors to accept. The completer will try to -generate completions by first allowing one error, then two errors, and +This is used by the tt(_approximate) and tt(_correct) completer functions +to determine the maximum number of errors to accept. The completer will try +to generate completions by first allowing one error, then two errors, and so on, until either a match was found or the maximum number of errors given by this style has been reached. @@ -1059,7 +963,7 @@ with a numeric argument of six (as in `tt(ESC-6 TAB)'), up to six errors are accepted. Hence with a value of `tt(0 numeric)', no correcting completion will be attempted unless a numeric argument is given. -If the value contains the string tt(not-numeric), tt(_approximate) +If the value contains the string tt(not-numeric), the completer will em(not) try to generate corrected completions when given a numeric argument, so in this case the number given should be greater than zero. For example, `tt(2 not-numeric)' specifies that @@ -1109,11 +1013,11 @@ appears. With tt(_oldlist), it will instead continue to cycle through the list of completions. ) item(tt(original))( -This is used by the tt(_approximate) and tt(_match) completers. The -first one uses it to decide if the original string should be added as -one possible completion. Normally, this is done only if there at least -two possible corrections, but if this style is set to `true', it will -always be added. +This is used by the tt(_approximate), tt(_correct) and tt(_match) +completers. The first two use it to decide if the original string should +be added as one possible completion. Normally, this is done only if there +at least two possible corrections, but if this style is set to `true', it +will always be added. For the tt(_match) completer, if this style is set to tt(only), it will try to generate matches without inserting a @@ -1192,6 +1096,31 @@ to tt(menu), then the expansions are only sorted when they are offered as single strings (not in the string containing all possible expansions). ) +item(tt(sort-tags))( +This provides a mechanism for sorting how the tags available in a +particular context will be used. It assumes you have not redefined the +standard tt(_sort_tags) function. + +The values for the style are sets of space-separated lists of tags. +The tags in each value will be tried at the same time; if no match is +found, the next value is used. + +For example, + +example( + zstyle :completion:complete::gunzip: sort-tags \ + 'globbed-files directories' all-files +) + +specifies that, when completing arguments of the command tt(gunzip), +files generated by patterns (in this case, those ending in tt(.gz)) and +any directories will be presented first, and if that fails, any other files +will be tried. If no valid tags are present, nothing will be completed. so +this can be used to turn off completion in a particular context. + +If no style has been defined for a context, the tt(_sort_tags) function +provides defaults, as given below. +) item(tt(special-dirs))( Normally, the completion code will not produce the directory names tt(.) and tt(..) as possible completions. If this style is set to @@ -1470,7 +1399,7 @@ adding the possible expansions as single matches and tt(original) when adding the original string from the line. In which order these strings are generated and which of these strings are generated at all can be controlled by using the tt(group-order) style and by modifying the -tt(_sort_tags) function, as usual. +tt(sort-tags) style or tt(_sort_tags) function, as usual. The format string for tt(all-expansions) and for tt(expansions) may contain the sequence `tt(%o)' which will be replaced by the original @@ -1583,7 +1512,7 @@ completions. Unambiguous parts of the function name will be completed automatically (normal completion is not available at this point) until a space is typed. -Otherwise, any other string, will be passed as arguments to +Any other string will be passed as a set of arguments to tt(compadd) and should hence be an expression specifying what should be completed. @@ -1689,9 +1618,9 @@ compadd "$expl[@]" - "$files[@]") ) findex(_message) item(tt(_message) var(descr))( -The var(descr) used like the third +The var(descr) is used like the third argument to the tt(_description) function. However, the resulting -string will always be shown, not only if some matches were +string will always be shown whether or not matches were generated. This is useful to display help texts in places where no completions can be generated automatically. @@ -2286,63 +2215,61 @@ of tt(context) (as described above). findex(_regex_arguments) item(tt(_regex_arguments) var(name) var(specs) ...)( This function is a compiler to generate a completion function. The -first argument specifies the name of generated function and rest arguments -specifies a completion specification in the notation like regular -expression with acions. The generated function is formed as a state -machine whose state corresponds each part of the specification of the -completion. The state machine runs on a command line and evaluate actions -when the command line is exhausted. The command line is represented by -single string that is generated by concatinating unquoted tt(words) -(before tt(CURRENT)) and tt(PREFIX) using the null character as a -separator. - -The specification is one of following forms. (Metacharacters such as -`tt(LPAR())', `tt(RPAR())', `tt(#)' and `tt(|)' should be quoted.) +first argument specifies the name of a generated function while the +remaining arguments specify a completion as a set of regular +expressions with actions. The generated function has the structure of a +finite-state machine whose state corresponds to the state (i.e. the +context) of the completion. This state machine uses a command line, +which comes from concatentating the tt(words) array up to the current +cursor position using null characters as a separator with no extra +quotation. This is analysed and at the end the appropriate action is +executed. + +Specification arguments take one of following forms, in which +metacharacters such as `tt(LPAR())', `tt(RPAR())', `tt(#)' and `tt(|)' +should be quoted. + startitem() item(tt(/)var(pattern)tt(/) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(action)])( -This is a primitive element for the specification and corresponds to the -state of the compiled state machine. When the state machine is trying to -enter to this state, the state machine tries to match the pattern -`tt((#b)LPAR()(#B))var(pattern)tt(RPAR()(#B))var(lookahead)tt(*)' against to +This is a primitive element, corresponding to one +state of the compiled state machine. The state is entered if the pattern +`tt((#b)LPAR()(#B))var(pattern)tt(RPAR()(#B))var(lookahead)tt(*)' matches the command line string. If it is matched, `var(guard)' is evaluated and -its return status is examined. If it is success, the state machine is -entered to this state. Otherwise when the pattern match or the guard -evaluation is failed, the state machine is failed to enter to this state -and other candidates are tried. If `var(pattern)' is the string `tt([])', -it is treated as the pattern which never match. - -When the state machine is entered to this state, the left part of the -command line string matched against to `var(pattern)' is removed and next -states of this state are tried to enter with inner-to-outer, left-to-right -fashion. - -If all tries are failed and remaining command line string contains no null -character, completion target is restricted to correspondence of remaining -command line string and `var(action)'s for the target is evaluated. Since -this state may not remove non-empty string from command line string, -prior states and its neighborhoods may have `var(actions)'s for the -target. +its return status is examined; if this is successful, the state is entered, +else the test fails and other candidates are tried. The var(pattern) +string `tt([])' is guaranteed never to match. + +If the test succeeds and the state is entered, the left part of the +command line string matched as `var(pattern)' is removed and the +next state is tried, proceeding from inside to outside and from left to +right. + +If no test succeeds and the remaining command line string contains no null +character, the completion target is restricted to the remainder of the +command line string and `var(action)'s for the target are evaluated. +In this case, nothing is actually removed from the command line string +so that any previous or neighbouring state may also have `var(actions)'s. ) item(tt(/)var(pattern)tt(/+) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(action)])( This is similar to `tt(/)var(pattern)tt(/) ...' but the left part of command line string is also considered as part of the completion target. ) item(tt(/)var(pattern)tt(/-) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(action)])( -This is similar to `tt(/)var(pattern)tt(/) ...' but `var(action)'s of this -and prior states are ignored even if following state's `var(pattern)' -matches empty string. +This is similar to `tt(/)var(pattern)tt(/) ...' but `var(action)'s of the +current and previous states are ignored even if the following state's +`var(pattern)' matches the empty string. ) item(tt(LPAR()) var(spec) tt(RPAR()))( This groups `var(spec)'. ) item(var(spec) tt(#))( -This is repetation of `var(spec)'. +This allows any number of repetitions of `var(spec)'. ) item(var(spec) var(spec))( -This is concatination of two `var(spec)'s. +This represents the concatenation of two `var(spec)'s. ) item(var(spec) tt(|) var(spec))( -This is alternation of two `var(spec)'s. +Either of two `var(spec)'s can be matched. ) enditem() ) @@ -2384,6 +2311,140 @@ All arguments after the requested fieldname are given to the tt(compadd) used (when generating matches from the style value) and to the functions for the fields if they are called. ) +findex(_sort_tags) +item(tt(_sort_tags) var(tag) ...)( +As described above, this may be redefined by the user, although a default +implementation is provided. In most cases, you will probably find it +easier to define a tt(sort-tags) style for the context whose behaviour you +wish to alter. + +Inside the tt(_sort_tags) function the name of the current context can +be accessed using the tt(curcontext) parameter. For example, the +function generating file names (called tt(_files)) in the completion +system is often called to generate only filenames matching a given +glob pattern, in which case it uses the tags tt(globbed-files), +tt(directories), and tt(all-files). This means that the function +offers to generate filenames matching the pattern, names of +directories or all filenames as possible matches. Example: + +example(_sort_tags() { + case $curcontext in + (*::dvips:*) + comptry globbed-files directories + comptry all-files + ;; + (*) + comptry globbed-files + comptry directories + comptry all-files + ;; + esac +}) + +Every call to the tt(comptry) function (actually a builtin +command defined by the tt(computil) module) gives a +set of tags to use; as soon as tt(comptry) produces some matches, +subsequent calls have no effect. Hence in the example +this means that for the tt(dvips) command on the first attempt the +names of DVI files and directories will be generated (first call to +tt(comptry)). If none of those names match the string from the command +line the completion function will generate all filenames as +possible matches (second call to tt(comptry)). + +For all other context names the second case-pattern matches, so that +normally the completion functions will only try the filenames matching +the glob pattern (if any glob pattern is used). If that doesn't yield +any matches, names of directories are generated, and if that doesn't +yield any matching names either, all filenames will be generated. + +In every context the tt(_sort_tags) function may call tt(comptry) as +often as it wants. Also, every string may be given as argument, even +if no tag with such a name was offered by the completion +function. This allows one to give a preferred ordering for some common +tag sets without having to worry about sensible patterns for context +names. For example, many completion functions can generate both +arguments and option names for commands. These functions normally use +the tags tt(arguments) and tt(options). Depending on your preference +you may write in your tt(_sort_tags) function: + +example(_sort_tags() { + comptry arguments options + case $curcontext in + ... + esac +}) + +or + +example(_sort_tags() { + comptry arguments + comptry options + case $curcontext in + ... + esac +}) + +The former always adds both the matches for the argument and the +option names as possible matches. The latter forces matches for the +arguments to be preferred. In this case option names are only generated +as matches if the string on the line matches no possible completion +for the argument, which normally means that you have to type the +hyphen the option names start with yourself to see the list of option +names that can be completed. + +Since the completion functions are free to choose the tag names they +use, there can't be a complete list. So to make sure that all types of +matches are eventually tried as completions, one should use a call to +tt(comptry) with all arguments at the end of tt(_sort_tags). For those +contexts where one really wants to make sure that certain tags are +never used one can then use a call to tt(return) to circumvent that +last tt(comptry). For example: + +example(_sort_tags() { + ... + case $curcontext in + (*::kill:*) + comptry processes + return + ;; + esac + comptry "$@" +}) + +The completion function for the tt(kill) builtin command offers the +tags tt(jobs) and tt(processes) which represent job references +(e.g. `tt(%1)') and process identifiers respectively. The function +above makes sure that for this builtin command only process +identifiers are generated as possible matches by using only the +tt(processes) tag in a call to tt(comptry). The immediate call to +tt(return) then makes sure that the default tt(comptry) at the end is +not executed. + +The default implementation of tt(_sort_tags) is the following: + +example(_sort_tags() { + local stags tag + + if zstyle -a ":completion${curcontext}" sort-tags stags; then + for tag in $stags; do + [[ $tags != '' ]] && comptry ${=tag} + done + + else + comptry arguments values + comptry options + case "$curcontext" in + (*) comptry globbed-files + comptry directories + comptry all-files + ;; + esac + comptry "$@" + fi +}) + +) + enditem() texinode(Completion Directories)()(Completion Functions)(Completion System) |