diff options
Diffstat (limited to 'Doc/Zsh/compsys.yo')
| -rw-r--r-- | Doc/Zsh/compsys.yo | 204 |
1 files changed, 176 insertions, 28 deletions
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 2aa0740b8..60ef9ee2c 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) @@ -143,8 +144,8 @@ directory mentioned in the tt(fpath) parameter, and should be autoloaded few utility functions, arrange for all the necessary shell functions to be autoloaded, and will then re-define all widgets that do completion to use the new system. If you use the tt(menu-select) widget, which is part of the -tt(zsh/complist) module, you should make sure that that module is loaded -before the call to tt(compinit) so that that widget is also +tt(zsh/complist) module, you should make sure that the module is loaded +before the call to tt(compinit) so that the widget is also re-defined. If completion styles (see below) are set up to perform expansion as well as completion by default, and the TAB key is bound to tt(expand-or-complete), tt(compinit) will rebind it to tt(complete-word); @@ -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 @@ -1554,7 +1559,8 @@ of the links themselves. ) kindex(filter, completion style) item(tt(filter))( -This is used by the LDAP plugin for e-mail address completion to specify +The tt(ldap) plugin of email address completion (see tt(_email_addresses)) uses +this style to specify the attributes to match against when filtering entries. So for example, if the style is set to `tt(sn)', matching is done against surnames. Standard LDAP filtering is used so normal completion matching is bypassed. If this @@ -1841,6 +1847,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 @@ -2022,8 +2037,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. @@ -2976,6 +2992,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 @@ -3221,6 +3252,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 @@ -3441,7 +3473,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) @@ -3454,12 +3486,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))( @@ -3589,8 +3615,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 @@ -3815,7 +3842,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. @@ -3930,8 +3957,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 @@ -4155,7 +4182,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 @@ -4163,6 +4190,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) ...)( @@ -4215,6 +4251,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) ... ]) @@ -4226,13 +4272,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 @@ -4316,6 +4362,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 @@ -4331,6 +4392,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 @@ -4415,7 +4514,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 @@ -4915,12 +5014,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, @@ -5043,9 +5148,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 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() -texinode(Completion Directories)()(Completion Functions)(Completion System) +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) |