diff options
Diffstat (limited to 'Doc/Zsh/compctl.yo')
| -rw-r--r-- | Doc/Zsh/compctl.yo | 201 |
1 files changed, 11 insertions, 190 deletions
diff --git a/Doc/Zsh/compctl.yo b/Doc/Zsh/compctl.yo index b55aa91be..b65666d5d 100644 --- a/Doc/Zsh/compctl.yo +++ b/Doc/Zsh/compctl.yo @@ -1,4 +1,4 @@ -texinode(Programmable Completion Using compctl)(Completion Widgets)(Zsh Line Editor)(Top) +texinode(Programmable Completion Using compctl)(Zsh Modules)(Completion Widgets)(Top) chapter(Programmable Completion Using compctl) cindex(completion, programmable) cindex(completion, controlling) @@ -47,7 +47,6 @@ menu(Command Flags) menu(Option Flags) menu(Alternative Completion) menu(Extended Completion) -menu(Matching Control) menu(Example) endmenu() @@ -132,8 +131,10 @@ the default. In other words, completion will subsequently use the options specified by the tt(-D) flag. The form with tt(-M) as the first and only option defines global -matching specifications, as described below in noderef(Matching -Control). +matching specifications, as described in +ifzman(zshcompwid)\ +ifnzman(noderef(Matching Control))\ +. texinode(Option Flags)(Alternative Completion)(Command Flags)(Programmable Completion Using compctl) sect(Option Flags) @@ -523,7 +524,10 @@ different name spaces. item(tt(-M) var(match-spec))( This defines additional matching control specifications that should be used only when testing words for the list of flags this flag appears in. The format -of the var(match-spec) string is described below in noderef(Matching Control). +of the var(match-spec) string is described in +ifzman(zshcompwid)\ +ifnzman(noderef(Matching Control))\ +. ) enditem() @@ -542,7 +546,7 @@ up to that point, default completion is tried. If the list of flags contains a tt(-t) with a tt(PLUS()) character, the next list of flags is used even if the current list produced matches. -texinode(Extended Completion)(Matching Control)(Alternative Completion)(Programmable Completion Using compctl) +texinode(Extended Completion)(Example)(Alternative Completion)(Programmable Completion Using compctl) sect(Extended Completion) startlist() list(nofill(tt(compctl) [ tt(-CDT) ] var(options) \ @@ -653,190 +657,7 @@ completion is done in backticks and var(str) starts with a `b'. ) enditem() -texinode(Matching Control)(Example)(Extended Completion)(Programmable Completion Using compctl) -sect(Matching Control) - -It is possible by use of the tt(-M) var(spec) flag to specify how the -characters in the string to be completed (referred to here as the -command line) map onto the characters in the list of matches produced by -the completion code (referred to here as the trial completions). Note -that this is not used if the command line contains a glob pattern and -the tt(GLOB_COMPLETE) option is set. - -The var(spec) consists of one or more matching descriptions separated by -whitespace. Each description consists of a letter followed by a colon, -then the patterns describing which character sequences on the line match -which character sequences in the trial completion. Any sequence of characters not -handled in this fashion must match exactly, as usual. - -The forms of var(spec) understood are as follows. In each case, the -form with an uppercase initial character retains the string already -typed on the command line as the final result of completion, while with -a lowercase initial character the string on the command line is changed -into the corresponding part of the trial completion. - -startitem() -xitem(tt(m:)var(lpat)tt(=)var(tpat)) -item(tt(M:)var(lpat)tt(=)var(tpat))( -Here, var(lpat) is a pattern that matches on the command line, -corresponding to var(tpat) which matches in the trial completion. -) -xitem(tt(l:)var(anchor)tt(|)var(lpat)tt(=)var(tpat)) -item(tt(L:)var(anchor)tt(|)var(lpat)tt(=)var(tpat))( -These letters are for patterns that are anchored by another pattern on -the left side. Matching for var(lpat) and var(tpat) is as for tt(m) and -tt(M), but the pattern var(lpat) matched on the command line must be -preceeded by the pattern var(anchor). The var(anchor) can be blank to -anchor the match to the start of the command line string; otherwise the -anchor can occur anywhere, but must match in both the command line and -trial completion strings. -) -xitem(tt(r:)var(lpat)tt(|)var(anchor)tt(=)var(tpat)) -item(tt(R:)var(lpat)tt(|)var(anchor)tt(=)var(tpat))( -As tt(l) and tt(L) with the difference that the command line and trial -completion patterns are anchored on the right side. Here an empty -var(anchor) forces the match to the end of the command line string. -) -enditem() - -Each var(lpat), var(tpat) or var(anchor) is either an empty string or -consists of a sequence of literal characters (which may be quoted with a -backslash), question marks, character classes, and correspondence -classes; ordinary shell patterns are not used. Literal characters match -only themselves, question marks match any character, and character -classes are formed as for globbing and match any character in the given -set. - -Correspondence classes are defined like character classes, but with two -differences: they are delimited by a pair of braces, and negated classes -are not allowed, so the characters tt(!) and tt(^) have no special -meaning directly after the opening brace. They indicate that a range of -characters on the line match a range of characters in the trial -completion, but (unlike ordinary character classes) paired according to -the corresponding position in the sequence. For example, to make any -lowercase letter on the line match the corresponding uppercase letter in -the trial completion, you can use `tt(m:{a-z}={A-Z})'. More than one -pair of classes can occur, in which case the first class before the -tt(=) corresponds to the first after it, and so on. If one side has -more such classes than the other side, the superfluous classes behave -like normal character classes. In anchor patterns correspondence classes -also behave like normal character classes. - -The pattern var(tpat) may also be a single star, `tt(*)'. This means -that the pattern on the command line can match any number of characters -in the trial completion. In this case the pattern must be anchored (on -either side); the var(anchor) then determines how much of the trial -completion is to be included --- only the characters up to the next -appearance of the anchor will be matched. - -Examples: - -The option tt(-o) produces option names in all-lowercase form, without -underscores, and without the optional tt(no) at the beginning even -though the builtins tt(setopt) and tt(unsetopt) understand option names -with uppercase letters, underscores, and the optional tt(no). The -following alters the matching rules so that the prefix tt(no) and any -underscore are ignored when trying to match the trial completions -generated and uppercase letters on the line match the corresponding -lowercase letters in the words: - -example(compctl -M 'L:|[nN][oO]= M:_= M:{A-Z}={a-z}' \ - -o setopt unsetopt) - -The first part says that the pattern `tt([nN][oO])' at the beginning -(the empty anchor before the pipe symbol) of the string on the -line matches the empty string in the list of words generated by -completion, so it will be ignored if present. The second part does the -same for an underscore anywhere in the command line string, and the -third part uses correspondence classes so that any -uppercase letter on the line matches the corresponding lowercase -letter in the word. The use of the uppercase forms of the -specification characters (tt(L) and tt(M)) guarantees that what has -already been typed on the command line (in particular the prefix -tt(no)) will not be deleted. - -The second example makes completion case insensitive. By using -tt(compctl) with the tt(-M) option alone this applies to every -completion. This is just the same as in the tt(setopt) example, except -here we wish to retain the characters in the list of completions: - -example(compctl -M 'm:{a-z}={A-Z}') - -This makes lowercase letters match their uppercase counterparts. -To make uppercase letters match the lowercase forms as well: - -example(compctl -M 'm:{a-zA-Z}={A-Za-z}') - -A nice example for the use of tt(*) patterns is partial word -completion. Sometimes you would like to make strings like tt(c.s.u) -complete to strings like tt(comp.source.unix), i.e. the word on the -command line consists of multiple parts, separated by a dot in this -example, where each part should be completed separately --- note, -however, that the case where each part of the word, i.e. tt(comp), -tt(source) and tt(unix) in this example, is to be completed separately -is a different problem to be solved by extended completion. The -example can be handled by: - -example(compctl -M 'r:|.=* r:|=*' \ - -k '(comp.sources.unix comp.sources.misc ...)' ngroups) - -The first specification says that tt(lpat) is the empty string, while -tt(anchor) is a dot; tt(tpat) is tt(*), so this can match anything -except for the `tt(.)' from the anchor in -the trial completion word. So in tt(c.s.u), the matcher sees tt(c), -followed by the empty string, followed by the anchor `tt(.)', and -likewise for the second dot, and replaces the empty strings before the -anchors, giving tt(c)[tt(omp)]tt(.s)[tt(ources)]tt(.u)[tt(nix)], where -the last part of the completion is just as normal. - -The second specification is needed to make this work when the cursor is -in the middle of the string on the command line and the option -tt(COMPLETE_IN_WORD) is set. In this case the completion code would -normally try to match trial completions that end with the string as -typed so far, i.e. it will only insert new characters at the cursor -position rather then at the end. However in our example we would like -the code to recognise matches which contain extra characters after the -string on the line (the tt(nix) in the example). Hence we say that the -empty string at the end of the string on the line matches any characters -at the end of the trial completion. - -More generally, the specification - -example(compctl -M 'r:|[.,_-]=* r:|=*') - -allows one to complete words with abbreviations before any of the -characters in the square brackets in any completion. For example, to -complete tt(veryverylongfile.c) rather than tt(veryverylongheader.h) -with the above in effect, you can just type tt(very.c) before attempting -completion. - -The form tt(compctl -M) that defines global matching actually accepts -any number of specification strings, unlike the case where the tt(-M) -option applies only to a particular command. In this case, when -completion is attempted for any command, the code will try the -specifications in order until one matches. This allows one to define -simple and fast matches to be used first, more powerful matchers as a -second choice, and so on. These global matchers can also be defined by -setting the tt(compmatchers) special array to the strings that would -otherwise be given to tt(compctl -M) as arguments. - -For example, one can make the code match trial completions that contain -the string on the command line as a substring, not just at the -beginning. Since this might produce more matches than we want, -we arrange for it to be tried only if the matchers described above don't -produce any matches: - -example(compctl -M 'r:|[.,_-]=* r:|=*' 'l:|=* r:|=*') - -Here, if the string on the command line is tt(foo.bar), tt(compctl) -first tries matching tt(foo)var(anything)tt(.bar)var(anything), as -with the previous example. If that fails, the two descriptions in the -second string after the tt(-M) say that the blanks at the beginning -and end of the string on the command line can match any set of -characters at the beginning or end of the trial completion, so it will -look for var(anything)tt(foo.bar)var(anything). - -texinode(Example)()(Matching Control)(Programmable Completion Using compctl) +texinode(Example)()(Extended Completion)(Programmable Completion Using compctl) sect(Example) example(compctl -u -x 's[tt(PLUS())] c[-1,-f],s[-f+PLUS()]' \ |