diff options
Diffstat (limited to 'Doc/Zsh/compsys.yo')
| -rw-r--r-- | Doc/Zsh/compsys.yo | 302 |
1 files changed, 238 insertions, 64 deletions
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index d478e818e..47b07e85e 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -91,6 +91,7 @@ menu(Control Functions) menu(Bindable Commands) menu(Completion Functions) menu(Completion Directories) +menu(Completion System Variables) endmenu() texinode(Initialization)(Completion System Configuration)()(Completion System) @@ -825,6 +826,10 @@ kindex(domains, completion tag) item(tt(domains))( for network domains ) +kindex(email-*, completion tag) +item(tt(email-)var(plugin))( +for email addresses from the `tt(_email-)var(plugin)' backend of tt(_email_addresses) +) kindex(expansions, completion tag) item(tt(expansions))( used by the tt(_expand) completer for individual words (as opposed to @@ -1110,14 +1115,14 @@ tt(default) tag. The most notable styles of this type are tt(menu), tt(list-colors) and styles controlling completion listing such as tt(list-packed) and tt(last-prompt). When tested for the tt(default) tag, only the var(function) field of the context will be set so that -a style using the default tag will normally be defined along the lines of: +a style using the tt(default) tag will normally be defined along the lines of: example(zstyle ':completion:*:default' menu ...) startitem() kindex(accept-exact, completion style) item(tt(accept-exact))( -This is tested for the default tag in addition to the tags valid for +This is tested for the tt(default) tag in addition to the tags valid for the current context. If it is set to `true' and any of the trial matches is the same as the string on the command line, this match will immediately be accepted (even if it would otherwise be considered @@ -1153,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'. ) @@ -1423,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. @@ -1842,6 +1854,15 @@ In the case of the tt(_match) completer, the style may also be set to the string `tt(pattern)'. Then the pattern on the line is left unchanged if it does not match unambiguously. ) +kindex(gain-privileges, completion style) +item(tt(gain-privileges))( +If set to tt(true), this style enables the use of commands like tt(sudo) +or tt(doas) to gain extra privileges when retrieving information for +completion. This is only done when a command such as tt(sudo) appears on +the command-line. To force the use of, e.g. tt(sudo) or to override any +prefix that might be added due to tt(gain-privileges), the tt(command) +style can be used with a value that begins with a hyphen. +) kindex(keep-prefix, completion style) item(tt(keep-prefix))( This style is used by the tt(_expand) completer. If it is `true', the @@ -2023,8 +2044,9 @@ only be performed with the `tt(*)' inserted. kindex(matcher, completion style) item(tt(matcher))( This style is tested separately for each tag valid in the current -context. Its value is tried before any match specifications given by the -tt(matcher-list) style. It should be in the form described in +context. Its value is placed before any match specifications given by the +tt(matcher-list) style so can override them via the use of an tt(x:) +specification. The value should be in the form described in ifzman(the section `Completion Matching Control' in zmanref(zshcompwid))\ ifnzman(noderef(Completion Matching Control))\ . For examples of this, see the description of the tt(tag-order) style. @@ -2181,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)'. @@ -2977,6 +2999,21 @@ widgets to find out if the command line hasn't changed since the last time completion was tried. Only then are the tt(_ignored), tt(_correct) and tt(_approximate) completers called. ) +findex(_canonical_paths) +item(tt(_canonical_paths) [ tt(-A) var(var) ] [ tt(-N) ] [ tt(-MJV12nfX) ] var(tag) var(descr) [ var(paths) ... ])( +This completion function completes all paths given to it, and also tries to +offer completions which point to the same file as one of the paths given +(relative path when an absolute path is given, and vice versa; when tt(..)'s +are present in the word to be completed; and some paths got from symlinks). + +tt(-A), if specified, takes the paths from the array variable specified. Paths can +also be specified on the command line as shown above. tt(-N), if specified, +prevents canonicalizing the paths given before using them for completion, in +case they are already so. The options tt(-M), tt(-J), tt(-V), tt(-1), tt(-2), +tt(-n), tt(-F), tt(-X) are passed to tt(compadd). + +See tt(_description) for a description of var(tag) and var(descr). +) findex(_complete) item(tt(_complete))( This completer generates all possible completions in a context-sensitive @@ -3093,6 +3130,15 @@ completion continues to allow other completers such as tt(_expand) to expand the pattern. The standard tt(add-space) and tt(prefix-hidden) styles are observed. ) +findex(_external_pwds) +item(tt(_external_pwds))( +Completes current directories of other zsh processes belonging to the +current user. + +This is intended to be used via tt(_generic), bound to a custom key +combination. Note that pattern matching is enabled so matching is +performed similar to how it works with the tt(_match) completer. +) findex(_history) item(tt(_history))( Complete words from the shell's command history. This completer @@ -3222,6 +3268,7 @@ for the current context; remember that the context for completers is less specific than that for contextual completion as the full context has not yet been determined. Elements of the array may have one of the following forms: + startsitem() sitem(tt($)var(hash))( var(hash) is the name of an associative array. Note this is not a full @@ -3442,7 +3489,7 @@ emacs and vi respectively. ) enditem() -texinode(Completion Functions)(Completion Directories)(Bindable Commands)(Completion System) +texinode(Completion Functions)(Completion System Variables)(Bindable Commands)(Completion System) sect(Utility Functions) cindex(completion system, utility functions) @@ -3455,12 +3502,6 @@ generating matches all follow the convention of returning status zero if they generated completions and non-zero if no matching completions could be added. -Two more features are offered by the tt(_main_complete) function. The -arrays tt(compprefuncs) and tt(comppostfuncs) may contain -names of functions that are to be called immediately before or after -completion has been tried. A function will only be called once unless -it explicitly reinserts itself into the array. - startitem() findex(_absolute_command_paths) item(tt(_absolute_command_paths))( @@ -3539,13 +3580,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. @@ -3590,8 +3629,9 @@ even if one or more of the options take arguments. For example, if tt(-x) takes an argument, with no tt(-s), `tt(-xy)' is considered as a single (unhandled) option; with tt(-s), tt(-xy) is an option with the argument `tt(y)'; with both tt(-s) -and tt(-w), tt(-xy) may be the option tt(-x) and the option tt(-y) with -arguments still to come. +and tt(-w), tt(-xy) is the option tt(-x) and the option tt(-y) with +arguments to tt(-x) (and to tt(-y), if it takes arguments) still to come +in subsequent words. ) item(tt(-W))( This option takes tt(-w) a stage further: it is possible to @@ -3816,7 +3856,7 @@ form below, the var(action) will be executed by calling the tt(_all_labels) function to process all tag labels. No special handling of tags is needed unless a function call introduces a new one. -The functions called to execute var(action)s will be called with the the +The functions called to execute var(action)s will be called with the elements of the array named by the `tt(-O) var(name)' option as arguments. This can be used, for example, to pass the same set of options for the tt(compadd) builtin to all var(action)s. @@ -3931,8 +3971,8 @@ command line after the command name excluding all options and their arguments. Options are stored in the associative array `tt(opt_args)' with option names as keys and their arguments as the values. For options that have more than one argument these are -given as one string, separated by colons. All colons in the original -arguments are preceded with backslashes. +given as one string, separated by colons. All colons and backslashes +in the original arguments are preceded with backslashes. The parameter `tt(context)' is set when returning to the calling function to perform an action of the form `tt(->)var(string)'. It is set to an @@ -3962,18 +4002,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 \ @@ -3989,28 +4059,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. @@ -4156,7 +4209,7 @@ The return status of tt(_call_function) itself is zero if the function var(name) exists and was called and non-zero otherwise. ) findex(_call_program) -item(tt(_call_program) var(tag) var(string) ...)( +item(tt(_call_program) [ tt(-p) ] var(tag) var(string) ...)( This function provides a mechanism for the user to override the use of an external 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 @@ -4164,6 +4217,15 @@ execute. The var(string)s from the call to tt(_call_program), or from the style if set, are concatenated with spaces between them and the resulting string is evaluated. The return status is the return status of the command called. + +If the option `tt(-p)' is supplied it indicates that the command +output is influenced by the permissions it is run with. If the +tt(gain-privileges) style is set to true, tt(_call_program) will make +use of commands such as tt(sudo), if present on the command-line, to +match the permissions to whatever the final command is likely to run +under. When looking up the tt(gain-privileges) and tt(command) styles, +the command component of the zstyle context will end with a slash +(`tt(/)') followed by the command that would be used to gain privileges. ) findex(_combination) item(tt(_combination) [ tt(-s) var(pattern) ] var(tag) var(style) var(spec) ... var(field) var(opts) ...)( @@ -4216,6 +4278,16 @@ This function completes words that are valid at command position: names of aliases, builtins, hashed commands, functions, and so on. With the tt(-e) flag, only hashed commands are completed. The tt(-) flag is ignored. ) +findex(_completers) +item(tt(_completers) [ tt(-p) ])( +This function completes names of completers. + +startitem() +item(tt(-p))( +Include the leading underscore (`tt(_)') in the matches. +) +enditem() +) findex(_describe) redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ @ @ ))ifnztexi( ))) xitem(tt(_describe )[tt(-12JVx)] [ tt(-oO) | tt(-t) var(tag) ] var(descr) var(name1) [ var(name2) ] [ var(opt) ... ]) @@ -4227,13 +4299,13 @@ different completion options var(opt)s. 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. This is followed by one or two names of arrays followed by options to pass to tt(compadd). The -first array contains the possible completions with their descriptions in +array var(name1) contains the possible completions with their descriptions in the form `var(completion)tt(:)var(description)'. Any literal colons in -var(completion) must be quoted with a backslash. If a second array is -given, it should have the same number of elements as the first; in this +var(completion) must be quoted with a backslash. If a var(name2) is +given, it should have the same number of elements as var(name1); in this case the corresponding elements are added as possible completions instead -of the var(completion) strings from the first array. The completion list -will retain the descriptions from the first array. Finally, a set of +of the var(completion) strings from var(name1). The completion list +will retain the descriptions from var(name1). Finally, a set of completion options can appear. If the option `tt(-o)' appears before the first argument, the matches added @@ -4317,6 +4389,21 @@ matches. Almost all calls to tt(compadd) within the completion system use a similar format; this ensures that user-specified styles are correctly passed down to the builtins which implement the internals of completion. ) +findex(_dir_list) +item(tt(_dir_list) [ tt(-s) var(sep) ] [ tt(-S) ])( +Complete a list of directory names separated by colons +(the same format as tt($PATH)). + +startitem() +item(tt(-s) var(sep))( +Use var(sep) as separator between items. +var(sep) defaults to a colon (`tt(:)'). +) +item(tt(-S))( +Add var(sep) instead of slash (`tt(/)') as an autoremoveable suffix. +) +enditem() +) findex(_dispatch) item(tt(_dispatch) var(context string) ...)( This sets the current context to var(context) and looks for completion @@ -4332,6 +4419,44 @@ tt($service) to the var(string) being tried, and sets the var(context/command) field (the fourth) of the tt($curcontext) parameter to the var(context) given as the first argument. ) +findex(_email_addresses) +item(tt(_email_addresses) [ tt(-c) ] [ tt(-n) var(plugin) ])( +Complete email addresses. Addresses are provided by plugins. + +startitem() +item(tt(-c))( +Complete bare tt(localhost@domain.tld) addresses, without a name part or +a comment. +Without this option, RFC822 `var(Firstname Lastname) tt(<)var(address)tt(>)' +strings are completed. +) +item(tt(-n) var(plugin))( +Complete aliases from var(plugin). +) +COMMENT(Intentionally leaving tt(-s) undocumented: new code should use +tt(_sequence) instead.)\ +enditem() + +The following plugins are available by default: +tt(_email-ldap) (see the tt(filter) style), +tt(_email-local) (completes var(user)tt(@)var(hostname) Unix addresses), +tt(_email-mail) (completes aliases from tt(~/.mailrc)), +tt(_email-mush), +tt(_email-mutt), +and +tt(_email-pine). + +Addresses from the tt(_email-)var(foo) plugin are added under the +tag `tt(email-)var(foo)'. + +em(Writing plugins) + +Plugins are written as separate functions with names starting with `tt(_email-)'. +They are invoked with the tt(-c) option and tt(compadd) options. +They should either do their own completion or +set the tt($reply) array to a list of `var(alias)tt(:)var(address)' elements and return tt(300). +New plugins will be picked up and run automatically. +) findex(_files) item(tt(_files))( The function tt(_files) calls tt(_path_files) with all the arguments it @@ -4416,7 +4541,7 @@ the time this function is called, tt(compstate[insert]) is cleared, so additional matches generated later are not inserted on the command line. ) findex(_multi_parts) -item(tt(_multi_parts) var(sep) var(array))( +item(tt(_multi_parts) [ tt(-i) ] var(sep) var(array))( The argument var(sep) is a separator character. The var(array) may be either the name of an array parameter or a literal array in the form @@ -4916,12 +5041,18 @@ particular tag is to be tried, the tt(_requested) function should be called (see above). If `tt(-C) var(name)' is given, var(name) is temporarily stored in the -argument field (the fifth) of the context in the tt(curcontext) parameter +var(argument) field (the fifth) of the context in the tt(curcontext) parameter during the call to tt(_tags); the field is restored on exit. This allows tt(_tags) to use a more specific context without having to change and reset the tt(curcontext) parameter (which has the same effect). ) +findex(_tilde_files) +item(tt(_tilde_files))( +Like tt(_files), but resolve leading tildes according to the rules of +filename expansion, so the suggested completions don't start with +a `tt(~)' even if the filename on the command-line does. +) findex(_values) item(tt(_values) [ tt(-O) var(name) ] [ tt(-s) var(sep) ] [ tt(-S) var(sep) ] [ tt(-wC) ] var(desc) var(spec) ...)( This is used to complete arbitrary keywords (values) and their arguments, @@ -5044,9 +5175,52 @@ Like tt(_tags) this function supports the tt(-C) option to give a different name for the argument context field. The tt(-x) option has the same meaning as for tt(_description). ) +findex(_widgets) +item(tt(_widgets) [ tt(-g) var(pattern) ])( +This function completes names of zle widgets (see +ifzman(the section `Widgets' in zmanref(zshzle))\ +ifnzman(noderef(Zle Widgets))\ +). The var(pattern), if present, is matched against values of the tt($widgets) +special parameter, documented in +ifzman(the section `The zsh/zleparameter Module' in zmanref(zshmodules))\ +ifnzman(noderef(The zsh/zleparameter Module)). +) enditem() -texinode(Completion Directories)()(Completion Functions)(Completion System) +texinode(Completion System Variables)(Completion Directories)(Completion Functions)(Completion System) +sect(Completion System Variables) +cindex(completion system, variables) + +There are some standard variables, initialised by the tt(_main_complete) +function and then used from other functions. + +The standard variables are: + +startitem() +item(tt(_comp_caller_options))( +The completion system uses tt(setopt) to set a number of options. This +allows functions to be written without concern for compatibility with +every possible combination of user options. However, sometimes completion +needs to know what the user's option preferences are. These are saved +in the tt(_comp_caller_options) associative array. Option names, spelled +in lowercase without underscores, are mapped to one or other of the +strings `tt(on)' and `tt(off)'. +) + +item(tt(_comp_priv_prefix))( +Completion functions such as tt(_sudo) can set the tt(_comp_priv_prefix) +array to a command prefix that may then be used by tt(_call_program) to +match the privileges when calling programs to generate matches. +) +enditem() + +Two more features are offered by the tt(_main_complete) function. The +arrays tt(compprefuncs) and tt(comppostfuncs) may contain +names of functions that are to be called immediately before or after +completion has been tried. A function will only be called once unless +it explicitly reinserts itself into the array. + +texinode(Completion Directories)()(Completion System Variables)(Completion System) sect(Completion Directories) cindex(completion system, directory structure) |