diff options
author | Tanaka Akira <akr@users.sourceforge.net> | 1999-12-15 17:35:20 +0000 |
---|---|---|
committer | Tanaka Akira <akr@users.sourceforge.net> | 1999-12-15 17:35:20 +0000 |
commit | 8bc41ba869dbbd3c6bc2c8f2338c740311074f23 (patch) | |
tree | d595aeb0a5e399d4cb6a7dfd3818c395e9118ec0 /Doc/Zsh | |
parent | e401df24821d873eba579d2961a0886881b0acf6 (diff) | |
download | zsh-8bc41ba869dbbd3c6bc2c8f2338c740311074f23.tar.gz zsh-8bc41ba869dbbd3c6bc2c8f2338c740311074f23.tar.xz zsh-8bc41ba869dbbd3c6bc2c8f2338c740311074f23.zip |
manual/9058
Diffstat (limited to 'Doc/Zsh')
-rw-r--r-- | Doc/Zsh/compsys.yo | 111 |
1 files changed, 47 insertions, 64 deletions
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index ba863cfe8..07dca151c 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -302,13 +302,11 @@ In many of the possible contexts the completion system can generate 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. +below. To determine in which order the tags are to be used by the +completion function, the `tt(tag-order)' style for the appropriate +context may be set, as described in the list of standard styles below. +Only those types of matches whose tags were selected by this style +will be produced, and in the order given. The tt(_complete_help) bindable command described in ifzman(the section `Bindable Commands' below)\ @@ -317,8 +315,8 @@ 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. 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. +information needed to change the behaviour of the tt(tag-order) style +for a particular context. Completion behaviour can be modified by various other `styles' defined with the tt(zstyle) builtin command @@ -756,9 +754,9 @@ ifnzman(noderef(The zutil Module))\ . ) item(tt(glob))( -Like tt(complete), this is used by the tt(_expand) completer. +Like tt(completions), this is used by the tt(_expand) completer. -The value is used like the one for tt(complete) and if it evaluates to +The value is used like the one for tt(completions) and if it evaluates to `tt(1)', globbing will be attempted on the words resulting from substitution (see the tt(substitute) style) or the original string from the line. @@ -819,7 +817,7 @@ displayed. Note that the matches will still be completed, they are just not shown in the list. To avoid having matches considered as possible -completions at all the tt(_sort_tags) function can be modified as described +completions at all the tt(tag-order) style can be modified as described below. ) item(tt(hosts))( @@ -1012,6 +1010,15 @@ tt(TAB) at this point would start trying to complete the line as it now appears. With tt(_oldlist), it will instead continue to cycle through the list of completions. ) +item(tt(numbers))( +This is used with the tt(jobs) tag. If it is `true', the completions +will use the job numbers instead of the shortest unambiguous strings +of the jobs' command lines. If the value is a number, job numbers will +only be used if for at least one of the jobs that many (or more) words +from the command line string have to be used to make the strings +unambiguous. E.g. if it is set to `tt(1)', strings will only be used +if all jobs differ in the first word on their command lines. +) item(tt(original))( 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 @@ -1096,10 +1103,9 @@ 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))( +item(tt(tag-order))( 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. +particular context will be used. 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 @@ -1108,18 +1114,27 @@ found, the next value is used. For example, example( - zstyle :completion:complete::gunzip: sort-tags \ + zstyle :completion:complete::gunzip: tag-order \ '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. +will be tried. If any string in the value consists of only a hyphen +(`tt(-)'), then only the tags selected by the other strings will be +generated. Normally all tags not explicitly selected will be tried at +the end if the selected tags did not generate any matches. This means +that a value of only one hyphen turns off completion in a particular +context. + +Strings in the value may also be of the form `var(func)tt(())'. In +this case the function var(func) will be called which can then define +in which order tags are to be used based on additional context +information. See the tt(_sort_tags) function below for a description +of how such functions can be implemented. -If no style has been defined for a context, the tt(_sort_tags) function -provides defaults, as given below. +If no style has been defined for a context, all tags will be used. ) item(tt(special-dirs))( Normally, the completion code will not produce the directory names @@ -1133,11 +1148,6 @@ command will always insert matches as if menucompletion were started and it will stop when the last match is inserted. If this style is set to tt(verbose) a message will be displayed when the last match is reached. ) -item(tt(strings))( -This is used with the tt(jobs) tag. If it is `true', the completions -will use the shortest unambiguous strings of the jobs' command lines -instead of the job numbers. -) item(tt(substitute))( If this is unset or set to the empty string, the tt(_expand) completer will first try to expand all substitutions in the string (such as @@ -1399,7 +1409,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) style or tt(_sort_tags) function, as usual. +tt(tag-order) style, 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 @@ -1642,7 +1652,7 @@ item(tt(_tags) [ tt(-C) var(name) [ var(tags) ... ] ])( If called with arguments, these are taken as the names of the tags for the types of matches the calling completion function can generate in the current context. These tags are stored internally and sorted by -calling the tt(_sort_tags) function. Following calls to this function +using the tt(tag-order) style. Following calls to this function without arguments from the same function will then select the first, second, etc. set of tags requested by the user. To test if a certain tag should be tried, the tt(_requested) function has to be called (see @@ -1654,10 +1664,9 @@ non-zero otherwise. This function also accepts the tt(-C) option followed by a var(name). This name is temporarily (i.e. not visible outside tt(_tags)) appended (with a colon before it) to the contents of the -tt(curcontext) parameter. This allows to make tt(_tags) and -tt(_sort_tags) use a more specific context name without having to -change and reset the tt(curcontext) parameter (which would otherwise -have the same effect). +tt(curcontext) parameter. This allows to make tt(_tags) use a more +specific context name without having to change and reset the +tt(curcontext) parameter (which would otherwise have the same effect). ) findex(_requested) item(tt(_requested) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(specs) ... ])( @@ -2313,12 +2322,10 @@ 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. +As described above for the tt(tag-order) style, this is only provided +to show how functions that sort tags can be implemented. -Inside the tt(_sort_tags) function the name of the current context can +Inside such functions 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 @@ -2357,7 +2364,7 @@ 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 +In every context the 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 @@ -2365,7 +2372,7 @@ 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: +you may write in your sorting function: example(_sort_tags() { comptry arguments options @@ -2395,8 +2402,8 @@ 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 +tt(comptry) with all arguments at the end of the sorting function. 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: @@ -2419,30 +2426,6 @@ 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() |