diff options
Diffstat (limited to 'Doc/zshcontrib.1')
| -rw-r--r-- | Doc/zshcontrib.1 | 5558 |
1 files changed, 5558 insertions, 0 deletions
diff --git a/Doc/zshcontrib.1 b/Doc/zshcontrib.1 new file mode 100644 index 000000000..573822d46 --- /dev/null +++ b/Doc/zshcontrib.1 @@ -0,0 +1,5558 @@ +.TH "ZSHCONTRIB" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zshcontrib \- user contributions to zsh +.\" Yodl file: Zsh/contrib.yo +.SH "DESCRIPTION" +.PP +The Zsh source distribution includes a number of items contributed by the +user community\&. These are not inherently a part of the shell, and some +may not be available in every zsh installation\&. The most significant of +these are documented here\&. For documentation on other contributed items +such as shell functions, look for comments in the function source files\&. +.PP +.PP +.SH "UTILITIES" +.PP +.SS "Accessing On\-Line Help" +.PP +The key sequence \fBESC h\fP is normally bound by ZLE to execute the +\fBrun\-help\fP widget (see +\fIzshzle\fP(1))\&. This invokes the \fBrun\-help\fP command with the command word from the +current input line as its argument\&. By default, \fBrun\-help\fP is an alias +for the \fBman\fP command, so this often fails when the command word is a +shell builtin or a user\-defined function\&. By redefining the \fBrun\-help\fP +alias, one can improve the on\-line help provided by the shell\&. +.PP +The \fBhelpfiles\fP utility, found in the \fBUtil\fP directory of the +distribution, is a Perl program that can be used to process the zsh manual +to produce a separate help file for each shell builtin and for many other +shell features as well\&. The autoloadable \fBrun\-help\fP function, found in +\fBFunctions/Misc\fP, searches for these helpfiles and performs several +other tests to produce the most complete help possible for the command\&. +.PP +Help files are installed by default to a subdirectory of \fB/usr/share/zsh\fP +or \fB/usr/local/share/zsh\fP\&. +.PP +To create your own help files with \fBhelpfiles\fP, choose or create a +directory where the individual command help files will reside\&. For +example, you might choose \fB~/zsh_help\fP\&. If you unpacked the zsh +distribution in your home directory, you would use the commands: +.PP +.RS +.nf +\fBmkdir ~/zsh_help +perl ~/zsh\-5\&.8\&.1\&.3\-test/Util/helpfiles ~/zsh_help\fP +.fi +.RE +.PP +The \fBHELPDIR\fP parameter tells \fBrun\-help\fP where to look for the help +files\&. When unset, it uses the default installation path\&. +To use your own set of help files, set this to the appropriate path +in one of your startup files: +.PP +.RS +.nf +\fBHELPDIR=~/zsh_help\fP +.fi +.RE +.PP +To use the \fBrun\-help\fP function, you need to add lines something +like the following to your \fB\&.zshrc\fP or equivalent startup file: +.PP +.RS +.nf +\fBunalias run\-help +autoload run\-help\fP +.fi +.RE +.PP +Note that in order for `\fBautoload run\-help\fP\&' to work, the \fBrun\-help\fP +file must be in one of the directories named in your \fBfpath\fP array (see +\fIzshparam\fP(1))\&. This should already be the case if you have a standard zsh +installation; if it is not, copy \fBFunctions/Misc/run\-help\fP to an +appropriate directory\&. +.PP +.SS "Recompiling Functions" +.PP +If you frequently edit your zsh functions, or periodically update your zsh +installation to track the latest developments, you may find that function +digests compiled with the \fBzcompile\fP builtin are frequently out of date +with respect to the function source files\&. This is not usually a problem, +because zsh always looks for the newest file when loading a function, but +it may cause slower shell startup and function loading\&. Also, if a digest +file is explicitly used as an element of \fBfpath\fP, zsh won\&'t check whether +any of its source files has changed\&. +.PP +The \fBzrecompile\fP autoloadable function, found in \fBFunctions/Misc\fP, can +be used to keep function digests up to date\&. +.PP +.PD 0 +.TP +.PD 0 +\fBzrecompile\fP [ \fB\-qt\fP ] [ \fIname\fP \&.\&.\&. ] +.TP +.PD +\fBzrecompile\fP [ \fB\-qt\fP ] \fB\-p\fP \fIarg\fP \&.\&.\&. [ \fB\-\fP\fB\-\fP \fIarg\fP \&.\&.\&. ] +This tries to find \fB*\&.zwc\fP files and automatically re\-compile them if at +least one of the original files is newer than the compiled file\&. This +works only if the names stored in the compiled files are full paths or are +relative to the directory that contains the \fB\&.zwc\fP file\&. +.RS +.PP +In the first form, each \fIname\fP is the name of a compiled file or a +directory containing \fB*\&.zwc\fP files that should be checked\&. If no +arguments are given, the directories and \fB*\&.zwc\fP files in \fBfpath\fP are +used\&. +.PP +When \fB\-t\fP is given, no compilation is performed, but a return status of +zero (true) is set if there are files that need to be re\-compiled and +non\-zero (false) otherwise\&. The \fB\-q\fP option quiets the chatty output +that describes what \fBzrecompile\fP is doing\&. +.PP +Without the \fB\-t\fP option, the return status is zero if all files that +needed re\-compilation could be compiled and non\-zero if compilation for at +least one of the files failed\&. +.PP +If the \fB\-p\fP option is given, the \fIarg\fPs are interpreted as one +or more sets of arguments for \fBzcompile\fP, separated by `\fB\-\fP\fB\-\fP\&'\&. +For example: +.PP +.RS +.nf +\fBzrecompile \-p \e + \-R ~/\&.zshrc \-\- \e + \-M ~/\&.zcompdump \-\- \e + ~/zsh/comp\&.zwc ~/zsh/Completion/*/_*\fP +.fi +.RE +.PP +This compiles \fB~/\&.zshrc\fP into \fB~/\&.zshrc\&.zwc\fP if that doesn\&'t exist or +if it is older than \fB~/\&.zshrc\fP\&. The compiled file will be marked for +reading instead of mapping\&. The same is done for \fB~/\&.zcompdump\fP and +\fB~/\&.zcompdump\&.zwc\fP, but this compiled file is marked for mapping\&. The +last line re\-creates the file \fB~/zsh/comp\&.zwc\fP if any of the files +matching the given pattern is newer than it\&. +.PP +Without the \fB\-p\fP option, \fBzrecompile\fP does not create function digests +that do not already exist, nor does it add new functions to the digest\&. +.RE +.PP +The following shell loop is an example of a method for creating function +digests for all functions in your \fBfpath\fP, assuming that you have write +permission to the directories: +.PP +.RS +.nf +\fBfor ((i=1; i <= $#fpath; ++i)); do + dir=$fpath[i] + zwc=${dir:t}\&.zwc + if [[ $dir == (\&.|\&.\&.) || $dir == (\&.|\&.\&.)/* ]]; then + continue + fi + files=($dir/*(N\-\&.)) + if [[ \-w $dir:h && \-n $files ]]; then + files=(${${(M)files%/*/*}#/}) + if ( cd $dir:h && + zrecompile \-p \-U \-z $zwc $files ); then + fpath[i]=$fpath[i]\&.zwc + fi + fi +done\fP +.fi +.RE +.PP +The \fB\-U\fP and \fB\-z\fP options are appropriate for functions in the default +zsh installation \fBfpath\fP; you may need to use different options for your +personal function directories\&. +.PP +Once the digests have been created and your \fBfpath\fP modified to refer to +them, you can keep them up to date by running \fBzrecompile\fP with no +arguments\&. +.PP +.SS "Keyboard Definition" +.PP +The large number of possible combinations of keyboards, workstations, +terminals, emulators, and window systems makes it impossible for zsh to +have built\-in key bindings for every situation\&. The \fBzkbd\fP utility, +found in \fBFunctions/Misc\fP, can help you quickly create key bindings for your +configuration\&. +.PP +Run \fBzkbd\fP either as an autoloaded function, or as a shell script: +.PP +.RS +.nf +\fBzsh \-f ~/zsh\-5\&.8\&.1\&.3\-test/Functions/Misc/zkbd\fP +.fi +.RE +.PP +When you run \fBzkbd\fP, it first asks you to enter your terminal type; if +the default it offers is correct, just press return\&. It then asks you to +press a number of different keys to determine characteristics of your +keyboard and terminal; \fBzkbd\fP warns you if it finds anything out of the +ordinary, such as a Delete key that sends neither \fB^H\fP nor \fB^?\fP\&. +.PP +The keystrokes read by \fBzkbd\fP are recorded as a definition for an +associative array named \fBkey\fP, written to a file in the subdirectory +\fB\&.zkbd\fP within either your \fBHOME\fP or \fBZDOTDIR\fP directory\&. The name +of the file is composed from the \fBTERM\fP, \fBVENDOR\fP and \fBOSTYPE\fP +parameters, joined by hyphens\&. +.PP +You may read this file into your \fB\&.zshrc\fP or another startup file with +the `\fBsource\fP\&' or `\fB\&.\fP' commands, then reference the \fBkey\fP parameter +in bindkey commands, like this: +.PP +.RS +.nf +\fBsource ${ZDOTDIR:\-$HOME}/\&.zkbd/$TERM\-$VENDOR\-$OSTYPE +[[ \-n ${key[Left]} ]] && bindkey "${key[Left]}" backward\-char +[[ \-n ${key[Right]} ]] && bindkey "${key[Right]}" forward\-char +# etc\&.\fP +.fi +.RE +.PP +Note that in order for `\fBautoload zkbd\fP\&' to work, the \fBzkdb\fP file must +be in one of the directories named in your \fBfpath\fP array (see +\fIzshparam\fP(1))\&. This should already be the case if you have a standard zsh +installation; if it is not, copy \fBFunctions/Misc/zkbd\fP to an +appropriate directory\&. +.PP +.SS "Dumping Shell State" +.PP +Occasionally you may encounter what appears to be a bug in the shell, +particularly if you are using a beta version of zsh or a development +release\&. Usually it is sufficient to send a description of the +problem to one of the zsh mailing lists (see +\fIzsh\fP(1)), but sometimes one of the zsh developers will need to recreate your +environment in order to track the problem down\&. +.PP +The script named \fBreporter\fP, found in the \fBUtil\fP directory of the +distribution, is provided for this purpose\&. (It is also possible to +\fBautoload reporter\fP, but \fBreporter\fP is not installed in \fBfpath\fP +by default\&.) This script outputs a detailed dump of the shell state, +in the form of another script that can be read with `\fBzsh \-f\fP\&' to +recreate that state\&. +.PP +To use \fBreporter\fP, read the script into your shell with the `\fB\&.\fP\&' +command and redirect the output into a file: +.PP +.RS +.nf +\fB\&. ~/zsh\-5\&.8\&.1\&.3\-test/Util/reporter > zsh\&.report\fP +.fi +.RE +.PP +You should check the \fBzsh\&.report\fP file for any sensitive information +such as passwords and delete them by hand before sending the script to the +developers\&. Also, as the output can be voluminous, it\&'s best to wait for +the developers to ask for this information before sending it\&. +.PP +You can also use \fBreporter\fP to dump only a subset of the shell state\&. +This is sometimes useful for creating startup files for the first time\&. +Most of the output from reporter is far more detailed than usually is +necessary for a startup file, but the \fBaliases\fP, \fBoptions\fP, and +\fBzstyles\fP states may be useful because they include only changes from +the defaults\&. The \fBbindings\fP state may be useful if you have created +any of your own keymaps, because \fBreporter\fP arranges to dump the keymap +creation commands as well as the bindings for every keymap\&. +.PP +As is usual with automated tools, if you create a startup file with +\fBreporter\fP, you should edit the results to remove unnecessary commands\&. +Note that if you\&'re using the new completion system, you should \fInot\fP +dump the \fBfunctions\fP state to your startup files with \fBreporter\fP; use +the \fBcompdump\fP function instead (see +\fIzshcompsys\fP(1))\&. +.PP +.PD 0 +.TP +.PD +\fBreporter\fP [ \fIstate\fP \&.\&.\&. ] +Print to standard output the indicated subset of the current shell state\&. +The \fIstate\fP arguments may be one or more of: +.RS +.PP +.PD 0 +.TP +\fBall\fP +Output everything listed below\&. +.TP +\fBaliases\fP +Output alias definitions\&. +.TP +\fBbindings\fP +Output ZLE key maps and bindings\&. +.TP +\fBcompletion\fP +Output old\-style \fBcompctl\fP commands\&. +New completion is covered by \fBfunctions\fP and \fBzstyles\fP\&. +.TP +\fBfunctions\fP +Output autoloads and function definitions\&. +.TP +\fBlimits\fP +Output \fBlimit\fP commands\&. +.TP +\fBoptions\fP +Output \fBsetopt\fP commands\&. +.TP +\fBstyles\fP +Same as \fBzstyles\fP\&. +.TP +\fBvariables\fP +Output shell parameter assignments, plus \fBexport\fP +commands for any environment variables\&. +.TP +\fBzstyles\fP +Output \fBzstyle\fP commands\&. +.PD +.PP +If the \fIstate\fP is omitted, \fBall\fP is assumed\&. +.RE +.PP +With the exception of `\fBall\fP\&', every \fIstate\fP can be abbreviated by +any prefix, even a single letter; thus \fBa\fP is the same as \fBaliases\fP, +\fBz\fP is the same as \fBzstyles\fP, etc\&. +.PP +.SS "Manipulating Hook Functions" +.PP +.PD 0 +.TP +.PD +\fBadd\-zsh\-hook\fP [ \fB\-L\fP | \fB\-dD\fP ] [ \fB\-Uzk\fP ] \fIhook\fP \fIfunction\fP +Several functions are special to the shell, as described in the section +SPECIAL FUNCTIONS, see \fIzshmisc\fP(1), +in that they are automatically called at specific points during shell execution\&. +Each has an associated array consisting of names of functions to be +called at the same point; these are so\-called `hook functions\&'\&. +The shell function \fBadd\-zsh\-hook\fP provides a simple way of adding or +removing functions from the array\&. +.RS +.PP +\fIhook\fP is one of \fBchpwd\fP, \fBperiodic\fP, \fBprecmd\fP, \fBpreexec\fP, +\fBzshaddhistory\fP, \fBzshexit\fP, or \fBzsh_directory_name\fP, +the special functions in question\&. Note that \fBzsh_directory_name\fP +is called in a different way from the other functions, but may +still be manipulated as a hook\&. +.PP +\fIfunction\fP is name of an ordinary shell function\&. If no options +are given this will be added to the array of functions to be executed +in the given context\&. +Functions are invoked in the order they were added\&. +.PP +If the option \fB\-L\fP is given, the current values for the hook arrays +are listed with \fBtypeset\fP\&. +.PP +If the option \fB\-d\fP is given, the \fIfunction\fP is removed from +the array of functions to be executed\&. +.PP +If the option \fB\-D\fP is given, the \fIfunction\fP is treated as a pattern +and any matching names of functions are removed from the array of +functions to be executed\&. +.PP +The options \fB\-U\fP, \fB\-z\fP and \fB\-k\fP are passed as arguments to +\fBautoload\fP for \fIfunction\fP\&. For functions contributed with zsh, the +options \fB\-Uz\fP are appropriate\&. +.RE +.TP +\fBadd\-zle\-hook\-widget\fP [ \fB\-L\fP | \fB\-dD\fP ] [ \fB\-Uzk\fP ] \fIhook\fP \fIwidgetname\fP +Several widget names are special to the line editor, as described in the section +Special Widgets, see \fIzshzle\fP(1), +in that they are automatically called at specific points during editing\&. +Unlike function hooks, these do not use a predefined array of other names +to call at the same point; the shell function \fBadd\-zle\-hook\-widget\fP +maintains a similar array and arranges for the special widget to invoke +those additional widgets\&. +.RS +.PP +\fIhook\fP is one of \fBisearch\-exit\fP, \fBisearch\-update\fP, +\fBline\-pre\-redraw\fP, \fBline\-init\fP, \fBline\-finish\fP, \fBhistory\-line\-set\fP, +or \fBkeymap\-select\fP, corresponding to each of the special widgets +\fBzle\-isearch\-exit\fP, etc\&. The special widget names are also accepted +as the \fIhook\fP argument\&. +.PP +\fIwidgetname\fP is the name of a ZLE widget\&. If no options are given this +is added to the array of widgets to be invoked in the given hook context\&. +Widgets are invoked in the order they were added, with +.RS +.nf +\fB\fBzle \fP\fIwidgetname\fP\fB \-Nw \-f "nolast" \-\- "$@"\fP\fP +.fi +.RE +.PP +Note that this means that the `\fBWIDGET\fP\&' special parameter tracks the +\fIwidgetname\fP when the widget function is called, rather than tracking +the name of the corresponding special hook widget\&. +.PP +If the option \fB\-d\fP is given, the \fIwidgetname\fP is removed from +the array of widgets to be executed\&. +.PP +If the option \fB\-D\fP is given, the \fIwidgetname\fP is treated as a pattern +and any matching names of widgets are removed from the array\&. +.PP +If \fIwidgetname\fP does not name an existing widget when added to the +array, it is assumed that a shell function also named \fIwidgetname\fP is +meant to provide the implementation of the widget\&. This name is therefore +marked for autoloading, and the options \fB\-U\fP, \fB\-z\fP and \fB\-k\fP are +passed as arguments to \fBautoload\fP as with \fBadd\-zsh\-hook\fP\&. The +widget is also created with `\fBzle \-N \fP\fIwidgetname\fP\&' to cause the +corresponding function to be loaded the first time the hook is called\&. +.PP +The arrays of \fIwidgetname\fP are currently maintained in \fBzstyle\fP +contexts, one for each \fIhook\fP context, with a style of `\fBwidgets\fP\&'\&. +If the \fB\-L\fP option is given, this set of styles is listed with +`\fBzstyle \-L\fP\&'\&. This implementation may change, and the special widgets +that refer to the styles are created only if \fBadd\-zle\-hook\-widget\fP is +called to add at least one widget, so if this function is used for any +hooks, then all hooks should be managed only via this function\&. +.RE +.PP +.SH "REMEMBERING RECENT DIRECTORIES" +.PP +The function \fBcdr\fP allows you to change the working directory to a +previous working directory from a list maintained automatically\&. It is +similar in concept to the directory stack controlled by the \fBpushd\fP, +\fBpopd\fP and \fBdirs\fP builtins, but is more configurable, and as it stores +all entries in files it is maintained across sessions and (by default) +between terminal emulators in the current session\&. Duplicates are +automatically removed, so that the list reflects the single most recent +use of each directory\&. +.PP +Note that the \fBpushd\fP directory stack is not actually modified or used +by \fBcdr\fP unless you configure it to do so as described in the +configuration section below\&. +.PP +.SS "Installation" +.PP +The system works by means of a hook function that is called every time the +directory changes\&. To install the system, autoload the required functions +and use the \fBadd\-zsh\-hook\fP function described above: +.PP +.RS +.nf +\fBautoload \-Uz chpwd_recent_dirs cdr add\-zsh\-hook +add\-zsh\-hook chpwd chpwd_recent_dirs\fP +.fi +.RE +.PP +Now every time you change directly interactively, no matter which +command you use, the directory to which you change will be remembered +in most\-recent\-first order\&. +.PP +.SS "Use" +.PP +All direct user interaction is via the \fBcdr\fP function\&. +.PP +The argument to cdr is a number \fIN\fP corresponding to the \fIN\fPth most +recently changed\-to directory\&. 1 is the immediately preceding directory; +the current directory is remembered but is not offered as a destination\&. +Note that if you have multiple windows open 1 may refer to a directory +changed to in another window; you can avoid this by having per\-terminal +files for storing directory as described for the +\fBrecent\-dirs\-file\fP style below\&. +.PP +If you set the \fBrecent\-dirs\-default\fP style described below \fBcdr\fP +will behave the same as \fBcd\fP if given a non\-numeric argument, or more +than one argument\&. The recent directory list is updated just the same +however you change directory\&. +.PP +If the argument is omitted, 1 is assumed\&. This is similar to \fBpushd\fP\&'s +behaviour of swapping the two most recent directories on the stack\&. +.PP +Completion for the argument to \fBcdr\fP is available if compinit has been +run; menu selection is recommended, using: +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:cdr:*:*' menu selection\fP +.fi +.RE +.PP +to allow you to cycle through recent directories; the order is preserved, +so the first choice is the most recent directory before the current one\&. +The verbose style is also recommended to ensure the directory is shown; this +style is on by default so no action is required unless you have changed it\&. +.PP +.SS "Options" +.PP +The behaviour of \fBcdr\fP may be modified by the following options\&. +.PP +.PD 0 +.TP +.PD +\fB\-l\fP +lists the numbers and the corresponding directories in +abbreviated form (i\&.e\&. with \fB~\fP substitution reapplied), one per line\&. +The directories here are not quoted (this would only be an issue if a +directory name contained a newline)\&. This is used by the completion +system\&. +.TP +\fB\-r\fP +sets the variable \fBreply\fP to the current set of directories\&. Nothing +is printed and the directory is not changed\&. +.TP +\fB\-e\fP +allows you to edit the list of directories, one per line\&. The +list can be edited to any extent you like; no sanity checking is +performed\&. Completion is available\&. No quoting is necessary (except for +newlines, where I have in any case no sympathy); directories are in +unabbreviated form and contain an absolute path, i\&.e\&. they start with \fB/\fP\&. +Usually the first entry should be left as the current directory\&. +.TP +\fB\-p \&'\fP\fIpattern\fP\fB'\fP +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\&. \fB\&'*removeme*'\fP) are needed to remove entries with a given +substring\&. +.RS +.PP +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 \fB\-P\fP instead of \fB\-p\fP\&. +.RE +.PP +.SS "Configuration" +.PP +Configuration is by means of the styles mechanism that should be familiar +from completion; if not, see the description of the \fBzstyle\fP command in +see \fIzshmodules\fP(1)\&. The context for setting styles +should be \fB\&':chpwd:*'\fP in case the meaning of the context is extended in +future, for example: +.PP +.RS +.nf +\fBzstyle \&':chpwd:*' recent\-dirs\-max 0\fP +.fi +.RE +.PP +sets the value of the \fBrecent\-dirs\-max\fP style to 0\&. In practice the +style name is specific enough that a context of \&'*' should be fine\&. +.PP +An exception is \fBrecent\-dirs\-insert\fP, which is used exclusively by the +completion system and so has the usual completion system context +(\fB\&':completion:*'\fP if nothing more specific is needed), though again +\fB\&'*'\fP should be fine in practice\&. +.PP +.PD 0 +.TP +.PD +\fBrecent\-dirs\-default\fP +If true, and the command is expecting a recent directory index, and +either there is more than one argument or the argument is not an +integer, then fall through to "cd"\&. This allows the lazy to use only +one command for directory changing\&. Completion recognises this, too; +see recent\-dirs\-insert for how to control completion when this option +is in use\&. +.TP +\fBrecent\-dirs\-file\fP +The file where the list of directories is saved\&. The default +is \fB${ZDOTDIR:\-$HOME}/\&.chpwd\-recent\-dirs\fP, i\&.e\&. this is in your +home directory unless you have set the variable \fBZDOTDIR\fP to point +somewhere else\&. Directory names are saved in \fB$\&'\fP\fI\&.\&.\&.\fP\fB'\fP quoted +form, so each line in the file can be supplied directly to the shell as an +argument\&. +.RS +.PP +The value of this style may be an array\&. In this case, the first +file in the list will always be used for saving directories while any +other files are left untouched\&. When reading the recent directory +list, if there are fewer than the maximum number of entries in the +first file, the contents of later files in the array will be appended +with duplicates removed from the list shown\&. The contents of the two +files are not sorted together, i\&.e\&. all the entries in the first file +are shown first\&. The special value \fB+\fP can appear in the list to +indicate the default file should be read at that point\&. This allows +effects like the following: +.PP +.RS +.nf +\fBzstyle \&':chpwd:*' recent\-dirs\-file \e +~/\&.chpwd\-recent\-dirs\-${TTY##*/} +\fP +.fi +.RE +.PP +Recent directories are read from a file numbered according to +the terminal\&. If there are insufficient entries the list +is supplemented from the default file\&. +.PP +It is possible to use \fBzstyle \-e\fP to make the directory configurable +at run time: +.PP +.RS +.nf +\fBzstyle \-e \&':chpwd:*' recent\-dirs\-file pick\-recent\-dirs\-file +pick\-recent\-dirs\-file() { + if [[ $PWD = ~/text/writing(|/*) ]]; then + reply=(~/\&.chpwd\-recent\-dirs\-writing) + else + reply=(+) + fi +}\fP +.fi +.RE +.PP +In this example, if the current directory is \fB~/text/writing\fP or a +directory under it, then use a special file for saving recent +directories, else use the default\&. +.RE +.TP +\fBrecent\-dirs\-insert\fP +Used by completion\&. If \fBrecent\-dirs\-default\fP is true, then setting +this to \fBtrue\fP causes the actual directory, rather than its index, to +be inserted on the command line; this has the same effect as using +the corresponding index, but makes the history clearer and the line +easier to edit\&. With this setting, if part of an argument was +already typed, normal directory completion rather than recent +directory completion is done; this is because recent directory +completion is expected to be done by cycling through entries menu +fashion\&. +.RS +.PP +If the value of the style is \fBalways\fP, then only recent directories will +be completed; in that case, use the \fBcd\fP command when you want to +complete other directories\&. +.PP +If the value is \fBfallback\fP, recent directories will be tried first, then +normal directory completion is performed if recent directory completion +failed to find a match\&. +.PP +Finally, if the value is \fBboth\fP then both sets of completions are +presented; the usual tag mechanism can be used to distinguish results, with +recent directories tagged as \fBrecent\-dirs\fP\&. Note that the recent +directories inserted are abbreviated with directory names where appropriate\&. +.RE +.TP +\fBrecent\-dirs\-max\fP +The maximum number of directories to save to the file\&. If +this is zero or negative there is no maximum\&. The default is 20\&. +Note this includes the current directory, which isn\&'t offered, +so the highest number of directories you will be offered +is one less than the maximum\&. +.TP +\fBrecent\-dirs\-prune\fP +This style is an array determining what directories should (or should +not) be added to the recent list\&. Elements of the array can include: +.RS +.PP +.PD 0 +.TP +.PD +\fBparent\fP +Prune parents (more accurately, ancestors) from the recent list\&. +If present, changing directly down by any number of directories +causes the current directory to be overwritten\&. For example, +changing from ~pws to ~pws/some/other/dir causes ~pws not to be +left on the recent directory stack\&. This only applies to direct +changes to descendant directories; earlier directories on the +list are not pruned\&. For example, changing from ~pws/yet/another +to ~pws/some/other/dir does not cause ~pws to be pruned\&. +.TP +\fBpattern:\fP\fIpattern\fP +Gives a zsh pattern for directories that should not be +added to the recent list (if not already there)\&. This element +can be repeated to add different patterns\&. For example, +\fB\&'pattern:/tmp(|/*)'\fP stops \fB/tmp\fP or its descendants +from being added\&. The \fBEXTENDED_GLOB\fP option is always turned on +for these patterns\&. +.RE +.TP +\fBrecent\-dirs\-pushd\fP +If set to true, \fBcdr\fP will use \fBpushd\fP instead of \fBcd\fP to change the +directory, so the directory is saved on the directory stack\&. As the +directory stack is completely separate from the list of files saved +by the mechanism used in this file there is no obvious reason to do +this\&. +.PP +.SS "Use with dynamic directory naming" +.PP +It is possible to refer to recent directories using the dynamic directory +name syntax by using the supplied function \fBzsh_directory_name_cdr\fP +a hook: +.PP +.RS +.nf +\fBautoload \-Uz add\-zsh\-hook +add\-zsh\-hook \-Uz zsh_directory_name zsh_directory_name_cdr\fP +.fi +.RE +.PP +When this is done, \fB~[1]\fP will refer to the most recent +directory other than $PWD, and so on\&. Completion after \fB~[\fP\fI\&.\&.\&.\fP +also works\&. +.PP +.SS "Details of directory handling" +.PP +This section is for the curious or confused; most users will not +need to know this information\&. +.PP +Recent directories are saved to a file immediately and hence are +preserved across sessions\&. Note currently no file locking is applied: +the list is updated immediately on interactive commands and nowhere else +(unlike history), and it is assumed you are only going to change +directory in one window at once\&. This is not safe on shared accounts, +but in any case the system has limited utility when someone else is +changing to a different set of directories behind your back\&. +.PP +To make this a little safer, only directory changes instituted from the +command line, either directly or indirectly through shell function calls +(but not through subshells, evals, traps, completion functions and the +like) are saved\&. Shell functions should use \fBcd \-q\fP or \fBpushd \-q\fP to +avoid side effects if the change to the directory is to be invisible at the +command line\&. See the contents of the function \fBchpwd_recent_dirs\fP for +more details\&. +.PP +.SH "ABBREVIATED DYNAMIC REFERENCES TO DIRECTORIES" +.PP +The dynamic directory naming system is described in the subsection +\fIDynamic named directories\fP of +the section \fIFilename Expansion\fP in \fIzshexpn\fP(1)\&. In this, a reference to +\fB~[\fP\fI\&.\&.\&.\fP\fB]\fP is expanded by a function found by the hooks +mechanism\&. +.PP +The contributed function \fBzsh_directory_name_generic\fP 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\&. +.PP +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: +.PD 0 +.TP +.PD +\fBg\fP +The top level directory for your git area\&. This first component +has to match, or the function will return indicating another +directory name hook function should be tried\&. +.TP +\fBp\fP +The name of a project within your git area\&. +.TP +\fBs\fP +The source area within that project\&. +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\&. +.PP +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\&. +.PP +.SS "Usage" +.PP +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\&. +.PP +Then arrange for the wrapper to be run as a zsh_directory_name hook: +.PP +.RS +.nf +\fBautoload \-Uz add\-zsh\-hook zsh_directory_name_generic zdn_mywrapper +add\-zsh\-hook \-U zsh_directory_name zdn_mywrapper\fP +.fi +.RE +.PP +.SS "Configuration" +.PP +The wrapper function should define a local associative array zdn_top\&. +Alternatively, this can be set with a style called \fBmapping\fP\&. The +context for the style is \fB:zdn:\fP\fIwrapper\-name\fP where +\fIwrapper\-name\fP is the function calling zsh_directory_name_generic; +for example: +.PP +.RS +.nf +\fBzstyle :zdn:zdn_mywrapper: mapping zdn_mywrapper_top\fP +.fi +.RE +.PP +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 \fB:default:\fP specifies a variable in the form +\fB/:\fP\fIvar\fP (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 \fBzdn_top\fP have the same format as +\fBzdn_top\fP itself, but contain relative paths\&. +.PP +For example, +.PP +.RS +.nf +\fBlocal \-A zdn_top=( + g ~/git + ga ~/alternate/git + gs /scratch/$USER/git/:second2 + :default: /:second1 +)\fP +.fi +.RE +.PP +This specifies the behaviour of a directory referred to as \fB~[g:\&.\&.\&.]\fP +or \fB~[ga:\&.\&.\&.]\fP or \fB~[gs:\&.\&.\&.]\fP\&. Later path components are optional; +in that case \fB~[g]\fP expands to \fB~/git\fP, and so on\&. \fBgs\fP expands +to \fB/scratch/$USER/git\fP and uses the associative array \fBsecond2\fP to +match the second component; \fBg\fP and \fBga\fP use the associative array +\fBsecond1\fP to match the second component\&. +.PP +When expanding a name to a directory, if the first component is not \fBg\fP or +\fBga\fP or \fBgs\fP, 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)\&. +.PP +For components after the first, a relative path is expected, but note that +multiple levels may still appear\&. Here is an example of \fBsecond1\fP: +.PP +.RS +.nf +\fBlocal \-A second1=( + p myproject + s somproject + os otherproject/subproject/:third +)\fP +.fi +.RE +.PP +The path as found from \fBzdn_top\fP is extended with the matching +directory, so \fB~[g:p]\fP becomes \fB~/git/myproject\fP\&. The slash between +is added automatically (it\&'s not possible to have a later component +modify the name of a directory already matched)\&. Only \fBos\fP specifies +a variable for a third component, and there\&'s no \fB:default:\fP, so it's +an error to use a name like \fB~[g:p:x]\fP or \fB~[ga:s:y]\fP because +there\&'s nowhere to look up the \fBx\fP or \fBy\fP\&. +.PP +The associative arrays need to be visible within this function; the +generic function therefore uses internal variable names beginning +\fB_zdn_\fP in order to avoid clashes\&. Note that the variable \fBreply\fP +needs to be passed back to the shell, so should not be local in the +calling function\&. +.PP +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\&. +.PP +.SS "Complete example" +.PP +Here is a full fictitious but usable autoloadable definition of the +example function defined by the code above\&. So \fB~[gs:p:s]\fP expands +to \fB/scratch/$USER/git/myscratchproject/top/srcdir\fP (with \fB$USER\fP +also expanded)\&. +.PP +.RS +.nf +\fBlocal \-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 "$@\fP +.fi +.RE +.PP +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: +.PP +.RS +.nf +\fBtypeset \-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\fP +.fi +.RE +.PP +and the function \fBzdn_mywrapper\fP would contain only the following: +.PP +.RS +.nf +\fBzsh_directory_name_generic "$@"\fP +.fi +.RE +.PP +.SH "GATHERING INFORMATION FROM VERSION CONTROL SYSTEMS" +.PP +In a lot of cases, it is nice to automatically retrieve information from +version control systems (VCSs), such as subversion, CVS or git, to be able +to provide it to the user; possibly in the user\&'s prompt\&. So that you can +instantly tell which branch you are currently on, for example\&. +.PP +In order to do that, you may use the \fBvcs_info\fP function\&. +.PP +The following VCSs are supported, showing the abbreviated name by which +they are referred to within the system: +.PD 0 +.TP +Bazaar (\fBbzr\fP) +\fBhttps://bazaar\&.canonical\&.com/\fP +.TP +Codeville (\fBcdv\fP) +\fBhttp://freecode\&.com/projects/codeville/\fP +.TP +Concurrent Versioning System (\fBcvs\fP) +\fBhttps://www\&.nongnu\&.org/cvs/\fP +.TP +Darcs (\fBdarcs\fP) +\fBhttp://darcs\&.net/\fP +.TP +Fossil (\fBfossil\fP) +\fBhttps://fossil\-scm\&.org/\fP +.TP +Git (\fBgit\fP) +\fBhttps://git\-scm\&.com/\fP +.TP +GNU arch (\fBtla\fP) +\fBhttps://www\&.gnu\&.org/software/gnu\-arch/\fP +.TP +Mercurial (\fBhg\fP) +\fBhttps://www\&.mercurial\-scm\&.org/\fP +.TP +Monotone (\fBmtn\fP) +\fBhttps://monotone\&.ca/\fP +.TP +Perforce (\fBp4\fP) +\fBhttps://www\&.perforce\&.com/\fP +.TP +Subversion (\fBsvn\fP) +\fBhttps://subversion\&.apache\&.org/\fP +.TP +SVK (\fBsvk\fP) +\fBhttps://svk\&.bestpractical\&.com/\fP +.PD +.PP +There is also support for the patch management system \fBquilt\fP +(\fBhttps://savannah\&.nongnu\&.org/projects/quilt\fP)\&. See +\fBQuilt Support\fP +below for details\&. +.PP +To load \fBvcs_info\fP: +.PP +.RS +.nf +\fBautoload \-Uz vcs_info\fP +.fi +.RE +.PP +It can be used in any existing prompt, because it does not require any +specific \fB$psvar\fP entries to be available\&. +.PP +.PP +.SS "Quickstart" +.PP +To get this feature working quickly (including colors), you can do the +following (assuming, you loaded \fBvcs_info\fP properly \- see above): +.PP +.RS +.nf +\fBzstyle \&':vcs_info:*' actionformats \e + \&'%F{5}(%f%s%F{5})%F{3}\-%F{5}[%F{2}%b%F{3}|%F{1}%a%F{5}]%f ' +zstyle \&':vcs_info:*' formats \e + \&'%F{5}(%f%s%F{5})%F{3}\-%F{5}[%F{2}%b%F{5}]%f ' +zstyle \&':vcs_info:(sv[nk]|bzr):*' branchformat '%b%F{1}:%F{3}%r' +precmd () { vcs_info } +PS1=\&'%F{5}[%F{2}%n%F{5}] %F{3}%3~ ${vcs_info_msg_0_}%f%# '\fP +.fi +.RE +.PP +Obviously, the last two lines are there for demonstration\&. You need to +call \fBvcs_info\fP from your \fBprecmd\fP function\&. Once that is done you need +a \fIsingle quoted\fP \fB\&'${vcs_info_msg_0_}'\fP in your prompt\&. +.PP +To be able to use \fB\&'${vcs_info_msg_0_}'\fP directly in your prompt like +this, you will need to have the \fBPROMPT_SUBST\fP option enabled\&. +.PP +Now call the \fBvcs_info_printsys\fP utility from the command line: +.PP +.RS +.nf +\fB% vcs_info_printsys +## list of supported version control backends: +## disabled systems are prefixed by a hash sign (#) +bzr +cdv +cvs +darcs +fossil +git +hg +mtn +p4 +svk +svn +tla +## flavours (cannot be used in the enable or disable styles; they +## are enabled and disabled with their master [git\-svn \-> git]) +## they *can* be used in contexts: \&':vcs_info:git\-svn:*'\&. +git\-p4 +git\-svn +hg\-git +hg\-hgsubversion +hg\-hgsvn\fP +.fi +.RE +.PP +You may not want all of these because there is no point in running the +code to detect systems you do not use\&. So there is a way to disable +some backends altogether: +.PP +.RS +.nf +\fBzstyle \&':vcs_info:*' disable bzr cdv darcs mtn svk tla\fP +.fi +.RE +.PP +You may also pick a few from that list and enable only those: +.PP +.RS +.nf +\fBzstyle \&':vcs_info:*' enable git cvs svn\fP +.fi +.RE +.PP +If you rerun \fBvcs_info_printsys\fP after one of these commands, you will +see the backends listed in the \fBdisable\fP style (or backends not in the +\fBenable\fP style \- if you used that) marked as disabled by a hash sign\&. +That means the detection of these systems is skipped \fIcompletely\fP\&. No +wasted time there\&. +.PP +.SS "Configuration" +.PP +The \fBvcs_info\fP feature can be configured via \fBzstyle\fP\&. +.PP +First, the context in which we are working: +.RS +.nf +\fB:vcs_info:\fIvcs\-string\fP:\fIuser\-context\fP:\fIrepo\-root\-name\fP\fP +.fi +.RE +.PP +.PD 0 +.TP +.PD +\fIvcs\-string\fP +is one of: \fBgit\fP, \fBgit\-svn\fP, \fBgit\-p4\fP, \fBhg\fP, \fBhg\-git\fP, +\fBhg\-hgsubversion\fP, \fBhg\-hgsvn\fP, \fBdarcs\fP, \fBbzr\fP, \fBcdv\fP, \fBmtn\fP, +\fBsvn\fP, \fBcvs\fP, \fBsvk\fP, \fBtla\fP, \fBp4\fP or \fBfossil\fP\&. +This is followed by `\fB\&.quilt\-\fP\fIquilt\-mode\fP\&' in Quilt mode +(see \fBQuilt Support\fP for details) +and by `\fB+\fP\fIhook\-name\fP\&' while hooks are active +(see \fBHooks in vcs_info\fP for details)\&. +.RS +.PP + +Currently, hooks in quilt mode don\&'t add the `\fB\&.quilt\-\fP\fIquilt\-mode\fP' information\&. +This may change in the future\&. +.RE +.TP +\fIuser\-context\fP +is a freely configurable string, assignable by +the user as the first argument to \fBvcs_info\fP (see its description +below)\&. +.TP +\fIrepo\-root\-name\fP +is the name of a repository in which you want a +style to match\&. So, if you want a setting specific to \fB/usr/src/zsh\fP, +with that being a CVS checkout, you can set \fIrepo\-root\-name\fP to +\fBzsh\fP to make it so\&. +.PP +There are three special values for \fIvcs\-string\fP: The first is named +\fB\-init\-\fP, that is in effect as long as there was no decision what VCS +backend to use\&. The second is \fB\-preinit\-\fP; it is used \fIbefore\fP +\fBvcs_info\fP is run, when initializing the data exporting variables\&. The +third special value is \fBformats\fP and is used by the \fBvcs_info_lastmsg\fP +for looking up its styles\&. +.PP +The initial value of \fIrepo\-root\-name\fP is \fB\-all\-\fP and it is replaced +with the actual name, as soon as it is known\&. Only use this part of the +context for defining the \fBformats\fP, \fBactionformats\fP or +\fBbranchformat\fP styles, as it is guaranteed that \fIrepo\-root\-name\fP is +set up correctly for these only\&. For all other styles, just use \fB\&'*'\fP +instead\&. +.PP +There are two pre\-defined values for \fIuser\-context\fP: +.PD 0 +.TP +\fBdefault\fP +the one used if none is specified +.TP +\fBcommand\fP +used by vcs_info_lastmsg to lookup its styles +.PD +.PP +You can of course use \fB\&':vcs_info:*'\fP to match all VCSs in all +user\-contexts at once\&. +.PP +This is a description of all styles that are looked up\&. +.PP +.PD 0 +.TP +.PD +\fBformats\fP +A list of formats, used when actionformats is not used +(which is most of the time)\&. +.TP +\fBactionformats\fP +A list of formats, used if there is a special +action going on in your current repository; like an interactive rebase or +a merge conflict\&. +.TP +\fBbranchformat\fP +Some backends replace \fB%b\fP in the formats and +actionformats styles above, not only by a branch name but also by a +revision number\&. This style lets you modify how that string should look\&. +.TP +\fBnvcsformats\fP +These "formats" are set when we didn\&'t detect a version control system +for the current directory or \fBvcs_info\fP was disabled\&. This is useful if +you want \fBvcs_info\fP to completely take over the generation of your +prompt\&. You would do something like \fBPS1=\&'${vcs_info_msg_0_}'\fP to +accomplish that\&. +.TP +\fBhgrevformat\fP +\fBhg\fP uses both a hash and a revision number to reference a specific +changeset in a repository\&. With this style you can format the revision +string (see \fBbranchformat\fP) to include either or both\&. It\&'s only +useful when \fBget\-revision\fP is true\&. Note, the full 40\-character revision id +is not available (except when using the \fBuse\-simple\fP option) because +executing hg more than once per prompt is too slow; you may customize this +behavior using hooks\&. +.TP +\fBmax\-exports\fP +Defines the maximum number of +\fBvcs_info_msg_*_\fP variables \fBvcs_info\fP will set\&. +.TP +\fBenable\fP +A list of backends you want to use\&. Checked in the \fB\-init\-\fP context\&. If +this list contains an item called \fBNONE\fP no backend is used at all and +\fBvcs_info\fP will do nothing\&. If this list contains \fBALL\fP, \fBvcs_info\fP +will use all known backends\&. Only with \fBALL\fP in \fBenable\fP will the +\fBdisable\fP style have any effect\&. \fBALL\fP and \fBNONE\fP are case insensitive\&. +.TP +\fBdisable\fP +A list of VCSs you don\&'t want \fBvcs_info\fP to test for +repositories (checked in the \fB\-init\-\fP context, too)\&. Only used if +\fBenable\fP contains \fBALL\fP\&. +.TP +\fBdisable\-patterns\fP +A list of patterns that are checked against \fB$PWD\fP\&. If a pattern +matches, \fBvcs_info\fP will be disabled\&. This style is checked in the +\fB:vcs_info:\-init\-:*:\-all\-\fP context\&. +.RS +.PP +Say, \fB~/\&.zsh\fP is a directory under version control, in which you do +not want \fBvcs_info\fP to be active, do: +.RS +.nf +\fBzstyle \&':vcs_info:*' disable\-patterns "${(b)HOME}/\&.zsh(|/*)"\fP +.fi +.RE +.RE +.TP +\fBuse\-quilt\fP +If enabled, the \fBquilt\fP support code is active in `addon\&' mode\&. +See \fBQuilt Support\fP for details\&. +.TP +\fBquilt\-standalone\fP +If enabled, `standalone\&' mode detection is attempted if no VCS is active +in a given directory\&. See \fBQuilt Support\fP for details\&. +.TP +\fBquilt\-patch\-dir\fP +Overwrite the value of the \fB$QUILT_PATCHES\fP environment variable\&. See +\fBQuilt Support\fP for details\&. +.TP +\fBquiltcommand\fP +When \fBquilt\fP itself is called in quilt support, the value of this style +is used as the command name\&. +.TP +\fBcheck\-for\-changes\fP +If enabled, this style causes the \fB%c\fP and \fB%u\fP format escapes to show +when the working directory has uncommitted changes\&. The strings displayed by +these escapes can be controlled via the \fBstagedstr\fP and \fBunstagedstr\fP +styles\&. The only backends that currently support this option are \fBgit\fP, +\fBhg\fP, and \fBbzr\fP (the latter two only support unstaged)\&. +.RS +.PP +For this style to be evaluated with the \fBhg\fP backend, the \fBget\-revision\fP +style needs to be set and the \fBuse\-simple\fP style needs to be unset\&. The +latter is the default; the former is not\&. +.PP +With the \fBbzr\fP backend, \fIlightweight checkouts\fP only honor this style if +the \fBuse\-server\fP style is set\&. +.PP +Note, the actions taken if this style is enabled are potentially expensive +(read: they may be slow, depending on how big the current repository is)\&. +Therefore, it is disabled by default\&. +.RE +.TP +\fBcheck\-for\-staged\-changes\fP +This style is like \fBcheck\-for\-changes\fP, but it never checks the worktree +files, only the metadata in the \fB\&.${vcs}\fP dir\&. Therefore, +this style initializes only the \fB%c\fP escape (with \fBstagedstr\fP) but +not the \fB%u\fP escape\&. This style is faster than \fBcheck\-for\-changes\fP\&. +.RS +.PP +In the \fBgit\fP backend, this style checks for changes in the index\&. +Other backends do not currently implement this style\&. +.PP +This style is disabled by default\&. +.RE +.TP +\fBstagedstr\fP +This string will be used in the \fB%c\fP escape if there are staged changes in +the repository\&. +.TP +\fBunstagedstr\fP +This string will be used in the \fB%u\fP escape if there are unstaged changes +in the repository\&. +.TP +\fBcommand\fP +This style causes \fBvcs_info\fP to use the supplied string as the command +to use as the VCS\&'s binary\&. Note, that setting this in '\fB:vcs_info:*\fP' is +not a good idea\&. +.RS +.PP +If the value of this style is empty (which is the default), the used binary +name is the name of the backend in use (e\&.g\&. \fBsvn\fP is used in an \fBsvn\fP +repository)\&. +.PP +The \fBrepo\-root\-name\fP part in the context is always the default \fB\-all\-\fP +when this style is looked up\&. +.PP +For example, this style can be used to use binaries from non\-default +installation directories\&. Assume, \fBgit\fP is installed in /usr/bin but +your sysadmin installed a newer version in /usr/local/bin\&. Instead of +changing the order of your \fB$PATH\fP parameter, you can do this: +.RS +.nf +\fBzstyle \&':vcs_info:git:*:\-all\-' command /usr/local/bin/git\fP +.fi +.RE +.RE +.TP +\fBuse\-server\fP +This is used by the Perforce backend (\fBp4\fP) to decide if it should +contact the Perforce server to find out if a directory is managed +by Perforce\&. This is the only reliable way of doing this, but runs +the risk of a delay if the server name cannot be found\&. If the +server (more specifically, the \fIhost\fP\fB:\fP\fIport\fP pair describing the +server) cannot be contacted, its name is put into the associative array +\fBvcs_info_p4_dead_servers\fP and is not contacted again during the session +until it is removed by hand\&. If you do not set this style, the \fBp4\fP +backend is only usable if you have set the environment variable +\fBP4CONFIG\fP to a file name and have corresponding files in the root +directories of each Perforce client\&. See comments in the function +\fBVCS_INFO_detect_p4\fP for more detail\&. +.RS +.PP +The Bazaar backend (\fBbzr\fP) uses this to permit contacting the server +about lightweight checkouts, see the \fBcheck\-for\-changes\fP style\&. +.RE +.TP +\fBuse\-simple\fP +If there are two different ways of gathering +information, you can select the simpler one by setting this style to true; +the default is to use the not\-that\-simple code, which is potentially a lot +slower but might be more accurate in all possible cases\&. This style is +used by the \fBbzr\fP, \fBhg\fP, and \fBgit\fP backends\&. In the case of \fBhg\fP it will invoke +the external hexdump program to parse the binary dirstate cache file; this +method will not return the local revision number\&. +.TP +\fBget\-revision\fP +If set to true, vcs_info goes the extra mile to figure out the revision of +a repository\&'s work tree (currently for the \fBgit\fP and \fBhg\fP backends, +where this kind of information is not always vital)\&. For \fBgit\fP, the +hash value of the currently checked out commit is available via the \fB%i\fP +expansion\&. With \fBhg\fP, the local revision number and the corresponding +global hash are available via \fB%i\fP\&. +.TP +\fBget\-mq\fP +If set to true, the \fBhg\fP backend will look for a Mercurial Queue (\fBmq\fP) +patch directory\&. Information will be available via the `\fB%m\fP\&' replacement\&. +.TP +\fBget\-bookmarks\fP +If set to true, the \fBhg\fP backend will try to get a list of current +bookmarks\&. They will be available via the `\fB%m\fP\&' replacement\&. +.RS +.PP +The default is to generate a comma\-separated list of all bookmark names +that refer to the currently checked out revision\&. If a bookmark is active, +its name is suffixed an asterisk and placed first in the list\&. +.RE +.TP +\fBuse\-prompt\-escapes\fP +Determines if we assume that the assembled +string from \fBvcs_info\fP includes prompt escapes\&. (Used by +\fBvcs_info_lastmsg\fP\&.) +.TP +\fBdebug\fP +Enable debugging output to track possible problems\&. Currently this style +is only used by \fBvcs_info\fP\&'s hooks system\&. +.TP +\fBhooks\fP +A list style that defines hook\-function names\&. See \fBHooks in vcs_info\fP +below for details\&. +.TP +.PD 0 +\fBpatch\-format\fP +.TP +.PD +\fBnopatch\-format\fP +This pair of styles format the patch information used by the \fB%m\fP expando in +formats and actionformats for the \fBgit\fP and \fBhg\fP backends\&. The value is +subject to certain \fB%\fP\-expansions described below\&. +The expanded value is made available in the global \fBbackend_misc\fP array as +\fB${backend_misc[patches]}\fP (also if a \fBset\-patch\-format\fP hook is used)\&. +.TP +\fBget\-unapplied\fP +This boolean style controls whether a backend should attempt to gather a list +of unapplied patches (for example with Mercurial Queue patches)\&. +.RS +.PP +Used by the \fBquilt\fP, \fBhg\fP, and \fBgit\fP backends\&. +.RE +.PP +The default values for these styles in all contexts are: +.PP +.PD 0 +.TP +\fBformats\fP +" (%s)\-[%b]%u%c\-" +.TP +\fBactionformats\fP +" (%s)\-[%b|%a]%u%c\-" +.TP +\fBbranchformat\fP +"%b:%r" (for bzr, svn, svk and hg) +.TP +\fBnvcsformats\fP +"" +.TP +\fBhgrevformat\fP +"%r:%h" +.TP +\fBmax\-exports\fP +2 +.TP +\fBenable\fP +ALL +.TP +\fBdisable\fP +(empty list) +.TP +\fBdisable\-patterns\fP +(empty list) +.TP +\fBcheck\-for\-changes\fP +false +.TP +\fBcheck\-for\-staged\-changes\fP +false +.TP +\fBstagedstr\fP +(string: "S") +.TP +\fBunstagedstr\fP +(string: "U") +.TP +\fBcommand\fP +(empty string) +.TP +\fBuse\-server\fP +false +.TP +\fBuse\-simple\fP +false +.TP +\fBget\-revision\fP +false +.TP +\fBget\-mq\fP +true +.TP +\fBget\-bookmarks\fP +false +.TP +\fBuse\-prompt\-escapes\fP +true +.TP +\fBdebug\fP +false +.TP +\fBhooks\fP +(empty list) +.TP +\fBuse\-quilt\fP +false +.TP +\fBquilt\-standalone\fP +false +.TP +\fBquilt\-patch\-dir\fP +empty \- use \fB$QUILT_PATCHES\fP +.TP +\fBquiltcommand\fP +quilt +.TP +\fBpatch\-format\fP +\fIbackend dependent\fP +.TP +\fBnopatch\-format\fP +\fIbackend dependent\fP +.TP +\fBget\-unapplied\fP +false +.PD +.PP +In normal \fBformats\fP and \fBactionformats\fP the following replacements are +done: +.PP +.PD 0 +.TP +\fB%s\fP +The VCS in use (git, hg, svn, etc\&.)\&. +.TP +\fB%b\fP +Information about the current branch\&. +.TP +\fB%a\fP +An identifier that describes the action\&. Only makes sense in +\fBactionformats\fP\&. +.TP +\fB%i\fP +The current revision number or identifier\&. For \fBhg\fP +the \fBhgrevformat\fP style may be used to customize the output\&. +.TP +\fB%c\fP +The string from the \fBstagedstr\fP style if there are staged +changes in the repository\&. +.TP +\fB%u\fP +The string from the \fBunstagedstr\fP style if there are +unstaged changes in the repository\&. +.TP +\fB%R\fP +The base directory of the repository\&. +.TP +\fB%r\fP +The repository name\&. If \fB%R\fP is \fB/foo/bar/repoXY\fP, \fB%r\fP +is \fBrepoXY\fP\&. +.TP +\fB%S\fP +A subdirectory within a repository\&. If \fB$PWD\fP is +\fB/foo/bar/repoXY/beer/tasty\fP, \fB%S\fP is \fBbeer/tasty\fP\&. +.PD +.PD 0 +.TP +.PD +\fB%m\fP +A "misc" replacement\&. It is at the discretion of the backend to +decide what this replacement expands to\&. +.RS +.PP +The \fBhg\fP and \fBgit\fP backends use this expando to display patch information\&. +\fBhg\fP sources patch information from the \fBmq\fP extensions; \fBgit\fP from in\-progress +\fBrebase\fP and \fBcherry\-pick\fP operations and from the \fBstgit\fP extension\&. The \fBpatch\-format\fP +and \fBnopatch\-format\fP 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\&. +.PP +The \fBhg\fP backend displays bookmark information in this expando (in addition +to \fBmq\fP information)\&. See the \fBget\-mq\fP and \fBget\-bookmarks\fP 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)\&. +.PP +The \fBquilt\fP `standalone\&' backend sets this expando to the same value as the +\fB%Q\fP expando\&. +.RE +.TP +\fB%Q\fP +Quilt series information\&. +When quilt is used (either in `addon\&' mode or as a `standalone' backend), +this expando is set to the quilt series\&' \fBpatch\-format\fP string\&. +The \fBset\-patch\-format\fP hook and \fBnopatch\-format\fP style are honoured\&. +.RS +.PP +See \fBQuilt Support\fP below for details\&. +.RE +.PP +In \fBbranchformat\fP these replacements are done: +.PP +.PD 0 +.TP +\fB%b\fP +The branch name\&. For \fBhg\fP, the branch name can include a +topic name\&. +.TP +\fB%r\fP +The current revision number or the \fBhgrevformat\fP style for +\fBhg\fP\&. +.PD +.PP +In \fBhgrevformat\fP these replacements are done: +.PP +.PD 0 +.TP +\fB%r\fP +The current local revision number\&. +.TP +\fB%h\fP +The current global revision identifier\&. +.PD +.PP +In \fBpatch\-format\fP and \fBnopatch\-format\fP these replacements are done: +.PP +.PD 0 +.TP +\fB%p\fP +The name of the top\-most applied patch; may be overridden by the \fBapplied\-string\fP hook\&. +.TP +\fB%u\fP +The number of unapplied patches; may be overridden by the \fBunapplied\-string\fP hook\&. +.TP +\fB%n\fP +The number of applied patches\&. +.TP +\fB%c\fP +The number of unapplied patches\&. +.TP +\fB%a\fP +The number of all patches (\fB%a = %n + %c\fP)\&. +.TP +\fB%g\fP +The names of active \fBmq\fP guards (\fBhg\fP backend)\&. +.TP +\fB%G\fP +The number of active \fBmq\fP guards (\fBhg\fP backend)\&. +.PD +.PP +Not all VCS backends have to support all replacements\&. For \fBnvcsformats\fP +no replacements are performed at all, it is just a string\&. +.PP +.SS "Oddities" +.PP +If you want to use the \fB%b\fP (bold off) prompt expansion in \fBformats\fP, +which expands \fB%b\fP itself, use \fB%%b\fP\&. That will cause the \fBvcs_info\fP +expansion to replace \fB%%b\fP with \fB%b\fP, so that zsh\&'s prompt expansion +mechanism can handle it\&. Similarly, to hand down \fB%b\fP from +\fBbranchformat\fP, use \fB%%%%b\fP\&. 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\&. +.PP +When one of the \fBgen\-applied\-string\fP, \fBgen\-unapplied\-string\fP, and +\fBset\-patch\-format\fP hooks is defined, +applying \fB%\fP\-escaping (`\fBfoo=${foo//\&'%'/%%}\fP') to the interpolated values +for use in the prompt is the responsibility of those hooks (jointly); +when neither of those hooks is defined, \fBvcs_info\fP handles escaping by itself\&. +We regret this coupling, but it was required for backwards compatibility\&. +.PP +.SS "Quilt Support" +.PP +\fBQuilt\fP is not a version control system, therefore this is not implemented +as a backend\&. It can help keeping track of a series of patches\&. People use it +to keep a set of changes they want to use on top of software packages (which +is tightly integrated into the package build process \- the Debian project +does this for a large number of packages)\&. Quilt can also help individual +developers keep track of their own patches on top of real version control +systems\&. +.PP +The \fBvcs_info\fP integration tries to support both ways of using quilt by +having two slightly different modes of operation: `addon\&' mode and +`standalone\&' mode)\&. +.PP +Quilt integration is off by default; to enable it, set the \fBuse\-quilt\fP style, +and add \fB%Q\fP to your \fBformats\fP or \fBactionformats\fP style: +.RS +.nf +\fBzstyle \&':vcs_info:*' use\-quilt true\fP +.fi +.RE +.PP +Styles looked up from the Quilt support code include `\fB\&.quilt\-\fP\fIquilt\-mode\fP\&' +in the \fIvcs\-string\fP part of the context, where \fIquilt\-mode\fP is either +\fBaddon\fP or \fBstandalone\fP\&. +Example: \fB:vcs_info:git\&.quilt\-addon:default:\fP\fIrepo\-root\-name\fP\&. +.PP +For `addon\&' mode to become active \fBvcs_info\fP 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 `\fBQUILT_PATCHES\fP\&' environment variable\&. If that +variable exists its value is used, otherwise the value `\fBpatches\fP\&' is +assumed\&. The value from \fB$QUILT_PATCHES\fP can be overwritten using the +`\fBquilt\-patch\-dir\fP\&' style\&. (Note: you can use \fBvcs_info\fP to keep the value +of \fB$QUILT_PATCHES\fP correct all the time via the \fBpost\-quilt\fP hook)\&. +.PP +When the directory in question is found, quilt is assumed to be active\&. To +gather more information, \fBvcs_info\fP looks for a directory called `\&.pc\&'; +Quilt uses that directory to track its current state\&. If this directory does +not exist we know that quilt has not done anything to the working directory +(read: no patches have been applied yet)\&. +.PP +If patches are applied, \fBvcs_info\fP will try to find out which\&. If you want +to know which patches of a series are not yet applied, you need to activate +the \fBget\-unapplied\fP style in the appropriate context\&. +.PP +\fBvcs_info\fP allows for very detailed control over how the gathered +information is presented (see +the \fBConfiguration\fP and \fBHooks in vcs_info\fP sections), +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 \fBstgit\fP for \fBgit\fP, or \fBmq\fP for \fBhg\fP); the configuration +for systems like that are generally configured the same way as the \fBquilt\fP +support\&. +.PP +If the \fBquilt\fP support is working in `addon\&' mode, the produced string is +available as a simple format replacement (\fB%Q\fP to be precise), which can +be used in \fBformats\fP and \fBactionformats\fP; see below for details)\&. +.PP +If, on the other hand, the support code is working in `standalone\&' mode, +\fBvcs_info\fP will pretend as if \fBquilt\fP were an actual version control +system\&. That means that the version control system identifier (which +otherwise would be something like `svn\&' or `cvs') will be set to +`\fB\-quilt\-\fP\&'\&. This has implications on the used style context where this +identifier is the second element\&. \fBvcs_info\fP 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 \fB%Q\fP for compatibility with `addon\&' mode)\&. +.PP +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 +enabled all the time in every directory that is not otherwise under version +control\&. If you know there is only a limited set of trees where you would +like \fBvcs_info\fP to try and look for Quilt in `standalone\&' mode to minimise +the amount of searching on every call to \fBvcs_info\fP, there are a number of +ways to do that: +.PP +Essentially, `standalone\&' mode detection is controlled by a style called +`\fBquilt\-standalone\fP\&'\&. It is a string style and its value can have different +effects\&. The simplest values are: `\fBalways\fP\&' to run detection every time +\fBvcs_info\fP is run, and `\fBnever\fP\&' to turn the detection off entirely\&. +.PP +If the value of \fBquilt\-standalone\fP is something else, it is interpreted +differently\&. If the value is the name of a scalar variable the value of that +variable is checked and that value is used in the same `always\&'/`never' way +as described above\&. +.PP +If the value of \fBquilt\-standalone\fP is an array, the elements of that array +are used as directory names under which you want the detection to be active\&. +.PP +If \fBquilt\-standalone\fP is an associative array, the keys are taken as +directory names under which you want the detection to be active, but only if +the corresponding value is the string `\fBtrue\fP\&'\&. +.PP +Last, but not least, if the value of \fBquilt\-standalone\fP is the name of a +function, the function is called without arguments and the return value +decides whether detection should be active\&. A `0\&' return value is true; a +non\-zero return value is interpreted as false\&. +.PP +Note, if there is both a function and a variable by the name of +\fBquilt\-standalone\fP, the function will take precedence\&. +.PP +.SS "Function Descriptions (Public API)" +.PP +.PD 0 +.TP +.PD +\fBvcs_info\fP [\fIuser\-context\fP] +The main function, that runs all backends and assembles all data into +\fB${vcs_info_msg_*_}\fP\&. This is the function you want to call from +\fBprecmd\fP if you want to include up\-to\-date information in your prompt (see +\fBVariable Description\fP +below)\&. If an argument is given, that string will be +used instead of \fBdefault\fP in the \fIuser\-context\fP field of the style +context\&. +.TP +\fBvcs_info_hookadd\fP +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 `\fB+vi\-\fP\&' prefix needs to be left out +here\&. See \fBHooks in vcs_info\fP +below for details\&. +.TP +\fBvcs_info_hookdel\fP +Remove hook\-functions from a given hook\&. The hook needs to be given as the +first non\-option argument; what follows is a list of hook\-function +names to un\-register from the hook\&. If `\fB\-a\fP\&' is used as the first +argument, \fBall\fP 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 `\fB+vi\-\fP\&' prefix needs to be left out here\&. +See \fBHooks in vcs_info\fP +below for details\&. +.TP +\fBvcs_info_lastmsg\fP +Outputs the current values of \fB${vcs_info_msg_*_}\fP\&. +Takes into account the value of the \fBuse\-prompt\-escapes\fP style in +\fB\&':vcs_info:formats:command:\-all\-'\fP\&. It also only prints \fBmax\-exports\fP +values\&. +.TP +\fBvcs_info_printsys\fP [\fIuser\-context\fP] +Prints a list of all +supported version control systems\&. Useful to find out possible contexts +(and which of them are enabled) or values for the \fBdisable\fP style\&. +.TP +\fBvcs_info_setsys\fP +Initializes \fBvcs_info\fP\&'s internal list of +available backends\&. With this function, you can add support for new VCSs +without restarting the shell\&. +.PP +All functions named \fBVCS_INFO_*\fP are for internal use only\&. +.PP +.SS "Variable Description" +.PP +.PD 0 +.TP +.PD +\fB${vcs_info_msg_\fP\fIN\fP\fB_}\fP (Note the trailing underscore) +Where \fIN\fP is an integer, e\&.g\&., \fBvcs_info_msg_0_\fP\&. These variables +are the storage for the informational message the last \fBvcs_info\fP call +has assembled\&. These are strongly connected to the \fBformats\fP, +\fBactionformats\fP and \fBnvcsformats\fP styles described above\&. Those styles +are lists\&. The first member of that list gets expanded into +\fB${vcs_info_msg_0_}\fP, the second into \fB${vcs_info_msg_1_}\fP +and the Nth into \fB${vcs_info_msg_N\-1_}\fP\&. (See the \fBmax\-exports\fP +style above\&.) +.PP +All variables named \fBVCS_INFO_*\fP are for internal use only\&. +.PP +.SS "Hooks in vcs_info" +.PP +Hooks are places in \fBvcs_info\fP where you can run your own code\&. That +code can communicate with the code that called it and through that, +change the system\&'s behaviour\&. +.PP +For configuration, hooks change the style context: +.RS +.nf +\fB:vcs_info:\fIvcs\-string\fP+\fIhook\-name\fP:\fIuser\-context\fP:\fIrepo\-root\-name\fP\fP +.fi +.RE +.PP +To register functions to a hook, you need to list them in the \fBhooks\fP +style in the appropriate context\&. +.PP +Example: +.RS +.nf +\fBzstyle \&':vcs_info:*+foo:*' hooks bar baz\fP +.fi +.RE +.PP +This registers functions to the hook `foo\&' for all backends\&. In order to +avoid namespace problems, all registered function names are prepended by +a `\fB+vi\-\fP\&', so the actual functions called for the `foo' hook are +`\fB+vi\-bar\fP\&' and `\fB+vi\-baz\fP'\&. +.PP +If you would like to register a function to a hook regardless of the +current context, you may use the \fBvcs_info_hookadd\fP function\&. To remove +a function that was added like that, the \fBvcs_info_hookdel\fP function +can be used\&. +.PP +If something seems weird, you can enable the `debug\&' boolean style in +the proper context and the hook\-calling code will print what it tried +to execute and whether the function in question existed\&. +.PP +When you register more than one function to a hook, all functions are +executed one after another until one function returns non\-zero or until +all functions have been called\&. Context\-sensitive hook functions are +executed \fBbefore\fP statically registered ones (the ones added by +\fBvcs_info_hookadd\fP)\&. +.PP +You may pass data between functions via an associative array, \fBuser_data\fP\&. +For example: +.RS +.nf +\fB ++vi\-git\-myfirsthook(){ + user_data[myval]=$myval +} ++vi\-git\-mysecondhook(){ + # do something with ${user_data[myval]} +}\fP +.fi +.RE +.PP +There are a number of variables that are special in hook contexts: +.PP +.PD 0 +.TP +.PD +\fBret\fP +The return value that the hooks system will return to the caller\&. The +default is an integer `zero\&'\&. If and how a changed \fBret\fP value changes +the execution of the caller depends on the specific hook\&. See the hook +documentation below for details\&. +.TP +\fBhook_com\fP +An associated array which is used for bidirectional communication from +the caller to hook functions\&. The used keys depend on the specific hook\&. +.TP +\fBcontext\fP +The active context of the hook\&. Functions that wish to change this +variable should make it local scope first\&. +.TP +\fBvcs\fP +The current VCS after it was detected\&. The same values as in the +enable/disable style are used\&. Available in all hooks except \fBstart\-up\fP\&. +.PP +Finally, the full list of currently available hooks: +.PP +.PD 0 +.TP +.PD +\fBstart\-up\fP +Called after starting \fBvcs_info\fP but before the VCS in this directory is +determined\&. It can be used to deactivate \fBvcs_info\fP temporarily if +necessary\&. When \fBret\fP is set to \fB1\fP, \fBvcs_info\fP aborts and does +nothing; when set to \fB2\fP, \fBvcs_info\fP sets up everything as if no +version control were active and exits\&. +.TP +\fBpre\-get\-data\fP +Same as \fBstart\-up\fP but after the VCS was detected\&. +.TP +\fBgen\-hg\-bookmark\-string\fP +Called in the Mercurial backend when a bookmark string is generated; the +\fBget\-revision\fP and \fBget\-bookmarks\fP styles must be true\&. +.RS +.PP +This hook gets the names of the Mercurial bookmarks that +\fBvcs_info\fP collected from `hg\&'\&. +.PP +If a bookmark is active, the key \fB${hook_com[hg\-active\-bookmark]}\fP is +set to its name\&. The key is otherwise unset\&. +.PP +When setting \fBret\fP to non\-zero, the string in +\fB${hook_com[hg\-bookmark\-string]}\fP will be used in the \fB%m\fP escape in +\fBformats\fP and \fBactionformats\fP and will be available in the global +\fBbackend_misc\fP array as \fB${backend_misc[bookmarks]}\fP\&. +.RE +.TP +\fBgen\-applied\-string\fP +Called in the \fBgit\fP (with \fBstgit\fP or during rebase or merge), and \fBhg\fP +(with \fBmq\fP) backends and in \fBquilt\fP support when the \fBapplied\-string\fP +is generated; the \fBuse\-quilt\fP zstyle must be true for \fBquilt\fP (the \fBmq\fP +and \fBstgit\fP backends are active by default)\&. +.RS +.PP +The arguments to this hook describe applied patches +in the opposite order, which means that the first argument is the +top\-most patch and so forth\&. +.PP +When the patches\&' log messages can be extracted, those are embedded +within each argument after a space, so each argument is of the form +`\fIpatch\-name\fP \fIfirst line of the log message\fP\&', where \fIpatch\-name\fP +contains no whitespace\&. The \fBmq\fP backend passes arguments of +the form `\fIpatch name\fP\&', with possible embedded spaces, but without +extracting the patch\&'s log message\&. +.PP +When setting \fBret\fP to non\-zero, the string in +\fB${hook_com[applied\-string]}\fP will be +available as \fB%p\fP in the \fBpatch\-format\fP and \fBnopatch\-format\fP styles\&. +This hook is, in concert with \fBset\-patch\-format\fP, responsible for +\fB%\fP\-escaping that value for use in the prompt\&. +(See the \fBOddities\fP section\&.) +.PP +The \fBquilt\fP backend passes to this hook the inputs +\fB${hook_com[quilt\-patches\-dir]}\fP and, if it has been +determined, \fB${hook_com[quilt\-pc\-dir]}\fP\&. +.RE +.TP +\fBgen\-unapplied\-string\fP +Called in the \fBgit\fP (with \fBstgit\fP or during rebase), and \fBhg\fP (with +\fBmq\fP) backend and in \fBquilt\fP support when the \fBunapplied\-string\fP is +generated; the \fBget\-unapplied\fP style must be true\&. +.RS +.PP +This hook gets the names of all unapplied patches which \fBvcs_info\fP +in order, which means that the first argument is +the patch next\-in\-line to be applied and so forth\&. +.PP +The format of each argument is as for \fBgen\-applied\-string\fP, above\&. +.PP +When setting \fBret\fP to non\-zero, the string in +\fB${hook_com[unapplied\-string]}\fP will be available as \fB%u\fP in the +\fBpatch\-format\fP and \fBnopatch\-format\fP styles\&. +This hook is, in concert with \fBset\-patch\-format\fP, responsible for +\fB%\fP\-escaping that value for use in the prompt\&. +(See the \fBOddities\fP section\&.) +.PP +The \fBquilt\fP backend passes to this hook the inputs +\fB${hook_com[quilt\-patches\-dir]}\fP and, if it has been +determined, \fB${hook_com[quilt\-pc\-dir]}\fP\&. +.RE +.TP +\fBgen\-mqguards\-string\fP +Called in the \fBhg\fP backend when \fBguards\-string\fP is generated; the +\fBget\-mq\fP style must be true (default)\&. +.RS +.PP +This hook gets the names of any active \fBmq\fP guards\&. +.PP +When setting \fBret\fP to non\-zero, the string in +\fB${hook_com[guards\-string]}\fP will be used in the \fB%g\fP escape in the +\fBpatch\-format\fP and \fBnopatch\-format\fP styles\&. +.RE +.TP +\fBno\-vcs\fP +This hooks is called when no version control system was detected\&. +.RS +.PP +The `\fBhook_com\fP\&' parameter is not used\&. +.RE +.TP +\fBpost\-backend\fP +Called as soon as the backend has finished collecting information\&. +.RS +.PP +The `\fBhook_com\fP\&' keys available are as for the \fBset\-message\fP hook\&. +.RE +.TP +\fBpost\-quilt\fP +Called after the \fBquilt\fP support is done\&. The following information +is passed as arguments to the hook: 1\&. the quilt\-support mode (`addon\&' or +`standalone\&'); 2\&. the directory that contains the patch series; 3\&. the +directory that holds quilt\&'s status information (the `\&.pc' directory) or +the string \fB"\-nopc\-"\fP if that directory wasn\&'t found\&. +.RS +.PP +The `hook_com\&' parameter is not used\&. +.RE +.TP +\fBset\-branch\-format\fP +Called before `\fBbranchformat\fP\&' is set\&. The only argument to the +hook is the format that is configured at this point\&. +.RS +.PP +The `\fBhook_com\fP\&' keys considered are `\fBbranch\fP' and `\fBrevision\fP'\&. +They are set to the values figured out so far by \fBvcs_info\fP and any +change will be used directly when the actual replacement is done\&. +.PP +If \fBret\fP is set to non\-zero, the string in +\fB${hook_com[branch\-replace]}\fP will be used unchanged as the +`\fB%b\fP\&' replacement in the variables set by \fBvcs_info\fP\&. +.RE +.TP +\fBset\-hgrev\-format\fP +Called before a `\fBhgrevformat\fP\&' is set\&. The only argument to the +hook is the format that is configured at this point\&. +.RS +.PP +The `\fBhook_com\fP\&' keys considered are `\fBhash\fP' and `\fBlocalrev\fP'\&. +They are set to the values figured out so far by \fBvcs_info\fP and any +change will be used directly when the actual replacement is done\&. +.PP +If \fBret\fP is set to non\-zero, the string in +\fB${hook_com[rev\-replace]}\fP will be used unchanged as the +`\fB%i\fP\&' replacement in the variables set by \fBvcs_info\fP\&. +.RE +.TP +\fBpre\-addon\-quilt\fP +This hook is used when \fBvcs_info\fP\&'s quilt functionality is active in "addon" +mode (quilt used on top of a real version control system)\&. It is activated +right before any quilt specific action is taken\&. +.RS +.PP +Setting the `\fBret\fP\&' variable in this hook to a non\-zero value avoids any +quilt specific actions from being run at all\&. +.RE +.TP +\fBset\-patch\-format\fP +This hook is used to control some of the possible expansions in +\fBpatch\-format\fP and \fBnopatch\-format\fP styles with patch queue systems such as +quilt, mqueue and the like\&. +.RS +.PP +This hook is used in the \fBgit\fP, \fBhg\fP and \fBquilt\fP backends\&. +.PP +The hook allows the control of the \fB%p\fP (\fB${hook_com[applied]}\fP) and \fB%u\fP +(\fB${hook_com[unapplied]}\fP) expansion in all backends that use the hook\&. With +the mercurial backend, the \fB%g\fP (\fB${hook_com[guards]}\fP) expansion is +controllable in addition to that\&. +.PP +If \fBret\fP is set to non\-zero, the string in \fB${hook_com[patch\-replace]}\fP +will be used unchanged instead of an expanded format from \fBpatch\-format\fP or +\fBnopatch\-format\fP\&. +.PP +This hook is, in concert with the \fBgen\-applied\-string\fP or +\fBgen\-unapplied\-string\fP hooks if they are defined, responsible for +\fB%\fP\-escaping the final \fBpatch\-format\fP value for use in the prompt\&. +(See the \fBOddities\fP section\&.) +.PP +The \fBquilt\fP backend passes to this hook the inputs +\fB${hook_com[quilt\-patches\-dir]}\fP and, if it has been +determined, \fB${hook_com[quilt\-pc\-dir]}\fP\&. +.RE +.TP +\fBset\-message\fP +Called each time before a `\fBvcs_info_msg_\fP\fIN\fP\fB_\fP\&' message is set\&. +It takes two arguments; the first being the `\fIN\fP\&' in the message +variable name, the second is the currently configured \fBformats\fP or +\fBactionformats\fP\&. +.RS +.PP +There are a number of `\fBhook_com\fP\&' keys, that are used here: +`\fBaction\fP\&', `\fBbranch\fP', `\fBbase\fP', `\fBbase\-name\fP', `\fBsubdir\fP', +`\fBstaged\fP\&', `\fBunstaged\fP', `\fBrevision\fP', `\fBmisc\fP', `\fBvcs\fP' +and one `\fBmiscN\fP\&' entry for each backend\-specific data field (\fBN\fP +starting at zero)\&. They are set to the values figured out so far by +\fBvcs_info\fP and any change will be used directly when the actual +replacement is done\&. +.PP +Since this hook is triggered multiple times (once for each configured +\fBformats\fP or \fBactionformats\fP), each of the `\fBhook_com\fP\&' keys mentioned +above (except for the \fBmiscN\fP entries) has an `\fB_orig\fP\&' counterpart, +so even if you changed a value to your liking you can still get the +original value in the next run\&. Changing the `\fB_orig\fP\&' values is +probably not a good idea\&. +.PP +If \fBret\fP is set to non\-zero, the string in +\fB${hook_com[message]}\fP will be used unchanged as the message by +\fBvcs_info\fP\&. +.RE +.PP +If all of this sounds rather confusing, take a look at +the \fBExamples\fP section below +and also in the \fBMisc/vcs_info\-examples\fP file in the Zsh source\&. +They contain some explanatory code\&. +.PP +.SS "Examples" +.PP +Don\&'t use \fBvcs_info\fP at all (even though it's in your prompt): +.RS +.nf +\fBzstyle \&':vcs_info:*' enable NONE\fP +.fi +.RE +.PP +Disable the backends for \fBbzr\fP and \fBsvk\fP: +.RS +.nf +\fBzstyle \&':vcs_info:*' disable bzr svk\fP +.fi +.RE +.PP +Disable everything \fIbut\fP \fBbzr\fP and \fBsvk\fP: +.RS +.nf +\fBzstyle \&':vcs_info:*' enable bzr svk\fP +.fi +.RE +.PP +Provide a special formats for \fBgit\fP: +.RS +.nf +\fBzstyle \&':vcs_info:git:*' formats ' GIT, BABY! [%b]' +zstyle \&':vcs_info:git:*' actionformats ' GIT ACTION! [%b|%a]'\fP +.fi +.RE +.PP +All \fB%x\fP expansion in all sorts of formats (\fBformats\fP, \fBactionformats\fP, +\fBbranchformat\fP, you name it) are done using the `\fBzformat\fP\&' builtin from +the `\fBzsh/zutil\fP\&' module\&. That means you can do everything with these +\fB%x\fP items what zformat supports\&. In particular, if you want something +that is really long to have a fixed width, like a hash in a mercurial +branchformat, you can do this: \fB%12\&.12i\fP\&. That\&'ll shrink the 40 character +hash to its 12 leading characters\&. The form is actually +`\fB%\fP\fImin\fP\fB\&.\fP\fImax\fP\fBx\fP\&'\&. More is possible\&. +See the section `The zsh/zutil Module\&' in \fIzshmodules\fP(1) for details\&. +.PP +Use the quicker \fBbzr\fP backend +.RS +.nf +\fBzstyle \&':vcs_info:bzr:*' use\-simple true\fP +.fi +.RE +.PP +If you do use \fBuse\-simple\fP, please report if it does `the\-right\-thing[tm]\&'\&. +.PP +Display the revision number in yellow for \fBbzr\fP and \fBsvn\fP: +.RS +.nf +\fBzstyle \&':vcs_info:(svn|bzr):*' \e + branchformat \&'%b%%F{yellow}:%r'\fP +.fi +.RE +.PP +The doubled percent sign is explained in +the \fBOddities\fP section\&. +.PP +Alternatively, one can use the raw colour codes directly: +.PP +.RS +.nf +\fBzstyle \&':vcs_info:(svn|bzr):*' \e + branchformat \&'%b%{'${fg[yellow]}'%}:%r'\fP +.fi +.RE +.PP +Normally when a variable is interpolated into a format string, the variable +needs to be \fB%\fP\-escaped\&. In this example we skipped that because we assume +the value of \fB${fg[yellow]}\fP doesn\&'t contain any \fB%\fP signs\&. +.PP +Make sure you enclose the color codes in \fB%{\fP\fI\&.\&.\&.\fP\fB%}\fP +if you want to use the string provided by \fBvcs_info\fP in prompts\&. +.PP +Here is how to print the VCS information as a command (not in a prompt): +.RS +.nf +\fBvcsi() { vcs_info interactive; vcs_info_lastmsg }\fP +.fi +.RE +.PP +This way, you can even define different formats for output via +\fBvcs_info_lastmsg\fP in the \&'\fB:vcs_info:*:interactive:*\fP' namespace\&. +.PP +Now as promised, some code that uses hooks: +say, you\&'d like to replace the string `svn' by `subversion' in +\fBvcs_info\fP\&'s \fB%s\fP \fBformats\fP replacement\&. +.PP +First, we will tell \fBvcs_info\fP to call a function when populating +the message variables with the gathered information: +.RS +.nf +\fBzstyle \&':vcs_info:*+set\-message:*' hooks svn2subversion\fP +.fi +.RE +.PP +Nothing happens\&. Which is reasonable, since we didn\&'t define the actual +function yet\&. To see what the hooks subsystem is trying to do, enable the +`\fBdebug\fP\&' style: +.RS +.nf +\fBzstyle \&':vcs_info:*+*:*' debug true\fP +.fi +.RE +.PP +That should give you an idea what is going on\&. Specifically, the function +that we are looking for is `\fB+vi\-svn2subversion\fP\&'\&. Note, the `\fB+vi\-\fP' +prefix\&. So, everything is in order, just as documented\&. When you are done +checking out the debugging output, disable it again: +.RS +.nf +\fBzstyle \&':vcs_info:*+*:*' debug false\fP +.fi +.RE +.PP +Now, let\&'s define the function: +.RS +.nf +\fB +function +vi\-svn2subversion() { + [[ ${hook_com[vcs_orig]} == svn ]] && hook_com[vcs]=subversion +}\fP +.fi +.RE +.PP +Simple enough\&. And it could have even been simpler, if only we had +registered our function in a less generic context\&. If we do it only in +the `\fBsvn\fP\&' backend's context, we don't need to test which the active +backend is: +.RS +.nf +\fBzstyle \&':vcs_info:svn+set\-message:*' hooks svn2subversion\fP +.fi +.RE +.RS +.nf +\fB +function +vi\-svn2subversion() { + hook_com[vcs]=subversion +}\fP +.fi +.RE +.PP +And finally a little more elaborate example, that uses a hook to create +a customised bookmark string for the \fBhg\fP backend\&. +.PP +Again, we start off by registering a function: +.RS +.nf +\fBzstyle \&':vcs_info:hg+gen\-hg\-bookmark\-string:*' hooks hgbookmarks\fP +.fi +.RE +.PP +And then we define the `\fB+vi\-hgbookmarks\fP\&' function: +.RS +.nf +\fB +function +vi\-hgbookmarks() { + # The default is to connect all bookmark names by + # commas\&. This mixes things up a little\&. + # Imagine, there\&'s one type of bookmarks that is + # special to you\&. Say, because it\&'s *your* work\&. + # Those bookmarks look always like this: "sh/*" + # (because your initials are sh, for example)\&. + # This makes the bookmarks string use only those + # bookmarks\&. If there\&'s more than one, it + # concatenates them using commas\&. + # The bookmarks returned by `hg\&' are available in + # the function\&'s positional parameters\&. + local s="${(Mj:,:)@:#sh/*}" + # Now, the communication with the code that calls + # the hook functions is done via the hook_com[] + # hash\&. The key at which the `gen\-hg\-bookmark\-string\&' + # hook looks is `hg\-bookmark\-string\&'\&. So: + hook_com[hg\-bookmark\-string]=$s + # And to signal that we want to use the string we + # just generated, set the special variable `ret\&' to + # something other than the default zero: + ret=1 + return 0 +}\fP +.fi +.RE +.PP +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 +directory\&. +.PP +This concludes our guided tour through zsh\&'s \fBvcs_info\fP\&. +.PP +.SH "PROMPT THEMES" +.PP +.SS "Installation" +.PP +You should make sure all the functions from the \fBFunctions/Prompts\fP +directory of the source distribution are available; they all begin with +the string `\fBprompt_\fP\&' except for the special function `\fBpromptinit\fP'\&. +You also need the `\fBcolors\fP\&' and `\fBadd\-zsh\-hook\fP' functions from +\fBFunctions/Misc\fP\&. +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 \fBfpath\fP array (this should already be the +case if they were installed), and at least the function \fBpromptinit\fP +should be autoloaded; it will autoload the rest\&. Finally, to initialize +the use of the system you need to call the \fBpromptinit\fP function\&. The +following code in your \fB\&.zshrc\fP will arrange for this; assume the +functions are stored in the directory \fB~/myfns\fP: +.PP +.RS +.nf +\fBfpath=(~/myfns $fpath) +autoload \-U promptinit +promptinit\fP +.fi +.RE +.PP +.SS "Theme Selection" +.PP +Use the \fBprompt\fP command to select your preferred theme\&. This command +may be added to your \fB\&.zshrc\fP following the call to \fBpromptinit\fP in +order to start zsh with a theme already selected\&. +.PP +.PD 0 +.TP +.PD 0 +\fBprompt\fP [ \fB\-c\fP | \fB\-l\fP ] +.TP +.PD 0 +\fBprompt\fP [ \fB\-p\fP | \fB\-h\fP ] [ \fItheme\fP \&.\&.\&. ] +.TP +.PD +\fBprompt\fP [ \fB\-s\fP ] \fItheme\fP [ \fIarg\fP \&.\&.\&. ] +Set or examine the prompt theme\&. With no options and a \fItheme\fP +argument, the theme with that name is set as the current theme\&. The +available themes are determined at run time; use the \fB\-l\fP option to see +a list\&. The special \fItheme\fP `\fBrandom\fP\&' selects at random one of the +available themes and sets your prompt to that\&. +.RS +.PP +In some cases the \fItheme\fP may be modified by one or more arguments, +which should be given after the theme name\&. See the help for each theme +for descriptions of these arguments\&. +.PP +Options are: +.PP +.PD 0 +.TP +\fB\-c\fP +Show the currently selected theme and its parameters, if any\&. +.TP +\fB\-l\fP +List all available prompt themes\&. +.TP +\fB\-p\fP +Preview the theme named by \fItheme\fP, or all themes if no +\fItheme\fP is given\&. +.TP +\fB\-h\fP +Show help for the theme named by \fItheme\fP, or for the +\fBprompt\fP function if no \fItheme\fP is given\&. +.TP +\fB\-s\fP +Set \fItheme\fP as the current theme and save state\&. +.PD +.RE +.TP +\fBprompt_\fP\fItheme\fP\fB_setup\fP +Each available \fItheme\fP has a setup function which is called by the +\fBprompt\fP function to install that theme\&. This function may define +other functions as necessary to maintain the prompt, including functions +used to preview the prompt or provide help for its use\&. You should not +normally call a theme\&'s setup function directly\&. +.PP +.SS "Utility Themes" +.PP +.PD 0 +.TP +.PD +\fBprompt off\fP +The theme `\fBoff\fP\&' sets all the prompt variables to minimal values with +no special effects\&. +.TP +\fBprompt default\fP +The theme `\fBdefault\fP\&' sets all prompt variables to the same state as +if an interactive zsh was started with no initialization files\&. +.TP +\fBprompt restore\fP +The special theme `\fBrestore\fP\&' erases all theme settings and sets prompt +variables to their state before the first time the `\fBprompt\fP\&' function +was run, provided each theme has properly defined its cleanup (see below)\&. +.RS +.PP +Note that you can undo `\fBprompt off\fP\&' and `\fBprompt default\fP' with +`\fBprompt restore\fP\&', but a second restore does not undo the first\&. +.RE +.PP +.SS "Writing Themes" +.PP +The first step for adding your own theme is to choose a name for it, +and create a file `\fBprompt_\fIname\fP_setup\fP\&' in a directory in your +\fBfpath\fP, such as \fB~/myfns\fP 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 \fBPS1\fP, \fBPS2\fP, +\fBRPS1\fP, etc\&., rather than the longer \fBPROMPT\fP and \fBRPROMPT\fP\&. +.PP +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: +.PP +.PD 0 +.TP +.PD +Assign \fBprompt_opts\fP +The array \fBprompt_opts\fP may be assigned any of \fB"bang"\fP, \fB"cr"\fP, +\fB"percent"\fP, \fB"sp"\fP, and/or \fB"subst"\fP as values\&. The corresponding +setopts (\fBpromptbang\fP, etc\&.) are turned on, all other prompt\-related +options are turned off\&. The \fBprompt_opts\fP array preserves setopts even +beyond the scope of \fBlocaloptions\fP, should your function need that\&. +.TP +Modify hooks +Use of \fBadd\-zsh\-hook\fP and \fBadd\-zle\-hook\-widget\fP is recommended (see +the \fBManipulating Hook Functions\fP section above)\&. +All hooks that follow the naming pattern \fBprompt_\fP\fItheme\fP\fB_\fP\fIhook\fP +are automatically removed when the prompt theme changes or is disabled\&. +.TP +Declare cleanup +If your function makes any other changes that should be undone when the +theme is disabled, your setup function may call +.RS +.PP +.RS +.nf +\fBprompt_cleanup \fIcommand\fP\fP +.fi +.RE +.PP +where \fIcommand\fP should be suitably quoted\&. If your theme is ever +disabled or replaced by another, \fIcommand\fP is executed with \fBeval\fP\&. +You may declare more than one such cleanup hook\&. +.RE +.TP +Define preview +Define or autoload a function \fBprompt_\fP\fIname\fP\fB_preview\fP to display +a simulated version of your prompt\&. A simple default previewer is +defined by \fBpromptinit\fP for themes that do not define their own\&. +This preview function is called by `\fBprompt \-p\fP\&'\&. +.TP +Provide help +Define or autoload a function \fBprompt_\fP\fIname\fP\fB_help\fP to display +documentation or help text for your theme\&. +This help function is called by `\fBprompt \-h\fP\&'\&. +.PP +.SH "ZLE FUNCTIONS" +.PP +.SS "Widgets" +.PP +These functions all implement user\-defined ZLE widgets (see +\fIzshzle\fP(1)) which can be bound to keystrokes in interactive shells\&. To use them, +your \fB\&.zshrc\fP should contain lines of the form +.PP +.RS +.nf +\fBautoload \fIfunction\fP +zle \-N \fIfunction\fP\fP +.fi +.RE +.PP +followed by an appropriate \fBbindkey\fP command to associate the function +with a key sequence\&. Suggested bindings are described below\&. +.PP +.PD 0 +.TP +.PD +bash\-style word functions +If you are looking for functions to implement moving over and editing +words in the manner of bash, where only alphanumeric characters are +considered word characters, you can use the functions described in +the next section\&. The following is sufficient: +.RS +.PP +.RS +.nf +\fBautoload \-U select\-word\-style +select\-word\-style bash\fP +.fi +.RE +.PP +.RE +.TP +.PD 0 +\fBforward\-word\-match\fP, \fBbackward\-word\-match\fP +.TP +.PD 0 +\fBkill\-word\-match\fP, \fBbackward\-kill\-word\-match\fP +.TP +.PD 0 +\fBtranspose\-words\-match\fP, \fBcapitalize\-word\-match\fP +.TP +.PD 0 +\fBup\-case\-word\-match\fP, \fBdown\-case\-word\-match\fP +.TP +.PD 0 +\fBdelete\-whole\-word\-match\fP, \fBselect\-word\-match\fP +.TP +.PD +\fBselect\-word\-style\fP, \fBmatch\-word\-context\fP, \fBmatch\-words\-by\-style\fP +The first eight `\fB\-match\fP\&' 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 \fBselect\-word\-style\fP, +the way words are matched can be altered\&. \fBselect\-word\-match\fP is intended +to be used as a text object in vi mode but with custom word styles\&. For +comparison, the widgets described in \fIzshzle\fP(1) under Text Objects use fixed definitions of words, compatible +with the \fBvim\fP editor\&. +.RS +.PP +The simplest way of configuring the functions is to use +\fBselect\-word\-style\fP, which can either be called as a normal function with +the appropriate argument, or invoked as a user\-defined widget that will +prompt for the first character of the word style to be used\&. The first +time it is invoked, the first eight \fB\-match\fP functions will automatically +replace the builtin versions, so they do not need to be loaded explicitly\&. +.PP +The word styles available are as follows\&. Only the first character +is examined\&. +.PP +.PD 0 +.TP +.PD +\fBbash\fP +Word characters are alphanumeric characters only\&. +.TP +\fBnormal\fP +As in normal shell operation: word characters are alphanumeric characters +plus any characters present in the string given by the parameter +\fB$WORDCHARS\fP\&. +.TP +\fBshell\fP +Words are complete shell command arguments, possibly including complete +quoted strings, or any tokens special to the shell\&. +.TP +\fBwhitespace\fP +Words are any set of characters delimited by whitespace\&. +.TP +\fBdefault\fP +Restore the default settings; this is usually the same as `\fBnormal\fP\&'\&. +.PP +All but `\fBdefault\fP\&' can be input as an upper case character, which has +the same effect but with subword matching turned on\&. In this case, words +with upper case characters are treated specially: each separate run of +upper case characters, or an upper case character followed by any number of +other characters, is considered a word\&. The style \fBsubword\-range\fP +can supply an alternative character range to the default `\fB[:upper:]\fP\&'; +the value of the style is treated as the contents of a `\fB[\fP\fI\&.\&.\&.\fP\fB]\fP\&' +pattern (note that the outer brackets should not be supplied, only +those surrounding named ranges)\&. +.PP +More control can be obtained using the \fBzstyle\fP command, as described in +\fIzshmodules\fP(1)\&. Each style is looked up in the +context \fB:zle:\fP\fIwidget\fP where \fIwidget\fP is the name of the +user\-defined widget, not the name of the function implementing it, so in +the case of the definitions supplied by \fBselect\-word\-style\fP the +appropriate contexts are \fB:zle:forward\-word\fP, and so on\&. The function +\fBselect\-word\-style\fP itself always defines styles for the context +`\fB:zle:*\fP\&' which can be overridden by more specific (longer) patterns as +well as explicit contexts\&. +.PP +The style \fBword\-style\fP specifies the rules to use\&. This may have the +following values\&. +.PP +.PD 0 +.TP +.PD +\fBnormal\fP +Use the standard shell rules, i\&.e\&. alphanumerics and \fB$WORDCHARS\fP, unless +overridden by the styles \fBword\-chars\fP or \fBword\-class\fP\&. +.TP +\fBspecified\fP +Similar to \fBnormal\fP, but \fIonly\fP the specified characters, and not also +alphanumerics, are considered word characters\&. +.TP +\fBunspecified\fP +The negation of specified\&. The given characters are those which will +\fInot\fP be considered part of a word\&. +.TP +\fBshell\fP +Words are obtained by using the syntactic rules for generating shell +command arguments\&. In addition, special tokens which are never command +arguments such as `\fB()\fP\&' are also treated as words\&. +.TP +\fBwhitespace\fP +Words are whitespace\-delimited strings of characters\&. +.PP +The first three of those rules usually use \fB$WORDCHARS\fP, but the value +in the parameter can be overridden by the style \fBword\-chars\fP, which works +in exactly the same way as \fB$WORDCHARS\fP\&. In addition, the style +\fBword\-class\fP uses character class syntax to group characters and takes +precedence over \fBword\-chars\fP if both are set\&. The \fBword\-class\fP style +does not include the surrounding brackets of the character class; for +example, `\fB\-:[:alnum:]\fP\&' is a valid \fBword\-class\fP to include all +alphanumerics plus the characters `\fB\-\fP\&' and `\fB:\fP'\&. Be careful +including `\fB]\fP\&', `\fB^\fP' and `\fB\-\fP' as these are special inside +character classes\&. +.PP +\fBword\-style\fP may also have `\fB\-subword\fP\&' appended to its value to +turn on subword matching, as described above\&. +.PP +The style \fBskip\-chars\fP is mostly useful for +\fBtranspose\-words\fP and similar functions\&. If set, it gives a count of +characters starting at the cursor position which will not be considered +part of the word and are treated as space, regardless of what they actually +are\&. For example, if +.PP +.RS +.nf +\fBzstyle \&':zle:transpose\-words' skip\-chars 1\fP +.fi +.RE +.PP +has been set, and \fBtranspose\-words\-match\fP is called with the cursor on +the \fIX\fP of \fBfoo\fP\fIX\fP\fBbar\fP, where \fIX\fP can be any character, then +the resulting expression is \fBbar\fP\fIX\fP\fBfoo\fP\&. +.PP +Finer grained control can be obtained by setting the style \fBword\-context\fP +to an array of pairs of entries\&. Each pair of entries consists of a +\fIpattern\fP and a \fIsubcontext\fP\&. The shell argument the cursor is on is +matched against each \fIpattern\fP in turn until one matches; if it does, +the context is extended by a colon and the corresponding \fIsubcontext\fP\&. +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 \fBbetween\fP the word +is set to a single space; else if it is contains the string \fBback\fP, +the word before the cursor is considered, else the word after cursor is +considered\&. Some examples are given below\&. +.PP +The style \fBskip\-whitespace\-first\fP is only used with the +\fBforward\-word\fP widget\&. If it is set to true, then \fBforward\-word\fP +skips any non\-word\-characters, followed by any non\-word\-characters: +this is similar to the behaviour of other word\-orientated widgets, +and also that used by other editors, however it differs from the +standard zsh behaviour\&. When using \fBselect\-word\-style\fP the widget +is set in the context \fB:zle:*\fP to \fBtrue\fP if the word style is +\fBbash\fP and \fBfalse\fP otherwise\&. It may be overridden by setting it in +the more specific context \fB:zle:forward\-word*\fP\&. +.PP +It is possible to create widgets with specific behaviour by defining +a new widget implemented by the appropriate generic function, then +setting a style for the context of the specific widget\&. For example, +the following defines a widget \fBbackward\-kill\-space\-word\fP using +\fBbackward\-kill\-word\-match\fP, the generic widget implementing +\fBbackward\-kill\-word\fP behaviour, and ensures that the new widget +always implements space\-delimited behaviour\&. +.PP +.RS +.nf +\fBzle \-N backward\-kill\-space\-word backward\-kill\-word\-match +zstyle :zle:backward\-kill\-space\-word word\-style space\fP +.fi +.RE +.PP +The widget \fBbackward\-kill\-space\-word\fP can now be bound to a key\&. +.PP +Here are some further examples of use of the styles, actually taken from the +simplified interface in \fBselect\-word\-style\fP: +.PP +.RS +.nf +\fBzstyle \&':zle:*' word\-style standard +zstyle \&':zle:*' word\-chars ''\fP +.fi +.RE +.PP +Implements bash\-style word handling for all widgets, i\&.e\&. only +alphanumerics are word characters; equivalent to setting +the parameter \fBWORDCHARS\fP empty for the given context\&. +.PP +.RS +.nf +\fBstyle \&':zle:*kill*' word\-style space\fP +.fi +.RE +.PP +Uses space\-delimited words for widgets with the word `kill\&' in the name\&. +Neither of the styles \fBword\-chars\fP nor \fBword\-class\fP is used in this case\&. +.PP +Here are some examples of use of the \fBword\-context\fP style to extend +the context\&. +.PP +.RS +.nf +\fBzstyle \&':zle:*' word\-context \e + "*/*" filename "[[:space:]]" whitespace +zstyle \&':zle:transpose\-words:whitespace' word\-style shell +zstyle \&':zle:transpose\-words:filename' word\-style normal +zstyle \&':zle:transpose\-words:filename' word\-chars ''\fP +.fi +.RE +.PP +This provides two different ways of using \fBtranspose\-words\fP depending on +whether the cursor is on whitespace between words or on a filename, here +any word containing a \fB/\fP\&. On whitespace, complete arguments as defined +by standard shell rules will be transposed\&. In a filename, only +alphanumerics will be transposed\&. Elsewhere, words will be transposed +using the default style for \fB:zle:transpose\-words\fP\&. +.PP +The word matching and all the handling of \fBzstyle\fP settings is actually +implemented by the function \fBmatch\-words\-by\-style\fP\&. This can be used to +create new user\-defined widgets\&. The calling function should set the local +parameter \fBcurcontext\fP to \fB:zle:\fP\fIwidget\fP, create the local +parameter \fBmatched_words\fP and call \fBmatch\-words\-by\-style\fP with no +arguments\&. On return, \fBmatched_words\fP will be set to an array with the +elements: (1) the start of the line (2) the word before the cursor (3) any +non\-word characters between that word and the cursor (4) any non\-word +character at the cursor position plus any remaining non\-word characters +before the next word, including all characters specified by the +\fBskip\-chars\fP style, (5) the word at or following the cursor (6) any +non\-word characters following that word (7) the remainder of the line\&. Any +of the elements may be an empty string; the calling function should test +for this to decide whether it can perform its function\&. +.PP +If the variable \fBmatched_words\fP is defined by the caller to +\fBmatch\-words\-by\-style\fP as an associative array (\fBlocal \-A +matched_words\fP), then the seven values given above should be retrieved +from it as elements named \fBstart\fP, \fBword\-before\-cursor\fP, +\fBws\-before\-cursor\fP, \fBws\-after\-cursor\fP, \fBword\-after\-cursor\fP, +\fBws\-after\-word\fP, and \fBend\fP\&. In addition the element +\fBis\-word\-start\fP is 1 if the cursor is on the start of a word or +subword, or on white space before it (the cases can be distinguished by +testing the \fBws\-after\-cursor\fP element) and 0 otherwise\&. This form is +recommended for future compatibility\&. +.PP +It is possible to pass options with arguments to \fBmatch\-words\-by\-style\fP +to override the use of styles\&. The options are: +.PD 0 +.TP +\fB\-w\fP +\fIword\-style\fP +.TP +\fB\-s\fP +\fIskip\-chars\fP +.TP +\fB\-c\fP +\fIword\-class\fP +.TP +\fB\-C\fP +\fIword\-chars\fP +.TP +\fB\-r\fP +\fIsubword\-range\fP +.PD +.PP +For example, \fBmatch\-words\-by\-style \-w shell \-c 0\fP may be used to +extract the command argument around the cursor\&. +.PP +The \fBword\-context\fP style is implemented by the function +\fBmatch\-word\-context\fP\&. This should not usually need to be called +directly\&. +.RE +.TP +\fBbracketed\-paste\-magic\fP +The \fBbracketed\-paste\fP widget (see the subsection `Miscellaneous\&' in +\fIzshzle\fP(1)) +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 \fBurl\-quote\-magic\fP widget described below\&. +.RS +.PP +The \fBbracketed\-paste\-magic\fP widget is meant to replace \fBbracketed\-paste\fP +with a wrapper that re\-enables these self\-insert actions, and other +actions as selected by zstyles\&. Therefore this widget is installed with + +.RS +.nf +\fBautoload \-Uz bracketed\-paste\-magic +zle \-N bracketed\-paste bracketed\-paste\-magic\fP +.fi +.RE +.PP +Other than enabling some widget processing, \fBbracketed\-paste\-magic\fP +attempts to replicate \fBbracketed\-paste\fP as faithfully as possible\&. +.PP +The following zstyles may be set to control processing of pasted text\&. +All are looked up in the context `\fB:bracketed\-paste\-magic\fP\&'\&. +.PP +.PD 0 +.TP +.PD +\fBactive\-widgets\fP +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 `\fBself\-*\fP\&' so any user\-defined widgets named with that +prefix are active along with the builtin self\-insert\&. +.RS +.PP +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 `\fBundefined\-key\fP\&', any unknown sequences are discarded +from the pasted text\&. +.RE +.TP +\fBinactive\-keys\fP +The inverse of \fBactive\-widgets\fP, a list of key sequences that always use +\fBself\-insert\-unmeta\fP even when bound to an active widget\&. Note that +this is a list of literal key sequences, not patterns\&. +.TP +\fBpaste\-init\fP +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 `\fBPASTED\fP\&' contains the initial state of the +pasted text\&. All other ZLE parameters such as `\fBBUFFER\fP\&' have their +normal values and side\-effects, and full history is available, so for +example \fBpaste\-init\fP functions may move words from \fBBUFFER\fP into +\fBPASTED\fP to make those words visible to the \fBactive\-widgets\fP\&. +.RS +.PP +A non\-zero return from a \fBpaste\-init\fP function does \fInot\fP prevent the +paste itself from proceeding\&. +.PP +Loading \fBbracketed\-paste\-magic\fP defines \fBbackward\-extend\-paste\fP, a +helper function for use in \fBpaste\-init\fP\&. +.PP +.RS +.nf +\fBzstyle :bracketed\-paste\-magic paste\-init \e + backward\-extend\-paste\fP +.fi +.RE +.PP +When a paste would insert into the middle of a word or append text to a +word already on the line, \fBbackward\-extend\-paste\fP moves the prefix +from \fBLBUFFER\fP into \fBPASTED\fP so that the \fBactive\-widgets\fP see the +full word so far\&. This may be useful with \fBurl\-quote\-magic\fP\&. +.RE +.TP +\fBpaste\-finish\fP +Another list of function names called in order until one returns non\-zero\&. +These functions are called \fIafter\fP the pasted text has been processed +by the \fBactive\-widgets\fP, but \fIbefore\fP it is inserted into `\fBBUFFER\fP\&'\&. +ZLE parameters have their normal values and side\-effects\&. +.RS +.PP +A non\-zero return from a \fBpaste\-finish\fP function does \fInot\fP prevent +the paste itself from proceeding\&. +.PP +Loading \fBbracketed\-paste\-magic\fP also defines \fBquote\-paste\fP, a helper +function for use in \fBpaste\-finish\fP\&. +.PP +.RS +.nf +\fBzstyle :bracketed\-paste\-magic paste\-finish \e + quote\-paste +zstyle :bracketed\-paste\-magic:finish quote\-style \e + qqq\fP +.fi +.RE +.PP +When the pasted text is inserted into \fBBUFFER\fP, it is quoted per the +\fBquote\-style\fP value\&. To forcibly turn off the built\-in numeric prefix +quoting of \fBbracketed\-paste\fP, use: +.PP +.RS +.nf +\fBzstyle :bracketed\-paste\-magic:finish quote\-style \e + none\fP +.fi +.RE +.RE +.PP +\fIImportant:\fP During \fBactive\-widgets\fP processing of the paste (after +\fBpaste\-init\fP and before \fBpaste\-finish\fP), \fBBUFFER\fP starts empty and +history is restricted, so cursor motions, etc\&., may not pass outside of +the pasted content\&. Text assigned to \fBBUFFER\fP by the active widgets +is copied back into \fBPASTED\fP before \fBpaste\-finish\fP\&. +.RE +.TP +\fBcopy\-earlier\-word\fP +This widget works like a combination of \fBinsert\-last\-word\fP and +\fBcopy\-prev\-shell\-word\fP\&. Repeated invocations of the widget retrieve +earlier words on the relevant history line\&. With a numeric argument +\fIN\fP, insert the \fIN\fPth word from the history line; \fIN\fP may be +negative to count from the end of the line\&. +.RS +.PP +If \fBinsert\-last\-word\fP has been used to retrieve the last word on a +previous history line, repeated invocations will replace that word with +earlier words from the same line\&. +.PP +Otherwise, the widget applies to words on the line currently being edited\&. +The \fBwidget\fP style can be set to the name of another widget that should +be called to retrieve words\&. This widget must accept the same three +arguments as \fBinsert\-last\-word\fP\&. +.RE +.TP +\fBcycle\-completion\-positions\fP +After inserting an unambiguous string into the command line, the new +function based completion system may know about multiple places in +this string where characters are missing or differ from at least one +of the possible matches\&. It will then place the cursor on the +position it considers to be the most interesting one, i\&.e\&. the one +where one can disambiguate between as many matches as possible with as +little typing as possible\&. +.RS +.PP +This widget allows the cursor to be easily moved to the other interesting +spots\&. It can be invoked repeatedly to cycle between all positions +reported by the completion system\&. +.RE +.TP +\fBdelete\-whole\-word\-match\fP +This is another function which works like the \fB\-match\fP functions +described immediately above, i\&.e\&. using styles to decide the word +boundaries\&. However, it is not a replacement for any existing function\&. +.RS +.PP +The basic behaviour is to delete the word around the cursor\&. There is no +numeric argument handling; only the single word around the cursor is +considered\&. If the widget contains the string \fBkill\fP, the removed text +will be placed in the cutbuffer for future yanking\&. This can be obtained +by defining \fBkill\-whole\-word\-match\fP as follows: +.PP +.RS +.nf +\fBzle \-N kill\-whole\-word\-match delete\-whole\-word\-match\fP +.fi +.RE +.PP +and then binding the widget \fBkill\-whole\-word\-match\fP\&. +.RE +.TP +\fBup\-line\-or\-beginning\-search\fP, \fBdown\-line\-or\-beginning\-search\fP +These widgets are similar to the builtin functions \fBup\-line\-or\-search\fP +and \fBdown\-line\-or\-search\fP: if in a multiline buffer they move up or +down within the buffer, otherwise they search for a history line matching +the start of the current line\&. In this case, however, they search for +a line which matches the current line up to the current cursor position, in +the manner of \fBhistory\-beginning\-search\-backward\fP and \fB\-forward\fP, rather +than the first word on the line\&. +.TP +\fBedit\-command\-line\fP +Edit the command line using your visual editor, as in \fBksh\fP\&. +.RS +.PP +.RS +.nf +\fBbindkey \-M vicmd v edit\-command\-line\fP +.fi +.RE +.PP +The editor to be used can also be specified using the \fBeditor\fP style in +the context of the widget\&. It is specified as an array of command and +arguments: +.PP +.RS +.nf +\fBzstyle :zle:edit\-command\-line editor gvim \-f\fP +.fi +.RE +.RE +.TP +\fBexpand\-absolute\-path\fP +Expand the file name under the cursor to an absolute path, resolving +symbolic links\&. Where possible, the initial path segment is turned +into a named directory or reference to a user\&'s home directory\&. +.TP +\fBhistory\-search\-end\fP +This function implements the widgets +\fBhistory\-beginning\-search\-backward\-end\fP and +\fBhistory\-beginning\-search\-forward\-end\fP\&. These commands work by first +calling the corresponding builtin widget (see +`History Control\&' in \fIzshzle\fP(1)) and then moving the cursor to the end of the line\&. The original cursor +position is remembered and restored before calling the builtin widget a +second time, so that the same search is repeated to look farther through +the history\&. +.RS +.PP +Although you \fBautoload\fP only one function, the commands to use it are +slightly different because it implements two widgets\&. +.PP +.RS +.nf +\fBzle \-N history\-beginning\-search\-backward\-end \e + history\-search\-end +zle \-N history\-beginning\-search\-forward\-end \e + history\-search\-end +bindkey \&'\ee^P' history\-beginning\-search\-backward\-end +bindkey \&'\ee^N' history\-beginning\-search\-forward\-end\fP +.fi +.RE +.RE +.TP +\fBhistory\-beginning\-search\-menu\fP +This function implements yet another form of history searching\&. The +text before the cursor is used to select lines from the history, +as for \fBhistory\-beginning\-search\-backward\fP except that all matches are +shown in a numbered menu\&. Typing the appropriate digits inserts the +full history line\&. Note that leading zeroes must be typed (they are only +shown when necessary for removing ambiguity)\&. The entire history is +searched; there is no distinction between forwards and backwards\&. +.RS +.PP +With a numeric argument, the search is not anchored to the start of +the line; the string typed by the use may appear anywhere in the line +in the history\&. +.PP +If the widget name contains `\fB\-end\fP\&' the cursor is moved to the end of +the line inserted\&. If the widget name contains `\fB\-space\fP\&' any space +in the text typed is treated as a wildcard and can match anything (hence +a leading space is equivalent to giving a numeric argument)\&. Both +forms can be combined, for example: +.PP +.RS +.nf +\fBzle \-N history\-beginning\-search\-menu\-space\-end \e + history\-beginning\-search\-menu\fP +.fi +.RE +.RE +.TP +\fBhistory\-pattern\-search\fP +The function \fBhistory\-pattern\-search\fP implements widgets which prompt +for a pattern with which to search the history backwards or forwards\&. The +pattern is in the usual zsh format, however the first character may be +\fB^\fP to anchor the search to the start of the line, and the last character +may be \fB$\fP to anchor the search to the end of the line\&. If the +search was not anchored to the end of the line the cursor is positioned +just after the pattern found\&. +.RS +.PP +The commands to create bindable widgets are similar to those in the +example immediately above: +.PP +.RS +.nf +\fBautoload \-U history\-pattern\-search +zle \-N history\-pattern\-search\-backward history\-pattern\-search +zle \-N history\-pattern\-search\-forward history\-pattern\-search\fP +.fi +.RE +.RE +.TP +\fBincarg\fP +Typing the keystrokes for this widget with the cursor placed on or to the +left of an integer causes that integer to be incremented by one\&. With a +numeric argument, the number is incremented by the amount of the +argument (decremented if the numeric argument is negative)\&. The shell +parameter \fBincarg\fP may be set to change the default increment to +something other than one\&. +.RS +.PP +.RS +.nf +\fBbindkey \&'^X+' incarg\fP +.fi +.RE +.RE +.TP +\fBincremental\-complete\-word\fP +This allows incremental completion of a word\&. After starting this +command, a list of completion choices can be shown after every character +you type, which you can delete with \fB^H\fP or \fBDEL\fP\&. Pressing return +accepts the completion so far and returns you to normal editing (that is, +the command line is \fInot\fP immediately executed)\&. You can hit \fBTAB\fP to +do normal completion, \fB^G\fP to abort back to the state when you started, +and \fB^D\fP to list the matches\&. +.RS +.PP +This works only with the new function based completion system\&. +.PP +.RS +.nf +\fBbindkey \&'^Xi' incremental\-complete\-word\fP +.fi +.RE +.RE +.TP +\fBinsert\-composed\-char\fP +This function allows you to compose characters that don\&'t appear on the +keyboard to be inserted into the command line\&. The command is followed by +two keys corresponding to ASCII characters (there is no prompt)\&. For +accented characters, the two keys are a base character followed by a code +for the accent, while for other special characters the two characters +together form a mnemonic for the character to be inserted\&. The +two\-character codes are a subset of those given by RFC 1345 (see for +example \fBhttp://www\&.faqs\&.org/rfcs/rfc1345\&.html\fP)\&. +.RS +.PP +The function may optionally be followed by up to two characters which +replace one or both of the characters read from the keyboard; if both +characters are supplied, no input is read\&. For example, +\fBinsert\-composed\-char a:\fP can be used within a widget to insert an a with +umlaut into the command line\&. This has the advantages over use of a +literal character that it is more portable\&. +.PP +For best results zsh should have been built with support for multibyte +characters (configured with \fB\-\-enable\-multibyte\fP); however, the function +works for the limited range of characters available in single\-byte +character sets such as ISO\-8859\-1\&. +.PP +The character is converted into the local representation and +inserted into the command line at the cursor position\&. +(The conversion is done within the shell, using whatever facilities +the C library provides\&.) With a numeric argument, the character and its +code are previewed in the status line +.PP +The function may be run outside zle in which case it prints the character +(together with a newline) to standard output\&. Input is still read from +keystrokes\&. +.PP +See \fBinsert\-unicode\-char\fP for an alternative way of inserting Unicode +characters using their hexadecimal character number\&. +.PP +The set of accented characters is reasonably complete up to Unicode +character U+0180, the set of special characters less so\&. However, it +is very sporadic from that point\&. Adding new characters is easy, +however; see the function \fBdefine\-composed\-chars\fP\&. Please send any +additions to \fBzsh\-workers@zsh\&.org\fP\&. +.PP +The codes for the second character when used to accent the first are as +follows\&. Note that not every character can take every accent\&. +.PD 0 +.TP +\fB!\fP +Grave\&. +.TP +\fB\&'\fP +Acute\&. +.TP +\fB>\fP +Circumflex\&. +.TP +\fB?\fP +Tilde\&. (This is not \fB~\fP as RFC 1345 does not assume that +character is present on the keyboard\&.) +.TP +\fB\-\fP +Macron\&. (A horizontal bar over the base character\&.) +.TP +\fB(\fP +Breve\&. (A shallow dish shape over the base character\&.) +.TP +\fB\&.\fP +Dot above the base character, or in the case of \fBi\fP no dot, +or in the case of \fBL\fP and \fBl\fP a centered dot\&. +.TP +\fB:\fP +Diaeresis (Umlaut)\&. +.TP +\fBc\fP +Cedilla\&. +.TP +\fB_\fP +Underline, however there are currently no underlined characters\&. +.TP +\fB/\fP +Stroke through the base character\&. +.TP +\fB"\fP +Double acute (only supported on a few letters)\&. +.TP +\fB;\fP +Ogonek\&. (A little forward facing hook at the bottom right +of the character\&.) +.TP +\fB<\fP +Caron\&. (A little v over the letter\&.) +.TP +\fB0\fP +Circle over the base character\&. +.TP +\fB2\fP +Hook over the base character\&. +.TP +\fB9\fP +Horn over the base character\&. +.PD +.PP +The most common characters from the Arabic, Cyrillic, Greek and Hebrew +alphabets are available; consult RFC 1345 for the appropriate sequences\&. +In addition, a set of two letter codes not in RFC 1345 are available for +the double\-width characters corresponding to ASCII characters from \fB!\fP +to \fB~\fP (0x21 to 0x7e) by preceding the character with \fB^\fP, for +example \fB^A\fP for a double\-width \fBA\fP\&. +.PP +The following other two\-character sequences are understood\&. +.PP +.PD 0 +.TP +.PD +ASCII characters +These are already present on most keyboards: +.PD 0 +.TP +\fB<(\fP +Left square bracket +.TP +\fB//\fP +Backslash (solidus) +.TP +\fB)>\fP +Right square bracket +.TP +\fB(!\fP +Left brace (curly bracket) +.TP +\fB!!\fP +Vertical bar (pipe symbol) +.TP +\fB!)\fP +Right brace (curly bracket) +.TP +\fB\&'?\fP +Tilde +.PD +.TP +Special letters +Characters found in various variants of the Latin alphabet: +.PD 0 +.TP +\fBss\fP +Eszett (scharfes S) +.TP +\fBD\-\fP, \fBd\-\fP +Eth +.TP +\fBTH\fP, \fBth\fP +Thorn +.TP +\fBkk\fP +Kra +.TP +\fB\&'n\fP +\&'n +.TP +\fBNG\fP, \fBng\fP +Ng +.TP +\fBOI\fP, \fBoi\fP +Oi +.TP +\fByr\fP +yr +.TP +\fBED\fP +ezh +.PD +.TP +Currency symbols +.PD 0 +.TP +\fBCt\fP +Cent +.TP +\fBPd\fP +Pound sterling (also lira and others) +.TP +\fBCu\fP +Currency +.TP +\fBYe\fP +Yen +.TP +\fBEu\fP +Euro (N\&.B\&. not in RFC 1345) +.PD +.TP +Punctuation characters +References to "right" quotes indicate the shape (like a 9 rather than 6) +rather than their grammatical use\&. (For example, a "right" low double +quote is used to open quotations in German\&.) +.PD 0 +.TP +\fB!I\fP +Inverted exclamation mark +.TP +\fBBB\fP +Broken vertical bar +.TP +\fBSE\fP +Section +.TP +\fBCo\fP +Copyright +.TP +\fB\-a\fP +Spanish feminine ordinal indicator +.TP +\fB<<\fP +Left guillemet +.TP +\fB\-\fP\fB\-\fP +Soft hyphen +.TP +\fBRg\fP +Registered trade mark +.TP +\fBPI\fP +Pilcrow (paragraph) +.TP +\fB\-o\fP +Spanish masculine ordinal indicator +.TP +\fB>>\fP +Right guillemet +.TP +\fB?I\fP +Inverted question mark +.TP +\fB\-1\fP +Hyphen +.TP +\fB\-N\fP +En dash +.TP +\fB\-M\fP +Em dash +.TP +\fB\-3\fP +Horizontal bar +.TP +\fB:3\fP +Vertical ellipsis +.TP +\fB\&.3\fP +Horizontal midline ellipsis +.TP +\fB!2\fP +Double vertical line +.TP +\fB=2\fP +Double low line +.TP +\fB\&'6\fP +Left single quote +.TP +\fB\&'9\fP +Right single quote +.TP +\fB\&.9\fP +"Right" low quote +.TP +\fB9\&'\fP +Reversed "right" quote +.TP +\fB"6\fP +Left double quote +.TP +\fB"9\fP +Right double quote +.TP +\fB:9\fP +"Right" low double quote +.TP +\fB9"\fP +Reversed "right" double quote +.TP +\fB/\-\fP +Dagger +.TP +\fB/=\fP +Double dagger +.PD +.TP +Mathematical symbols +.PD 0 +.TP +\fBDG\fP +Degree +.TP +\fB\-2\fP, \fB+\-\fP, \fB\-+\fP +\- sign, +/\- sign, \-/+ sign +.TP +\fB2S\fP +Superscript 2 +.TP +\fB3S\fP +Superscript 3 +.TP +\fB1S\fP +Superscript 1 +.TP +\fBMy\fP +Micro +.TP +\fB\&.M\fP +Middle dot +.TP +\fB14\fP +Quarter +.TP +\fB12\fP +Half +.TP +\fB34\fP +Three quarters +.TP +\fB*X\fP +Multiplication +.TP +\fB\-:\fP +Division +.TP +\fB%0\fP +Per mille +.TP +\fBFA\fP, \fBTE\fP, \fB/0\fP +For all, there exists, empty set +.TP +\fBdP\fP, \fBDE\fP, \fBNB\fP +Partial derivative, delta (increment), del +(nabla) +.TP +\fB(\-\fP, \fB\-)\fP +Element of, contains +.TP +\fB*P\fP, \fB+Z\fP +Product, sum +.TP +\fB*\-\fP, \fBOb\fP, \fBSb\fP +Asterisk, ring, bullet +.TP +\fBRT\fP, \fB0(\fP, \fB00\fP +Root sign, proportional to, infinity +.PD +.TP +Other symbols +.PD 0 +.TP +\fBcS\fP, \fBcH\fP, \fBcD\fP, \fBcC\fP +Card suits: spades, hearts, diamonds, +clubs +.TP +\fBMd\fP, \fBM8\fP, \fBM2\fP, \fBMb\fP, \fBMx\fP, \fBMX\fP +Musical notation: +crotchet (quarter note), quaver (eighth note), semiquavers (sixteenth +notes), flag sign, natural sign, sharp sign +.TP +\fBFm\fP, \fBMl\fP +Female, male +.PD +.TP +Accents on their own +.PD 0 +.TP +\fB\&'>\fP +Circumflex (same as caret, \fB^\fP) +.TP +\fB\&'!\fP +Grave (same as backtick, \fB`\fP) +.TP +\fB\&',\fP +Cedilla +.TP +\fB\&':\fP +Diaeresis (Umlaut) +.TP +\fB\&'m\fP +Macron +.TP +\fB\&''\fP +Acute +.PD +.RE +.TP +\fBinsert\-files\fP +This function allows you type a file pattern, and see the results of the +expansion at each step\&. When you hit return, all expansions are inserted +into the command line\&. +.RS +.PP +.RS +.nf +\fBbindkey \&'^Xf' insert\-files\fP +.fi +.RE +.RE +.TP +\fBinsert\-unicode\-char\fP +When first executed, the user inputs a set of hexadecimal digits\&. +This is terminated with another call to \fBinsert\-unicode\-char\fP\&. +The digits are then turned into the corresponding Unicode character\&. +For example, if the widget is bound to \fB^XU\fP, the character sequence +`\fB^XU 4 c ^XU\fP\&' inserts \fBL\fP (Unicode U+004c)\&. +.RS +.PP +See \fBinsert\-composed\-char\fP for a way of inserting characters +using a two\-character mnemonic\&. +.RE + +.TP +.PD 0 +\fBnarrow\-to\-region \fP[ \fB\-p\fP \fIpre\fP ] [ \fB\-P\fP \fIpost\fP ] +.TP +.PD 0 +\fB \fP[ \fB\-S\fP \fIstatepm\fP | \fB\-R\fP \fIstatepm\fP | [ \fB\-l\fP \fIlbufvar\fP ] [ \fB\-r\fP \fIrbufvar\fP ] ] +.TP +.PD 0 +\fB \fP[ \fB\-n\fP ] [ \fIstart\fP \fIend\fP ] +.TP +.PD +\fBnarrow\-to\-region\-invisible\fP +Narrow the editable portion of the buffer to the region between the cursor +and the mark, which may be in either order\&. The region may not be empty\&. +.RS +.PP +\fBnarrow\-to\-region\fP may be used as a widget or called as a function from a +user\-defined widget; by default, the text outside the editable area remains +visible\&. A \fBrecursive\-edit\fP is performed and the original widening +status is then restored\&. Various options and arguments are available when +it is called as a function\&. +.PP +The options \fB\-p\fP \fIpretext\fP and \fB\-P\fP \fIposttext\fP may be +used to replace the text before and after the display for the duration of +the function; either or both may be an empty string\&. +.PP +If the option \fB\-n\fP is also given, \fIpretext\fP or \fIposttext\fP will only +be inserted if there is text before or after the region respectively which +will be made invisible\&. +.PP +Two numeric arguments may be given which will be used instead of the cursor +and mark positions\&. +.PP +The option \fB\-S\fP \fIstatepm\fP is used to narrow according to the other +options while saving the original state in the parameter with name +\fIstatepm\fP, while the option \fB\-R\fP \fIstatepm\fP is used to restore the +state from the parameter; note in both cases the \fIname\fP of the parameter +is required\&. In the second case, other options and arguments are +irrelevant\&. When this method is used, no \fBrecursive\-edit\fP is performed; +the calling widget should call this function with the option \fB\-S\fP, +perform its own editing on the command line or pass control to the user +via `\fBzle recursive\-edit\fP\&', then call this function with the option +\fB\-R\fP\&. The argument \fIstatepm\fP must be a suitable name for an ordinary +parameter, except that parameters beginning with the prefix \fB_ntr_\fP are +reserved for use within \fBnarrow\-to\-region\fP\&. Typically the parameter will +be local to the calling function\&. +.PP +The options \fB\-l\fP \fIlbufvar\fP and \fB\-r\fP \fIrbufvar\fP may be used to +specify parameters where the widget will store the resulting text from +the operation\&. The parameter \fIlbufvar\fP will contain \fBLBUFFER\fP +and \fIrbufvar\fP will contain \fBRBUFFER\fP\&. Neither of these two options +may be used with \fB\-S\fP or \fB\-R\fP\&. +.PP +\fBnarrow\-to\-region\-invisible\fP is a simple widget which calls +\fBnarrow\-to\-region\fP with arguments which replace any text outside the +region with `\fB\&.\&.\&.\fP\&'\&. It does not take any arguments\&. +.PP +The display is restored (and the widget returns) upon any zle command +which would usually cause the line to be accepted or aborted\&. Hence an +additional such command is required to accept or abort the current line\&. +.PP +The return status of both widgets is zero if the line was accepted, else +non\-zero\&. +.PP +Here is a trivial example of a widget using this feature\&. +.RS +.nf +\fBlocal state +narrow\-to\-region \-p $\&'Editing restricted region\en' \e + \-P \&'' \-S state +zle recursive\-edit +narrow\-to\-region \-R state\fP +.fi +.RE +.RE +.TP +\fBpredict\-on\fP +This set of functions implements predictive typing using history search\&. +After \fBpredict\-on\fP, typing characters causes the editor to look backward +in the history for the first line beginning with what you have typed so +far\&. After \fBpredict\-off\fP, editing returns to normal for the line found\&. +In fact, you often don\&'t even need to use \fBpredict\-off\fP, because if the +line doesn\&'t match something in the history, adding a key performs +standard completion, and then inserts itself if no completions were found\&. +However, editing in the middle of a line is liable to confuse prediction; +see the \fBtoggle\fP style below\&. +.RS +.PP +With the function based completion system (which is needed for this), you +should be able to type \fBTAB\fP at almost any point to advance the cursor +to the next ``interesting\&'' character position (usually the end of the +current word, but sometimes somewhere in the middle of the word)\&. And of +course as soon as the entire line is what you want, you can accept with +return, without needing to move the cursor to the end first\&. +.PP +The first time \fBpredict\-on\fP is used, it creates several additional +widget functions: +.PP +.PD 0 +.TP +\fBdelete\-backward\-and\-predict\fP +Replaces the \fBbackward\-delete\-char\fP +widget\&. You do not need to bind this yourself\&. +.TP +\fBinsert\-and\-predict\fP +Implements predictive typing by replacing the +\fBself\-insert\fP widget\&. You do not need to bind this yourself\&. +.TP +\fBpredict\-off\fP +Turns off predictive typing\&. +.PD +.PP +Although you \fBautoload\fP only the \fBpredict\-on\fP function, it is +necessary to create a keybinding for \fBpredict\-off\fP as well\&. +.PP +.RS +.nf +\fBzle \-N predict\-on +zle \-N predict\-off +bindkey \&'^X^Z' predict\-on +bindkey \&'^Z' predict\-off\fP +.fi +.RE +.RE +.TP +\fBread\-from\-minibuffer\fP +This is most useful when called as a function from inside a widget, but will +work correctly as a widget in its own right\&. It prompts for a value +below the current command line; a value may be input using all of the +standard zle operations (and not merely the restricted set available +when executing, for example, \fBexecute\-named\-cmd\fP)\&. The value is then +returned to the calling function in the parameter \fB$REPLY\fP and the +editing buffer restored to its previous state\&. If the read was aborted +by a keyboard break (typically \fB^G\fP), the function returns status 1 +and \fB$REPLY\fP is not set\&. +.RS +.PP +If one argument is supplied to the function it is taken as a prompt, +otherwise `\fB? \fP\&' is used\&. If two arguments are supplied, they are the +prompt and the initial value of \fB$LBUFFER\fP, and if a third argument is +given it is the initial value of \fB$RBUFFER\fP\&. This provides a default +value and starting cursor placement\&. Upon return the entire buffer is the +value of \fB$REPLY\fP\&. +.PP +One option is available: `\fB\-k\fP \fInum\fP\&' specifies that \fInum\fP +characters are to be read instead of a whole line\&. The line editor is not +invoked recursively in this case, so depending on the terminal settings +the input may not be visible, and only the input keys are placed in +\fB$REPLY\fP, not the entire buffer\&. Note that unlike the \fBread\fP builtin +\fInum\fP must be given; there is no default\&. +.PP +The name is a slight misnomer, as in fact the shell\&'s own minibuffer is +not used\&. Hence it is still possible to call \fBexecuted\-named\-cmd\fP and +similar functions while reading a value\&. +.RE +.TP +\fBreplace\-argument\fP, \fBreplace\-argument\-edit\fP +The function \fBreplace\-argument\fP can be used to replace a command +line argument in the current command line or, if the current command +line is empty, in the last command line executed (the new command line +is not executed)\&. Arguments are as delimited by standard shell syntax, +.RS +.PP +If a numeric argument is given, that specifies the argument to be +replaced\&. 0 means the command name, as in history expansion\&. +A negative numeric argument counts backward from the last word\&. +.PP +If no numeric argument is given, the current argument is replaced; +this is the last argument if the previous history line is being used\&. +.PP +The function prompts for a replacement argument\&. +.PP +If the widget contains the string \fBedit\fP, for example is defined as +.PP +.RS +.nf +\fBzle \-N replace\-argument\-edit replace\-argument\fP +.fi +.RE +.PP +then the function presents the current value of the argument for +editing, otherwise the editing buffer for the replacement is +initially empty\&. +.RE +.TP +.PD 0 +\fBreplace\-string\fP, \fBreplace\-pattern\fP +.TP +.PD +\fBreplace\-string\-again\fP, \fBreplace\-pattern\-again\fP +The function \fBreplace\-string\fP implements three widgets\&. +If defined under the same name as the function, it prompts for two +strings; the first (source) string will be replaced by the second +everywhere it occurs in the line editing buffer\&. +.RS +.PP +If the widget name contains the word `\fBpattern\fP\&', for example by +defining the widget using the command `\fBzle \-N replace\-pattern +replace\-string\fP\&', then the matching is performed using zsh patterns\&. All +zsh extended globbing patterns can be used in the source string; note +that unlike filename generation the pattern does not need to match an +entire word, nor do glob qualifiers have any effect\&. In addition, the +replacement string can contain parameter or command substitutions\&. +Furthermore, a `\fB&\fP\&' in the replacement string will be replaced with +the matched source string, and a backquoted digit `\fB\e\fP\fIN\fP\&' will be +replaced by the \fIN\fPth parenthesised expression matched\&. The form +`\fB\e{\fP\fIN\fP\fB}\fP\&' may be used to protect the digit from following +digits\&. +.PP +If the widget instead contains the word `\fBregex\fP\&' (or `\fBregexp\fP'), +then the matching is performed using regular expressions, respecting +the setting of the option \fBRE_MATCH_PCRE\fP (see the description of the +function \fBregexp\-replace\fP below)\&. The special replacement facilities +described above for pattern matching are available\&. +.PP +By default the previous source or replacement string will not be offered +for editing\&. However, this feature can be activated by setting the style +\fBedit\-previous\fP in the context \fB:zle:\fP\fIwidget\fP (for example, +\fB:zle:replace\-string\fP) to \fBtrue\fP\&. In addition, a positive +numeric argument forces the previous values to be offered, a negative or +zero argument forces them not to be\&. +.PP +The function \fBreplace\-string\-again\fP can be used to repeat the previous +replacement; no prompting is done\&. As with \fBreplace\-string\fP, if the name +of the widget contains the word `\fBpattern\fP\&' or `\fBregex\fP', pattern or +regular expression matching is performed, else a literal string +replacement\&. Note that the previous source and replacement text are the +same whether pattern, regular expression or string matching is used\&. +.PP +In addition, \fBreplace\-string\fP shows the previous replacement above +the prompt, so long as there was one during the current session; if the +source string is empty, that replacement will be repeated without +the widget prompting for a replacement string\&. +.PP +For example, starting from the line: +.PP +.RS +.nf +\fBprint This line contains fan and fond\fP +.fi +.RE +.PP +and invoking \fBreplace\-pattern\fP with the source string +`\fBf(?)n\fP\&' and +the replacement string `\fBc\e1r\fP\&' produces the not very useful line: +.PP +.RS +.nf +\fBprint This line contains car and cord\fP +.fi +.RE +.PP +The range of the replacement string can be limited by using the +\fBnarrow\-to\-region\-invisible\fP widget\&. One limitation of the current +version is that \fBundo\fP will cycle through changes to the replacement +and source strings before undoing the replacement itself\&. +.RE +.TP +\fBsend\-invisible\fP +This is similar to read\-from\-minibuffer in that it may be called as a +function from a widget or as a widget of its own, and interactively reads +input from the keyboard\&. However, the input being typed is concealed and +a string of asterisks (`\fB*\fP\&') is shown instead\&. The value is saved in +the parameter \fB$INVISIBLE\fP to which a reference is inserted into the +editing buffer at the restored cursor position\&. If the read was aborted +by a keyboard break (typically \fB^G\fP) or another escape from editing such +as \fBpush\-line\fP, \fB$INVISIBLE\fP is set to empty and the original buffer +is restored unchanged\&. +.RS +.PP +If one argument is supplied to the function it is taken as a prompt, +otherwise `\fBNon\-echoed text: \fP\&' is used (as in emacs)\&. If a second and +third argument are supplied they are used to begin and end the reference +to \fB$INVISIBLE\fP that is inserted into the buffer\&. The default is to +open with \fB${\fP, then \fBINVISIBLE\fP, and close with \fB}\fP, but many +other effects are possible\&. +.RE +.TP +\fBsmart\-insert\-last\-word\fP +This function may replace the \fBinsert\-last\-word\fP widget, like so: +.RS +.PP +.RS +.nf +\fBzle \-N insert\-last\-word smart\-insert\-last\-word\fP +.fi +.RE +.PP +With a numeric argument, or when passed command line arguments in a call +from another widget, it behaves like \fBinsert\-last\-word\fP, except that +words in comments are ignored when \fBINTERACTIVE_COMMENTS\fP is set\&. +.PP +Otherwise, the rightmost ``interesting\&'' word from the previous command is +found and inserted\&. The default definition of ``interesting\&'' is that the +word contains at least one alphabetic character, slash, or backslash\&. +This definition may be overridden by use of the \fBmatch\fP style\&. The +context used to look up the style is the widget name, so usually the +context is \fB:insert\-last\-word\fP\&. However, you can bind this function to +different widgets to use different patterns: +.PP +.RS +.nf +\fBzle \-N insert\-last\-assignment smart\-insert\-last\-word +zstyle :insert\-last\-assignment match \&'[[:alpha:]][][[:alnum:]]#=*' +bindkey \&'\ee=' insert\-last\-assignment\fP +.fi +.RE +.PP +If no interesting word is found and the \fBauto\-previous\fP style is set to +a true value, the search continues upward through the history\&. When +\fBauto\-previous\fP is unset or false (the default), the widget must be +invoked repeatedly in order to search earlier history lines\&. +.RE +.TP +\fBtranspose\-lines\fP +Only useful with a multi\-line editing buffer; the lines here are +lines within the current on\-screen buffer, not history lines\&. +The effect is similar to the function of the same name in Emacs\&. +.RS +.PP +Transpose the current line with the previous line and move the cursor +to the start of the next line\&. Repeating this (which can be done by +providing a positive numeric argument) has the effect of moving +the line above the cursor down by a number of lines\&. +.PP +With a negative numeric argument, requires two lines above the +cursor\&. These two lines are transposed and the cursor moved to the +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\&. +.RE +.TP +\fBurl\-quote\-magic\fP +This widget replaces the built\-in \fBself\-insert\fP 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\&. +.RS +.PP +Styles to control quoting behavior: +.PP +.PD 0 +.TP +.PD +\fBurl\-metas\fP +This style is looked up in the context `\fB:url\-quote\-magic:\fP\fIscheme\fP\&' +(where \fIscheme\fP is that of the current URL, e\&.g\&. "\fBftp\fP")\&. 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 \&'\fB<\fP' and +\&'\fB>\fP' but including braces (as in brace expansion)\&. See also +\fBurl\-seps\fP\&. +.TP +\fBurl\-seps\fP +Like \fBurl\-metas\fP, 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 \&'\fB<\fP' and +\&'\fB>\fP' and the first character of \fB$histchars\fP\&. +.TP +\fBurl\-globbers\fP +This style is looked up in the context `\fB:url\-quote\-magic\fP\&'\&. 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 +`\fBnoglob\fP\&' modifier\&. When the first word on the line matches one of the +values \fIand\fP the URL refers to a local file (see \fBurl\-local\-schema\fP), +only the \fBurl\-seps\fP characters are quoted; the \fBurl\-metas\fP are left +alone, allowing them to affect command\-line parsing, completion, etc\&. The +default values are a literal `\fBnoglob\fP\&' plus (when the \fBzsh/parameter\fP +module is available) any commands aliased to the helper function +`\fBurlglobber\fP\&' or its alias `\fBgloburl\fP'\&. +.TP +\fBurl\-local\-schema\fP +This style is always looked up in the context `\fB:urlglobber\fP\&', 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 +"\fBftp\fP" and "\fBfile\fP"\&. +.TP +\fBurl\-other\-schema\fP +Like \fBurl\-local\-schema\fP, but lists all other URI schema upon which +\fBurlglobber\fP and \fBurl\-quote\-magic\fP should act\&. If the URI on the +command line does not have a scheme appearing either in this list or in +\fBurl\-local\-schema\fP, it is not magically quoted\&. The default values are +"\fBhttp\fP", "\fBhttps\fP", and "\fBftp\fP"\&. When a scheme appears both here +and in \fBurl\-local\-schema\fP, it is quoted differently depending on whether +the command name appears in \fBurl\-globbers\fP\&. +.PP +Loading \fBurl\-quote\-magic\fP also defines a helper function `\fBurlglobber\fP\&' +and aliases `\fBgloburl\fP\&' to `\fBnoglob urlglobber\fP'\&. 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\&. +.RE +.TP +\fBvi\-pipe\fP +This function reads a movement command from the keyboard and then +prompts for an external command\&. The part of the buffer covered by +the movement is piped to the external command and then replaced by +the command\&'s output\&. If the movement command is bound to vi\-pipe, +the current line is used\&. +.RS +.PP +The function serves as an example for reading a vi movement command +from within a user\-defined widget\&. +.RE +.TP +\fBwhich\-command\fP +This function is a drop\-in replacement for the builtin widget +\fBwhich\-command\fP\&. It has enhanced behaviour, in that it correctly +detects whether or not the command word needs to be expanded as an +alias; if so, it continues tracing the command word from the expanded +alias until it reaches the command that will be executed\&. +.RS +.PP +The style \fBwhence\fP is available in the context \fB:zle:$WIDGET\fP; this +may be set to an array to give the command and options that will be used to +investigate the command word found\&. The default is \fBwhence \-c\fP\&. +.RE +.TP +\fBzcalc\-auto\-insert\fP +This function is useful together with the \fBzcalc\fP function described in +the section `Mathematical Functions\&'\&. +It should be bound to a key representing a binary operator such +as `\fB+\fP\&', `\fB\-\fP', `\fB*\fP' or `\fB/\fP'\&. When running in zcalc, +if the key occurs at the start of the line or immediately following +an open parenthesis, the text \fB"ans "\fP is inserted before the +representation of the key itself\&. This allows easy use of the +answer from the previous calculation in the current line\&. The +text to be inserted before the symbol typed can be modified by setting +the variable \fBZCALC_AUTO_INSERT_PREFIX\fP\&. +.RS +.PP +Hence, for example, typing `\fB+12\fP\&' followed by return adds 12 +to the previous result\&. +.PP +If zcalc is in RPN mode (\fB\-r\fP option) the effect of this binding is +automatically suppressed as operators alone on a line are meaningful\&. +.PP +When not in zcalc, the key simply inserts the symbol itself\&. +.RE +.PP +.SS "Utility Functions" +.PP +These functions are useful in constructing widgets\&. They +should be loaded with `\fBautoload \-U\fP \fIfunction\fP\&' and called +as indicated from user\-defined widgets\&. +.PP +.PD 0 +.TP +.PD +\fBsplit\-shell\-arguments\fP +This function splits the line currently being edited into shell arguments +and whitespace\&. The result is stored in the array \fBreply\fP\&. The array +contains all the parts of the line in order, starting with any whitespace +before the first argument, and finishing with any whitespace after the last +argument\&. Hence (so long as the option \fBKSH_ARRAYS\fP is not set) +whitespace is given by odd indices in the array and arguments by +even indices\&. Note that no stripping of quotes is done; joining together +all the elements of \fBreply\fP in order is guaranteed to produce the +original line\&. +.RS +.PP +The parameter \fBREPLY\fP is set to the index of the word in \fBreply\fP which +contains the character after the cursor, where the first element has index +1\&. The parameter \fBREPLY2\fP is set to the index of the character under the +cursor in that word, where the first character has index 1\&. +.PP +Hence \fBreply\fP, \fBREPLY\fP and \fBREPLY2\fP should all be made local to +the enclosing function\&. +.PP +See the function \fBmodify\-current\-argument\fP, described below, for +an example of how to call this function\&. +.RE +.TP +\fBmodify\-current\-argument\fP [ \fIexpr\-using\-\fP\fB$ARG\fP | \fIfunc\fP ] +This function provides a simple method of allowing user\-defined widgets +to modify the command line argument under the cursor (or immediately to the +left of the cursor if the cursor is between arguments)\&. +.RS +.PP +The argument can be an expression which when evaluated operates on the shell +parameter \fBARG\fP, which will have been set to the command line argument +under the cursor\&. The expression should be suitably quoted to prevent +it being evaluated too early\&. +.PP +Alternatively, if the argument does not contain the string \fBARG\fP, it +is assumed to be a shell function, to which the current command line +argument is passed as the only argument\&. The function should set the +variable \fBREPLY\fP to the new value for the command line argument\&. +If the function returns non\-zero status, so does the calling function\&. +.PP +For example, a user\-defined widget containing the following code +converts the characters in the argument under the cursor into all upper +case: +.PP +.RS +.nf +\fBmodify\-current\-argument \&'${(U)ARG}'\fP +.fi +.RE +.PP +The following strips any quoting from the current word (whether backslashes +or one of the styles of quotes), and replaces it with single quoting +throughout: +.PP +.RS +.nf +\fBmodify\-current\-argument \&'${(qq)${(Q)ARG}}'\fP +.fi +.RE +.PP +The following performs directory expansion on the command line +argument and replaces it by the absolute path: +.PP +.RS +.nf +\fBexpand\-dir() { + REPLY=${~1} + REPLY=${REPLY:a} +} +modify\-current\-argument expand\-dir\fP +.fi +.RE +.PP +In practice the function \fBexpand\-dir\fP would probably not be defined +within the widget where \fBmodify\-current\-argument\fP is called\&. +.RE +.PP +.SS "Styles" +.PP +The behavior of several of the above widgets can be controlled by the use +of the \fBzstyle\fP mechanism\&. In particular, widgets that interact with +the completion system pass along their context to any completions that +they invoke\&. +.PP +.PD 0 +.TP +.PD +\fBbreak\-keys\fP +This style is used by the \fBincremental\-complete\-word\fP widget\&. Its value +should be a pattern, and all keys matching this pattern will cause the +widget to stop incremental completion without the key having any further +effect\&. Like all styles used directly by +\fBincremental\-complete\-word\fP, this style is looked up using the +context `\fB:incremental\fP\&'\&. +.TP +\fBcompleter\fP +The \fBincremental\-complete\-word\fP and \fBinsert\-and\-predict\fP widgets set +up their top\-level context name before calling completion\&. This allows +one to define different sets of completer functions for normal completion +and for these widgets\&. For example, to use completion, approximation and +correction for normal completion, completion and correction for +incremental completion and only completion for prediction one could use: +.RS +.PP +.RS +.nf +\fBzstyle \&':completion:*' completer \e + _complete _correct _approximate +zstyle \&':completion:incremental:*' completer \e + _complete _correct +zstyle \&':completion:predict:*' completer \e + _complete\fP +.fi +.RE +.PP +It is a good idea to restrict the completers used in prediction, because +they may be automatically invoked as you type\&. The \fB_list\fP and +\fB_menu\fP completers should never be used with prediction\&. The +\fB_approximate\fP, \fB_correct\fP, \fB_expand\fP, and \fB_match\fP completers may +be used, but be aware that they may change characters anywhere in the word +behind the cursor, so you need to watch carefully that the result is what +you intended\&. +.RE +.TP +\fBcursor\fP +The \fBinsert\-and\-predict\fP widget uses this style, in the context +`\fB:predict\fP\&', to decide where to place the cursor after completion has +been tried\&. Values are: +.RS +.PP +.PD 0 +.TP +.PD +\fBcomplete\fP +The cursor is left where it was when completion finished, but only if +it is after a character equal to the one just inserted by the user\&. If +it is after another character, this value is the same as `\fBkey\fP\&'\&. +.TP +\fBkey\fP +The cursor is left +after the \fIn\fPth occurrence of the character just inserted, where +\fIn\fP is the number of times that character appeared in the word +before completion was attempted\&. In short, this has the effect of +leaving the cursor after the character just typed even if the +completion code found out that no other characters need to be inserted +at that position\&. +.PP +Any other value for this style unconditionally leaves the cursor at the +position where the completion code left it\&. +.RE +.TP +\fBlist\fP +When using the \fBincremental\-complete\-word\fP widget, this style says +if the matches should be listed on every key press (if they fit on the +screen)\&. Use the context prefix `\fB:completion:incremental\fP\&'\&. +.RS +.PP +The \fBinsert\-and\-predict\fP widget uses this style to decide if the +completion should be shown even if there is only one possible completion\&. +This is done if the value of this style is the string \fBalways\fP\&. In this +case the context is `\fB:predict\fP\&' (\fInot\fP `\fB:completion:predict\fP')\&. +.RE +.TP +\fBmatch\fP +This style is used by \fBsmart\-insert\-last\-word\fP to provide a pattern +(using full \fBEXTENDED_GLOB\fP syntax) that matches an interesting word\&. +The context is the name of the widget to which \fBsmart\-insert\-last\-word\fP +is bound (see above)\&. The default behavior of \fBsmart\-insert\-last\-word\fP +is equivalent to: +.RS +.PP +.RS +.nf +\fBzstyle :insert\-last\-word match \&'*[[:alpha:]/\e\e]*'\fP +.fi +.RE +.PP +However, you might want to include words that contain spaces: +.PP +.RS +.nf +\fBzstyle :insert\-last\-word match \&'*[[:alpha:][:space:]/\e\e]*'\fP +.fi +.RE +.PP +Or include numbers as long as the word is at least two characters long: +.PP +.RS +.nf +\fBzstyle :insert\-last\-word match \&'*([[:digit:]]?|[[:alpha:]/\e\e])*'\fP +.fi +.RE +.PP +The above example causes redirections like "2>" to be included\&. +.RE +.TP +\fBprompt\fP +The \fBincremental\-complete\-word\fP widget shows the value of this +style in the status line during incremental completion\&. The string +value may contain any of the following substrings in the manner of +the \fBPS1\fP and other prompt parameters: +.RS +.PP +.PD 0 +.TP +.PD +\fB%c\fP +Replaced by the name of the completer function that generated the +matches (without the leading underscore)\&. +.TP +\fB%l\fP +When the \fBlist\fP style is set, +replaced by `\fB\&.\&.\&.\fP\&' if the list of matches is too long to fit on the +screen and with an empty string otherwise\&. If the \fBlist\fP style is +`false\&' or not set, `\fB%l\fP' is always removed\&. +.TP +\fB%n\fP +Replaced by the number of matches generated\&. +.TP +\fB%s\fP +Replaced by `\fB\-no match\-\fP\&', `\fB\-no prefix\-\fP', or an empty string +if there is no completion matching the word on the line, if the +matches have no common prefix different from the word on the line, or +if there is such a common prefix, respectively\&. +.TP +\fB%u\fP +Replaced by the unambiguous part of all matches, if there +is any, and if it is different from the word on the line\&. +.PP +Like `\fBbreak\-keys\fP\&', this uses the `\fB:incremental\fP' context\&. +.RE +.TP +\fBstop\-keys\fP +This style is used by the \fBincremental\-complete\-word\fP widget\&. Its value +is treated similarly to the one for the \fBbreak\-keys\fP style (and uses +the same context: `\fB:incremental\fP\&')\&. However, in +this case all keys matching the pattern given as its value will stop +incremental completion and will then execute their usual function\&. +.TP +\fBtoggle\fP +This boolean style is used by \fBpredict\-on\fP and its related widgets in +the context `\fB:predict\fP\&'\&. If set to one of the standard `true' values, +predictive typing is automatically toggled off in situations where it is +unlikely to be useful, such as when editing a multi\-line buffer or after +moving into the middle of a line and then deleting a character\&. The +default is to leave prediction turned on until an explicit call to +\fBpredict\-off\fP\&. +.TP +\fBverbose\fP +This boolean style is used by \fBpredict\-on\fP and its related widgets in +the context `\fB:predict\fP\&'\&. If set to one of the standard `true' values, +these widgets display a message below the prompt when the predictive state +is toggled\&. This is most useful in combination with the \fBtoggle\fP style\&. +The default does not display these messages\&. +.TP +\fBwidget\fP +This style is similar to the \fBcommand\fP style: For widget functions that +use \fBzle\fP to call other widgets, this style can sometimes be used to +override the widget which is called\&. The context for this style is the +name of the calling widget (\fInot\fP the name of the calling function, +because one function may be bound to multiple widget names)\&. +.RS +.PP +.RS +.nf +\fBzstyle :copy\-earlier\-word widget smart\-insert\-last\-word\fP +.fi +.RE +.PP +Check the documentation for the calling widget or function to determine +whether the \fBwidget\fP style is used\&. +.RE +.PP +.SH "EXCEPTION HANDLING" +.PP +Two functions are provided to enable zsh to provide exception handling in a +form that should be familiar from other languages\&. +.PP +.PD 0 +.TP +.PD +\fBthrow\fP \fIexception\fP +The function \fBthrow\fP throws the named \fIexception\fP\&. The name is +an arbitrary string and is only used by the \fBthrow\fP and \fBcatch\fP +functions\&. An exception is for the most part treated the same as a +shell error, i\&.e\&. an unhandled exception will cause the shell to abort all +processing in a function or script and to return to the top level in an +interactive shell\&. +.TP +\fBcatch\fP \fIexception\-pattern\fP +The function \fBcatch\fP returns status zero if an exception was thrown and +the pattern \fIexception\-pattern\fP matches its name\&. Otherwise it +returns status 1\&. \fIexception\-pattern\fP is a standard +shell pattern, respecting the current setting of the \fBEXTENDED_GLOB\fP +option\&. An alias \fBcatch\fP is also defined to prevent the argument to the +function from matching filenames, so patterns may be used unquoted\&. Note +that as exceptions are not fundamentally different from other shell errors +it is possible to catch shell errors by using an empty string as the +exception name\&. The shell variable \fBCAUGHT\fP is set by \fBcatch\fP to the +name of the exception caught\&. It is possible to rethrow an exception by +calling the \fBthrow\fP function again once an exception has been caught\&. +.PP +The functions are designed to be used together with the \fBalways\fP construct +described in +\fIzshmisc\fP(1)\&. This is important as only this +construct provides the required support for exceptions\&. A typical example +is as follows\&. +.PP +.RS +.nf +\fB{ + # "try" block + # \&.\&.\&. nested code here calls "throw MyExcept" +} always { + # "always" block + if catch MyExcept; then + print "Caught exception MyExcept" + elif catch \&''; then + print "Caught a shell error\&. Propagating\&.\&.\&." + throw \&'' + fi + # Other exceptions are not handled but may be caught further + # up the call stack\&. +}\fP +.fi +.RE +.PP +If all exceptions should be caught, the following idiom might be +preferable\&. +.PP +.RS +.nf +\fB{ + # \&.\&.\&. nested code here throws an exception +} always { + if catch *; then + case $CAUGHT in + (MyExcept) + print "Caught my own exception" + ;; + (*) + print "Caught some other exception" + ;; + esac + fi +}\fP +.fi +.RE +.PP +In common with exception handling in other languages, the exception may be +thrown by code deeply nested inside the `try\&' block\&. However, note that it +must be thrown inside the current shell, not in a subshell forked for a +pipeline, parenthesised current\-shell construct, or some form of +command or process substitution\&. +.PP +The system internally uses the shell variable \fBEXCEPTION\fP to record the +name of the exception between throwing and catching\&. One drawback of this +scheme is that if the exception is not handled the variable \fBEXCEPTION\fP +remains set and may be incorrectly recognised as the name of an exception +if a shell error subsequently occurs\&. Adding \fBunset EXCEPTION\fP at the +start of the outermost layer of any code that uses exception handling will +eliminate this problem\&. +.PP +.SH "MIME FUNCTIONS" +.PP +Three functions are available to provide handling of files recognised by +extension, for example to dispatch a file \fBtext\&.ps\fP when executed as a +command to an appropriate viewer\&. +.PP +.PD 0 +.TP +.PD 0 +\fBzsh\-mime\-setup\fP [ \fB\-fv\fP ] [ \fB\-l\fP [ \fIsuffix\fP \&.\&.\&. ] ] +.TP +.PD +\fBzsh\-mime\-handler\fP [ \fB\-l\fP ] \fIcommand argument\fP \&.\&.\&. +These two functions use the files \fB~/\&.mime\&.types\fP and \fB/etc/mime\&.types\fP, +which associate types and extensions, as well as \fB~/\&.mailcap\fP and +\fB/etc/mailcap\fP files, which associate types and the programs that +handle them\&. These are provided on many systems with the Multimedia +Internet Mail Extensions\&. +.RS +.PP +To enable the system, the function \fBzsh\-mime\-setup\fP should be +autoloaded and run\&. This allows files with extensions to be treated +as executable; such files be completed by the function completion system\&. +The function \fBzsh\-mime\-handler\fP should not need to be called by the +user\&. +.PP +The system works by setting up suffix aliases with `\fBalias \-s\fP\&'\&. +Suffix aliases already installed by the user will not be overwritten\&. +.PP +For suffixes defined in lower case, upper case variants will also +automatically be handled (e\&.g\&. \fBPDF\fP is automatically handled if +handling for the suffix \fBpdf\fP is defined), but not vice versa\&. +.PP +Repeated calls to \fBzsh\-mime\-setup\fP do not override the existing +mapping between suffixes and executable files unless the option \fB\-f\fP +is given\&. Note, however, that this does not override existing suffix +aliases assigned to handlers other than \fBzsh\-mime\-handler\fP\&. +.PP +Calling \fBzsh\-mime\-setup\fP with the option \fB\-l\fP lists the existing +mappings without altering them\&. Suffixes to list (which may contain +pattern characters that should be quoted from immediate interpretation +on the command line) may be given as additional arguments, otherwise +all suffixes are listed\&. +.PP +Calling \fBzsh\-mime\-setup\fP with the option +\fB\-v\fP causes verbose output to be shown during the setup operation\&. +.PP +The system respects the \fBmailcap\fP flags \fBneedsterminal\fP and +\fBcopiousoutput\fP; see \fImailcap\fP(4) or \fImailcap\fP(5) +(the man page\&'s name varies across platforms)\&. +.PP +The functions use the following styles, which are defined with the +\fBzstyle\fP builtin command (see \fIzshmodules\fP(1))\&. They should be defined +before \fBzsh\-mime\-setup\fP is run\&. The contexts used all +start with \fB:mime:\fP, with additional components in some cases\&. +It is recommended that a trailing \fB*\fP (suitably quoted) be appended +to style patterns in case the system is extended in future\&. Some +examples are given below\&. +.PP +For files that have multiple suffixes, e\&.g\&. \fB\&.pdf\&.gz\fP, where the +context includes the suffix it will be looked up starting with the +longest possible suffix until a match for the style is found\&. +For example, if \fB\&.pdf\&.gz\fP produces a match for the handler, that +will be used; otherwise the handler for \fB\&.gz\fP will be used\&. Note +that, owing to the way suffix aliases work, it is always required that +there be a handler for the shortest possible suffix, so in this example +\fB\&.pdf\&.gz\fP can only be handled if \fB\&.gz\fP is also handled (though +not necessarily in the same way)\&. Alternatively, if no handling +for \fB\&.gz\fP on its own is needed, simply adding the command +.PP +.RS +.nf +\fBalias \-s gz=zsh\-mime\-handler\fP +.fi +.RE +.PP +to the initialisation code is sufficient; \fB\&.gz\fP will not be handled +on its own, but may be in combination with other suffixes\&. +.PP +.PD 0 +.TP +.PD +\fBcurrent\-shell\fP +If this boolean style is true, the mailcap handler for the context in +question is run using the \fBeval\fP builtin instead of by starting a new +\fBsh\fP process\&. This is more efficient, but may not work in the occasional +cases where the mailcap handler uses strict POSIX syntax\&. +.TP +\fBdisown\fP +If this boolean style is true, mailcap handlers started in the +background will be disowned, i\&.e\&. not subject to job control within +the parent shell\&. Such handlers nearly always produce their own +windows, so the only likely harmful side effect of setting the style is +that it becomes harder to kill jobs from within the shell\&. +.TP +\fBexecute\-as\-is\fP +This style gives a list of patterns to be matched against files +passed for execution with a handler program\&. If the file matches +the pattern, the entire command line is executed in its current form, +with no handler\&. This is useful for files which might have suffixes +but nonetheless be executable in their own right\&. If the style +is not set, the pattern \fB*(*) *(/)\fP is used; +hence executable files are executed directly and not passed to a +handler, and the option \fBAUTO_CD\fP may be used to change to directories +that happen to have MIME suffixes\&. +.TP +\fBexecute\-never\fP +This style is useful in combination with \fBexecute\-as\-is\fP\&. It is +set to an array of patterns corresponding to full paths to files that +should never be treated as executable, even if the file passed to +the MIME handler matches \fBexecute\-as\-is\fP\&. This is useful for file +systems that don\&'t handle execute permission or that contain executables +from another operating system\&. For example, if \fB/mnt/windows\fP is a +Windows mount, then +.RS +.PP +.RS +.nf +\fBzstyle \&':mime:*' execute\-never '/mnt/windows/*'\fP +.fi +.RE +.PP +will ensure that any files found in that area will be executed as MIME +types even if they are executable\&. As this example shows, the complete +file name is matched against the pattern, regardless of how the file +was passed to the handler\&. The file is resolved to a full path using +the \fB:P\fP modifier described in +the subsection `Modifiers\&' in \fIzshexpn\fP(1); +this means that symbolic links are resolved where possible, so that +links into other file systems behave in the correct fashion\&. +.RE +.TP +\fBfile\-path\fP +Used if the style \fBfind\-file\-in\-path\fP is true for the same context\&. +Set to an array of directories that are used for searching for the +file to be handled; the default is the command path given by the +special parameter \fBpath\fP\&. The shell option \fBPATH_DIRS\fP is respected; +if that is set, the appropriate path will be searched even if the +name of the file to be handled as it appears on the command line contains +a `\fB/\fP\&'\&. +The full context is \fB:mime:\&.\fP\fIsuffix\fP\fB:\fP, as described for the style +\fBhandler\fP\&. +.TP +\fBfind\-file\-in\-path\fP +If set, allows files whose names do not contain absolute paths +to be searched for in the command path or the path specified by the +\fBfile\-path\fP style\&. If the file is not found in the path, it is looked +for locally (whether or not the current directory is in the path); if it is +not found locally, the handler will abort unless the \fBhandle\-nonexistent\fP +style is set\&. Files found in the path are tested as described for +the style \fBexecute\-as\-is\fP\&. +The full context is \fB:mime:\&.\fP\fIsuffix\fP\fB:\fP, as described for the style +\fBhandler\fP\&. +.TP +\fBflags\fP +Defines flags to go with a handler; the context is as for the +\fBhandler\fP style, and the format is as for the flags in \fBmailcap\fP\&. +.TP +\fBhandle\-nonexistent\fP +By default, arguments that don\&'t correspond to files are not passed +to the MIME handler in order to prevent it from intercepting commands found +in the path that happen to have suffixes\&. This style may be set to +an array of extended glob patterns for arguments that will be passed to the +handler even if they don\&'t exist\&. If it is not explicitly set it +defaults to \fB[[:alpha:]]#:/*\fP which allows URLs to be passed to the MIME +handler even though they don\&'t exist in that format in the file system\&. +The full context is \fB:mime:\&.\fP\fIsuffix\fP\fB:\fP, as described for the style +\fBhandler\fP\&. +.TP +\fBhandler\fP +Specifies a handler for a suffix; the suffix is given by the context as +\fB:mime:\&.\fP\fIsuffix\fP\fB:\fP, and the format of the handler is exactly +that in \fBmailcap\fP\&. Note in particular the `\fB\&.\fP\&' and trailing colon +to distinguish this use of the context\&. This overrides any handler +specified by the \fBmailcap\fP files\&. If the handler requires a terminal, +the \fBflags\fP style should be set to include the word \fBneedsterminal\fP, +or if the output is to be displayed through a pager (but not if the +handler is itself a pager), it should include \fBcopiousoutput\fP\&. +.TP +\fBmailcap\fP +A list of files in the format of \fB~/\&.mailcap\fP and +\fB/etc/mailcap\fP to be read during setup, replacing the default list +which consists of those two files\&. The context is \fB:mime:\fP\&. +A \fB+\fP in the list will be replaced by the default files\&. +.TP +\fBmailcap\-priorities\fP +This style is used to resolve multiple mailcap entries for the same MIME +type\&. It consists of an array of the following elements, in descending +order of priority; later entries will be used if earlier entries are +unable to resolve the entries being compared\&. If none of the tests +resolve the entries, the first entry encountered is retained\&. +.RS +.PP +.PD 0 +.TP +.PD +\fBfiles\fP +The order of files (entries in the \fBmailcap\fP style) read\&. Earlier +files are preferred\&. (Note this does not resolve entries in the same file\&.) +.TP +\fBpriority\fP +The priority flag from the mailcap entry\&. The priority is an integer +from 0 to 9 with the default value being 5\&. +.TP +\fBflags\fP +The test given by the \fBmailcap\-prio\-flags\fP option is used to resolve +entries\&. +.TP +\fBplace\fP +Later entries are preferred; as the entries are strictly ordered, this +test always succeeds\&. +.PP +Note that as this style is handled during initialisation, the context +is always \fB:mime:\fP, with no discrimination by suffix\&. +.RE +.TP +\fBmailcap\-prio\-flags\fP +This style is used when the keyword \fBflags\fP is encountered in the +list of tests specified by the \fBmailcap\-priorities\fP style\&. +It should be set to a list of patterns, each of which is tested against +the flags specified in the mailcap entry (in other words, the sets of +assignments found with some entries in the mailcap file)\&. Earlier +patterns in the list are preferred to later ones, and matched patterns +are preferred to unmatched ones\&. +.TP +\fBmime\-types\fP +A list of files in the format of \fB~/\&.mime\&.types\fP and +\fB/etc/mime\&.types\fP to be read during setup, replacing the default list +which consists of those two files\&. The context is \fB:mime:\fP\&. +A \fB+\fP in the list will be replaced by the default files\&. +.TP +\fBnever\-background\fP +If this boolean style is set, the handler for the given context is +always run in the foreground, even if the flags provided in the mailcap +entry suggest it need not be (for example, it doesn\&'t require a +terminal)\&. +.TP +\fBpager\fP +If set, will be used instead of \fB$PAGER\fP or \fBmore\fP to handle +suffixes where the \fBcopiousoutput\fP flag is set\&. The context is +as for \fBhandler\fP, i\&.e\&. \fB:mime:\&.\fP\fIsuffix\fP\fB:\fP for handling +a file with the given \fIsuffix\fP\&. +.PP +Examples: +.PP +.RS +.nf +\fBzstyle \&':mime:*' mailcap ~/\&.mailcap /usr/local/etc/mailcap +zstyle \&':mime:\&.txt:' handler less %s +zstyle \&':mime:\&.txt:' flags needsterminal\fP +.fi +.RE +.PP +When \fBzsh\-mime\-setup\fP is subsequently run, it will look for +\fBmailcap\fP entries in the two files given\&. Files of suffix \fB\&.txt\fP +will be handled by running `\fBless\fP \fIfile\&.txt\fP\&'\&. The flag +\fBneedsterminal\fP is set to show that this program must run attached to a +terminal\&. +.PP +As there are several steps to dispatching a command, the following +should be checked if attempting to execute a file by extension +\fB\&.\fP\fIext\fP does not have the expected effect\&. +.PP +The command `\fBalias \-s\fP \fIext\fP\&' should show +`\fBps=zsh\-mime\-handler\fP\&'\&. If it shows something else, another suffix +alias was already installed and was not overwritten\&. If it shows +nothing, no handler was installed: this is most likely because no +handler was found in the \fB\&.mime\&.types\fP and \fBmailcap\fP combination for +\fB\&.ext\fP files\&. In that case, appropriate handling should be added to +\fB~/\&.mime\&.types\fP and \fBmailcap\fP\&. +.PP +If the extension is handled by \fBzsh\-mime\-handler\fP but the file is +not opened correctly, either the handler defined for the type is +incorrect, or the flags associated with it are in appropriate\&. Running +\fBzsh\-mime\-setup \-l\fP will show the handler and, if there are any, the +flags\&. A \fB%s\fP in the handler is replaced by the file (suitably quoted +if necessary)\&. Check that the handler program listed lists and can +be run in the way shown\&. Also check that the flags \fBneedsterminal\fP or +\fBcopiousoutput\fP are set if the handler needs to be run under a +terminal; the second flag is used if the output should be sent to a pager\&. +An example of a suitable \fBmailcap\fP entry for such a program is: +.PP +.RS +.nf +\fBtext/html; /usr/bin/lynx \&'%s'; needsterminal\fP +.fi +.RE +.PP +Running `\fBzsh\-mime\-handler \-l\fP \fIcommand line\fP\&' prints the command +line that would be executed, simplified to remove the effect of any +flags, and quoted so that the output can be run as a complete zsh +command line\&. This is used by the completion system to decide how to +complete after a file handled by \fBzsh\-mime\-setup\fP\&. +.RE +.TP +\fBpick\-web\-browser\fP +This function is separate from the two MIME functions described above +and can be assigned directly to a suffix: +.RS +.PP +.RS +.nf +\fBautoload \-U pick\-web\-browser +alias \-s html=pick\-web\-browser\fP +.fi +.RE +.PP +It is provided as an intelligent front end to dispatch a web browser\&. +It may be run as either a function or a shell script\&. The status +255 is returned if no browser could be started\&. +.PP +Various styles are available to customize the choice of browsers: +.PP +.PD 0 +.TP +.PD +\fBbrowser\-style\fP +The value of the style is an array giving preferences in decreasing order +for the type of browser to use\&. The values of elements may be +.RS +.PP +.PD 0 +.TP +.PD +\fBrunning\fP +Use a GUI browser that is already running when an X Window display is +available\&. The browsers listed in the \fBx\-browsers\fP style are tried +in order until one is found; if it is, the file will be displayed in +that browser, so the user may need to check whether it has appeared\&. +If no running browser is found, one is not started\&. Browsers other than +Firefox, Opera and Konqueror are assumed to understand the Mozilla +syntax for opening a URL remotely\&. +.TP +\fBx\fP +Start a new GUI browser when an X Window display is available\&. Search for +the availability of one of the browsers listed in the \fBx\-browsers\fP style +and start the first one that is found\&. No check is made for an already +running browser\&. +.TP +\fBtty\fP +Start a terminal\-based browser\&. Search for the availability of one +of the browsers listed in the \fBtty\-browsers\fP style and start the +first one that is found\&. +.PP +If the style is not set the default \fBrunning x tty\fP is used\&. +.RE +.TP +\fBx\-browsers\fP +An array in decreasing order +of preference of browsers to use when running under the X Window System\&. +The array consists of the command name under which to start the +browser\&. They are looked up in the context \fB:mime:\fP (which may +be extended in future, so appending `\fB*\fP\&' is recommended)\&. For +example, +.RS +.PP +.RS +.nf +\fBzstyle \&':mime:*' x\-browsers opera konqueror firefox\fP +.fi +.RE +.PP +specifies that \fBpick\-web\-browser\fP should first look for a running +instance of Opera, Konqueror or Firefox, in that order, and if it +fails to find any should attempt to start Opera\&. The default is +\fBfirefox mozilla netscape opera konqueror\fP\&. +.RE +.TP +\fBtty\-browsers\fP +An array similar to \fBx\-browsers\fP, except that it gives browsers to +use when no X Window display is available\&. The default is +\fBelinks links lynx\fP\&. +.TP +\fBcommand\fP +If it is set this style is used to pick the command +used to open a page for a browser\&. The context is +\fB:mime:browser:new:$browser:\fP to start a new browser or +\fB:mime:browser:running:$browser:\fP to open a URL in a browser already +running on the current X display, where \fB$browser\fP is the value matched +in the \fBx\-browsers\fP or \fBtty\-browsers\fP style\&. The escape sequence +\fB%b\fP in the style\&'s value will be replaced by the browser, while \fB%u\fP +will be replaced by the URL\&. If the style is not set, the default for all +new instances is equivalent to \fB%b %u\fP and the defaults for using running +browsers are equivalent to the values \fBkfmclient openURL %u\fP for +Konqueror, \fBfirefox \-new\-tab %u\fP for Firefox, \fBopera \-newpage %u\fP +for Opera, and \fB%b \-remote "openUrl(%u)"\fP for all others\&. +.RE +.PP +.SH "MATHEMATICAL FUNCTIONS" +.PP +.PD 0 +.TP +.PD +\fBzcalc\fP [ \fB\-erf\fP ] [ \fIexpression\fP \&.\&.\&. ] +A reasonably powerful calculator based on zsh\&'s arithmetic evaluation +facility\&. The syntax is similar to that of formulae in most programming +languages; see +the section `Arithmetic Evaluation\&' in \fIzshmisc\fP(1) for details\&. +.RS +.PP +Non\-programmers should note that, as in many other programming +languages, expressions involving only integers (whether constants +without a `\fB\&.\fP\&', variables containing such constants as strings, or +variables declared to be integers) are by default evaluated using +integer arithmetic, which is not how an ordinary desk calculator +operates\&. To force floating point operation, pass the option \fB\-f\fP; +see further notes below\&. +.PP +If the file \fB~/\&.zcalcrc\fP 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; \fBemulate \-L zsh\fP +and \fBsetopt extendedglob\fP 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 \fB$ZDOTDIR\fP is used +instead of \fB$HOME\fP if it is set\&. +.PP +The mathematical library \fBzsh/mathfunc\fP will be loaded if it is +available; see +the section `The zsh/mathfunc Module\&' in \fIzshmodules\fP(1)\&. The mathematical functions +correspond to the raw system libraries, so trigonometric functions are +evaluated using radians, and so on\&. +.PP +Each line typed is evaluated as an expression\&. The prompt shows a number, +which corresponds to a positional parameter where the result of that +calculation is stored\&. For example, the result of the calculation on the +line preceded by `\fB4> \fP\&' is available as \fB$4\fP\&. The last value +calculated is available as \fBans\fP\&. Full command line editing, including +the history of previous calculations, is available; the history is saved in +the file \fB~/\&.zcalc_history\fP\&. To exit, enter a blank line or type `\fB:q\fP\&' +on its own (`\fBq\fP\&' is allowed for historical compatibility)\&. +.PP +A line ending with a single backslash is treated in the same fashion +as it is in command line editing: the backslash is removed, the +function prompts for more input (the prompt is preceded by `\fB\&.\&.\&.\fP\&' +to indicate this), and the lines are combined into one to get the final +result\&. In addition, if the input so far contains more open than +close parentheses \fBzcalc\fP will prompt for more input\&. +.PP +If arguments are given to \fBzcalc\fP on start up, they are used to prime the +first few positional parameters\&. A visual indication of this is given when +the calculator starts\&. +.PP +The constants \fBPI\fP (3\&.14159\&.\&.\&.) and \fBE\fP (2\&.71828\&.\&.\&.) are provided\&. +Parameter assignment is possible, but note that all parameters will be +put into the global namespace unless the \fB:local\fP special command is +used\&. The function creates local variables whose names start with +\fB_\fP, so users should avoid doing so\&. The variables \fBans\fP (the last +answer) and \fBstack\fP (the stack in RPN mode) may be referred to +directly; \fBstack\fP is an array but elements of it are numeric\&. Various +other special variables are used locally with their standard meaning, +for example \fBcompcontext\fP, \fBmatch\fP, \fBmbegin\fP, \fBmend\fP, \fBpsvar\fP\&. +.PP +The output base can be initialised by passing the option `\fB\-#\fP\fIbase\fP\&', +for example `\fBzcalc \-#16\fP\&' (the `\fB#\fP' may have to be quoted, depending +on the globbing options set)\&. +.PP +If the option `\fB\-e\fP\&' is set, the function runs non\-interactively: +the arguments are treated as expressions to be evaluated as if entered +interactively line by line\&. +.PP +If the option `\fB\-f\fP\&' is set, all numbers are treated as floating +point, hence for example the expression `\fB3/4\fP\&' evaluates to 0\&.75 +rather than 0\&. Options must appear in separate words\&. +.PP +If the option `\fB\-r\fP\&' is set, RPN (Reverse Polish Notation) mode is +entered\&. This has various additional properties: +.PD 0 +.TP +.PD +Stack +Evaluated values are maintained in a stack; this is contained in +an array named \fBstack\fP with the most recent value in \fB${stack[1]}\fP\&. +.TP +Operators and functions +If the line entered matches an operator (\fB+\fP, \fB\-\fP, \fB*\fP, +\fB/\fP, \fB**\fP, \fB^\fP, \fB|\fP or \fB&\fP) or a function supplied by the +\fBzsh/mathfunc\fP library, the bottom element or elements of the stack +are popped to use as the argument or arguments\&. The higher elements +of stack (least recent) are used as earlier arguments\&. The result is +then pushed into \fB${stack[1]}\fP\&. +.TP +Expressions +Other expressions are evaluated normally, printed, and added to the +stack as numeric values\&. The syntax within expressions on a single line +is normal shell arithmetic (not RPN)\&. +.TP +Stack listing +If an integer follows the option \fB\-r\fP with no space, then +on every evaluation that many elements of the stack, where available, +are printed instead of just the most recent result\&. Hence, for example, +\fBzcalc \-r4\fP shows \fB$stack[4]\fP to \fB$stack[1]\fP each time results +are printed\&. +.TP +Duplication: \fB=\fP +The pseudo\-operator \fB=\fP causes the most recent element of +the stack to be duplicated onto the stack\&. +.TP +\fBpop\fP +The pseudo\-function \fBpop\fP causes the most recent element of +the stack to be popped\&. A `\fB>\fP\&' on its own has the same effect\&. +.TP +\fB>\fP\fIident\fP +The expression \fB>\fP followed (with no space) by a shell identifier +causes the most recent element of the stack to be popped and +assigned to the variable with that name\&. The variable is +local to the \fBzcalc\fP function\&. +.TP +\fB<\fP\fIident\fP +The expression \fB<\fP followed (with no space) by a shell identifier +causes the value of the variable with that name to be pushed +onto the stack\&. \fIident\fP may be an integer, in which +case the previous result with that number (as shown before +the \fB>\fP in the standard \fBzcalc\fP prompt) is put on the stack\&. +.TP +Exchange: \fBxy\fP +The pseudo\-function \fBxy\fP causes the most recent two elements of +the stack to be exchanged\&. `\fB<>\fP\&' has the same effect\&. +.PP +The prompt is configurable via the parameter \fBZCALCPROMPT\fP, which +undergoes standard prompt expansion\&. The index of the current entry is +stored locally in the first element of the array \fBpsvar\fP, which can be +referred to in \fBZCALCPROMPT\fP as `\fB%1v\fP\&'\&. The default prompt is +`\fB%1v> \fP\&'\&. +.PP +The variable \fBZCALC_ACTIVE\fP is set within the function and can +be tested by nested functions; it has the value \fBrpn\fP if RPN mode is +active, else 1\&. +.PP +A few special commands are available; these are introduced by a colon\&. +For backward compatibility, the colon may be omitted for certain +commands\&. Completion is available if \fBcompinit\fP has been run\&. +.PP +The output precision may be specified within zcalc by special commands +familiar from many calculators\&. +.PD 0 +.TP +.PD +\fB:norm\fP +The default output format\&. It corresponds to the printf \fB%g\fP +specification\&. Typically this shows six decimal digits\&. +.TP +\fB:sci\fP \fIdigits\fP +Scientific notation, corresponding to the printf \fB%g\fP output format with +the precision given by \fIdigits\fP\&. This produces either fixed point or +exponential notation depending on the value output\&. +.TP +\fB:fix\fP \fIdigits\fP +Fixed point notation, corresponding to the printf \fB%f\fP output format with +the precision given by \fIdigits\fP\&. +.TP +\fB:eng\fP \fIdigits\fP +Exponential notation, corresponding to the printf \fB%E\fP output format with +the precision given by \fIdigits\fP\&. +.TP +\fB:raw\fP +Raw output: this is the default form of the output from a math +evaluation\&. This may show more precision than the number actually +possesses\&. +.PP +Other special commands: +.PD 0 +.TP +.PD +\fB:!\fP\fIline\&.\&.\&.\fP +Execute \fIline\&.\&.\&.\fP as a normal shell command line\&. Note that it +is executed in the context of the function, i\&.e\&. with local variables\&. +Space is optional after \fB:!\fP\&. +.TP +\fB:local\fP \fIarg\fP \&.\&.\&. +Declare variables local to the function\&. Other variables +may be used, too, but they will be taken from or put into the global +scope\&. +.TP +\fB:function\fP \fIname\fP [ \fIbody\fP ] +Define a mathematical function or (with no \fIbody\fP) delete it\&. +\fB:function\fP may be abbreviated to \fB:func\fP or simply \fB:f\fP\&. +The \fIname\fP may contain the same characters as a shell function name\&. +The function is defined using \fBzmathfuncdef\fP, see below\&. +.RS +.PP +Note that \fBzcalc\fP takes care of all quoting\&. Hence for example: +.PP +.RS +.nf +\fB:f cube $1 * $1 * $1\fP +.fi +.RE +.PP +defines a function to cube the sole argument\&. Functions so defined, or +indeed any functions defined directly or indirectly using \fBfunctions +\-M\fP, are available to execute by typing only the name on the line in RPN +mode; this pops the appropriate number of arguments off the stack +to pass to the function, i\&.e\&. 1 in the case of the example \fBcube\fP +function\&. If there are optional arguments only the mandatory +arguments are supplied by this means\&. +.RE +.TP +\fB[#\fP\fIbase\fP\fB]\fP +This is not a special command, rather part of normal arithmetic +syntax; however, when this form appears on a line by itself the default +output radix is set to \fIbase\fP\&. Use, for example, `\fB[#16]\fP\&' to display +hexadecimal output preceded by an indication of the base, or `\fB[##16]\fP\&' +just to display the raw number in the given base\&. Bases themselves are +always specified in decimal\&. `\fB[#]\fP\&' restores the normal output format\&. +Note that setting an output base suppresses floating point output; use +`\fB[#]\fP\&' to return to normal operation\&. +.TP +\fB$\fP\fIvar\fP +Print out the value of var literally; does not affect the calculation\&. +To use the value of var, omit the leading `\fB$\fP\&'\&. +.PP +See the comments in the function for a few extra tips\&. +.RE +.TP +.PD 0 +\fBmin(\fP\fIarg\fP\fB, \&.\&.\&.)\fP +.TP +.PD 0 +\fBmax(\fP\fIarg\fP\fB, \&.\&.\&.)\fP +.TP +.PD 0 +\fBsum(\fP\fIarg\fP\fB, \&.\&.\&.)\fP +.TP +.PD +\fBzmathfunc\fP +The function \fBzmathfunc\fP defines the three mathematical functions +\fBmin\fP, \fBmax\fP, and \fBsum\fP\&. The functions \fBmin\fP and \fBmax\fP take +one or more arguments\&. The function \fBsum\fP takes zero or more arguments\&. +Arguments can be of different types (ints and floats)\&. +.RS +.PP +Not to be confused with the \fBzsh/mathfunc\fP module, described in +the section `The zsh/mathfunc Module\&' in \fIzshmodules\fP(1)\&. +.RE +.TP +\fBzmathfuncdef\fP [ \fImathfunc\fP [ \fIbody\fP ] ] +A convenient front end to \fBfunctions \-M\fP\&. +.RS +.PP +With two arguments, define a mathematical function named \fImathfunc\fP +which can be used in any form of arithmetic evaluation\&. \fIbody\fP +is a mathematical expression to implement the function\&. It may +contain references to position parameters \fB$1\fP, \fB$2\fP, \&.\&.\&. +to refer to mandatory parameters and \fB${1:\-\fP\fIdefvalue\fP\fB}\fP \&.\&.\&. +to refer to optional parameters\&. Note that the forms must be +strictly adhered to for the function to calculate the correct number +of arguments\&. The implementation is held in a shell function named +\fBzsh_math_func_\fP\fImathfunc\fP; usually the user will not need +to refer to the shell function directly\&. Any existing function +of the same name is silently replaced\&. +.PP +With one argument, remove the mathematical function \fImathfunc\fP +as well as the shell function implementation\&. +.PP +With no arguments, list all \fImathfunc\fP functions in a form +suitable for restoring the definition\&. +The functions have not necessarily been defined by \fBzmathfuncdef\fP\&. +.RE +.PP +.SH "USER CONFIGURATION FUNCTIONS" +.PP +The \fBzsh/newuser\fP module comes with a function to aid in configuring +shell options for new users\&. If the module is installed, this function can +also be run by hand\&. It is available even if the module\&'s default +behaviour, namely running the function for a new user logging in without +startup files, is inhibited\&. +.PP +.PD 0 +.TP +.PD +\fBzsh\-newuser\-install\fP [ \fB\-f\fP ] +The function presents the user with various options for customizing +their initialization scripts\&. Currently only \fB~/\&.zshrc\fP is handled\&. +\fB$ZDOTDIR/\&.zshrc\fP is used instead if the parameter \fBZDOTDIR\fP is +set; this provides a way for the user to configure a file without +altering an existing \fB\&.zshrc\fP\&. +.RS +.PP +By default the function exits immediately if it finds any of the files +\fB\&.zshenv\fP, \fB\&.zprofile\fP, \fB\&.zshrc\fP, or \fB\&.zlogin\fP in the appropriate +directory\&. The option \fB\-f\fP is required in order to force the function +to continue\&. Note this may happen even if \fB\&.zshrc\fP itself does not +exist\&. +.PP +As currently configured, the function will exit immediately if the +user has root privileges; this behaviour cannot be overridden\&. +.PP +Once activated, the function\&'s behaviour is supposed to be +self\-explanatory\&. Menus are present allowing the user to alter +the value of options and parameters\&. Suggestions for improvements are +always welcome\&. +.PP +When the script exits, the user is given the opportunity to save the new +file or not; changes are not irreversible until this point\&. However, +the script is careful to restrict changes to the file only to a group +marked by the lines `\fB# Lines configured by zsh\-newuser\-install\fP\&' and +`\fB# End of lines configured by zsh\-newuser\-install\fP\&'\&. In addition, +the old version of \fB\&.zshrc\fP is saved to a file with the suffix +\fB\&.zni\fP appended\&. +.PP +If the function edits an existing \fB\&.zshrc\fP, it is up to the user +to ensure that the changes made will take effect\&. For example, if +control usually returns early from the existing \fB\&.zshrc\fP the lines +will not be executed; or a later initialization file may override +options or parameters, and so on\&. The function itself does not attempt to +detect any such conflicts\&. +.RE +.PP +.SH "OTHER FUNCTIONS" +.PP +There are a large number of helpful functions in the \fBFunctions/Misc\fP +directory of the zsh distribution\&. Most are very simple and do not +require documentation here, but a few are worthy of special mention\&. +.PP +.SS "Descriptions" +.PP +.PD 0 +.TP +.PD +\fBcolors\fP +This function initializes several associative arrays to map color names to +(and from) the ANSI standard eight\-color terminal codes\&. These are used +by the prompt theme system (see above)\&. You seldom should need to run +\fBcolors\fP more than once\&. +.RS +.PP +The eight base colors are: \fBblack\fP, \fBred\fP, \fBgreen\fP, \fByellow\fP, +\fBblue\fP, \fBmagenta\fP, \fBcyan\fP, and \fBwhite\fP\&. Each of these has codes for +foreground and background\&. In addition there are seven intensity attributes: +\fBbold\fP, \fBfaint\fP, \fBstandout\fP, \fBunderline\fP, \fBblink\fP, \fBreverse\fP, +and \fBconceal\fP\&. Finally, there are seven codes used to negate attributes: +\fBnone\fP (reset all attributes to the defaults), \fBnormal\fP +(neither bold nor faint), \fBno\-standout\fP, \fBno\-underline\fP, \fBno\-blink\fP, +\fBno\-reverse\fP, and \fBno\-conceal\fP\&. +.PP +Some terminals do not support all combinations of colors and intensities\&. +.PP +The associative arrays are: +.PP +.PD 0 +.TP +.PD 0 +\fBcolor\fP +.TP +.PD +\fBcolour\fP +Map all the color names to their integer codes, and integer codes to the +color names\&. The eight base names map to the foreground color codes, as +do names prefixed with `\fBfg\-\fP\&', such as `\fBfg\-red\fP'\&. Names prefixed +with `\fBbg\-\fP\&', such as `\fBbg\-blue\fP', refer to the background codes\&. The +reverse mapping from code to color yields base name for foreground codes +and the \fBbg\-\fP form for backgrounds\&. +.RS +.PP +Although it is a misnomer to call them `colors\&', these arrays also map the +other fourteen attributes from names to codes and codes to names\&. +.RE +.TP +.PD 0 +\fBfg\fP +.TP +.PD 0 +\fBfg_bold\fP +.TP +.PD +\fBfg_no_bold\fP +Map the eight basic color names to ANSI terminal escape sequences that set +the corresponding foreground text properties\&. The \fBfg\fP sequences change +the color without changing the eight intensity attributes\&. +.TP +.PD 0 +\fBbg\fP +.TP +.PD 0 +\fBbg_bold\fP +.TP +.PD +\fBbg_no_bold\fP +Map the eight basic color names to ANSI terminal escape sequences that set +the corresponding background properties\&. The \fBbg\fP sequences change the +color without changing the eight intensity attributes\&. +.PP +In addition, the scalar parameters \fBreset_color\fP and \fBbold_color\fP are +set to the ANSI terminal escapes that turn off all attributes and turn on +bold intensity, respectively\&. +.RE +.TP +\fBfned\fP [ \fB\-x\fP \fInum\fP ] \fIname\fP +Same as \fBzed \-f\fP\&. This function does not appear in the zsh +distribution, but can be created by linking \fBzed\fP to the name \fBfned\fP +in some directory in your \fBfpath\fP\&. +.TP +\fBhisted\fP [ [ \fIname\fP ] \fIsize\fP ] +Same as \fBzed \-h\fP\&. This function does not appear in the zsh +distribution, but can be created by linking \fBzed\fP to the name \fBhisted\fP +in some directory in your \fBfpath\fP\&. +.TP +\fBis\-at\-least\fP \fIneeded\fP [ \fIpresent\fP ] +Perform a greater\-than\-or\-equal\-to comparison of two strings having the +format of a zsh version number; that is, a string of numbers and text with +segments separated by dots or dashes\&. If the \fIpresent\fP string is not +provided, \fB$ZSH_VERSION\fP is used\&. Segments are paired left\-to\-right in +the two strings with leading non\-number parts ignored\&. If one string has +fewer segments than the other, the missing segments are considered zero\&. +.RS +.PP +This is useful in startup files to set options and other state that are +not available in all versions of zsh\&. +.PP +.RS +.nf +\fBis\-at\-least 3\&.1\&.6\-15 && setopt NO_GLOBAL_RCS +is\-at\-least 3\&.1\&.0 && setopt HIST_REDUCE_BLANKS +is\-at\-least 2\&.6\-17 || print "You can\&'t use is\-at\-least here\&."\fP +.fi +.RE +.RE +.TP +\fBnslookup\fP [ \fIarg\fP \&.\&.\&. ] +This wrapper function for the \fBnslookup\fP command requires the +\fBzsh/zpty\fP module (see +\fIzshmodules\fP(1))\&. It behaves exactly like the standard \fBnslookup\fP +except that it provides customizable prompts (including a right\-side +prompt) and completion of nslookup commands, host names, etc\&. (if you use +the function\-based completion system)\&. Completion styles may be set with +the context prefix `\fB:completion:nslookup\fP\&'\&. +.RS +.PP +See also the \fBpager\fP, \fBprompt\fP and \fBrprompt\fP styles below\&. +.RE +.TP +\fBregexp\-replace\fP \fIvar\fP \fIregexp\fP \fIreplace\fP +Use regular expressions to perform a global search and replace operation +on a variable\&. POSIX extended regular expressions (ERE) are used, +unless the option \fBRE_MATCH_PCRE\fP has been set, in which case +Perl\-compatible regular expressions are used +(this requires the shell to be linked against the \fBpcre\fP +library)\&. +.RS +.PP +\fIvar\fP is the name of the variable containing the string to be matched\&. +The variable will be modified directly by the function\&. The +variables \fBMATCH\fP, \fBMBEGIN\fP, \fBMEND\fP, \fBmatch\fP, \fBmbegin\fP, \fBmend\fP +should be avoided as these are used by the regular expression code\&. +.PP +\fIregexp\fP is the regular expression to match against the string\&. +.PP +\fIreplace\fP is the replacement text\&. This can contain parameter, command +and arithmetic expressions which will be replaced: in particular, a +reference to \fB$MATCH\fP will be replaced by the text matched by the pattern\&. +.PP +The return status is 0 if at least one match was performed, else 1\&. +.PP +Note that if using POSIX EREs, the \fB^\fP or word boundary operators +(where available) may not work properly\&. +.RE +.TP +\fBrun\-help\fP \fIcmd\fP +This function is designed to be invoked by the \fBrun\-help\fP ZLE widget, +in place of the default alias\&. See `Accessing On\-Line Help\&' +above for setup instructions\&. +.RS +.PP +In the discussion which follows, if \fIcmd\fP is a file system path, it is +first reduced to its rightmost component (the file name)\&. +.PP +Help is first sought by looking for a file named \fIcmd\fP in the directory +named by the \fBHELPDIR\fP parameter\&. If no file is found, an assistant +function, alias, or command named \fBrun\-help\-\fIcmd\fP\fP is sought\&. If +found, the assistant is executed with the rest of the current command line +(everything after the command name \fIcmd\fP) as its arguments\&. When +neither file nor assistant is found, the external command +`\fBman\fP \fIcmd\fP\&' is run\&. +.PP +An example assistant for the "ssh" command: +.PP +.RS +.nf +\fBrun\-help\-ssh() { + emulate \-LR zsh + local \-a args + # Delete the "\-l username" option + zparseopts \-D \-E \-a args l: + # Delete other options, leaving: host command + args=(${@:#\-*}) + if [[ ${#args} \-lt 2 ]]; then + man ssh + else + run\-help $args[2] + fi +}\fP +.fi +.RE +.PP +Several of these assistants are provided in the \fBFunctions/Misc\fP +directory\&. These must be autoloaded, or placed as executable scripts in +your search path, in order to be found and used by \fBrun\-help\fP\&. +.PP +.PD 0 +.TP +.PD 0 +\fBrun\-help\-btrfs\fP +.TP +.PD 0 +\fBrun\-help\-git\fP +.TP +.PD 0 +\fBrun\-help\-ip\fP +.TP +.PD 0 +\fBrun\-help\-openssl\fP +.TP +.PD 0 +\fBrun\-help\-p4\fP +.TP +.PD 0 +\fBrun\-help\-sudo\fP +.TP +.PD 0 +\fBrun\-help\-svk\fP +.TP +.PD +\fBrun\-help\-svn\fP +Assistant functions for the +\fBbtrfs\fP, +\fBgit\fP, +\fBip\fP, +\fBopenssl\fP, +\fBp4\fP, +\fBsudo\fP, +\fBsvk\fP, +and +\fBsvn\fP, +commands\&. +.RE +.TP +\fBtetris\fP +Zsh was once accused of not being as complete as Emacs, +because it lacked a Tetris game\&. This function was written to +refute this vicious slander\&. +.RS +.PP +This function must be used as a ZLE widget: +.PP +.RS +.nf +\fBautoload \-U tetris +zle \-N tetris +bindkey \fIkeys\fP tetris\fP +.fi +.RE +.PP +To start a game, execute the widget by typing the \fIkeys\fP\&. Whatever command +line you were editing disappears temporarily, and your keymap is also +temporarily replaced by the Tetris control keys\&. The previous editor state +is restored when you quit the game (by pressing `\fBq\fP\&') or when you lose\&. +.PP +If you quit in the middle of a game, the next invocation of the \fBtetris\fP +widget will continue where you left off\&. If you lost, it will start a new +game\&. +.RE +.TP +\fBtetriscurses\fP +This is a port of the above to zcurses\&. The input handling is improved +a bit so that moving a block sideways doesn\&'t automatically advance a +timestep, and the graphics use unicode block graphics\&. +.RS +.PP +This version does not save the game state between invocations, and is not +invoked as a widget, but rather as: +.PP +.RS +.nf +\fBautoload \-U tetriscurses +tetriscurses\fP +.fi +.RE +.RE +.TP +\fBzargs\fP [ \fIoption\fP \&.\&.\&. \fB\-\fP\fB\-\fP ] [ \fIinput\fP \&.\&.\&. ] [ \fB\-\fP\fB\-\fP \fIcommand\fP [ \fIarg\fP \&.\&.\&. ] ] +This function has a similar purpose to GNU xargs\&. Instead of +reading lines of arguments from the standard input, it takes them from +the command line\&. This is useful because zsh, especially with recursive +glob operators, often can construct a command line for a shell function +that is longer than can be accepted by an external command\&. +.RS +.PP +The \fIoption\fP list represents options of the \fBzargs\fP command itself, +which are the same as those of \fBxargs\fP\&. The \fIinput\fP list is the +collection of strings (often file names) that become the arguments of the +\fBcommand\fP, analogous to the standard input of \fBxargs\fP\&. Finally, the +\fIarg\fP list consists of those arguments (usually options) that are +passed to the \fIcommand\fP each time it runs\&. The \fIarg\fP list precedes +the elements from the \fBinput\fP list in each run\&. If no \fIcommand\fP is +provided, then no \fIarg\fP list may be provided, and in that event the +default command is `\fBprint\fP\&' with arguments `\fB\-r \-\fP\fB\-\fP'\&. +.PP +For example, to get a long \fBls\fP listing of all non\-hidden plain files +in the current directory or its subdirectories: +.PP +.RS +.nf +\fBautoload \-U zargs +zargs \-\- **/*(\&.) \-\- ls \-ld \-\-\fP +.fi +.RE +.PP +The first and third occurrences of `\fB\-\fP\fB\-\fP\&' are used to mark the end +of options for \fBzargs\fP and \fBls\fP respectively to guard against +filenames starting with `\fB\-\fP\&', while the second is used to separate the +list of files from the command to run (`\fBls \-ld \-\-\fP\&')\&. +.PP +The first `\fB\-\fP\fB\-\fP\&' would also be needed if there was a chance the +list might be empty as in: +.PP +.RS +.nf +\fBzargs \-r \-\- \&./*\&.back(#qN) \-\- rm \-f\fP +.fi +.RE +.PP +In the event that the string `\fB\-\fP\fB\-\fP\&' is or may be an \fIinput\fP, the +\fB\-e\fP option may be used to change the end\-of\-inputs marker\&. Note that +this does \fInot\fP change the end\-of\-options marker\&. For example, to use +`\fB\&.\&.\fP\&' as the marker: +.PP +.RS +.nf +\fBzargs \-e\&.\&. \-\- **/*(\&.) \&.\&. ls \-ld \-\-\fP +.fi +.RE +.PP +This is a good choice in that example because no plain file can be named +`\fB\&.\&.\fP\&', but the best end\-marker depends on the circumstances\&. +.PP +The options \fB\-i\fP, \fB\-I\fP, \fB\-l\fP, \fB\-L\fP, and \fB\-n\fP differ slightly +from their usage in \fBxargs\fP\&. There are no input lines for \fBzargs\fP to +count, so \fB\-l\fP and \fB\-L\fP count through the \fIinput\fP list, and \fB\-n\fP +counts the number of arguments passed to each execution of \fIcommand\fP, +\fIincluding\fP any \fIarg\fP list\&. Also, any time \fB\-i\fP or \fB\-I\fP is used, +each \fIinput\fP is processed separately as if by `\fB\-L\fP \fB1\fP\&'\&. +.PP +For details of the other \fBzargs\fP options, see the \fIxargs\fP(1) man page (but note +the difference in function between \fBzargs\fP and \fBxargs\fP) or run +\fBzargs\fP with the \fB\-\fP\fB\-help\fP option\&. +.RE +.TP +.PD 0 +\fBzed\fP [ \fB\-f\fP [ \fB\-x\fP \fInum\fP ] ] \fIname\fP +.TP +.PD 0 +\fBzed\fP [ \fB\-h\fP [ \fIname\fP ] \fIsize\fP ] +.TP +.PD +\fBzed \-b\fP +This function uses the ZLE editor to edit a file or function\&. +.RS +.PP +Only one \fIname\fP argument is allowed\&. +If the \fB\-f\fP option is given, the name is taken to be that of +a function; if the function is marked for autoloading, \fBzed\fP searches +for it in the \fBfpath\fP and loads it\&. Note that functions edited this way +are installed into the current shell, but \fInot\fP written back to the +autoload file\&. In this case the \fB\-x\fP option specifies that leading +tabs indenting the function according to syntax should be converted into +the given number of spaces; `\fB\-x 2\fP\&' is consistent with the layout +of functions distributed with the shell\&. +.PP +Without \fB\-f\fP, \fIname\fP is the path name of the file to edit, which need +not exist; it is created on write, if necessary\&. With \fB\-h\fP, the file is +presumed to contain history events\&. +.PP +When no file name is provided for \fB\-h\fP the current shell history is edited +in place\&. The history is renumbered when zed exits successfully\&. +.PP +When editing history, multi\-line events must have a trailing backslash on +every line before the last\&. +.PP +While editing, the function sets the main keymap to \fBzed\fP and the +vi command keymap to \fBzed\-vicmd\fP\&. These will be copied from the existing +\fBmain\fP and \fBvicmd\fP keymaps if they do not exist the first time \fBzed\fP +is run\&. They can be used to provide special key bindings used only in zed\&. +.PP +If it creates the keymap, \fBzed\fP rebinds the return key to insert a line +break and `\fB^X^W\fP\&' to accept the edit in the \fBzed\fP keymap, and binds +`\fBZZ\fP\&' to accept the edit in the \fBzed\-vicmd\fP keymap\&. +.PP +The bindings alone can be installed by running `\fBzed \-b\fP\&'\&. This is +suitable for putting into a startup file\&. Note that, if rerun, +this will overwrite the existing \fBzed\fP and \fBzed\-vicmd\fP keymaps\&. +.PP +Completion is available, and styles may be set with the context prefix +`\fB:completion:zed:\fP\&'\&. +.PP +A zle widget \fBzed\-set\-file\-name\fP is available\&. This can be called +by name from within zed using `\fB\eex zed\-set\-file\-name\fP\&' or can be +bound to a key in either of the \fBzed\fP or \fBzed\-vicmd\fP keymaps after +`\fBzed \-b\fP\&' has been run\&. When the widget is called, it prompts for +a new name for the file being edited\&. When zed exits the file will be +written under that name and the original file will be left alone\&. The +widget has no effect when invoked from `\fBzed \-f\fP\&'\&. The completion +context is changed to `\fB:completion:zed\-set\-file\-name:\fP\&'\&. When editing +the current history with `\fBzed \-h\fP\&', the history is first updated and +then the file is written, but the global setting of \fBHISTFILE\fP is not +altered\&. +.PP +While \fBzed\-set\-file\-name\fP is running, zed uses the keymap +\fBzed\-normal\-keymap\fP, which is linked from the main keymap in effect +at the time zed initialised its bindings\&. (This is to make the return key +operate normally\&.) The result is that if the main keymap has been changed, +the widget won\&'t notice\&. This is not a concern for most users\&. +.RE +.TP +.PD 0 +\fBzcp\fP [ \fB\-finqQvwW\fP ] \fIsrcpat\fP \fIdest\fP +.TP +.PD +\fBzln\fP [ \fB\-finqQsvwW\fP ] \fIsrcpat\fP \fIdest\fP +Same as \fBzmv \-C\fP and \fBzmv \-L\fP, respectively\&. These functions do not +appear in the zsh distribution, but can be created by linking \fBzmv\fP to +the names \fBzcp\fP and \fBzln\fP in some directory in your \fBfpath\fP\&. +.TP +\fBzkbd\fP +See `Keyboard Definition\&' +above\&. + +.TP +.PD 0 +\fBzmv\fP [ \fB\-finqQsvwW\fP ] [ \fB\-C\fP | \fB\-L\fP | \fB\-M\fP | \-{\fBp\fP|\fBP\fP} \fIprogram\fP ] [ \fB\-o\fP \fIoptstring\fP ] +.TP +.PD +\fB \fP\fIsrcpat\fP \fIdest\fP +Move (usually, rename) files matching the pattern \fIsrcpat\fP to +corresponding files having names of the form given by \fIdest\fP, where +\fIsrcpat\fP contains parentheses surrounding patterns which will be +replaced in turn by \fB$1\fP, \fB$2\fP, \&.\&.\&. in \fIdest\fP\&. For example, +.RS +.PP +.RS +.nf +\fBzmv \&'(*)\&.lis' '$1\&.txt'\fP +.fi +.RE +.PP +renames `\fBfoo\&.lis\fP\&' to `\fBfoo\&.txt\fP', `\fBmy\&.old\&.stuff\&.lis\fP' to +`\fBmy\&.old\&.stuff\&.txt\fP\&', and so on\&. +.PP +The pattern is always treated as an \fBEXTENDED_GLOB\fP pattern\&. Any file +whose name is not changed by the substitution is simply ignored\&. Any +error (a substitution resulted in an empty string, two substitutions gave +the same result, the destination was an existing regular file and \fB\-f\fP +was not given) causes the entire function to abort without doing +anything\&. +.PP +In addition to pattern replacement, the variable \fB$f\fP can be referred +to in the second (replacement) argument\&. This makes it possible to +use variable substitution to alter the argument; see examples below\&. +.PP +Options: +.PP +.PD 0 +.TP +\fB\-f\fP +Force overwriting of destination files\&. Not currently +passed down to the \fBmv\fP/\fBcp\fP/\fBln\fP command due to vagaries of +implementations (but you can use \fB\-o\-f\fP to do that)\&. +.TP +\fB\-i\fP +Interactive: show each line to be executed and ask the user +whether to execute it\&. `\fBY\fP\&' or `\fBy\fP' will execute it, anything else will +skip it\&. Note that you just need to type one character\&. +.TP +\fB\-n\fP +No execution: print what would happen, but don\&'t do it\&. +.TP +\fB\-q\fP +Turn bare glob qualifiers off: now assumed by default, so +this has no effect\&. +.TP +\fB\-Q\fP +Force bare glob qualifiers on\&. Don\&'t turn this on unless +you are actually using glob qualifiers in a pattern\&. +.TP +\fB\-s\fP +Symbolic, passed down to \fBln\fP; only works with \fB\-L\fP\&. +.TP +\fB\-v\fP +Verbose: print each command as it\&'s being executed\&. +.TP +\fB\-w\fP +Pick out wildcard parts of the pattern, as described above, +and implicitly add parentheses for referring to them\&. +.TP +\fB\-W\fP +Just like \fB\-w\fP, with the addition of turning wildcards in +the replacement pattern into sequential \fB${1}\fP \&.\&. \fB${N}\fP references\&. +.TP +\fB\-C\fP +.TP +\fB\-L\fP +.TP +\fB\-M\fP +Force \fBcp\fP, \fBln\fP or \fBmv\fP, respectively, regardless of +the name of the function\&. +.TP +\fB\-p\fP \fIprogram\fP +Call \fIprogram\fP instead of \fBcp\fP, \fBln\fP or +\fBmv\fP\&. Whatever it does, it should at least understand the form +`\fIprogram\fP \fB\-\fP\fB\-\fP \fIoldname\fP \fInewname\fP\&' +where \fIoldname\fP and \fInewname\fP are filenames generated by \fBzmv\fP\&. +\fIprogram\fP will be split into words, so might be e\&.g\&. the name +of an archive tool plus a copy or rename subcommand\&. +.TP +\fB\-P\fP \fIprogram\fP +As \fB\-p\fP \fIprogram\fP, except that +\fIprogram\fP does not accept a following \fB\-\fP\fB\-\fP to indicate the +end of options\&. In this case filenames must already be in a sane +form for the program in question\&. +.TP +\fB\-o\fP \fIoptstring\fP +The \fIoptstring\fP is split into words and +passed down verbatim to the \fBcp\fP, \fBln\fP or \fBmv\fP command called to +perform the work\&. It should probably begin with a `\fB\-\fP\&'\&. +.PD +.PP +Further examples: +.PP +.RS +.nf +\fBzmv \-v \&'(* *)' '${1// /_}'\fP +.fi +.RE +.PP +For any file in the current directory with at least one space in the name, +replace every space by an underscore and display the commands executed\&. +.PP +.RS +.nf +\fBzmv \-v \&'* *' '${f// /_}'\fP +.fi +.RE +.PP +This does exactly the same by referring to the file name stored in \fB$f\fP\&. +.PP +For more complete examples and other implementation details, see the +\fBzmv\fP source file, usually located in one of the directories named in +your \fBfpath\fP, or in \fBFunctions/Misc/zmv\fP in the zsh distribution\&. +.RE +.TP +\fBzrecompile\fP +See `Recompiling Functions\&' +above\&. +.TP +\fBzstyle+\fP \fIcontext\fP \fIstyle\fP \fIvalue\fP [ \fB+\fP \fIsubcontext\fP \fIstyle\fP \fIvalue\fP \&.\&.\&. ] +This makes defining styles a bit simpler by using a single `\fB+\fP\&' as a +special token that allows you to append a context name to the previously +used context name\&. Like this: +.RS +.PP +.RS +.nf +\fBzstyle+ \&':foo:bar' \fIstyle1\fP \fIvalue1\fP \e + +\&':baz' \fIstyle2\fP \fIvalue2\fP \e + +\&':frob' \fIstyle3\fP \fIvalue3\fP\fP +.fi +.RE +.PP +This defines \fIstyle1\fP with \fIvalue1\fP for the context \fB:foo:bar\fP as usual, +but it also defines \fIstyle2\fP with \fIvalue2\fP for the context +\fB:foo:bar:baz\fP and \fIstyle3\fP with \fIvalue3\fP for \fB:foo:bar:frob\fP\&. Any +\fIsubcontext\fP may be the empty string to re\-use the first context +unchanged\&. +.RE +.PP +.SS "Styles" +.PP +.PD 0 +.TP +.PD +\fBinsert\-tab\fP +The \fBzed\fP function \fIsets\fP this style in context `\fB:completion:zed:*\fP\&' +to turn off completion when \fBTAB\fP is typed at the beginning of a line\&. +You may override this by setting your own value for this context and style\&. +.TP +\fBpager\fP +The \fBnslookup\fP function looks up this style in the context +`\fB:nslookup\fP\&' to determine the program used to display output that does +not fit on a single screen\&. +.TP +.PD 0 +\fBprompt\fP +.TP +.PD +\fBrprompt\fP +The \fBnslookup\fP function looks up this style in the context +`\fB:nslookup\fP\&' to set the prompt and the right\-side prompt, respectively\&. +The usual expansions for the \fBPS1\fP and \fBRPS1\fP parameters may be used +(see +EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1))\&. |