diff options
Diffstat (limited to 'Doc/Zsh/compsys.yo')
| -rw-r--r-- | Doc/Zsh/compsys.yo | 277 |
1 files changed, 216 insertions, 61 deletions
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 89b918d60..f75298a1b 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -190,7 +190,7 @@ tt(compinit) will ask if the completion system should really be used. To avoid these tests and make all files found be used without asking, use the option tt(-u), and to make tt(compinit) silently ignore all insecure files and directories use the option tt(-i). This security check is skipped -entirely when the tt(-C) option is given. +entirely when the tt(-C) option is given, provided the dumpfile exists. findex(compaudit) The security check can be retried at any time by running the function @@ -322,15 +322,15 @@ item(tt(-array-value-))( The right hand side of an array-assignment (`var(name)tt(=LPAR())var(...)tt(RPAR())') ) -kindex(-brace-parameter-, completion context) -item(tt(-brace-parameter-))( -The name of a parameter expansion within braces (`tt(${)var(...)tt(})') -) kindex(-assign-parameter-, completion context) item(tt(-assign-parameter-))( The name of a parameter in an assignment, i.e. on the left hand side of an `tt(=)' ) +kindex(-brace-parameter-, completion context) +item(tt(-brace-parameter-))( +The name of a parameter expansion within braces (`tt(${)var(...)tt(})') +) kindex(-command-, completion context) item(tt(-command-))( A word in command position @@ -891,14 +891,14 @@ kindex(indexes, completion tag) item(tt(indexes))( for array indexes ) -kindex(jobs, completion tag) -item(tt(jobs))( -for jobs (as listed by the `tt(jobs)' builtin) -) kindex(interfaces, completion tag) item(tt(interfaces))( for network interfaces ) +kindex(jobs, completion tag) +item(tt(jobs))( +for jobs (as listed by the `tt(jobs)' builtin) +) kindex(keymaps, completion tag) item(tt(keymaps))( for names of zsh keymaps @@ -922,14 +922,14 @@ directory when completing arguments of tt(cd) and related builtin commands (compare tt(path-directories)) DASH()- when the tt(cdpath) array is unset, tt(directories) is used instead ) -kindex(manuals, completion tag) -item(tt(manuals))( -for names of manual pages -) kindex(mailboxes, completion tag) item(tt(mailboxes))( for e-mail folders ) +kindex(manuals, completion tag) +item(tt(manuals))( +for names of manual pages +) kindex(maps, completion tag) item(tt(maps))( for map names (e.g. NIS maps) @@ -979,11 +979,6 @@ kindex(other-accounts, completion tag) item(tt(other-accounts))( used to look up the tt(users-hosts) style ) -kindex(other-files, completion tag) -item(tt(other-files))( -for the names of any non-directory files. This is used instead -of tt(all-files) when the tt(list-dirs-first) style is in effect. -) kindex(packages, completion tag) item(tt(packages))( for packages (e.g. tt(rpm) or installed tt(Debian) packages) @@ -1394,6 +1389,12 @@ components after the first ambiguous one will also be added. This means that the resulting string is the longest unambiguous string possible. However, menu completion can be used to cycle through all matches. ) +kindex(extra-verbose, completion style) +item(tt(extra-verbose))( +If set, the completion listing is more verbose at the cost of +a probable decrease in completion speed. Completion performance +will suffer if this style is set to `true'. +) kindex(fake, completion style) item(tt(fake))( This style may be set for any completion context. It @@ -1529,9 +1530,10 @@ If no `tt(:)var(tag)' is given the `tt(files)' tag will be used. The var(tag) may also be followed by an optional second colon and a description, which will be used for the `tt(%d)' in the value of the tt(format) style (if that is set) instead of the default -description supplied by the completion function. If the description -given here contains itself a `tt(%d)', that is replaced with the -description supplied by the completion function. +description supplied by the completion function. The inclusion +of a description also gives precedence to associated options such as +for completion grouping so it can be used where files should be +separated. For example, to make the tt(rm) command first complete only names of object files and then the names of all files if there is no matching @@ -1553,6 +1555,15 @@ all files using the pattern `tt(*)' at the first step and stops when it sees this pattern. Note also it will never try a pattern more than once for a single completion attempt. +To separate directories into a separate group from the files but still +complete them at the first attempt, a description needs to be given. +Note that directories need to be explicitly excluded from the +globbed-files because `tt(*)' will match directories. For grouping, it +is also necessary to set the tt(group-name) style. + +example(zstyle ':completion:*' file-patterns \ + '%p+LPAR()^-/RPAR():globbed-files *(-/):directories:location') + During the execution of completion functions, the tt(EXTENDED_GLOB) option is in effect, so the characters `tt(#)', `tt(~)' and `tt(^)' have special meanings in the patterns. @@ -1647,6 +1658,15 @@ ifzman(zmanref(zshmodules))\ ifnzman(noderef(The zsh/zutil Module))\ . ) +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(glob, completion style) item(tt(glob))( This is used by the tt(_expand) completer. If @@ -1793,12 +1813,6 @@ Excluded values act in a similar fashion to values of the tt(ignored-patterns) style, so they can be restored to consideration by the tt(_ignored) completer. ) -kindex(extra-verbose, completion style) -item(tt(extra-verbose))( -If set, the completion listing is more verbose at the cost of -a probable decrease in completion speed. Completion performance -will suffer if this style is set to `true'. -) kindex(ignored-patterns, completion style) item(tt(ignored-patterns))( A list of patterns; any trial completion matching one of the patterns @@ -1895,15 +1909,6 @@ 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 @@ -1919,6 +1924,13 @@ The behaviour of tt(_expand) when this style is `true' is to cause tt(_expand) to give up when a single expansion with the restored prefix is the same as the original; hence any remaining completers may be called. ) +kindex(known-hosts-files) +item(tt(known-hosts-files))( +This style should contain a list of files to search for host names and +(if the tt(use-ip) style is set) IP addresses in a format compatible with +ssh tt(known_hosts) files. If it is not set, the files +tt(/etc/ssh/ssh_known_hosts) and tt(~/.ssh/known_hosts) are used. +) kindex(last-prompt, completion style) item(tt(last-prompt))( This is a more flexible form of the tt(ALWAYS_LAST_PROMPT) option. @@ -1930,13 +1942,6 @@ previous line if this style is `true' for all types of match. Note that unlike the tt(ALWAYS_LAST_PROMPT) option this is independent of the numeric argument. ) -kindex(known-hosts-files) -item(tt(known-hosts-files))( -This style should contain a list of files to search for host names and -(if the tt(use-ip) style is set) IP addresses in a format compatible with -ssh tt(known_hosts) files. If it is not set, the files -tt(/etc/ssh/ssh_known_hosts) and tt(~/.ssh/known_hosts) are used. -) kindex(list, completion style) item(tt(list))( This style is used by the tt(_history_complete_word) bindable command. @@ -1976,11 +1981,10 @@ obtained by setting the style to an empty string (i.e. tt('')). ) kindex(list-dirs-first, completion style) item(tt(list-dirs-first))( -This is used by file completion. If set, directories to be completed -are listed separately from and before completion for other files, -regardless of tag ordering. In addition, the tag tt(other-files) -is used in place of tt(all-files) for the remaining files, to indicate -that no directories are presented with that tag. +This is used by file completion and corresponds to a particular +setting of the tt(file-patterns) style. +If set, the default directories to be completed +are listed separately from and before completion for other files. ) kindex(list-grouped, completion style) item(tt(list-grouped))( @@ -2019,8 +2023,8 @@ position shown as a percentage of the total length otherwise. In each case the form with the uppercase letter will be replaced by a string of fixed width, padded to the right with spaces, while the lowercase form will be replaced by a variable width string. As in other prompt strings, the -escape sequences `tt(%S)', `tt(%s)', `tt(%B)', `tt(%b)', `tt(%U)', -`tt(%u)' for entering and leaving the display modes +escape sequence `tt(%H)` along with `tt(%S)', `tt(%s)', `tt(%B)', `tt(%b)', +`tt(%U)', `tt(%u)' for entering and leaving the display modes standout, bold and underline, and `tt(%F)', `tt(%f)', `tt(%K)', `tt(%k)' for changing the foreground background colour, are also available, as is the form `tt(%{)...tt(%})' for enclosing escape sequences which display with zero @@ -2035,6 +2039,12 @@ This style is tested in the same way as the tt(list-packed) style and determines whether matches are to be listed in a rows-first fashion as if the tt(LIST_ROWS_FIRST) option were set. ) +kindex(list-separator, completion style) +item(tt(list-separator))( +The value of this style is used in completion listing to separate the +string to complete from a description when possible (e.g. when +completing options). It defaults to `tt(-)tt(-)' (two hyphens). +) kindex(list-suffixes, completion style) item(tt(list-suffixes))( This style is used by the function that completes filenames. If it is @@ -2042,12 +2052,6 @@ This style is used by the function that completes filenames. If it is typed pathname components, all ambiguous components will be shown. Otherwise, completion stops at the first ambiguous component. ) -kindex(list-separator, completion style) -item(tt(list-separator))( -The value of this style is used in completion listing to separate the -string to complete from a description when possible (e.g. when -completing options). It defaults to `tt(-)tt(-)' (two hyphens). -) kindex(local, completion style) item(tt(local))( This is for use with functions that complete URLs for which the @@ -3616,8 +3620,18 @@ described using the var(spec)s which are of the form: `var(tag)tt(:)var(descr)tt(:)var(action)'. The var(tag)s are offered using tt(_tags) and if the tag is requested, the var(action) is executed with the given description var(descr). The var(action)s are those accepted -by the tt(_arguments) function (described below), excluding the -`tt(->)var(state)' and `tt(=)var(...)' forms. +by the tt(_arguments) function (described below), with the following +exceptions: +startitemize() +itemiz(\ +The `tt(->)var(state)' and `tt(=)var(...)' forms are not supported. +) +itemiz(\ +The `tt(LPAR()LPAR()a\:bar b\:baz)tt(RPAR()RPAR())' form does not need +the colon to be escaped, since the var(spec)s have no colon-separated fields +after the var(action). +) +enditemize() For example, the var(action) may be a simple function call: @@ -4400,6 +4414,15 @@ Include the leading underscore (`tt(_)') in the matches. ) enditem() ) +findex(_default) +item(tt(_default))( +This function corresponds to the tt(-default-) special context which is +applied where no completion is defined. It is useful to call it under +certain error conditions such as completion after an unrecognised +subcommand. This applies the concept of graceful degradation to the +completion system, allowing it to fallback on basic completion of +commonly useful things like filenames. +) 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) ... ]) @@ -4473,8 +4496,22 @@ not contain an explanation string to be displayed above the matches. If tt(_description) is called with more than three arguments, the additional var(spec)s should be of the form `var(char)tt(:)var(str)'. These supply escape sequence replacements for the tt(format) style: -every appearance of `tt(%)var(char)' will be -replaced by var(string). +every appearance of `tt(%)var(char)' will be replaced by var(string). +If no additional var(spec)s are given but the description in var(descr) +conforms to a common form then further escape sequences are set for +elements of that description. These elements correspond to a default +value (`tt(%o)'), the units (`tt(%m)') range of acceptable values +(`tt(%r)') and the remaining initial part of the description (`tt(%h)'). +The form the description takes consists of specifying the units and +range in parentheses and the default value in square brackets, for +example: + +example(_description times expl 'timeout (seconds) (0-60) [20]') + +It is possible to use tt(zformat) conditional expressions when styling +these elements. So, for example, to add `tt(default:)' as a tag but only +when there is a default value to show, the tt(format) style might +include `tt(%(o.default: %o.))'. If the tt(-x) option is given, the description will be passed to tt(compadd) using the tt(-x) option instead of the default tt(-X). This @@ -4750,6 +4787,69 @@ checked. If it is set completion is terminated at that point even if no matches have been found. This is the same effect as in the tt(-first-) context. ) +findex(_numbers) +item(tt(_numbers) [ var(option) ... ] [ var(description) ] [ var(suffix) ... ])( +This can be used where a number is followed by a suffix to indicate the units. +The unit suffixes are completed and can also be included in the description +used when completion is invoked for the preceding number. + +In addition to common tt(compadd) options, tt(_numbers) accepts the following +options: + +startitem() +item(tt(-t) var(tag))( +Specify a tag to use instead of the default of tt(numbers). +) +item(tt(-u) var(units))( +Indicate the default units for the number, e.g. tt(bytes). +) +item(tt(-l) var(min))( +Specify the lowest possible value for the number. +) +item(tt(-m) var(max))( +Specify the highest possible value for the number. +) +item(tt(-d) var(default))( +Specify the default value. +) +item(tt(-N))( +Allow negative numbers. This is implied if the range includes a negative. +) +item(tt(-f))( +Allow decimal numbers. +) +enditem() + +Where a particular suffix represents the default units for a number, it +should be prefixed with a colon. Additionally, suffixes can be followed +by a colon and a description. So for example, the following allows the +age of something to be specified, either in seconds or with an optional +suffix with a longer unit of time: + +example(_numbers -u seconds age :s:seconds m:minutes h:hours d:days) + +It is typically helpful for units to be presented in order of magnitude +when completed. To facilitate this, the order in which they are given +is preserved. + +When the tt(format) style is looked up with the tt(descriptions) tag or +the tag specified with tt(-t), the list of suffixes is available as a +`tt(%x)' escape sequence. This is in addition to the usual sequences +documented under the tt(format) style. The form this list takes can also +be configured. To this end, the tt(format) style is first looked up with +the tag tt(unit-suffixes). The retrieved format is applied to each +suffix in turn and the results are then concatenated to form the +completed list. For the tt(unit-suffixes) format, `tt(%x)' expands to +the individual suffix and `tt(%X)' to its description. tt(%d)' indicates +a default suffix and can be used in a condition. The index and reverse +index are set in `tt(%i)' and `tt(%r)' respectively and are useful for +text included only with the first and last suffixes in the list. So for +example, the following joins the suffixes together as a comma-separated +list: + +example(zstyle ':completion:*:unit-suffixes' format '%x%(r::,)') +) + findex(_options) item(tt(_options))( This can be used to complete the names of shell options. It provides a @@ -5127,6 +5227,57 @@ the group name. This function is called automatically from tt(_description) and hence is not normally called explicitly. ) +findex(_shadow) +findex(_unshadow) +xitem(tt(_shadow) [ tt(-s) var(suffix) ] [ -- ] var(command_name) ...) +item(tt(_unshadow))( +The tt(_shadow) function creates a copy of each of the shell functions +in the var(command_name) arguments. The original functions can then +be replaced by new implementations. A later call to tt(_unshadow) +removes the new implementations, if any, and restores the originals. + +Recommended usage is to pair tt(_shadow) and tt(_unshadow) calls by +use of an `tt(always)' block: +example({ + _shadow fname + function fname { + # Do your new thing + } + # Invoke callers of fname +} always { + _unshadow +}) + +The var(suffix), if supplied, is prepended by an `tt(@)' character and +then appended to each var(command_name) to create the copy. Thus +example(_shadow -s XX foo) +creates a function named `tt(foo@XX)'. This provides a well-known +name for the original implementation if the new implementation needs +to call it as a wrapper. If a nested call to tt(_shadow) uses the +same var(suffix), em(no new copy is made). The presumption thus is +that suffixes and new implementations correspond one to one. + +If var(command_name) is a builtin or external command, and there has been +no preceding tt(_shadow) replacement made, the function so created calls +the shadowed name prefixed by the tt(builtin) or tt(command) keywords as +appropriate. +example({ + _shadow -s wrap compadd + compadd LPAR()RPAR() { + # compadd@wrap runs builtin compadd + compadd@wrap -O tmparr "$@" } +} always { + _unshadow +}) + +When no var(suffix) argument is present, tt(_shadow) creates a unique +suffix to avoid name collisions. + +Arguments of tt(_unshadow) are ignored. Every listed var(command_name) +for the most recent call to tt(_shadow) is removed. This differs from +an early implementation that required tt(_unshadow) to receive the +same var(suffix) and var(command_name) list as tt(_shadow). +) findex(_store_cache) item(tt(_store_cache) var(cache_identifier) var(param) ...)( This function, together with tt(_retrieve_cache) and @@ -5295,7 +5446,11 @@ matches with the given description: example(local expl _wanted tag expl 'description' \ - compadd matches...) + compadd -- var(match1) var(match2)...) + +See also the use of tt(_wanted) in the example function in +ifzman(the subsection `Dynamic named directories' in zmanref(zshexpn))\ +ifnzman(noderef(Dynamic named directories)). Note that, as for tt(_requested), the var(command) must be able to accept options to be passed down to tt(compadd). |