diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/Zsh/builtins.yo | 18 | ||||
| -rw-r--r-- | Doc/Zsh/compctl.yo | 447 | ||||
| -rw-r--r-- | Doc/Zsh/expn.yo | 45 | ||||
| -rw-r--r-- | Doc/Zsh/files.yo | 6 | ||||
| -rw-r--r-- | Doc/Zsh/metafaq.yo | 22 | ||||
| -rw-r--r-- | Doc/Zsh/mod_zle.yo | 14 | ||||
| -rw-r--r-- | Doc/Zsh/options.yo | 31 | ||||
| -rw-r--r-- | Doc/Zsh/params.yo | 8 |
8 files changed, 350 insertions, 241 deletions
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index 98110d122..4a86b16de 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -913,7 +913,9 @@ is unset, the other will automatically be unset too. There is no way of untying the variables without unsetting them, or converting the type of one them with another tt(typeset) command; tt(+T) does not work, assigning an array to var(SCALAR) is an error, and assigning a scalar -to var(array) sets it to be a single-element array. +to var(array) sets it to be a single-element array. Note that +both tt(typeset -xT ...) and tt(export -T ...) work, but only the +scalar will be marked for export. If no var(name) is present, the names and values of all parameters are printed. In this case the attribute flags restrict the the display to @@ -1072,10 +1074,16 @@ Each named parameter is unset. Local parameters remain local even if unset; they appear unset within scope, but the previous value will still reappear when the scope ends. -If the tt(-m) flag is specified the -arguments are taken as patterns (should be quoted) and all parameters -with matching names are unset. tt(unset -f) is equivalent to -tt(unfunction). +Individual elements of associative array parameters may be unset by using +subscript syntax on var(name), which should be quoted (or the entire command +prefixed with tt(noglob)) to protect the subscript from filename generation. + +If the tt(-m) flag is specified the arguments are taken as patterns (should +be quoted) and all parameters with matching names are unset. Note that this +cannot be used when unsetting associative array elements, as the subscript +will be treated as part of the pattern. + +tt(unset -f) is equivalent to tt(unfunction). ) findex(unsetopt) cindex(options, unsetting) diff --git a/Doc/Zsh/compctl.yo b/Doc/Zsh/compctl.yo index e9634a26f..f29be4731 100644 --- a/Doc/Zsh/compctl.yo +++ b/Doc/Zsh/compctl.yo @@ -32,6 +32,7 @@ menu(Extended Completion) menu(Matching Control) menu(Example) endmenu() + texinode(Command Flags)(Option Flags)()(Programmable Completion) sect(Command Flags) Completion of the arguments of a command may be different for each @@ -49,18 +50,20 @@ pathname containing slashes and no completion definition is found, the search is retried with the last pathname component. If the command starts with a tt(=), completion is tried with the pathname of the command. -The strings may also be patterns (i.e. they may contain an unquoted -occurrence of characters used to form patterns in the shell). When -completion is attempted, the shell first tries all such pattern compctls. -If one matches the command name on the line or if the pathname of the -command on the line matches a pattern, it is used. The patterns are tested -in reverse order, i.e. the pattern compctl defined last overrides all -previously defined pattern compctls. Unless the option list of that compctl -contains an tt(-t) flag with a \tt(c) character, no more compctls are tried. +Any of the var(command) strings may be patterns of the form normally +used for filename generation. These should be be quoted to protect them +from immediate expansion; for example the command string tt('foo*') +arranges for completion of the words of any command beginning with +tt(foo). When completion is attempted, all pattern completions are +tried in the reverse order of their definition until one matches. By +default, completion then procedes as normal, i.e. the shell will try to +generate more matches for the specific command on the command line; this +can be overridden by including tt(-tn) in the flags for the pattern +completion. Note that aliases are expanded before the command name is determined unless the -tt(COMPLETE_ALIASES) option is set. Commands should not be combined +tt(COMPLETE_ALIASES) option is set. Commands may not be combined with the tt(-C), tt(-D) or tt(-T) flags. ) item(tt(-C))( @@ -76,8 +79,8 @@ been issued, filenames are completed. ) item(tt(-T))( supplies completion flags to be used before any other processing is -done, even those given to specific commands with other compctl -definitions. This is especially useful when combined with extended +done, even before processing for tt(compctl)s defined for specific +commands. This is especially useful when combined with extended completion (the tt(-x) flag, see noderef(Extended Completion) below). Using this flag you can define default behavior which will apply to all commands without exception, or you can alter @@ -85,10 +88,12 @@ the standard behavior for all commands. For example, if your access to the user database is too slow and/or it contains too many users (so that completion after `tt(~)' is too slow to be usable), you can use -nofill(tt(compctl -Tx 'C[0,*/*]' -f - 's[~]' -k friends -S/ -tn)) +indent( +tt(compctl -T -x 'C[0,*/*]' -f - 's[~]' -k friends -S/ -tn) +) to complete the strings in the array tt(friends) after a `tt(~)'. -The first argument is necessary so that this form of ~-completion is +The tt(C[...]) argument is necessary so that this form of ~-completion is not tried after the directory name is finished. ) item(tt(-L))( @@ -111,7 +116,8 @@ 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 described below in noderef(Matching Control). +matching specifications, as described below in noderef(Matching Control). + texinode(Option Flags)(Alternative Completion)(Command Flags)(Programmable Completion) sect(Option Flags) startlist() @@ -136,6 +142,7 @@ menu(Simple Flags) menu(Flags with Arguments) menu(Control Flags) endmenu() + texinode(Simple Flags)(Flags with Arguments)()(Option Flags) subsect(Simple Flags) These produce completion lists made up by the shell itself: @@ -234,6 +241,7 @@ item(tt(-u))( User names. ) enditem() + texinode(Flags with Arguments)(Control Flags)(Simple Flags)(Option Flags) subsect(Flags with Arguments) These have user supplied arguments to determine how the list of @@ -248,8 +256,10 @@ of space- or comma-separated values in parentheses, in which any delimiter may be escaped with a backslash; in this case the argument should be quoted. For example, +indent( nofill(tt(compctl -k "(cputime filesize datasize stacksize - coredumpsize resident descriptors)" limit)) + coredumpsize resident descriptors)" limit)) +) ) item(tt(-g) var(globstring))( The var(globstring) is expanded using filename globbing; it should be @@ -282,8 +292,10 @@ should not be made local to the function. From such a function the command line can be accessed with the tt(-c) and tt(-l) flags to the tt(read) builtin. For example, +indent( nofill(tt(function whoson { reply=(`users`); } compctl -K whoson talk)) +) completes only logged-on users after `tt(talk)'. Note that `tt(whoson)' must return an array, so `tt(reply=`users`)' would be incorrect. @@ -295,12 +307,15 @@ zero or negative the whole history is searched and if var(pattern) is the empty string all words are taken (as with `tt(*)'). A typical use is -nofill(tt(compctl -D -f PLUS() -H 0 '')) +indent( +tt(compctl -D -f PLUS() -H 0 '') +) which forces completion to look back in the history list for a word if no filename matches. ) enditem() + texinode(Control Flags)()(Flags with Arguments)(Option Flags) subsect(Control Flags) These do not directly specify types of name to be completed, but @@ -322,7 +337,9 @@ The var(prefix) is inserted just before the completed string; any initial part already typed will be completed and the whole var(prefix) ignored for completion purposes. For example, -nofill(tt(compctl -j -P "%" kill)) +indent( +tt(compctl -j -P "%" kill) +) inserts a `%' after the kill command and then completes job names. ) @@ -337,20 +354,23 @@ With directory var(file-prefix): for command, file, directory and globbing completion (options tt(-c), tt(-f), tt(-/), tt(-g)), the file prefix is implicitly added in front of the completion. For example, -nofill(tt(compctl -/ -W ~/Mail maildirs)) +indent( +tt(compctl -/ -W ~/Mail maildirs) +) completes any subdirectories to any depth beneath the directory tt(~/Mail), although that prefix does not appear on the command line. -The var(suffix) may also be of the form accepted by the tt(-k) flag, i.e. -the name of an array or a literal list in parenthesis. In this cases all -words are used as prefixes. +The var(file-prefix) may also be of the form accepted by the tt(-k) +flag, i.e. the name of an array or a literal list in parenthesis. In +this case all the directories in the list will be searched for +possible completions. ) item(tt(-q))( If used with a suffix as specified by the tt(-S) option, this causes the suffix to be removed if the next character typed is a blank or does not insert anything or if the suffix consists of only one character -and the next character typed is the same character (the same rule as used -for the tt(AUTO_REMOVE_SLASH) option). The option is most useful for list +and the next character typed is the same character; this the same rule used +for the tt(AUTO_REMOVE_SLASH) option. The option is most useful for list separators (comma, colon, etc.). ) item(tt(-l) var(cmd))( @@ -365,7 +385,9 @@ option. If the var(cmd) string is empty the first word in the range is instead taken as the command name, and command name completion performed on the first word in the range. For example, -nofill(tt(compctl -x 'r[-exec,;]' -l '' -- find)) +indent( +tt(compctl -x 'r[-exec,;]' -l '' -- find) +) completes arguments between `tt(-exec)' and the following `tt(;)' (or the end of the command line if there is no such string) as if they were @@ -417,33 +439,52 @@ expansion following the usual rules for strings in double quotes. The expansion will be carried out after any functions are called for the tt(-K) or tt(-y) options, allowing them to set variables. ) -item(tt(-J))( +item(tt(-t) var(continue))( +The var(continue)-string contains a character that specifies which set +of completion flags should be used next. It is useful: + +(i) With tt(-T), or when trying a list of pattern completions, when +tt(compctl) would usually continue with ordinary processing after +finding matches; this can be suppressed with `tt(-tn)'. + +(ii) With a list of alternatives separated by tt(+), when tt(compctl) +would normally stop when one of the alternatives generates matches. It +can be forced to consider the next set of completions by adding `tt(-t+)' +to the flags of the alternative before the `tt(+)'. + +(iii) In an extended completion list (see below), when tt(compctl) would +normally continue until a set of conditions succeeded, then use only +the immediately following flags. With `tt(-t-)', tt(compctl) will +continue trying extended completions after the next `tt(-)'; with +`tt(-tx)' it will attempt completion with the default flags, in other +words those before the `tt(-x)'. +) +item(tt(-J) var(name))( This gives the name of the group the matches should be placed in. Groups -are listed and sorted separately. Also, menucompletion will offer the matches -in the groups in the order, in which the groups were defined. If no group -name is explicitly given, the matches are stored in a group named var(default). -The first time a group name is encountered, a group with that name is created. -After that all matches with the same group name are stored in that group. -) -item(tt(-V))( -Like tt(-J), but the matches in the group will not be sorted in the listing and -with menucompletion. These unsorted groups are in a different name space than -the sorted ones. I.e. it is possible to have a sorted and a unsorted group -with the same name and the matches in those groups will not be mixed. +are listed and sorted separately; likewise, menucompletion will offer +the matches in the groups in the order in which the groups were +defined. If no group name is explicitly given, the matches are stored in +a group named var(default). The first time a group name is encountered, +a group with that name is created. After that all matches with the same +group name are stored in that group. + +This can be useful with non-exclusive alternative completions. For +example, in + +indent( +tt(compctl -f -J files -t+ + -v -J variables foo) ) -item(tt(-t) var(continue))( -The var(continue)-string contains a character that specifies which set -of completion flags should be used next. Normally those of the next -matching compctl are used, i.e. pattern compctls and normal compctls -after tt(-T) and after a pattern compctl. If var(continue) is the -character tt(PLUS()) the flags for the next alternative completion -(see below) are used. The characters tt(-) and tt(x) can be used in -sub-lists for extended completion (see below). They will make the -completion code use the flag list after the next tt(-) (if the -corresponding pattern matches) and the default flag list (those before -the tt(-x)), respectively. if var(continue) is the character tt(n) no -other flag lists are used, i.e. the generation of matches stops -immediately. + +both files and variables are possible completions, as the tt(-t+) forces +both sets of alternatives before and after the tt(+) to be considered at +once. Because of the tt(-J) options, however, all files are listed +before all variables. +) +item(tt(-V) var(name))( +Like tt(-J), but matches within the group will not be sorted in listings +nor in menucompletion. These unsorted groups are in a different name +space than the sorted ones, so groups defined as tt(-J files) and tt(-V +files) are distinct. ) item(tt(-M) var(match-spec))( This defines additional matching control specifications that should be used @@ -451,6 +492,7 @@ 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). ) enditem() + texinode(Alternative Completion)(Extended Completion)(Option Flags)(Programmable Completion) sect(Alternative Completion) startlist() @@ -465,16 +507,17 @@ there are no flags after the last `tt(PLUS())' and a match has not been found 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) sect(Extended Completion) startlist() -list(tt(compctl) [ tt(-CDT) ] var(options) \ -tt(-x) var(pattern) var(options) tt(-) ... tt(--) \ -[ var(command) ... ]) -list(tt(compctl) [ tt(-CDT) ] var(options) \ -[ tt(-x) var(pattern) var(options) tt(-) ... tt(--) ] \ -[ tt(PLUS()) var(options) [ tt(-x) ... tt(--) ] ... [tt(PLUS())] ] \ -[ var(command) ... ]) +list(nofill(tt(compctl) [ tt(-CDT) ] var(options) \ +tt(-x) var(pattern) var(options) tt(-) ... tt(--) + [ var(command) ... ])) +list(nofill(tt(compctl) [ tt(-CDT) ] var(options) \ +[ tt(-x) var(pattern) var(options) tt(-) ... tt(--) ] + [ tt(PLUS()) var(options) [ tt(-x) ... tt(--) ] ... [tt(PLUS())] ] \ +[ var(command) ... ])) endlist() The form with `tt(-x)' specifies extended completion for the @@ -541,7 +584,9 @@ considered part of the completion, but the rest will. var(index) may be negative to count from the end: in most cases, var(index) will be 1 or -1. For example, -nofill(tt(compctl -s '`users`' -x 'n[1,@]' -k hosts -- talk)) +indent( +tt(compctl -s '`users`' -x 'n[1,@]' -k hosts -- talk) +) will usually complete usernames, but if you insert an tt(@) after the name, names from the array var(hosts) (assumed to contain hostnames, @@ -568,184 +613,192 @@ item(tt(R[)var(str1)tt(,)var(str2)tt(])...)( Like tt(r) but using pattern matching instead. ) enditem() + texinode(Matching Control)(Example)(Extended Completion)(Programmable Completion) sect(Matching Control) -Matching specifications are used to describe that certain strings -on the command line match possibly different strings in the words produced -by the completion code. +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). + +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. -Matching specification strings consist of one or more matching -descriptions separated by whitespace. Each description consists of -a letter followed by a colon and the patterns describing which character -sequences on the line match which character sequences in the words. +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. -The letters understood are: tt(l), tt(r), tt(m), tt(L), tt(R), and tt(M). startitem() -item(tt(m) and tt(M))( -These describe patterns that match anywhere in the words. The colon should -be followed by two patterns separated by an equal sign. The pattern on the -left side describes the substrings that are to be matched on the command line, -the pattern on the right side describes the substrings matched in the word. +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. ) -item(tt(l) and tt(L))( +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. In this case the colon has to be followed by the pattern -for the anchor, a pipe symbol, the pattern for the command line, an equal -sign, and the pattern for the word. Patterns anchored on the left side match -only if the anchor-pattern matches directly before the line pattern and if -the string in the word before the word pattern matches the string before -the line pattern in the line string. -) -item(tt(r) and tt(R))( -Like tt(l) and tt(L) with the difference that the line and word patterns -are anchored on the right side. Also, here the pattern for the anchor has -to come after the pattern for the line, again separated by a pipe symbol. +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 pattern is either an empty string or consists of a sequence of -character (possibly quoted), question marks, character classes, and -correspondence classes. Normal characters match only themselves, question -marks match any character, and character classes are formed as for -globbing and match the same characters as there. -Correspondence classes are formed like character classes with two -differences: they are delimited by a pair of braces and negated -classes are not allowed (i.e. the characters tt(!) and tt(^) have no -special meaning directly after the opening brace). - -Correspondence classes are used to conveniently describe that several -characters on the line match several other characters in the word. For -example, if you want to define the any lowercase letter on the line -matches the corresponding uppercase letter in the word all you need to -write down is: `tt(m:{a-z}={A-Z})'. More than one correspondence class -may be given on either side of the equal sign, in this case the first -class on the left says which character matches for the first class on -the right, the second class on either side work together, 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 always behave like normal character classes. - -The word pattern may also be a single star (tt(*)). This means that -the line pattern matches any number of characters in the word. In this -case the pattern has to be anchored (on any side) and the line pattern -matches all characters in the word up to a character sequence that -matches the anchor. - -For anchors the empty string as a pattern has a special meaning. Such -empty anchors match only the beginning (in the case of an left side -anchor) or end (for right side anchors) of the command line string or -word. - -The distinction between the lowercase and the uppercase forms of the -specification characters is used to define which matched substring -should be put in the match and the generated command line. The -lowercase forms use the substring from the word, so this should be -used if the exact words produced by the completion code need to be -used. The uppercase forms use the substring from the command line and -should be used if the typed string need to be retained. +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. Examples: -startitem() -The option tt(-o) produces option names in all-lowercase form, without +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 buitlins tt(setopt) and tt(unsetopt) understand opotion -names with uppercase letters, underscores, and the optional tt(no). -So we want to be able to say, that in this case an prefix tt(no) and -any underscore may be ignored when trying to match the produced words, -and that uppercase letters on the line match the corresponding -lowercase letters in the words. This can be done with: - +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: indent( -tt(compctl -M 'L:|[nN][oO]= M:_= M:{A-Z}={a-z}' -o setopt unsetopt) +nofill(tt(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 -(note the empty anchor before the pipe symbol) of the string on the -line matches the the empty string in the produced words, i.e. it need -not be there. The second part says that an underscore anywhere on the -line need not be present in the word, and the third part uses -correspondence classes as in the example above to say that any +(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 the special -wrinting on the command line (and especially the option tt(no)) will -not be erased. - -As a second example we will make completion case insensitive. For this -we use the form of tt(compctl) that defines matching specification that -are to be used everywhere, i.e. a tt(compctl) with tt(-M) as the only -option given. - -The pattern needed was already explained above, this gives us: - +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: indent( tt(compctl -M 'm:{a-z}={A-Z}') ) - -This makes lowercase letters match their uppercase counterparts. If we -want to make uppercase letters match the lowercase forms, we would -have to use: - +This makes lowercase letters match their uppercase counterparts. +To make uppercase letters match the lowercase forms as well: indent( -tt(compctl -M 'm:{a-z}={A-Z} m:{A-Z}={a-z}') +tt(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. you consider the -word to consist of multiple parts (separated by the dot in the -example) and each part should be completed separately. Defining such -forms of matching is simple, for example if we want to separately -complete word parts separated by dots, commas, underscores, and -hyphens, we can do this by saying: - +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: +indent( +nofill(tt(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 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 indent( tt(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 first specification says that an empty string on the line before -one of our special characters matches any number of characters in the -word which has the effect we wanted. The second specification is -needed to make this work when the cursor is in the middle of the word -and the option tt(COMPLETE_IN_WORD) is set. In this case the -completion code would normally try to match word that end with the -string that is already on the command line, but in our example we -would like the code to match words even if they contain extra -characters after the string on the line. Hence we say that the empty -string at the end of the string on the line matches any characters at -the end of the word. - -The form of tt(compctl) that defines the global matching -specifications is a bit more powerful than described until now. It -accepts not only one specification strin, but any number of them. When -completion is attempted, the code first uses the definitions from the -first string. If no words could be matched with these specifications, -it tries the whole thing again with the specifications from the second -string, and so on. This allows one to define simple and fast matches -to be used first, more powerful matchers as a second choice, and so on. - -As an example we would like to make the code match words that contain -the string on the line as a substring (anywhere, not just at the -beginning). But since this could produce more matches than we want, -this should be tried only if the matchers described above don't -produce any matches. E.g.: - +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. + +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: indent( tt(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). -If using the first specification string does not produce matches, the -second one is tried. The two descriptions it this string say that the -empty string at the beginning and end of the string on the line -matches any characters at the beginning or end of the word. -enditem() texinode(Example)()(Matching Control)(Programmable Completion) sect(Example) -nofill(tt(compctl -u -x 's[tt(PLUS())] c[-1,-f],s[-f+PLUS()]' -g '~/Mail/*(:t)' \ - - 's[-f],c[-1,-f]' -f -- mail)) - +indent( +nofill( +tt(compctl -u -x 's[tt(PLUS())] c[-1,-f],s[-f+PLUS()]' \ + -g '~/Mail/*(:t)' - 's[-f],c[-1,-f]' -f -- mail)) +) This is to be interpreted as follows: If the current command is tt(mail), then diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo index 87ef13d06..ccf245367 100644 --- a/Doc/Zsh/expn.yo +++ b/Doc/Zsh/expn.yo @@ -161,8 +161,10 @@ Print the new command but do not execute it. Only works with history expansion. ) item(tt(q))( -Quote the substituted words, escaping further substitutions. Only -works with history expansion. +Quote the substituted words, escaping further substitutions. Works +with history expansion and parameter expansion, though in the second +case it is only useful if the resulting text is to be re-evaluated +such as by tt(eval). ) item(tt(x))( Like tt(q), but break into words at each blank. @@ -477,9 +479,10 @@ item(tt(${~)var(spec)tt(}))( pindex(GLOB_SUBST) Turn on the tt(GLOB_SUBST) option for the evaluation of var(spec); if the `tt(~)' is doubled, turn it off. When this option is -set, any pattern characters resulting -from parameter expansion are eligible for filename expansion and filename -generation. +set, the string resulting from the expansion will be interpreted as a +pattern anywhere that is possible, such as in filename expansion and +filename generation and pattern-matching contexts like the right +hand side of the `tt(=)' and `tt(!=)' operators in conditions. ) enditem() @@ -523,6 +526,15 @@ Perform em(parameter expansion), em(command substitution) and em(arithmetic expansion) on the result. Such expansions can be nested but too deep recursion may have unpredictable effects. ) +item(tt(P))( +This makes the value of the parameter var(name) be taken as a +parameter name on which to work. If it is used with a tt(${)...tt(}) +type parameter expression or a tt($LPAR())...tt(RPAR()) type command +substitution in place of the parameter name this flag makes the result +of the expansion be taken as a parameter name which is then +used. E.g. if you have `tt(foo=bar)' and `tt(bar=baz)', the strings +`tt(${(P)foo})' and `tt(${(P)${foo}})' will be expanded to `tt(baz)'. +) item(tt(o))( Sort the resulting words in ascending order. ) @@ -788,7 +800,8 @@ directory as its prefix. If so, then the prefix portion is replaced with a `tt(~)' followed by the name of the directory. The shortest way of referring to the directory is used, with ties broken in favour of using a named directory, -except when the directory is tt(/) itself. +except when the directory is tt(/) itself. The variables tt($PWD) and +tt($OLDPWD) are never abbreviated in this fashion. If a word begins with an unquoted `tt(=)' and the tt(EQUALS) option is set, @@ -1088,7 +1101,7 @@ setgid files (02000) item(tt(t))( files with the sticky bit (01000) ) -item(tt(o)var(spec))( +item(tt(f)var(spec))( files with access rights matching var(spec). This var(spec) may be a octal number optionally preceded by a `tt(=)', a `tt(PLUS())', or a `tt(-)'. If none of these characters is given, the behavior is the @@ -1101,7 +1114,7 @@ octal digit anywhere in the number ensures that the corresponding bits inthe file-modes are not checked, this is only useful in combination with `tt(=)'. -If the qualifier `tt(o)' is followed by any other character anything +If the qualifier `tt(f)' is followed by any other character anything up to the next matching character (`tt([)', `tt({)', and `tt(<)' match `tt(])', `tt(})', and `tt(>)' respectively, any other character matches itself) is taken as a list of comma-separated @@ -1122,11 +1135,11 @@ are to be expected: `tt(r)' for read access, `tt(w)' for write access, `tt(s)' for the setuid and setgid bits, and `tt(t)' for the sticky bit. -Thus, `tt(*(o70?))' gives the files for which the owner has read, +Thus, `tt(*(f70?))' gives the files for which the owner has read, write, and execute permission, and for which other group members have no rights, independent of the permissions for other user. The pattern -`tt(*(o-100))' gives all files for which the owner does not have -execute permission, and `tt(*(o:gu+w,o-rx))' gives the files for which +`tt(*(f-100))' gives all files for which the owner does not have +execute permission, and `tt(*(f:gu+w,o-rx))' gives the files for which the owner and the other members of the group have at least write permission, and fo which other users don't have read or execute permission. @@ -1205,7 +1218,7 @@ item(tt(D))( sets the tt(GLOB_DOTS) option for the current pattern pindex(GLOB_DOTS, setting in pattern) ) -item(tt(O)var(c))( +item(tt(o)var(c))( specifies how the names of the files should be sorted. If var(c) is tt(n) they are sorted by name (the default), if var(c) is tt(L) they are sorted depending on the size (length) of the files, tt(l) makes @@ -1214,16 +1227,20 @@ make them be sorted by the time of the last access, modification, and inode change respectively. Note that tt(a), tt(m), and tt(c) compare the age to the current time, so the first name in the list is the one of the youngest file. Also note that the modifiers tt(^) and tt(-) are -used, so `tt(*(^-OL))' gives a list of all files sorted by file size in +used, so `tt(*(^-oL))' gives a list of all files sorted by file size in descending order working not on symbolic links but on the files they point to. ) +item(tt(O)var(c))( +like `tt(o)', but sorts in descending order; i.e. `tt(*(^oc))' is the +same as `tt(*(Oc))' and `tt(*(^Oc))' is the same as `tt(*(oc))' +) item(tt([)var(beg)[tt(,)var(end)]tt(]))( specifies which of the matched filenames should be included in the returned list. The syntax is the same as for array subscripts. var(beg) and the optional var(end) may be mathematical expressions. As in parameter subscripting they may be negative to make -them count from the last match backward. E.g.: `tt(*(^-OL[1,3]))' +them count from the last match backward. E.g.: `tt(*(-OL[1,3]))' gives a list of the names of three biggest files. ) enditem() diff --git a/Doc/Zsh/files.yo b/Doc/Zsh/files.yo index 0d775a14f..a90e2b3d5 100644 --- a/Doc/Zsh/files.yo +++ b/Doc/Zsh/files.yo @@ -20,6 +20,12 @@ commands are read from tt(/etc/zshrc) and then tt($ZDOTDIR/.zshrc). Finally, if the shell is a login shell, tt(/etc/zlogin) and tt($ZDOTDIR/.zlogin) are read. +When a login shell exits, the files tt($ZDOTDIR/.zlogout) and then +tt(/etc/zlogout) are read. This happens with either an explicit exit +via the tt(exit) or tt(logout) commands, or an implict exit by reading +end-of-file from the terminal. However, if the shell terminates due +to tt(exec)'ing another process, the logout files are not read. + If tt(ZDOTDIR) is unset, tt(HOME) is used instead. Those files listed above as being in tt(/etc) may be in another directory, depending on the installation. diff --git a/Doc/Zsh/metafaq.yo b/Doc/Zsh/metafaq.yo index a9e0bbecf..cad82ee65 100644 --- a/Doc/Zsh/metafaq.yo +++ b/Doc/Zsh/metafaq.yo @@ -91,28 +91,30 @@ cindex(mailing lists) Zsh has 3 mailing lists: startitem() -item(tt(<zsh-announce@math.gatech.edu>))( +item(tt(<zsh-announce@sunsite.auc.dk>))( Announcements about releases, major changes in the shell and the monthly posting of the Zsh FAQ. (moderated) ) -item(tt(<zsh-users@math.gatech.edu>))( +item(tt(<zsh-users@sunsite.auc.dk>))( User discussions. ) -item(tt(<zsh-workers@math.gatech.edu>))( +item(tt(<zsh-workers@sunsite.auc.dk>))( Hacking, development, bug reports and patches. ) enditem() -To subscribe, send mail with the SUBJECT `tt(subscribe) var(<e-mail-address>)' +To subscribe or unsubscribe, send mail to the associated administrative address for the mailing list. startlist() -list(tt(<zsh-announce-request@math.gatech.edu>)) -list(tt(<zsh-users-request@math.gatech.edu>)) -list(tt(<zsh-workers-request@math.gatech.edu>)) -endlist() +list(tt(<zsh-announce-subscribe@sunsite.auc.dk>)) +list(tt(<zsh-users-subscribe@sunsite.auc.dk>)) +list(tt(<zsh-workers-subscribe@sunsite.auc.dk>)) -Unsubscribing is done similarly. +list(tt(<zsh-announce-unsubscribe@sunsite.auc.dk>)) +list(tt(<zsh-users-unsubscribe@sunsite.auc.dk>)) +list(tt(<zsh-workers-unsubscribe@sunsite.auc.dk>)) +endlist() YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED. All submissions to bf(zsh-announce) are automatically forwarded to @@ -121,7 +123,7 @@ forwarded to bf(zsh-workers). If you have problems subscribing/unsubscribing to any of the mailing lists, send mail to tt(<listmaster@zsh.org>). The mailing lists are -maintained by Richard Coleman tt(<coleman@zsh.org>). +maintained by Karsten Thygesen tt(<karthy@kom.auc.dk>). The mailing lists are archived; the archives can be accessed via the administrative addresses listed above. There is also a hypertext diff --git a/Doc/Zsh/mod_zle.yo b/Doc/Zsh/mod_zle.yo index 48dd1935f..86d145636 100644 --- a/Doc/Zsh/mod_zle.yo +++ b/Doc/Zsh/mod_zle.yo @@ -131,12 +131,20 @@ written as `tt(^?)'. Note that `tt(\M^?)' and `tt(^\M?)' are not the same. findex(vared) cindex(parameters, editing) cindex(editing parameters) -item(tt(vared) [ tt(-ch) ] [ tt(-p) var(prompt) ] [ tt(-r) var(rprompt) ] var(name))( +item(tt(vared) [ tt(-Aach) ] [ tt(-p) var(prompt) ] [ tt(-r) var(rprompt) ] var(name))( The value of the parameter var(name) is loaded into the edit buffer, and the line editor is invoked. When the editor exits, var(name) is set to the string value returned by the editor. -If the tt(-c) flag is given, the parameter is created if it doesn't -already exist. +When the tt(-c) flag is given, the parameter is created if it doesn't +already exist. The tt(-a) flag may be given with tt(-c) to create +an array parameter, or the tt(-A) flag to create an associative array. +If the type of an existing parameter does not match the type to be +created, the parameter is unset and recreated. + +Individual elements of existing array or associative array parameters +may be edited by using subscript syntax on var(name). New elements are +created automatically, even without tt(-c). + If the tt(-p) flag is given, the following string will be taken as the prompt to display at the left. If the tt(-r) flag is given, the following string gives the prompt to display at the right. If the diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo index 6b6093623..b9455f578 100644 --- a/Doc/Zsh/options.yo +++ b/Doc/Zsh/options.yo @@ -150,6 +150,17 @@ In a glob pattern, treat a trailing set of parentheses as a qualifier list, if it contains no `tt(|)', `tt(LPAR())' or (if special) `tt(~)' characters. See noderef(Filename Generation). ) +pindex(BASH_AUTO_LIST) +cindex(completion, listing choices, bash style) +item(tt(BASH_AUTO_LIST))( +On an ambiguous completion, automatically list choices when the +completion function is called twice in succession. This takes +precedence over tt(AUTO_LIST). The setting of tt(LIST_AMBIGUOUS) is +respected. If tt(AUTO_MENU) is set, the menu behaviour will then start +with the third press. Note that this will not work with +tt(MENU_COMPLETE), since repeated completion calls immediately cycle +through the list in that case. +) pindex(BEEP) cindex(beep, enabling) cindex(enabling the beep) @@ -331,11 +342,12 @@ will be an array or a scalar. pindex(GLOB_COMPLETE) item(tt(GLOB_COMPLETE))( When the current word has a glob pattern, do not insert all the words -resulting from the expansion but cycle through them like -tt(MENU_COMPLETE). If no matches are found, a `tt(*)' is added to the end of the -word or inserted at the cursor if tt(COMPLETE_IN_WORD) is set, and expansion -is attempted again. Using patterns works not only for files but for all -completions, such as options, user names, etc. +resulting from the expansion but generate matches as for completion and +cycle through them like tt(MENU_COMPLETE). If no matches are found, a +`tt(*)' is added to the end of the word or inserted at the cursor if +tt(COMPLETE_IN_WORD) is set, and completion is attempted again using +pattern matching. Since this doesn't use globbing, it works not only for +files but for all completions, such as options, user names, etc. ) pindex(GLOB_DOTS) cindex(globbing, of . files) @@ -488,9 +500,12 @@ pindex(LIST_AMBIGUOUS) cindex(ambiguous completion) cindex(completion, ambiguous) item(tt(LIST_AMBIGUOUS))( -If this option is set, completions are shown only if the completions -don't have a unambiguous prefix or suffix that could be inserted in -the command line. +This option works when tt(AUTO_LIST) or tt(BASH_AUTO_LIST) is also +set. If there is an unambiguous prefix to insert on the command line, +that is done without a completion list being displayed; in other +words, auto-listing behaviour only takes place when nothing would be +inserted. In the case of tt(BASH_AUTO_LIST), this means that the list +will be delayed to the third call of the function. ) pindex(LIST_BEEP) cindex(beep, ambiguous completion) diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo index 29899b379..dc7f0b75d 100644 --- a/Doc/Zsh/params.yo +++ b/Doc/Zsh/params.yo @@ -40,7 +40,8 @@ Shell function executions delimit scopes for shell parameters. (Parameters are dynamically scoped.) The tt(typeset) builtin, and its alternative forms tt(declare), tt(integer), tt(local) and tt(readonly) (but not tt(export)), can be used to declare a parameter as being local -to the innermost scope. +to the innermost scope. Note that em(special) parameters cannot be made +local. When a parameter is read or assigned to, the innermost existing parameter of that name is used. (That is, the @@ -49,9 +50,8 @@ to a non-existent parameter, or declaring a new parameter with tt(export), causes it to be created in the em(outer)most scope. Local parameters disappear when their scope ends. -tt(unset) can be used to delete a parameter while it is still in scope; this -will reveal the next outer parameter of the same name. However, em(special) -parameters are still special when unset. +tt(unset) can be used to delete a parameter while it is still in scope; +any outer parameter of the same name remains hidden. texinode(Array Parameters)(Positional Parameters)(Local Parameters)(Parameters) sect(Array Parameters) The value of an array parameter may be assigned by writing: |