diff options
Diffstat (limited to 'Doc/Zsh/compsys.yo')
| -rw-r--r-- | Doc/Zsh/compsys.yo | 117 |
1 files changed, 78 insertions, 39 deletions
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 953d51c4c..36afd7305 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -1158,6 +1158,12 @@ directory is accepted without any attempt to complete it further. Hence, in the given example, the path tt(/usr/bin/) is accepted immediately and completion tried in that directory. +This style is also useful when completing after directories that +magically appear when referenced, such as ZFS tt(.zfs) directories +or NetApp tt(.snapshot) directories. When the style is set the +shell does not check for the existence of the directory within the +parent directory. + If you wish to inhibit this behaviour entirely, set the tt(path-completion) style (see below) to `false'. ) @@ -1428,9 +1434,10 @@ or colons in var(dir) should be quoted with a backslash to be treated literally. This can be useful on systems that support special file systems whose -top-level pathnames can not be listed or generated with glob patterns. -It can also be used for directories for which one does not have read -permission. +top-level pathnames can not be listed or generated with glob patterns +(but see tt(accept-exact-dirs) for a more general way of dealing +with this problem). It can also be used for directories for which one +does not have read permission. The pattern form can be used to add a certain `magic' entry to all directories on a particular file system. @@ -2196,7 +2203,7 @@ matches does not fit on the screen by using the value `tt(select=long)'. To start menu selection even if the current widget only performs listing, use the value `tt(select=long-list)'. -To turn on menu completion or menu selection when a there are a certain +To turn on menu completion or menu selection when there are a certain number of matches em(or) the list of matches does not fit on the screen, both of `tt(yes=)' and `tt(select=)' may be given twice, once with a number and once with `tt(long)' or `tt(long-list)'. @@ -3007,6 +3014,22 @@ tt(-n), tt(-F), tt(-X) are passed to tt(compadd). See tt(_description) for a description of var(tag) and var(descr). ) +findex(_cmdambivalent) +item(tt(_cmdambivalent))( +Completes the remaining positional arguments as an external command. +The external command and its arguments are completed as separate arguments +(in a manner appropriate for completing tt(/usr/bin/env)) +if there are two or more remaining positional arguments on the command line, +and as a quoted command string (in the manner of tt(system+LPAR()...+RPAR())) otherwise. +See also tt(_cmdstring) and tt(_precommand). + +This function takes no arguments. +) +findex(_cmdstring) +item(tt(_cmdstring))( +Completes an external command as a single argument, as for +tt(system+LPAR()...+RPAR()). +) findex(_complete) item(tt(_complete))( This completer generates all possible completions in a context-sensitive @@ -3207,6 +3230,11 @@ tt(old-menu), see ifzman(the section `Completion System Configuration' above)\ ifnzman(noderef(Completion System Configuration)). ) +findex(_precommand) +item(tt(_precommand))( +Complete an external command in word-separated arguments, as for +tt(exec) and tt(/usr/bin/env). +) findex(_prefix) item(tt(_prefix))( This completer can be used to try completion with the suffix (everything @@ -3573,13 +3601,11 @@ This function can be used to give a complete specification for completion for a command whose arguments follow standard UNIX option and argument conventions. -em(Options overview) +em(Options Overview) Options to tt(_arguments) itself must be in separate words, i.e. tt(-s -w), not tt(-sw). The options are followed by var(spec)s that describe options and -arguments of the analyzed command. var(spec)s that describe option flags must -precede var(spec)s that describe non-option ("positional" or "normal") -arguments of the analyzed line. To avoid ambiguity, all +arguments of the analyzed command. To avoid ambiguity, all options to tt(_arguments) itself may be separated from the var(spec) forms by a single colon. @@ -3997,18 +4023,48 @@ example(local curcontext="$curcontext") This is useful where it is not possible for multiple states to be valid together. -em(Specifying multiple sets of options) +em(Grouping Options) -It is possible to specify multiple sets of options and -arguments with the sets separated by single hyphens. The specifications -before the first hyphen (if any) are shared by all the remaining sets. -The first word in every other set provides a name for the -set which may appear in exclusion lists in specifications, -either alone or before one of the possible values described above. -In the second case a `tt(-)' should appear between this name and the -remainder. +Options can be grouped to simplify exclusion lists. A group is +introduced with `tt(PLUS())' followed by a name for the group in the +subsequent word. Whole groups can then be referenced in an exclusion +list or a group name can be used to disambiguate between two forms of +the same option. For example: -For example: +example(_arguments \ + '(group2--x)-a' \ + PLUS() group1 \ + -m \ + '(group2)-n' \ + PLUS() group2 \ + -x -y) + +If the name of a group is specified in the form +`tt(LPAR())var(name)tt(RPAR())' then only one value from that group +will ever be completed; more formally, all specifications are mutually +exclusive to all other specifications in that group. This is useful for +defining options that are aliases for each other. For example: + +example(_arguments \ + -a -b \ + PLUS() '(operation)' \ + {-c,--compress}'[compress]' \ + {-d,--decompress}'[decompress]' \ + {-l,--list}'[list]') + +If an option in a group appears on the command line, it is stored in the +associative array `tt(opt_args)' with 'var(group)tt(-)var(option)' +as a key. In the example above, a key `tt(operation--c)' is used if the option +`tt(-c)' is present on the command line. + +em(Specifying Multiple Sets of Arguments) + +It is possible to specify multiple sets of options and arguments with +the sets separated by single hyphens. This differs from groups in that +sets are considered to be mutually exclusive of each other. + +Specifications before the first set and from any group are common to +all sets. For example: example(_arguments \ -a \ @@ -4024,28 +4080,11 @@ possible completions. When it contains `tt(-d)' or an argument, the option `tt(-c)' will not be considered. However, after `tt(-a)' both sets will still be considered valid. -If an option in a set appears on the command line, it is stored in the -associative array `tt(opt_args)' with 'var(set)tt(-)var(option)' -as a key. In the example above, a key `tt(set1--c)' is used if the option -`tt(-c)' is on the command line. - -If the name given for one of the mutually exclusive sets is of the form -`tt(LPAR())var(name)tt(RPAR())' then only one value from each set will ever -be completed; more formally, all specifications are mutually -exclusive to all other specifications in the same set. This is -useful for defining multiple sets of options which are mutually -exclusive and in which the options are aliases for each other. For -example: - -example(_arguments \ - -a -b \ - - '(compress)' \ - {-c,--compress}'[compress]' \ - - '(uncompress)' \ - {-d,--decompress}'[decompress]') +As for groups, the name of a set may appear in exclusion lists, either +alone or preceding a normal option or argument specification. -As the completion code has to parse the command line separately for each -set this form of argument is slow and should only be used when necessary. +The completion code has to parse the command line separately for each +set. This can be slow so sets should only be used when necessary. A useful alternative is often an option specification with rest-arguments (as in `tt(-foo:*:...)'); here the option tt(-foo) swallows up all remaining arguments as described by the var(optarg) definitions. |