diff options
Diffstat (limited to 'Doc/Zsh')
| -rw-r--r-- | Doc/Zsh/builtins.yo | 117 | ||||
| -rw-r--r-- | Doc/Zsh/compsys.yo | 302 | ||||
| -rw-r--r-- | Doc/Zsh/compwid.yo | 7 | ||||
| -rw-r--r-- | Doc/Zsh/cond.yo | 9 | ||||
| -rw-r--r-- | Doc/Zsh/contrib.yo | 307 | ||||
| -rw-r--r-- | Doc/Zsh/exec.yo | 15 | ||||
| -rw-r--r-- | Doc/Zsh/expn.yo | 93 | ||||
| -rw-r--r-- | Doc/Zsh/grammar.yo | 3 | ||||
| -rw-r--r-- | Doc/Zsh/jobs.yo | 4 | ||||
| -rw-r--r-- | Doc/Zsh/mod_complist.yo | 5 | ||||
| -rw-r--r-- | Doc/Zsh/mod_curses.yo | 18 | ||||
| -rw-r--r-- | Doc/Zsh/mod_db_gdbm.yo | 11 | ||||
| -rw-r--r-- | Doc/Zsh/mod_parameter.yo | 29 | ||||
| -rw-r--r-- | Doc/Zsh/mod_sched.yo | 5 | ||||
| -rw-r--r-- | Doc/Zsh/mod_zleparameter.yo | 16 | ||||
| -rw-r--r-- | Doc/Zsh/options.yo | 76 | ||||
| -rw-r--r-- | Doc/Zsh/params.yo | 52 | ||||
| -rw-r--r-- | Doc/Zsh/restricted.yo | 10 | ||||
| -rw-r--r-- | Doc/Zsh/roadmap.yo | 3 | ||||
| -rw-r--r-- | Doc/Zsh/zle.yo | 91 |
20 files changed, 961 insertions, 212 deletions
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index 1ca1f24a8..81687c7a7 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -147,20 +147,42 @@ ifnzman(noderef(Aliasing)). findex(autoload) cindex(functions, autoloading) cindex(autoloading functions) -item(tt(autoload) [ {tt(PLUS())|tt(-)}tt(TUXkmtz) ] [ tt(-w) ] [ var(name) ... ])( +item(tt(autoload) [ {tt(PLUS())|tt(-)}tt(RTUXdkmrtWz) ] [ tt(-w) ] [ var(name) ... ])( vindex(fpath, searching) -Equivalent to tt(functions -u), with the exception of tt(-X)/tt(+X) and -tt(-w). See the section `Autoloading Functions' in ifzman(zmanref(zshmisc))\ +See the section `Autoloading Functions' in ifzman(zmanref(zshmisc))\ ifnzman(noderef(Functions)) for full details. The tt(fpath) parameter will be searched to find the function definition when the function is first referenced. -The flag tt(-X) may be used only inside a shell function, and may not be -followed by a var(name). It causes the calling function to be marked for -autoloading and then immediately loaded and executed, with the current -array of positional parameters as arguments. This replaces the previous -definition of the function. If no function definition is found, an error -is printed and the function remains undefined and marked for autoloading. +If var(name) consists of an absolute path, the function is defined to +load from the file given (searching as usual for dump files in the given +location). The name of the function is the basename (non-directory +part) of the file. It is normally an error if the function is not found +in the given location; however, if the option tt(-d) is given, searching +for the function defaults to tt($fpath). If a function is loaded by +absolute path, any functions loaded from it that are marked for +tt(autoload) without an absolute path have the load path of the parent +function temporarily prepended to tt($fpath). + +If the option tt(-r) or tt(-R) is given, the function is searched for +immediately and the location is recorded internally for use when the +function is executed; a relative path is expanded using the value of +tt($PWD). This protects against a change to tt($fpath) after the call +to tt(autoload). With tt(-r), if the function is not found, it is +silently left unresolved until execution; with tt(-R), an error message +is printed and command processing aborted immediately the search fails, +i.e. at the tt(autoload) command rather than at function execution.. + +The flag tt(-X) may be used only inside a shell function. It causes the +calling function to be marked for autoloading and then immediately +loaded and executed, with the current array of positional parameters as +arguments. This replaces the previous definition of the function. If +no function definition is found, an error is printed and the function +remains undefined and marked for autoloading. If an argument is given, +it is used as a directory (i.e. it does not include the name of the +function) in which the function is to be found; this may be combined +with the tt(-d) option to allow the function search to default to tt($fpath) +if it is not in the given location. The flag tt(+X) attempts to load each var(name) as an autoloaded function, but does em(not) execute it. The exit status is zero (success) if the @@ -176,6 +198,13 @@ If the tt(-m) flag is also given each var(name) is treated as a pattern and all functions already marked for autoload that match the pattern are loaded. +With the tt(-t) flag, turn on execution tracing; with tt(-T), turn on +execution tracing only for the current function, turning it off on entry +to any called functions that do not also have tracing enabled. + +With the tt(-U) flag, alias expansion is suppressed when the function is +loaded. + With the tt(-w) flag, the var(name)s are taken as names of files compiled with the tt(zcompile) builtin, and all functions defined in them are marked for autoloading. @@ -193,6 +222,10 @@ example(emulate zsh -c 'autoload -Uz var(func)') arranges that when var(func) is loaded the shell is in native tt(zsh) emulation, and this emulation is also applied when var(func) is run. + +Some of the functions of tt(autoload) are also provided by tt(functions +-u) or tt(functions -U), but tt(autoload) is a more comprehensive +interface. ) findex(bg) cindex(jobs, backgrounding) @@ -453,7 +486,7 @@ tt(echo) recognizes the following escape sequences: startsitem() sitem(tt(\a))(bell character) sitem(tt(\b))(backspace) -sitem(tt(\c))(suppress final newline) +sitem(tt(\c))(suppress subsequent characters and final newline) sitem(tt(\e))(escape) sitem(tt(\f))(form feed) sitem(tt(\n))(linefeed (newline)) @@ -570,7 +603,7 @@ with emulations to be set to their values in tt(sh). tt(fno) then calls tt(fni); because tt(fni) is also marked for sticky tt(sh) emulation, no option changes take place on entry to or exit from it. Hence the option tt(cshnullglob), turned off by tt(sh) emulation, will -be turned on within tt(fni) and remain on on return to tt(fno). On exit +be turned on within tt(fni) and remain on return to tt(fno). On exit from tt(fno), the emulation mode and all options will be restored to the state they were in before entry to the temporary emulation. @@ -656,7 +689,7 @@ An EOF condition will also cause the shell to exit, unless the tt(IGNORE_EOF) option is set. See notes at the end of -ifzman(the section JOBS in in zmanref(zshmisc))\ +ifzman(the section JOBS in zmanref(zshmisc))\ ifnzman(noderef(Jobs & Signals)) for some possibly unexpected interactions of the tt(exit) command with jobs. ) @@ -697,7 +730,7 @@ specifies the most recent event beginning with the given string. All substitutions var(old)tt(=)var(new), if any, are then performed on the text of the events. -In addition to the the number range, +In addition to the number range, startsitem() sitem(tt(-I))(restricts to only internal events (not from tt($HISTFILE))) sitem(tt(-L))(restricts to only local events (not from other shells, see @@ -806,18 +839,24 @@ Equivalent to tt(typeset -E), except that options irrelevant to floating point numbers are not permitted. ) findex(functions) -xitem(tt(functions) [ {tt(PLUS())|tt(-)}tt(UkmtTuz) ] [ tt(-x) var(num) ] [ var(name) ... ]) -xitem(tt(functions -M) var(mathfn) [ var(min) [ var(max) [ var(shellfn) ] ] ]) +xitem(tt(functions) [ {tt(PLUS())|tt(-)}tt(UkmtTuWz) ] [ tt(-x) var(num) ] [ var(name) ... ]) +xitem(tt(functions -M) [tt(-s)] var(mathfn) [ var(min) [ var(max) [ var(shellfn) ] ] ]) xitem(tt(functions -M) [ tt(-m) var(pattern) ... ]) item(tt(functions +M) [ tt(-m) ] var(mathfn) ... )( -Equivalent to tt(typeset -f), with the exception of the tt(-x) and -tt(-M) options. +Equivalent to tt(typeset -f), with the exception of the tt(-x), +tt(-M) and tt(-W) options. For tt(functions -u) and tt(functions -U), +see tt(autoload), which provides additional options. The tt(-x) option indicates that any functions output will have each leading tab for indentation, added by the shell to show syntactic structure, expanded to the given number var(num) of spaces. var(num) can also be 0 to suppress all indentation. +The tt(-W) option turns on the option tt(WARN_NESTED_VAR) for the named +function or functions only. The option is turned off at the start of +nested functions (apart from anonoymous functions) unless the called +function also has the tt(-W) attribute. + Use of the tt(-M) option may not be combined with any of the options handled by tt(typeset -f). @@ -843,6 +882,13 @@ The result of the last arithmetical expression evaluated inside the shell function (even if it is a form that normally only returns a status) gives the result of the mathematical function. +If the additional option tt(-s) is given to tt(functions -M), the +argument to the function is a single string: anything between the +opening and matching closing parenthesis is passed to the function as a +single argument, even if it includes commas or white space. The minimum +and maximum argument specifiers must therefore be 1 if given. An empty +argument list is passed as a zero-length string. + tt(functions -M) with no arguments lists all such user-defined functions in the same form as a definition. With the additional option tt(-m) and a list of arguments, all functions whose var(mathfn) matches one of @@ -850,15 +896,22 @@ the pattern arguments are listed. tt(function +M) removes the list of mathematical functions; with the additional option tt(-m) the arguments are treated as patterns and -all functions whose tt(mathfn) matches the pattern are removed. Note +all functions whose var(mathfn) matches the pattern are removed. Note that the shell function implementing the behaviour is not removed -(regardless of whether its name coincides with tt(mathfn)). +(regardless of whether its name coincides with var(mathfn)). For example, the following prints the cube of 3: example(zmath_cube+LPAR()RPAR() { (( $1 * $1 * $1 )) } functions -M cube 1 1 zmath_cube print $(( cube+LPAR()3+RPAR() ))) + +The following string function takes a single argument, including +the commas, so prints 11: + +example(stringfn+LPAR()RPAR() { (( $#1 )) } +functions -Ms stringfn +print $(( stringfn+LPAR()foo,bar,rod+RPAR() ))) ) module(getcap)(zsh/cap) findex(getln) @@ -1199,6 +1252,9 @@ Perform prompt expansion (see ifzman(EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\ ifnzman(noderef(Prompt Expansion))\ ). +In combination with `tt(-f)', +prompt escape sequences are parsed only within interpolated arguments, +not within the format string. ) item(tt(-r))( Ignore the escape conventions of tt(echo). @@ -1289,7 +1345,9 @@ required by the format than have been specified, the behaviour is as if zero or an empty string had been specified as the argument. The tt(-v) option causes the output to be stored as the value of the -parameter var(name), instead of printed. +parameter var(name), instead of printed. If var(name) is an array and +the format string is reused when consuming arguments then one +array element will be used for each use of the format string. ) findex(pushd) pindex(PUSHD_TO_HOME, use of) @@ -1918,11 +1976,6 @@ If the tt(-p) option is given, parameters and values are printed in the form of a typeset command with an assignment, regardless of other flags and options. Note that the tt(-H) flag on parameters is respected; no value will be shown for these parameters. - -As the intention of this option is to produce output that can restore -the current state, readonly specials (whose values cannot be -changed) are not shown and assignments to arrays are shown before -the tt(typeset) rendering the array readonly. ) item(tt(-T) [ var(scalar)[tt(=)var(value)] var(array)[tt(=LPAR())var(value) ...tt(RPAR())] [ var(sep) ] ])( This flag has a different meaning when used with tt(-f); see below. @@ -2019,23 +2072,27 @@ place in the output. ) item(tt(-a))( The names refer to array parameters. An array parameter may be -created this way, but it may not be assigned to in the tt(typeset) -statement. When displaying, both normal and associative arrays are -shown. +created this way, but it may be assigned to in the tt(typeset) +statement only if the reserved word form of tt(typeset) is enabled +(as it is by default). When displaying, both normal and associative +arrays are shown. ) item(tt(-f))( The names refer to functions rather than parameters. No assignments can be made, and the only other valid flags are tt(-t), tt(-T), tt(-k), tt(-u), tt(-U) and tt(-z). The flag tt(-t) turns on execution tracing for this function; the flag tt(-T) does the same, but turns off tracing -on any function called from the present one, unless that function also +for any named (not anonymous) function called from the present one, +unless that function also has the tt(-t) or tt(-T) flag. The tt(-u) and tt(-U) flags cause the function to be marked for autoloading; tt(-U) also causes alias expansion to be suppressed when the function is loaded. See the description of the `tt(autoload)' builtin for details. Note that the builtin tt(functions) provides the same basic capabilities -as tt(typeset -f) but gives access to a few extra options. +as tt(typeset -f) but gives access to a few extra options; tt(autoload) +gives further additional options for the case tt(typeset -fu) and +tt(typeset -fU). ) item(tt(-h))( Hide: only useful for special parameters (those marked `<S>' in the table in diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index d478e818e..47b07e85e 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -91,6 +91,7 @@ menu(Control Functions) menu(Bindable Commands) menu(Completion Functions) menu(Completion Directories) +menu(Completion System Variables) endmenu() texinode(Initialization)(Completion System Configuration)()(Completion System) @@ -825,6 +826,10 @@ kindex(domains, completion tag) item(tt(domains))( for network domains ) +kindex(email-*, completion tag) +item(tt(email-)var(plugin))( +for email addresses from the `tt(_email-)var(plugin)' backend of tt(_email_addresses) +) kindex(expansions, completion tag) item(tt(expansions))( used by the tt(_expand) completer for individual words (as opposed to @@ -1110,14 +1115,14 @@ tt(default) tag. The most notable styles of this type are tt(menu), tt(list-colors) and styles controlling completion listing such as tt(list-packed) and tt(last-prompt). When tested for the tt(default) tag, only the var(function) field of the context will be set so that -a style using the default tag will normally be defined along the lines of: +a style using the tt(default) tag will normally be defined along the lines of: example(zstyle ':completion:*:default' menu ...) startitem() kindex(accept-exact, completion style) item(tt(accept-exact))( -This is tested for the default tag in addition to the tags valid for +This is tested for the tt(default) tag in addition to the tags valid for the current context. If it is set to `true' and any of the trial matches is the same as the string on the command line, this match will immediately be accepted (even if it would otherwise be considered @@ -1153,6 +1158,12 @@ directory is accepted without any attempt to complete it further. Hence, in the given example, the path tt(/usr/bin/) is accepted immediately and completion tried in that directory. +This style is also useful when completing after directories that +magically appear when referenced, such as ZFS tt(.zfs) directories +or NetApp tt(.snapshot) directories. When the style is set the +shell does not check for the existence of the directory within the +parent directory. + If you wish to inhibit this behaviour entirely, set the tt(path-completion) style (see below) to `false'. ) @@ -1423,9 +1434,10 @@ or colons in var(dir) should be quoted with a backslash to be treated literally. This can be useful on systems that support special file systems whose -top-level pathnames can not be listed or generated with glob patterns. -It can also be used for directories for which one does not have read -permission. +top-level pathnames can not be listed or generated with glob patterns +(but see tt(accept-exact-dirs) for a more general way of dealing +with this problem). It can also be used for directories for which one +does not have read permission. The pattern form can be used to add a certain `magic' entry to all directories on a particular file system. @@ -1842,6 +1854,15 @@ In the case of the tt(_match) completer, the style may also be set to the string `tt(pattern)'. Then the pattern on the line is left unchanged if it does not match unambiguously. ) +kindex(gain-privileges, completion style) +item(tt(gain-privileges))( +If set to tt(true), this style enables the use of commands like tt(sudo) +or tt(doas) to gain extra privileges when retrieving information for +completion. This is only done when a command such as tt(sudo) appears on +the command-line. To force the use of, e.g. tt(sudo) or to override any +prefix that might be added due to tt(gain-privileges), the tt(command) +style can be used with a value that begins with a hyphen. +) kindex(keep-prefix, completion style) item(tt(keep-prefix))( This style is used by the tt(_expand) completer. If it is `true', the @@ -2023,8 +2044,9 @@ only be performed with the `tt(*)' inserted. kindex(matcher, completion style) item(tt(matcher))( This style is tested separately for each tag valid in the current -context. Its value is tried before any match specifications given by the -tt(matcher-list) style. It should be in the form described in +context. Its value is placed before any match specifications given by the +tt(matcher-list) style so can override them via the use of an tt(x:) +specification. The value should be in the form described in ifzman(the section `Completion Matching Control' in zmanref(zshcompwid))\ ifnzman(noderef(Completion Matching Control))\ . For examples of this, see the description of the tt(tag-order) style. @@ -2181,7 +2203,7 @@ matches does not fit on the screen by using the value `tt(select=long)'. To start menu selection even if the current widget only performs listing, use the value `tt(select=long-list)'. -To turn on menu completion or menu selection when a there are a certain +To turn on menu completion or menu selection when there are a certain number of matches em(or) the list of matches does not fit on the screen, both of `tt(yes=)' and `tt(select=)' may be given twice, once with a number and once with `tt(long)' or `tt(long-list)'. @@ -2977,6 +2999,21 @@ widgets to find out if the command line hasn't changed since the last time completion was tried. Only then are the tt(_ignored), tt(_correct) and tt(_approximate) completers called. ) +findex(_canonical_paths) +item(tt(_canonical_paths) [ tt(-A) var(var) ] [ tt(-N) ] [ tt(-MJV12nfX) ] var(tag) var(descr) [ var(paths) ... ])( +This completion function completes all paths given to it, and also tries to +offer completions which point to the same file as one of the paths given +(relative path when an absolute path is given, and vice versa; when tt(..)'s +are present in the word to be completed; and some paths got from symlinks). + +tt(-A), if specified, takes the paths from the array variable specified. Paths can +also be specified on the command line as shown above. tt(-N), if specified, +prevents canonicalizing the paths given before using them for completion, in +case they are already so. The options tt(-M), tt(-J), tt(-V), tt(-1), tt(-2), +tt(-n), tt(-F), tt(-X) are passed to tt(compadd). + +See tt(_description) for a description of var(tag) and var(descr). +) findex(_complete) item(tt(_complete))( This completer generates all possible completions in a context-sensitive @@ -3093,6 +3130,15 @@ completion continues to allow other completers such as tt(_expand) to expand the pattern. The standard tt(add-space) and tt(prefix-hidden) styles are observed. ) +findex(_external_pwds) +item(tt(_external_pwds))( +Completes current directories of other zsh processes belonging to the +current user. + +This is intended to be used via tt(_generic), bound to a custom key +combination. Note that pattern matching is enabled so matching is +performed similar to how it works with the tt(_match) completer. +) findex(_history) item(tt(_history))( Complete words from the shell's command history. This completer @@ -3222,6 +3268,7 @@ for the current context; remember that the context for completers is less specific than that for contextual completion as the full context has not yet been determined. Elements of the array may have one of the following forms: + startsitem() sitem(tt($)var(hash))( var(hash) is the name of an associative array. Note this is not a full @@ -3442,7 +3489,7 @@ emacs and vi respectively. ) enditem() -texinode(Completion Functions)(Completion Directories)(Bindable Commands)(Completion System) +texinode(Completion Functions)(Completion System Variables)(Bindable Commands)(Completion System) sect(Utility Functions) cindex(completion system, utility functions) @@ -3455,12 +3502,6 @@ generating matches all follow the convention of returning status zero if they generated completions and non-zero if no matching completions could be added. -Two more features are offered by the tt(_main_complete) function. The -arrays tt(compprefuncs) and tt(comppostfuncs) may contain -names of functions that are to be called immediately before or after -completion has been tried. A function will only be called once unless -it explicitly reinserts itself into the array. - startitem() findex(_absolute_command_paths) item(tt(_absolute_command_paths))( @@ -3539,13 +3580,11 @@ This function can be used to give a complete specification for completion for a command whose arguments follow standard UNIX option and argument conventions. -em(Options overview) +em(Options Overview) Options to tt(_arguments) itself must be in separate words, i.e. tt(-s -w), not tt(-sw). The options are followed by var(spec)s that describe options and -arguments of the analyzed command. var(spec)s that describe option flags must -precede var(spec)s that describe non-option ("positional" or "normal") -arguments of the analyzed line. To avoid ambiguity, all +arguments of the analyzed command. To avoid ambiguity, all options to tt(_arguments) itself may be separated from the var(spec) forms by a single colon. @@ -3590,8 +3629,9 @@ even if one or more of the options take arguments. For example, if tt(-x) takes an argument, with no tt(-s), `tt(-xy)' is considered as a single (unhandled) option; with tt(-s), tt(-xy) is an option with the argument `tt(y)'; with both tt(-s) -and tt(-w), tt(-xy) may be the option tt(-x) and the option tt(-y) with -arguments still to come. +and tt(-w), tt(-xy) is the option tt(-x) and the option tt(-y) with +arguments to tt(-x) (and to tt(-y), if it takes arguments) still to come +in subsequent words. ) item(tt(-W))( This option takes tt(-w) a stage further: it is possible to @@ -3816,7 +3856,7 @@ form below, the var(action) will be executed by calling the tt(_all_labels) function to process all tag labels. No special handling of tags is needed unless a function call introduces a new one. -The functions called to execute var(action)s will be called with the the +The functions called to execute var(action)s will be called with the elements of the array named by the `tt(-O) var(name)' option as arguments. This can be used, for example, to pass the same set of options for the tt(compadd) builtin to all var(action)s. @@ -3931,8 +3971,8 @@ command line after the command name excluding all options and their arguments. Options are stored in the associative array `tt(opt_args)' with option names as keys and their arguments as the values. For options that have more than one argument these are -given as one string, separated by colons. All colons in the original -arguments are preceded with backslashes. +given as one string, separated by colons. All colons and backslashes +in the original arguments are preceded with backslashes. The parameter `tt(context)' is set when returning to the calling function to perform an action of the form `tt(->)var(string)'. It is set to an @@ -3962,18 +4002,48 @@ example(local curcontext="$curcontext") This is useful where it is not possible for multiple states to be valid together. -em(Specifying multiple sets of options) +em(Grouping Options) -It is possible to specify multiple sets of options and -arguments with the sets separated by single hyphens. The specifications -before the first hyphen (if any) are shared by all the remaining sets. -The first word in every other set provides a name for the -set which may appear in exclusion lists in specifications, -either alone or before one of the possible values described above. -In the second case a `tt(-)' should appear between this name and the -remainder. +Options can be grouped to simplify exclusion lists. A group is +introduced with `tt(PLUS())' followed by a name for the group in the +subsequent word. Whole groups can then be referenced in an exclusion +list or a group name can be used to disambiguate between two forms of +the same option. For example: -For example: +example(_arguments \ + '(group2--x)-a' \ + PLUS() group1 \ + -m \ + '(group2)-n' \ + PLUS() group2 \ + -x -y) + +If the name of a group is specified in the form +`tt(LPAR())var(name)tt(RPAR())' then only one value from that group +will ever be completed; more formally, all specifications are mutually +exclusive to all other specifications in that group. This is useful for +defining options that are aliases for each other. For example: + +example(_arguments \ + -a -b \ + PLUS() '(operation)' \ + {-c,--compress}'[compress]' \ + {-d,--decompress}'[decompress]' \ + {-l,--list}'[list]') + +If an option in a group appears on the command line, it is stored in the +associative array `tt(opt_args)' with 'var(group)tt(-)var(option)' +as a key. In the example above, a key `tt(operation--c)' is used if the option +`tt(-c)' is present on the command line. + +em(Specifying Multiple Sets of Arguments) + +It is possible to specify multiple sets of options and arguments with +the sets separated by single hyphens. This differs from groups in that +sets are considered to be mutually exclusive of each other. + +Specifications before the first set and from any group are common to +all sets. For example: example(_arguments \ -a \ @@ -3989,28 +4059,11 @@ possible completions. When it contains `tt(-d)' or an argument, the option `tt(-c)' will not be considered. However, after `tt(-a)' both sets will still be considered valid. -If an option in a set appears on the command line, it is stored in the -associative array `tt(opt_args)' with 'var(set)tt(-)var(option)' -as a key. In the example above, a key `tt(set1--c)' is used if the option -`tt(-c)' is on the command line. - -If the name given for one of the mutually exclusive sets is of the form -`tt(LPAR())var(name)tt(RPAR())' then only one value from each set will ever -be completed; more formally, all specifications are mutually -exclusive to all other specifications in the same set. This is -useful for defining multiple sets of options which are mutually -exclusive and in which the options are aliases for each other. For -example: - -example(_arguments \ - -a -b \ - - '(compress)' \ - {-c,--compress}'[compress]' \ - - '(uncompress)' \ - {-d,--decompress}'[decompress]') +As for groups, the name of a set may appear in exclusion lists, either +alone or preceding a normal option or argument specification. -As the completion code has to parse the command line separately for each -set this form of argument is slow and should only be used when necessary. +The completion code has to parse the command line separately for each +set. This can be slow so sets should only be used when necessary. A useful alternative is often an option specification with rest-arguments (as in `tt(-foo:*:...)'); here the option tt(-foo) swallows up all remaining arguments as described by the var(optarg) definitions. @@ -4156,7 +4209,7 @@ The return status of tt(_call_function) itself is zero if the function var(name) exists and was called and non-zero otherwise. ) findex(_call_program) -item(tt(_call_program) var(tag) var(string) ...)( +item(tt(_call_program) [ tt(-p) ] var(tag) var(string) ...)( This function provides a mechanism for the user to override the use of an external command. It looks up the tt(command) style with the supplied var(tag). If the style is set, its value is used as the command to @@ -4164,6 +4217,15 @@ execute. The var(string)s from the call to tt(_call_program), or from the style if set, are concatenated with spaces between them and the resulting string is evaluated. The return status is the return status of the command called. + +If the option `tt(-p)' is supplied it indicates that the command +output is influenced by the permissions it is run with. If the +tt(gain-privileges) style is set to true, tt(_call_program) will make +use of commands such as tt(sudo), if present on the command-line, to +match the permissions to whatever the final command is likely to run +under. When looking up the tt(gain-privileges) and tt(command) styles, +the command component of the zstyle context will end with a slash +(`tt(/)') followed by the command that would be used to gain privileges. ) findex(_combination) item(tt(_combination) [ tt(-s) var(pattern) ] var(tag) var(style) var(spec) ... var(field) var(opts) ...)( @@ -4216,6 +4278,16 @@ This function completes words that are valid at command position: names of aliases, builtins, hashed commands, functions, and so on. With the tt(-e) flag, only hashed commands are completed. The tt(-) flag is ignored. ) +findex(_completers) +item(tt(_completers) [ tt(-p) ])( +This function completes names of completers. + +startitem() +item(tt(-p))( +Include the leading underscore (`tt(_)') in the matches. +) +enditem() +) findex(_describe) redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ @ @ ))ifnztexi( ))) xitem(tt(_describe )[tt(-12JVx)] [ tt(-oO) | tt(-t) var(tag) ] var(descr) var(name1) [ var(name2) ] [ var(opt) ... ]) @@ -4227,13 +4299,13 @@ different completion options var(opt)s. The var(descr) is taken as a string to display above the matches if the tt(format) style for the tt(descriptions) tag is set. This is followed by one or two names of arrays followed by options to pass to tt(compadd). The -first array contains the possible completions with their descriptions in +array var(name1) contains the possible completions with their descriptions in the form `var(completion)tt(:)var(description)'. Any literal colons in -var(completion) must be quoted with a backslash. If a second array is -given, it should have the same number of elements as the first; in this +var(completion) must be quoted with a backslash. If a var(name2) is +given, it should have the same number of elements as var(name1); in this case the corresponding elements are added as possible completions instead -of the var(completion) strings from the first array. The completion list -will retain the descriptions from the first array. Finally, a set of +of the var(completion) strings from var(name1). The completion list +will retain the descriptions from var(name1). Finally, a set of completion options can appear. If the option `tt(-o)' appears before the first argument, the matches added @@ -4317,6 +4389,21 @@ matches. Almost all calls to tt(compadd) within the completion system use a similar format; this ensures that user-specified styles are correctly passed down to the builtins which implement the internals of completion. ) +findex(_dir_list) +item(tt(_dir_list) [ tt(-s) var(sep) ] [ tt(-S) ])( +Complete a list of directory names separated by colons +(the same format as tt($PATH)). + +startitem() +item(tt(-s) var(sep))( +Use var(sep) as separator between items. +var(sep) defaults to a colon (`tt(:)'). +) +item(tt(-S))( +Add var(sep) instead of slash (`tt(/)') as an autoremoveable suffix. +) +enditem() +) findex(_dispatch) item(tt(_dispatch) var(context string) ...)( This sets the current context to var(context) and looks for completion @@ -4332,6 +4419,44 @@ tt($service) to the var(string) being tried, and sets the var(context/command) field (the fourth) of the tt($curcontext) parameter to the var(context) given as the first argument. ) +findex(_email_addresses) +item(tt(_email_addresses) [ tt(-c) ] [ tt(-n) var(plugin) ])( +Complete email addresses. Addresses are provided by plugins. + +startitem() +item(tt(-c))( +Complete bare tt(localhost@domain.tld) addresses, without a name part or +a comment. +Without this option, RFC822 `var(Firstname Lastname) tt(<)var(address)tt(>)' +strings are completed. +) +item(tt(-n) var(plugin))( +Complete aliases from var(plugin). +) +COMMENT(Intentionally leaving tt(-s) undocumented: new code should use +tt(_sequence) instead.)\ +enditem() + +The following plugins are available by default: +tt(_email-ldap) (see the tt(filter) style), +tt(_email-local) (completes var(user)tt(@)var(hostname) Unix addresses), +tt(_email-mail) (completes aliases from tt(~/.mailrc)), +tt(_email-mush), +tt(_email-mutt), +and +tt(_email-pine). + +Addresses from the tt(_email-)var(foo) plugin are added under the +tag `tt(email-)var(foo)'. + +em(Writing plugins) + +Plugins are written as separate functions with names starting with `tt(_email-)'. +They are invoked with the tt(-c) option and tt(compadd) options. +They should either do their own completion or +set the tt($reply) array to a list of `var(alias)tt(:)var(address)' elements and return tt(300). +New plugins will be picked up and run automatically. +) findex(_files) item(tt(_files))( The function tt(_files) calls tt(_path_files) with all the arguments it @@ -4416,7 +4541,7 @@ the time this function is called, tt(compstate[insert]) is cleared, so additional matches generated later are not inserted on the command line. ) findex(_multi_parts) -item(tt(_multi_parts) var(sep) var(array))( +item(tt(_multi_parts) [ tt(-i) ] var(sep) var(array))( The argument var(sep) is a separator character. The var(array) may be either the name of an array parameter or a literal array in the form @@ -4916,12 +5041,18 @@ particular tag is to be tried, the tt(_requested) function should be called (see above). If `tt(-C) var(name)' is given, var(name) is temporarily stored in the -argument field (the fifth) of the context in the tt(curcontext) parameter +var(argument) field (the fifth) of the context in the tt(curcontext) parameter during the call to tt(_tags); the field is restored on exit. This allows tt(_tags) to use a more specific context without having to change and reset the tt(curcontext) parameter (which has the same effect). ) +findex(_tilde_files) +item(tt(_tilde_files))( +Like tt(_files), but resolve leading tildes according to the rules of +filename expansion, so the suggested completions don't start with +a `tt(~)' even if the filename on the command-line does. +) findex(_values) item(tt(_values) [ tt(-O) var(name) ] [ tt(-s) var(sep) ] [ tt(-S) var(sep) ] [ tt(-wC) ] var(desc) var(spec) ...)( This is used to complete arbitrary keywords (values) and their arguments, @@ -5044,9 +5175,52 @@ Like tt(_tags) this function supports the tt(-C) option to give a different name for the argument context field. The tt(-x) option has the same meaning as for tt(_description). ) +findex(_widgets) +item(tt(_widgets) [ tt(-g) var(pattern) ])( +This function completes names of zle widgets (see +ifzman(the section `Widgets' in zmanref(zshzle))\ +ifnzman(noderef(Zle Widgets))\ +). The var(pattern), if present, is matched against values of the tt($widgets) +special parameter, documented in +ifzman(the section `The zsh/zleparameter Module' in zmanref(zshmodules))\ +ifnzman(noderef(The zsh/zleparameter Module)). +) enditem() -texinode(Completion Directories)()(Completion Functions)(Completion System) +texinode(Completion System Variables)(Completion Directories)(Completion Functions)(Completion System) +sect(Completion System Variables) +cindex(completion system, variables) + +There are some standard variables, initialised by the tt(_main_complete) +function and then used from other functions. + +The standard variables are: + +startitem() +item(tt(_comp_caller_options))( +The completion system uses tt(setopt) to set a number of options. This +allows functions to be written without concern for compatibility with +every possible combination of user options. However, sometimes completion +needs to know what the user's option preferences are. These are saved +in the tt(_comp_caller_options) associative array. Option names, spelled +in lowercase without underscores, are mapped to one or other of the +strings `tt(on)' and `tt(off)'. +) + +item(tt(_comp_priv_prefix))( +Completion functions such as tt(_sudo) can set the tt(_comp_priv_prefix) +array to a command prefix that may then be used by tt(_call_program) to +match the privileges when calling programs to generate matches. +) +enditem() + +Two more features are offered by the tt(_main_complete) function. The +arrays tt(compprefuncs) and tt(comppostfuncs) may contain +names of functions that are to be called immediately before or after +completion has been tried. A function will only be called once unless +it explicitly reinserts itself into the array. + +texinode(Completion Directories)()(Completion System Variables)(Completion System) sect(Completion Directories) cindex(completion system, directory structure) diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo index c01763316..1cc94bf95 100644 --- a/Doc/Zsh/compwid.yo +++ b/Doc/Zsh/compwid.yo @@ -913,6 +913,13 @@ line and trial completion patterns are anchored on the right side. Here an empty var(ranchor) and the tt(e) and tt(E) forms force the match to the end of the command line or trial completion string. ) +item(tt(x:))( +This form is used to mark the end of matching specifications: +subsequent specifications are ignored. In a single standalone list +of specifications this has no use but where matching specifications +are accumulated, such as from nested function calls, it can allow one +function to override another. +) enditem() Each var(lpat), var(tpat) or var(anchor) is either an empty string or diff --git a/Doc/Zsh/cond.yo b/Doc/Zsh/cond.yo index 3d369fb83..e08fc0d36 100644 --- a/Doc/Zsh/cond.yo +++ b/Doc/Zsh/cond.yo @@ -63,6 +63,9 @@ is open and associated with a terminal device. item(tt(-u) var(file))( true if var(file) exists and has its setuid bit set. ) +item(tt(-v) var(varname))( +true if shell variable var(varname) is set. +) item(tt(-w) var(file))( true if var(file) exists and is writable by current process. ) @@ -103,8 +106,10 @@ true if var(file1) and var(file2) exist and refer to the same file. xitem(var(string) tt(=) var(pattern)) item(var(string) tt(==) var(pattern))( true if var(string) matches var(pattern). -The `tt(==)' form is the preferred one. The `tt(=)' form is for -backward compatibility and should be considered obsolete. +The two forms are exactly equivalent. The `tt(=)' form is +the traditional shell syntax (and hence the only one generally used +with the tt(test) and tt([) builtins); the `tt(==)' form provides +compatibility with other sorts of computer language. ) item(var(string) tt(!=) var(pattern))( true if var(string) does not match var(pattern). diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index 923bb29a9..35ab100b5 100644 --- a/Doc/Zsh/contrib.yo +++ b/Doc/Zsh/contrib.yo @@ -292,11 +292,11 @@ cindex(hook function utility) startitem() findex(add-zsh-hook) -item(tt(add-zsh-hook) [ tt(-dD) ] [ tt(-Uzk) ] var(hook) var(function))( +item(tt(add-zsh-hook) [ tt(-L) | tt(-dD) ] [ tt(-Uzk) ] var(hook) var(function))( Several functions are special to the shell, as described in the section ifnzman(Special Functions, noderef(Functions))\ ifzman(SPECIAL FUNCTIONS, see zmanref(zshmisc)), -in that they are automatic called at a specific point during shell execution. +in that they are automatically called at specific points during shell execution. Each has an associated array consisting of names of functions to be called at the same point; these are so-called `hook functions'. The shell function tt(add-zsh-hook) provides a simple way of adding or @@ -311,6 +311,10 @@ still be manipulated as a hook. var(function) is name of an ordinary shell function. If no options are given this will be added to the array of functions to be executed in the given context. +Functions are invoked in the order they were added. + +If the option tt(-L) is given, the current values for the hook arrays +are listed with tt(typeset). If the option tt(-d) is given, the var(function) is removed from the array of functions to be executed. @@ -323,6 +327,55 @@ The options tt(-U), tt(-z) and tt(-k) are passed as arguments to tt(autoload) for var(function). For functions contributed with zsh, the options tt(-Uz) are appropriate. ) +findex(add-zle-hook-widget) +item(tt(add-zle-hook-widget) [ tt(-L) | tt(-dD) ] [ tt(-Uzk) ] var(hook) var(widgetname))( +Several widget names are special to the line editor, as described in the section +ifnzman(Special Widgets, noderef(Zle Widgets))\ +ifzman(Special Widgets, see zmanref(zshzle)), +in that they are automatically called at specific points during editing. +Unlike function hooks, these do not use a predefined array of other names +to call at the same point; the shell function tt(add-zle-hook-widget) +maintains a similar array and arranges for the special widget to invoke +those additional widgets. + +var(hook) is one of tt(isearch-exit), tt(isearch-update), +tt(line-pre-redraw), tt(line-init), tt(line-finish), tt(history-line-set), +or tt(keymap-select), corresponding to each of the special widgets +tt(zle-isearch-exit), etc. The special widget names are also accepted +as the var(hook) argument. + +var(widgetname) is the name of a ZLE widget. If no options are given this +is added to the array of widgets to be invoked in the given hook context. +Widgets are invoked in the order they were added, with +example(tt(zle )var(widgetname)tt( -Nw -- "$@")) + +vindex(WIDGET, in hooks) +Note that this means that the `tt(WIDGET)' special parameter tracks the +var(widgetname) when the widget function is called, rather than tracking +the name of the corresponding special hook widget. + +If the option tt(-d) is given, the var(widgetname) is removed from +the array of widgets to be executed. + +If the option tt(-D) is given, the var(widgetname) is treated as a pattern +and any matching names of widgets are removed from the array. + +If var(widgetname) does not name an existing widget when added to the +array, it is assumed that a shell function also named var(widgetname) is +meant to provide the implementation of the widget. This name is therefore +marked for autoloading, and the options tt(-U), tt(-z) and tt(-k) are +passed as arguments to tt(autoload) as with tt(add-zsh-hook). The +widget is also created with `tt(zle -N )var(widgetname)' to cause the +corresponding function to be loaded the first time the hook is called. + +The arrays of var(widgetname) are currently maintained in tt(zstyle) +contexts, one for each var(hook) context, with a style of `tt(widgets)'. +If the tt(-L) option is given, this set of styles is listed with +`tt(zstyle -L)'. This implementation may change, and the special widgets +that refer to the styles are created only if tt(add-zle-hook-widget) is +called to add at least one widget, so if this function is used for any +hooks, then all hooks should be managed only via this function. +) enditem() texinode(Recent Directories)(Other Directory Functions)(Utilities)(User Contributions) @@ -809,7 +862,8 @@ sitem(SVK (tt(svk)))(uref(http://svk.bestpractical.com/)) endsitem() There is also support for the patch management system tt(quilt) -(uref(http://savannah.nongnu.org/projects/quilt)). See tt(Quilt Support) +(uref(http://savannah.nongnu.org/projects/quilt)). See +ifzman(bf(Quilt Support))ifnzman(noderef(vcs_info Quilt Support)) below for details. To load tt(vcs_info): @@ -819,6 +873,18 @@ example(autoload -Uz vcs_info) It can be used in any existing prompt, because it does not require any specific tt($psvar) entries to be available. +startmenu() +menu(vcs_info Quickstart) +menu(vcs_info Configuration) +menu(vcs_info Oddities) +menu(vcs_info Quilt Support) +menu(vcs_info API) +menu(vcs_info Variables) +menu(vcs_info Hooks) +menu(vcs_info Examples) +endmenu() + +texinode(vcs_info Quickstart)(vcs_info Configuration)()(Version Control Information) subsect(Quickstart) To get this feature working quickly (including colors), you can do the @@ -882,6 +948,7 @@ That means the detection of these systems is skipped em(completely). No wasted time there. +texinode(vcs_info Configuration)(vcs_info Oddities)(vcs_info Quickstart)(Version Control Information) subsect(Configuration) The tt(vcs_info) feature can be configured via tt(zstyle). @@ -891,11 +958,17 @@ example(:vcs_info:var(vcs-string):var(user-context):var(repo-root-name)) startitem() item(var(vcs-string))( -is one of: bf(git), bf(git-svn), bf(git-p4), bf(hg), bf(hg-git), -bf(hg-hgsubversion), bf(hg-hgsvn), bf(darcs), bf(bzr), bf(cdv), bf(mtn), -bf(svn), bf(cvs), bf(svk), bf(tla), bf(p4) or bf(fossil). When hooks are -active the hooks name is added after a `+'. (See bf(Hooks in vcs_info) -below.) +is one of: tt(git), tt(git-svn), tt(git-p4), tt(hg), tt(hg-git), +tt(hg-hgsubversion), tt(hg-hgsvn), tt(darcs), tt(bzr), tt(cdv), tt(mtn), +tt(svn), tt(cvs), tt(svk), tt(tla), tt(p4) or tt(fossil). +This is followed by `tt(.quilt-)var(quilt-mode)' in Quilt mode +(see ifzman(bf(Quilt Support))ifnzman(noderef(vcs_info Quilt Support)) for details) +and by `tt(+)var(hook-name)' while hooks are active +(see ifzman(bf(Hooks in vcs_info))ifnzman(noderef(vcs_info Hooks)) for details). + +COMMENT(users/20807) +Currently, hooks in quilt mode don't add the `tt(.quilt-)var(quilt-mode)' information. +This may change in the future. ) item(var(user-context))( is a freely configurable string, assignable by @@ -998,26 +1071,26 @@ tt(:vcs_info:-init-:*:-all-) context. Say, tt(~/.zsh) is a directory under version control, in which you do not want tt(vcs_info) to be active, do: -example(zstyle ':vcs_info:*' disable-patterns "$HOME/.zsh+LPAR()|/*+RPAR()") +example(zstyle ':vcs_info:*' disable-patterns "${+LPAR()b+RPAR()HOME}/.zsh+LPAR()|/*+RPAR()") ) kindex(use-quilt) item(tt(use-quilt))( If enabled, the tt(quilt) support code is active in `addon' mode. -See tt(Quilt Support) for details. +See ifzman(bf(Quilt Support))ifnzman(noderef(vcs_info Quilt Support)) for details. ) kindex(quilt-standalone) item(tt(quilt-standalone))( If enabled, `standalone' mode detection is attempted if no VCS is active -in a given directory. See tt(Quilt Support) for details. +in a given directory. See ifzman(bf(Quilt Support))ifnzman(noderef(vcs_info Quilt Support)) for details. ) kindex(quilt-patch-dir) item(tt(quilt-patch-dir))( Overwrite the value of the tt($QUILT_PATCHES) environment variable. See -tt(Quilt Support) for details. +ifzman(bf(Quilt Support))ifnzman(noderef(vcs_info Quilt Support)) for details. ) kindex(quiltcommand) item(tt(quiltcommand))( -When tt(quilt) itself is called in quilt support the value of this style +When tt(quilt) itself is called in quilt support, the value of this style is used as the command name. ) kindex(check-for-changes) @@ -1144,7 +1217,8 @@ is only used by tt(vcs_info)'s hooks system. ) kindex(hooks) item(tt(hooks))( -A list style that defines hook-function names. See bf(Hooks in vcs_info) +A list style that defines hook-function names. See ifzman(bf(Hooks in vcs_info))\ +ifnzman(noderef(vcs_info Hooks)) below for details. ) kindex(patch-format) @@ -1154,6 +1228,8 @@ item(tt(nopatch-format))( This pair of styles format the patch information used by the tt(%m) expando in formats and actionformats for the tt(git) and tt(hg) backends. The value is subject to certain tt(%)-expansions described below. +The expanded value is made available in the global tt(backend_misc) array as +tt(${backend_misc[patches]}) (also if a tt(set-patch-format) hook is used). ) kindex(get-unapplied) item(tt(get-unapplied))( @@ -1224,8 +1300,8 @@ A "misc" replacement. It is at the discretion of the backend to decide what this replacement expands to. The tt(hg) and tt(git) backends use this expando to display patch information. -tt(hg) sources patch information from the tt(mq) extensions; tt(git) from the -tt(rebase) command and from the and tt(stgit) extension. The tt(patch-format) +tt(hg) sources patch information from the tt(mq) extensions; tt(git) from in-progress +tt(rebase) and tt(cherry-pick) operations and from the tt(stgit) extension. The tt(patch-format) and tt(nopatch-format) styles control the generated string. The former is used when at least one patch from the patch queue has been applied, and the latter otherwise. @@ -1235,6 +1311,17 @@ to tt(mq) information). See the tt(get-mq) and tt(get-bookmarks) styles. Both of these styles may be enabled at the same time. If both are enabled, both resulting strings will be shown separated by a semicolon (that cannot currently be customized). + +The tt(quilt) `standalone' backend sets this expando to the same value as the +tt(%Q) expando. +) +item(tt(%Q))( +Quilt series information. +When quilt is used (either in `addon' mode or as a `standalone' backend), +this expando is set to quilt series' tt(patch-format) string. +The tt(set-patch-format) hook and tt(nopatch-format) style are honoured. + +See ifzman(tt(Quilt Support))ifnzman(noderef(vcs_info Quilt Support)) below for details. ) enditem() @@ -1268,6 +1355,7 @@ endsitem() Not all VCS backends have to support all replacements. For tt(nvcsformats) no replacements are performed at all, it is just a string. +texinode(vcs_info Oddities)(vcs_info Quilt Support)(vcs_info Configuration)(Version Control Information) subsect(Oddities) If you want to use the tt(%b) (bold off) prompt expansion in tt(formats), @@ -1278,7 +1366,14 @@ tt(branchformat), use tt(%%%%b). Sorry for this inconvenience, but it cannot be easily avoided. Luckily we do not clash with a lot of prompt expansions and this only needs to be done for those. +When one of the tt(gen-applied-string), tt(gen-unapplied-string), and +tt(set-patch-format) hooks is defined, +applying tt(%)-escaping (`tt(foo=${foo//'%'/%%})') to the interpolated values +for use in the prompt is the responsibility of those hooks (jointly); +when neither of those hooks is defined, tt(vcs_info) handles escaping by itself. +We regret this coupling, but it was required for backwards compatibility. +texinode(vcs_info Quilt Support)(vcs_info API)(vcs_info Oddities)(Version Control Information) subsect(Quilt Support) bf(Quilt) is not a version control system, therefore this is not implemented @@ -1293,13 +1388,22 @@ The tt(vcs_info) integration tries to support both ways of using quilt by having two slightly different modes of operation: `addon' mode and `standalone' mode). +Quilt integration is off by default; to enable it, set the tt(use-quilt) style, +and add tt(%Q) to your tt(formats) or tt(actionformats) style: +example(zstyle ':vcs_info:*' use-quilt true) + +Styles looked up from the Quilt support code include `tt(.quilt-)var(quilt-mode)' +in the var(vcs-string) part of the context, where var(quilt-mode) is either +tt(addon) or tt(standalone). +Example: tt(:vcs_info:git.quilt-addon:default:)var(repo-root-name). + For `addon' mode to become active tt(vcs_info) must have already detected a real version control system controlling the directory. If that is the case, a directory that holds quilt's patches needs to be found. That directory is configurable via the `tt(QUILT_PATCHES)' environment variable. If that variable exists its value is used, otherwise the value `tt(patches)' is assumed. The value from tt($QUILT_PATCHES) can be overwritten using the -tt(`quilt-patches') style. (Note: you can use tt(vcs_info) to keep the value +`tt(quilt-patches)' style. (Note: you can use tt(vcs_info) to keep the value of tt($QUILT_PATCHES) correct all the time via the tt(post-quilt) hook). When the directory in question is found, quilt is assumed to be active. To @@ -1313,8 +1417,10 @@ to know which patches of a series are not yet applied, you need to activate the tt(get-unapplied) style in the appropriate context. tt(vcs_info) allows for very detailed control over how the gathered -information is presented (see the below sections, bf(Styles) and bf(Hooks in -vcs_info)), all of which are documented below. Note there are a number of +information is presented (see +ifzman(the bf(Configuration) and bf(Hooks in vcs_info) sections)\ +ifnzman(noderef(vcs_info Configuration) and noderef(vcs_info Hooks))), +all of which are documented below. Note there are a number of other patch tracking systems that work on top of a certain version control system (like tt(stgit) for bf(git), or tt(mq) for bf(hg)); the configuration for systems like that are generally configured the same way as the bf(quilt) @@ -1368,6 +1474,7 @@ Note, if there is both a function and a variable by the name of tt(quilt-standalone), the function will take precedence. +texinode(vcs_info API)(vcs_info Variables)(vcs_info Quilt Support)(Version Control Information) subsect(Function Descriptions (Public API)) startitem() @@ -1376,7 +1483,8 @@ item(tt(vcs_info) [var(user-context)])( The main function, that runs all backends and assembles all data into tt(${vcs_info_msg_*_}). This is the function you want to call from tt(precmd) if you want to include up-to-date information in your prompt (see -tt(Variable description) below). If an argument is given, that string will be +ifzman(bf(Variable Description))ifnzman(noderef(vcs_info Variables)) +below). If an argument is given, that string will be used instead of tt(default) in the var(user-context) field of the style context. ) @@ -1385,7 +1493,8 @@ item(tt(vcs_info_hookadd))( Statically registers a number of functions to a given hook. The hook needs to be given as the first argument; what follows is a list of hook-function names to register to the hook. The `tt(+vi-)' prefix needs to be left out -here. See bf(Hooks in vcs_info) below for details. +here. See ifzman(bf(Hooks in vcs_info))ifnzman(noderef(vcs_info Hooks)) +below for details. ) findex(vcs_info_hookdel) item(tt(vcs_info_hookdel))( @@ -1394,8 +1503,9 @@ first non-option argument; what follows is a list of hook-function names to un-register from the hook. If `tt(-a)' is used as the first argument, tt(all) occurrences of the functions are unregistered. Otherwise only the last occurrence is removed (if a function was registered to a hook -more than once) . The `tt(+vi-)' prefix needs to be left out here. See -bf(Hooks in vcs_info) below for details. +more than once). The `tt(+vi-)' prefix needs to be left out here. +See ifzman(bf(Hooks in vcs_info))ifnzman(noderef(vcs_info Hooks)) +below for details. ) findex(vcs_info_lastmsg) item(tt(vcs_info_lastmsg))( @@ -1420,6 +1530,7 @@ enditem() All functions named tt(VCS_INFO_*) are for internal use only. +texinode(vcs_info Variables)(vcs_info Hooks)(vcs_info API)(Version Control Information) subsect(Variable Description) startitem() @@ -1437,6 +1548,7 @@ enditem() All variables named tt(VCS_INFO_*) are for internal use only. +texinode(vcs_info Hooks)(vcs_info Examples)(vcs_info Variables)(Version Control Information) subsect(Hooks in vcs_info) Hooks are places in tt(vcs_info) where you can run your own code. That @@ -1544,10 +1656,11 @@ so far in the opposite order, which means that the first argument is the top-most patch and so forth. When setting tt(ret) to non-zero, the string in -tt(${hook_com[applied-string]}) will be used in the tt(%m) escape in -tt(formats) and tt(actionformats); it will be available in the global -tt(backend_misc) array as tt($backend_misc[patches]}); and it will be +tt(${hook_com[applied-string]}) will be available as tt(%p) in the tt(patch-format) and tt(nopatch-format) styles. +This hook is, in concert with tt(set-patch-format), responsible for +tt(%)-escaping that value for use in the prompt. +(See ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).) ) item(tt(gen-unapplied-string))( Called in the tt(git) (with tt(stgit) or during rebase), and tt(hg) (with @@ -1561,6 +1674,9 @@ the patch next-in-line to be applied and so forth. When setting tt(ret) to non-zero, the string in tt(${hook_com[unapplied-string]}) will be available as tt(%u) in the tt(patch-format) and tt(nopatch-format) styles. +This hook is, in concert with tt(set-patch-format), responsible for +tt(%)-escaping that value for use in the prompt. +(See ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).) ) item(tt(gen-mqguards-string))( Called in the tt(hg) backend when tt(guards-string) is generated; the @@ -1638,6 +1754,11 @@ controllable in addition to that. If tt(ret) is set to non-zero, the string in tt(${hook_com[patch-replace]}) will be used unchanged instead of an expanded format from tt(patch-format) or tt(nopatch-format). + +This hook is, in concert with the tt(gen-applied-string) or +tt(gen-unapplied-string) hooks if they are defined, responsible for +tt(%)-escaping the final tt(patch-format) value for use in the prompt. +(See ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).) ) item(tt(set-message))( Called each time before a `tt(vcs_info_msg_)var(N)tt(_)' message is set. @@ -1666,10 +1787,12 @@ tt(vcs_info). ) enditem() -If all of this sounds rather confusing, take a look at the bf(Examples) -section below and also in the tt(Misc/vcs_info-examples) file in the Zsh source. +If all of this sounds rather confusing, take a look at +ifzman(the bf(Examples) section below)ifnzman(noderef(vcs_info Examples)) +and also in the tt(Misc/vcs_info-examples) file in the Zsh source. They contain some explanatory code. +texinode(vcs_info Examples)()(vcs_info Hooks)(Version Control Information) subsect(Examples) Don't use tt(vcs_info) at all (even though it's in your prompt): @@ -1888,6 +2011,8 @@ tindex(transpose-words-match) tindex(capitalize-word-match) tindex(up-case-word-match) tindex(down-case-word-match) +tindex(delete-whole-word-match) +tindex(select-word-match) tindex(select-word-style) tindex(match-word-context) tindex(match-words-by-style) @@ -1895,12 +2020,14 @@ xitem(tt(forward-word-match), tt(backward-word-match)) xitem(tt(kill-word-match), tt(backward-kill-word-match)) xitem(tt(transpose-words-match), tt(capitalize-word-match)) xitem(tt(up-case-word-match), tt(down-case-word-match)) +xitem(tt(delete-whole-word-match), tt(select-word-match)) item(tt(select-word-style), tt(match-word-context), tt(match-words-by-style))( -The eight `tt(-match)' functions are drop-in replacements for the +The first eight `tt(-match)' functions are drop-in replacements for the builtin widgets without the suffix. By default they behave in a similar way. However, by the use of styles and the function tt(select-word-style), -the way words are matched can be altered. For comparison, the widgets -described in ifzman(zmanref(zshzle) under Text Objects)\ +the way words are matched can be altered. tt(select-word-match) is intended +to be used as a text object in vi mode but with custom word styles. For +comparison, the widgets described in ifzman(zmanref(zshzle) under Text Objects)\ ifnzman(noderef(Text Objects)) use fixed definitions of words, compatible with the tt(vim) editor. @@ -1908,7 +2035,7 @@ The simplest way of configuring the functions is to use tt(select-word-style), which can either be called as a normal function with the appropriate argument, or invoked as a user-defined widget that will prompt for the first character of the word style to be used. The first -time it is invoked, the eight tt(-match) functions will automatically +time it is invoked, the first eight tt(-match) functions will automatically replace the builtin versions, so they do not need to be loaded explicitly. The word styles available are as follows. Only the first character @@ -2049,7 +2176,7 @@ Here are some examples of use of the tt(word-context) style to extend the context. example(zstyle ':zle:*' word-context \ - "*/*" file "[[:space:]]" whitespace + "*/*" filename "[[:space:]]" whitespace zstyle ':zle:transpose-words:whitespace' word-style shell zstyle ':zle:transpose-words:filename' word-style normal zstyle ':zle:transpose-words:filename' word-chars '') @@ -2076,6 +2203,17 @@ non-word characters following that word (7) the remainder of the line. Any of the elements may be an empty string; the calling function should test for this to decide whether it can perform its function. +If the variable tt(matched_words) is defined by the caller to +tt(match-words-by-style) as an associative array (tt(local -A +matched_words)), then the seven values given above should be retrieved +from it as elements named tt(start), tt(word-before-cursor), +tt(ws-before-cursor), tt(ws-after-cursor), tt(word-after-cursor), +tt(ws-after-word), and tt(end). In addition the element +tt(is-word-start) is 1 if the cursor is on the start of a word or +subword, or on white space before it (the cases can be distinguished by +testing the tt(ws-after-cursor) element) and 0 otherwise. This form is +recommended for future compatibility. + It is possible to pass options with arguments to tt(match-words-by-style) to override the use of styles. The options are: startsitem() @@ -2094,7 +2232,7 @@ tt(match-word-context). This should not usually need to be called directly. ) tindex(bracketed-paste-magic) -item(bracketed-paste-magic)( +item(tt(bracketed-paste-magic))( The tt(bracketed-paste) widget (see ifzman(subsection Miscellaneous in zmanref(zshzle))ifnzman(noderef(Miscellaneous) in noderef(Zle Widgets))) inserts pasted text literally into the editor buffer rather than interpret @@ -2912,6 +3050,17 @@ and aliases `tt(globurl)' to `tt(noglob urlglobber)'. This function takes a local URL apart, attempts to pattern-match the local file portion of the URL path, and then puts the results back into URL format again. ) +tindex(vi-pipe) +item(tt(vi-pipe))( +This function reads a movement command from the keyboard and then +prompts for an external command. The part of the buffer covered by +the movement is piped to the external command and then replaced by +the command's output. If the movement command is bound to vi-pipe, +the current line is used. + +The function serves as an example for reading a vi movement command +from within a user-defined widget. +) tindex(which-command) item(tt(which-command))( This function is a drop-in replacement for the builtin widget @@ -2941,6 +3090,9 @@ the variable tt(ZCALC_AUTO_INSERT_PREFIX). Hence, for example, typing `tt(PLUS()12)' followed by return adds 12 to the previous result. +If zcalc is in RPN mode (tt(-r) option) the effect of this binding is +automatically suppressed as operators alone on a line are meaningful. + When not in zcalc, the key simply inserts the symbol itself. ) enditem() @@ -3396,7 +3548,7 @@ will ensure that any files found in that area will be executed as MIME types even if they are executable. As this example shows, the complete file name is matched against the pattern, regardless of how the file was passed to the handler. The file is resolved to a full path using -the tt(:A) modifier described in +the tt(:P) modifier described in ifzman(the subsection Modifiers in zmanref(zshexpn))\ ifnzman(noderef(Modifiers)); this means that symbolic links are resolved where possible, so that @@ -3654,7 +3806,7 @@ sect(Mathematical Functions) startitem() findex(zcalc) -item(tt(zcalc) [ tt(-ef) ] [ var(expression) ... ])( +item(tt(zcalc) [ tt(-erf) ] [ var(expression) ... ])( A reasonably powerful calculator based on zsh's arithmetic evaluation facility. The syntax is similar to that of formulae in most programming languages; see @@ -3705,8 +3857,14 @@ first few positional parameters. A visual indication of this is given when the calculator starts. The constants tt(PI) (3.14159...) and tt(E) (2.71828...) are provided. -Parameter assignment is possible, but note that all parameters will be put -into the global namespace. +Parameter assignment is possible, but note that all parameters will be +put into the global namespace unless the tt(:local) special command is +used. The function creates local variables whose names start with +tt(_), so users should avoid doing so. The variables tt(ans) (the last +answer) and tt(stack) (the stack in RPN mode) may be referred to +directly; tt(stack) is an array but elements of it are numeric. Various +other special variables are used locally with their standard meaning, +for example tt(compcontext), tt(match), tt(mbegin), tt(mend), tt(psvar). The output base can be initialised by passing the option `tt(-#)var(base)', for example `tt(zcalc -#16)' (the `tt(#)' may have to be quoted, depending @@ -3720,12 +3878,70 @@ If the option `tt(-f)' is set, all numbers are treated as floating point, hence for example the expression `tt(3/4)' evaluates to 0.75 rather than 0. Options must appear in separate words. +If the option `tt(-r)' is set, RPN (Reverse Polish Notation) mode is +entered. This has various additional properties: +startitem() +item(Stack)( +Evaluated values are maintained in a stack; this is contained in +an array named tt(stack) with the most recent value in tt(${stack[1]}). +) +item(Operators and functions)( +If the line entered matches an operator (tt(+), tt(-), tt(*), +tt(/), tt(**), tt(^), tt(|) or tt(&)) or a function supplied by the +tt(zsh/mathfunc) library, the bottom element or elements of the stack +are popped to use as the argument or arguments. The higher elements +of stack (least recent) are used as earlier arguments. The result is +then pushed into tt(${stack[1]}). +) +item(Expressions)( +Other expressions are evaluated normally, printed, and added to the +stack as numeric values. The syntax within expressions on a single line +is normal shell arithmetic (not RPN). +) +item(Stack listing)( +If an integer follows the option tt(-r) with no space, then +on every evaluation that many elements of the stack, where available, +are printed instead of just the most recent result. Hence, for example, +tt(zcalc -r4) shows tt($stack[4]) to tt($stack[1]) each time results +are printed. +) +item(Duplication: tt(=))( +The pseudo-operator tt(=) causes the most recent element of +the stack to be duplicated onto the stack. +) +item(tt(pop))( +The pseudo-function tt(pop) causes the most recent element of +the stack to be popped. A `tt(>)' on its own has the same effect. +) +item(tt(>)var(ident))( +The expression tt(>) followed (with no space) by a shell identifier +causes the most recent element of the stack to be popped and +assigned to the variable with that name. The variable is +local to the tt(zcalc) function. +) +item(tt(<)var(ident))( +The expression tt(<) followed (with no space) by a shell identifier +causes the value of the variable with that name to be pushed +onto the stack. var(ident) may be an integer, in which +case the previous result with that number (as shown before +the tt(>) in the standard tt(zcalc) prompt) is put on the stack. +) +item(Exchange: tt(xy))( +The pseudo-function tt(xy) causes the most recent two elements of +the stack to be exchanged. `tt(<>)' has the same effect. +) +enditem() + The prompt is configurable via the parameter tt(ZCALCPROMPT), which undergoes standard prompt expansion. The index of the current entry is stored locally in the first element of the array tt(psvar), which can be referred to in tt(ZCALCPROMPT) as `tt(%1v)'. The default prompt is `tt(%1v> )'. +The variable tt(ZCALC_ACTIVE) is set within the function and can +be tested by nested functions; it has the value tt(rpn) if RPN mode is +active, else 1. + A few special commands are available; these are introduced by a colon. For backward compatibility, the colon may be omitted for certain commands. Completion is available if tt(compinit) has been run. @@ -3765,8 +3981,7 @@ is executed in the context of the function, i.e. with local variables. Space is optional after tt(:!). ) item(tt(:local) var(arg) ...)( -Declare variables local to the function. Note that certain variables -are used by the function for its own purposes. Other variables +Declare variables local to the function. Other variables may be used, too, but they will be taken from or put into the global scope. ) @@ -3780,7 +3995,13 @@ Note that tt(zcalc) takes care of all quoting. Hence for example: example(:f cube $1 * $1 * $1) -defines a function to cube the sole argument. +defines a function to cube the sole argument. Functions so defined, or +indeed any functions defined directly or indirectly using tt(functions +-M), are available to execute by typing only the name on the line in RPN +mode; this pops the appropriate number of arguments off the stack +to pass to the function, i.e. 1 in the case of the example tt(cube) +function. If there are optional arguments only the mandatory +arguments are supplied by this means. ) item(tt([#)var(base)tt(]))( This is not a special command, rather part of normal arithmetic @@ -3792,6 +4013,10 @@ always specified in decimal. `tt([#])' restores the normal output format. Note that setting an output base suppresses floating point output; use `tt([#])' to return to normal operation. ) +item(tt($)var(var))( +Print out the value of var literally; does not affect the calculation. +To use the value of var, omit the leading `tt($)'. +) enditem() See the comments in the function for a few extra tips. diff --git a/Doc/Zsh/exec.yo b/Doc/Zsh/exec.yo index 30e4a61a2..5f79967de 100644 --- a/Doc/Zsh/exec.yo +++ b/Doc/Zsh/exec.yo @@ -28,10 +28,11 @@ not handle this executable format in the kernel. If no external command is found but a function tt(command_not_found_handler) exists the shell executes this function with all -command line arguments. The function should return status zero if it -successfully handled the command, or non-zero status if it failed. -In the latter case the standard handling is applied: `command not -found' is printed to standard error and the shell exits with status 127. -Note that the handler is executed in a subshell forked to execute -an external command, hence changes to directories, shell parameters, -etc. have no effect on the main shell. +command line arguments. The return status of the function becomes the +status of the command. If the function wishes to mimic the +behaviour of the shell when the command is not found, it should +print the message `tt(command not found:) var(cmd)' to standard error +and return status 127. Note that the handler is executed in a +subshell forked to execute an external command, hence changes to +directories, shell parameters, etc. have no effect on the main shell. + diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo index c6e7b6f16..d161b0ba5 100644 --- a/Doc/Zsh/expn.yo +++ b/Doc/Zsh/expn.yo @@ -219,15 +219,28 @@ noted. startitem() item(tt(a))( Turn a file name into an absolute path: prepends the current directory, -if necessary, and resolves any use of `tt(..)' and `tt(.)' in the path. -Note that the transformation takes place even if the file or any -intervening directories do not exist. +if necessary; remove `tt(.)' path segments; and remove `tt(..)' path segments +and the segments that immediately precede them. + +This transformation is agnostic about what is in the filesystem, i.e. is +on the logical, not the physical directory. It takes place in the same +manner as when changing directories when neither of the options +tt(CHASE_DOTS) or tt(CHASE_LINKS) is set. For example, +`tt(/before/here/../after)' is always transformed to +`tt(/before/after)', regardless of whether `tt(/before/here)' exists or what +kind of object (dir, file, symlink, etc.) it is. ) item(tt(A))( -As `tt(a)', but also resolve use of symbolic links where possible. -Note that resolution of `tt(..)' occurs em(before) resolution of symbolic -links. This call is equivalent to tt(a) unless your system has the -tt(realpath) system call (modern systems do). +Turn a file name into an absolute path as the `tt(a)' modifier does, and +em(then) pass the result through the tt(realpath+LPAR()3+RPAR()) library +function to resolve symbolic links. + +Note: on systems that do not have a tt(realpath+LPAR()3+RPAR()) library +function, symbolic links are not resolved, so on those systems `tt(a)' and +`tt(A)' are equivalent. + +Note: tt(foo:A) and tt(realpath+LPAR()foo+RPAR()) are different on some inputs. +For tt(realpath+LPAR()foo+RPAR()) semantics, see the `tt(P)` modifier. ) item(tt(c))( Resolve a command name into an absolute path by searching the command @@ -253,6 +266,14 @@ item(tt(p))( Print the new command but do not execute it. Only works with history expansion. ) +item(tt(P))( +Turn a file name into an absolute path, like tt(realpath+LPAR()3+RPAR()). +The resulting path will be absolute, have neither `tt(.)' nor `tt(..)' components, +and refer to the same directory entry as the input filename. + +Unlike tt(realpath+LPAR()3+RPAR()), non-existent trailing components are +permitted and preserved. +) item(tt(q))( Quote the substituted words, escaping further substitutions. Works with history expansion and parameter expansion, though for parameters @@ -551,6 +572,18 @@ noderef(Modifiers) in noderef(History Expansion) can be applied: for example, tt(${i:s/foo/bar/}) performs string substitution on the expansion of parameter tt($i). +In the following descriptions, `word' refers to a single word +substituted on the command line, not necessarily a space delimited word. +With default options, after the assignments: + +example(array=("first word" "second word") +scalar="only word") + +then tt($array) substitutes two words, `tt(first word)' and `tt(second +word)', and tt($scalar) substitutes a single word `tt(only word)'. This +may be modified by explicit or implicit word-splitting, however. The +full rules are complicated and are noted at the end. + startitem() item(tt(${)var(name)tt(}))( The value, if any, of the parameter var(name) is substituted. @@ -724,7 +757,7 @@ character of tt($foo) if the substitution would otherwise return a scalar, or the array starting at the fourth element if tt($foo) would return an array. Note that with the option tt(KSH_ARRAYS) tt($foo) always returns a scalar (regardless of the use of the offset syntax) and a form -such as tt($foo[*]:3) is required to extract elements of an array named +such as tt(${foo[*]:3}) is required to extract elements of an array named tt(foo). If var(offset) is negative, the tt(-) may not appear immediately @@ -740,8 +773,8 @@ expression tt(${var: offs}) does work, retrieving the offset from tt($offs). For further compatibility with other shells there is a special case -for array offset 0. This usually accesses to the -first element of the array. However, if the substitution refers the +for array offset 0. This usually accesses the +first element of the array. However, if the substitution refers to the positional parameter array, e.g. tt($@) or tt($*), then offset 0 instead refers to tt($0), offset 1 refers to tt($1), and so on. In other words, the positional parameter array is effectively extended by @@ -749,12 +782,14 @@ prepending tt($0). Hence tt(${*:0:1}) substitutes tt($0) and tt(${*:1:1}) substitutes tt($1). ) xitem(tt(${)var(name)tt(/)var(pattern)tt(/)var(repl)tt(})) -item(tt(${)var(name)tt(//)var(pattern)tt(/)var(repl)tt(}))( +xitem(tt(${)var(name)tt(//)var(pattern)tt(/)var(repl)tt(})) +item(tt(${)var(name)tt(:/)var(pattern)tt(/)var(repl)tt(}))( Replace the longest possible match of var(pattern) in the expansion of parameter var(name) by string var(repl). The first form -replaces just the first occurrence, the second form all occurrences. +replaces just the first occurrence, the second form all occurrences, +and the third form replaces only if var(pattern) matches the entire string. Both var(pattern) and var(repl) are subject to double-quoted substitution, -so that expressions like tt(${name/$opat/$npat}) will work, but note the +so that expressions like tt(${name/$opat/$npat}) will work, but obey the usual rule that pattern characters in tt($opat) are not treated specially unless either the option tt(GLOB_SUBST) is set, or tt($opat) is instead substituted as tt(${~opat}). @@ -770,8 +805,8 @@ single backslash; this is not necessary if the `tt(%)' and `tt(#%) are not active if they occur inside a substituted parameter, even at the start. -The first `tt(/)' may be preceded by a `tt(:)', in which case the match -will only succeed if it matches the entire word. Note also the +If, after quoting rules apply, tt(${)var(name)tt(}) expands to an array, +the replacements act on each element individually. Note also the effect of the tt(I) and tt(S) parameter expansion flags below; however, the flags tt(M), tt(R), tt(B), tt(E) and tt(N) are not useful. @@ -920,15 +955,25 @@ This is distinct from em(field splitting) by the tt(f), tt(s) or tt(z) flags, which still applies within each array element. ) item(tt(A))( -Create an array parameter with `tt(${)...tt(=)...tt(})', +Convert the substitution into an array expression, even if it otherwise +would be scalar. This has lower precedence than subscripting, so one +level of nested expansion is required in order that subscripts apply +to array elements. Thus tt(${${LPAR()A)tt(RPAR())var(name)tt(}[1]}) +yields the full value of var(name) when var(name) is scalar. + +This assigns an array parameter with `tt(${)...tt(=)...tt(})', `tt(${)...tt(:=)...tt(})' or `tt(${)...tt(::=)...tt(})'. -If this flag is repeated (as in `tt(AA)'), create an associative +If this flag is repeated (as in `tt(AA)'), assigns an associative array parameter. Assignment is made before sorting or padding; if field splitting is active, the var(word) part is split before assignment. The var(name) part may be a subscripted range for -ordinary arrays; the var(word) part em(must) be converted to -an array, for example by using `tt(${(AA)=)var(name)tt(=)...tt(})' -to activate field splitting, when creating an associative array. +ordinary arrays; when assigning an associative array, the var(word) +part em(must) be converted to an array, for example by using +`tt(${(AA)=)var(name)tt(=)...tt(})' to activate field splitting. + +Surrounding context such as additional nesting or use of the value +in a scalar assignment may cause the array to be joined back into +a single string again. ) item(tt(a))( Sort in array index order; when combined with `tt(O)' sort in reverse @@ -1004,7 +1049,9 @@ If var(name) refers to an associative array, substitute the em(keys) (element names) rather than the values of the elements. Used with subscripts (including ordinary arrays), force indices or keys to be substituted even if the subscript form refers to values. However, -this flag may not be combined with subscript ranges. +this flag may not be combined with subscript ranges. With the +tt(KSH_ARRAYS) option a subscript `tt([*])' or `tt([@])' is needed +to operate on the whole array, as usual. ) item(tt(L))( Convert all letters in the result to lower case. @@ -1359,7 +1406,8 @@ item(tt(B))( Include the index of the beginning of the match in the result. ) item(tt(E))( -Include the index of the end of the match in the result. +Include the index one character past the end of the match in the result +(note this is inconsistent with other uses of parameter index). ) item(tt(M))( Include the matched portion in the result. @@ -2064,6 +2112,7 @@ Matches either var(x) or var(y). This operator has lower precedence than any other. The `tt(|)' character must be within parentheses, to avoid interpretation as a pipeline. +The alternatives are tried in order from left to right. ) item(tt(^)var(x))( (Requires tt(EXTENDED_GLOB) to be set.) diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo index 2a76964f3..463ac8831 100644 --- a/Doc/Zsh/grammar.yo +++ b/Doc/Zsh/grammar.yo @@ -461,6 +461,9 @@ item(tt(select) var(name) [ tt(in) var(word) ... var(term) ] var(sublist))( where var(term) is at least one newline or tt(;). A short form of tt(select). ) +item(tt(function) var(word) ... [ tt(+LPAR()+RPAR()) ] [ var(term) ] var(sublist))( +This is a short form of tt(function). +) enditem() texinode(Reserved Words)(Errors)(Alternate Forms For Complex Commands)(Shell Grammar) sect(Reserved Words) diff --git a/Doc/Zsh/jobs.yo b/Doc/Zsh/jobs.yo index d9395010a..6262dd244 100644 --- a/Doc/Zsh/jobs.yo +++ b/Doc/Zsh/jobs.yo @@ -74,8 +74,8 @@ or by one of the following: startsitem() sitem(tt(%)var(number))(The job with the given number.) -sitem(tt(%)var(string))(Any job whose command line begins with var(string).) -sitem(tt(%?)var(string))(Any job whose command line contains var(string).) +sitem(tt(%)var(string))(The last job whose command line begins with var(string).) +sitem(tt(%?)var(string))(The last job whose command line contains var(string).) sitem(tt(%%))(Current job.) sitem(tt(%PLUS()))(Equivalent to `tt(%%)'.) sitem(tt(%-))(Previous job.) diff --git a/Doc/Zsh/mod_complist.yo b/Doc/Zsh/mod_complist.yo index 31aa656f1..463486ff9 100644 --- a/Doc/Zsh/mod_complist.yo +++ b/Doc/Zsh/mod_complist.yo @@ -134,7 +134,10 @@ matches beginning with `tt(m)' in groups whose names begin with Note also that all patterns are tried in the order in which they appear in the parameter value until the first one matches which is -then used. +then used. Patterns may be matched against completions, descriptions +(possibly with spaces appended for padding), or lines consisting of a +completion followed by a description. For consistent coloring it may be +necessary to use more than one pattern or a pattern with backreferences. When printing a match, the code prints the value of tt(lc), the value for the file-type or the last matching specification with a `tt(*)', diff --git a/Doc/Zsh/mod_curses.yo b/Doc/Zsh/mod_curses.yo index 72dc4094a..6e4831abe 100644 --- a/Doc/Zsh/mod_curses.yo +++ b/Doc/Zsh/mod_curses.yo @@ -27,7 +27,8 @@ xitem(tt(zcurses) tt(scroll) var(targetwin) [ tt(on) | tt(off) | [tt(+)|tt(-)]va xitem(tt(zcurses) tt(input) var(targetwin) [ var(param) [ var(kparam) [ var(mparam) ] ] ]) xitem(tt(zcurses) tt(mouse) [ tt(delay) var(num) | [tt(+)|tt(-)]tt(motion) ]) xitem(tt(zcurses) tt(timeout) var(targetwin) var(intval)) -item(tt(zcurses) tt(querychar) var(targetwin) [ var(param) ])( +xitem(tt(zcurses) tt(querychar) var(targetwin) [ var(param) ]) +item(tt(zcurses) tt(resize) var(height) var(width) [ tt(endwin) | tt(nosave) | tt(endwin_nosave) ])( Manipulate curses windows. All uses of this command should be bracketed by `tt(zcurses init)' to initialise use of curses, and `tt(zcurses end)' to end it; omitting `tt(zcurses end)' can cause @@ -211,6 +212,21 @@ second is the color pair in the usual var(fg_col)tt(/)var(bg_col) notation, or tt(0) if color is not supported. Any attributes other than color that apply to the character, as set with the subcommand tt(attr), appear as additional elements. + +The subcommand tt(resize) resizes tt(stdscr) and all windows to given +dimensions (windows that stick out from the new dimensions are resized +down). The underlying curses extension (tt(resize_term call)) can be +unavailable. To verify, zeroes can be used for var(height) and +var(width). If the result of the subcommand is tt(0), resize_term is +available (tt(2) otherwise). Tests show that resizing can be normally +accomplished by calling tt(zcurses end) and tt(zcurses refresh). The +tt(resize) subcommand is provided for versatility. Multiple system +configurations have been checked and tt(zcurses end) and tt(zcurses +refresh) are still needed for correct terminal state after resize. To +invoke them with tt(resize), use var(endwin) argument. Using +var(nosave) argument will cause new terminal state to not be saved +internally by tt(zcurses). This is also provided for versatility and +should normally be not needed. ) enditem() diff --git a/Doc/Zsh/mod_db_gdbm.yo b/Doc/Zsh/mod_db_gdbm.yo index 90974297c..699e9ab93 100644 --- a/Doc/Zsh/mod_db_gdbm.yo +++ b/Doc/Zsh/mod_db_gdbm.yo @@ -43,6 +43,17 @@ local scope (function) ends. Note that a readonly parameter may not be explicitly unset, so the only way to unset a global parameter created with `tt(ztie -r)' is to use `tt(zuntie -u)'. ) +findex(zgdbmpath) +cindex(database file path, reading) +item(tt(zgdbmpath) var(parametername))( +Put path to database file assigned to var(parametername) into tt(REPLY) +scalar. +) +findex(zgdbm_tied) +cindex(database tied arrays, enumerating) +item(tt(zgdbm_tied))( +Array holding names of all tied parameters. +) enditem() The fields of an associative array tied to GDBM are neither cached nor diff --git a/Doc/Zsh/mod_parameter.yo b/Doc/Zsh/mod_parameter.yo index 3d260f8e9..942e4c5b6 100644 --- a/Doc/Zsh/mod_parameter.yo +++ b/Doc/Zsh/mod_parameter.yo @@ -37,6 +37,30 @@ vindex(dis_functions) item(tt(dis_functions))( Like tt(functions) but for disabled functions. ) +vindex(functions_source) +item(tt(functions_source))( +This readonly associative array maps names of enabled functions to the +name of the file containing the source of the function. + +For an autoloaded function that has already been loaded, or marked for +autoload with an absolute path, or that has had its path resolved with +`tt(functions -r)', this is the file found for autoloading, resolved +to an absolute path. + +For a function defined within the body of a script or sourced file, +this is the name of that file. In this case, this is the exact path +originally used to that file, which may be a relative path. + +For any other function, including any defined at an interactive prompt or +an autoload function whose path has not yet been resolved, this is +the empty string. However, the hash element is reported as defined +just so long as the function is present: the keys to this hash are +the same as those to tt($funcions). +) +vindex(dis_functions_source) +item(tt(dis_functions_source))( +Like tt(functions_source) but for disabled functions. +) vindex(builtins) item(tt(builtins))( This associative array gives information about the builtin commands @@ -202,10 +226,13 @@ defined. The line number is the line where the `tt(function) var(name)' or `var(name) tt(LPAR()RPAR())' started. In the case of an autoloaded function the line number is reported as zero. The format of each element is var(filename)tt(:)var(lineno). + For functions autoloaded from a file in native zsh format, where only the body of the function occurs in the file, or for files that have been executed by the tt(source) or `tt(.)' builtins, the trace information is -shown as var(filename)tt(:)var(0), since the entire file is the definition. +shown as var(filename)tt(:)var(0), since the entire file is the +definition. The source file name is resolved to an absolute path when +the function is loaded or the path to it otherwise resolved. Most users will be interested in the information in the tt(funcfiletrace) array instead. diff --git a/Doc/Zsh/mod_sched.yo b/Doc/Zsh/mod_sched.yo index 1350b9e4c..30b08a3ff 100644 --- a/Doc/Zsh/mod_sched.yo +++ b/Doc/Zsh/mod_sched.yo @@ -40,6 +40,11 @@ afterwards. This should be used with any scheduled event that produces visible output to the terminal; it is not needed, for example, with output that updates a terminal emulator's title bar. +To effect changes to the editor buffer when an event executes, use the +`tt(zle)' command with no arguments to test whether the editor is active, +and if it is, then use `tt(zle )var(widget)' to access the editor via +the named var(widget). + The tt(sched) builtin is not made available by default when the shell starts in a mode emulating another shell. It can be made available with the command `tt(zmodload -F zsh/sched b:sched)'. diff --git a/Doc/Zsh/mod_zleparameter.yo b/Doc/Zsh/mod_zleparameter.yo index 03d504724..76d23ba2a 100644 --- a/Doc/Zsh/mod_zleparameter.yo +++ b/Doc/Zsh/mod_zleparameter.yo @@ -15,14 +15,16 @@ This array contains the names of the keymaps currently defined. ) vindex(widgets) item(tt(widgets))( -This associative array contains one entry per widget defined. The name +This associative array contains one entry per widget. The name of the widget is the key and the value gives information about the -widget. It is either the string `tt(builtin)' for builtin widgets, a -string of the form `tt(user:)var(name)' for user-defined widgets, -where var(name) is the name of the shell function implementing the -widget, or it is a string of the form -`tt(completion:)var(type)tt(:)var(name)', for completion widgets. In -the last case var(type) is the name of the builtin widgets the +widget. It is either + the string `tt(builtin)' for builtin widgets, + a string of the form `tt(user:)var(name)' for user-defined widgets, + where var(name) is the name of the shell function implementing the widget, + a string of the form `tt(completion:)var(type)tt(:)var(name)' + for completion widgets, + or a null value if the widget is not yet fully defined. +In the penultimate case, var(type) is the name of the builtin widget the completion widget imitates in its behavior and var(name) is the name of the shell function implementing the completion widget. ) diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo index 2fce10780..cc6ae2a47 100644 --- a/Doc/Zsh/options.yo +++ b/Doc/Zsh/options.yo @@ -395,8 +395,9 @@ pindex(RECEXACT) pindex(NORECEXACT) cindex(completion, exact matches) item(tt(REC_EXACT) (tt(-S)))( -In completion, recognize exact matches even -if they are ambiguous. +If the string on the command line exactly matches one of the possible +completions, it is accepted, even if there is another completion (i.e. that +string with something else added) that also matches. ) enditem() @@ -722,9 +723,10 @@ pindex(REMATCHPCRE) pindex(NOREMATCHPCRE) cindex(regexp, PCRE) cindex(PCRE, regexp) -item(tt(REMATCH_PCRE) <Z>)( +item(tt(REMATCH_PCRE))( If set, regular expression matching with the tt(=~) operator will use -Perl-Compatible Regular Expressions from the PCRE library, if available. +Perl-Compatible Regular Expressions from the PCRE library. +(The tt(zsh/pcre) module must be available.) If not set, regular expressions will use the extended regexp syntax provided by the system libraries. ) @@ -768,6 +770,37 @@ global from within a function using tt(typeset -g) do not cause a warning. Note that there is no warning when a local parameter is assigned to in a nested function, which may also indicate an error. ) +pindex(WARN_NESTED_VAR) +pindex(NO_WARN_NESTED_VAR) +pindex(WARNNESTEDVAR) +pindex(NO_WARNNESTEDVAR) +cindex(parameters, warning when setting in enclosing scope) +item(tt(WARN_NESTED_VAR))( +Print a warning message when an existing parameter from an +enclosing function scope, or global, is set in a function +by an assignment or in math context. Assignment to shell +special parameters does not cause a warning. This is the companion +to tt(WARN_CREATE_GLOBAL) as in this case the warning is only +printed when a parameter is em(not) created. Where possible, +use of tt(typeset -g) to set the parameter suppresses the error, +but note that this needs to be used every time the parameter is set. +To restrict the effect of this option to a single function scope, +use `tt(functions -W)'. + +For example, the following code produces a warning for the assignment +inside the function tt(nested) as that overrides the value within +tt(toplevel) + +example(toplevel+LPAR()RPAR() { + local foo="in fn" + nested +} +nested+LPAR()RPAR() { + foo="in nested" +} +setopt warn_nested_var +toplevel) +) enditem() subsect(History) @@ -1539,6 +1572,36 @@ enditem() subsect(Scripts and Functions) startitem() +pindex(ALIAS_FUNC_DEF) +pindex(NO_ALIAS_FUNC_DEF) +pindex(ALIASFUNCDEF) +pindex(NOALIASFUNCDEF) +cindex(functions, defining with expanded aliases) +cindex(aliases, expanding in function definition) +item(tt(ALIAS_FUNC_DEF) <S>)( +By default, zsh does not allow the definition of functions using +the `var(name) tt(LPAR()RPAR())' syntax if var(name) was expanded as an +alias: this causes an error. This is usually the desired behaviour, as +otherwise the combination of an alias and a function based on the same +definition can easily cause problems. + +When this option is set, aliases can be used for defining functions. + +For example, consider the following definitions as they might +occur in a startup file. + +example(alias foo=bar +foo+LPAR()RPAR() { + print This probably does not do what you expect. +}) + +Here, tt(foo) is expanded as an alias to tt(bar) before the +tt(LPAR()RPAR()) is encountered, so the function defined would be named +tt(bar). By default this is instead an error in native mode. Note that +quoting any part of the function name, or using the keyword +tt(function), avoids the problem, so is recommended when the function +name can also be an alias. +) pindex(C_BASES) pindex(NO_C_BASES) pindex(CBASES) @@ -1598,7 +1661,7 @@ skipped. The option is restored after the trap exits. Exiting due to tt(ERR_EXIT) has certain interactions with asynchronous jobs noted in -ifzman(the section JOBS in in zmanref(zshmisc))\ +ifzman(the section JOBS in zmanref(zshmisc))\ ifnzman(noderef(Jobs & Signals)). ) pindex(ERR_RETURN) @@ -1929,7 +1992,8 @@ Emulate bf(ksh) array handling as closely as possible. If this option is set, array elements are numbered from zero, an array parameter without subscript refers to the first element instead of the whole array, and braces are required to delimit a subscript (`tt(${path[2]})' rather -than just `tt($path[2])'). +than just `tt($path[2])') or to apply modifiers to any parameter +(`tt(${PWD:h})' rather than `tt($PWD:h)'). ) pindex(KSH_AUTOLOAD) pindex(NO_KSH_AUTOLOAD) diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo index d23c459a0..905e92d22 100644 --- a/Doc/Zsh/params.yo +++ b/Doc/Zsh/params.yo @@ -1059,7 +1059,8 @@ If the tt(ENV) environment variable is set when zsh is invoked as tt(sh) or tt(ksh), tt($ENV) is sourced after the profile scripts. The value of tt(ENV) is subjected to parameter expansion, command substitution, and arithmetic expansion before being interpreted as a pathname. Note that -tt(ENV) is em(not) used unless zsh is emulating bf(sh) or bf(ksh). +tt(ENV) is em(not) used unless the shell is interactive and zsh is +emulating bf(sh) or bf(ksh). ) vindex(FCEDIT) item(tt(FCEDIT))( @@ -1390,6 +1391,20 @@ item(tt(READNULLCMD) <S>)( The command name to assume if a single input redirection is specified with no command. Defaults to tt(more). ) +vindex(REPORTMEMORY) +item(tt(REPORTMEMORY))( +If nonnegative, commands whose maximum resident set size (roughly +speaking, main memory usage) in megabytes is greater than this +value have timing statistics reported. The format used to output +statistics is the value of the tt(TIMEFMT) parameter, which is the same +as for the tt(REPORTTIME) variable and the tt(time) builtin; note that +by default this does not output memory usage. Appending +tt(" max RSS %M") to the value of tt(TIMEFMT) causes it to output the +value that triggered the report. If tt(REPORTTIME) is also in use, +at most a single report is printed for both triggers. This feature +requires the tt(getrusage+LPAR()RPAR()) system call, commonly supported by +modern Unix-like systems. +) vindex(REPORTTIME) item(tt(REPORTTIME))( If nonnegative, commands whose combined user and system execution times @@ -1443,6 +1458,14 @@ The prompt used for spelling correction. The sequence `tt(%R)' expands to the string which presumably needs spelling correction, and `tt(%r)' expands to the proposed correction. All other prompt escapes are also allowed. + +The actions available at the prompt are tt([nyae]): +startsitem() +sitem(tt(n) +LPAR()`no'+RPAR() +LPAR()default+RPAR())(Discard the correction and run the command.) +sitem(tt(y) +LPAR()`yes'+RPAR())(Make the correction and run the command.) +sitem(tt(a) +LPAR()`abort'+RPAR())(Discard the entire command line without running it.) +sitem(tt(e) +LPAR()`edit'+RPAR())(Resume editing the command line.) +endsitem() ) vindex(STTY) item(tt(STTY))( @@ -1470,10 +1493,20 @@ take effect. ) vindex(TERMINFO) item(tt(TERMINFO) <S>)( -A reference to a compiled description of the terminal, used by the -`terminfo' library when the system has it; see manref(terminfo)(5). -If set, this causes the shell to reinitialise the terminal, making -the workaround `tt(TERM=$TERM)' unnecessary. +A reference to your terminfo database, used by the `terminfo' library when the +system has it; see manref(terminfo)(5). +If set, this causes the shell to reinitialise the terminal, making the +workaround `tt(TERM=$TERM)' unnecessary. +) +vindex(TERMINFO_DIRS) +item(tt(TERMINFO_DIRS) <S>)( +A colon-seprarated list of terminfo databases, used by the `terminfo' library +when the system has it; see manref(terminfo)(5). This variable is only +used by certain terminal libraries, in particular ncurses; see +manref(terminfo)(5) to check support on your system. If set, this +causes the shell to reinitialise the terminal, making the workaround +`tt(TERM=$TERM)' unnecessary. Note that unlike other colon-separated +arrays this is not tied to a zsh array. ) vindex(TIMEFMT) item(tt(TIMEFMT))( @@ -1532,6 +1565,15 @@ A pathname prefix which the shell will use for all temporary files. Note that this should include an initial part for the file name as well as any directory names. The default is `tt(/tmp/zsh)'. ) +vindex(TMPSUFFIX) +item(tt(TMPSUFFIX))( +A filename suffix which the shell will use for temporary files created +by process substitutions (e.g., `tt(=LPAR()var(list)RPAR())'). +Note that the value should include a leading dot `tt(.)' if intended +to be interpreted as a file extension. The default is not to append +any suffix, thus this parameter should be assigned only when needed +and then unset again. +) vindex(watch) vindex(WATCH) item(tt(watch) <S> <Z> (tt(WATCH) <S>))( diff --git a/Doc/Zsh/restricted.yo b/Doc/Zsh/restricted.yo index b56b50c6f..6cf9b36b5 100644 --- a/Doc/Zsh/restricted.yo +++ b/Doc/Zsh/restricted.yo @@ -10,11 +10,11 @@ restricted mode: startitemize() itemiz(changing directories with the tt(cd) builtin) -itemiz(changing or unsetting the tt(PATH), tt(path), tt(MODULE_PATH), -tt(module_path), tt(SHELL), tt(HISTFILE), tt(HISTSIZE), tt(GID), tt(EGID), -tt(UID), tt(EUID), tt(USERNAME), tt(LD_LIBRARY_PATH), -tt(LD_AOUT_LIBRARY_PATH), tt(LD_PRELOAD) and tt(LD_AOUT_PRELOAD) -parameters) +itemiz(changing or unsetting the tt(EGID), tt(EUID), tt(GID), +tt(HISTFILE), tt(HISTSIZE), tt(IFS), tt(LD_AOUT_LIBRARY_PATH), +tt(LD_AOUT_PRELOAD), tt(LD_LIBRARY_PATH), tt(LD_PRELOAD), +tt(MODULE_PATH), tt(module_path), tt(PATH), tt(path), tt(SHELL), +tt(UID) and tt(USERNAME) parameters) itemiz(specifying command names containing tt(/)) itemiz(specifying command pathnames using tt(hash)) itemiz(redirecting output to files) diff --git a/Doc/Zsh/roadmap.yo b/Doc/Zsh/roadmap.yo index bd064e2b2..94ef74d1f 100644 --- a/Doc/Zsh/roadmap.yo +++ b/Doc/Zsh/roadmap.yo @@ -139,6 +139,9 @@ startitem() item(tt(**))( for matching over multiple directories ) +item(tt(|))( +for matching either of two alternatives +) item(tt(~), tt(^))( the ability to exclude patterns from matching when the tt(EXTENDED_GLOB) option is set diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo index 80d3f39d8..b65e3be64 100644 --- a/Doc/Zsh/zle.yo +++ b/Doc/Zsh/zle.yo @@ -479,6 +479,13 @@ tt(kill) for indicating that text has been killed into the cutbuffer. When repeatedly invoking a kill widget, text is appended to the cutbuffer instead of replacing it, but when wrapping such widgets, it is necessary to call `tt(zle -f kill)' to retain this effect. + +tt(vichange) for indicating that the widget represents a vi change that +can be repeated as a whole with `tt(vi-repeat-change)'. The flag should be set +early in the function before inspecting the value of tt(NUMERIC) or invoking +other widgets. This has no effect for a widget invoked from insert mode. If +insert mode is active when the widget finishes, the change extends until next +returning to command mode. ) cindex(completion widgets, creating) item(tt(-C) var(widget) var(completion-widget) var(function))( @@ -857,6 +864,12 @@ vindex(KEYS) item(tt(KEYS) (scalar))( The keys typed to invoke this widget, as a literal string; read-only. ) +vindex(KEYS_QUEUED_COUNT) +item(tt(KEYS_QUEUED_COUNT) (integer))( +The number of bytes pushed back to the input queue and therefore +available for reading immediately before any I/O is done; read-only. +See also tt(PENDING); the two values are distinct. +) vindex(killring) item(tt(killring) (array))( The array of previously killed items, with the most recently killed first. @@ -896,7 +909,7 @@ vindex(MARK) item(tt(MARK) (integer))( Like tt(CURSOR), but for the mark. With vi-mode operators that wait for a movement command to select a region of text, setting tt(MARK) allows -the selection to extend in both directions from the the initial cursor +the selection to extend in both directions from the initial cursor position. ) vindex(NUMERIC) @@ -912,7 +925,8 @@ item(tt(PENDING) (integer))( The number of bytes pending for input, i.e. the number of bytes which have already been typed and can immediately be read. On systems where the shell is not able to get this information, this parameter will always have a -value of zero. Read-only. +value of zero. Read-only. See also tt(KEYS_QUEUED_COUNT); the two +values are distinct. ) vindex(PREBUFFER) item(tt(PREBUFFER) (scalar))( @@ -991,6 +1005,12 @@ and tt(zle_highlight); see ifzman(the section CHARACTER HIGHLIGHTING below)\ ifnzman(noderef(Character Highlighting)) for details. ) +vindex(registers) +item(tt(registers) (associative array))( +The contents of each of the vi register buffers. These are +typically set using tt(vi-set-buffer) followed by a delete, change or +yank command. +) vindex(SUFFIX_ACTIVE) vindex(SUFFIX_START) vindex(SUFFIX_END) @@ -1781,6 +1801,13 @@ tindex(down-case-word) item(tt(down-case-word) (tt(ESC-L ESC-l)) (unbound) (unbound))( Convert the current word to all lowercase and move past it. ) +tindex(vi-down-case) +item(tt(vi-down-case) (unbound) (tt(gu)) (unbound))( +Read a movement command from the keyboard, and convert all characters +from the cursor position to the endpoint of the movement to lowercase. +If the movement command is tt(vi-down-case), swap the case of all +characters on the current line. +) tindex(kill-word) item(tt(kill-word) (tt(ESC-D ESC-d)) (unbound) (unbound))( Kill the current word. @@ -1941,11 +1968,27 @@ to the left. tindex(transpose-words) item(tt(transpose-words) (tt(ESC-T ESC-t)) (unbound) (unbound))( Exchange the current word with the one before it. + +With a positive numeric argument em(N), the word around the cursor, or +following it if the cursor is between words, is transposed with the +preceding em(N) words. The cursor is put at the end of the resulting +group of words. + +With a negative numeric argument em(-N), the effect is the same as using +a positive argument em(N) except that the original cursor position is +retained, regardless of how the words are rearranged. ) tindex(vi-unindent) item(tt(vi-unindent) (unbound) (tt(<)) (unbound))( Unindent a number of lines. ) +tindex(vi-up-case) +item(tt(vi-up-case) (unbound) (tt(gU)) (unbound))( +Read a movement command from the keyboard, and convert all characters +from the cursor position to the endpoint of the movement to lowercase. +If the movement command is tt(vi-up-case), swap the case of all +characters on the current line. +) tindex(up-case-word) item(tt(up-case-word) (tt(ESC-U ESC-u)) (unbound) (unbound))( Convert the current word to all caps and move past it. @@ -2152,10 +2195,18 @@ item(tt(bracketed-paste))( This widget is invoked when text is pasted to the terminal emulator. It is not intended to be bound to actual keys but instead to the special sequence generated by the terminal emulator when text is pasted. + +When invoked interactively, the pasted text is inserted to the buffer +and placed in the cutbuffer. If a numeric argument is given, shell quoting will be applied to the -pasted text before it is inserted. When called from a widget function, -an argument can be given to specify a variable to which pasted text is -assigned. +pasted text before it is inserted. + +When a named buffer is specified with tt(vi-set-buffer) (tt("x)), +the pasted text is stored in that named buffer but not inserted. + +When called from a widget function as `tt(bracketed-paste) var(name)`, the +pasted text is assigned to the variable var(name) and no other processing is +done. See also the tt(zle_bracketed_paste) parameter. ) @@ -2193,8 +2244,12 @@ point and mark are not swapped. ) tindex(execute-named-cmd) item(tt(execute-named-cmd) (tt(ESC-x)) (tt(:)) (unbound))( -Read the name of an editor command and -execute it. A restricted set of editing functions is available in the +Read the name of an editor command and execute it. Aliasing this +widget with `tt(zle -A)' or replacing it with `tt(zle -N)' has no +effect when interpreting key bindings, but `tt(zle execute-named-cmd)' +will invoke such an alias or replacement. + +A restricted set of editing functions is available in the mini-buffer. Keys are looked up in the special tt(command) keymap, and if not found there in the main keymap. An interrupt signal, as defined by the stty setting, will @@ -2235,7 +2290,8 @@ tindex(execute-last-named-cmd) item(tt(execute-last-named-cmd) (tt(ESC-z)) (unbound) (unbound))( Redo the last function executed with tt(execute-named-cmd). -Currently this command may not be redefined or called by name. +Like tt(execute-named-cmd), this command may not be redefined, +but it may be called by name. ) tindex(get-line) item(tt(get-line) (tt(ESC-G ESC-g)) (unbound) (unbound))( @@ -2381,7 +2437,7 @@ concerned replaces the previous contents of the specified buffer. If a named buffer is specified using a capital, the newly cut text is appended to the buffer instead of overwriting it. When using the tt("_) buffer, nothing happens. This can be useful for deleting text without -affecting the normal registers. +affecting any buffers. If no buffer is specified for a cut or change command, tt("1) is used, and the contents of tt("1) to tt("8) are each shifted along one buffer; @@ -2557,15 +2613,14 @@ When one of the incremental history search widgets is active, the area of the command line matched by the search string or pattern. ) item(tt(region))( -The region between the cursor (point) and the mark as set with -tt(set-mark-command). The region is only highlighted if it is active, -which is the case if tt(set-mark-command) or tt(exchange-point-and-mark) -has been called and the line has not been subsequently modified. The -region can be deactivated by calling tt(set-mark-command) with a -negative numeric argument, or reactivated by calling -tt(exchange-point-and-mark) with a zero numeric argument. Note -that whether or not the region is active has no effect on its -use within widgets, it simply determines whether it is highlighted. +The currently selected text. In emacs terminology, this is referred to as +the region and is bounded by the cursor (point) and the mark. The region +is only highlighted if it is active, which is the case after the mark +is modified with tt(set-mark-command) or tt(exchange-point-and-mark). +Note that whether or not the region is active has no effect on its +use within emacs style widgets, it simply determines whether it is +highlighted. In vi mode, the region corresponds to selected text in +visual mode. ) cindex(special characters, highlighting) cindex(highlighting, special characters) |