diff options
Diffstat (limited to 'Doc/Zsh')
| -rw-r--r-- | Doc/Zsh/builtins.yo | 116 | ||||
| -rw-r--r-- | Doc/Zsh/compsys.yo | 117 | ||||
| -rw-r--r-- | Doc/Zsh/contrib.yo | 192 | ||||
| -rw-r--r-- | Doc/Zsh/expn.yo | 39 | ||||
| -rw-r--r-- | Doc/Zsh/grammar.yo | 3 | ||||
| -rw-r--r-- | Doc/Zsh/jobs.yo | 6 | ||||
| -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_zutil.yo | 2 | ||||
| -rw-r--r-- | Doc/Zsh/options.yo | 75 | ||||
| -rw-r--r-- | Doc/Zsh/params.yo | 4 | ||||
| -rw-r--r-- | Doc/Zsh/roadmap.yo | 3 | ||||
| -rw-r--r-- | Doc/Zsh/seealso.yo | 6 | ||||
| -rw-r--r-- | Doc/Zsh/zle.yo | 21 |
16 files changed, 531 insertions, 116 deletions
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index 7b04d0648..3afe990ba 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)) @@ -634,7 +667,10 @@ if there are no var(args) or they contain no commands (i.e. are an empty string or whitespace) the return status is zero. ) item(tt(exec) [ tt(-cl) ] [ tt(-a) var(argv0) ] [ var(command) [ var(arg) ... ] ])( -Replace the current shell with an external var(command) rather than forking. +Replace the current shell with var(command) rather than forking. +If var(command) is a shell builtin command or a shell function, +the shell executes it, then immediately exits. + With tt(-c) clear the environment; with tt(-l) prepend tt(-) to the tt(argv[0]) string of the command executed (to simulate a login shell); with tt(-a) var(argv0) set the tt(argv[0]) string of the command @@ -642,6 +678,12 @@ executed. See ifzman(the section `Precommand Modifiers' in zmanref(zshmisc))\ ifnzman(noderef(Precommand Modifiers)). +If the option tt(POSIX_BUILTINS) is set, var(command) is never +interpreted as a shell builtin command or shell function. This +means further precommand modifiers such as tt(builtin) and +tt(noglob) are also not interpreted within the shell. Hence +var(command) is always found by searching the command path. + cindex(redirection, current shell's I/O) If var(command) is omitted but any redirections are specified, then the redirections will take effect in the current shell. @@ -806,18 +848,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 +891,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 +905,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 +1261,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). @@ -2034,7 +2099,9 @@ 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 @@ -2496,7 +2563,7 @@ zlecmd(zle) findex(zmodload) cindex(modules, loading) cindex(loading modules) -xitem(tt(zmodload) [ tt(-dL) ] [ ... ]) +xitem(tt(zmodload) [ tt(-dL) ] [ tt(-s) ] [ ... ]) xitem(tt(zmodload -F) [ tt(-alLme) tt(-P) var(param) ] var(module) [ [tt(PLUS()-)]var(feature) ... ]) xitem(tt(zmodload -e) [ tt(-A) ] [ ... ]) xitem(tt(zmodload) [ tt(-a) [ tt(-bcpf) [ tt(-I) ] ] ] [ tt(-iL) ] ...) @@ -2515,7 +2582,7 @@ printed. The tt(-L) option causes this list to be in the form of a series of tt(zmodload) commands. Forms with arguments are: startitem() -xitem(tt(zmodload) [ tt(-i) ] var(name) ... ) +xitem(tt(zmodload) [ tt(-is) ] var(name) ... ) item(tt(zmodload) tt(-u) [ tt(-i) ] var(name) ...)( In the simplest case, tt(zmodload) loads a binary module. The module must be in a file with a name consisting of the specified var(name) followed by @@ -2523,9 +2590,7 @@ a standard suffix, usually `tt(.so)' (`tt(.sl)' on HPUX). If the module to be loaded is already loaded the duplicate module is ignored. If tt(zmodload) detects an inconsistency, such as an invalid module name or circular dependency list, the current code block is -aborted. Hence `tt(zmodload) var(module) tt(2>/dev/null)' is sufficient -to test whether a module is available. -If it is available, the module is loaded if necessary, while if it +aborted. If it is available, the module is loaded if necessary, while if it is not available, non-zero status is silently returned. The option tt(-i) is accepted for compatibility but has no effect. @@ -2538,6 +2603,11 @@ If the module supports features (see below), tt(zmodload) tries to enable all features when loading a module. If the module was successfully loaded but not all features could be enabled, tt(zmodload) returns status 2. +If the option tt(-s) is given, no error is printed if the module was not +available (though other errors indicating a problem with the module are +printed). The return status indicates if the module was loaded. This +is appropriate if the caller considers the module optional. + With tt(-u), tt(zmodload) unloads modules. The same var(name) must be given that was given when the module was loaded, but it is not necessary for the module to exist in the file system. diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 953d51c4c..36afd7305 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -1158,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'. ) @@ -1428,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. @@ -2196,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)'. @@ -3007,6 +3014,22 @@ tt(-n), tt(-F), tt(-X) are passed to tt(compadd). See tt(_description) for a description of var(tag) and var(descr). ) +findex(_cmdambivalent) +item(tt(_cmdambivalent))( +Completes the remaining positional arguments as an external command. +The external command and its arguments are completed as separate arguments +(in a manner appropriate for completing tt(/usr/bin/env)) +if there are two or more remaining positional arguments on the command line, +and as a quoted command string (in the manner of tt(system+LPAR()...+RPAR())) otherwise. +See also tt(_cmdstring) and tt(_precommand). + +This function takes no arguments. +) +findex(_cmdstring) +item(tt(_cmdstring))( +Completes an external command as a single argument, as for +tt(system+LPAR()...+RPAR()). +) findex(_complete) item(tt(_complete))( This completer generates all possible completions in a context-sensitive @@ -3207,6 +3230,11 @@ tt(old-menu), see ifzman(the section `Completion System Configuration' above)\ ifnzman(noderef(Completion System Configuration)). ) +findex(_precommand) +item(tt(_precommand))( +Complete an external command in word-separated arguments, as for +tt(exec) and tt(/usr/bin/env). +) findex(_prefix) item(tt(_prefix))( This completer can be used to try completion with the suffix (everything @@ -3573,13 +3601,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. @@ -3997,18 +4023,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 \ @@ -4024,28 +4080,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. diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index f764eb7c6..35ce91575 100644 --- a/Doc/Zsh/contrib.yo +++ b/Doc/Zsh/contrib.yo @@ -862,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): @@ -872,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 @@ -935,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). @@ -944,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 @@ -1056,17 +1076,17 @@ example(zstyle ':vcs_info:*' disable-patterns "${+LPAR()b+RPAR()HOME}/.zsh+LPAR( 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))( @@ -1197,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) @@ -1207,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))( @@ -1277,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. @@ -1288,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() @@ -1321,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), @@ -1331,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 @@ -1346,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 @@ -1366,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) @@ -1421,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() @@ -1429,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. ) @@ -1438,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))( @@ -1447,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))( @@ -1473,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() @@ -1490,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 @@ -1597,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 @@ -1614,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 @@ -1691,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. @@ -1719,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): @@ -1850,8 +1920,9 @@ subsect(Installation) You should make sure all the functions from the tt(Functions/Prompts) directory of the source distribution are available; they all begin with the string `tt(prompt_)' except for the special function`tt(promptinit)'. -You also need the `tt(colors)' function from tt(Functions/Misc). All of -these functions may already have been installed on your system; if not, +You also need the `tt(colors)' and `tt(add-zsh-hook)' functions from +tt(Functions/Misc). +All these functions may already be installed on your system; if not, you will need to find them and copy them. The directory should appear as one of the elements of the tt(fpath) array (this should already be the case if they were installed), and at least the function tt(promptinit) @@ -1905,6 +1976,75 @@ normally call a theme's setup function directly. ) enditem() +subsect(Utility Themes) + +startitem() +item(tt(prompt off))( +The theme `tt(off)' sets all the prompt variables to minimal values with +no special effects. +) +item(tt(prompt default))( +The theme `tt(default)' sets all prompt variables to the same state as +if an interactive zsh was started with no initialization files. +) +item(tt(prompt restore))( +The special theme `tt(restore)' erases all theme settings and sets prompt +variables to their state before the first time the `tt(prompt)' function +was run, provided each theme has properly defined its cleanup (see below). + +Note that you can undo `tt(prompt off)' and `tt(prompt default)' with +`tt(prompt restore)', but a second restore does not undo the first. +) +enditem() + +subsect(Writing Themes) + +The first step for adding your own theme is to choose a name for it, +and create a file `tt(prompt_var(name)_setup)' in a directory in your +tt(fpath), such as tt(~/myfns) in the example above. The file should +at minimum contain assignments for the prompt variables that your +theme wishes to modify. By convention, themes use tt(PS1), tt(PS2), +tt(RPS1), etc., rather than the longer tt(PROMPT) and tt(RPROMPT). + +The file is autoloaded as a function in the current shell context, so +it may contain any necessary commands to customize your theme, including +defining additional functions. To make some complex tasks easier, your +setup function may also do any of the following: + +startitem() +item(Assign tt(prompt_opts))( +The array tt(prompt_opts) may be assigned any of tt("bang"), tt("cr"), +tt("percent"), tt("sp"), and/or tt("subst") as values. The corresponding +setopts (tt(promptbang), etc.) are turned on, all other prompt-related +options are turned off. The tt(prompt_opts) array preserves setopts even +beyond the scope of tt(localoptions), should your function need that. +) +item(Modify precmd and preexec)( +Use of tt(add-zsh-hook) is recommended. The tt(precmd) and tt(preexec) +hooks are automatically adjusted if the prompt theme changes or is +disabled. +) +item(Declare cleanup)( +If your function makes any other changes that should be undone when the +theme is disabled, your setup function may call +example(prompt_cleanup var(command)) +where var(command) should be suitably quoted. If your theme is ever +disabled or replaced by another, var(command) is executed with tt(eval). +You may declare more than one such cleanup hook. +) +item(Define preview)( +Define or autoload a function tt(prompt_var(name)_preview) to display +a simulated version of your prompt. A simple default previewer is +defined by tt(promptinit) for themes that do not define their own. +This preview function is called by `tt(prompt -p)'. +) +item(Provide help)( +Define or autoload a function tt(prompt_var(name)_help) to display +documentation or help text for your theme. +This help function is called by `tt(prompt -h)'. +) +enditem() + texinode(ZLE Functions)(Exception Handling)(Prompt Themes)(User Contributions) sect(ZLE Functions) diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo index cf4f69ea2..a61738f84 100644 --- a/Doc/Zsh/expn.yo +++ b/Doc/Zsh/expn.yo @@ -21,9 +21,12 @@ xitem(em(Parameter Expansion)) xitem(em(Command Substitution)) xitem(em(Arithmetic Expansion)) item(em(Brace Expansion))( -These five are performed in one step in left-to-right fashion. After -these expansions, all unquoted occurrences of the characters `tt(\)', -`tt(')' and `tt(")' are removed. +These five are performed in left-to-right fashion. On each argument, +any of the five steps that are needed are performed one after the other. +Hence, for example, all the parts of parameter expansion are completed +before command substitution is started. After these expansions, all +unquoted occurrences of the characters `tt(\)',`tt(')' and `tt(")' are +removed. ) item(em(Filename Expansion))( If the tt(SH_FILE_EXPANSION) option is set, the order of expansion is @@ -856,8 +859,9 @@ all arguments to be removed. Internally, each such expansion is converted into the equivalent list for brace expansion. E.g., tt(${^var}) becomes tt({$var[1],$var[2],)...tt(}), and is processed as described in -noderef(Brace Expansion) below. -If word splitting is also in effect the +noderef(Brace Expansion) below: note, however, the expansion +happens immediately, with any explicit brace expansion +happening later. If word splitting is also in effect the tt($var[)var(N)tt(]) may themselves be split into different list elements. ) @@ -955,15 +959,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 @@ -1039,7 +1053,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. @@ -2100,6 +2116,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 6262dd244..70559f2d8 100644 --- a/Doc/Zsh/jobs.yo +++ b/Doc/Zsh/jobs.yo @@ -49,6 +49,12 @@ in the parent shell. Thus the behaviour is different from the case where the function was never suspended. Zsh is different from many other shells in this regard. +One additional side effect is that use of tt(disown) with a job +created by suspending shell code in this fashion is delayed: the +job can only be disowned once any process started from the parent +shell has terminated. At that point, the disowned job disappears +silently from the job list. + The same behaviour is found when the shell is executing code as the right hand side of a pipeline or any complex shell construct such as tt(if), tt(for), etc., in order that the entire block of code 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_zutil.yo b/Doc/Zsh/mod_zutil.yo index dc17161f1..8331eabb7 100644 --- a/Doc/Zsh/mod_zutil.yo +++ b/Doc/Zsh/mod_zutil.yo @@ -179,7 +179,7 @@ item(tt(zregexparse))( This implements some internals of the tt(_regex_arguments) function. ) findex(zparseopts) -item(tt(zparseopts) [ tt(-D) tt(-K) tt(-M) tt(-E) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] var(spec) ...)( +item(tt(zparseopts) [ tt(-D) tt(-K) tt(-M) tt(-E) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] [ tt(-) ] var(spec) ...)( This builtin simplifies the parsing of options in positional parameters, i.e. the set of arguments given by tt($*). Each var(spec) describes one option and must be of the form `var(opt)[tt(=)var(array)]'. If an option diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo index f68a945ec..70092d681 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) @@ -2077,6 +2140,10 @@ In addition, various error conditions associated with the above builtins or tt(exec) cause a non-interactive shell to exit and an interactive shell to return to its top-level processing. +Furthermore, functions and shell builtins are not executed after +an tt(exec) prefix; the command to be executed must be an external +command found in the path. + Furthermore, the tt(getopts) builtin behaves in a POSIX-compatible fashion in that the associated variable tt(OPTIND) is not made local to functions. diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo index 905e92d22..817496b8a 100644 --- a/Doc/Zsh/params.yo +++ b/Doc/Zsh/params.yo @@ -952,8 +952,8 @@ of zsh. ) vindex(ZSH_PATCHLEVEL) item(tt(ZSH_PATCHLEVEL))( -The revision string for the version number of the ChangeLog file -in the zsh distribution. This is most useful in order to keep +The output of `tt(git describe --tags --long)' for the zsh repository +used to build the shell. This is most useful in order to keep track of versions of the shell during development between releases; hence most users should not use it and should instead rely on tt($ZSH_VERSION). 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/seealso.yo b/Doc/Zsh/seealso.yo index 73c7fa673..7a78c481b 100644 --- a/Doc/Zsh/seealso.yo +++ b/Doc/Zsh/seealso.yo @@ -8,15 +8,21 @@ manref(bash)(1), manref(ksh)(1)\ ifzshone(\ , +zmanref(zshall), zmanref(zshbuiltins), +zmanref(zshcalsys), zmanref(zshcompwid), zmanref(zshcompsys), zmanref(zshcompctl), +zmanref(zshcontrib), zmanref(zshexpn), zmanref(zshmisc), zmanref(zshmodules), zmanref(zshoptions), zmanref(zshparam), +zmanref(zshroadmap), +zmanref(zshtcpsys), +zmanref(zshzftpsys), zmanref(zshzle)\ )\ diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo index d68365b94..bd0252f6e 100644 --- a/Doc/Zsh/zle.yo +++ b/Doc/Zsh/zle.yo @@ -750,12 +750,12 @@ sect(User-Defined Widgets) cindex(widgets, user-defined) User-defined widgets, being implemented as shell functions, can execute any normal shell command. They can also run other widgets -(whether built-in or user-defined) using the tt(zle) builtin command. -The standard input of the function is closed to prevent external commands -from unintentionally blocking ZLE by reading from the terminal, but -tt(read -k) or tt(read -q) can be used to read characters. Finally, -they can examine and edit the ZLE buffer being edited by -reading and setting the special parameters described below. +(whether built-in or user-defined) using the tt(zle) builtin command. The +standard input of the function is redirected from /dev/null to prevent +external commands from unintentionally blocking ZLE by reading from the +terminal, but tt(read -k) or tt(read -q) can be used to read characters. +Finally, they can examine and edit the ZLE buffer being edited by reading +and setting the special parameters described below. cindex(parameters, editor) cindex(parameters, zle) @@ -864,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. @@ -919,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))( |