diff options
Diffstat (limited to 'Doc/Zsh')
| -rw-r--r-- | Doc/Zsh/arith.yo | 10 | ||||
| -rw-r--r-- | Doc/Zsh/builtins.yo | 30 | ||||
| -rw-r--r-- | Doc/Zsh/compsys.yo | 5 | ||||
| -rw-r--r-- | Doc/Zsh/compwid.yo | 6 | ||||
| -rw-r--r-- | Doc/Zsh/contrib.yo | 383 | ||||
| -rw-r--r-- | Doc/Zsh/expn.yo | 100 | ||||
| -rw-r--r-- | Doc/Zsh/func.yo | 3 | ||||
| -rw-r--r-- | Doc/Zsh/grammar.yo | 3 | ||||
| -rw-r--r-- | Doc/Zsh/manual.yo | 1 | ||||
| -rw-r--r-- | Doc/Zsh/mod_parameter.yo | 6 | ||||
| -rw-r--r-- | Doc/Zsh/mod_pcre.yo | 8 | ||||
| -rw-r--r-- | Doc/Zsh/mod_private.yo | 89 | ||||
| -rw-r--r-- | Doc/Zsh/mod_socket.yo | 5 | ||||
| -rw-r--r-- | Doc/Zsh/options.yo | 28 | ||||
| -rw-r--r-- | Doc/Zsh/params.yo | 17 | ||||
| -rw-r--r-- | Doc/Zsh/zle.yo | 34 |
16 files changed, 646 insertions, 82 deletions
diff --git a/Doc/Zsh/arith.yo b/Doc/Zsh/arith.yo index 1dcd18cad..c152bf48d 100644 --- a/Doc/Zsh/arith.yo +++ b/Doc/Zsh/arith.yo @@ -215,7 +215,7 @@ findex(integer, use of) Arithmetic evaluation is performed on the value of each assignment to a named parameter declared integer in this manner. Assigning a floating point number to an integer results in -rounding down to the next integer. +rounding towards zero. cindex(parameters, floating point) cindex(floating point parameters) @@ -230,16 +230,16 @@ format. Promotion of integer to floating point values is performed where necessary. In addition, if any operator which requires an integer -(`tt(~)', `tt(&)', `tt(|)', `tt(^)', `tt(%)', `tt(<<)', `tt(>>)' and their -equivalents with assignment) is given a floating point argument, it will be -silently rounded down to the next integer. +(`tt(&)', `tt(|)', `tt(^)', `tt(<<)', `tt(>>)' and their equivalents with +assignment) is given a floating point argument, it will be silently rounded +towards zero except for `tt(~)' which rounds down. Users should beware that, in common with many other programming languages but not software designed for calculation, the evaluation of an expression in zsh is taken a term at a time and promotion of integers to floating point does not occur in terms only containing integers. A typical result of this is that a division such as tt(6/8) is truncated, -in this being rounded down to 0. The tt(FORCE_FLOAT) shell option can +in this being rounded towards 0. The tt(FORCE_FLOAT) shell option can be used in scripts or functions where floating point evaluation is required throughout. diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index 5bbe7e70b..49806e4d8 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -144,8 +144,12 @@ findex(autoload) cindex(functions, autoloading) cindex(autoloading functions) item(tt(autoload) [ {tt(PLUS())|tt(-)}tt(TUXkmtz) ] [ tt(-w) ] [ var(name) ... ])( +vindex(fpath, searching) Equivalent to tt(functions -u), with the exception of tt(-X)/tt(+X) and -tt(-w). +tt(-w). 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 @@ -473,7 +477,7 @@ cindex(compatibility, csh) cindex(sh, compatibility) cindex(ksh, compatibility) cindex(csh, compatibility) -item(tt(emulate) [ tt(-LR) ] [ {tt(zsh)|tt(sh)|tt(ksh)|tt(csh)} [ var(flags) ... ] ])( +item(tt(emulate) [ tt(-lLR) ] [ {tt(zsh)|tt(sh)|tt(ksh)|tt(csh)} [ var(flags) ... ] ])( Without any argument print current emulation mode. With single argument set up zsh options to emulate the specified shell @@ -514,6 +518,14 @@ function, if any; normally these options are turned off in all emulation modes except tt(ksh). The tt(-L) switch is mutually exclusive with the use of tt(-c) in var(flags). +If there is a single argument and the tt(-l) switch is given, the +options that would be set or unset (the latter indicated with the prefix +`tt(no)') are listed. tt(-l) can be combined with tt(-L) or tt(-R) and +the list will be modified in the appropriate way. Note the list does +not depend on the current setting of options, i.e. it includes all +options that may in principle change, not just those that would actually +change. + The var(flags) may be any of the invocation-time flags described in ifnzman(noderef(Invocation))\ ifzman(the section INVOCATION in zmanref(zsh)), @@ -546,8 +558,7 @@ For example: example(emulate sh -c 'fni+LPAR()RPAR() { setopt cshnullglob; } fno+LPAR()RPAR() { fni; }' -fno -) +fno) The two functions tt(fni) and tt(fno) are defined with sticky tt(sh) emulation. tt(fno) is then executed, causing options associated @@ -1981,12 +1992,8 @@ 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 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. The tt(fpath) -parameter will be searched to find the function definition when the -function is first referenced; see noderef(Functions). The tt(-k) and -tt(-z) flags make the function be loaded using ksh-style or zsh-style -autoloading respectively. If neither is given, the setting of the -tt(KSH_AUTOLOAD) option determines how the function is loaded. +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. @@ -2320,7 +2327,7 @@ item(tt(zcompile -t) var(file) [ var(name) ... ])( This builtin command can be used to compile functions or scripts, storing the compiled form in a file, and to examine files containing the compiled form. This allows faster autoloading of functions and -execution of scripts by avoiding parsing of the text when the files +sourcing of scripts by avoiding parsing of the text when the files are read. The first form (without the tt(-c), tt(-a) or tt(-t) options) creates a @@ -2338,6 +2345,7 @@ noderef(Functions) for a description of how autoloaded functions are searched. The extension tt(.zwc) stands for `zsh word code'. +vindex(fpath, with zcompile) If there is at least one var(name) argument, all the named files are compiled into the output var(file) given as the first argument. If var(file) does not end in tt(.zwc), this extension is automatically diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index d067795dd..d6b180301 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -3982,6 +3982,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 diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo index 40cabea88..c01763316 100644 --- a/Doc/Zsh/compwid.yo +++ b/Doc/Zsh/compwid.yo @@ -899,8 +899,8 @@ var(lanchor), the var(ranchor) only needs to match the trial completion string. The tt(b) and tt(B) forms are similar to tt(l) and tt(L) with an empty -anchor, but need to match only the beginning of the trial completion -or the word on the command line, respectively. +anchor, but need to match only the beginning of the word on the command line +or trial completion, respectively. ) xitem(tt(r:)var(lpat)tt(|)var(ranchor)tt(=)var(tpat)) xitem(tt(R:)var(lpat)tt(|)var(ranchor)tt(=)var(tpat)) @@ -911,7 +911,7 @@ item(tt(E:)var(lpat)tt(=)var(tpat))( As tt(l), tt(L), tt(b) and tt(B), with the difference that the command 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 trial completion or command line string. +match to the end of the command line or trial completion string. ) enditem() diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index 741d4ad07..07a5eb08e 100644 --- a/Doc/Zsh/contrib.yo +++ b/Doc/Zsh/contrib.yo @@ -12,6 +12,7 @@ such as shell functions, look for comments in the function source files. startmenu() menu(Utilities) menu(Recent Directories) +menu(Other Directory Functions) menu(Version Control Information) menu(Prompt Themes) menu(ZLE Functions) @@ -324,7 +325,7 @@ options tt(-Uz) are appropriate. ) enditem() -texinode(Recent Directories)(Version Control Information)(Utilities)(User Contributions) +texinode(Recent Directories)(Other Directory Functions)(Utilities)(User Contributions) cindex(recent directories, maintaining list of) cindex(directories, maintaining list of recent) findex(cdr) @@ -414,6 +415,18 @@ newlines, where I have in any case no sympathy); directories are in unabbreviated from and contain an absolute path, i.e. they start with tt(/). Usually the first entry should be left as the current directory. ) +item(tt(-p ')var(pattern)tt('))( +Prunes any items in the directory list that match the given extended glob +pattern; the pattern needs to be quoted from immediate expansion on the +command line. The pattern is matched against each completely expanded +file name in the list; the full string must match, so wildcards at the +end (e.g. tt('*removeme*')) are needed to remove entries with a given +substring. + +If output is to a terminal, then the function will print the new list +after pruning and prompt for confirmation by the user. This output and +confirmation step can be skipped by using tt(-P) instead of tt(-p). +) enditem() subsect(Configuration) @@ -585,7 +598,189 @@ avoid side effects if the change to the directory is to be invisible at the command line. See the contents of the function tt(chpwd_recent_dirs) for more details. -texinode(Version Control Information)(Prompt Themes)(Recent Directories)(User Contributions) +texinode(Other Directory Functions)(Version Control Information)(Recent Directories)(User Contributions) +cindex(directories, named, dynamic, helper function) +cindex(dynamic directory naming, helper function) +cindex(named directories, dynamic, helper function) +findex(zsh_directory_name_generic) +sect(Abbreviated dynamic references to directories) + +The dynamic directory naming system is described in the subsection +em(Dynamic named directories) of +ifzman(the section em(Filename Expansion) in zmanref(expn))\ +ifnzman(noderef(Filename Expansion)). In this, a reference to +tt(~[)var(...)tt(]) is expanded by a function found by the hooks +mechanism. + +The contributed function tt(zsh_directory_name_generic) provides a +system allowing the user to refer to directories with only a limited +amount of new code. It supports all three of the standard interfaces +for directory naming: converting from a name to a directory, converting +in the reverse direction to find a short name, and completion of names. + +The main feature of this function is a path-like syntax, +combining abbreviations at multiple levels separated by ":". +As an example, ~[g:p:s] might specify: +startitem() +item(tt(g))( +The top level directory for your git area. This first component +has to match, or the function will retrun indicating another +directory name hook function should be tried. +) +item(tt(p))( +The name of a project within your git area. +) +item(tt(s))( +The source area within that project. +) +enditem() +This allows you to collapse references to long hierarchies to a very +compact form, particularly if the hierarchies are similar across different +areas of the disk. + +Name components may be completed: if a description is shown at the top +of the list of completions, it includes the path to which previous +components expand, while the description for an individual completion +shows the path segment it would add. No additional configuration is +needed for this as the completion system is aware of the dynamic +directory name mechanism. + +subsect(Usage) + +To use the function, first define a wrapper function for your specific +case. We'll assume it's to be autoloaded. This can have any name but +we'll refer to it as zdn_mywrapper. This wrapper function will define +various variables and then call this function with the same arguments +that the wrapper function gets. This configuration is described below. + +Then arrange for the wrapper to be run as a zsh_directory_name hook: + +example(autoload -Uz add-zsh-hook zsh_diretory_name_generic zdn_mywrapper +add-zsh-hook -U zsh_directory_name zdn_mywrapper) + +subsect(Configuration) + +The wrapper function should define a local associative array zdn_top. +Alternatively, this can be set with a style called tt(mapping). The +context for the style is tt(:zdn:)var(wrapper-name) where +var(wrapper-name) is the function calling zsh_directory_name_generic; +for example: + +example(zstyle :zdn:zdn_mywrapper: mapping zdn_mywrapper_top) + +The keys in this associative array correspond to the first component of +the name. The values are matching directories. They may have an +optional suffix with a slash followed by a colon and the name of a +variable in the same format to give the next component. (The slash +before the colon is to disambiguate the case where a colon is needed in +the path for a drive. There is otherwise no syntax for escaping this, +so path components whose names start with a colon are not supported.) A +special component tt(:default:) specifies a variable in the form +tt(/:)var(var) (the path section is ignored and so is usually empty) +that will be used for the next component if no variable is given for the +path. Variables referred to within tt(zdn_top) have the same format as +tt(zdn_top) itself, but contain relative paths. + +For example, + +example(local -A zdn_top=( + g ~/git + ga ~/alternate/git + gs /scratch/$USER/git/:second2 + :default: /:second1 +)) + +This specifies the behaviour of a directory referred to as tt(~[g:...]) +or tt(~[ga:...]) or tt(~[gs:...]). Later path components are optional; +in that case tt(~[g]) expands to tt(~/git), and so on. tt(gs) expands +to tt(/scratch/$USER/git) and uses the associative array tt(second2) to +match the second component; tt(g) and tt(ga) use the associative array +tt(second1) to match the second component. + +When expanding a name to a directory, if the first component is not tt(g) or +tt(ga) or tt(gs), it is not an error; the function simply returns 1 so that a +later hook function can be tried. However, matching the first component +commits the function, so if a later component does not match, an error +is printed (though this still does not stop later hooks from being +executed). + +For components after the first, a relative path is expected, but note that +multiple levels may still appear. Here is an example of tt(second1): + +example(local -A second1=( + p myproject + s somproject + os otherproject/subproject/:third +)) + +The path as found from tt(zdn_top) is extended with the matching +directory, so tt(~[g:p]) becomes tt(~/git/myproject). The slash between +is added automatically (it's not possible to have a later component +modify the name of a directory already matched). Only tt(os) specifies +a variable for a third component, and there's no tt(:default:), so it's +an error to use a name like tt(~[g:p:x]) or tt(~[ga:s:y]) because +there's nowhere to look up the tt(x) or tt(y). + +The associative arrays need to be visible within this function; the +generic function therefore uses internal variable names beginning +tt(_zdn_) in order to avoid clashes. Note that the variable tt(reply) +needs to be passed back to the shell, so should not be local in the +calling function. + +The function does not test whether directories assembled by component +actually exist; this allows the system to work across automounted +file systems. The error from the command trying to use a non-existent +directory should be sufficient to indicate the problem. + +subsect(Complete example) + +Here is a full fictitious but usable autoloadable definition of the +example function defined by the code above. So tt(~[gs:p:s]) expands +to tt(/scratch/$USER/git/myscratchproject/top/srcdir) (with tt($USER) +also expanded). + +example(local -A zdn_top=( + g ~/git + ga ~/alternate/git + gs /scratch/$USER/git/:second2 + :default: /:second1 +) + +local -A second1=( + p myproject + s somproject + os otherproject/subproject/:third +) + +local -A second2=( + p myscratchproject + s somescratchproject +) + +local -A third=( + s top/srcdir + d top/documentation +) + +# autoload not needed if you did this at initialisation... +autoload -Uz zsh_directory_name_generic +zsh_directory_name_generic "$@) + +It is also possible to use global associative arrays, suitably named, +and set the style for the context of your wrapper function to +refer to this. Then your set up code would contain the following: + +example(typeset -A zdn_mywrapper_top=(...) +# ... and so on for other associative arrays ... +zstyle ':zdn:zdn_mywrapper:' mapping zdn_mywrapper_top +autoload -Uz add-zsh-hook zsh_directory_name_generic zdn_mywrapper +add-zsh-hook -U zsh_directory_name zdn_mywrapper) + +and the function tt(zdn_mywrapper) would contain only the following: + +example(zsh_directory_name_generic "$@") + +texinode(Version Control Information)(Prompt Themes)(Other Directory Functions)(User Contributions) sect(Gathering information from version control systems) cindex(version control utility) @@ -1137,7 +1332,7 @@ otherwise would be something like `svn' or `cvs') will be set to identifier is the second element. tt(vcs_info) will have filled in a proper value for the "repository's" root directory and the string containing the information about quilt's state will be available as the `misc' replacement -(and tt(%Q) for compatibility with `addon' mode. +(and tt(%Q) for compatibility with `addon' mode). What is left to discuss is how `standalone' mode is detected. The detection itself is a series of searches for directories. You can have this detection @@ -1560,7 +1755,7 @@ a customised bookmark string for the tt(hg) backend. Again, we start off by registering a function: example(zstyle ':vcs_info:hg+gen-hg-bookmark-string:*' hooks hgbookmarks) -And then we define the `tt(+vi-hgbookmarks) function: +And then we define the `tt(+vi-hgbookmarks)' function: example( function +vi-hgbookmarks+LPAR()RPAR() { # The default is to connect all bookmark names by @@ -1585,8 +1780,7 @@ function +vi-hgbookmarks+LPAR()RPAR() { # something other than the default zero: ret=1 return 0 -} -) +}) Some longer examples and code snippets which might be useful are available in the examples file located at Misc/vcs_info-examples in the Zsh source @@ -1705,7 +1899,10 @@ 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 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. +the way words are matched can be altered. 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. The simplest way of configuring the functions is to use tt(select-word-style), which can either be called as a normal function with @@ -1818,9 +2015,10 @@ matched against each var(pattern) in turn until one matches; if it does, the context is extended by a colon and the corresponding var(subcontext). Note that the test is made against the original word on the line, with no stripping of quotes. Special handling is done between words: the current -context is examined and if it contains the string tt(back), the word before -the cursor is considered, else the word after cursor is considered. Some -examples are given below. +context is examined and if it contains the string tt(between) the word +is set to a single space; else if it is contains the string tt(back), +the word before the cursor is considered, else the word after cursor is +considered. Some examples are given below. The style tt(skip-whitespace-first) is only used with the tt(forward-word) widget. If it is set to true, then tt(forward-word) @@ -1895,6 +2093,100 @@ The tt(word-context) style is implemented by the function tt(match-word-context). This should not usually need to be called directly. ) +tindex(bracketed-paste-magic) +item(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 +it as keystrokes. This disables some common usages where the self-insert +widget is replaced in order to accomplish some extra processing. An +example is the contributed tt(url-quote-magic) widget described below. + +The tt(bracketed-paste-magic) widget is meant to replace tt(bracketed-paste) +with a wrapper that re-enables these self-insert actions, and other +actions as selected by zstyles. Therefore this widget is installed with +ifzman() +example(autoload -Uz bracketed-paste-magic +zle -N bracketed-paste bracketed-paste-magic) + +Other than enabling some widget processing, tt(bracketed-paste-magic) +attempts to replicate tt(bracketed-paste) as faithfully as possible. + +The following zstyles may be set to control processing of pasted text. +All are looked up in the context `tt(:bracketed-paste-magic)'. + +startitem() +item(tt(active-widgets))( +A list of patterns matching widget names that should be activated during +the paste. All other key sequences are processed as self-insert-unmeta. +The default is `tt(self-*)' so any user-defined widgets named with that +prefix are active along with the builtin self-insert. + +If this style is not set (explicitly deleted) or set to an empty value, +no widgets are active and the pasted text is inserted literally. If the +value includes `tt(undefined-key)', any unknown sequences are discarded +from the pasted text. +) +item(tt(inactive-keys))( +The inverse of tt(active-widgets), a list of key sequences that always use +tt(self-insert-unmeta) even when bound to an active widget. Note that +this is a list of literal key sequences, not patterns. +) +item(tt(paste-init))( +A list of function names, called in widget context (but not as widgets). +The functions are called in order until one of them returns a non-zero +status. The parameter `tt(PASTED)' contains the initial state of the +pasted text. All other ZLE parameters such as `tt(BUFFER)' have their +normal values and side-effects, and full history is available, so for +example tt(paste-init) functions may move words from tt(BUFFER) into +tt(PASTED) to make those words visible to the tt(active-widgets). + +A non-zero return from a tt(paste-init) function does em(not) prevent the +paste itself from proceeding. + +Loading tt(bracketed-paste-magic) defines tt(backward-extend-paste), a +helper function for use in tt(paste-init). + +example(zstyle :bracketed-paste-magic paste-init \ + backward-extend-paste) + +When a paste would insert into the middle of a word or append text to a +word already on the line, tt(backward-extend-paste) moves the prefix +from tt(LBUFFER) into tt(PASTED) so that the tt(active-widgets) see the +full word so far. This may be useful with tt(url-quote-magic). +) +item(tt(paste-finish))( +Another list of function names called in order until one returns non-zero. +These functions are called em(after) the pasted text has been processed +by the tt(active-widgets), but em(before) it is inserted into `tt(BUFFER)'. +ZLE parameters have their normal values and side-effects. + +A non-zero return from a tt(paste-finish) function does em(not) prevent +the paste itself from proceeding. + +Loading tt(bracketed-paste-magic) also defines tt(quote-paste), a helper +function for use in tt(paste-finish). + +example(zstyle :bracketed-paste-magic paste-finish \ + quote-paste +zstyle :bracketed-paste-magic:finish quote-style \ + qqq) + +When the pasted text is inserted into tt(BUFFER), it is quoted per the +tt(quote-style) value. To forcibly turn off the built-in numeric prefix +quoting of tt(bracketed-paste), use: + +example(zstyle :bracketed-paste-magic:finish quote-style \ + none) +) +enditem() + +em(Important:) During tt(active-widgets) processing of the paste (after +tt(paste-init) and before tt(paste-finish)), tt(BUFFER) starts empty and +history is restricted, so cursor motions, etc., may not pass outside of +the pasted content. Text assigned to tt(BUFFER) by the active widgets +is copied back into tt(PASTED) before tt(paste-finish). +) tindex(copy-earlier-word) item(tt(copy-earlier-word))( This widget works like a combination of tt(insert-last-word) and @@ -2557,6 +2849,69 @@ start of the previous line. Using a numeric argument less than -1 has the effect of moving the line above the cursor up by minus that number of lines. ) +tindex(url-quote-magic) +item(tt(url-quote-magic))( +This widget replaces the built-in tt(self-insert) to make it easier to +type URLs as command line arguments. As you type, the input character is +analyzed and, if it may need quoting, the current word is checked for a +URI scheme. If one is found and the current word is not already in +quotes, a backslash is inserted before the input character. + +Styles to control quoting behavior: + +startitem() +item(tt(url-metas))( +This style is looked up in the context `tt(:url-quote-magic:)var(scheme)' +(where var(scheme) is that of the current URL, e.g. "tt(ftp)"). The value +is a string listing the characters to be treated as globbing +metacharacters when appearing in a URL using that scheme. The default is +to quote all zsh extended globbing characters, excluding 'tt(<)' and +'tt(>)' but including braces (as in brace expansion). See also +tt(url-seps). +) +item(tt(url-seps))( +Like tt(url-metas), but lists characters that should be considered command +separators, redirections, history references, etc. The default is to +quote the standard set of shell separators, excluding those that overlap +with the extended globbing characters, but including 'tt(<)' and +'tt(>)' and the first character of tt($histchars). +) +item(tt(url-globbers))( +This style is looked up in the context `tt(:url-quote-magic)'. The values +form a list of command names that are expected to do their own globbing +on the URL string. This implies that they are aliased to use the +`tt(noglob)' modifier. When the first word on the line matches one of the +values em(and) the URL refers to a local file (see tt(url-local-schema)), +only the tt(url-seps) characters are quoted; the tt(url-metas) are left +alone, allowing them to affect command-line parsing, completion, etc. The +default values are a literal `tt(noglob)' plus (when the tt(zsh/parameter) +module is available) any commands aliased to the helper function +`tt(urlglobber)' or its alias `tt(globurl)'. +) +item(tt(url-local-schema))( +This style is always looked up in the context `tt(:urlglobber)', even +though it is used by both url-quote-magic and urlglobber. The values form +a list of URI schema that should be treated as referring to local files by +their real local path names, as opposed to files which are specified +relative to a web-server-defined document root. The defaults are +"tt(ftp)" and "tt(file)". +) +item(tt(url-other-schema))( +Like tt(url-local-schema), but lists all other URI schema upon which +tt(urlglobber) and tt(url-quote-magic) should act. If the URI on the +command line does not have a scheme appearing either in this list or in +tt(url-local-schema), it is not magically quoted. The default values are +"tt(http)", "tt(https)", and "tt(ftp)". When a scheme appears both here +and in tt(url-local-schema), it is quoted differently depending on whether +the command name appears in tt(url-globbers). +) +enditem() + +Loading tt(url-quote-magic) also defines a helper function `tt(urlglobber)' +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(which-command) item(tt(which-command))( This function is a drop-in replacement for the builtin widget @@ -3314,6 +3669,14 @@ integer arithmetic, which is not how an ordinary desk calculator operates. To force floating point operation, pass the option tt(-f); see further notes below. +If the file tt(~/.zcalcrc) exists it will be sourced inside the function +once it is set up and about to process the command line. This +can be used, for example, to set shell options; tt(emulate -L zsh) +and tt(setopt extendedglob) are in effect at this point. Any +failure to source the file if it exists is treated as fatal. +As with other initialisation files, the directory tt($ZDOTDIR) is used +instead of tt($HOME) if it is set. + The mathematical library tt(zsh/mathfunc) will be loaded if it is available; see ifzman(the section `The zsh/mathfunc Module' in zmanref(zshmodules))\ diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo index 5ea8610f2..564c70dd1 100644 --- a/Doc/Zsh/expn.yo +++ b/Doc/Zsh/expn.yo @@ -410,6 +410,12 @@ are only expanded when first parsing command or assignment arguments. Process substitutions may be used following redirection operators; in this case, the substitution must appear with no trailing string. +Note that `tt(<<LPAR())var(list)tt(RPAR())' is not a special syntax; it +is equivalent to `tt(< <LPAR())var(list)tt(RPAR())', redirecting +standard input from the result of process substitution. Hence all +the following documentation applies. The second form (with the space) +is recommended for clarity. + In the case of the tt(<) or tt(>) forms, the shell runs the commands in var(list) as a subprocess of the job executing the shell command line. If the system supports the tt(/dev/fd) @@ -1033,7 +1039,16 @@ var(name) used in this fashion. If used with a nested parameter or command substitution, the result of that will be taken as a parameter name in the same way. For example, if you have `tt(foo=bar)' and `tt(bar=baz)', the strings tt(${(P)foo}), -tt(${(P)${foo}}), and tt(${(P)$(echo bar)}) will be expanded to `tt(baz)'. +tt(${(P)${foo}}), and tt(${(P)$(echo bar)}) will be expanded to +`tt(baz)'. + +Likewise, if the reference is itself nested, the expression with the +flag is treated as if it were directly replaced by the parameter name. +It is an error if this nested substitution produces an array with more +than one word. For example, if `tt(name=assoc)' where the parameter +tt(assoc) is an associative array, then +`tt(${${(P)name}[elt]})' refers to the element of the associative +subscripted `tt(elt)'. ) item(tt(q))( Quote characters that are special to the shell in the resulting words with @@ -1371,9 +1386,13 @@ outermost. The flags are not propagated up to enclosing substitutions; the nested substitution will return either a scalar or an array as determined by the flags, possibly adjusted for quoting. All the following steps take place where applicable at all levels of substitution. -Note that, unless the `tt((P))' flag is present, the flags and any subscripts -apply directly to the value of the nested substitution; for example, the -expansion tt(${${foo}}) behaves exactly the same as tt(${foo}). + +Note that, unless the `tt((P))' flag is present, the flags and any +subscripts apply directly to the value of the nested substitution; for +example, the expansion tt(${${foo}}) behaves exactly the same as +tt(${foo}). When the `tt((P))' flag is present in a nested substitution, +the other substitution rules are applied to the value em(before) it is +interpreted as a name, so tt(${${(P)foo}}) may differ from tt(${(P)foo}). At each nested level of substitution, the substituted words undergo all forms of single-word substitution (i.e. not filename generation), including @@ -1386,11 +1405,18 @@ substitution then applies the modifier tt(:h) and takes the directory part of the path.) ) item(tt(2.) em(Internal parameter flags))( -Any parameter flags set by one of the tt(typeset) family of commands, -in particular the tt(L), tt(R), tt(Z), tt(u) and tt(l) flags for padding -and capitalization, are applied directly to the parameter value. -Note these flags are options to the command, e.g. `tt(typeset -Z)'; -they are not the same as the flags used within parameter substitutions. +Any parameter flags set by one of the tt(typeset) family of commands, in +particular the tt(-L), tt(-R), tt(-Z), tt(-u) and tt(-l) options for +padding and capitalization, are applied directly to the parameter value. +Note these flags are options to the command, e.g. `tt(typeset -Z)'; they +are not the same as the flags used within parameter substitutions. + +At the outermost level of substitution, the `tt((P))' flag (rule tt(4.)) +ignores these transformations and uses the unmodified value of the +parameter as the name to be replaced. This is usually the desired +behavior because padding may make the value syntactically illegal as a +parameter name, but if capitalization changes are desired, use the +tt(${${(P)foo}}) form (rule tt(25.)). ) item(tt(3.) em(Parameter subscripting))( If the value is a raw parameter reference with a subscript, such as @@ -1401,19 +1427,25 @@ subscript. Thus if tt(var) is an array, tt(${var[1][2]}) is the second character of the first word, but tt(${var[2,4][2]}) is the entire third word (the second word of the range of words two through four of the original array). Any number of subscripts may appear. Flags such as -tt((k)) and tt((v)) which alter the result of subscripting are applied. +`tt((k))' and `tt((v))' which alter the result of subscripting are applied. ) item(tt(4.) em(Parameter name replacement))( -The effect of any tt((P)) flag, which treats the value so far as a -parameter name and replaces it with the corresponding value, is applied. +At the outermost level of nesting only, the `tt((P))' flag is applied. This +treats the value so far as a parameter name (which may include a subscript +expression) and replaces that with the corresponding value. This +replacement occurs later if the `tt((P))' flag appears in a nested +substitution. + +If the value so far names a parameter that has internal flags (rule tt(2.)), +those internal flags are applied to the new value after replacement. ) item(tt(5.) em(Double-quoted joining))( If the value after this process is an array, and the substitution -appears in double quotes, and neither an tt((@)) flag nor a tt(#) +appears in double quotes, and neither an `tt((@))' flag nor a `tt(#)' length operator is present at the current level, then words of the value are joined with the first character of the parameter tt($IFS), by default a space, between each word (single word arrays are not -modified). If the tt((j)) flag is present, that is used for joining +modified). If the `tt((j))' flag is present, that is used for joining instead of tt($IFS). ) item(tt(6.) em(Nested subscripting))( @@ -1427,22 +1459,22 @@ returns a scalar because of the quotes). ) item(tt(7.) em(Modifiers))( Any modifiers, as specified by a trailing `tt(#)', `tt(%)', `tt(/)' -(possibly doubled) or by a set of modifiers of the form tt(:...) (see +(possibly doubled) or by a set of modifiers of the form `tt(:...)' (see noderef(Modifiers) in noderef(History Expansion)), are applied to the words of the value at this level. ) item(tt(8.) em(Character evaluation))( -Any tt((#)) flag is applied, evaluating the result so far numerically +Any `tt((#))' flag is applied, evaluating the result so far numerically as a character. ) item(tt(9.) em(Length))( -Any initial tt(#) modifier, i.e. in the form tt(${#)var(var)tt(}), is +Any initial `tt(#)' modifier, i.e. in the form tt(${#)var(var)tt(}), is used to evaluate the length of the expression so far. ) item(tt(10.) em(Forced joining))( If the `tt((j))' flag is present, or no `tt((j))' flag is present but the string is to be split as given by rule tt(11.), and joining -did not take place at step tt(5.), any words in the value are joined +did not take place at rule tt(5.), any words in the value are joined together using the given string or the first character of tt($IFS) if none. Note that the `tt((F))' flag implicitly supplies a string for joining in this manner. @@ -1459,22 +1491,22 @@ occurrences of any of the characters in tt($IFS). Note this step, too, takes place at all levels of a nested substitution. ) item(tt(12.) em(Case modification))( -Any case modification from one of the flags tt((L)), tt((U)) or tt((C)) +Any case modification from one of the flags `tt((L))', `tt((U))' or `tt((C))' is applied. ) item(tt(13.) em(Escape sequence replacement))( -First any replacements from the tt((g)) flag are performed, then any -prompt-style formatting from the tt((%)) family of flags is applied. +First any replacements from the `tt((g))' flag are performed, then any +prompt-style formatting from the `tt((%))' family of flags is applied. ) item(tt(14.) em(Quote application))( -Any quoting or unquoting using tt((q)) and tt((Q)) and related flags +Any quoting or unquoting using `tt((q))' and `tt((Q))' and related flags is applied. ) item(tt(15.) em(Directory naming))( -Any directory name substitution using tt((D)) flag is applied. +Any directory name substitution using `tt((D))' flag is applied. ) item(tt(16.) em(Visibility enhancement))( -Any modifications to make characters visible using the tt((V)) flag +Any modifications to make characters visible using the `tt((V))' flag are applied. ) item(tt(17.) em(Lexical word splitting))( @@ -1512,7 +1544,7 @@ In contexts where expansion semantics requires a single word to result, all words are rejoined with the first character of tt(IFS) between. So in `tt(${LPAR()P)tt(RPAR()${LPAR()f)tt(RPAR()lines}})' the value of tt(${lines}) is split at newlines, but then must be -joined again before the tt(P) flag can be applied. +joined again before the `tt((P))' flag can be applied. If a single word is not required, this rule is skipped. ) @@ -1525,6 +1557,12 @@ Strictly speaking, the removal happens later as the same happens with other forms of substitution; the point to note here is simply that it occurs after any of the above parameter operations. ) +item(tt(25.) em(Nested parameter name replacement))( +If the `tt((P))' flag is present and rule tt(4.) has not applied, the +value so far is treated as a parameter name (which may include a subscript +expression) and replaced with the corresponding value, with internal flags +(rule tt(2.)) applied to the new value. +) enditem() subsect(Examples) @@ -2381,6 +2419,18 @@ follow symbolic links; the alternative form `tt(***/)' does, but is otherwise identical. Neither of these can be combined with other forms of globbing within the same path segment; in that case, the `tt(*)' operators revert to their usual effect. + +Even shorter forms are available when the option tt(GLOB_STAR_SHORT) is +set. In that case if no tt(/) immediately follows a tt(**) or tt(***) +they are treated as if both a tt(/) plus a further tt(*) are present. +Hence: + +example(setopt GLOBSTARSHORT +ls **.c) + +is equivalent to + +example(ls **/*.c) subsect(Glob Qualifiers) cindex(globbing, qualifiers) cindex(qualifiers, globbing) diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo index ace0a4051..d500a78ae 100644 --- a/Doc/Zsh/func.yo +++ b/Doc/Zsh/func.yo @@ -111,8 +111,7 @@ arguments, at the end. For example, suppose the autoload file tt(func) contains example(func+LPAR()RPAR() { print This is func; } -print func is initialized -) +print func is initialized) then `tt(func; func)' with tt(KSH_AUTOLOAD) set will produce both messages on the first call, but only the message `tt(This is func)' on the second diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo index 83968fedf..2a76964f3 100644 --- a/Doc/Zsh/grammar.yo +++ b/Doc/Zsh/grammar.yo @@ -421,8 +421,7 @@ works, but example(if true { # Does not work! print yes -} -) +}) does em(not), since the test is not suitably delimited. ) diff --git a/Doc/Zsh/manual.yo b/Doc/Zsh/manual.yo index 86c72c0ff..119849e4c 100644 --- a/Doc/Zsh/manual.yo +++ b/Doc/Zsh/manual.yo @@ -164,6 +164,7 @@ User Contributions menu(Utilities) menu(Recent Directories) +menu(Other Directory Functions) menu(Version Control Information) menu(Prompt Themes) menu(ZLE Functions) diff --git a/Doc/Zsh/mod_parameter.yo b/Doc/Zsh/mod_parameter.yo index 9d1dc8b7d..3d260f8e9 100644 --- a/Doc/Zsh/mod_parameter.yo +++ b/Doc/Zsh/mod_parameter.yo @@ -123,10 +123,14 @@ directory, the current working directory. vindex(history) item(tt(history))( This associative array maps history event numbers to the full history lines. +Although it is presented as an associative array, the array of all values +(tt(${history[@]})) is guaranteed to be returned in order from most recent +to oldest history event, that is, by decreasing history event number. ) vindex(historywords) item(tt(historywords))( -A special array containing the words stored in the history. +A special array containing the words stored in the history. These also +appear in most to least recent order. ) vindex(jobdirs) item(tt(jobdirs))( diff --git a/Doc/Zsh/mod_pcre.yo b/Doc/Zsh/mod_pcre.yo index d6b4bd15d..c2817f519 100644 --- a/Doc/Zsh/mod_pcre.yo +++ b/Doc/Zsh/mod_pcre.yo @@ -54,8 +54,7 @@ used to implement the "find all non-overlapping matches" functionality. A simple example of "find all non-overlapping matches": -example( -string="The following zip codes: 78884 90210 99513" +example(string="The following zip codes: 78884 90210 99513" pcre_compile -m "\d{5}" accum=() pcre_match -b -- $string @@ -64,10 +63,7 @@ while [[ $? -eq 0 ]] do accum+=$MATCH pcre_match -b -n $b[2] -- $string done -print -l $accum - - -) +print -l $accum) ) enditem() diff --git a/Doc/Zsh/mod_private.yo b/Doc/Zsh/mod_private.yo new file mode 100644 index 000000000..78aee0acf --- /dev/null +++ b/Doc/Zsh/mod_private.yo @@ -0,0 +1,89 @@ +COMMENT(!MOD!zsh/param/private +Builtins for managing private-scoped parameters in function context. +!MOD!) +The tt(zsh/param/private) module is used to create parameters whose scope +is limited to the current function body, and em(not) to other functions +called by the current function. + +This module provides a single autoloaded builtin: +ifnzman() +startitem() +findex(private) +cindex(private parameter, creating) +item(tt(private) [ {tt(PLUS())|tt(-)}tt(AHUahlprtux) ] \ +[ {tt(PLUS())|tt(-)}tt(EFLRZi) [ var(n) ] ] [ var(name)[tt(=)var(value)] ... ])( +The tt(private) builtin accepts all the same options and arguments as tt(local) +(ifzman(zmanref(zshbuiltins))ifnzman(noderef(Shell Builtin Commands))) except +for the `tt(-)tt(T)' option. Tied parameters may not be made private. + +If used at the top level (outside a function scope), tt(private) creates a +normal parameter in the same manner as tt(declare) or tt(typeset). A +warning about this is printed if tt(WARN_CREATE_GLOBAL) is set +(ifzman(zmanref(zshoptions))ifnzman(noderef(Options))). Used inside a +function scope, tt(private) creates a local parameter similar to one +declared with tt(local), except having special properties noted below. + +Special parameters which expose or manipulate internal shell state, such +as tt(ARGC), tt(argv), tt(COLUMNS), tt(LINES), tt(UID), tt(EUID), tt(IFS), +tt(PROMPT), tt(RANDOM), tt(SECONDS), etc., cannot be made private unless +the `tt(-)tt(h)' option is used to hide the special meaning of the +parameter. This may change in the future. +) +enditem() + +As with other tt(typeset) equivalents, tt(private) is both a builtin and a +reserved word, so arrays may be assigned with parenthesized word list +var(name)tt(=LPAR())var(value)...tt(RPAR()) syntax. However, the reserved +word `tt(private)' is not available until tt(zsh/param/private) is loaded, +so care must be taken with order of execution and parsing for function +definitions which use tt(private). To compensate for this, the module +also adds the option `tt(-P)' to the `tt(local)' builtin to declare private +parameters. + +For example, this construction fails if tt(zsh/param/private) has not yet +been loaded when `tt(bad_declaration)' is defined: +example(bad_declaration+LPAR()RPAR() { + zmodload zsh/param/private + private array=LPAR() one two three RPAR() +}) + +This construction works because tt(local) is already a keyword, and the +module is loaded before the statement is executed: +example(good_declaration+LPAR()RPAR() { + zmodload zsh/param/private + local -P array=LPAR() one two three RPAR() +}) + +The following is usable in scripts but may have trouble with tt(autoload): +example(zmodload zsh/param/private +iffy_declaration+LPAR()RPAR() { + private array=LPAR() one two three RPAR() +}) + +The tt(private) builtin may always be used with scalar assignments and +for declarations without assignments. + +Parameters declared with tt(private) have the following properties: +ifnzman() +startitemize() +itemiz(Within the function body where it is declared, the parameter +behaves as a local, except as noted above for tied or special parameters.) +itemiz(The type of a parameter declared private cannot be changed in the +scope where it was declared, even if the parameter is unset. Thus an +array cannot be assigned to a private scalar, etc.) +itemiz(Within any other function called by the declaring function, the +private parameter does em(NOT) hide other parameters of the same name, so +for example a global parameter of the same name is visible and may be +assigned or unset. This includes calls to anonymous functions, although +that may also change in the future.) +itemiz(An exported private remains in the environment of inner scopes but +appears unset for the current shell in those scopes. Generally, exporting +private parameters should be avoided.) +enditemize() + +Note that this differs from the static scope defined by compiled languages +derived from C, in that the a new call to the same function creates a new +scope, i.e., the parameter is still associated with the call stack rather +than with the function definition. It differs from ksh `tt(typeset -S)' +because the syntax used to define the function has no bearing on whether +the parameter scope is respected. diff --git a/Doc/Zsh/mod_socket.yo b/Doc/Zsh/mod_socket.yo index 332c551fe..867f6081f 100644 --- a/Doc/Zsh/mod_socket.yo +++ b/Doc/Zsh/mod_socket.yo @@ -28,6 +28,11 @@ will be taken as the target file descriptor for the connection. In order to elicit more verbose output, use tt(-v). + +File descriptors can be closed with normal shell syntax when no longer +needed, for example: + +example(exec {REPLY}>&-) ) enditem() diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo index abd0f8715..f37753991 100644 --- a/Doc/Zsh/options.yo +++ b/Doc/Zsh/options.yo @@ -534,6 +534,21 @@ cindex(globbing, of . files) item(tt(GLOB_DOTS) (tt(-4)))( Do not require a leading `tt(.)' in a filename to be matched explicitly. ) +pindex(GLOB_STAR_SHORT) +pindex(NO_GLOB_STAR_SHORT) +pindex(GLOBSTARSHORT) +pindex(NOGLOBSTARSHORT) +cindex(globbing, short forms) +cindex(globbing, ** special) +item(tt(GLOB_STAR_SHORT))( +When this option is set and the default zsh-style globbing is in +effect, the pattern `tt(**/*)' can be abbreviated to `tt(**)' and the +pattern `tt(***/*)' can be abbreviated to tt(***). Hence `tt(**.c)' +finds a file ending in tt(.c) in any subdirectory, and `tt(***.c)' does +the same while also following symbolic links. A tt(/) immediately +after the `tt(**)' or `tt(***)' forces the pattern to be treated as the +unabbreviated form. +) pindex(GLOB_SUBST) pindex(NO_GLOB_SUBST) pindex(GLOBSUBST) @@ -746,7 +761,8 @@ pindex(NOWARNCREATEGLOBAL) cindex(parameters, warning when created globally) item(tt(WARN_CREATE_GLOBAL))( Print a warning message when a global parameter is created in a function -by an assignment. This often indicates that a parameter has not been +by an assignment or in math context. +This often indicates that a parameter has not been declared local when it should have been. Parameters explicitly declared 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 @@ -1552,13 +1568,13 @@ ifnzman(noderef(Arithmetic Evaluation))\ ifzman(the section ARITHMETIC EVALUATION in zmanref(zshmisc)) has an explicit list. ) -pindex(DEBUG_BEFORE_CMD <D>) -pindex(NO_DEBUG_BEFORE_CMD <D>) -pindex(DEBUGBEFORECMD <D>) -pindex(NODEBUGBEFORECMD <D>) +pindex(DEBUG_BEFORE_CMD) +pindex(NO_DEBUG_BEFORE_CMD) +pindex(DEBUGBEFORECMD) +pindex(NODEBUGBEFORECMD) cindex(traps, DEBUG, before or after command) cindex(DEBUG trap, before or after command) -item(tt(DEBUG_BEFORE_CMD))( +item(tt(DEBUG_BEFORE_CMD) <D>)( Run the tt(DEBUG) trap before each command; otherwise it is run after each command. Setting this option mimics the behaviour of ksh 93; with the option unset the behaviour is that of ksh 88. diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo index ba2856b34..21bb87442 100644 --- a/Doc/Zsh/params.yo +++ b/Doc/Zsh/params.yo @@ -99,6 +99,11 @@ the syntax: ifzman() indent(var(name)tt(+=LPAR())var(value) ...tt(RPAR())) +Within the parentheses on the right hand side of either form of the +assignment, newlines and semicolons are treated the same as white space, +separating individual var(value)s. Any consecutive sequence of such +characters has the same effect. + Ordinary array parameters may also be explicitly declared with: findex(typeset, use of) ifzman() @@ -383,9 +388,7 @@ as part of an arithmetic expression in an ordinary subscript. To avoid subscript parsing limitations in assignments to associative array elements, use the append syntax: -example( - aa+=('key with "*strange*" characters' 'value string') -) +example(aa+=('key with "*strange*" characters' 'value string')) The basic rule to remember when writing a subscript expression is that all text between the opening `tt([)' and the closing `tt(])' is interpreted @@ -773,7 +776,13 @@ Incremented by one each time a new shell is started. ) vindex(signals) item(tt(signals))( -An array containing the names of the signals. +An array containing the names of the signals. Note that with +the standard zsh numbering of array indices, where the first element +has index 1, the signals are offset by 1 from the signal number +used by the operating system. For example, on typical Unix-like systems +tt(HUP) is signal number 1, but is referred to as tt($signals[2]). This +is because of tt(EXIT) at position 1 in the array, which is used +internally by zsh but is not known to the operating system. ) vindex(TRY_BLOCK_ERROR) item(tt(TRY_BLOCK_ERROR) <S>)( diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo index 2c539c460..7047b43d9 100644 --- a/Doc/Zsh/zle.yo +++ b/Doc/Zsh/zle.yo @@ -404,6 +404,7 @@ xitem(tt(zle) tt(-l) [ tt(-L) | tt(-a) ] [ var(string) ... ]) xitem(tt(zle) tt(-D) var(widget) ...) xitem(tt(zle) tt(-A) var(old-widget) var(new-widget)) xitem(tt(zle) tt(-N) var(widget) [ var(function) ]) +xitem(tt(zle) tt(-f) var(flag) [ var(flag)... ]) xitem(tt(zle) tt(-C) var(widget) var(completion-widget) var(function)) xitem(tt(zle) tt(-R) [ tt(-c) ] [ var(display-string) ] [ var(string) ... ]) xitem(tt(zle) tt(-M) var(string)) @@ -464,6 +465,21 @@ ifzman(the section `Widgets' below)\ ifnzman(noderef(Zle Widgets))\ . ) +item(tt(-f) var(flag) [ var(flag)... ])( +Set various flags on the running widget. Possible values for var(flag) are: + +tt(yank) for indicating that the widget has yanked text into the buffer. +If the widget is wrapping an existing internal widget, no further +action is necessary, but if it has inserted the text manually, then it +should also take care to set tt(YANK_START) and tt(YANK_END) correctly. +tt(yankbefore) does the same but is used when the yanked text appears +after the cursor. + +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. +) cindex(completion widgets, creating) item(tt(-C) var(widget) var(completion-widget) var(function))( Create a user-defined completion widget named var(widget). The @@ -1011,11 +1027,14 @@ vindex(YANK_END) xitem(tt(YANK_ACTIVE) (integer)) xitem(tt(YANK_START) (integer)) item(tt(YANK_END) (integer))( -These three parameters indicate whether text has just been yanked (pasted) -into the buffer. tt(YANK_START) and tt(YANK_END) are in the same unit sas -tt(CURSOR), and are only valid when tt(YANK_ACTIVE) is non-zero. +tt(YANK_ACTIVE) indicates whether text has just been yanked (pasted) +into the buffer. tt(YANK_START) and tt(YANK_END) give the location of +the pasted text and are in the same units as tt(CURSOR). They are only +valid for reading when tt(YANK_ACTIVE) is non-zero. They can also be +assigned by widgets that insert text in a yank-like fashion, for example +wrappers of tt(bracketed-paste). See also tt(zle -f). -All three are read-only. +tt(YANK_ACTIVE) is read-only. ) vindex(ZLE_STATE) item(tt(ZLE_STATE) (scalar))( @@ -2255,6 +2274,7 @@ the command line or key bindings temporarily. The following widget, tt(caps-lock), serves as an example. + example(self-insert-ucase+LPAR()RPAR() { LBUFFER+=${(U)KEYS[-1]} } @@ -2274,8 +2294,8 @@ zle -D save-caps-lock (( stat )) && zle send-break -return $stat -) +return $stat) + This causes typed letters to be inserted capitalised until either tt(accept-line) (i.e. typically the return key) is typed or the tt(caps-lock) widget is invoked again; the later is handled by saving @@ -2679,7 +2699,7 @@ If tt(zle_highlight) is not set or no value applies to a particular context, the defaults applied are equivalent to example(zle_highlight=LPAR()region:standout special:standout -suffix:bold isearch:underline+RPAR()) +suffix:bold isearch:underline paste:standout+RPAR()) i.e. both the region and special characters are shown in standout mode. |