diff options
| -rw-r--r-- | ChangeLog | 2 | ||||
| -rw-r--r-- | Doc/Zsh/compsys.yo | 1206 |
2 files changed, 606 insertions, 602 deletions
diff --git a/ChangeLog b/ChangeLog index 05a044493..59a2d5468 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,7 @@ 2000-05-20 Bart Schaefer <schaefer@zsh.org> + * 11477: Doc/Zsh/compsys.yo: Alphabetize itemized lists. + * 11473: Src/utils.c: Turn off xtrace while printing PS4. 2000-05-19 Oliver Kiddle <opk@zsh.org> diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index ddd815c4a..a749d9ba2 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -2014,6 +2014,49 @@ may write their own): cindex(completion system, completers) startitem() +findex(_approximate) +item(tt(_approximate))( +This completer function uses the tt(_complete) completer to generate +a list of strings for the context the cursor is currently in, allowing +you to specify a maximum number of errors: see the description of +approximate matching in +ifzman(\ +zmanref(zshexpn) +)\ +ifnzman(\ +noderef(Filename Generation) +)\ +for how errors are counted. The resulting list of corrected and completed +strings is then presented to the user. The intended use of this completer +function is to try after the normal tt(_complete) completer by setting: + +example(zstyle ':completion:*' completer _complete _approximate) + +This will give correcting completion if and only if +normal completion yields no possible completions. When +corrected completions are found, the completer will normally start +menu completion allowing you to cycle through these strings. + +This completer uses the tags tt(corrections) and tt(original) when +generating the possible corrections and the original string. The +tt(format) style for the former may contain the additional sequences +`tt(%e)' and `tt(%o)' which will be replaced by the number of errors +accepted to generate the corrections and the original string, +respectively. + +As with all completers, tt(_approximate) uses its name without the +underscore in the var(completer) field of the context name. Once it +has started trying to generate matches, it will append a minus sign +and the number of errors accepted to its name. tt(_approximate) will +first look for completions with one error, then two, and on so up to the +limit on the number of errors set by the tt(max-errors) style. +Hence on the first try the completer field of the context contains +`tt(approximate-1)', on the second try `tt(approximate-2)', and so on. + +When tt(_approximate) is called from another function, the number of errors +to accept may be given with the tt(-a) option. Its argument should be +the same as the value of the tt(max-errors) style, all in one string. +) findex(_complete) item(tt(_complete))( This completer generates all possible completions in a context-sensitive @@ -2028,48 +2071,31 @@ tt(-)var(context)tt(-), as mentioned above for the tt(#compdef) tag, are handled specially. These are: startitem() -kindex(-equal-, completion context) -item(tt(-equal-))( -for completion of words beginning with an equal sign -) -kindex(-tilde-, completion context) -item(tt(-tilde-))( -for completion after a tilde (`tt(~)') character, but before a slash. -) -kindex(-redirect-, completion context) -item(tt(-redirect-))( -for completion after a redirection operator. -) -kindex(-math-, completion context) -item(tt(-math-))( -for completion inside mathematical contexts, such as -`tt(LPAR()LPAR())...tt(RPAR()RPAR())'. -) -kindex(-subscript-, completion context) -item(tt(-subscript-))( -for completion inside subscripts. -) -kindex(-value-, completion context) -item(tt(-value-))( -for completion on the right hand side of an assignment. -) kindex(-array-value-, completion context) item(tt(-array-value-))( for completion on the right hand side of an array-assignment (`tt(foo=LPAR()...RPAR())'). ) +kindex(-brace-parameter-, completion context) +item(tt(-brace-parameter-))( +for completing the name of a parameter expansion within braces +(`tt(${...})'). +) +kindex(-command-, completion context) +item(tt(-command-))( +for completing in a command position. +) kindex(-condition-, completion context) item(tt(-condition-))( for completion inside conditions (`tt([[...]])'). ) -kindex(-parameter-, completion context) -item(tt(-parameter-))( -for completing the name of a parameter expansion (`tt($...)'). +kindex(-default-, completion context) +item(tt(-default-))( +for generating completions when no special completion function is used. ) -kindex(-brace-parameter-, completion context) -item(tt(-brace-parameter-))( -for completing the name of a parameter expansion within braces -(`tt(${...})'). +kindex(-equal-, completion context) +item(tt(-equal-))( +for completion of words beginning with an equal sign ) kindex(-first-, completion context) item(tt(-first-))( @@ -2082,13 +2108,30 @@ will be called, and if it is set to a string containing tt(default) the function for the `tt(-default-)' context will not be called, but functions defined for commands will. ) -kindex(-default-, completion context) -item(tt(-default-))( -for generating completions when no special completion function is used. +kindex(-math-, completion context) +item(tt(-math-))( +for completion inside mathematical contexts, such as +`tt(LPAR()LPAR())...tt(RPAR()RPAR())'. ) -kindex(-command-, completion context) -item(tt(-command-))( -for completing in a command position. +kindex(-parameter-, completion context) +item(tt(-parameter-))( +for completing the name of a parameter expansion (`tt($...)'). +) +kindex(-redirect-, completion context) +item(tt(-redirect-))( +for completion after a redirection operator. +) +kindex(-subscript-, completion context) +item(tt(-subscript-))( +for completion inside subscripts. +) +kindex(-tilde-, completion context) +item(tt(-tilde-))( +for completion after a tilde (`tt(~)') character, but before a slash. +) +kindex(-value-, completion context) +item(tt(-value-))( +for completion on the right hand side of an assignment. ) enditem() @@ -2106,49 +2149,6 @@ completes whole command lines (commands and their arguments) and is not used by the completion system itself, but has a function handling completion for it. ) -findex(_approximate) -item(tt(_approximate))( -This completer function uses the tt(_complete) completer to generate -a list of strings for the context the cursor is currently in, allowing -you to specify a maximum number of errors: see the description of -approximate matching in -ifzman(\ -zmanref(zshexpn) -)\ -ifnzman(\ -noderef(Filename Generation) -)\ -for how errors are counted. The resulting list of corrected and completed -strings is then presented to the user. The intended use of this completer -function is to try after the normal tt(_complete) completer by setting: - -example(zstyle ':completion:*' completer _complete _approximate) - -This will give correcting completion if and only if -normal completion yields no possible completions. When -corrected completions are found, the completer will normally start -menu completion allowing you to cycle through these strings. - -This completer uses the tags tt(corrections) and tt(original) when -generating the possible corrections and the original string. The -tt(format) style for the former may contain the additional sequences -`tt(%e)' and `tt(%o)' which will be replaced by the number of errors -accepted to generate the corrections and the original string, -respectively. - -As with all completers, tt(_approximate) uses its name without the -underscore in the var(completer) field of the context name. Once it -has started trying to generate matches, it will append a minus sign -and the number of errors accepted to its name. tt(_approximate) will -first look for completions with one error, then two, and on so up to the -limit on the number of errors set by the tt(max-errors) style. -Hence on the first try the completer field of the context contains -`tt(approximate-1)', on the second try `tt(approximate-2)', and so on. - -When tt(_approximate) is called from another function, the number of errors -to accept may be given with the tt(-a) option. Its argument should be -the same as the value of the tt(max-errors) style, all in one string. -) findex(_correct) item(tt(_correct))( Generate corrections, but not completions, for the current word; this is @@ -2180,30 +2180,6 @@ it. Using it after the tt(_approximate) completer is useless since tt(_approximate) will at least generate the corrected strings generated by the tt(_correct) completer -- and probably more. ) -findex(_match) -item(tt(_match))( -This completer is intended to be used after the tt(_complete) -completer. It allows one to give patterns on the command line and -to complete all strings matching these patterns from the set of -possible completions for the context the cursor is in, without having -to set the tt(GLOB_COMPLETE) option. - -Normally this will be done by taking the pattern from the line, -inserting a `tt(*)' at the cursor position and comparing the resulting -pattern with the possible completions generated. However, if the -tt(match-original) style has a value of tt(only), no `tt(*)' will be -inserted. If tt(match-original) has any other non-empty string as its -value, this completer will first try to generate matches without, then -with a `tt(*)' inserted at the cursor position. - -The generated matches will be offered in a menu completion unless the -tt(insert-unambiguous) style is set to `true'. In -this case menu completion will only be started if no unambiguous string -could be generated that is at least as long as the original string. - -Note that the matcher specifications defined globally or used by the -completion functions will not be used. -) findex(_expand) item(tt(_expand))( This completer function does not really do completion, but instead @@ -2247,9 +2223,28 @@ item(tt(_history))( Complete words from the shell's command history. This completer uses the tt(remove-all-dups), and tt(sort) styles also used by the tt(_history_complete_word) bindable command, see +ifzman(the section `Bindable Commands' below)\ +ifnzman(noderef(Bindable Commands)) +and ifzman(the section `Completion System Configuration' above)\ ifnzman(noderef(Completion System Configuration)). ) +findex(_ignored) +item(tt(_ignored))( +The tt(ignored-patterns) style can be set to a list of patterns which are +compared against possible completions; matching ones are removed. +With this completer those matches can be reinstated, as +if no tt(ignored-patterns) style were set. The completer actually +generates its own list of matches; which completers are used +for this is determined in the same way as for the tt(_prefix) +completer. + +The tt(single-ignored) style is used if only one +match could be generated. It can be set to tt(show) to prevent that match +from being displayed or inserted into the line, or it can be set to +tt(menu), in which case the single match and the original string from the +line will be offered in a menu completion. +) findex(_list) item(tt(_list))( This completer allows one to delay the insertion of matches until @@ -2259,6 +2254,40 @@ shown. It is affected by the styles tt(condition) and tt(word), see ifzman(the section `Completion System Configuration' above)\ ifnzman(noderef(Completion System Configuration)). ) +findex(_match) +item(tt(_match))( +This completer is intended to be used after the tt(_complete) +completer. It allows one to give patterns on the command line and +to complete all strings matching these patterns from the set of +possible completions for the context the cursor is in, without having +to set the tt(GLOB_COMPLETE) option. + +Normally this will be done by taking the pattern from the line, +inserting a `tt(*)' at the cursor position and comparing the resulting +pattern with the possible completions generated. However, if the +tt(match-original) style has a value of tt(only), no `tt(*)' will be +inserted. If tt(match-original) has any other non-empty string as its +value, this completer will first try to generate matches without, then +with a `tt(*)' inserted at the cursor position. + +The generated matches will be offered in a menu completion unless the +tt(insert-unambiguous) style is set to `true'. In +this case menu completion will only be started if no unambiguous string +could be generated that is at least as long as the original string. + +Note that the matcher specifications defined globally or used by the +completion functions will not be used. +) +findex(_menu) +item(tt(_menu))( +This completer is a simple example function implemented to show how +menu completion can be done in shell code. It should be used as the +first completer and has the effect of making the code perform +menu completion. Note that this is independent of the setting of the +tt(MENU_COMPLETE) option and does not work with the other +menu completion widgets such as tt(reverse-menu-complete), or +tt(accept-and-menu-complete). +) findex(_oldlist) item(tt(_oldlist))( This completer controls how the standard completion widgets behave @@ -2311,32 +2340,6 @@ tt(COMPLETE_IN_WORD) option is set; otherwise, the cursor will be moved to the end of the current word before the completion code is called and hence there will be no suffix. ) -findex(_ignored) -item(tt(_ignored))( -The tt(ignored-patterns) style can be set to a list of patterns which are -compared against possible completions; matching ones are removed. -With this completer those matches can be reinstated, as -if no tt(ignored-patterns) style were set. The completer actually -generates its own list of matches; which completers are used -for this is determined in the same way as for the tt(_prefix) -completer. - -The tt(single-ignored) style is used if only one -match could be generated. It can be set to tt(show) to prevent that match -from being displayed or inserted into the line, or it can be set to -tt(menu), in which case the single match and the original string from the -line will be offered in a menu completion. -) -findex(_menu) -item(tt(_menu))( -This completer is a simple example function implemented to show how -menu completion can be done in shell code. It should be used as the -first completer and has the effect of making the code perform -menu completion. Note that this is independent of the setting of the -tt(MENU_COMPLETE) option and does not work with the other -menu completion widgets such as tt(reverse-menu-complete), or -tt(accept/usr/-and-menu-complete). -) enditem() texinode(Bindable Commands)(Completion Functions)(Control Functions)(Completion System) @@ -2480,186 +2483,19 @@ has been tried. The functions will only be called once, unless they put themselves into the arrays again. startitem() -findex(_funcall) -item(tt(_funcall) var(return) var(name) [ var(args) ... ])( -If a function var(name) exists, it is called with the arguments -var(args). Unless it is the empty string or a single hyphen, -var(return) is taken as the name of a parameter and the return status -from the called function is stored in it. -The return value of tt(_funcall) itself is zero if the function -var(name) exists and was called and non-zero otherwise. -) -findex(_compalso) -item(tt(_compalso) var(names) ...)( -This function looks up the definitions for the context and command -names given as arguments and calls the handler functions for them if -there is a definition (given with the tt(compdef) function). For -example, the function completing inside subscripts might use -`tt(_compalso -math-)' to include the completions generated for -mathematical environments. -) -findex(_call) -item(tt(_call) var(tag) var(string) ...)( -This function is used in places where a command is called and the user -should have the possibility to override the default for calling this -command. It looks up the tt(command) style with the supplied -var(tag). If the style is set, its value is used as the command to -execute. - -In any case, the var(strings) from the call to tt(_call) or from the -style are concatenated with spaces between them and the resulting -string is evaluated. The return value is the return value of the -command called. -) -findex(_normal) -item(tt(_normal))( -This function is used for normal command completion. If -completion is attempted on the first word, command names are -completed. Otherwise, the arguments are completed by calling the -functions defined for this command, including those functions defined -for patterns matching the command name. This function can also be -called by other completion functions if they have to complete a range -of words as a separate command. For example, the function to complete after -the pre-command specifiers such as tt(nohup) removes the first word from -the tt(words) array, decrements the tt(CURRENT) parameter, then calls this -function. - -When calling a function defined for a pattern, this function also -checks if the parameter tt(_compskip) is set and uses the value in the -same way it is used after calling the completion function for the -tt(-first-) context. With this -one can write a pattern completion function that keeps other functions -from being tried simply by setting this parameter to any value. -) -findex(_description) -item(tt(_description) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(specs) ... ])( -This function tests some styles for the var(tag) and and stores -options usable for tt(compadd) in the array with the given var(name) -which guarantee that the matches are generated as requested by the -user. The styles tested are: tt(format) (which is first tested for the -given tag and then for the tt(descriptions) tag if that isn't -defined), tt(hidden), tt(matcher), tt(ignored-patterns) and -tt(group-name) (the last are tested only for the tag given as the -first argument). This function also calls the tt(_setup) function -which tests some more styles. - -The format string from the style (if any) will be modified so that the -sequence `tt(%d)' is replaced by the var(descr) given as the third -argument. If tt(_description) is called with more than three -arguments, these var(specs) should be of the form -`var(char)tt(:)var(str)' and every appearance of `tt(%)var(char)' in -the format string will be replaced by var(string). - -The options placed in the array will also make sure that the matches -are placed in a separate group, depending on the value of the -tt(group-name) style. Normally a sorted group will be used for this -(with the `tt(-J)' option), but if a option starting with `tt(-V)', -`tt(-J)', `tt(-1)', or `tt(-2)' is given, that option will be included -in the array, so that it is possible to make the group unsorted by -giving the option `tt(-V)', `tt(-1V)', or `tt(-2V)'. - -In most cases, this function will be used like this: - -example(local expl -_description files expl file -compadd "$expl[@]" - "$files[@]") -) -findex(_message) -item(tt(_message) [ -r ] var(descr))( -The var(descr) is used like the third -argument to the tt(_description) function. However, the resulting -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. - -This function also uses the tt(format) style for the tt(messages) tag in -preference to the tt(format) style for the tt(descriptions) tag. The -latter is used only if the former is unset. - -If the tt(-r) option is given, no style is used and the var(descr) is -used literally as the string to display. This is only used in cases -where that string is taken from some pre-processed argument list -containing an expanded description. -) -findex(_setup) -item(tt(_setup) var(tag))( -This function expects a tag as its argument and sets up the special -parameters used by the completion system appropriately for the tag, -using styles such as tt(list-colors) and tt(last-prompt). - -Note that this function is called automatically from tt(_description) -so that one normally doesn't have to call it explicitly. -) -findex(_tags) -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 -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 -below). - -The return value is zero if at least one of the tags is requested and -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)) stored in the argument field of the context name in the -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(_next_label) -item(tt(_next_label) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(options) ... ])( -This function should be called repeatedly to generate the tag -labels. On each call it will check if another tag label is to be used -and, if there is at least one, zero is returned. If no more tag -labels are to be used, a non-zero status is returned. - -The tt(-12JV) options and the first three arguments are given to the -tt(_description) function using the tag label instead of the first -argument as appropriate. The var(options) given after the var(descr) -should be other options to be used for tt(compadd) or whatever -function is to be called to add the matches. tt(_next_label) will store these -var(options) in the parameter whose var(name) is given as the second -argument. This is done in such a way that the description given by the -user to the tt(tag-order) style is preferred over the one given to -tt(_next_label). - -Note that this function must not be called without a previous call to -tt(_tags) or tt(_requested) because it uses the tag label -for the current tag found by these functions. - -A normal use of this function for the tag labels of the tag tt(foo) -looks like this: - -example(local expl ret=1 -... -if _requested foo; then - ... - while _next_label foo expl '...'; do - compadd "$expl[@]" ... && ret=0 - done - ... -fi -return ret -) -) findex(_all_labels) item(tt(_all_labels) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(command) var(args) ... ])( -This is a convenient interface to the tt(_next_label) function, implementing -the loop shown in the example above. The var(command) is the one that -should be called to generate the matches. The options stored in the -parameter var(name) will automatically be inserted into the var(args) -given to the var(command). Normally, they are put directly after the -var(command), but if one of the var(args) is a single hyphen, they are -inserted directly before that. If the hyphen is the last argument, -that will be removed from the argument list before the var(command) is -called. This allows to use tt(_all_labels) in almost all cases where the -matches can be generated by a single call to the tt(compadd) builtin -command or by a call to one of the utility functions. +This is a convenient interface to the tt(_next_label) function below, +implementing the loop shown in the tt(_next_label) example. The +var(command) is the one that should be called to generate the matches. The +options stored in the parameter var(name) will automatically be inserted +into the var(args) given to the var(command). Normally, they are put +directly after the var(command), but if one of the var(args) is a single +hyphen, they are inserted directly before that. If the hyphen is the last +argument, that will be removed from the argument list before the +var(command) is called. This allows to use tt(_all_labels) in almost all +cases where the matches can be generated by a single call to the +tt(compadd) builtin command or by a call to one of the utility functions. For example: @@ -2674,72 +2510,11 @@ Will complete the strings from the tt(matches) parameter, using tt(compadd) with additional options which will take precedence over those generated by tt(_all_labels). ) -findex(_requested) -item(tt(_requested) [ tt(-12VJ) ] var(tag) [ var(name) var(descr) [ var(command) var(args) ... ] ])( -A function that uses tt(_tags) to register tags and then calls it to -loop over the requested sets of tags should call this function to -check if a certain tag is currently requested. This normally has to be -done in a loop such as: - -example(_tags foo bar baz -while _tags; do - if _requested foo; then - ... - fi - ... # test other tags - ... # exit loop if matches were generated -done) - -So, the first argument for tt(_requested) is used as the name of a tag -and if that tag is currently requested, the return value is zero (and -non-zero otherwise). - -If the var(name) and the var(descr) are given, tt(_requested) calls the -tt(_description) function with these arguments, including the options. - -If the var(command) is given, the tt(_all_labels) function will be called -immediately with the same arguments. - -This is often useful to do both the testing of the tag, -getting the description for the matches and adding the matches at -once. E.g.: - -example(local expl ret=1 -_tags foo bar baz -while _tags; do - _requested foo expl 'description' \ - compadd foobar foobaz && ret=0 - ... - (( ret )) || break -done) -) -findex(_wanted) -item(tt(_wanted) [ tt(-C) var(name) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) var(command) var(args) ...)( -In many contexts only one type of matches can be generated but even -then it should be tested if the tag representing those matches is -requested by the user. This function makes that easier. - -Like tt(_requested) it gets arguments as for tt(_description). -With the var(tag) it calls tt(_tags) and if that returns zero -(i.e. the var(tag) is requested by the user) it calls tt(_description). So, -if you want to offer only one tag and immediatly want to use the -description built, you can just do: - -example(_wanted tag expl 'description' \ - compadd matches...) - -Unlike tt(_requested), however, tt(_wanted) can not be called without -the var(command). That's because tt(_wanted) also implements the loop -over the tags, not only the one for the labels. - -Like tt(_tags) this function supports the tt(-C) option to give a -different name for the argument context field. -) findex(_alternative) item(tt(_alternative) [ tt(-C) var(name) ] var(specs) ...)( This function is useful if you offer multiple tags and building the matches for them is easy enough. It basically implements a loop like -the one described for the tt(_tags) function above. +the one described for the tt(_tags) function below. The tags to use and what to do if the tags are requested are described using the var(specs) which are of the form: @@ -2767,146 +2542,6 @@ tt(_alternative). Like tt(_tags) this function supports the tt(-C) option to give a different name for the argument context field. ) -findex(_describe) -item(tt(_describe) [ tt(-o) ] var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)( -This function can be used to add options or values with descriptions -as matches. The var(descr) is taken as a string to display above -the matches if the tt(format) style for the tt(descriptions) tag is set. - -After this one or two names of arrays followed by options to give -to tt(compadd) must be given. The first array contains the possible -completions with their descriptions (with the description separated -by a colon from the completion string). If the second array is given, -it should have the same number of elements as the first one and these -elements are added as possible completions instead of the strings from -the first array. In any case, however, the completion list will contain -the strings from the first array. - -Any number of array/option sequences may be given separated by -`tt(-)tt(-)'. This allows one to display matches together that need -to be added with different options for tt(compadd). - -Before the first argument, the option `tt(-o)' may be given. It says -that the matches added are option names. This will make tt(_describe) -use the tt(prefix-hidden), tt(prefix-needed) and tt(verbose) styles -to find out if the strings should be added at all and if the -descriptions should be shown. Without the `tt(-o)' option, only the -tt(verbose) style is used. - -tt(_describe) uses the tt(_all_labels) function to generate the matches, so -that one doesn't need to put it into a loop over the tag labels. -) -findex(_multi_parts) -item(tt(_multi_parts) var(sep) var(array))( -This function gets two arguments: a separator character and an -array. As usual, the var(array) may be either the -name of an array parameter or a literal array in the form -`tt(LPAR()foo bar)tt(RPAR())' (i.e. a list of words separated by white -space in parentheses). With these arguments, this function will -complete to strings from the array where the parts separated by the -separator character are completed independently. For example, the -tt(_tar) function from the distribution caches the pathnames from the -tar file in an array and then calls this function to complete these -names in the way normal filenames are completed by the -tt(_path_files) function. - -If given the tt(-i) option a single match left will be accepted -immediatly even if that means that additional parts for which no -separators were on the line are to be inserted. When completing from a -fixed set of possible completions which are really words, this is -often the expected behaviour. But if tt(_multi_parts) should behave -like completing pathnames, the tt(-i) option should not be used. - -Like other utility functions, this function accepts the `tt(-V)', -`tt(-J)', `tt(-1)', `tt(-2)', `tt(-n)', `tt(-f)', `tt(-X)', `tt(-M)', `tt(-P)', -`tt(-S)', `tt(-r)', `tt(-R)', and `tt(-q)' options and passes them to -the tt(compadd) builtin. -) -findex(_sep_parts) -item(tt(_sep_parts))( -This function gets as arguments alternating arrays and separators. -The arrays specify completions for parts of strings to be separated by the -separators. The arrays may be the names of array parameters or -a quoted list of words in parentheses. For example, with the array -`tt(hosts=(ftp news))' the call `tt(_sep_parts '(foo bar)' @ hosts)' will -complete the string `tt(f)' to `tt(foo)' and the string `tt(b@n)' to -`tt(bar@news)'. - -This function passes the `tt(-V)', `tt(-J)', `tt(-1)', `tt(-2)', -`tt(-n)', `tt(-X)', `tt(-M)', `tt(-P)', `tt(-S)', `tt(-r)', `tt(-R)', -and `tt(-q)' options and their arguments to the tt(compadd) builtin -used to add the matches. -) -findex(_path_files) -findex(_files) -item(tt(_path_files) and tt(_files))( -The function tt(_path_files) is used throughout the shell code -to complete filenames. It allows completion of partial paths. For -example, the string `tt(/u/i/s/sig)' may be completed to -`tt(/usr/include/sys/signal.h)'. - -The function tt(_files) uses the tt(file-patterns) style and calls -tt(_path_files) with all the arguments it was passed except for tt(-g) -and tt(-/). These two options are used depending on the setting of the -tt(file-patterns) style. - -Options accepted by both tt(_path_files) and tt(_files) are: - -startitem() -item(tt(-f))( -Complete all filenames. This is the default. -) -item(tt(-/))( -Specifies that only directories should be completed. -) -item(tt(-g) var(pattern))( -Says that only files matching the var(pattern) should be completed. -) -item(tt(-W) var(paths))( -Specifies path prefixes that are to be prepended to the string from the -line to generate the filenames but that should not be inserted in the line -or shown in a completion listing. The var(paths) may be the name of an -array parameter, a literal list of paths enclosed in parentheses or an -absolute pathname. -) -item(tt(-F))( -This option from the tt(compadd) builtin gives direct control over which -filenames should be ignored. If no such option is given, the -tt(ignored-patterns) style is used. -) -enditem() - -These functions also accept the `tt(-J)', `tt(-V)', `tt(-1)', -`tt(-2)', `tt(-n)', `tt(-X)', `tt(-M)', `tt(-P)', `tt(-S)', `tt(-q)', -`tt(-r)', and `tt(-R)' options from the tt(compadd) builtin. - -Finally, the tt(_path_files) function uses the styles tt(expand), -tt(ambiguous) and tt(special-dirs) and tt(file-sort). -) -findex(_parameters) -item(tt(_parameters))( -This should be used to complete parameter names. All arguments are -passed unchanged to the tt(compadd) builtin. -) -findex(_options) -item(tt(_options))( -This can be used to complete option names. It uses a matching -specification that ignores a leading `tt(no)', ignores underscores and -allows the user to type upper-case letters, making them match their -lower-case counterparts. All arguments passed to this function are -propagated unchanged to the tt(compadd) builtin. -) -findex(_set_options) -findex(_unset_options) -item(tt(_set_options) and tt(_unset_options))( -These functions complete only set or unset options, with the same -matching specification used in the tt(_options) function. - -Note that you need to uncomment a few lines in the tt(_main_complete) -function for these functions to work properly. The lines in question -are used to store the option settings in effect before the completion -widget locally sets the options it needs. -) findex(_arguments) item(tt(_arguments) var(specs) ...)( This function can be used to complete words on the line by simply @@ -3289,77 +2924,296 @@ things should work. Note that the contexts reported in the tt(context) array and the options in the tt(opt_args) association are prefixed with the set names and a hyphen. ) -findex(_values) -item(tt(_values) var(specs) ...)( -This is used to complete values (strings) and their arguments or -lists of such values. +findex(_call) +item(tt(_call) var(tag) var(string) ...)( +This function is used in places where a command is called and the user +should have the possibility to override the default for calling this +command. It looks up the tt(command) style with the supplied +var(tag). If the style is set, its value is used as the command to +execute. -If the first argument is the option `tt(-O) var(name)', this will be -used in the same way as by the tt(_arguments) function. I.e. the -elements of the var(name) array will be given to calls to tt(compadd) -and when executing an action. +In any case, the var(strings) from the call to tt(_call) or from the +style are concatenated with spaces between them and the resulting +string is evaluated. The return value is the return value of the +command called. +) +findex(_combination) +item(tt(_combination) [ tt(-s) var(pattern) ] var(tag) var(style) var(specs) ... var(field) var(opts) ...)( +This function is used to complete combinations of values such as pairs +of hostnames and usernames. The possible values will be taken from the +var(style) whose name is given as the second argument. The first argument +is the var(tag) to use to do the lookup. -Otherwise, if the first argument (or the first argument after the -`tt(-O) var(name)' option if that is used) is the option `tt(-s)', the -next argument is used as the character that separates multiple values. +The style name should consist of multiple parts separated by +hyphens which are then used as fieldnames. Known values for such +fields can be given after the second argument in arguments of the form +`var(field)tt(=)var(pattern)'. The first argument without a equal sign +is taken as the name of the field for which completions should be +generated. -The first argument (after the options and separator character if they -are given) is used as a string to print as a description before -listing the values. +The matches generated will be taken from the value of the style. These +values should contain the possible values for the combinations where +the values for the different fields are separated by colons or +characters matching the pattern given after the tt(-s) option to +tt(_combination) (normally this is used to define character classes +like the `tt(-s "[:@]")' used for the tt(users-hosts) style). -All other arguments describe the possible values and their -arguments in the same format used for the description of options by -the tt(_arguments) function (see above). The only difference is that -there is no required minus or plus sign at the beginning and that -values can have only one argument. +Only the values for the requested fields for which the patterns given +in the `var(field)tt(=)var(pattern)' match the respective fields in +the strings from the style value are generated as possible matches. -Example: +If no style with the given name is defined for the given tag but a +function named with the name of the requested field preceded by an +underscore is defined, that function will be called to generate the +matches. This is also done if none of the strings in the value of the +style match all the patterns given as arguments. -example(_values -s , 'description' \ - '*foo[bar]' \ - '(two)*one[number]:first count:' \ - 'two[another number]::second count:(1 2 3)') +If the same name is used for more than one field, in both the +`var(field)tt(=)var(pattern)' and the argument that gives the field +name to complete for, the number of the field (starting with one) may +be given after the fieldname, separated from it by a colon. -This describes three possible values: `tt(foo)', `tt(one)', and -`tt(two)'. The first one is described as `tt(bar)', gets no argument -and may appear more than once. The second one is described as -`tt(number)', may appear more than once, and gets one mandatory -argument described as `tt(first count)' for which no action is -specified so that it will not be completed automatically. The -`tt((two))' at the beginning says that if the value `tt(one)' is on -the line, the value `tt(two)' will not be considered to be a possible -completion anymore. Finally, the last value (`tt(two)') is described -as `tt(another number)' and gets an optional argument described as -`tt(second count)' which will be completed from the strings `tt(1)', -`tt(2)', and `tt(3)'. The tt(_values) function will complete lists of -these values separated by commas. +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(_compalso) +item(tt(_compalso) var(names) ...)( +This function looks up the definitions for the context and command +names given as arguments and calls the handler functions for them if +there is a definition (given with the tt(compdef) function). For +example, the function completing inside subscripts might use +`tt(_compalso -math-)' to include the completions generated for +mathematical environments. +) +findex(_describe) +item(tt(_describe) [ tt(-o) ] var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)( +This function can be used to add options or values with descriptions +as matches. The var(descr) is taken as a string to display above +the matches if the tt(format) style for the tt(descriptions) tag is set. -Like tt(_arguments) this function temporarily adds another context -name component to the current context name while executing the -var(action). Here this name is just the name of the value for which -the argument is completed. +After this one or two names of arrays followed by options to give +to tt(compadd) must be given. The first array contains the possible +completions with their descriptions (with the description separated +by a colon from the completion string). If the second array is given, +it should have the same number of elements as the first one and these +elements are added as possible completions instead of the strings from +the first array. In any case, however, the completion list will contain +the strings from the first array. -To decide if the descriptions for the values (not those for the -arguments) should be printed, the tt(verbose) is used. +Any number of array/option sequences may be given separated by +`tt(-)tt(-)'. This allows one to display matches together that need +to be added with different options for tt(compadd). -One last difference to tt(_arguments) is that this function uses the -associative array -tt(val_args) to report values and their arguments (but otherwise this -is the same as the tt(opt_args) association used by -tt(_arguments)). This also means that the function calling tt(_values) -should declare the tt(state), tt(line), tt(context) and tt(val_args) -parameters as in: +Before the first argument, the option `tt(-o)' may be given. It says +that the matches added are option names. This will make tt(_describe) +use the tt(prefix-hidden), tt(prefix-needed) and tt(verbose) styles +to find out if the strings should be added at all and if the +descriptions should be shown. Without the `tt(-o)' option, only the +tt(verbose) style is used. -example(local context state line -typeset -A val_args) +tt(_describe) uses the tt(_all_labels) function to generate the matches, so +that one doesn't need to put it into a loop over the tag labels. +) +findex(_description) +item(tt(_description) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(specs) ... ])( +This function tests some styles for the var(tag) and and stores +options usable for tt(compadd) in the array with the given var(name) +which guarantee that the matches are generated as requested by the +user. The styles tested are: tt(format) (which is first tested for the +given tag and then for the tt(descriptions) tag if that isn't +defined), tt(hidden), tt(matcher), tt(ignored-patterns) and +tt(group-name) (the last are tested only for the tag given as the +first argument). This function also calls the tt(_setup) function +which tests some more styles. -when using an action of the form `tt(->)var(string)'. With this -function the tt(context) parameter will be set to the name of the -value whose argument is to be completed. +The format string from the style (if any) will be modified so that the +sequence `tt(%d)' is replaced by the var(descr) given as the third +argument. If tt(_description) is called with more than three +arguments, these var(specs) should be of the form +`var(char)tt(:)var(str)' and every appearance of `tt(%)var(char)' in +the format string will be replaced by var(string). -Like tt(_arguments), tt(_values) also supports the tt(-C) option in -which case you have to make the parameter tt(curcontext) local instead -of tt(context) (as described above). +The options placed in the array will also make sure that the matches +are placed in a separate group, depending on the value of the +tt(group-name) style. Normally a sorted group will be used for this +(with the `tt(-J)' option), but if a option starting with `tt(-V)', +`tt(-J)', `tt(-1)', or `tt(-2)' is given, that option will be included +in the array, so that it is possible to make the group unsorted by +giving the option `tt(-V)', `tt(-1V)', or `tt(-2V)'. + +In most cases, this function will be used like this: + +example(local expl +_description files expl file +compadd "$expl[@]" - "$files[@]") +) +findex(_funcall) +item(tt(_funcall) var(return) var(name) [ var(args) ... ])( +If a function var(name) exists, it is called with the arguments +var(args). Unless it is the empty string or a single hyphen, +var(return) is taken as the name of a parameter and the return status +from the called function is stored in it. +The return value of tt(_funcall) itself is zero if the function +var(name) exists and was called and non-zero otherwise. +) +findex(_message) +item(tt(_message) [ -r ] var(descr))( +The var(descr) is used like the third +argument to the tt(_description) function. However, the resulting +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. + +This function also uses the tt(format) style for the tt(messages) tag in +preference to the tt(format) style for the tt(descriptions) tag. The +latter is used only if the former is unset. + +If the tt(-r) option is given, no style is used and the var(descr) is +used literally as the string to display. This is only used in cases +where that string is taken from some pre-processed argument list +containing an expanded description. +) +findex(_multi_parts) +item(tt(_multi_parts) var(sep) var(array))( +This function gets two arguments: a separator character and an +array. As usual, the var(array) may be either the +name of an array parameter or a literal array in the form +`tt(LPAR()foo bar)tt(RPAR())' (i.e. a list of words separated by white +space in parentheses). With these arguments, this function will +complete to strings from the array where the parts separated by the +separator character are completed independently. For example, the +tt(_tar) function from the distribution caches the pathnames from the +tar file in an array and then calls this function to complete these +names in the way normal filenames are completed by the +tt(_path_files) function. + +If given the tt(-i) option a single match left will be accepted +immediatly even if that means that additional parts for which no +separators were on the line are to be inserted. When completing from a +fixed set of possible completions which are really words, this is +often the expected behaviour. But if tt(_multi_parts) should behave +like completing pathnames, the tt(-i) option should not be used. + +Like other utility functions, this function accepts the `tt(-V)', +`tt(-J)', `tt(-1)', `tt(-2)', `tt(-n)', `tt(-f)', `tt(-X)', `tt(-M)', `tt(-P)', +`tt(-S)', `tt(-r)', `tt(-R)', and `tt(-q)' options and passes them to +the tt(compadd) builtin. +) +findex(_next_label) +item(tt(_next_label) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(options) ... ])( +This function should be called repeatedly to generate the tag +labels. On each call it will check if another tag label is to be used +and, if there is at least one, zero is returned. If no more tag +labels are to be used, a non-zero status is returned. + +The tt(-12JV) options and the first three arguments are given to the +tt(_description) function using the tag label instead of the first +argument as appropriate. The var(options) given after the var(descr) +should be other options to be used for tt(compadd) or whatever +function is to be called to add the matches. tt(_next_label) will store these +var(options) in the parameter whose var(name) is given as the second +argument. This is done in such a way that the description given by the +user to the tt(tag-order) style is preferred over the one given to +tt(_next_label). + +Note that this function must not be called without a previous call to +tt(_tags) or tt(_requested) because it uses the tag label +for the current tag found by these functions. + +A normal use of this function for the tag labels of the tag tt(foo) +looks like this: + +example(local expl ret=1 +... +if _requested foo; then + ... + while _next_label foo expl '...'; do + compadd "$expl[@]" ... && ret=0 + done + ... +fi +return ret +) +) +findex(_normal) +item(tt(_normal))( +This function is used for normal command completion. If +completion is attempted on the first word, command names are +completed. Otherwise, the arguments are completed by calling the +functions defined for this command, including those functions defined +for patterns matching the command name. This function can also be +called by other completion functions if they have to complete a range +of words as a separate command. For example, the function to complete after +the pre-command specifiers such as tt(nohup) removes the first word from +the tt(words) array, decrements the tt(CURRENT) parameter, then calls this +function. + +When calling a function defined for a pattern, this function also +checks if the parameter tt(_compskip) is set and uses the value in the +same way it is used after calling the completion function for the +tt(-first-) context. With this +one can write a pattern completion function that keeps other functions +from being tried simply by setting this parameter to any value. +) +findex(_parameters) +item(tt(_parameters))( +This should be used to complete parameter names. All arguments are +passed unchanged to the tt(compadd) builtin. +) +findex(_path_files) +findex(_files) +item(tt(_path_files) and tt(_files))( +The function tt(_path_files) is used throughout the shell code +to complete filenames. It allows completion of partial paths. For +example, the string `tt(/u/i/s/sig)' may be completed to +`tt(/usr/include/sys/signal.h)'. + +The function tt(_files) uses the tt(file-patterns) style and calls +tt(_path_files) with all the arguments it was passed except for tt(-g) +and tt(-/). These two options are used depending on the setting of the +tt(file-patterns) style. + +Options accepted by both tt(_path_files) and tt(_files) are: + +startitem() +item(tt(-f))( +Complete all filenames. This is the default. +) +item(tt(-/))( +Specifies that only directories should be completed. +) +item(tt(-g) var(pattern))( +Says that only files matching the var(pattern) should be completed. +) +item(tt(-W) var(paths))( +Specifies path prefixes that are to be prepended to the string from the +line to generate the filenames but that should not be inserted in the line +or shown in a completion listing. The var(paths) may be the name of an +array parameter, a literal list of paths enclosed in parentheses or an +absolute pathname. +) +item(tt(-F))( +This option from the tt(compadd) builtin gives direct control over which +filenames should be ignored. If no such option is given, the +tt(ignored-patterns) style is used. +) +enditem() + +These functions also accept the `tt(-J)', `tt(-V)', `tt(-1)', +`tt(-2)', `tt(-n)', `tt(-X)', `tt(-M)', `tt(-P)', `tt(-S)', `tt(-q)', +`tt(-r)', and `tt(-R)' options from the tt(compadd) builtin. + +Finally, the tt(_path_files) function uses the styles tt(expand), +tt(ambiguous) and tt(special-dirs) and tt(file-sort). +) +findex(_options) +item(tt(_options))( +This can be used to complete option names. It uses a matching +specification that ignores a leading `tt(no)', ignores underscores and +allows the user to type upper-case letters, making them match their +lower-case counterparts. All arguments passed to this function are +propagated unchanged to the tt(compadd) builtin. ) findex(_regex_arguments) item(tt(_regex_arguments) var(name) var(specs) ...)( @@ -3426,45 +3280,79 @@ Either of the two var(spec)s can be matched. ) enditem() ) -findex(_combination) -item(tt(_combination) [ tt(-s) var(pattern) ] var(tag) var(style) var(specs) ... var(field) var(opts) ...)( -This function is used to complete combinations of values such as pairs -of hostnames and usernames. The possible values will be taken from the -var(style) whose name is given as the second argument. The first argument -is the var(tag) to use to do the lookup. +findex(_requested) +item(tt(_requested) [ tt(-12VJ) ] var(tag) [ var(name) var(descr) [ var(command) var(args) ... ] ])( +A function that uses tt(_tags) to register tags and then calls it to +loop over the requested sets of tags should call this function to +check if a certain tag is currently requested. This normally has to be +done in a loop such as: -The style name should consist of multiple parts separated by -hyphens which are then used as fieldnames. Known values for such -fields can be given after the second argument in arguments of the form -`var(field)tt(=)var(pattern)'. The first argument without a equal sign -is taken as the name of the field for which completions should be -generated. +example(_tags foo bar baz +while _tags; do + if _requested foo; then + ... + fi + ... # test other tags + ... # exit loop if matches were generated +done) -The matches generated will be taken from the value of the style. These -values should contain the possible values for the combinations where -the values for the different fields are separated by colons or -characters matching the pattern given after the tt(-s) option to -tt(_combination) (normally this is used to define character classes -like the `tt(-s "[:@]")' used for the tt(users-hosts) style). +So, the first argument for tt(_requested) is used as the name of a tag +and if that tag is currently requested, the return value is zero (and +non-zero otherwise). -Only the values for the requested fields for which the patterns given -in the `var(field)tt(=)var(pattern)' match the respective fields in -the strings from the style value are generated as possible matches. +If the var(name) and the var(descr) are given, tt(_requested) calls the +tt(_description) function with these arguments, including the options. -If no style with the given name is defined for the given tag but a -function named with the name of the requested field preceded by an -underscore is defined, that function will be called to generate the -matches. This is also done if none of the strings in the value of the -style match all the patterns given as arguments. +If the var(command) is given, the tt(_all_labels) function will be called +immediately with the same arguments. -If the same name is used for more than one field, in both the -`var(field)tt(=)var(pattern)' and the argument that gives the field -name to complete for, the number of the field (starting with one) may -be given after the fieldname, separated from it by a colon. +This is often useful to do both the testing of the tag, +getting the description for the matches and adding the matches at +once. E.g.: -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. +example(local expl ret=1 +_tags foo bar baz +while _tags; do + _requested foo expl 'description' \ + compadd foobar foobaz && ret=0 + ... + (( ret )) || break +done) +) +findex(_sep_parts) +item(tt(_sep_parts))( +This function gets as arguments alternating arrays and separators. +The arrays specify completions for parts of strings to be separated by the +separators. The arrays may be the names of array parameters or +a quoted list of words in parentheses. For example, with the array +`tt(hosts=(ftp news))' the call `tt(_sep_parts '(foo bar)' @ hosts)' will +complete the string `tt(f)' to `tt(foo)' and the string `tt(b@n)' to +`tt(bar@news)'. + +This function passes the `tt(-V)', `tt(-J)', `tt(-1)', `tt(-2)', +`tt(-n)', `tt(-X)', `tt(-M)', `tt(-P)', `tt(-S)', `tt(-r)', `tt(-R)', +and `tt(-q)' options and their arguments to the tt(compadd) builtin +used to add the matches. +) +findex(_set_options) +findex(_unset_options) +item(tt(_set_options) and tt(_unset_options))( +These functions complete only set or unset options, with the same +matching specification used in the tt(_options) function. + +Note that you need to uncomment a few lines in the tt(_main_complete) +function for these functions to work properly. The lines in question +are used to store the option settings in effect before the completion +widget locally sets the options it needs. +) +findex(_setup) +item(tt(_setup) var(tag))( +This function expects a tag as its argument and sets up the special +parameters used by the completion system appropriately for the tag, +using styles such as tt(list-colors) and tt(last-prompt). + +Note that this function is called automatically from tt(_description) +so that one normally doesn't have to call it explicitly. ) findex(_sort_tags) item(tt(_sort_tags) var(tag) ...)( @@ -3549,7 +3437,121 @@ separate set. With the tt(-m) option, the arguments are treated in the same way as the the values for the tt(tag-order) style (except for the `tt(!...)', `tt(-)' and `tt(foo())' forms). ) +findex(_tags) +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 +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 +above). + +The return value is zero if at least one of the tags is requested and +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)) stored in the argument field of the context name in the +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(_wanted) +item(tt(_wanted) [ tt(-C) var(name) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) var(command) var(args) ...)( +In many contexts only one type of matches can be generated but even +then it should be tested if the tag representing those matches is +requested by the user. This function makes that easier. + +Like tt(_requested) it gets arguments as for tt(_description). +With the var(tag) it calls tt(_tags) and if that returns zero +(i.e. the var(tag) is requested by the user) it calls tt(_description). So, +if you want to offer only one tag and immediatly want to use the +description built, you can just do: +example(_wanted tag expl 'description' \ + compadd matches...) + +Unlike tt(_requested), however, tt(_wanted) can not be called without +the var(command). That's because tt(_wanted) also implements the loop +over the tags, not only the one for the labels. + +Like tt(_tags) this function supports the tt(-C) option to give a +different name for the argument context field. +) +findex(_values) +item(tt(_values) var(specs) ...)( +This is used to complete values (strings) and their arguments or +lists of such values. + +If the first argument is the option `tt(-O) var(name)', this will be +used in the same way as by the tt(_arguments) function. I.e. the +elements of the var(name) array will be given to calls to tt(compadd) +and when executing an action. + +Otherwise, if the first argument (or the first argument after the +`tt(-O) var(name)' option if that is used) is the option `tt(-s)', the +next argument is used as the character that separates multiple values. + +The first argument (after the options and separator character if they +are given) is used as a string to print as a description before +listing the values. + +All other arguments describe the possible values and their +arguments in the same format used for the description of options by +the tt(_arguments) function (see above). The only difference is that +there is no required minus or plus sign at the beginning and that +values can have only one argument. + +Example: + +example(_values -s , 'description' \ + '*foo[bar]' \ + '(two)*one[number]:first count:' \ + 'two[another number]::second count:(1 2 3)') + +This describes three possible values: `tt(foo)', `tt(one)', and +`tt(two)'. The first one is described as `tt(bar)', gets no argument +and may appear more than once. The second one is described as +`tt(number)', may appear more than once, and gets one mandatory +argument described as `tt(first count)' for which no action is +specified so that it will not be completed automatically. The +`tt((two))' at the beginning says that if the value `tt(one)' is on +the line, the value `tt(two)' will not be considered to be a possible +completion anymore. Finally, the last value (`tt(two)') is described +as `tt(another number)' and gets an optional argument described as +`tt(second count)' which will be completed from the strings `tt(1)', +`tt(2)', and `tt(3)'. The tt(_values) function will complete lists of +these values separated by commas. + +Like tt(_arguments) this function temporarily adds another context +name component to the current context name while executing the +var(action). Here this name is just the name of the value for which +the argument is completed. + +To decide if the descriptions for the values (not those for the +arguments) should be printed, the tt(verbose) is used. + +One last difference to tt(_arguments) is that this function uses the +associative array +tt(val_args) to report values and their arguments (but otherwise this +is the same as the tt(opt_args) association used by +tt(_arguments)). This also means that the function calling tt(_values) +should declare the tt(state), tt(line), tt(context) and tt(val_args) +parameters as in: + +example(local context state line +typeset -A val_args) + +when using an action of the form `tt(->)var(string)'. With this +function the tt(context) parameter will be set to the name of the +value whose argument is to be completed. + +Like tt(_arguments), tt(_values) also supports the tt(-C) option in +which case you have to make the parameter tt(curcontext) local instead +of tt(context) (as described above). +) enditem() texinode(Completion Directories)()(Completion Functions)(Completion System) |