diff options
| -rw-r--r-- | ChangeLog | 6 | ||||
| -rw-r--r-- | Completion/Zsh/Context/_value | 8 | ||||
| -rw-r--r-- | Doc/Zsh/compsys.yo | 273 |
3 files changed, 143 insertions, 144 deletions
diff --git a/ChangeLog b/ChangeLog index 11ad17f6d..da5117650 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2003-02-25 Oliver Kiddle <opk@zsh.org> + + * unposted: Completion/Zsh/Context/_value, Doc/Zsh/compsys.yo: + fix out of date documentation and move description of special + contexts from _complete's to #compdef's description + 2003-02-24 Peter Stephenson <pws@csr.com> * 18230: Completion/Unix/Type/_path_files: If globbing failed diff --git a/Completion/Zsh/Context/_value b/Completion/Zsh/Context/_value index 15732f22c..47fbc1749 100644 --- a/Completion/Zsh/Context/_value +++ b/Completion/Zsh/Context/_value @@ -1,10 +1,10 @@ #compdef -value- -array-value- -value-,-default-,-default- # You can customize completion for different parameters by writing -# functions with the tag-line `#compdef -T value <name>'. -# The function searches for the strings `<param-name>:<param-type>' -# and `<param-name>'. If the line contains a command (as in `make foo=<TAB>') -# the string `<command>:<param-name>:<param-type>' is also searched for. +# functions with the tag-line `#compdef -value-,<name>,<command>' where +# <name> is the name of the parameter (or name-key when completing an +# associative array value) and <command> is either `-default-' or the +# name of the command from the command-line. if [[ "$service" != -value-,* ]]; then local strs ctx= diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index a8a1bbe42..7e0e8b452 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -159,13 +159,12 @@ completion system and will not be treated specially. The tags are: startitem() -item(tt(#compdef) var(names...) [ tt(-[pP]) var(patterns...) [ tt(-N) -var(names...) ] ])( +item(tt(#compdef) var(names...) [ tt(-[pP]) var(patterns...) [ tt(-N) var(names...) ] ])( The file will be made autoloadable and the function defined in it will be called when completing var(names), each of which is either the name of a command whose arguments are to be completed or one of a number of special contexts in the form tt(-)var(context)tt(-) described -below for the tt(_complete) function. +below. Each var(name) may also be of the form `var(cmd)tt(=)var(service)'. This is used by functions that offer multiple services, i.e. different @@ -250,6 +249,131 @@ ifnzman(noderef(Shell Builtin Commands))\ . This forces the functions to be autoloaded the way zsh normally loads functions. +The special contexts for which completion functions can be defined are: + +startitem() +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(-assign-parameter-, completion context) +item(tt(-assign-parameter-))( +for completing the name of a parameter in an assignment. +) +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(-default-, completion context) +item(tt(-default-))( +for generating completions when no special completion function is used. +) +kindex(-equal-, completion context) +item(tt(-equal-))( +for completion of words beginning with an equals sign +) +kindex(-first-, completion context) +item(tt(-first-))( +for adding completions before any other completion functions are tried; +if this function sets the tt(_compskip) parameter to tt(all), no other +completion functions will be called, if it is set to a string +containing the substring tt(patterns), no pattern completion functions +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(-math-, completion context) +item(tt(-math-))( +for completion inside mathematical contexts, such as +`tt(LPAR()LPAR())...tt(RPAR()RPAR())'. +) +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() + +Default implementations are supplied for each of these +contexts, in most cases named after the context itself +(e.g. completion for the `tt(-tilde-)' context is done by the function +named `tt(_tilde)'). + +The functions for some contexts re-dispatch by calling the function +tt(_dispatch) to offer more specific context information. This is +done by appending the parts of extra information to the name of the +context, separated by commas. Currently, only the function +completing redirection arguments (tt(_redirect)) and the function +completing values in parameter assignments (tt(_value)) use this +feature. The former uses contexts of the form +`tt(-redirect-,)var(op)tt(,)var(command)', where var(op) is the +redirection operator and var(command) is the name of the command on +the line. If there isn't a command yet, the var(command) field will +be empty. The function completing values uses contexts of the form +`tt(-value-,)var(name)tt(,)var(command)', where var(name) is the name +of the parameter (or `var(name)tt(-)var(key)' when completing a +value of an associative array in an assignment like +`tt(assoc=LPAR()key <TAB>)'). The var(command) part is the name of +the command from the line again in completions like `tt(make +CFLAGS=<TAB>)' and is empty for normal assignments. + +To simplify defining functions for multiple cases, the functions +tt(_redirect) and tt(_value) will make tt(_dispatch) try these context +names more than once with each of the parts once set to the string +tt(-default-). For example, when completing after `tt(foo=<TAB>)', +tt(_value) will try the names `tt(-value-,foo,)' (note the empty +var(command) part), `tt(-value-,foo,-default-)' and +`tt(-value-,-default-,-default-)'. Also note the order in which the +contexts are tried. + +As an example: + +example(compdef '_files -g "*.log"' '-redirect-,2>,-default-') + +could be used to complete files matching `tt(*.log)' when completing +after `tt(2> <TAB>)'. + +And: + +example(compdef _foo -value-,-default-,-default-) + +says that the function tt(_foo) is to be called to provide completion +for the values of parameters for which no special function has been +defined. + +In any case the most specific context name will be used inside the +context string used for looking up styles. For example: + +example(zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log') + +is another way to make completion after `tt(2> <TAB>)' complete files +matching `tt(*.log)'. + subsect(Functions) The tt(compinit) file defines the following function, which may @@ -258,7 +382,7 @@ also be called directly by the user. findex(compdef) cindex(completion system, adding definitions) startitem() -xitem(tt(compdef) [ tt(-an) ] var(function names...) [ tt(-[pP]) var(patterns...) ]) +xitem(tt(compdef) [ tt(-an) ] var(function names...) [ tt(-[pP]) var(patterns...) [ tt(-N) var(names...) ] ]) xitem(tt(compdef -d) var(names...)) xitem(tt(compdef -k) [ tt(-an) ] var(function style key-sequences...)) item(tt(compdef -K) [ tt(-an) ] var(function name style key-sequences ...))( @@ -390,7 +514,7 @@ for more information). itemiz(\ The var(context) or var(command). This is either one of the special context names such as tt(-condition-) as explained for the -tt(_complete) completer below, or the name of the command we are +tt(#compdef) tag above, or the name of the command we are completing arguments for. Completion functions for commands that have sub-commands usually modify this field to contain the name of the command followed by a minus sign and the sub-command (e.g. the @@ -2528,132 +2652,8 @@ This gives the normal completion behaviour. To complete arguments of commands, tt(_complete) uses the utility function tt(_normal), which is in turn responsible for finding the particular function; it is described below. Various contexts of the form -tt(-)var(context)tt(-), as mentioned above for the tt(#compdef) tag, are -handled specially. These are: - -startitem() -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(-assign-parameter-, completion context) -item(tt(-assign-parameter-))( -for completing the name of a parameter in an assignment. -) -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(-default-, completion context) -item(tt(-default-))( -for generating completions when no special completion function is used. -) -kindex(-equal-, completion context) -item(tt(-equal-))( -for completion of words beginning with an equals sign -) -kindex(-first-, completion context) -item(tt(-first-))( -for adding completions before any other completion functions are -tried; if this -function sets the tt(_compskip) parameter to tt(all), no other -completion functions will be called, if it is set to a string -containing the substring tt(patterns), no pattern completion functions -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(-math-, completion context) -item(tt(-math-))( -for completion inside mathematical contexts, such as -`tt(LPAR()LPAR())...tt(RPAR()RPAR())'. -) -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() - -Default implementations are supplied for each of these -contexts, in most cases named after the context itself -(e.g. completion for the `tt(-tilde-)' context is done by the function -named `tt(_tilde)'). - -The functions for some contexts re-dispatch by calling the function -tt(_dispatch) to offer more specific context information. This is -done by appending the parts of extra information to the name of the -context, separated by commas. Currently, only the function -completing redirection arguments (tt(_redirect)) and the function -completing values in parameter assignments (tt(_value)) use this -feature. The former uses contexts of the form -`tt(-redirect-,)var(op)tt(,)var(command)', where var(op) is the -redirection operator and var(command) is the name of the command on -the line. If there isn't a command yet, the var(command) field will -be empty. The function completing values uses contexts of the form -`tt(-value-,)var(name)tt(,)var(command)', where var(name) is the name -of the parameter (or `var(name)tt(-)var(key)' when completing a -value of an associative array in an assignment like -`tt(assoc=LPAR()key <TAB>)'). The var(command) part is the name of -the command from the line again in completions like `tt(make -CFLAGS=<TAB>)' and is empty for normal assignments. - -To simplify defining functions for multiple cases, the functions -tt(_redirect) and tt(_value) will make tt(_dispatch) try these context -names more than once with each of the parts once set to the string -tt(-default-). For example, when completing after `tt(foo=<TAB>)', -tt(_value) will try the names `tt(-value-,foo,)' (note the empty -var(command) part), `tt(-value-,foo,-default-)' and -`tt(-value-,-default-,-default-)'. Also note the order in which the -contexts are tried. - -As an example: - -example(compdef '_files -g "*.log"' '-redirect-,2>,-default-') - -could be used to complete files matching `tt(*.log)' when completing -after `tt(2> <TAB>)'. - -And: - -example(compdef _foo -value-,-default-,-default-) - -says that the function tt(_foo) is to be called to provide completion -for the values of parameters for which no special function has been -defined. - -In any case the most specific context name will be used inside the -context string used for looking up styles. For example: - -example(zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log') - -is another way to make completion after `tt(2> <TAB>)' complete files -matching `tt(*.log)'. +tt(-)var(context)tt(-) are handled specifically. These are all +mentioned above for the tt(#compdef) tag. Before trying to find a function for a specific context, tt(_complete) checks if the parameter `tt(compcontext)' is set. If it is set to an @@ -3914,7 +3914,7 @@ return ret ) ) findex(_normal) -item(tt(_normal) [ var(type) ])( +item(tt(_normal))( This function is used for normal command completion. It has two tasks: completing the first word on the command line as the name of a command, and completing the arguments to this command. In the second case, the name of @@ -3927,19 +3927,12 @@ treat a range of words as a command line. 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 tt(_normal) again, with the effect that `tt(nohup) var(cmd ...)' -is treated the same way was `var(cmd ...)'. +is treated the same way as `var(cmd ...)'. If the command name matches a pattern, the parameter tt(_compskip) is checked after the call to the corresponding completion function. This has the same effect here as in the tt(-first-) context: if it is set, no more completion functions are called even if there are no matches so far. - -If the optional var(type) argument is given, tt(_normal) does not use -the normal associative arrays for its lookup but instead uses the ones -defined for the given var(type), which may currently be one of -tt(comps) for normal completion, tt(redirs) for completion of -command-specific redirections or tt(values) to complete on the right -hand side of parameter assignments. ) findex(_options) item(tt(_options))( |