{ "content": [ { "type": "text", "text": "# zshcontrib (info)\n\n## NAME\n\nzshcontrib - user contributions to zsh\n\n## DESCRIPTION\n\nThe Zsh source distribution includes a number of items contributed by\nthe user community. These are not inherently a part of the shell, and\nsome may not be available in every zsh installation. The most signifi-\ncant of these are documented here. For documentation on other contrib-\nuted items such as shell functions, look for comments in the function\nsource files.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **UTILITIES**\n- **REMEMBERING RECENT DIRECTORIES**\n- **ABBREVIATED DYNAMIC REFERENCES TO DIRECTORIES**\n- **GATHERING INFORMATION FROM VERSION CONTROL SYSTEMS**\n- **PROMPT THEMES**\n- **ZLE FUNCTIONS**\n- **EXCEPTION HANDLING**\n- **MIME FUNCTIONS**\n- **MATHEMATICAL FUNCTIONS**\n- **USER CONFIGURATION FUNCTIONS**\n- **OTHER FUNCTIONS**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "zshcontrib", "section": "", "mode": "info", "summary": "zshcontrib - user contributions to zsh", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 7, "subsections": [] }, { "name": "UTILITIES", "lines": 321, "subsections": [] }, { "name": "REMEMBERING RECENT DIRECTORIES", "lines": 250, "subsections": [] }, { "name": "ABBREVIATED DYNAMIC REFERENCES TO DIRECTORIES", "lines": 163, "subsections": [] }, { "name": "GATHERING INFORMATION FROM VERSION CONTROL SYSTEMS", "lines": 1010, "subsections": [] }, { "name": "PROMPT THEMES", "lines": 119, "subsections": [] }, { "name": "ZLE FUNCTIONS", "lines": 1323, "subsections": [] }, { "name": "EXCEPTION HANDLING", "lines": 78, "subsections": [] }, { "name": "MIME FUNCTIONS", "lines": 359, "subsections": [] }, { "name": "MATHEMATICAL FUNCTIONS", "lines": 248, "subsections": [] }, { "name": "USER CONFIGURATION FUNCTIONS", "lines": 43, "subsections": [] }, { "name": "OTHER FUNCTIONS", "lines": 428, "subsections": [] } ], "sections": { "NAME": { "content": "zshcontrib - user contributions to zsh\n", "subsections": [] }, "DESCRIPTION": { "content": "The Zsh source distribution includes a number of items contributed by\nthe user community. These are not inherently a part of the shell, and\nsome may not be available in every zsh installation. The most signifi-\ncant of these are documented here. For documentation on other contrib-\nuted items such as shell functions, look for comments in the function\nsource files.\n", "subsections": [] }, "UTILITIES": { "content": "Accessing On-Line Help\nThe key sequence ESC h is normally bound by ZLE to execute the run-help\nwidget (see zshzle(1)). This invokes the run-help command with the\ncommand word from the current input line as its argument. By default,\nrun-help is an alias for the man command, so this often fails when the\ncommand word is a shell builtin or a user-defined function. By re-\ndefining the run-help alias, one can improve the on-line help provided\nby the shell.\n\nThe helpfiles utility, found in the Util directory of the distribution,\nis a Perl program that can be used to process the zsh manual to produce\na separate help file for each shell builtin and for many other shell\nfeatures as well. The autoloadable run-help function, found in Func-\ntions/Misc, searches for these helpfiles and performs several other\ntests to produce the most complete help possible for the command.\n\nHelp files are installed by default to a subdirectory of /usr/share/zsh\nor /usr/local/share/zsh.\n\nTo create your own help files with helpfiles, choose or create a direc-\ntory where the individual command help files will reside. For example,\nyou might choose ~/zshhelp. If you unpacked the zsh distribution in\nyour home directory, you would use the commands:\n\nmkdir ~/zshhelp\nperl ~/zsh-5.8.1/Util/helpfiles ~/zshhelp\n\nThe HELPDIR parameter tells run-help where to look for the help files.\nWhen unset, it uses the default installation path. To use your own set\nof help files, set this to the appropriate path in one of your startup\nfiles:\n\nHELPDIR=~/zshhelp\n\nTo use the run-help function, you need to add lines something like the\nfollowing to your .zshrc or equivalent startup file:\n\nunalias run-help\nautoload run-help\n\nNote that in order for `autoload run-help' to work, the run-help file\nmust be in one of the directories named in your fpath array (see zsh-\nparam(1)). This should already be the case if you have a standard zsh\ninstallation; if it is not, copy Functions/Misc/run-help to an appro-\npriate directory.\n\nRecompiling Functions\nIf you frequently edit your zsh functions, or periodically update your\nzsh installation to track the latest developments, you may find that\nfunction digests compiled with the zcompile builtin are frequently out\nof date with respect to the function source files. This is not usually\na problem, because zsh always looks for the newest file when loading a\nfunction, but it may cause slower shell startup and function loading.\nAlso, if a digest file is explicitly used as an element of fpath, zsh\nwon't check whether any of its source files has changed.\n\nThe zrecompile autoloadable function, found in Functions/Misc, can be\nused to keep function digests up to date.\n\nzrecompile [ -qt ] [ name ... ]\nzrecompile [ -qt ] -p arg ... [ -- arg ... ]\nThis tries to find *.zwc files and automatically re-compile them\nif at least one of the original files is newer than the compiled\nfile. This works only if the names stored in the compiled files\nare full paths or are relative to the directory that contains\nthe .zwc file.\n\nIn the first form, each name is the name of a compiled file or a\ndirectory containing *.zwc files that should be checked. If no\narguments are given, the directories and *.zwc files in fpath\nare used.\n\nWhen -t is given, no compilation is performed, but a return sta-\ntus of zero (true) is set if there are files that need to be\nre-compiled and non-zero (false) otherwise. The -q option qui-\nets the chatty output that describes what zrecompile is doing.\n\nWithout the -t option, the return status is zero if all files\nthat needed re-compilation could be compiled and non-zero if\ncompilation for at least one of the files failed.\n\nIf the -p option is given, the args are interpreted as one or\nmore sets of arguments for zcompile, separated by `--'. For ex-\nample:\n\nzrecompile -p \\\n-R ~/.zshrc -- \\\n-M ~/.zcompdump -- \\\n~/zsh/comp.zwc ~/zsh/Completion/*/*\n\nThis compiles ~/.zshrc into ~/.zshrc.zwc if that doesn't exist\nor if it is older than ~/.zshrc. The compiled file will be\nmarked for reading instead of mapping. The same is done for\n~/.zcompdump and ~/.zcompdump.zwc, but this compiled file is\nmarked for mapping. The last line re-creates the file\n~/zsh/comp.zwc if any of the files matching the given pattern is\nnewer than it.\n\nWithout the -p option, zrecompile does not create function di-\ngests that do not already exist, nor does it add new functions\nto the digest.\n\nThe following shell loop is an example of a method for creating func-\ntion digests for all functions in your fpath, assuming that you have\nwrite permission to the directories:\n\nfor ((i=1; i <= $#fpath; ++i)); do\ndir=$fpath[i]\nzwc=${dir:t}.zwc\nif [[ $dir == (.|..) || $dir == (.|..)/* ]]; then\ncontinue\nfi\nfiles=($dir/*(N-.))\nif [[ -w $dir:h && -n $files ]]; then\nfiles=(${${(M)files%/*/*}#/})\nif ( cd $dir:h &&\nzrecompile -p -U -z $zwc $files ); then\nfpath[i]=$fpath[i].zwc\nfi\nfi\ndone\n\nThe -U and -z options are appropriate for functions in the default zsh\ninstallation fpath; you may need to use different options for your per-\nsonal function directories.\n\nOnce the digests have been created and your fpath modified to refer to\nthem, you can keep them up to date by running zrecompile with no argu-\nments.\n\nKeyboard Definition\nThe large number of possible combinations of keyboards, workstations,\nterminals, emulators, and window systems makes it impossible for zsh to\nhave built-in key bindings for every situation. The zkbd utility,\nfound in Functions/Misc, can help you quickly create key bindings for\nyour configuration.\n\nRun zkbd either as an autoloaded function, or as a shell script:\n\nzsh -f ~/zsh-5.8.1/Functions/Misc/zkbd\n\nWhen you run zkbd, it first asks you to enter your terminal type; if\nthe default it offers is correct, just press return. It then asks you\nto press a number of different keys to determine characteristics of\nyour keyboard and terminal; zkbd warns you if it finds anything out of\nthe ordinary, such as a Delete key that sends neither ^H nor ^?.\n\nThe keystrokes read by zkbd are recorded as a definition for an asso-\nciative array named key, written to a file in the subdirectory .zkbd\nwithin either your HOME or ZDOTDIR directory. The name of the file is\ncomposed from the TERM, VENDOR and OSTYPE parameters, joined by hy-\nphens.\n\nYou may read this file into your .zshrc or another startup file with\nthe `source' or `.' commands, then reference the key parameter in bind-\nkey commands, like this:\n\nsource ${ZDOTDIR:-$HOME}/.zkbd/$TERM-$VENDOR-$OSTYPE\n[[ -n ${key[Left]} ]] && bindkey \"${key[Left]}\" backward-char\n[[ -n ${key[Right]} ]] && bindkey \"${key[Right]}\" forward-char\n# etc.\n\nNote that in order for `autoload zkbd' to work, the zkdb file must be\nin one of the directories named in your fpath array (see zshparam(1)).\nThis should already be the case if you have a standard zsh installa-\ntion; if it is not, copy Functions/Misc/zkbd to an appropriate direc-\ntory.\n\nDumping Shell State\nOccasionally you may encounter what appears to be a bug in the shell,\nparticularly if you are using a beta version of zsh or a development\nrelease. Usually it is sufficient to send a description of the problem\nto one of the zsh mailing lists (see zsh(1)), but sometimes one of the\nzsh developers will need to recreate your environment in order to track\nthe problem down.\n\nThe script named reporter, found in the Util directory of the distribu-\ntion, is provided for this purpose. (It is also possible to autoload\nreporter, but reporter is not installed in fpath by default.) This\nscript outputs a detailed dump of the shell state, in the form of an-\nother script that can be read with `zsh -f' to recreate that state.\n\nTo use reporter, read the script into your shell with the `.' command\nand redirect the output into a file:\n\n. ~/zsh-5.8.1/Util/reporter > zsh.report\n\nYou should check the zsh.report file for any sensitive information such\nas passwords and delete them by hand before sending the script to the\ndevelopers. Also, as the output can be voluminous, it's best to wait\nfor the developers to ask for this information before sending it.\n\nYou can also use reporter to dump only a subset of the shell state.\nThis is sometimes useful for creating startup files for the first time.\nMost of the output from reporter is far more detailed than usually is\nnecessary for a startup file, but the aliases, options, and zstyles\nstates may be useful because they include only changes from the de-\nfaults. The bindings state may be useful if you have created any of\nyour own keymaps, because reporter arranges to dump the keymap creation\ncommands as well as the bindings for every keymap.\n\nAs is usual with automated tools, if you create a startup file with re-\nporter, you should edit the results to remove unnecessary commands.\nNote that if you're using the new completion system, you should not\ndump the functions state to your startup files with reporter; use the\ncompdump function instead (see zshcompsys(1)).\n\nreporter [ state ... ]\nPrint to standard output the indicated subset of the current\nshell state. The state arguments may be one or more of:\n\nall Output everything listed below.\naliases\nOutput alias definitions.\nbindings\nOutput ZLE key maps and bindings.\ncompletion\nOutput old-style compctl commands. New completion is\ncovered by functions and zstyles.\nfunctions\nOutput autoloads and function definitions.\nlimits Output limit commands.\noptions\nOutput setopt commands.\nstyles Same as zstyles.\nvariables\nOutput shell parameter assignments, plus export commands\nfor any environment variables.\nzstyles\nOutput zstyle commands.\n\nIf the state is omitted, all is assumed.\n\nWith the exception of `all', every state can be abbreviated by any pre-\nfix, even a single letter; thus a is the same as aliases, z is the same\nas zstyles, etc.\n\nManipulating Hook Functions\nadd-zsh-hook [ -L | -dD ] [ -Uzk ] hook function\nSeveral functions are special to the shell, as described in the\nsection SPECIAL FUNCTIONS, see zshmisc(1), in that they are au-\ntomatically called at specific points during shell execution.\nEach has an associated array consisting of names of functions to\nbe called at the same point; these are so-called `hook func-\ntions'. The shell function add-zsh-hook provides a simple way\nof adding or removing functions from the array.\n\nhook is one of chpwd, periodic, precmd, preexec, zshaddhistory,\nzshexit, or zshdirectoryname, the special functions in ques-\ntion. Note that zshdirectoryname is called in a different way\nfrom the other functions, but may still be manipulated as a\nhook.\n\nfunction is name of an ordinary shell function. If no options\nare given this will be added to the array of functions to be ex-\necuted in the given context. Functions are invoked in the order\nthey were added.\n\nIf the option -L is given, the current values for the hook ar-\nrays are listed with typeset.\n\nIf the option -d is given, the function is removed from the ar-\nray of functions to be executed.\n\nIf the option -D is given, the function is treated as a pattern\nand any matching names of functions are removed from the array\nof functions to be executed.\n\nThe options -U, -z and -k are passed as arguments to autoload\nfor function. For functions contributed with zsh, the options\n-Uz are appropriate.\n\nadd-zle-hook-widget [ -L | -dD ] [ -Uzk ] hook widgetname\nSeveral widget names are special to the line editor, as de-\nscribed in the section Special Widgets, see zshzle(1), in that\nthey are automatically called at specific points during editing.\nUnlike function hooks, these do not use a predefined array of\nother names to call at the same point; the shell function\nadd-zle-hook-widget maintains a similar array and arranges for\nthe special widget to invoke those additional widgets.\n\nhook is one of isearch-exit, isearch-update, line-pre-redraw,\nline-init, line-finish, history-line-set, or keymap-select, cor-\nresponding to each of the special widgets zle-isearch-exit, etc.\nThe special widget names are also accepted as the hook argument.\n\nwidgetname is the name of a ZLE widget. If no options are given\nthis is added to the array of widgets to be invoked in the given\nhook context. Widgets are invoked in the order they were added,\nwith\nzle widgetname -Nw -- \"$@\"\n\nNote that this means that the `WIDGET' special parameter tracks\nthe widgetname when the widget function is called, rather than\ntracking the name of the corresponding special hook widget.\n\nIf the option -d is given, the widgetname is removed from the\narray of widgets to be executed.\n\nIf the option -D is given, the widgetname is treated as a pat-\ntern and any matching names of widgets are removed from the ar-\nray.\n\nIf widgetname does not name an existing widget when added to the\narray, it is assumed that a shell function also named widgetname\nis meant to provide the implementation of the widget. This name\nis therefore marked for autoloading, and the options -U, -z and\n-k are passed as arguments to autoload as with add-zsh-hook.\nThe widget is also created with `zle -N widgetname' to cause the\ncorresponding function to be loaded the first time the hook is\ncalled.\n\nThe arrays of widgetname are currently maintained in zstyle con-\ntexts, one for each hook context, with a style of `widgets'. If\nthe -L option is given, this set of styles is listed with\n`zstyle -L'. This implementation may change, and the special\nwidgets that refer to the styles are created only if\nadd-zle-hook-widget is called to add at least one widget, so if\nthis function is used for any hooks, then all hooks should be\nmanaged only via this function.\n", "subsections": [] }, "REMEMBERING RECENT DIRECTORIES": { "content": "The function cdr allows you to change the working directory to a previ-\nous working directory from a list maintained automatically. It is sim-\nilar in concept to the directory stack controlled by the pushd, popd\nand dirs builtins, but is more configurable, and as it stores all en-\ntries in files it is maintained across sessions and (by default) be-\ntween terminal emulators in the current session. Duplicates are auto-\nmatically removed, so that the list reflects the single most recent use\nof each directory.\n\nNote that the pushd directory stack is not actually modified or used by\ncdr unless you configure it to do so as described in the configuration\nsection below.\n\nInstallation\nThe system works by means of a hook function that is called every time\nthe directory changes. To install the system, autoload the required\nfunctions and use the add-zsh-hook function described above:\n\nautoload -Uz chpwdrecentdirs cdr add-zsh-hook\nadd-zsh-hook chpwd chpwdrecentdirs\n\nNow every time you change directly interactively, no matter which com-\nmand you use, the directory to which you change will be remembered in\nmost-recent-first order.\n\nUse\nAll direct user interaction is via the cdr function.\n\nThe argument to cdr is a number N corresponding to the Nth most re-\ncently changed-to directory. 1 is the immediately preceding directory;\nthe current directory is remembered but is not offered as a destina-\ntion. Note that if you have multiple windows open 1 may refer to a di-\nrectory changed to in another window; you can avoid this by having\nper-terminal files for storing directory as described for the re-\ncent-dirs-file style below.\n\nIf you set the recent-dirs-default style described below cdr will be-\nhave the same as cd if given a non-numeric argument, or more than one\nargument. The recent directory list is updated just the same however\nyou change directory.\n\nIf the argument is omitted, 1 is assumed. This is similar to pushd's\nbehaviour of swapping the two most recent directories on the stack.\n\nCompletion for the argument to cdr is available if compinit has been\nrun; menu selection is recommended, using:\n\nzstyle ':completion:*:*:cdr:*:*' menu selection\n\nto allow you to cycle through recent directories; the order is pre-\nserved, so the first choice is the most recent directory before the\ncurrent one. The verbose style is also recommended to ensure the di-\nrectory is shown; this style is on by default so no action is required\nunless you have changed it.\n\nOptions\nThe behaviour of cdr may be modified by the following options.\n\n-l lists the numbers and the corresponding directories in abbrevi-\nated form (i.e. with ~ substitution reapplied), one per line.\nThe directories here are not quoted (this would only be an issue\nif a directory name contained a newline). This is used by the\ncompletion system.\n\n-r sets the variable reply to the current set of directories.\nNothing is printed and the directory is not changed.\n\n-e allows you to edit the list of directories, one per line. The\nlist can be edited to any extent you like; no sanity checking is\nperformed. Completion is available. No quoting is necessary\n(except for newlines, where I have in any case no sympathy); di-\nrectories are in unabbreviated from and contain an absolute\npath, i.e. they start with /. Usually the first entry should be\nleft as the current directory.\n\n-p 'pattern'\nPrunes any items in the directory list that match the given ex-\ntended glob pattern; the pattern needs to be quoted from immedi-\nate expansion on the command line. The pattern is matched\nagainst each completely expanded file name in the list; the full\nstring must match, so wildcards at the end (e.g. '*removeme*')\nare needed to remove entries with a given substring.\n\nIf output is to a terminal, then the function will print the new\nlist after pruning and prompt for confirmation by the user.\nThis output and confirmation step can be skipped by using -P in-\nstead of -p.\n\nConfiguration\nConfiguration is by means of the styles mechanism that should be famil-\niar from completion; if not, see the description of the zstyle command\nin see zshmodules(1). The context for setting styles should be ':ch-\npwd:*' in case the meaning of the context is extended in future, for\nexample:\n\nzstyle ':chpwd:*' recent-dirs-max 0\n\nsets the value of the recent-dirs-max style to 0. In practice the\nstyle name is specific enough that a context of '*' should be fine.\n\nAn exception is recent-dirs-insert, which is used exclusively by the\ncompletion system and so has the usual completion system context\n(':completion:*' if nothing more specific is needed), though again '*'\nshould be fine in practice.\n\nrecent-dirs-default\nIf true, and the command is expecting a recent directory index,\nand either there is more than one argument or the argument is\nnot an integer, then fall through to \"cd\". This allows the lazy\nto use only one command for directory changing. Completion\nrecognises this, too; see recent-dirs-insert for how to control\ncompletion when this option is in use.\n\nrecent-dirs-file\nThe file where the list of directories is saved. The default is\n${ZDOTDIR:-$HOME}/.chpwd-recent-dirs, i.e. this is in your home\ndirectory unless you have set the variable ZDOTDIR to point\nsomewhere else. Directory names are saved in $'...' quoted\nform, so each line in the file can be supplied directly to the\nshell as an argument.\n\nThe value of this style may be an array. In this case, the\nfirst file in the list will always be used for saving directo-\nries while any other files are left untouched. When reading the\nrecent directory list, if there are fewer than the maximum num-\nber of entries in the first file, the contents of later files in\nthe array will be appended with duplicates removed from the list\nshown. The contents of the two files are not sorted together,\ni.e. all the entries in the first file are shown first. The\nspecial value + can appear in the list to indicate the default\nfile should be read at that point. This allows effects like the\nfollowing:\n\nzstyle ':chpwd:*' recent-dirs-file \\\n~/.chpwd-recent-dirs-${TTY##*/} +\n\nRecent directories are read from a file numbered according to\nthe terminal. If there are insufficient entries the list is\nsupplemented from the default file.\n\nIt is possible to use zstyle -e to make the directory config-\nurable at run time:\n\nzstyle -e ':chpwd:*' recent-dirs-file pick-recent-dirs-file\npick-recent-dirs-file() {\nif [[ $PWD = ~/text/writing(|/*) ]]; then\nreply=(~/.chpwd-recent-dirs-writing)\nelse\nreply=(+)\nfi\n}\n\nIn this example, if the current directory is ~/text/writing or a\ndirectory under it, then use a special file for saving recent\ndirectories, else use the default.\n\nrecent-dirs-insert\nUsed by completion. If recent-dirs-default is true, then set-\nting this to true causes the actual directory, rather than its\nindex, to be inserted on the command line; this has the same ef-\nfect as using the corresponding index, but makes the history\nclearer and the line easier to edit. With this setting, if part\nof an argument was already typed, normal directory completion\nrather than recent directory completion is done; this is because\nrecent directory completion is expected to be done by cycling\nthrough entries menu fashion.\n\nIf the value of the style is always, then only recent directo-\nries will be completed; in that case, use the cd command when\nyou want to complete other directories.\n\nIf the value is fallback, recent directories will be tried\nfirst, then normal directory completion is performed if recent\ndirectory completion failed to find a match.\n\nFinally, if the value is both then both sets of completions are\npresented; the usual tag mechanism can be used to distinguish\nresults, with recent directories tagged as recent-dirs. Note\nthat the recent directories inserted are abbreviated with direc-\ntory names where appropriate.\n\nrecent-dirs-max\nThe maximum number of directories to save to the file. If this\nis zero or negative there is no maximum. The default is 20.\nNote this includes the current directory, which isn't offered,\nso the highest number of directories you will be offered is one\nless than the maximum.\n\nrecent-dirs-prune\nThis style is an array determining what directories should (or\nshould not) be added to the recent list. Elements of the array\ncan include:\n\nparent Prune parents (more accurately, ancestors) from the re-\ncent list. If present, changing directly down by any\nnumber of directories causes the current directory to be\noverwritten. For example, changing from ~pws to\n~pws/some/other/dir causes ~pws not to be left on the re-\ncent directory stack. This only applies to direct\nchanges to descendant directories; earlier directories on\nthe list are not pruned. For example, changing from\n~pws/yet/another to ~pws/some/other/dir does not cause\n~pws to be pruned.\n\npattern:pattern\nGives a zsh pattern for directories that should not be\nadded to the recent list (if not already there). This\nelement can be repeated to add different patterns. For\nexample, 'pattern:/tmp(|/*)' stops /tmp or its descen-\ndants from being added. The EXTENDEDGLOB option is al-\nways turned on for these patterns.\n\nrecent-dirs-pushd\nIf set to true, cdr will use pushd instead of cd to change the\ndirectory, so the directory is saved on the directory stack. As\nthe directory stack is completely separate from the list of\nfiles saved by the mechanism used in this file there is no obvi-\nous reason to do this.\n\nUse with dynamic directory naming\nIt is possible to refer to recent directories using the dynamic direc-\ntory name syntax by using the supplied function zshdirectorynamecdr\na hook:\n\nautoload -Uz add-zsh-hook\nadd-zsh-hook -Uz zshdirectoryname zshdirectorynamecdr\n\nWhen this is done, ~[1] will refer to the most recent directory other\nthan $PWD, and so on. Completion after ~[... also works.\n\nDetails of directory handling\nThis section is for the curious or confused; most users will not need\nto know this information.\n\nRecent directories are saved to a file immediately and hence are pre-\nserved across sessions. Note currently no file locking is applied: the\nlist is updated immediately on interactive commands and nowhere else\n(unlike history), and it is assumed you are only going to change direc-\ntory in one window at once. This is not safe on shared accounts, but\nin any case the system has limited utility when someone else is chang-\ning to a different set of directories behind your back.\n\nTo make this a little safer, only directory changes instituted from the\ncommand line, either directly or indirectly through shell function\ncalls (but not through subshells, evals, traps, completion functions\nand the like) are saved. Shell functions should use cd -q or pushd -q\nto avoid side effects if the change to the directory is to be invisible\nat the command line. See the contents of the function chpwdre-\ncentdirs for more details.\n", "subsections": [] }, "ABBREVIATED DYNAMIC REFERENCES TO DIRECTORIES": { "content": "The dynamic directory naming system is described in the subsection Dy-\nnamic named directories of the section Filename Expansion in expn(1).\nIn this, a reference to ~[...] is expanded by a function found by the\nhooks mechanism.\n\nThe contributed function zshdirectorynamegeneric provides a system\nallowing the user to refer to directories with only a limited amount of\nnew code. It supports all three of the standard interfaces for direc-\ntory naming: converting from a name to a directory, converting in the\nreverse direction to find a short name, and completion of names.\n\nThe main feature of this function is a path-like syntax, combining ab-\nbreviations at multiple levels separated by \":\". As an example,\n~[g:p:s] might specify:\ng The top level directory for your git area. This first component\nhas to match, or the function will return indicating another di-\nrectory name hook function should be tried.\n\np The name of a project within your git area.\n\ns The source area within that project. This allows you to col-\nlapse references to long hierarchies to a very compact form,\nparticularly if the hierarchies are similar across different ar-\neas of the disk.\n\nName components may be completed: if a description is shown at the top\nof the list of completions, it includes the path to which previous com-\nponents expand, while the description for an individual completion\nshows the path segment it would add. No additional configuration is\nneeded for this as the completion system is aware of the dynamic direc-\ntory name mechanism.\n\nUsage\nTo use the function, first define a wrapper function for your specific\ncase. We'll assume it's to be autoloaded. This can have any name but\nwe'll refer to it as zdnmywrapper. This wrapper function will define\nvarious variables and then call this function with the same arguments\nthat the wrapper function gets. This configuration is described below.\n\nThen arrange for the wrapper to be run as a zshdirectoryname hook:\n\nautoload -Uz add-zsh-hook zshdiretorynamegeneric zdnmywrapper\nadd-zsh-hook -U zshdirectoryname zdnmywrapper\n\nConfiguration\nThe wrapper function should define a local associative array zdntop.\nAlternatively, this can be set with a style called mapping. The con-\ntext for the style is :zdn:wrapper-name where wrapper-name is the func-\ntion calling zshdirectorynamegeneric; for example:\n\nzstyle :zdn:zdnmywrapper: mapping zdnmywrappertop\n\nThe keys in this associative array correspond to the first component of\nthe name. The values are matching directories. They may have an op-\ntional suffix with a slash followed by a colon and the name of a vari-\nable in the same format to give the next component. (The slash before\nthe colon is to disambiguate the case where a colon is needed in the\npath for a drive. There is otherwise no syntax for escaping this, so\npath components whose names start with a colon are not supported.) A\nspecial component :default: specifies a variable in the form /:var (the\npath section is ignored and so is usually empty) that will be used for\nthe next component if no variable is given for the path. Variables re-\nferred to within zdntop have the same format as zdntop itself, but\ncontain relative paths.\n\nFor example,\n\nlocal -A zdntop=(\ng ~/git\nga ~/alternate/git\ngs /scratch/$USER/git/:second2\n:default: /:second1\n)\n\nThis specifies the behaviour of a directory referred to as ~[g:...] or\n~[ga:...] or ~[gs:...]. Later path components are optional; in that\ncase ~[g] expands to ~/git, and so on. gs expands to\n/scratch/$USER/git and uses the associative array second2 to match the\nsecond component; g and ga use the associative array second1 to match\nthe second component.\n\nWhen expanding a name to a directory, if the first component is not g\nor ga or gs, it is not an error; the function simply returns 1 so that\na later hook function can be tried. However, matching the first compo-\nnent commits the function, so if a later component does not match, an\nerror is printed (though this still does not stop later hooks from be-\ning executed).\n\nFor components after the first, a relative path is expected, but note\nthat multiple levels may still appear. Here is an example of second1:\n\nlocal -A second1=(\np myproject\ns somproject\nos otherproject/subproject/:third\n)\n\nThe path as found from zdntop is extended with the matching directory,\nso ~[g:p] becomes ~/git/myproject. The slash between is added automat-\nically (it's not possible to have a later component modify the name of\na directory already matched). Only os specifies a variable for a third\ncomponent, and there's no :default:, so it's an error to use a name\nlike ~[g:p:x] or ~[ga:s:y] because there's nowhere to look up the x or\ny.\n\nThe associative arrays need to be visible within this function; the\ngeneric function therefore uses internal variable names beginning zdn\nin order to avoid clashes. Note that the variable reply needs to be\npassed back to the shell, so should not be local in the calling func-\ntion.\n\nThe function does not test whether directories assembled by component\nactually exist; this allows the system to work across automounted file\nsystems. The error from the command trying to use a non-existent di-\nrectory should be sufficient to indicate the problem.\n\nComplete example\nHere is a full fictitious but usable autoloadable definition of the ex-\nample function defined by the code above. So ~[gs:p:s] expands to\n/scratch/$USER/git/myscratchproject/top/srcdir (with $USER also ex-\npanded).\n\nlocal -A zdntop=(\ng ~/git\nga ~/alternate/git\ngs /scratch/$USER/git/:second2\n:default: /:second1\n)\n\nlocal -A second1=(\np myproject\ns somproject\nos otherproject/subproject/:third\n)\n\nlocal -A second2=(\np myscratchproject\ns somescratchproject\n)\n\nlocal -A third=(\ns top/srcdir\nd top/documentation\n)\n\n# autoload not needed if you did this at initialisation...\nautoload -Uz zshdirectorynamegeneric\nzshdirectorynamegeneric \"$@\n\nIt is also possible to use global associative arrays, suitably named,\nand set the style for the context of your wrapper function to refer to\nthis. Then your set up code would contain the following:\n\ntypeset -A zdnmywrappertop=(...)\n# ... and so on for other associative arrays ...\nzstyle ':zdn:zdnmywrapper:' mapping zdnmywrappertop\nautoload -Uz add-zsh-hook zshdirectorynamegeneric zdnmywrapper\nadd-zsh-hook -U zshdirectoryname zdnmywrapper\n\nand the function zdnmywrapper would contain only the following:\n\nzshdirectorynamegeneric \"$@\"\n", "subsections": [] }, "GATHERING INFORMATION FROM VERSION CONTROL SYSTEMS": { "content": "In a lot of cases, it is nice to automatically retrieve information\nfrom version control systems (VCSs), such as subversion, CVS or git, to\nbe able to provide it to the user; possibly in the user's prompt. So\nthat you can instantly tell which branch you are currently on, for ex-\nample.\n\nIn order to do that, you may use the vcsinfo function.\n\nThe following VCSs are supported, showing the abbreviated name by which\nthey are referred to within the system:\nBazaar (bzr)\nhttps://bazaar.canonical.com/\nCodeville (cdv)\nhttp://freecode.com/projects/codeville/\nConcurrent Versioning System (cvs)\nhttps://www.nongnu.org/cvs/\nDarcs (darcs)\nhttp://darcs.net/\nFossil (fossil)\nhttps://fossil-scm.org/\nGit (git)\nhttps://git-scm.com/\nGNU arch (tla)\nhttps://www.gnu.org/software/gnu-arch/\nMercurial (hg)\nhttps://www.mercurial-scm.org/\nMonotone (mtn)\nhttps://monotone.ca/\nPerforce (p4)\nhttps://www.perforce.com/\nSubversion (svn)\nhttps://subversion.apache.org/\nSVK (svk)\nhttps://svk.bestpractical.com/\n\nThere is also support for the patch management system quilt\n(https://savannah.nongnu.org/projects/quilt). See Quilt Support below\nfor details.\n\nTo load vcsinfo:\n\nautoload -Uz vcsinfo\n\nIt can be used in any existing prompt, because it does not require any\nspecific $psvar entries to be available.\n\nQuickstart\nTo get this feature working quickly (including colors), you can do the\nfollowing (assuming, you loaded vcsinfo properly - see above):\n\nzstyle ':vcsinfo:*' actionformats \\\n'%F{5}(%f%s%F{5})%F{3}-%F{5}[%F{2}%b%F{3}|%F{1}%a%F{5}]%f '\nzstyle ':vcsinfo:*' formats \\\n'%F{5}(%f%s%F{5})%F{3}-%F{5}[%F{2}%b%F{5}]%f '\nzstyle ':vcsinfo:(sv[nk]|bzr):*' branchformat '%b%F{1}:%F{3}%r'\nprecmd () { vcsinfo }\nPS1='%F{5}[%F{2}%n%F{5}] %F{3}%3~ ${vcsinfomsg0}%f%# '\n\nObviously, the last two lines are there for demonstration. You need to\ncall vcsinfo from your precmd function. Once that is done you need a\nsingle quoted '${vcsinfomsg0}' in your prompt.\n\nTo be able to use '${vcsinfomsg0}' directly in your prompt like\nthis, you will need to have the PROMPTSUBST option enabled.\n\nNow call the vcsinfoprintsys utility from the command line:\n\n% vcsinfoprintsys\n## list of supported version control backends:\n## disabled systems are prefixed by a hash sign (#)\nbzr\ncdv\ncvs\ndarcs\nfossil\ngit\nhg\nmtn\np4\nsvk\nsvn\ntla\n## flavours (cannot be used in the enable or disable styles; they\n## are enabled and disabled with their master [git-svn -> git])\n## they *can* be used in contexts: ':vcsinfo:git-svn:*'.\ngit-p4\ngit-svn\nhg-git\nhg-hgsubversion\nhg-hgsvn\n\nYou may not want all of these because there is no point in running the\ncode to detect systems you do not use. So there is a way to disable\nsome backends altogether:\n\nzstyle ':vcsinfo:*' disable bzr cdv darcs mtn svk tla\n\nYou may also pick a few from that list and enable only those:\n\nzstyle ':vcsinfo:*' enable git cvs svn\n\nIf you rerun vcsinfoprintsys after one of these commands, you will\nsee the backends listed in the disable style (or backends not in the\nenable style - if you used that) marked as disabled by a hash sign.\nThat means the detection of these systems is skipped completely. No\nwasted time there.\n\nConfiguration\nThe vcsinfo feature can be configured via zstyle.\n\nFirst, the context in which we are working:\n:vcsinfo:vcs-string:user-context:repo-root-name\n\nvcs-string\nis one of: git, git-svn, git-p4, hg, hg-git, hg-hgsubversion,\nhg-hgsvn, darcs, bzr, cdv, mtn, svn, cvs, svk, tla, p4 or fos-\nsil. This is followed by `.quilt-quilt-mode' in Quilt mode (see\nQuilt Support for details) and by `+hook-name' while hooks are\nactive (see Hooks in vcsinfo for details).\n\nCurrently, hooks in quilt mode don't add the `.quilt-quilt-mode'\ninformation. This may change in the future.\n\nuser-context\nis a freely configurable string, assignable by the user as the\nfirst argument to vcsinfo (see its description below).\n\nrepo-root-name\nis the name of a repository in which you want a style to match.\nSo, if you want a setting specific to /usr/src/zsh, with that\nbeing a CVS checkout, you can set repo-root-name to zsh to make\nit so.\n\nThere are three special values for vcs-string: The first is named\n-init-, that is in effect as long as there was no decision what VCS\nbackend to use. The second is -preinit-; it is used before vcsinfo is\nrun, when initializing the data exporting variables. The third special\nvalue is formats and is used by the vcsinfolastmsg for looking up its\nstyles.\n\nThe initial value of repo-root-name is -all- and it is replaced with\nthe actual name, as soon as it is known. Only use this part of the con-\ntext for defining the formats, actionformats or branchformat styles, as\nit is guaranteed that repo-root-name is set up correctly for these\nonly. For all other styles, just use '*' instead.\n\nThere are two pre-defined values for user-context:\ndefault\nthe one used if none is specified\ncommand\nused by vcsinfolastmsg to lookup its styles\n\nYou can of course use ':vcsinfo:*' to match all VCSs in all user-con-\ntexts at once.\n\nThis is a description of all styles that are looked up.\n\nformats\nA list of formats, used when actionformats is not used (which is\nmost of the time).\n\nactionformats\nA list of formats, used if there is a special action going on in\nyour current repository; like an interactive rebase or a merge\nconflict.\n\nbranchformat\nSome backends replace %b in the formats and actionformats styles\nabove, not only by a branch name but also by a revision number.\nThis style lets you modify how that string should look.\n\nnvcsformats\nThese \"formats\" are set when we didn't detect a version control\nsystem for the current directory or vcsinfo was disabled. This\nis useful if you want vcsinfo to completely take over the gen-\neration of your prompt. You would do something like\nPS1='${vcsinfomsg0}' to accomplish that.\n\nhgrevformat\nhg uses both a hash and a revision number to reference a spe-\ncific changeset in a repository. With this style you can format\nthe revision string (see branchformat) to include either or\nboth. It's only useful when get-revision is true. Note, the full\n40-character revision id is not available (except when using the\nuse-simple option) because executing hg more than once per\nprompt is too slow; you may customize this behavior using hooks.\n\nmax-exports\nDefines the maximum number of vcsinfomsg* variables vcsinfo\nwill set.\n\nenable A list of backends you want to use. Checked in the -init- con-\ntext. If this list contains an item called NONE no backend is\nused at all and vcsinfo will do nothing. If this list contains\nALL, vcsinfo will use all known backends. Only with ALL in en-\nable will the disable style have any effect. ALL and NONE are\ncase insensitive.\n\ndisable\nA list of VCSs you don't want vcsinfo to test for repositories\n(checked in the -init- context, too). Only used if enable con-\ntains ALL.\n\ndisable-patterns\nA list of patterns that are checked against $PWD. If a pattern\nmatches, vcsinfo will be disabled. This style is checked in the\n:vcsinfo:-init-:*:-all- context.\n\nSay, ~/.zsh is a directory under version control, in which you\ndo not want vcsinfo to be active, do:\nzstyle ':vcsinfo:*' disable-patterns \"${(b)HOME}/.zsh(|/*)\"\n\nuse-quilt\nIf enabled, the quilt support code is active in `addon' mode.\nSee Quilt Support for details.\n\nquilt-standalone\nIf enabled, `standalone' mode detection is attempted if no VCS\nis active in a given directory. See Quilt Support for details.\n\nquilt-patch-dir\nOverwrite the value of the $QUILTPATCHES environment variable.\nSee Quilt Support for details.\n\nquiltcommand\nWhen quilt itself is called in quilt support, the value of this\nstyle is used as the command name.\n\ncheck-for-changes\nIf enabled, this style causes the %c and %u format escapes to\nshow when the working directory has uncommitted changes. The\nstrings displayed by these escapes can be controlled via the\nstagedstr and unstagedstr styles. The only backends that cur-\nrently support this option are git, hg, and bzr (the latter two\nonly support unstaged).\n\nFor this style to be evaluated with the hg backend, the get-re-\nvision style needs to be set and the use-simple style needs to\nbe unset. The latter is the default; the former is not.\n\nWith the bzr backend, lightweight checkouts only honor this\nstyle if the use-server style is set.\n\nNote, the actions taken if this style is enabled are potentially\nexpensive (read: they may be slow, depending on how big the cur-\nrent repository is). Therefore, it is disabled by default.\n\ncheck-for-staged-changes\nThis style is like check-for-changes, but it never checks the\nworktree files, only the metadata in the .${vcs} dir. There-\nfore, this style initializes only the %c escape (with stagedstr)\nbut not the %u escape. This style is faster than\ncheck-for-changes.\n\nIn the git backend, this style checks for changes in the index.\nOther backends do not currently implement this style.\n\nThis style is disabled by default.\n\nstagedstr\nThis string will be used in the %c escape if there are staged\nchanges in the repository.\n\nunstagedstr\nThis string will be used in the %u escape if there are unstaged\nchanges in the repository.\n\ncommand\nThis style causes vcsinfo to use the supplied string as the\ncommand to use as the VCS's binary. Note, that setting this in\n':vcsinfo:*' is not a good idea.\n\nIf the value of this style is empty (which is the default), the\nused binary name is the name of the backend in use (e.g. svn is\nused in an svn repository).\n\nThe repo-root-name part in the context is always the default\n-all- when this style is looked up.\n\nFor example, this style can be used to use binaries from non-de-\nfault installation directories. Assume, git is installed in\n/usr/bin but your sysadmin installed a newer version in /usr/lo-\ncal/bin. Instead of changing the order of your $PATH parameter,\nyou can do this:\nzstyle ':vcsinfo:git:*:-all-' command /usr/local/bin/git\n\nuse-server\nThis is used by the Perforce backend (p4) to decide if it should\ncontact the Perforce server to find out if a directory is man-\naged by Perforce. This is the only reliable way of doing this,\nbut runs the risk of a delay if the server name cannot be found.\nIf the server (more specifically, the host:port pair describing\nthe server) cannot be contacted, its name is put into the asso-\nciative array vcsinfop4deadservers and is not contacted\nagain during the session until it is removed by hand. If you do\nnot set this style, the p4 backend is only usable if you have\nset the environment variable P4CONFIG to a file name and have\ncorresponding files in the root directories of each Perforce\nclient. See comments in the function VCSINFOdetectp4 for\nmore detail.\n\nThe Bazaar backend (bzr) uses this to permit contacting the\nserver about lightweight checkouts, see the check-for-changes\nstyle.\n\nuse-simple\nIf there are two different ways of gathering information, you\ncan select the simpler one by setting this style to true; the\ndefault is to use the not-that-simple code, which is potentially\na lot slower but might be more accurate in all possible cases.\nThis style is used by the bzr and hg backends. In the case of hg\nit will invoke the external hexdump program to parse the binary\ndirstate cache file; this method will not return the local revi-\nsion number.\n\nget-revision\nIf set to true, vcsinfo goes the extra mile to figure out the\nrevision of a repository's work tree (currently for the git and\nhg backends, where this kind of information is not always vi-\ntal). For git, the hash value of the currently checked out com-\nmit is available via the %i expansion. With hg, the local revi-\nsion number and the corresponding global hash are available via\n%i.\n\nget-mq If set to true, the hg backend will look for a Mercurial Queue\n(mq) patch directory. Information will be available via the `%m'\nreplacement.\n\nget-bookmarks\nIf set to true, the hg backend will try to get a list of current\nbookmarks. They will be available via the `%m' replacement.\n\nThe default is to generate a comma-separated list of all book-\nmark names that refer to the currently checked out revision. If\na bookmark is active, its name is suffixed an asterisk and\nplaced first in the list.\n\nuse-prompt-escapes\nDetermines if we assume that the assembled string from vcsinfo\nincludes prompt escapes. (Used by vcsinfolastmsg.)\n\ndebug Enable debugging output to track possible problems. Currently\nthis style is only used by vcsinfo's hooks system.\n\nhooks A list style that defines hook-function names. See Hooks in\nvcsinfo below for details.\n\npatch-format\nnopatch-format\nThis pair of styles format the patch information used by the %m\nexpando in formats and actionformats for the git and hg back-\nends. The value is subject to certain %-expansions described\nbelow. The expanded value is made available in the global back-\nendmisc array as ${backendmisc[patches]} (also if a\nset-patch-format hook is used).\n\nget-unapplied\nThis boolean style controls whether a backend should attempt to\ngather a list of unapplied patches (for example with Mercurial\nQueue patches).\n\nUsed by the quilt and hg backends.\n\nThe default values for these styles in all contexts are:\n\nformats\n\" (%s)-[%b]%u%c-\"\nactionformats\n\" (%s)-[%b|%a]%u%c-\"\nbranchformat\n\"%b:%r\" (for bzr, svn, svk and hg)\nnvcsformats\n\"\"\nhgrevformat\n\"%r:%h\"\nmax-exports\n2\nenable ALL\ndisable\n(empty list)\ndisable-patterns\n(empty list)\ncheck-for-changes\nfalse\ncheck-for-staged-changes\nfalse\nstagedstr\n(string: \"S\")\nunstagedstr\n(string: \"U\")\ncommand\n(empty string)\nuse-server\nfalse\nuse-simple\nfalse\nget-revision\nfalse\nget-mq true\nget-bookmarks\nfalse\nuse-prompt-escapes\ntrue\ndebug false\nhooks (empty list)\nuse-quilt\nfalse\nquilt-standalone\nfalse\nquilt-patch-dir\nempty - use $QUILTPATCHES\nquiltcommand\nquilt\npatch-format\nbackend dependent\nnopatch-format\nbackend dependent\nget-unapplied\nfalse\n\nIn normal formats and actionformats the following replacements are\ndone:\n\n%s The VCS in use (git, hg, svn, etc.).\n%b Information about the current branch.\n%a An identifier that describes the action. Only makes sense in ac-\ntionformats.\n%i The current revision number or identifier. For hg the hgrevfor-\nmat style may be used to customize the output.\n%c The string from the stagedstr style if there are staged changes\nin the repository.\n%u The string from the unstagedstr style if there are unstaged\nchanges in the repository.\n%R The base directory of the repository.\n%r The repository name. If %R is /foo/bar/repoXY, %r is repoXY.\n%S A subdirectory within a repository. If $PWD is /foo/bar/re-\npoXY/beer/tasty, %S is beer/tasty.\n%m A \"misc\" replacement. It is at the discretion of the backend to\ndecide what this replacement expands to.\n\nThe hg and git backends use this expando to display patch infor-\nmation. hg sources patch information from the mq extensions;\ngit from in-progress rebase and cherry-pick operations and from\nthe stgit extension. The patch-format and nopatch-format styles\ncontrol the generated string. The former is used when at least\none patch from the patch queue has been applied, and the latter\notherwise.\n\nThe hg backend displays bookmark information in this expando (in\naddition to mq information). See the get-mq and get-bookmarks\nstyles. Both of these styles may be enabled at the same time.\nIf both are enabled, both resulting strings will be shown sepa-\nrated by a semicolon (that cannot currently be customized).\n\nThe quilt `standalone' backend sets this expando to the same\nvalue as the %Q expando.\n\n%Q Quilt series information. When quilt is used (either in `addon'\nmode or as a `standalone' backend), this expando is set to quilt\nseries' patch-format string. The set-patch-format hook and\nnopatch-format style are honoured.\n\nSee Quilt Support below for details.\n\nIn branchformat these replacements are done:\n\n%b The branch name.\n%r The current revision number or the hgrevformat style for hg.\n\nIn hgrevformat these replacements are done:\n\n%r The current local revision number.\n%h The current global revision identifier.\n\nIn patch-format and nopatch-format these replacements are done:\n\n%p The name of the top-most applied patch; may be overridden by the\napplied-string hook.\n%u The number of unapplied patches; may be overridden by the unap-\nplied-string hook.\n%n The number of applied patches.\n%c The number of unapplied patches.\n%a The number of all patches (%a = %n + %c).\n%g The names of active mq guards (hg backend).\n%G The number of active mq guards (hg backend).\n\nNot all VCS backends have to support all replacements. For nvcsformats\nno replacements are performed at all, it is just a string.\n\nOddities\nIf you want to use the %b (bold off) prompt expansion in formats, which\nexpands %b itself, use %%b. That will cause the vcsinfo expansion to\nreplace %%b with %b, so that zsh's prompt expansion mechanism can han-\ndle it. Similarly, to hand down %b from branchformat, use %%%%b. Sorry\nfor this inconvenience, but it cannot be easily avoided. Luckily we do\nnot clash with a lot of prompt expansions and this only needs to be\ndone for those.\n\nWhen one of the gen-applied-string, gen-unapplied-string, and\nset-patch-format hooks is defined, applying %-escaping\n(`foo=${foo//'%'/%%}') to the interpolated values for use in the prompt\nis the responsibility of those hooks (jointly); when neither of those\nhooks is defined, vcsinfo handles escaping by itself. We regret this\ncoupling, but it was required for backwards compatibility.\n\nQuilt Support\nQuilt is not a version control system, therefore this is not imple-\nmented as a backend. It can help keeping track of a series of patches.\nPeople use it to keep a set of changes they want to use on top of soft-\nware packages (which is tightly integrated into the package build\nprocess - the Debian project does this for a large number of packages).\nQuilt can also help individual developers keep track of their own\npatches on top of real version control systems.\n\nThe vcsinfo integration tries to support both ways of using quilt by\nhaving two slightly different modes of operation: `addon' mode and\n`standalone' mode).\n\nQuilt integration is off by default; to enable it, set the use-quilt\nstyle, and add %Q to your formats or actionformats style:\nzstyle ':vcsinfo:*' use-quilt true\n\nStyles looked up from the Quilt support code include\n`.quilt-quilt-mode' in the vcs-string part of the context, where\nquilt-mode is either addon or standalone. Example:\n:vcsinfo:git.quilt-addon:default:repo-root-name.\n\nFor `addon' mode to become active vcsinfo must have already detected a\nreal version control system controlling the directory. If that is the\ncase, a directory that holds quilt's patches needs to be found. That\ndirectory is configurable via the `QUILTPATCHES' environment variable.\nIf that variable exists its value is used, otherwise the value\n`patches' is assumed. The value from $QUILTPATCHES can be overwritten\nusing the `quilt-patches' style. (Note: you can use vcsinfo to keep\nthe value of $QUILTPATCHES correct all the time via the post-quilt\nhook).\n\nWhen the directory in question is found, quilt is assumed to be active.\nTo gather more information, vcsinfo looks for a directory called\n`.pc'; Quilt uses that directory to track its current state. If this\ndirectory does not exist we know that quilt has not done anything to\nthe working directory (read: no patches have been applied yet).\n\nIf patches are applied, vcsinfo will try to find out which. If you\nwant to know which patches of a series are not yet applied, you need to\nactivate the get-unapplied style in the appropriate context.\n\nvcsinfo allows for very detailed control over how the gathered infor-\nmation is presented (see the Configuration and Hooks in vcsinfo sec-\ntions), all of which are documented below. Note there are a number of\nother patch tracking systems that work on top of a certain version con-\ntrol system (like stgit for git, or mq for hg); the configuration for\nsystems like that are generally configured the same way as the quilt\nsupport.\n\nIf the quilt support is working in `addon' mode, the produced string is\navailable as a simple format replacement (%Q to be precise), which can\nbe used in formats and actionformats; see below for details).\n\nIf, on the other hand, the support code is working in `standalone'\nmode, vcsinfo will pretend as if quilt were an actual version control\nsystem. That means that the version control system identifier (which\notherwise would be something like `svn' or `cvs') will be set to\n`-quilt-'. This has implications on the used style context where this\nidentifier is the second element. vcsinfo will have filled in a proper\nvalue for the \"repository's\" root directory and the string containing\nthe information about quilt's state will be available as the `misc' re-\nplacement (and %Q for compatibility with `addon' mode).\n\nWhat is left to discuss is how `standalone' mode is detected. The de-\ntection itself is a series of searches for directories. You can have\nthis detection enabled all the time in every directory that is not oth-\nerwise under version control. If you know there is only a limited set\nof trees where you would like vcsinfo to try and look for Quilt in\n`standalone' mode to minimise the amount of searching on every call to\nvcsinfo, there are a number of ways to do that:\n\nEssentially, `standalone' mode detection is controlled by a style\ncalled `quilt-standalone'. It is a string style and its value can have\ndifferent effects. The simplest values are: `always' to run detection\nevery time vcsinfo is run, and `never' to turn the detection off en-\ntirely.\n\nIf the value of quilt-standalone is something else, it is interpreted\ndifferently. If the value is the name of a scalar variable the value of\nthat variable is checked and that value is used in the same `al-\nways'/`never' way as described above.\n\nIf the value of quilt-standalone is an array, the elements of that ar-\nray are used as directory names under which you want the detection to\nbe active.\n\nIf quilt-standalone is an associative array, the keys are taken as di-\nrectory names under which you want the detection to be active, but only\nif the corresponding value is the string `true'.\n\nLast, but not least, if the value of quilt-standalone is the name of a\nfunction, the function is called without arguments and the return value\ndecides whether detection should be active. A `0' return value is true;\na non-zero return value is interpreted as false.\n\nNote, if there is both a function and a variable by the name of\nquilt-standalone, the function will take precedence.\n\nFunction Descriptions (Public API)\nvcsinfo [user-context]\nThe main function, that runs all backends and assembles all data\ninto ${vcsinfomsg*}. This is the function you want to call\nfrom precmd if you want to include up-to-date information in\nyour prompt (see Variable Description below). If an argument is\ngiven, that string will be used instead of default in the\nuser-context field of the style context.\n\nvcsinfohookadd\nStatically registers a number of functions to a given hook. The\nhook needs to be given as the first argument; what follows is a\nlist of hook-function names to register to the hook. The `+vi-'\nprefix needs to be left out here. See Hooks in vcsinfo below\nfor details.\n\nvcsinfohookdel\nRemove hook-functions from a given hook. The hook needs to be\ngiven as the first non-option argument; what follows is a list\nof hook-function names to un-register from the hook. If `-a' is\nused as the first argument, all occurrences of the functions are\nunregistered. Otherwise only the last occurrence is removed (if\na function was registered to a hook more than once). The `+vi-'\nprefix needs to be left out here. See Hooks in vcsinfo below\nfor details.\n\nvcsinfolastmsg\nOutputs the last ${vcsinfomsg*} value. Takes into account\nthe value of the use-prompt-escapes style in ':vcsinfo:for-\nmats:command:-all-'. It also only prints max-exports values.\n\nvcsinfoprintsys [user-context]\nPrints a list of all supported version control systems. Useful\nto find out possible contexts (and which of them are enabled) or\nvalues for the disable style.\n\nvcsinfosetsys\nInitializes vcsinfo's internal list of available backends. With\nthis function, you can add support for new VCSs without restart-\ning the shell.\n\nAll functions named VCSINFO* are for internal use only.\n\nVariable Description\n${vcsinfomsgN} (Note the trailing underscore)\nWhere N is an integer, e.g., vcsinfomsg0. These variables\nare the storage for the informational message the last vcsinfo\ncall has assembled. These are strongly connected to the formats,\nactionformats and nvcsformats styles described above. Those\nstyles are lists. The first member of that list gets expanded\ninto ${vcsinfomsg0}, the second into ${vcsinfomsg1} and\nthe Nth into ${vcsinfomsgN-1}. (See the max-exports style\nabove.)\n\nAll variables named VCSINFO* are for internal use only.\n\nHooks in vcsinfo\nHooks are places in vcsinfo where you can run your own code. That code\ncan communicate with the code that called it and through that, change\nthe system's behaviour.\n\nFor configuration, hooks change the style context:\n:vcsinfo:vcs-string+hook-name:user-context:repo-root-name\n\nTo register functions to a hook, you need to list them in the hooks\nstyle in the appropriate context.\n\nExample:\nzstyle ':vcsinfo:*+foo:*' hooks bar baz\n\nThis registers functions to the hook `foo' for all backends. In order\nto avoid namespace problems, all registered function names are\nprepended by a `+vi-', so the actual functions called for the `foo'\nhook are `+vi-bar' and `+vi-baz'.\n\nIf you would like to register a function to a hook regardless of the\ncurrent context, you may use the vcsinfohookadd function. To remove a\nfunction that was added like that, the vcsinfohookdel function can be\nused.\n\nIf something seems weird, you can enable the `debug' boolean style in\nthe proper context and the hook-calling code will print what it tried\nto execute and whether the function in question existed.\n\nWhen you register more than one function to a hook, all functions are\nexecuted one after another until one function returns non-zero or until\nall functions have been called. Context-sensitive hook functions are\nexecuted before statically registered ones (the ones added by\nvcsinfohookadd).\n\nYou may pass data between functions via an associative array,\nuserdata. For example:\n+vi-git-myfirsthook(){\nuserdata[myval]=$myval\n}\n+vi-git-mysecondhook(){\n# do something with ${userdata[myval]}\n}\n\nThere are a number of variables that are special in hook contexts:\n\nret The return value that the hooks system will return to the\ncaller. The default is an integer `zero'. If and how a changed\nret value changes the execution of the caller depends on the\nspecific hook. See the hook documentation below for details.\n\nhookcom\nAn associated array which is used for bidirectional communica-\ntion from the caller to hook functions. The used keys depend on\nthe specific hook.\n\ncontext\nThe active context of the hook. Functions that wish to change\nthis variable should make it local scope first.\n\nvcs The current VCS after it was detected. The same values as in the\nenable/disable style are used. Available in all hooks except\nstart-up.\n\nFinally, the full list of currently available hooks:\n\nstart-up\nCalled after starting vcsinfo but before the VCS in this direc-\ntory is determined. It can be used to deactivate vcsinfo tempo-\nrarily if necessary. When ret is set to 1, vcsinfo aborts and\ndoes nothing; when set to 2, vcsinfo sets up everything as if\nno version control were active and exits.\n\npre-get-data\nSame as start-up but after the VCS was detected.\n\ngen-hg-bookmark-string\nCalled in the Mercurial backend when a bookmark string is gener-\nated; the get-revision and get-bookmarks styles must be true.\n\nThis hook gets the names of the Mercurial bookmarks that\nvcsinfo collected from `hg'.\n\nIf a bookmark is active, the key ${hookcom[hg-active-bookmark]}\nis set to its name. The key is otherwise unset.\n\nWhen setting ret to non-zero, the string in ${hookcom[hg-book-\nmark-string]} will be used in the %m escape in formats and ac-\ntionformats and will be available in the global backendmisc ar-\nray as ${backendmisc[bookmarks]}.\n\ngen-applied-string\nCalled in the git (with stgit or during rebase or merge), and hg\n(with mq) backends and in quilt support when the applied-string\nis generated; the use-quilt zstyle must be true for quilt (the\nmq and stgit backends are active by default).\n\nThis hook gets the names of all applied patches which vcsinfo\ncollected so far in the opposite order, which means that the\nfirst argument is the top-most patch and so forth.\n\nWhen setting ret to non-zero, the string in ${hookcom[ap-\nplied-string]} will be available as %p in the patch-format and\nnopatch-format styles. This hook is, in concert with\nset-patch-format, responsible for %-escaping that value for use\nin the prompt. (See the Oddities section.)\n\ngen-unapplied-string\nCalled in the git (with stgit or during rebase), and hg (with\nmq) backend and in quilt support when the unapplied-string is\ngenerated; the get-unapplied style must be true.\n\nThis hook gets the names of all unapplied patches which vcsinfo\ncollected so far in order, which means that the first argument\nis the patch next-in-line to be applied and so forth.\n\nWhen setting ret to non-zero, the string in ${hookcom[unap-\nplied-string]} will be available as %u in the patch-format and\nnopatch-format styles. This hook is, in concert with\nset-patch-format, responsible for %-escaping that value for use\nin the prompt. (See the Oddities section.)\n\ngen-mqguards-string\nCalled in the hg backend when guards-string is generated; the\nget-mq style must be true (default).\n\nThis hook gets the names of any active mq guards.\n\nWhen setting ret to non-zero, the string in\n${hookcom[guards-string]} will be used in the %g escape in the\npatch-format and nopatch-format styles.\n\nno-vcs This hooks is called when no version control system was de-\ntected.\n\nThe `hookcom' parameter is not used.\n\npost-backend\nCalled as soon as the backend has finished collecting informa-\ntion.\n\nThe `hookcom' keys available are as for the set-message hook.\n\npost-quilt\nCalled after the quilt support is done. The following informa-\ntion is passed as arguments to the hook: 1. the quilt-support\nmode (`addon' or `standalone'); 2. the directory that contains\nthe patch series; 3. the directory that holds quilt's status in-\nformation (the `.pc' directory) or the string \"-nopc-\" if that\ndirectory wasn't found.\n\nThe `hookcom' parameter is not used.\n\nset-branch-format\nCalled before `branchformat' is set. The only argument to the\nhook is the format that is configured at this point.\n\nThe `hookcom' keys considered are `branch' and `revision'.\nThey are set to the values figured out so far by vcsinfo and\nany change will be used directly when the actual replacement is\ndone.\n\nIf ret is set to non-zero, the string in ${hookcom[branch-re-\nplace]} will be used unchanged as the `%b' replacement in the\nvariables set by vcsinfo.\n\nset-hgrev-format\nCalled before a `hgrevformat' is set. The only argument to the\nhook is the format that is configured at this point.\n\nThe `hookcom' keys considered are `hash' and `localrev'. They\nare set to the values figured out so far by vcsinfo and any\nchange will be used directly when the actual replacement is\ndone.\n\nIf ret is set to non-zero, the string in ${hookcom[rev-re-\nplace]} will be used unchanged as the `%i' replacement in the\nvariables set by vcsinfo.\n\npre-addon-quilt\nThis hook is used when vcsinfo's quilt functionality is active\nin \"addon\" mode (quilt used on top of a real version control\nsystem). It is activated right before any quilt specific action\nis taken.\n\nSetting the `ret' variable in this hook to a non-zero value\navoids any quilt specific actions from being run at all.\n\nset-patch-format\nThis hook is used to control some of the possible expansions in\npatch-format and nopatch-format styles with patch queue systems\nsuch as quilt, mqueue and the like.\n\nThis hook is used in the git, hg and quilt backends.\n\nThe hook allows the control of the %p (${hookcom[applied]}) and\n%u (${hookcom[unapplied]}) expansion in all backends that use\nthe hook. With the mercurial backend, the %g\n(${hookcom[guards]}) expansion is controllable in addition to\nthat.\n\nIf ret is set to non-zero, the string in ${hookcom[patch-re-\nplace]} will be used unchanged instead of an expanded format\nfrom patch-format or nopatch-format.\n\nThis hook is, in concert with the gen-applied-string or gen-un-\napplied-string hooks if they are defined, responsible for %-es-\ncaping the final patch-format value for use in the prompt. (See\nthe Oddities section.)\n\nset-message\nCalled each time before a `vcsinfomsgN' message is set. It\ntakes two arguments; the first being the `N' in the message\nvariable name, the second is the currently configured formats or\nactionformats.\n\nThere are a number of `hookcom' keys, that are used here: `ac-\ntion', `branch', `base', `base-name', `subdir', `staged', `un-\nstaged', `revision', `misc', `vcs' and one `miscN' entry for\neach backend-specific data field (N starting at zero). They are\nset to the values figured out so far by vcsinfo and any change\nwill be used directly when the actual replacement is done.\n\nSince this hook is triggered multiple times (once for each con-\nfigured formats or actionformats), each of the `hookcom' keys\nmentioned above (except for the miscN entries) has an `orig'\ncounterpart, so even if you changed a value to your liking you\ncan still get the original value in the next run. Changing the\n`orig' values is probably not a good idea.\n\nIf ret is set to non-zero, the string in ${hookcom[message]}\nwill be used unchanged as the message by vcsinfo.\n\nIf all of this sounds rather confusing, take a look at the Examples\nsection below and also in the Misc/vcsinfo-examples file in the Zsh\nsource. They contain some explanatory code.\n\nExamples\nDon't use vcsinfo at all (even though it's in your prompt):\nzstyle ':vcsinfo:*' enable NONE\n\nDisable the backends for bzr and svk:\nzstyle ':vcsinfo:*' disable bzr svk\n\nDisable everything but bzr and svk:\nzstyle ':vcsinfo:*' enable bzr svk\n\nProvide a special formats for git:\nzstyle ':vcsinfo:git:*' formats ' GIT, BABY! [%b]'\nzstyle ':vcsinfo:git:*' actionformats ' GIT ACTION! [%b|%a]'\n\nAll %x expansion in all sorts of formats (formats, actionformats,\nbranchformat, you name it) are done using the `zformat' builtin from\nthe `zsh/zutil' module. That means you can do everything with these %x\nitems what zformat supports. In particular, if you want something that\nis really long to have a fixed width, like a hash in a mercurial\nbranchformat, you can do this: %12.12i. That'll shrink the 40 character\nhash to its 12 leading characters. The form is actually `%min.maxx'.\nMore is possible. See the section `The zsh/zutil Module' in zshmod-\nules(1) for details.\n\nUse the quicker bzr backend\nzstyle ':vcsinfo:bzr:*' use-simple true\n\nIf you do use use-simple, please report if it does\n`the-right-thing[tm]'.\n\nDisplay the revision number in yellow for bzr and svn:\nzstyle ':vcsinfo:(svn|bzr):*' \\\nbranchformat '%b%{'${fg[yellow]}'%}:%r'\n\nIf you want colors, make sure you enclose the color codes in %{...%} if\nyou want to use the string provided by vcsinfo in prompts.\n\nHere is how to print the VCS information as a command (not in a\nprompt):\nalias vcsi='vcsinfo command; vcsinfolastmsg'\n\nThis way, you can even define different formats for output via\nvcsinfolastmsg in the ':vcsinfo:*:command:*' namespace.\n\nNow as promised, some code that uses hooks: say, you'd like to replace\nthe string `svn' by `subversion' in vcsinfo's %s formats replacement.\n\nFirst, we will tell vcsinfo to call a function when populating the\nmessage variables with the gathered information:\nzstyle ':vcsinfo:*+set-message:*' hooks svn2subversion\n\nNothing happens. Which is reasonable, since we didn't define the actual\nfunction yet. To see what the hooks subsystem is trying to do, enable\nthe `debug' style:\nzstyle ':vcsinfo:*+*:*' debug true\n\nThat should give you an idea what is going on. Specifically, the func-\ntion that we are looking for is `+vi-svn2subversion'. Note, the `+vi-'\nprefix. So, everything is in order, just as documented. When you are\ndone checking out the debugging output, disable it again:\nzstyle ':vcsinfo:*+*:*' debug false\n\nNow, let's define the function:\nfunction +vi-svn2subversion() {\n[[ ${hookcom[vcsorig]} == svn ]] && hookcom[vcs]=subversion\n}\n\nSimple enough. And it could have even been simpler, if only we had reg-\nistered our function in a less generic context. If we do it only in the\n`svn' backend's context, we don't need to test which the active backend\nis:\nzstyle ':vcsinfo:svn+set-message:*' hooks svn2subversion\nfunction +vi-svn2subversion() {\nhookcom[vcs]=subversion\n}\n\nAnd finally a little more elaborate example, that uses a hook to create\na customised bookmark string for the hg backend.\n\nAgain, we start off by registering a function:\nzstyle ':vcsinfo:hg+gen-hg-bookmark-string:*' hooks hgbookmarks\n\nAnd then we define the `+vi-hgbookmarks' function:\nfunction +vi-hgbookmarks() {\n# The default is to connect all bookmark names by\n# commas. This mixes things up a little.\n# Imagine, there's one type of bookmarks that is\n# special to you. Say, because it's *your* work.\n# Those bookmarks look always like this: \"sh/*\"\n# (because your initials are sh, for example).\n# This makes the bookmarks string use only those\n# bookmarks. If there's more than one, it\n# concatenates them using commas.\n# The bookmarks returned by `hg' are available in\n# the function's positional parameters.\nlocal s=\"${(Mj:,:)@:#sh/*}\"\n# Now, the communication with the code that calls\n# the hook functions is done via the hookcom[]\n# hash. The key at which the `gen-hg-bookmark-string'\n# hook looks is `hg-bookmark-string'. So:\nhookcom[hg-bookmark-string]=$s\n# And to signal that we want to use the string we\n# just generated, set the special variable `ret' to\n# something other than the default zero:\nret=1\nreturn 0\n}\n\nSome longer examples and code snippets which might be useful are avail-\nable in the examples file located at Misc/vcsinfo-examples in the Zsh\nsource directory.\n\nThis concludes our guided tour through zsh's vcsinfo.\n", "subsections": [] }, "PROMPT THEMES": { "content": "Installation\nYou should make sure all the functions from the Functions/Prompts di-\nrectory of the source distribution are available; they all begin with\nthe string `prompt' except for the special function`promptinit'. You\nalso need the `colors' and `add-zsh-hook' functions from Func-\ntions/Misc. All these functions may already be installed on your sys-\ntem; if not, you will need to find them and copy them. The directory\nshould appear as one of the elements of the fpath array (this should\nalready be the case if they were installed), and at least the function\npromptinit should be autoloaded; it will autoload the rest. Finally,\nto initialize the use of the system you need to call the promptinit\nfunction. The following code in your .zshrc will arrange for this; as-\nsume the functions are stored in the directory ~/myfns:\n\nfpath=(~/myfns $fpath)\nautoload -U promptinit\npromptinit\n\nTheme Selection\nUse the prompt command to select your preferred theme. This command\nmay be added to your .zshrc following the call to promptinit in order\nto start zsh with a theme already selected.\n\nprompt [ -c | -l ]\nprompt [ -p | -h ] [ theme ... ]\nprompt [ -s ] theme [ arg ... ]\nSet or examine the prompt theme. With no options and a theme\nargument, the theme with that name is set as the current theme.\nThe available themes are determined at run time; use the -l op-\ntion to see a list. The special theme `random' selects at ran-\ndom one of the available themes and sets your prompt to that.\n\nIn some cases the theme may be modified by one or more argu-\nments, which should be given after the theme name. See the help\nfor each theme for descriptions of these arguments.\n\nOptions are:\n\n-c Show the currently selected theme and its parameters, if\nany.\n-l List all available prompt themes.\n-p Preview the theme named by theme, or all themes if no\ntheme is given.\n-h Show help for the theme named by theme, or for the prompt\nfunction if no theme is given.\n-s Set theme as the current theme and save state.\n\npromptthemesetup\nEach available theme has a setup function which is called by the\nprompt function to install that theme. This function may define\nother functions as necessary to maintain the prompt, including\nfunctions used to preview the prompt or provide help for its\nuse. You should not normally call a theme's setup function di-\nrectly.\n\nUtility Themes\nprompt off\nThe theme `off' sets all the prompt variables to minimal values\nwith no special effects.\n\nprompt default\nThe theme `default' sets all prompt variables to the same state\nas if an interactive zsh was started with no initialization\nfiles.\n\nprompt restore\nThe special theme `restore' erases all theme settings and sets\nprompt variables to their state before the first time the\n`prompt' function was run, provided each theme has properly de-\nfined its cleanup (see below).\n\nNote that you can undo `prompt off' and `prompt default' with\n`prompt restore', but a second restore does not undo the first.\n\nWriting Themes\nThe first step for adding your own theme is to choose a name for it,\nand create a file `promptnamesetup' in a directory in your fpath,\nsuch as ~/myfns in the example above. The file should at minimum con-\ntain assignments for the prompt variables that your theme wishes to\nmodify. By convention, themes use PS1, PS2, RPS1, etc., rather than\nthe longer PROMPT and RPROMPT.\n\nThe file is autoloaded as a function in the current shell context, so\nit may contain any necessary commands to customize your theme, includ-\ning defining additional functions. To make some complex tasks easier,\nyour setup function may also do any of the following:\n\nAssign promptopts\nThe array promptopts may be assigned any of \"bang\", \"cr\", \"per-\ncent\", \"sp\", and/or \"subst\" as values. The corresponding se-\ntopts (promptbang, etc.) are turned on, all other prompt-related\noptions are turned off. The promptopts array preserves setopts\neven beyond the scope of localoptions, should your function need\nthat.\n\nModify precmd and preexec\nUse of add-zsh-hook is recommended. The precmd and preexec\nhooks are automatically adjusted if the prompt theme changes or\nis disabled.\n\nDeclare cleanup\nIf your function makes any other changes that should be undone\nwhen the theme is disabled, your setup function may call\npromptcleanup command\nwhere command should be suitably quoted. If your theme is ever dis-\nabled or replaced by another, command is executed with eval. You may\ndeclare more than one such cleanup hook.\n\nDefine preview\nDefine or autoload a function promptnamepreview to display a\nsimulated version of your prompt. A simple default previewer is\ndefined by promptinit for themes that do not define their own.\nThis preview function is called by `prompt -p'.\n\nProvide help\nDefine or autoload a function promptnamehelp to display docu-\nmentation or help text for your theme. This help function is\ncalled by `prompt -h'.\n", "subsections": [] }, "ZLE FUNCTIONS": { "content": "Widgets\nThese functions all implement user-defined ZLE widgets (see zshzle(1))\nwhich can be bound to keystrokes in interactive shells. To use them,\nyour .zshrc should contain lines of the form\n\nautoload function\nzle -N function\n\nfollowed by an appropriate bindkey command to associate the function\nwith a key sequence. Suggested bindings are described below.\n\nbash-style word functions\nIf you are looking for functions to implement moving over and\nediting words in the manner of bash, where only alphanumeric\ncharacters are considered word characters, you can use the func-\ntions described in the next section. The following is suffi-\ncient:\n\nautoload -U select-word-style\nselect-word-style bash\n\nforward-word-match, backward-word-match\nkill-word-match, backward-kill-word-match\ntranspose-words-match, capitalize-word-match\nup-case-word-match, down-case-word-match\ndelete-whole-word-match, select-word-match\nselect-word-style, match-word-context, match-words-by-style\nThe first eight `-match' functions are drop-in replacements for\nthe builtin widgets without the suffix. By default they behave\nin a similar way. However, by the use of styles and the func-\ntion select-word-style, the way words are matched can be al-\ntered. select-word-match is intended to be used as a text object\nin vi mode but with custom word styles. For comparison, the wid-\ngets described in zshzle(1) under Text Objects use fixed defini-\ntions of words, compatible with the vim editor.\n\nThe simplest way of configuring the functions is to use se-\nlect-word-style, which can either be called as a normal function\nwith the appropriate argument, or invoked as a user-defined wid-\nget that will prompt for the first character of the word style\nto be used. The first time it is invoked, the first eight\n-match functions will automatically replace the builtin ver-\nsions, so they do not need to be loaded explicitly.\n\nThe word styles available are as follows. Only the first char-\nacter is examined.\n\nbash Word characters are alphanumeric characters only.\n\nnormal As in normal shell operation: word characters are al-\nphanumeric characters plus any characters present in the\nstring given by the parameter $WORDCHARS.\n\nshell Words are complete shell command arguments, possibly in-\ncluding complete quoted strings, or any tokens special to\nthe shell.\n\nwhitespace\nWords are any set of characters delimited by whitespace.\n\ndefault\nRestore the default settings; this is usually the same as\n`normal'.\n\nAll but `default' can be input as an upper case character, which\nhas the same effect but with subword matching turned on. In\nthis case, words with upper case characters are treated spe-\ncially: each separate run of upper case characters, or an upper\ncase character followed by any number of other characters, is\nconsidered a word. The style subword-range can supply an alter-\nnative character range to the default `[:upper:]'; the value of\nthe style is treated as the contents of a `[...]' pattern (note\nthat the outer brackets should not be supplied, only those sur-\nrounding named ranges).\n\nMore control can be obtained using the zstyle command, as de-\nscribed in zshmodules(1). Each style is looked up in the con-\ntext :zle:widget where widget is the name of the user-defined\nwidget, not the name of the function implementing it, so in the\ncase of the definitions supplied by select-word-style the appro-\npriate contexts are :zle:forward-word, and so on. The function\nselect-word-style itself always defines styles for the context\n`:zle:*' which can be overridden by more specific (longer) pat-\nterns as well as explicit contexts.\n\nThe style word-style specifies the rules to use. This may have\nthe following values.\n\nnormal Use the standard shell rules, i.e. alphanumerics and\n$WORDCHARS, unless overridden by the styles word-chars or\nword-class.\n\nspecified\nSimilar to normal, but only the specified characters, and\nnot also alphanumerics, are considered word characters.\n\nunspecified\nThe negation of specified. The given characters are\nthose which will not be considered part of a word.\n\nshell Words are obtained by using the syntactic rules for gen-\nerating shell command arguments. In addition, special\ntokens which are never command arguments such as `()' are\nalso treated as words.\n\nwhitespace\nWords are whitespace-delimited strings of characters.\n\nThe first three of those rules usually use $WORDCHARS, but the\nvalue in the parameter can be overridden by the style\nword-chars, which works in exactly the same way as $WORDCHARS.\nIn addition, the style word-class uses character class syntax to\ngroup characters and takes precedence over word-chars if both\nare set. The word-class style does not include the surrounding\nbrackets of the character class; for example, `-:[:alnum:]' is a\nvalid word-class to include all alphanumerics plus the charac-\nters `-' and `:'. Be careful including `]', `^' and `-' as\nthese are special inside character classes.\n\nword-style may also have `-subword' appended to its value to\nturn on subword matching, as described above.\n\nThe style skip-chars is mostly useful for transpose-words and\nsimilar functions. If set, it gives a count of characters\nstarting at the cursor position which will not be considered\npart of the word and are treated as space, regardless of what\nthey actually are. For example, if\n\nzstyle ':zle:transpose-words' skip-chars 1\n\nhas been set, and transpose-words-match is called with the cur-\nsor on the X of fooXbar, where X can be any character, then the\nresulting expression is barXfoo.\n\nFiner grained control can be obtained by setting the style\nword-context to an array of pairs of entries. Each pair of en-\ntries consists of a pattern and a subcontext. The shell argu-\nment the cursor is on is matched against each pattern in turn\nuntil one matches; if it does, the context is extended by a\ncolon and the corresponding subcontext. Note that the test is\nmade against the original word on the line, with no stripping of\nquotes. Special handling is done between words: the current\ncontext is examined and if it contains the string between the\nword is set to a single space; else if it is contains the string\nback, the word before the cursor is considered, else the word\nafter cursor is considered. Some examples are given below.\n\nThe style skip-whitespace-first is only used with the for-\nward-word widget. If it is set to true, then forward-word skips\nany non-word-characters, followed by any non-word-characters:\nthis is similar to the behaviour of other word-orientated wid-\ngets, and also that used by other editors, however it differs\nfrom the standard zsh behaviour. When using select-word-style\nthe widget is set in the context :zle:* to true if the word\nstyle is bash and false otherwise. It may be overridden by set-\nting it in the more specific context :zle:forward-word*.\n\nIt is possible to create widgets with specific behaviour by\ndefining a new widget implemented by the appropriate generic\nfunction, then setting a style for the context of the specific\nwidget. For example, the following defines a widget back-\nward-kill-space-word using backward-kill-word-match, the generic\nwidget implementing backward-kill-word behaviour, and ensures\nthat the new widget always implements space-delimited behaviour.\n\nzle -N backward-kill-space-word backward-kill-word-match\nzstyle :zle:backward-kill-space-word word-style space\n\nThe widget backward-kill-space-word can now be bound to a key.\n\nHere are some further examples of use of the styles, actually\ntaken from the simplified interface in select-word-style:\n\nzstyle ':zle:*' word-style standard\nzstyle ':zle:*' word-chars ''\n\nImplements bash-style word handling for all widgets, i.e. only\nalphanumerics are word characters; equivalent to setting the pa-\nrameter WORDCHARS empty for the given context.\n\nstyle ':zle:*kill*' word-style space\n\nUses space-delimited words for widgets with the word `kill' in\nthe name. Neither of the styles word-chars nor word-class is\nused in this case.\n\nHere are some examples of use of the word-context style to ex-\ntend the context.\n\nzstyle ':zle:*' word-context \\\n\"*/*\" filename \"[[:space:]]\" whitespace\nzstyle ':zle:transpose-words:whitespace' word-style shell\nzstyle ':zle:transpose-words:filename' word-style normal\nzstyle ':zle:transpose-words:filename' word-chars ''\n\nThis provides two different ways of using transpose-words de-\npending on whether the cursor is on whitespace between words or\non a filename, here any word containing a /. On whitespace,\ncomplete arguments as defined by standard shell rules will be\ntransposed. In a filename, only alphanumerics will be trans-\nposed. Elsewhere, words will be transposed using the default\nstyle for :zle:transpose-words.\n\nThe word matching and all the handling of zstyle settings is ac-\ntually implemented by the function match-words-by-style. This\ncan be used to create new user-defined widgets. The calling\nfunction should set the local parameter curcontext to :zle:wid-\nget, create the local parameter matchedwords and call\nmatch-words-by-style with no arguments. On return,\nmatchedwords will be set to an array with the elements: (1) the\nstart of the line (2) the word before the cursor (3) any\nnon-word characters between that word and the cursor (4) any\nnon-word character at the cursor position plus any remaining\nnon-word characters before the next word, including all charac-\nters specified by the skip-chars style, (5) the word at or fol-\nlowing the cursor (6) any non-word characters following that\nword (7) the remainder of the line. Any of the elements may be\nan empty string; the calling function should test for this to\ndecide whether it can perform its function.\n\nIf the variable matchedwords is defined by the caller to\nmatch-words-by-style as an associative array (local -A\nmatchedwords), then the seven values given above should be re-\ntrieved from it as elements named start, word-before-cursor,\nws-before-cursor, ws-after-cursor, word-after-cursor, ws-af-\nter-word, and end. In addition the element is-word-start is 1\nif the cursor is on the start of a word or subword, or on white\nspace before it (the cases can be distinguished by testing the\nws-after-cursor element) and 0 otherwise. This form is recom-\nmended for future compatibility.\n\nIt is possible to pass options with arguments to\nmatch-words-by-style to override the use of styles. The options\nare:\n-w word-style\n-s skip-chars\n-c word-class\n-C word-chars\n-r subword-range\n\nFor example, match-words-by-style -w shell -c 0 may be used to\nextract the command argument around the cursor.\n\nThe word-context style is implemented by the function\nmatch-word-context. This should not usually need to be called\ndirectly.\n\nbracketed-paste-magic\nThe bracketed-paste widget (see subsection Miscellaneous in zsh-\nzle(1)) inserts pasted text literally into the editor buffer\nrather than interpret it as keystrokes. This disables some com-\nmon usages where the self-insert widget is replaced in order to\naccomplish some extra processing. An example is the contributed\nurl-quote-magic widget described below.\n\nThe bracketed-paste-magic widget is meant to replace brack-\neted-paste with a wrapper that re-enables these self-insert ac-\ntions, and other actions as selected by zstyles. Therefore this\nwidget is installed with\n\nautoload -Uz bracketed-paste-magic\nzle -N bracketed-paste bracketed-paste-magic\n\nOther than enabling some widget processing, brack-\neted-paste-magic attempts to replicate bracketed-paste as faith-\nfully as possible.\n\nThe following zstyles may be set to control processing of pasted\ntext. All are looked up in the context `:brack-\neted-paste-magic'.\n\nactive-widgets\nA list of patterns matching widget names that should be\nactivated during the paste. All other key sequences are\nprocessed as self-insert-unmeta. The default is `self-*'\nso any user-defined widgets named with that prefix are\nactive along with the builtin self-insert.\n\nIf this style is not set (explicitly deleted) or set to\nan empty value, no widgets are active and the pasted text\nis inserted literally. If the value includes `unde-\nfined-key', any unknown sequences are discarded from the\npasted text.\n\ninactive-keys\nThe inverse of active-widgets, a list of key sequences\nthat always use self-insert-unmeta even when bound to an\nactive widget. Note that this is a list of literal key\nsequences, not patterns.\n\npaste-init\nA list of function names, called in widget context (but\nnot as widgets). The functions are called in order until\none of them returns a non-zero status. The parameter\n`PASTED' contains the initial state of the pasted text.\nAll other ZLE parameters such as `BUFFER' have their nor-\nmal values and side-effects, and full history is avail-\nable, so for example paste-init functions may move words\nfrom BUFFER into PASTED to make those words visible to\nthe active-widgets.\n\nA non-zero return from a paste-init function does not\nprevent the paste itself from proceeding.\n\nLoading bracketed-paste-magic defines backward-ex-\ntend-paste, a helper function for use in paste-init.\n\nzstyle :bracketed-paste-magic paste-init \\\nbackward-extend-paste\n\nWhen a paste would insert into the middle of a word or\nappend text to a word already on the line, backward-ex-\ntend-paste moves the prefix from LBUFFER into PASTED so\nthat the active-widgets see the full word so far. This\nmay be useful with url-quote-magic.\n\npaste-finish\nAnother list of function names called in order until one\nreturns non-zero. These functions are called after the\npasted text has been processed by the active-widgets, but\nbefore it is inserted into `BUFFER'. ZLE parameters have\ntheir normal values and side-effects.\n\nA non-zero return from a paste-finish function does not\nprevent the paste itself from proceeding.\n\nLoading bracketed-paste-magic also defines quote-paste, a\nhelper function for use in paste-finish.\n\nzstyle :bracketed-paste-magic paste-finish \\\nquote-paste\nzstyle :bracketed-paste-magic:finish quote-style \\\nqqq\n\nWhen the pasted text is inserted into BUFFER, it is\nquoted per the quote-style value. To forcibly turn off\nthe built-in numeric prefix quoting of bracketed-paste,\nuse:\n\nzstyle :bracketed-paste-magic:finish quote-style \\\nnone\n\nImportant: During active-widgets processing of the paste (after\npaste-init and before paste-finish), BUFFER starts empty and\nhistory is restricted, so cursor motions, etc., may not pass\noutside of the pasted content. Text assigned to BUFFER by the\nactive widgets is copied back into PASTED before paste-finish.\n\ncopy-earlier-word\nThis widget works like a combination of insert-last-word and\ncopy-prev-shell-word. Repeated invocations of the widget re-\ntrieve earlier words on the relevant history line. With a nu-\nmeric argument N, insert the Nth word from the history line; N\nmay be negative to count from the end of the line.\n\nIf insert-last-word has been used to retrieve the last word on a\nprevious history line, repeated invocations will replace that\nword with earlier words from the same line.\n\nOtherwise, the widget applies to words on the line currently be-\ning edited. The widget style can be set to the name of another\nwidget that should be called to retrieve words. This widget\nmust accept the same three arguments as insert-last-word.\n\ncycle-completion-positions\nAfter inserting an unambiguous string into the command line, the\nnew function based completion system may know about multiple\nplaces in this string where characters are missing or differ\nfrom at least one of the possible matches. It will then place\nthe cursor on the position it considers to be the most interest-\ning one, i.e. the one where one can disambiguate between as many\nmatches as possible with as little typing as possible.\n\nThis widget allows the cursor to be easily moved to the other\ninteresting spots. It can be invoked repeatedly to cycle be-\ntween all positions reported by the completion system.\n\ndelete-whole-word-match\nThis is another function which works like the -match functions\ndescribed immediately above, i.e. using styles to decide the\nword boundaries. However, it is not a replacement for any ex-\nisting function.\n\nThe basic behaviour is to delete the word around the cursor.\nThere is no numeric argument handling; only the single word\naround the cursor is considered. If the widget contains the\nstring kill, the removed text will be placed in the cutbuffer\nfor future yanking. This can be obtained by defining\nkill-whole-word-match as follows:\n\nzle -N kill-whole-word-match delete-whole-word-match\n\nand then binding the widget kill-whole-word-match.\n\nup-line-or-beginning-search, down-line-or-beginning-search\nThese widgets are similar to the builtin functions\nup-line-or-search and down-line-or-search: if in a multiline\nbuffer they move up or down within the buffer, otherwise they\nsearch for a history line matching the start of the current\nline. In this case, however, they search for a line which\nmatches the current line up to the current cursor position, in\nthe manner of history-beginning-search-backward and -forward,\nrather than the first word on the line.\n\nedit-command-line\nEdit the command line using your visual editor, as in ksh.\n\nbindkey -M vicmd v edit-command-line\n\nexpand-absolute-path\nExpand the file name under the cursor to an absolute path, re-\nsolving symbolic links. Where possible, the initial path seg-\nment is turned into a named directory or reference to a user's\nhome directory.\n\nhistory-search-end\nThis function implements the widgets history-begin-\nning-search-backward-end and history-beginning-search-for-\nward-end. These commands work by first calling the correspond-\ning builtin widget (see `History Control' in zshzle(1)) and then\nmoving the cursor to the end of the line. The original cursor\nposition is remembered and restored before calling the builtin\nwidget a second time, so that the same search is repeated to\nlook farther through the history.\n\nAlthough you autoload only one function, the commands to use it\nare slightly different because it implements two widgets.\n\nzle -N history-beginning-search-backward-end \\\nhistory-search-end\nzle -N history-beginning-search-forward-end \\\nhistory-search-end\nbindkey '\\e^P' history-beginning-search-backward-end\nbindkey '\\e^N' history-beginning-search-forward-end\n\nhistory-beginning-search-menu\nThis function implements yet another form of history searching.\nThe text before the cursor is used to select lines from the his-\ntory, as for history-beginning-search-backward except that all\nmatches are shown in a numbered menu. Typing the appropriate\ndigits inserts the full history line. Note that leading zeroes\nmust be typed (they are only shown when necessary for removing\nambiguity). The entire history is searched; there is no dis-\ntinction between forwards and backwards.\n\nWith a numeric argument, the search is not anchored to the start\nof the line; the string typed by the use may appear anywhere in\nthe line in the history.\n\nIf the widget name contains `-end' the cursor is moved to the\nend of the line inserted. If the widget name contains `-space'\nany space in the text typed is treated as a wildcard and can\nmatch anything (hence a leading space is equivalent to giving a\nnumeric argument). Both forms can be combined, for example:\n\nzle -N history-beginning-search-menu-space-end \\\nhistory-beginning-search-menu\n\nhistory-pattern-search\nThe function history-pattern-search implements widgets which\nprompt for a pattern with which to search the history backwards\nor forwards. The pattern is in the usual zsh format, however\nthe first character may be ^ to anchor the search to the start\nof the line, and the last character may be $ to anchor the\nsearch to the end of the line. If the search was not anchored\nto the end of the line the cursor is positioned just after the\npattern found.\n\nThe commands to create bindable widgets are similar to those in\nthe example immediately above:\n\nautoload -U history-pattern-search\nzle -N history-pattern-search-backward history-pattern-search\nzle -N history-pattern-search-forward history-pattern-search\n\nincarg Typing the keystrokes for this widget with the cursor placed on\nor to the left of an integer causes that integer to be incre-\nmented by one. With a numeric argument, the number is incre-\nmented by the amount of the argument (decremented if the numeric\nargument is negative). The shell parameter incarg may be set to\nchange the default increment to something other than one.\n\nbindkey '^X+' incarg\n\nincremental-complete-word\nThis allows incremental completion of a word. After starting\nthis command, a list of completion choices can be shown after\nevery character you type, which you can delete with ^H or DEL.\nPressing return accepts the completion so far and returns you to\nnormal editing (that is, the command line is not immediately ex-\necuted). You can hit TAB to do normal completion, ^G to abort\nback to the state when you started, and ^D to list the matches.\n\nThis works only with the new function based completion system.\n\nbindkey '^Xi' incremental-complete-word\n\ninsert-composed-char\nThis function allows you to compose characters that don't appear\non the keyboard to be inserted into the command line. The com-\nmand is followed by two keys corresponding to ASCII characters\n(there is no prompt). For accented characters, the two keys are\na base character followed by a code for the accent, while for\nother special characters the two characters together form a mne-\nmonic for the character to be inserted. The two-character codes\nare a subset of those given by RFC 1345 (see for example\nhttp://www.faqs.org/rfcs/rfc1345.html).\n\nThe function may optionally be followed by up to two characters\nwhich replace one or both of the characters read from the key-\nboard; if both characters are supplied, no input is read. For\nexample, insert-composed-char a: can be used within a widget to\ninsert an a with umlaut into the command line. This has the ad-\nvantages over use of a literal character that it is more porta-\nble.\n\nFor best results zsh should have been built with support for\nmultibyte characters (configured with --enable-multibyte); how-\never, the function works for the limited range of characters\navailable in single-byte character sets such as ISO-8859-1.\n\nThe character is converted into the local representation and in-\nserted into the command line at the cursor position. (The con-\nversion is done within the shell, using whatever facilities the\nC library provides.) With a numeric argument, the character and\nits code are previewed in the status line\n\nThe function may be run outside zle in which case it prints the\ncharacter (together with a newline) to standard output. Input\nis still read from keystrokes.\n\nSee insert-unicode-char for an alternative way of inserting Uni-\ncode characters using their hexadecimal character number.\n\nThe set of accented characters is reasonably complete up to Uni-\ncode character U+0180, the set of special characters less so.\nHowever, it is very sporadic from that point. Adding new char-\nacters is easy, however; see the function define-composed-chars.\nPlease send any additions to zsh-workers@zsh.org.\n\nThe codes for the second character when used to accent the first\nare as follows. Note that not every character can take every\naccent.\n! Grave.\n' Acute.\n> Circumflex.\n? Tilde. (This is not ~ as RFC 1345 does not assume that\ncharacter is present on the keyboard.)\n- Macron. (A horizontal bar over the base character.)\n( Breve. (A shallow dish shape over the base character.)\n. Dot above the base character, or in the case of i no dot,\nor in the case of L and l a centered dot.\n: Diaeresis (Umlaut).\nc Cedilla.\nUnderline, however there are currently no underlined\ncharacters.\n/ Stroke through the base character.\n\" Double acute (only supported on a few letters).\n; Ogonek. (A little forward facing hook at the bottom\nright of the character.)\n< Caron. (A little v over the letter.)\n0 Circle over the base character.\n2 Hook over the base character.\n9 Horn over the base character.\n\nThe most common characters from the Arabic, Cyrillic, Greek and\nHebrew alphabets are available; consult RFC 1345 for the appro-\npriate sequences. In addition, a set of two letter codes not in\nRFC 1345 are available for the double-width characters corre-\nsponding to ASCII characters from ! to ~ (0x21 to 0x7e) by pre-\nceding the character with ^, for example ^A for a double-width\nA.\n\nThe following other two-character sequences are understood.\n\nASCII characters\nThese are already present on most keyboards:\n<( Left square bracket\n// Backslash (solidus)\n)> Right square bracket\n(! Left brace (curly bracket)\n!! Vertical bar (pipe symbol)\n!) Right brace (curly bracket)\n'? Tilde\n\nSpecial letters\nCharacters found in various variants of the Latin alpha-\nbet:\nss Eszett (scharfes S)\nD-, d- Eth\nTH, th Thorn\nkk Kra\n'n 'n\nNG, ng Ng\nOI, oi Oi\nyr yr\nED ezh\n\nCurrency symbols\nCt Cent\nPd Pound sterling (also lira and others)\nCu Currency\nYe Yen\nEu Euro (N.B. not in RFC 1345)\n\nPunctuation characters\nReferences to \"right\" quotes indicate the shape (like a 9\nrather than 6) rather than their grammatical use. (For\nexample, a \"right\" low double quote is used to open quo-\ntations in German.)\n!I Inverted exclamation mark\nBB Broken vertical bar\nSE Section\nCo Copyright\n-a Spanish feminine ordinal indicator\n<< Left guillemet\n-- Soft hyphen\nRg Registered trade mark\nPI Pilcrow (paragraph)\n-o Spanish masculine ordinal indicator\n>> Right guillemet\n?I Inverted question mark\n-1 Hyphen\n-N En dash\n-M Em dash\n-3 Horizontal bar\n:3 Vertical ellipsis\n.3 Horizontal midline ellipsis\n!2 Double vertical line\n=2 Double low line\n'6 Left single quote\n'9 Right single quote\n.9 \"Right\" low quote\n9' Reversed \"right\" quote\n\"6 Left double quote\n\"9 Right double quote\n:9 \"Right\" low double quote\n9\" Reversed \"right\" double quote\n/- Dagger\n/= Double dagger\n\nMathematical symbols\nDG Degree\n-2, +-, -+\n- sign, +/- sign, -/+ sign\n2S Superscript 2\n3S Superscript 3\n1S Superscript 1\nMy Micro\n.M Middle dot\n14 Quarter\n12 Half\n34 Three quarters\n*X Multiplication\n-: Division\n%0 Per mille\nFA, TE, /0\nFor all, there exists, empty set\ndP, DE, NB\nPartial derivative, delta (increment), del (nabla)\n(-, -) Element of, contains\n*P, +Z Product, sum\n*-, Ob, Sb\nAsterisk, ring, bullet\nRT, 0(, 00\nRoot sign, proportional to, infinity\n\nOther symbols\ncS, cH, cD, cC\nCard suits: spades, hearts, diamonds, clubs\nMd, M8, M2, Mb, Mx, MX\nMusical notation: crotchet (quarter note), quaver (eighth\nnote), semiquavers (sixteenth notes), flag sign, natural\nsign, sharp sign\nFm, Ml Female, male\n\nAccents on their own\n'> Circumflex (same as caret, ^)\n'! Grave (same as backtick, `)\n', Cedilla\n': Diaeresis (Umlaut)\n'm Macron\n'' Acute\n\ninsert-files\nThis function allows you type a file pattern, and see the re-\nsults of the expansion at each step. When you hit return, all\nexpansions are inserted into the command line.\n\nbindkey '^Xf' insert-files\n\ninsert-unicode-char\nWhen first executed, the user inputs a set of hexadecimal dig-\nits. This is terminated with another call to insert-uni-\ncode-char. The digits are then turned into the corresponding\nUnicode character. For example, if the widget is bound to ^XU,\nthe character sequence `^XU 4 c ^XU' inserts L (Unicode U+004c).\n\nSee insert-composed-char for a way of inserting characters using\na two-character mnemonic.\n\nnarrow-to-region [ -p pre ] [ -P post ]\n[ -S statepm | -R statepm | [ -l lbufvar ] [ -r rbuf-\nvar ] ]\n[ -n ] [ start end ]\nnarrow-to-region-invisible\nNarrow the editable portion of the buffer to the region between\nthe cursor and the mark, which may be in either order. The re-\ngion may not be empty.\n\nnarrow-to-region may be used as a widget or called as a function\nfrom a user-defined widget; by default, the text outside the ed-\nitable area remains visible. A recursive-edit is performed and\nthe original widening status is then restored. Various options\nand arguments are available when it is called as a function.\n\nThe options -p pretext and -P posttext may be used to replace\nthe text before and after the display for the duration of the\nfunction; either or both may be an empty string.\n\nIf the option -n is also given, pretext or posttext will only be\ninserted if there is text before or after the region respec-\ntively which will be made invisible.\n\nTwo numeric arguments may be given which will be used instead of\nthe cursor and mark positions.\n\nThe option -S statepm is used to narrow according to the other\noptions while saving the original state in the parameter with\nname statepm, while the option -R statepm is used to restore the\nstate from the parameter; note in both cases the name of the pa-\nrameter is required. In the second case, other options and ar-\nguments are irrelevant. When this method is used, no recur-\nsive-edit is performed; the calling widget should call this\nfunction with the option -S, perform its own editing on the com-\nmand line or pass control to the user via `zle recursive-edit',\nthen call this function with the option -R. The argument\nstatepm must be a suitable name for an ordinary parameter, ex-\ncept that parameters beginning with the prefix ntr are re-\nserved for use within narrow-to-region. Typically the parameter\nwill be local to the calling function.\n\nThe options -l lbufvar and -r rbufvar may be used to specify pa-\nrameters where the widget will store the resulting text from the\noperation. The parameter lbufvar will contain LBUFFER and rbuf-\nvar will contain RBUFFER. Neither of these two options may be\nused with -S or -R.\n\nnarrow-to-region-invisible is a simple widget which calls nar-\nrow-to-region with arguments which replace any text outside the\nregion with `...'. It does not take any arguments.\n\nThe display is restored (and the widget returns) upon any zle\ncommand which would usually cause the line to be accepted or\naborted. Hence an additional such command is required to accept\nor abort the current line.\n\nThe return status of both widgets is zero if the line was ac-\ncepted, else non-zero.\n\nHere is a trivial example of a widget using this feature.\nlocal state\nnarrow-to-region -p $'Editing restricted region\\n' \\\n-P '' -S state\nzle recursive-edit\nnarrow-to-region -R state\n\npredict-on\nThis set of functions implements predictive typing using history\nsearch. After predict-on, typing characters causes the editor\nto look backward in the history for the first line beginning\nwith what you have typed so far. After predict-off, editing re-\nturns to normal for the line found. In fact, you often don't\neven need to use predict-off, because if the line doesn't match\nsomething in the history, adding a key performs standard comple-\ntion, and then inserts itself if no completions were found.\nHowever, editing in the middle of a line is liable to confuse\nprediction; see the toggle style below.\n\nWith the function based completion system (which is needed for\nthis), you should be able to type TAB at almost any point to ad-\nvance the cursor to the next ``interesting'' character position\n(usually the end of the current word, but sometimes somewhere in\nthe middle of the word). And of course as soon as the entire\nline is what you want, you can accept with return, without need-\ning to move the cursor to the end first.\n\nThe first time predict-on is used, it creates several additional\nwidget functions:\n\ndelete-backward-and-predict\nReplaces the backward-delete-char widget. You do not\nneed to bind this yourself.\ninsert-and-predict\nImplements predictive typing by replacing the self-insert\nwidget. You do not need to bind this yourself.\npredict-off\nTurns off predictive typing.\n\nAlthough you autoload only the predict-on function, it is neces-\nsary to create a keybinding for predict-off as well.\n\nzle -N predict-on\nzle -N predict-off\nbindkey '^X^Z' predict-on\nbindkey '^Z' predict-off\n\nread-from-minibuffer\nThis is most useful when called as a function from inside a wid-\nget, but will work correctly as a widget in its own right. It\nprompts for a value below the current command line; a value may\nbe input using all of the standard zle operations (and not\nmerely the restricted set available when executing, for example,\nexecute-named-cmd). The value is then returned to the calling\nfunction in the parameter $REPLY and the editing buffer restored\nto its previous state. If the read was aborted by a keyboard\nbreak (typically ^G), the function returns status 1 and $REPLY\nis not set.\n\nIf one argument is supplied to the function it is taken as a\nprompt, otherwise `? ' is used. If two arguments are supplied,\nthey are the prompt and the initial value of $LBUFFER, and if a\nthird argument is given it is the initial value of $RBUFFER.\nThis provides a default value and starting cursor placement.\nUpon return the entire buffer is the value of $REPLY.\n\nOne option is available: `-k num' specifies that num characters\nare to be read instead of a whole line. The line editor is not\ninvoked recursively in this case, so depending on the terminal\nsettings the input may not be visible, and only the input keys\nare placed in $REPLY, not the entire buffer. Note that unlike\nthe read builtin num must be given; there is no default.\n\nThe name is a slight misnomer, as in fact the shell's own\nminibuffer is not used. Hence it is still possible to call exe-\ncuted-named-cmd and similar functions while reading a value.\n\nreplace-argument, replace-argument-edit\nThe function replace-argument can be used to replace a command\nline argument in the current command line or, if the current\ncommand line is empty, in the last command line executed (the\nnew command line is not executed). Arguments are as delimited\nby standard shell syntax,\n\nIf a numeric argument is given, that specifies the argument to\nbe replaced. 0 means the command name, as in history expansion.\nA negative numeric argument counts backward from the last word.\n\nIf no numeric argument is given, the current argument is re-\nplaced; this is the last argument if the previous history line\nis being used.\n\nThe function prompts for a replacement argument.\n\nIf the widget contains the string edit, for example is defined\nas\n\nzle -N replace-argument-edit replace-argument\n\nthen the function presents the current value of the argument for\nediting, otherwise the editing buffer for the replacement is\ninitially empty.\n\nreplace-string, replace-pattern\nreplace-string-again, replace-pattern-again\nThe function replace-string implements three widgets. If de-\nfined under the same name as the function, it prompts for two\nstrings; the first (source) string will be replaced by the sec-\nond everywhere it occurs in the line editing buffer.\n\nIf the widget name contains the word `pattern', for example by\ndefining the widget using the command `zle -N replace-pattern\nreplace-string', then the matching is performed using zsh pat-\nterns. All zsh extended globbing patterns can be used in the\nsource string; note that unlike filename generation the pattern\ndoes not need to match an entire word, nor do glob qualifiers\nhave any effect. In addition, the replacement string can con-\ntain parameter or command substitutions. Furthermore, a `&' in\nthe replacement string will be replaced with the matched source\nstring, and a backquoted digit `\\N' will be replaced by the Nth\nparenthesised expression matched. The form `\\{N}' may be used\nto protect the digit from following digits.\n\nIf the widget instead contains the word `regex' (or `regexp'),\nthen the matching is performed using regular expressions, re-\nspecting the setting of the option REMATCHPCRE (see the de-\nscription of the function regexp-replace below). The special\nreplacement facilities described above for pattern matching are\navailable.\n\nBy default the previous source or replacement string will not be\noffered for editing. However, this feature can be activated by\nsetting the style edit-previous in the context :zle:widget (for\nexample, :zle:replace-string) to true. In addition, a positive\nnumeric argument forces the previous values to be offered, a\nnegative or zero argument forces them not to be.\n\nThe function replace-string-again can be used to repeat the pre-\nvious replacement; no prompting is done. As with re-\nplace-string, if the name of the widget contains the word `pat-\ntern' or `regex', pattern or regular expression matching is per-\nformed, else a literal string replacement. Note that the previ-\nous source and replacement text are the same whether pattern,\nregular expression or string matching is used.\n\nIn addition, replace-string shows the previous replacement above\nthe prompt, so long as there was one during the current session;\nif the source string is empty, that replacement will be repeated\nwithout the widget prompting for a replacement string.\n\nFor example, starting from the line:\n\nprint This line contains fan and fond\n\nand invoking replace-pattern with the source string `f(?)n' and\nthe replacement string `c\\1r' produces the not very useful line:\n\nprint This line contains car and cord\n\nThe range of the replacement string can be limited by using the\nnarrow-to-region-invisible widget. One limitation of the cur-\nrent version is that undo will cycle through changes to the re-\nplacement and source strings before undoing the replacement it-\nself.\n\nsend-invisible\nThis is similar to read-from-minibuffer in that it may be called\nas a function from a widget or as a widget of its own, and in-\nteractively reads input from the keyboard. However, the input\nbeing typed is concealed and a string of asterisks (`*') is\nshown instead. The value is saved in the parameter $INVISIBLE\nto which a reference is inserted into the editing buffer at the\nrestored cursor position. If the read was aborted by a keyboard\nbreak (typically ^G) or another escape from editing such as\npush-line, $INVISIBLE is set to empty and the original buffer is\nrestored unchanged.\n\nIf one argument is supplied to the function it is taken as a\nprompt, otherwise `Non-echoed text: ' is used (as in emacs). If\na second and third argument are supplied they are used to begin\nand end the reference to $INVISIBLE that is inserted into the\nbuffer. The default is to open with ${, then INVISIBLE, and\nclose with }, but many other effects are possible.\n\nsmart-insert-last-word\nThis function may replace the insert-last-word widget, like so:\n\nzle -N insert-last-word smart-insert-last-word\n\nWith a numeric argument, or when passed command line arguments\nin a call from another widget, it behaves like insert-last-word,\nexcept that words in comments are ignored when INTERACTIVECOM-\nMENTS is set.\n\nOtherwise, the rightmost ``interesting'' word from the previous\ncommand is found and inserted. The default definition of ``in-\nteresting'' is that the word contains at least one alphabetic\ncharacter, slash, or backslash. This definition may be overrid-\nden by use of the match style. The context used to look up the\nstyle is the widget name, so usually the context is :in-\nsert-last-word. However, you can bind this function to differ-\nent widgets to use different patterns:\n\nzle -N insert-last-assignment smart-insert-last-word\nzstyle :insert-last-assignment match '[[:alpha:]][][[:alnum:]]#=*'\nbindkey '\\e=' insert-last-assignment\n\nIf no interesting word is found and the auto-previous style is\nset to a true value, the search continues upward through the\nhistory. When auto-previous is unset or false (the default),\nthe widget must be invoked repeatedly in order to search earlier\nhistory lines.\n\ntranspose-lines\nOnly useful with a multi-line editing buffer; the lines here are\nlines within the current on-screen buffer, not history lines.\nThe effect is similar to the function of the same name in Emacs.\n\nTranspose the current line with the previous line and move the\ncursor to the start of the next line. Repeating this (which can\nbe done by providing a positive numeric argument) has the effect\nof moving the line above the cursor down by a number of lines.\n\nWith a negative numeric argument, requires two lines above the\ncursor. These two lines are transposed and the cursor moved to\nthe start of the previous line. Using a numeric argument less\nthan -1 has the effect of moving the line above the cursor up by\nminus that number of lines.\n\nurl-quote-magic\nThis widget replaces the built-in self-insert to make it easier\nto type URLs as command line arguments. As you type, the input\ncharacter is analyzed and, if it may need quoting, the current\nword is checked for a URI scheme. If one is found and the cur-\nrent word is not already in quotes, a backslash is inserted be-\nfore the input character.\n\nStyles to control quoting behavior:\n\nurl-metas\nThis style is looked up in the context\n`:url-quote-magic:scheme' (where scheme is that of the\ncurrent URL, e.g. \"ftp\"). The value is a string listing\nthe characters to be treated as globbing metacharacters\nwhen appearing in a URL using that scheme. The default\nis to quote all zsh extended globbing characters, exclud-\ning '<' and '>' but including braces (as in brace expan-\nsion). See also url-seps.\n\nurl-seps\nLike url-metas, but lists characters that should be con-\nsidered command separators, redirections, history refer-\nences, etc. The default is to quote the standard set of\nshell separators, excluding those that overlap with the\nextended globbing characters, but including '<' and '>'\nand the first character of $histchars.\n\nurl-globbers\nThis style is looked up in the context\n`:url-quote-magic'. The values form a list of command\nnames that are expected to do their own globbing on the\nURL string. This implies that they are aliased to use\nthe `noglob' modifier. When the first word on the line\nmatches one of the values and the URL refers to a local\nfile (see url-local-schema), only the url-seps characters\nare quoted; the url-metas are left alone, allowing them\nto affect command-line parsing, completion, etc. The de-\nfault values are a literal `noglob' plus (when the\nzsh/parameter module is available) any commands aliased\nto the helper function `urlglobber' or its alias\n`globurl'.\n\nurl-local-schema\nThis style is always looked up in the context `:urlglob-\nber', even though it is used by both url-quote-magic and\nurlglobber. The values form a list of URI schema that\nshould be treated as referring to local files by their\nreal local path names, as opposed to files which are\nspecified relative to a web-server-defined document root.\nThe defaults are \"ftp\" and \"file\".\n\nurl-other-schema\nLike url-local-schema, but lists all other URI schema\nupon which urlglobber and url-quote-magic should act. If\nthe URI on the command line does not have a scheme ap-\npearing either in this list or in url-local-schema, it is\nnot magically quoted. The default values are \"http\",\n\"https\", and \"ftp\". When a scheme appears both here and\nin url-local-schema, it is quoted differently depending\non whether the command name appears in url-globbers.\n\nLoading url-quote-magic also defines a helper function `urlglob-\nber' and aliases `globurl' to `noglob urlglobber'. This func-\ntion takes a local URL apart, attempts to pattern-match the lo-\ncal file portion of the URL path, and then puts the results back\ninto URL format again.\n\nvi-pipe\nThis function reads a movement command from the keyboard and\nthen prompts for an external command. The part of the buffer\ncovered by the movement is piped to the external command and\nthen replaced by the command's output. If the movement command\nis bound to vi-pipe, the current line is used.\n\nThe function serves as an example for reading a vi movement com-\nmand from within a user-defined widget.\n\nwhich-command\nThis function is a drop-in replacement for the builtin widget\nwhich-command. It has enhanced behaviour, in that it correctly\ndetects whether or not the command word needs to be expanded as\nan alias; if so, it continues tracing the command word from the\nexpanded alias until it reaches the command that will be exe-\ncuted.\n\nThe style whence is available in the context :zle:$WIDGET; this\nmay be set to an array to give the command and options that will\nbe used to investigate the command word found. The default is\nwhence -c.\n\nzcalc-auto-insert\nThis function is useful together with the zcalc function de-\nscribed in the section Mathematical Functions. It should be\nbound to a key representing a binary operator such as `+', `-',\n`*' or `/'. When running in zcalc, if the key occurs at the\nstart of the line or immediately following an open parenthesis,\nthe text \"ans \" is inserted before the representation of the key\nitself. This allows easy use of the answer from the previous\ncalculation in the current line. The text to be inserted before\nthe symbol typed can be modified by setting the variable\nZCALCAUTOINSERTPREFIX.\n\nHence, for example, typing `+12' followed by return adds 12 to\nthe previous result.\n\nIf zcalc is in RPN mode (-r option) the effect of this binding\nis automatically suppressed as operators alone on a line are\nmeaningful.\n\nWhen not in zcalc, the key simply inserts the symbol itself.\n\nUtility Functions\nThese functions are useful in constructing widgets. They should be\nloaded with `autoload -U function' and called as indicated from\nuser-defined widgets.\n\nsplit-shell-arguments\nThis function splits the line currently being edited into shell\narguments and whitespace. The result is stored in the array re-\nply. The array contains all the parts of the line in order,\nstarting with any whitespace before the first argument, and fin-\nishing with any whitespace after the last argument. Hence (so\nlong as the option KSHARRAYS is not set) whitespace is given by\nodd indices in the array and arguments by even indices. Note\nthat no stripping of quotes is done; joining together all the\nelements of reply in order is guaranteed to produce the original\nline.\n\nThe parameter REPLY is set to the index of the word in reply\nwhich contains the character after the cursor, where the first\nelement has index 1. The parameter REPLY2 is set to the index\nof the character under the cursor in that word, where the first\ncharacter has index 1.\n\nHence reply, REPLY and REPLY2 should all be made local to the\nenclosing function.\n\nSee the function modify-current-argument, described below, for\nan example of how to call this function.\n\nmodify-current-argument [ expr-using-$ARG | func ]\nThis function provides a simple method of allowing user-defined\nwidgets to modify the command line argument under the cursor (or\nimmediately to the left of the cursor if the cursor is between\narguments).\n\nThe argument can be an expression which when evaluated operates\non the shell parameter ARG, which will have been set to the com-\nmand line argument under the cursor. The expression should be\nsuitably quoted to prevent it being evaluated too early.\n\nAlternatively, if the argument does not contain the string ARG,\nit is assumed to be a shell function, to which the current com-\nmand line argument is passed as the only argument. The function\nshould set the variable REPLY to the new value for the command\nline argument. If the function returns non-zero status, so does\nthe calling function.\n\nFor example, a user-defined widget containing the following code\nconverts the characters in the argument under the cursor into\nall upper case:\n\nmodify-current-argument '${(U)ARG}'\n\nThe following strips any quoting from the current word (whether\nbackslashes or one of the styles of quotes), and replaces it\nwith single quoting throughout:\n\nmodify-current-argument '${(qq)${(Q)ARG}}'\n\nThe following performs directory expansion on the command line\nargument and replaces it by the absolute path:\n\nexpand-dir() {\nREPLY=${~1}\nREPLY=${REPLY:a}\n}\nmodify-current-argument expand-dir\n\nIn practice the function expand-dir would probably not be de-\nfined within the widget where modify-current-argument is called.\n\nStyles\nThe behavior of several of the above widgets can be controlled by the\nuse of the zstyle mechanism. In particular, widgets that interact with\nthe completion system pass along their context to any completions that\nthey invoke.\n\nbreak-keys\nThis style is used by the incremental-complete-word widget. Its\nvalue should be a pattern, and all keys matching this pattern\nwill cause the widget to stop incremental completion without the\nkey having any further effect. Like all styles used directly by\nincremental-complete-word, this style is looked up using the\ncontext `:incremental'.\n\ncompleter\nThe incremental-complete-word and insert-and-predict widgets set\nup their top-level context name before calling completion. This\nallows one to define different sets of completer functions for\nnormal completion and for these widgets. For example, to use\ncompletion, approximation and correction for normal completion,\ncompletion and correction for incremental completion and only\ncompletion for prediction one could use:\n\nzstyle ':completion:*' completer \\\ncomplete correct approximate\nzstyle ':completion:incremental:*' completer \\\ncomplete correct\nzstyle ':completion:predict:*' completer \\\ncomplete\n\nIt is a good idea to restrict the completers used in prediction,\nbecause they may be automatically invoked as you type. The\nlist and menu completers should never be used with prediction.\nThe approximate, correct, expand, and match completers may\nbe used, but be aware that they may change characters anywhere\nin the word behind the cursor, so you need to watch carefully\nthat the result is what you intended.\n\ncursor The insert-and-predict widget uses this style, in the context\n`:predict', to decide where to place the cursor after completion\nhas been tried. Values are:\n\ncomplete\nThe cursor is left where it was when completion finished,\nbut only if it is after a character equal to the one just\ninserted by the user. If it is after another character,\nthis value is the same as `key'.\n\nkey The cursor is left after the nth occurrence of the char-\nacter just inserted, where n is the number of times that\ncharacter appeared in the word before completion was at-\ntempted. In short, this has the effect of leaving the\ncursor after the character just typed even if the comple-\ntion code found out that no other characters need to be\ninserted at that position.\n\nAny other value for this style unconditionally leaves the cursor\nat the position where the completion code left it.\n\nlist When using the incremental-complete-word widget, this style says\nif the matches should be listed on every key press (if they fit\non the screen). Use the context prefix `:completion:incremen-\ntal'.\n\nThe insert-and-predict widget uses this style to decide if the\ncompletion should be shown even if there is only one possible\ncompletion. This is done if the value of this style is the\nstring always. In this case the context is `:predict' (not\n`:completion:predict').\n\nmatch This style is used by smart-insert-last-word to provide a pat-\ntern (using full EXTENDEDGLOB syntax) that matches an interest-\ning word. The context is the name of the widget to which\nsmart-insert-last-word is bound (see above). The default behav-\nior of smart-insert-last-word is equivalent to:\n\nzstyle :insert-last-word match '*[[:alpha:]/\\\\]*'\n\nHowever, you might want to include words that contain spaces:\n\nzstyle :insert-last-word match '*[[:alpha:][:space:]/\\\\]*'\n\nOr include numbers as long as the word is at least two charac-\nters long:\n\nzstyle :insert-last-word match '*([[:digit:]]?|[[:alpha:]/\\\\])*'\n\nThe above example causes redirections like \"2>\" to be included.\n\nprompt The incremental-complete-word widget shows the value of this\nstyle in the status line during incremental completion. The\nstring value may contain any of the following substrings in the\nmanner of the PS1 and other prompt parameters:\n\n%c Replaced by the name of the completer function that gen-\nerated the matches (without the leading underscore).\n\n%l When the list style is set, replaced by `...' if the list\nof matches is too long to fit on the screen and with an\nempty string otherwise. If the list style is `false' or\nnot set, `%l' is always removed.\n\n%n Replaced by the number of matches generated.\n\n%s Replaced by `-no match-', `-no prefix-', or an empty\nstring if there is no completion matching the word on the\nline, if the matches have no common prefix different from\nthe word on the line, or if there is such a common pre-\nfix, respectively.\n\n%u Replaced by the unambiguous part of all matches, if there\nis any, and if it is different from the word on the line.\n\nLike `break-keys', this uses the `:incremental' context.\n\nstop-keys\nThis style is used by the incremental-complete-word widget. Its\nvalue is treated similarly to the one for the break-keys style\n(and uses the same context: `:incremental'). However, in this\ncase all keys matching the pattern given as its value will stop\nincremental completion and will then execute their usual func-\ntion.\n\ntoggle This boolean style is used by predict-on and its related widgets\nin the context `:predict'. If set to one of the standard `true'\nvalues, predictive typing is automatically toggled off in situa-\ntions where it is unlikely to be useful, such as when editing a\nmulti-line buffer or after moving into the middle of a line and\nthen deleting a character. The default is to leave prediction\nturned on until an explicit call to predict-off.\n\nverbose\nThis boolean style is used by predict-on and its related widgets\nin the context `:predict'. If set to one of the standard `true'\nvalues, these widgets display a message below the prompt when\nthe predictive state is toggled. This is most useful in combi-\nnation with the toggle style. The default does not display\nthese messages.\n\nwidget This style is similar to the command style: For widget functions\nthat use zle to call other widgets, this style can sometimes be\nused to override the widget which is called. The context for\nthis style is the name of the calling widget (not the name of\nthe calling function, because one function may be bound to mul-\ntiple widget names).\n\nzstyle :copy-earlier-word widget smart-insert-last-word\n\nCheck the documentation for the calling widget or function to\ndetermine whether the widget style is used.\n", "subsections": [] }, "EXCEPTION HANDLING": { "content": "Two functions are provided to enable zsh to provide exception handling\nin a form that should be familiar from other languages.\n\nthrow exception\nThe function throw throws the named exception. The name is an\narbitrary string and is only used by the throw and catch func-\ntions. An exception is for the most part treated the same as a\nshell error, i.e. an unhandled exception will cause the shell to\nabort all processing in a function or script and to return to\nthe top level in an interactive shell.\n\ncatch exception-pattern\nThe function catch returns status zero if an exception was\nthrown and the pattern exception-pattern matches its name. Oth-\nerwise it returns status 1. exception-pattern is a standard\nshell pattern, respecting the current setting of the EX-\nTENDEDGLOB option. An alias catch is also defined to prevent\nthe argument to the function from matching filenames, so pat-\nterns may be used unquoted. Note that as exceptions are not\nfundamentally different from other shell errors it is possible\nto catch shell errors by using an empty string as the exception\nname. The shell variable CAUGHT is set by catch to the name of\nthe exception caught. It is possible to rethrow an exception by\ncalling the throw function again once an exception has been\ncaught.\n\nThe functions are designed to be used together with the always con-\nstruct described in zshmisc(1). This is important as only this con-\nstruct provides the required support for exceptions. A typical example\nis as follows.\n\n{\n# \"try\" block\n# ... nested code here calls \"throw MyExcept\"\n} always {\n# \"always\" block\nif catch MyExcept; then\nprint \"Caught exception MyExcept\"\nelif catch ''; then\nprint \"Caught a shell error. Propagating...\"\nthrow ''\nfi\n# Other exceptions are not handled but may be caught further\n# up the call stack.\n}\n\nIf all exceptions should be caught, the following idiom might be\npreferable.\n\n{\n# ... nested code here throws an exception\n} always {\nif catch *; then\ncase $CAUGHT in\n(MyExcept)\nprint \"Caught my own exception\"\n;;\n(*)\nprint \"Caught some other exception\"\n;;\nesac\nfi\n}\n\nIn common with exception handling in other languages, the exception may\nbe thrown by code deeply nested inside the `try' block. However, note\nthat it must be thrown inside the current shell, not in a subshell\nforked for a pipeline, parenthesised current-shell construct, or some\nform of command or process substitution.\n\nThe system internally uses the shell variable EXCEPTION to record the\nname of the exception between throwing and catching. One drawback of\nthis scheme is that if the exception is not handled the variable EXCEP-\nTION remains set and may be incorrectly recognised as the name of an\nexception if a shell error subsequently occurs. Adding unset EXCEPTION\nat the start of the outermost layer of any code that uses exception\nhandling will eliminate this problem.\n", "subsections": [] }, "MIME FUNCTIONS": { "content": "Three functions are available to provide handling of files recognised\nby extension, for example to dispatch a file text.ps when executed as a\ncommand to an appropriate viewer.\n\nzsh-mime-setup [ -fv ] [ -l [ suffix ... ] ]\nzsh-mime-handler [ -l ] command argument ...\nThese two functions use the files ~/.mime.types and\n/etc/mime.types, which associate types and extensions, as well\nas ~/.mailcap and /etc/mailcap files, which associate types and\nthe programs that handle them. These are provided on many sys-\ntems with the Multimedia Internet Mail Extensions.\n\nTo enable the system, the function zsh-mime-setup should be au-\ntoloaded and run. This allows files with extensions to be\ntreated as executable; such files be completed by the function\ncompletion system. The function zsh-mime-handler should not\nneed to be called by the user.\n\nThe system works by setting up suffix aliases with `alias -s'.\nSuffix aliases already installed by the user will not be over-\nwritten.\n\nFor suffixes defined in lower case, upper case variants will\nalso automatically be handled (e.g. PDF is automatically handled\nif handling for the suffix pdf is defined), but not vice versa.\n\nRepeated calls to zsh-mime-setup do not override the existing\nmapping between suffixes and executable files unless the option\n-f is given. Note, however, that this does not override exist-\ning suffix aliases assigned to handlers other than zsh-mime-han-\ndler.\n\nCalling zsh-mime-setup with the option -l lists the existing\nmappings without altering them. Suffixes to list (which may\ncontain pattern characters that should be quoted from immediate\ninterpretation on the command line) may be given as additional\narguments, otherwise all suffixes are listed.\n\nCalling zsh-mime-setup with the option -v causes verbose output\nto be shown during the setup operation.\n\nThe system respects the mailcap flags needsterminal and copi-\nousoutput, see mailcap(4).\n\nThe functions use the following styles, which are defined with\nthe zstyle builtin command (see zshmodules(1)). They should be\ndefined before zsh-mime-setup is run. The contexts used all\nstart with :mime:, with additional components in some cases. It\nis recommended that a trailing * (suitably quoted) be appended\nto style patterns in case the system is extended in future.\nSome examples are given below.\n\nFor files that have multiple suffixes, e.g. .pdf.gz, where the\ncontext includes the suffix it will be looked up starting with\nthe longest possible suffix until a match for the style is\nfound. For example, if .pdf.gz produces a match for the han-\ndler, that will be used; otherwise the handler for .gz will be\nused. Note that, owing to the way suffix aliases work, it is\nalways required that there be a handler for the shortest possi-\nble suffix, so in this example .pdf.gz can only be handled if\n.gz is also handled (though not necessarily in the same way).\nAlternatively, if no handling for .gz on its own is needed, sim-\nply adding the command\n\nalias -s gz=zsh-mime-handler\n\nto the initialisation code is sufficient; .gz will not be han-\ndled on its own, but may be in combination with other suffixes.\n\ncurrent-shell\nIf this boolean style is true, the mailcap handler for\nthe context in question is run using the eval builtin in-\nstead of by starting a new sh process. This is more ef-\nficient, but may not work in the occasional cases where\nthe mailcap handler uses strict POSIX syntax.\n\ndisown If this boolean style is true, mailcap handlers started\nin the background will be disowned, i.e. not subject to\njob control within the parent shell. Such handlers\nnearly always produce their own windows, so the only\nlikely harmful side effect of setting the style is that\nit becomes harder to kill jobs from within the shell.\n\nexecute-as-is\nThis style gives a list of patterns to be matched against\nfiles passed for execution with a handler program. If\nthe file matches the pattern, the entire command line is\nexecuted in its current form, with no handler. This is\nuseful for files which might have suffixes but nonethe-\nless be executable in their own right. If the style is\nnot set, the pattern *(*) *(/) is used; hence executable\nfiles are executed directly and not passed to a handler,\nand the option AUTOCD may be used to change to directo-\nries that happen to have MIME suffixes.\n\nexecute-never\nThis style is useful in combination with execute-as-is.\nIt is set to an array of patterns corresponding to full\npaths to files that should never be treated as exe-\ncutable, even if the file passed to the MIME handler\nmatches execute-as-is. This is useful for file systems\nthat don't handle execute permission or that contain exe-\ncutables from another operating system. For example, if\n/mnt/windows is a Windows mount, then\n\nzstyle ':mime:*' execute-never '/mnt/windows/*'\n\nwill ensure that any files found in that area will be ex-\necuted as MIME types even if they are executable. As\nthis example shows, the complete file name is matched\nagainst the pattern, regardless of how the file was\npassed to the handler. The file is resolved to a full\npath using the :P modifier described in the subsection\nModifiers in zshexpn(1); this means that symbolic links\nare resolved where possible, so that links into other\nfile systems behave in the correct fashion.\n\nfile-path\nUsed if the style find-file-in-path is true for the same\ncontext. Set to an array of directories that are used\nfor searching for the file to be handled; the default is\nthe command path given by the special parameter path.\nThe shell option PATHDIRS is respected; if that is set,\nthe appropriate path will be searched even if the name of\nthe file to be handled as it appears on the command line\ncontains a `/'. The full context is :mime:.suffix:, as\ndescribed for the style handler.\n\nfind-file-in-path\nIf set, allows files whose names do not contain absolute\npaths to be searched for in the command path or the path\nspecified by the file-path style. If the file is not\nfound in the path, it is looked for locally (whether or\nnot the current directory is in the path); if it is not\nfound locally, the handler will abort unless the han-\ndle-nonexistent style is set. Files found in the path\nare tested as described for the style execute-as-is. The\nfull context is :mime:.suffix:, as described for the\nstyle handler.\n\nflags Defines flags to go with a handler; the context is as for\nthe handler style, and the format is as for the flags in\nmailcap.\n\nhandle-nonexistent\nBy default, arguments that don't correspond to files are\nnot passed to the MIME handler in order to prevent it\nfrom intercepting commands found in the path that happen\nto have suffixes. This style may be set to an array of\nextended glob patterns for arguments that will be passed\nto the handler even if they don't exist. If it is not\nexplicitly set it defaults to [[:alpha:]]#:/* which al-\nlows URLs to be passed to the MIME handler even though\nthey don't exist in that format in the file system. The\nfull context is :mime:.suffix:, as described for the\nstyle handler.\n\nhandler\nSpecifies a handler for a suffix; the suffix is given by\nthe context as :mime:.suffix:, and the format of the han-\ndler is exactly that in mailcap. Note in particular the\n`.' and trailing colon to distinguish this use of the\ncontext. This overrides any handler specified by the\nmailcap files. If the handler requires a terminal, the\nflags style should be set to include the word needstermi-\nnal, or if the output is to be displayed through a pager\n(but not if the handler is itself a pager), it should in-\nclude copiousoutput.\n\nmailcap\nA list of files in the format of ~/.mailcap and\n/etc/mailcap to be read during setup, replacing the de-\nfault list which consists of those two files. The con-\ntext is :mime:. A + in the list will be replaced by the\ndefault files.\n\nmailcap-priorities\nThis style is used to resolve multiple mailcap entries\nfor the same MIME type. It consists of an array of the\nfollowing elements, in descending order of priority;\nlater entries will be used if earlier entries are unable\nto resolve the entries being compared. If none of the\ntests resolve the entries, the first entry encountered is\nretained.\n\nfiles The order of files (entries in the mailcap style)\nread. Earlier files are preferred. (Note this\ndoes not resolve entries in the same file.)\n\npriority\nThe priority flag from the mailcap entry. The\npriority is an integer from 0 to 9 with the de-\nfault value being 5.\n\nflags The test given by the mailcap-prio-flags option is\nused to resolve entries.\n\nplace Later entries are preferred; as the entries are\nstrictly ordered, this test always succeeds.\n\nNote that as this style is handled during initialisation,\nthe context is always :mime:, with no discrimination by\nsuffix.\n\nmailcap-prio-flags\nThis style is used when the keyword flags is encountered\nin the list of tests specified by the mailcap-priorities\nstyle. It should be set to a list of patterns, each of\nwhich is tested against the flags specified in the mail-\ncap entry (in other words, the sets of assignments found\nwith some entries in the mailcap file). Earlier patterns\nin the list are preferred to later ones, and matched pat-\nterns are preferred to unmatched ones.\n\nmime-types\nA list of files in the format of ~/.mime.types and\n/etc/mime.types to be read during setup, replacing the\ndefault list which consists of those two files. The con-\ntext is :mime:. A + in the list will be replaced by the\ndefault files.\n\nnever-background\nIf this boolean style is set, the handler for the given\ncontext is always run in the foreground, even if the\nflags provided in the mailcap entry suggest it need not\nbe (for example, it doesn't require a terminal).\n\npager If set, will be used instead of $PAGER or more to handle\nsuffixes where the copiousoutput flag is set. The con-\ntext is as for handler, i.e. :mime:.suffix: for handling\na file with the given suffix.\n\nExamples:\n\nzstyle ':mime:*' mailcap ~/.mailcap /usr/local/etc/mailcap\nzstyle ':mime:.txt:' handler less %s\nzstyle ':mime:.txt:' flags needsterminal\n\nWhen zsh-mime-setup is subsequently run, it will look for mail-\ncap entries in the two files given. Files of suffix .txt will\nbe handled by running `less file.txt'. The flag needsterminal\nis set to show that this program must run attached to a termi-\nnal.\n\nAs there are several steps to dispatching a command, the follow-\ning should be checked if attempting to execute a file by exten-\nsion .ext does not have the expected effect.\n\nThe command `alias -s ext' should show `ps=zsh-mime-handler'.\nIf it shows something else, another suffix alias was already in-\nstalled and was not overwritten. If it shows nothing, no han-\ndler was installed: this is most likely because no handler was\nfound in the .mime.types and mailcap combination for .ext files.\nIn that case, appropriate handling should be added to\n~/.mime.types and mailcap.\n\nIf the extension is handled by zsh-mime-handler but the file is\nnot opened correctly, either the handler defined for the type is\nincorrect, or the flags associated with it are in appropriate.\nRunning zsh-mime-setup -l will show the handler and, if there\nare any, the flags. A %s in the handler is replaced by the file\n(suitably quoted if necessary). Check that the handler program\nlisted lists and can be run in the way shown. Also check that\nthe flags needsterminal or copiousoutput are set if the handler\nneeds to be run under a terminal; the second flag is used if the\noutput should be sent to a pager. An example of a suitable\nmailcap entry for such a program is:\n\ntext/html; /usr/bin/lynx '%s'; needsterminal\n\nRunning `zsh-mime-handler -l command line' prints the command\nline that would be executed, simplified to remove the effect of\nany flags, and quoted so that the output can be run as a com-\nplete zsh command line. This is used by the completion system\nto decide how to complete after a file handled by\nzsh-mime-setup.\n\npick-web-browser\nThis function is separate from the two MIME functions described\nabove and can be assigned directly to a suffix:\n\nautoload -U pick-web-browser\nalias -s html=pick-web-browser\n\nIt is provided as an intelligent front end to dispatch a web\nbrowser. It may be run as either a function or a shell script.\nThe status 255 is returned if no browser could be started.\n\nVarious styles are available to customize the choice of\nbrowsers:\n\nbrowser-style\nThe value of the style is an array giving preferences in\ndecreasing order for the type of browser to use. The\nvalues of elements may be\n\nrunning\nUse a GUI browser that is already running when an\nX Window display is available. The browsers\nlisted in the x-browsers style are tried in order\nuntil one is found; if it is, the file will be\ndisplayed in that browser, so the user may need to\ncheck whether it has appeared. If no running\nbrowser is found, one is not started. Browsers\nother than Firefox, Opera and Konqueror are as-\nsumed to understand the Mozilla syntax for opening\na URL remotely.\n\nx Start a new GUI browser when an X Window display\nis available. Search for the availability of one\nof the browsers listed in the x-browsers style and\nstart the first one that is found. No check is\nmade for an already running browser.\n\ntty Start a terminal-based browser. Search for the\navailability of one of the browsers listed in the\ntty-browsers style and start the first one that is\nfound.\n\nIf the style is not set the default running x tty is\nused.\n\nx-browsers\nAn array in decreasing order of preference of browsers to\nuse when running under the X Window System. The array\nconsists of the command name under which to start the\nbrowser. They are looked up in the context :mime: (which\nmay be extended in future, so appending `*' is recom-\nmended). For example,\n\nzstyle ':mime:*' x-browsers opera konqueror firefox\n\nspecifies that pick-web-browser should first look for a\nrunning instance of Opera, Konqueror or Firefox, in that\norder, and if it fails to find any should attempt to\nstart Opera. The default is firefox mozilla netscape\nopera konqueror.\n\ntty-browsers\nAn array similar to x-browsers, except that it gives\nbrowsers to use when no X Window display is available.\nThe default is elinks links lynx.\n\ncommand\nIf it is set this style is used to pick the command used\nto open a page for a browser. The context is\n:mime:browser:new:$browser: to start a new browser or\n:mime:browser:running:$browser: to open a URL in a\nbrowser already running on the current X display, where\n$browser is the value matched in the x-browsers or\ntty-browsers style. The escape sequence %b in the\nstyle's value will be replaced by the browser, while %u\nwill be replaced by the URL. If the style is not set,\nthe default for all new instances is equivalent to %b %u\nand the defaults for using running browsers are equiva-\nlent to the values kfmclient openURL %u for Konqueror,\nfirefox -new-tab %u for Firefox, opera -newpage %u for\nOpera, and %b -remote \"openUrl(%u)\" for all others.\n", "subsections": [] }, "MATHEMATICAL FUNCTIONS": { "content": "zcalc [ -erf ] [ expression ... ]\nA reasonably powerful calculator based on zsh's arithmetic eval-\nuation facility. The syntax is similar to that of formulae in\nmost programming languages; see the section `Arithmetic Evalua-\ntion' in zshmisc(1) for details.\n\nNon-programmers should note that, as in many other programming\nlanguages, expressions involving only integers (whether con-\nstants without a `.', variables containing such constants as\nstrings, or variables declared to be integers) are by default\nevaluated using integer arithmetic, which is not how an ordinary\ndesk calculator operates. To force floating point operation,\npass the option -f; see further notes below.\n\nIf the file ~/.zcalcrc exists it will be sourced inside the\nfunction once it is set up and about to process the command\nline. This can be used, for example, to set shell options; emu-\nlate -L zsh and setopt extendedglob are in effect at this point.\nAny failure to source the file if it exists is treated as fatal.\nAs with other initialisation files, the directory $ZDOTDIR is\nused instead of $HOME if it is set.\n\nThe mathematical library zsh/mathfunc will be loaded if it is\navailable; see the section `The zsh/mathfunc Module' in zshmod-\nules(1). The mathematical functions correspond to the raw sys-\ntem libraries, so trigonometric functions are evaluated using\nradians, and so on.\n\nEach line typed is evaluated as an expression. The prompt shows\na number, which corresponds to a positional parameter where the\nresult of that calculation is stored. For example, the result\nof the calculation on the line preceded by `4> ' is available as\n$4. The last value calculated is available as ans. Full com-\nmand line editing, including the history of previous calcula-\ntions, is available; the history is saved in the file\n~/.zcalchistory. To exit, enter a blank line or type `:q' on\nits own (`q' is allowed for historical compatibility).\n\nA line ending with a single backslash is treated in the same\nfashion as it is in command line editing: the backslash is re-\nmoved, the function prompts for more input (the prompt is pre-\nceded by `...' to indicate this), and the lines are combined\ninto one to get the final result. In addition, if the input so\nfar contains more open than close parentheses zcalc will prompt\nfor more input.\n\nIf arguments are given to zcalc on start up, they are used to\nprime the first few positional parameters. A visual indication\nof this is given when the calculator starts.\n\nThe constants PI (3.14159...) and E (2.71828...) are provided.\nParameter assignment is possible, but note that all parameters\nwill be put into the global namespace unless the :local special\ncommand is used. The function creates local variables whose\nnames start with , so users should avoid doing so. The vari-\nables ans (the last answer) and stack (the stack in RPN mode)\nmay be referred to directly; stack is an array but elements of\nit are numeric. Various other special variables are used lo-\ncally with their standard meaning, for example compcontext,\nmatch, mbegin, mend, psvar.\n\nThe output base can be initialised by passing the option\n`-#base', for example `zcalc -#16' (the `#' may have to be\nquoted, depending on the globbing options set).\n\nIf the option `-e' is set, the function runs non-interactively:\nthe arguments are treated as expressions to be evaluated as if\nentered interactively line by line.\n\nIf the option `-f' is set, all numbers are treated as floating\npoint, hence for example the expression `3/4' evaluates to 0.75\nrather than 0. Options must appear in separate words.\n\nIf the option `-r' is set, RPN (Reverse Polish Notation) mode is\nentered. This has various additional properties:\nStack Evaluated values are maintained in a stack; this is con-\ntained in an array named stack with the most recent value\nin ${stack[1]}.\n\nOperators and functions\nIf the line entered matches an operator (+, -, *, /, ,\n^, | or &) or a function supplied by the zsh/mathfunc li-\nbrary, the bottom element or elements of the stack are\npopped to use as the argument or arguments. The higher\nelements of stack (least recent) are used as earlier ar-\nguments. The result is then pushed into ${stack[1]}.\n\nExpressions\nOther expressions are evaluated normally, printed, and\nadded to the stack as numeric values. The syntax within\nexpressions on a single line is normal shell arithmetic\n(not RPN).\n\nStack listing\nIf an integer follows the option -r with no space, then\non every evaluation that many elements of the stack,\nwhere available, are printed instead of just the most re-\ncent result. Hence, for example, zcalc -r4 shows\n$stack[4] to $stack[1] each time results are printed.\n\nDuplication: =\nThe pseudo-operator = causes the most recent element of\nthe stack to be duplicated onto the stack.\n\npop The pseudo-function pop causes the most recent element of\nthe stack to be popped. A `>' on its own has the same\neffect.\n\n>ident The expression > followed (with no space) by a shell\nidentifier causes the most recent element of the stack to\nbe popped and assigned to the variable with that name.\nThe variable is local to the zcalc function.\n\n in the standard zcalc prompt) is\nput on the stack.\n\nExchange: xy\nThe pseudo-function xy causes the most recent two ele-\nments of the stack to be exchanged. `<>' has the same\neffect.\n\nThe prompt is configurable via the parameter ZCALCPROMPT, which\nundergoes standard prompt expansion. The index of the current\nentry is stored locally in the first element of the array psvar,\nwhich can be referred to in ZCALCPROMPT as `%1v'. The default\nprompt is `%1v> '.\n\nThe variable ZCALCACTIVE is set within the function and can be\ntested by nested functions; it has the value rpn if RPN mode is\nactive, else 1.\n\nA few special commands are available; these are introduced by a\ncolon. For backward compatibility, the colon may be omitted for\ncertain commands. Completion is available if compinit has been\nrun.\n\nThe output precision may be specified within zcalc by special\ncommands familiar from many calculators.\n:norm The default output format. It corresponds to the printf\n%g specification. Typically this shows six decimal dig-\nits.\n\n:sci digits\nScientific notation, corresponding to the printf %g out-\nput format with the precision given by digits. This pro-\nduces either fixed point or exponential notation depend-\ning on the value output.\n\n:fix digits\nFixed point notation, corresponding to the printf %f out-\nput format with the precision given by digits.\n\n:eng digits\nExponential notation, corresponding to the printf %E out-\nput format with the precision given by digits.\n\n:raw Raw output: this is the default form of the output from\na math evaluation. This may show more precision than the\nnumber actually possesses.\n\nOther special commands:\n:!line...\nExecute line... as a normal shell command line. Note\nthat it is executed in the context of the function, i.e.\nwith local variables. Space is optional after :!.\n\n:local arg ...\nDeclare variables local to the function. Other variables\nmay be used, too, but they will be taken from or put into\nthe global scope.\n\n:function name [ body ]\nDefine a mathematical function or (with no body) delete\nit. :function may be abbreviated to :func or simply :f.\nThe name may contain the same characters as a shell func-\ntion name. The function is defined using zmathfuncdef,\nsee below.\n\nNote that zcalc takes care of all quoting. Hence for ex-\nample:\n\n:f cube $1 * $1 * $1\n\ndefines a function to cube the sole argument. Functions\nso defined, or indeed any functions defined directly or\nindirectly using functions -M, are available to execute\nby typing only the name on the line in RPN mode; this\npops the appropriate number of arguments off the stack to\npass to the function, i.e. 1 in the case of the example\ncube function. If there are optional arguments only the\nmandatory arguments are supplied by this means.\n\n[#base]\nThis is not a special command, rather part of normal\narithmetic syntax; however, when this form appears on a\nline by itself the default output radix is set to base.\nUse, for example, `[#16]' to display hexadecimal output\npreceded by an indication of the base, or `[##16]' just\nto display the raw number in the given base. Bases them-\nselves are always specified in decimal. `[#]' restores\nthe normal output format. Note that setting an output\nbase suppresses floating point output; use `[#]' to re-\nturn to normal operation.\n\n$var Print out the value of var literally; does not affect the\ncalculation. To use the value of var, omit the leading\n`$'.\n\nSee the comments in the function for a few extra tips.\n\nmin(arg, ...)\nmax(arg, ...)\nsum(arg, ...)\nzmathfunc\nThe function zmathfunc defines the three mathematical functions\nmin, max, and sum. The functions min and max take one or more\narguments. The function sum takes zero or more arguments. Ar-\nguments can be of different types (ints and floats).\n\nNot to be confused with the zsh/mathfunc module, described in\nthe section `The zsh/mathfunc Module' in zshmodules(1).\n\nzmathfuncdef [ mathfunc [ body ] ]\nA convenient front end to functions -M.\n\nWith two arguments, define a mathematical function named math-\nfunc which can be used in any form of arithmetic evaluation.\nbody is a mathematical expression to implement the function. It\nmay contain references to position parameters $1, $2, ... to\nrefer to mandatory parameters and ${1:-defvalue} ... to refer\nto optional parameters. Note that the forms must be strictly\nadhered to for the function to calculate the correct number of\narguments. The implementation is held in a shell function named\nzshmathfuncmathfunc; usually the user will not need to refer\nto the shell function directly. Any existing function of the\nsame name is silently replaced.\n\nWith one argument, remove the mathematical function mathfunc as\nwell as the shell function implementation.\n\nWith no arguments, list all mathfunc functions in a form suit-\nable for restoring the definition. The functions have not nec-\nessarily been defined by zmathfuncdef.\n", "subsections": [] }, "USER CONFIGURATION FUNCTIONS": { "content": "The zsh/newuser module comes with a function to aid in configuring\nshell options for new users. If the module is installed, this function\ncan also be run by hand. It is available even if the module's default\nbehaviour, namely running the function for a new user logging in with-\nout startup files, is inhibited.\n\nzsh-newuser-install [ -f ]\nThe function presents the user with various options for cus-\ntomizing their initialization scripts. Currently only ~/.zshrc\nis handled. $ZDOTDIR/.zshrc is used instead if the parameter\nZDOTDIR is set; this provides a way for the user to configure a\nfile without altering an existing .zshrc.\n\nBy default the function exits immediately if it finds any of the\nfiles .zshenv, .zprofile, .zshrc, or .zlogin in the appropriate\ndirectory. The option -f is required in order to force the\nfunction to continue. Note this may happen even if .zshrc it-\nself does not exist.\n\nAs currently configured, the function will exit immediately if\nthe user has root privileges; this behaviour cannot be overrid-\nden.\n\nOnce activated, the function's behaviour is supposed to be\nself-explanatory. Menus are present allowing the user to alter\nthe value of options and parameters. Suggestions for improve-\nments are always welcome.\n\nWhen the script exits, the user is given the opportunity to save\nthe new file or not; changes are not irreversible until this\npoint. However, the script is careful to restrict changes to\nthe file only to a group marked by the lines `# Lines configured\nby zsh-newuser-install' and `# End of lines configured by\nzsh-newuser-install'. In addition, the old version of .zshrc is\nsaved to a file with the suffix .zni appended.\n\nIf the function edits an existing .zshrc, it is up to the user\nto ensure that the changes made will take effect. For example,\nif control usually returns early from the existing .zshrc the\nlines will not be executed; or a later initialization file may\noverride options or parameters, and so on. The function itself\ndoes not attempt to detect any such conflicts.\n", "subsections": [] }, "OTHER FUNCTIONS": { "content": "There are a large number of helpful functions in the Functions/Misc di-\nrectory of the zsh distribution. Most are very simple and do not re-\nquire documentation here, but a few are worthy of special mention.\n\nDescriptions\ncolors This function initializes several associative arrays to map\ncolor names to (and from) the ANSI standard eight-color terminal\ncodes. These are used by the prompt theme system (see above).\nYou seldom should need to run colors more than once.\n\nThe eight base colors are: black, red, green, yellow, blue, ma-\ngenta, cyan, and white. Each of these has codes for foreground\nand background. In addition there are seven intensity at-\ntributes: bold, faint, standout, underline, blink, reverse, and\nconceal. Finally, there are seven codes used to negate at-\ntributes: none (reset all attributes to the defaults), normal\n(neither bold nor faint), no-standout, no-underline, no-blink,\nno-reverse, and no-conceal.\n\nSome terminals do not support all combinations of colors and in-\ntensities.\n\nThe associative arrays are:\n\ncolor\ncolour Map all the color names to their integer codes, and inte-\nger codes to the color names. The eight base names map\nto the foreground color codes, as do names prefixed with\n`fg-', such as `fg-red'. Names prefixed with `bg-', such\nas `bg-blue', refer to the background codes. The reverse\nmapping from code to color yields base name for fore-\nground codes and the bg- form for backgrounds.\n\nAlthough it is a misnomer to call them `colors', these\narrays also map the other fourteen attributes from names\nto codes and codes to names.\n\nfg\nfgbold\nfgnobold\nMap the eight basic color names to ANSI terminal escape\nsequences that set the corresponding foreground text\nproperties. The fg sequences change the color without\nchanging the eight intensity attributes.\n\nbg\nbgbold\nbgnobold\nMap the eight basic color names to ANSI terminal escape\nsequences that set the corresponding background proper-\nties. The bg sequences change the color without changing\nthe eight intensity attributes.\n\nIn addition, the scalar parameters resetcolor and boldcolor\nare set to the ANSI terminal escapes that turn off all at-\ntributes and turn on bold intensity, respectively.\n\nfned [ -x num ] name\nSame as zed -f. This function does not appear in the zsh dis-\ntribution, but can be created by linking zed to the name fned in\nsome directory in your fpath.\n\nis-at-least needed [ present ]\nPerform a greater-than-or-equal-to comparison of two strings\nhaving the format of a zsh version number; that is, a string of\nnumbers and text with segments separated by dots or dashes. If\nthe present string is not provided, $ZSHVERSION is used. Seg-\nments are paired left-to-right in the two strings with leading\nnon-number parts ignored. If one string has fewer segments than\nthe other, the missing segments are considered zero.\n\nThis is useful in startup files to set options and other state\nthat are not available in all versions of zsh.\n\nis-at-least 3.1.6-15 && setopt NOGLOBALRCS\nis-at-least 3.1.0 && setopt HISTREDUCEBLANKS\nis-at-least 2.6-17 || print \"You can't use is-at-least here.\"\n\nnslookup [ arg ... ]\nThis wrapper function for the nslookup command requires the\nzsh/zpty module (see zshmodules(1)). It behaves exactly like\nthe standard nslookup except that it provides customizable\nprompts (including a right-side prompt) and completion of\nnslookup commands, host names, etc. (if you use the func-\ntion-based completion system). Completion styles may be set\nwith the context prefix `:completion:nslookup'.\n\nSee also the pager, prompt and rprompt styles below.\n\nregexp-replace var regexp replace\nUse regular expressions to perform a global search and replace\noperation on a variable. POSIX extended regular expressions are\nused, unless the option REMATCHPCRE has been set, in which\ncase Perl-compatible regular expressions are used (this requires\nthe shell to be linked against the pcre library).\n\nvar is the name of the variable containing the string to be\nmatched. The variable will be modified directly by the func-\ntion. The variables MATCH, MBEGIN, MEND, match, mbegin, mend\nshould be avoided as these are used by the regular expression\ncode.\n\nregexp is the regular expression to match against the string.\n\nreplace is the replacement text. This can contain parameter,\ncommand and arithmetic expressions which will be replaced: in\nparticular, a reference to $MATCH will be replaced by the text\nmatched by the pattern.\n\nThe return status is 0 if at least one match was performed, else\n1.\n\nrun-help cmd\nThis function is designed to be invoked by the run-help ZLE wid-\nget, in place of the default alias. See `Accessing On-Line\nHelp' above for setup instructions.\n\nIn the discussion which follows, if cmd is a file system path,\nit is first reduced to its rightmost component (the file name).\n\nHelp is first sought by looking for a file named cmd in the di-\nrectory named by the HELPDIR parameter. If no file is found, an\nassistant function, alias, or command named run-help-cmd is\nsought. If found, the assistant is executed with the rest of\nthe current command line (everything after the command name cmd)\nas its arguments. When neither file nor assistant is found, the\nexternal command `man cmd' is run.\n\nAn example assistant for the \"ssh\" command:\n\nrun-help-ssh() {\nemulate -LR zsh\nlocal -a args\n# Delete the \"-l username\" option\nzparseopts -D -E -a args l:\n# Delete other options, leaving: host command\nargs=(${@:#-*})\nif [[ ${#args} -lt 2 ]]; then\nman ssh\nelse\nrun-help $args[2]\nfi\n}\n\nSeveral of these assistants are provided in the Functions/Misc\ndirectory. These must be autoloaded, or placed as executable\nscripts in your search path, in order to be found and used by\nrun-help.\n\nrun-help-git\nrun-help-ip\nrun-help-openssl\nrun-help-p4\nrun-help-sudo\nrun-help-svk\nrun-help-svn\nAssistant functions for the git, ip, openssl, p4, sudo,\nsvk, and svn, commands.\n\ntetris Zsh was once accused of not being as complete as Emacs, because\nit lacked a Tetris game. This function was written to refute\nthis vicious slander.\n\nThis function must be used as a ZLE widget:\n\nautoload -U tetris\nzle -N tetris\nbindkey keys tetris\n\nTo start a game, execute the widget by typing the keys. What-\never command line you were editing disappears temporarily, and\nyour keymap is also temporarily replaced by the Tetris control\nkeys. The previous editor state is restored when you quit the\ngame (by pressing `q') or when you lose.\n\nIf you quit in the middle of a game, the next invocation of the\ntetris widget will continue where you left off. If you lost, it\nwill start a new game.\n\ntetriscurses\nThis is a port of the above to zcurses. The input handling is\nimproved a bit so that moving a block sideways doesn't automati-\ncally advance a timestep, and the graphics use unicode block\ngraphics.\n\nThis version does not save the game state between invocations,\nand is not invoked as a widget, but rather as:\n\nautoload -U tetriscurses\ntetriscurses\n\nzargs [ option ... -- ] [ input ... ] [ -- command [ arg ... ] ]\nThis function has a similar purpose to GNU xargs. Instead of\nreading lines of arguments from the standard input, it takes\nthem from the command line. This is useful because zsh, espe-\ncially with recursive glob operators, often can construct a com-\nmand line for a shell function that is longer than can be ac-\ncepted by an external command.\n\nThe option list represents options of the zargs command itself,\nwhich are the same as those of xargs. The input list is the\ncollection of strings (often file names) that become the argu-\nments of the command, analogous to the standard input of xargs.\nFinally, the arg list consists of those arguments (usually op-\ntions) that are passed to the command each time it runs. The\narg list precedes the elements from the input list in each run.\nIf no command is provided, then no arg list may be provided, and\nin that event the default command is `print' with arguments `-r\n--'.\n\nFor example, to get a long ls listing of all non-hidden plain\nfiles in the current directory or its subdirectories:\n\nautoload -U zargs\nzargs -- /*(.) -- ls -ld --\n\nThe first and third occurrences of `--' are used to mark the end\nof options for zargs and ls respectively to guard against file-\nnames starting with `-', while the second is used to separate\nthe list of files from the command to run (`ls -ld --').\n\nThe first `--' would also be needed if there was a chance the\nlist might be empty as in:\n\nzargs -r -- ./*.back(#qN) -- rm -f\n\nIn the event that the string `--' is or may be an input, the -e\noption may be used to change the end-of-inputs marker. Note\nthat this does not change the end-of-options marker. For exam-\nple, to use `..' as the marker:\n\nzargs -e.. -- /*(.) .. ls -ld --\n\nThis is a good choice in that example because no plain file can\nbe named `..', but the best end-marker depends on the circum-\nstances.\n\nThe options -i, -I, -l, -L, and -n differ slightly from their\nusage in xargs. There are no input lines for zargs to count, so\n-l and -L count through the input list, and -n counts the number\nof arguments passed to each execution of command, including any\narg list. Also, any time -i or -I is used, each input is pro-\ncessed separately as if by `-L 1'.\n\nFor details of the other zargs options, see xargs(1) (but note\nthe difference in function between zargs and xargs) or run zargs\nwith the --help option.\n\nzed [ -f [ -x num ] ] name\nzed -b This function uses the ZLE editor to edit a file or function.\n\nOnly one name argument is allowed. If the -f option is given,\nthe name is taken to be that of a function; if the function is\nmarked for autoloading, zed searches for it in the fpath and\nloads it. Note that functions edited this way are installed\ninto the current shell, but not written back to the autoload\nfile. In this case the -x option specifies that leading tabs\nindenting the function according to syntax should be converted\ninto the given number of spaces; `-x 2' is consistent with the\nlayout of functions distributed with the shell.\n\nWithout -f, name is the path name of the file to edit, which\nneed not exist; it is created on write, if necessary.\n\nWhile editing, the function sets the main keymap to zed and the\nvi command keymap to zed-vicmd. These will be copied from the\nexisting main and vicmd keymaps if they do not exist the first\ntime zed is run. They can be used to provide special key bind-\nings used only in zed.\n\nIf it creates the keymap, zed rebinds the return key to insert a\nline break and `^X^W' to accept the edit in the zed keymap, and\nbinds `ZZ' to accept the edit in the zed-vicmd keymap.\n\nThe bindings alone can be installed by running `zed -b'. This\nis suitable for putting into a startup file. Note that, if re-\nrun, this will overwrite the existing zed and zed-vicmd keymaps.\n\nCompletion is available, and styles may be set with the context\nprefix `:completion:zed'.\n\nA zle widget zed-set-file-name is available. This can be called\nby name from within zed using `\\ex zed-set-file-name' (note,\nhowever, that because of zed's rebindings you will have to type\n^j at the end instead of the return key), or can be bound to a\nkey in either of the zed or zed-vicmd keymaps after `zed -b' has\nbeen run. When the widget is called, it prompts for a new name\nfor the file being edited. When zed exits the file will be\nwritten under that name and the original file will be left\nalone. The widget has no effect with `zed -f'.\n\nWhile zed-set-file-name is running, zed uses the keymap zed-nor-\nmal-keymap, which is linked from the main keymap in effect at\nthe time zed initialised its bindings. (This is to make the re-\nturn key operate normally.) The result is that if the main\nkeymap has been changed, the widget won't notice. This is not a\nconcern for most users.\n\nzcp [ -finqQvwW ] srcpat dest\nzln [ -finqQsvwW ] srcpat dest\nSame as zmv -C and zmv -L, respectively. These functions do not\nappear in the zsh distribution, but can be created by linking\nzmv to the names zcp and zln in some directory in your fpath.\n\nzkbd See `Keyboard Definition' above.\n\nzmv [ -finqQsvwW ] [ -C | -L | -M | -{p|P} program ] [ -o optstring ]\nsrcpat dest\nMove (usually, rename) files matching the pattern srcpat to cor-\nresponding files having names of the form given by dest, where\nsrcpat contains parentheses surrounding patterns which will be\nreplaced in turn by $1, $2, ... in dest. For example,\n\nzmv '(*).lis' '$1.txt'\n\nrenames `foo.lis' to `foo.txt', `my.old.stuff.lis' to\n`my.old.stuff.txt', and so on.\n\nThe pattern is always treated as an EXTENDEDGLOB pattern. Any\nfile whose name is not changed by the substitution is simply ig-\nnored. Any error (a substitution resulted in an empty string,\ntwo substitutions gave the same result, the destination was an\nexisting regular file and -f was not given) causes the entire\nfunction to abort without doing anything.\n\nIn addition to pattern replacement, the variable $f can be re-\nferrred to in the second (replacement) argument. This makes it\npossible to use variable substitution to alter the argument; see\nexamples below.\n\nOptions:\n\n-f Force overwriting of destination files. Not currently\npassed down to the mv/cp/ln command due to vagaries of\nimplementations (but you can use -o-f to do that).\n-i Interactive: show each line to be executed and ask the\nuser whether to execute it. `Y' or `y' will execute it,\nanything else will skip it. Note that you just need to\ntype one character.\n-n No execution: print what would happen, but don't do it.\n-q Turn bare glob qualifiers off: now assumed by default, so\nthis has no effect.\n-Q Force bare glob qualifiers on. Don't turn this on unless\nyou are actually using glob qualifiers in a pattern.\n-s Symbolic, passed down to ln; only works with -L.\n-v Verbose: print each command as it's being executed.\n-w Pick out wildcard parts of the pattern, as described\nabove, and implicitly add parentheses for referring to\nthem.\n-W Just like -w, with the addition of turning wildcards in\nthe replacement pattern into sequential ${1} .. ${N} ref-\nerences.\n-C\n-L\n-M Force cp, ln or mv, respectively, regardless of the name\nof the function.\n-p program\nCall program instead of cp, ln or mv. Whatever it does,\nit should at least understand the form `program -- old-\nname newname' where oldname and newname are filenames\ngenerated by zmv. program will be split into words, so\nmight be e.g. the name of an archive tool plus a copy or\nrename subcommand.\n-P program\nAs -p program, except that program does not accept a fol-\nlowing -- to indicate the end of options. In this case\nfilenames must already be in a sane form for the program\nin question.\n-o optstring\nThe optstring is split into words and passed down verba-\ntim to the cp, ln or mv command called to perform the\nwork. It should probably begin with a `-'.\n\nFurther examples:\n\nzmv -v '(* *)' '${1// /}'\n\nFor any file in the current directory with at least one space in\nthe name, replace every space by an underscore and display the\ncommands executed.\n\nzmv -v '* *' '${f// /}'\n\nThis does exactly the same by referring to the file name stored\nin $f.\n\nFor more complete examples and other implementation details, see\nthe zmv source file, usually located in one of the directories\nnamed in your fpath, or in Functions/Misc/zmv in the zsh distri-\nbution.\n\nzrecompile\nSee `Recompiling Functions' above.\n\nzstyle+ context style value [ + subcontext style value ... ]\nThis makes defining styles a bit simpler by using a single `+'\nas a special token that allows you to append a context name to\nthe previously used context name. Like this:\n\nzstyle+ ':foo:bar' style1 value1 \\\n+':baz' style2 value2 \\\n+':frob' style3 value3\n\nThis defines style1 with value1 for the context :foo:bar as\nusual, but it also defines style2 with value2 for the context\n:foo:bar:baz and style3 with value3 for :foo:bar:frob. Any sub-\ncontext may be the empty string to re-use the first context un-\nchanged.\n\nStyles\ninsert-tab\nThe zed function sets this style in context `:completion:zed:*'\nto turn off completion when TAB is typed at the beginning of a\nline. You may override this by setting your own value for this\ncontext and style.\n\npager The nslookup function looks up this style in the context\n`:nslookup' to determine the program used to display output that\ndoes not fit on a single screen.\n\nprompt\nrprompt\nThe nslookup function looks up this style in the context\n`:nslookup' to set the prompt and the right-side prompt, respec-\ntively. The usual expansions for the PS1 and RPS1 parameters\nmay be used (see EXPANSION OF PROMPT SEQUENCES in zshmisc(1)).\n\nzsh 5.8.1 February 12, 2022 ZSHCONTRIB(1)", "subsections": [] } } } }