{ "mode": "man", "parameter": "zshall", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/zshall/1/json", "generated": "2026-06-03T00:21:16Z", "sections": { "NAME": { "content": "zshcontrib - user contributions to zsh\n", "subsections": [] }, "OVERVIEW": { "content": "Because zsh contains many features, the zsh manual has been split into a number of sections.\nThis manual page includes all the separate manual pages in the following order:\n\nzsh Zsh overview\nzshroadmap Informal introduction to the manual\nzshmisc Anything not fitting into the other sections\nzshexpn Zsh command and parameter expansion\nzshparam Zsh parameters\nzshoptions Zsh options\nzshbuiltins Zsh built-in functions\nzshzle Zsh command line editing\nzshcompwid Zsh completion widgets\nzshcompsys Zsh completion system\nzshcompctl Zsh completion control\nzshmodules Zsh loadable modules\nzshcalsys Zsh built-in calendar functions\nzshtcpsys Zsh built-in TCP functions\nzshzftpsys Zsh built-in FTP client\nzshcontrib Additional zsh functions and utilities\n", "subsections": [] }, "DESCRIPTION": { "content": "The Zsh source distribution includes a number of items contributed by the user community.\nThese are not inherently a part of the shell, and some may not be available in every zsh in‐\nstallation. The most significant of these are documented here. For documentation on other\ncontributed items such as shell functions, look for comments in the function source files.\n", "subsections": [] }, "AUTHOR": { "content": "Zsh was originally written by Paul Falstad . Zsh is now maintained by the mem‐\nbers of the zsh-workers mailing list . The development is currently co‐\nordinated by Peter Stephenson . The coordinator can be contacted at , but matters relating to the code should generally go to the mailing list.\n", "subsections": [] }, "AVAILABILITY": { "content": "Zsh is available from the following HTTP and anonymous FTP site.\n", "subsections": [ { "name": "ftp://ftp.zsh.org/pub/", "content": "" }, { "name": "https://www.zsh.org/pub/", "content": ")\n\nThe up-to-date source code is available via Git from Sourceforge. See https://source‐‐\nforge.net/projects/zsh/ for details. A summary of instructions for the archive can be found\nat http://zsh.sourceforge.net/.\n" } ] }, "MAILING LISTS": { "content": "Zsh has 3 mailing lists:\n", "subsections": [ { "name": "", "content": "Announcements about releases, major changes in the shell and the monthly posting of\nthe Zsh FAQ. (moderated)\n" }, { "name": "", "content": "User discussions.\n" }, { "name": "", "content": "Hacking, development, bug reports and patches.\n\nTo subscribe or unsubscribe, send mail to the associated administrative address for the mail‐\ning list.\n" }, { "name": "", "content": "" }, { "name": "", "content": "" }, { "name": "", "content": "" }, { "name": "", "content": "" }, { "name": "", "content": "" }, { "name": "", "content": "YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED. All submissions to\nzsh-announce are automatically forwarded to zsh-users. All submissions to zsh-users are au‐\ntomatically forwarded to zsh-workers.\n\nIf you have problems subscribing/unsubscribing to any of the mailing lists, send mail to\n. The mailing lists are maintained by Karsten Thygesen\n.\n\nThe mailing lists are archived; the archives can be accessed via the administrative addresses\nlisted above. There is also a hypertext archive, maintained by Geoff Wing ,\navailable at https://www.zsh.org/mla/.\n" } ] }, "THE ZSH FAQ": { "content": "Zsh has a list of Frequently Asked Questions (FAQ), maintained by Peter Stephenson\n. It is regularly posted to the newsgroup comp.unix.shell and the zsh-announce\nmailing list. The latest version can be found at any of the Zsh FTP sites, or at\nhttp://www.zsh.org/FAQ/. The contact address for FAQ-related matters is .\n", "subsections": [] }, "THE ZSH WEB PAGE": { "content": "Zsh has a web page which is located at https://www.zsh.org/. This is maintained by Karsten\nThygesen , of SunSITE Denmark. The contact address for web-related matters\nis .\n", "subsections": [] }, "THE ZSH USERGUIDE": { "content": "A userguide is currently in preparation. It is intended to complement the manual, with ex‐\nplanations and hints on issues where the manual can be cabbalistic, hierographic, or down‐\nright mystifying (for example, the word `hierographic' does not exist). It can be viewed in\nits current state at http://zsh.sourceforge.net/Guide/. At the time of writing, chapters\ndealing with startup files and their contents and the new completion system were essentially\ncomplete.\n", "subsections": [] }, "INVOCATION": { "content": "The following flags are interpreted by the shell when invoked to determine where the shell\nwill read commands from:\n", "subsections": [ { "name": "-c", "content": "script or standard input. If any further arguments are given, the first one is as‐\nsigned to $0, rather than being used as a positional parameter.\n", "flag": "-c" }, { "name": "-i", "content": "", "flag": "-i" }, { "name": "-s -s", "content": "and an argument is given, the first argument is taken to be the pathname of a script\nto execute.\n\nIf there are any remaining arguments after option processing, and neither of the options -c\nor -s was supplied, the first argument is taken as the file name of a script containing shell\ncommands to be executed. If the option PATHSCRIPT is set, and the file name does not con‐\ntain a directory path (i.e. there is no `/' in the name), first the current directory and\nthen the command path given by the variable PATH are searched for the script. If the option\nis not set or the file name contains a `/' it is used directly.\n\nAfter the first one or two arguments have been appropriated as described above, the remaining\narguments are assigned to the positional parameters.\n\nFor further options, which are common to invocation and the set builtin, see zshoptions(1).\n\nThe long option `--emulate' followed (in a separate word) by an emulation mode may be passed\nto the shell. The emulation modes are those described for the emulate builtin, see zsh‐\nbuiltins(1). The `--emulate' option must precede any other options (which might otherwise be\noverridden), but following options are honoured, so may be used to modify the requested emu‐\nlation mode. Note that certain extra steps are taken to ensure a smooth emulation when this\noption is used compared with the emulate command within the shell: for example, variables\nthat conflict with POSIX usage such as path are not defined within the shell.\n\nOptions may be specified by name using the -o option. -o acts like a single-letter option,\nbut takes a following string as the option name. For example,\n\nzsh -x -o shwordsplit scr\n\nruns the script scr, setting the XTRACE option by the corresponding letter `-x' and the\nSHWORDSPLIT option by name. Options may be turned off by name by using +o instead of -o.", "flag": "-s" }, { "name": "-o -xo", "content": "or `-xoshwordsplit' is equivalent to `-x -o shwordsplit'.\n\nOptions may also be specified by name in GNU long option style, `--option-name'. When this\nis done, `-' characters in the option name are permitted: they are translated into `', and\nthus ignored. So, for example, `zsh --sh-word-split' invokes zsh with the SHWORDSPLIT op‐\ntion turned on. Like other option syntaxes, options can be turned off by replacing the ini‐\ntial `-' with a `+'; thus `+-sh-word-split' is equivalent to `--no-sh-word-split'. Unlike\nother option syntaxes, GNU-style long options cannot be stacked with any other options, so\nfor example `-x-shwordsplit' is an error, rather than being treated like `-x --shwordsplit'.\n\nThe special GNU-style option `--version' is handled; it sends to standard output the shell's\nversion information, then exits successfully. `--help' is also handled; it sends to standard\noutput a list of options that can be used when invoking the shell, then exits successfully.\n\nOption processing may be finished, allowing following arguments that start with `-' or `+' to\nbe treated as normal arguments, in two ways. Firstly, a lone `-' (or `+') as an argument by\nitself ends option processing. Secondly, a special option `--' (or `+-'), which may be spec‐\nified on its own (which is the standard POSIX usage) or may be stacked with preceding options\n(so `-x-' is equivalent to `-x --'). Options are not permitted to be stacked after `--' (so\n`-x-f' is an error), but note the GNU-style option form discussed above, where `--shword‐‐\nsplit' is permitted and does not end option processing.\n\nExcept when the sh/ksh emulation single-letter options are in effect, the option `-b' (or\n`+b') ends option processing. `-b' is like `--', except that further single-letter options\ncan be stacked after the `-b' and will take effect as normal.\n", "flag": "-o" } ] }, "COMPATIBILITY": { "content": "Zsh tries to emulate sh or ksh when it is invoked as sh or ksh respectively; more precisely,\nit looks at the first letter of the name by which it was invoked, excluding any initial `r'\n(assumed to stand for `restricted'), and if that is `b', `s' or `k' it will emulate sh or\nksh. Furthermore, if invoked as su (which happens on certain systems when the shell is exe‐\ncuted by the su command), the shell will try to find an alternative name from the SHELL envi‐\nronment variable and perform emulation based on that.\n\nIn sh and ksh compatibility modes the following parameters are not special and not initial‐\nized by the shell: ARGC, argv, cdpath, fignore, fpath, HISTCHARS, mailpath, MANPATH, manpath,\npath, prompt, PROMPT, PROMPT2, PROMPT3, PROMPT4, psvar, status, watch.\n\nThe usual zsh startup/shutdown scripts are not executed. Login shells source /etc/profile\nfollowed by $HOME/.profile. If the ENV environment variable is set on invocation, $ENV is\nsourced after the profile scripts. The value of ENV is subjected to parameter expansion,\ncommand substitution, and arithmetic expansion before being interpreted as a pathname. Note\nthat the PRIVILEGED option also affects the execution of startup files.\n\nThe following options are set if the shell is invoked as sh or ksh: NOBADPATTERN,\nNOBANGHIST, NOBGNICE, NOEQUALS, NOFUNCTIONARGZERO, GLOBSUBST, NOGLOBALEXPORT,\nNOHUP, INTERACTIVECOMMENTS, KSHARRAYS, NOMULTIOS, NONOMATCH, NONOTIFY, POSIXBUILTINS,\nNOPROMPTPERCENT, RMSTARSILENT, SHFILEEXPANSION, SHGLOB, SHOPTIONLETTERS,\nSHWORDSPLIT. Additionally the BSDECHO and IGNOREBRACES options are set if zsh is invoked\nas sh. Also, the KSHOPTIONPRINT, LOCALOPTIONS, PROMPTBANG, PROMPTSUBST and SIN‐‐\nGLELINEZLE options are set if zsh is invoked as ksh.\n", "subsections": [] }, "RESTRICTED SHELL": { "content": "When the basename of the command used to invoke zsh starts with the letter `r' or the `-r'\ncommand line option is supplied at invocation, the shell becomes restricted. Emulation mode\nis determined after stripping the letter `r' from the invocation name. The following are\ndisabled in restricted mode:\n\n• changing directories with the cd builtin\n\n• changing or unsetting the EGID, EUID, GID, HISTFILE, HISTSIZE, IFS, LDAOUTLI‐‐\nBRARYPATH, LDAOUTPRELOAD, LDLIBRARYPATH, LDPRELOAD, MODULEPATH, modulepath,\nPATH, path, SHELL, UID and USERNAME parameters\n\n• specifying command names containing /\n\n• specifying command pathnames using hash\n\n• redirecting output to files\n\n• using the exec builtin command to replace the shell with another command\n\n• using jobs -Z to overwrite the shell process' argument and environment space\n\n• using the ARGV0 parameter to override argv[0] for external commands\n\n• turning off restricted mode with set +r or unsetopt RESTRICTED\n\nThese restrictions are enforced after processing the startup files. The startup files should\nset up PATH to point to a directory of commands which can be safely invoked in the restricted\nenvironment. They may also add further restrictions by disabling selected builtins.\n\nRestricted mode can also be activated any time by setting the RESTRICTED option. This imme‐\ndiately enables all the restrictions described above even if the shell still has not pro‐\ncessed all startup files.\n\nA shell Restricted Mode is an outdated way to restrict what users may do: modern systems\nhave better, safer and more reliable ways to confine user actions, such as chroot jails, con‐\ntainers and zones.\n\nA restricted shell is very difficult to implement safely. The feature may be removed in a\nfuture version of zsh.\n\nIt is important to realise that the restrictions only apply to the shell, not to the commands\nit runs (except for some shell builtins). While a restricted shell can only run the re‐\nstricted list of commands accessible via the predefined `PATH' variable, it does not prevent\nthose commands from running any other command.\n\nAs an example, if `env' is among the list of allowed commands, then it allows the user to run\nany command as `env' is not a shell builtin command and can run arbitrary executables.\n\nSo when implementing a restricted shell framework it is important to be fully aware of what\nactions each of the allowed commands or features (which may be regarded as modules) can per‐\nform.\n\nMany commands can have their behaviour affected by environment variables. Except for the few\nlisted above, zsh does not restrict the setting of environment variables.\n\nIf a `perl', `python', `bash', or other general purpose interpreted script it treated as a\nrestricted command, the user can work around the restriction by setting specially crafted\n`PERL5LIB', `PYTHONPATH', `BASHENV' (etc.) environment variables. On GNU systems, any command\ncan be made to run arbitrary code when performing character set conversion (including zsh it‐\nself) by setting a `GCONVPATH' environment variable. Those are only a few examples.\n\nBear in mind that, contrary to some other shells, `readonly' is not a security feature in zsh\nas it can be undone and so cannot be used to mitigate the above.\n\nA restricted shell only works if the allowed commands are few and carefully written so as not\nto grant more access to users than intended. It is also important to restrict what zsh mod‐\nule the user may load as some of them, such as `zsh/system', `zsh/mapfile' and `zsh/files',\nallow bypassing most of the restrictions.\n", "subsections": [] }, "STARTUP/SHUTDOWN FILES": { "content": "Commands are first read from /etc/zsh/zshenv; this cannot be overridden. Subsequent behav‐\niour is modified by the RCS and GLOBALRCS options; the former affects all startup files,\nwhile the second only affects global startup files (those shown here with an path starting\nwith a /). If one of the options is unset at any point, any subsequent startup file(s) of\nthe corresponding type will not be read. It is also possible for a file in $ZDOTDIR to\nre-enable GLOBALRCS. Both RCS and GLOBALRCS are set by default.\n\nCommands are then read from $ZDOTDIR/.zshenv. If the shell is a login shell, commands are\nread from /etc/zsh/zprofile and then $ZDOTDIR/.zprofile. Then, if the shell is interactive,\ncommands are read from /etc/zsh/zshrc and then $ZDOTDIR/.zshrc. Finally, if the shell is a\nlogin shell, /etc/zsh/zlogin and $ZDOTDIR/.zlogin are read.\n\nWhen a login shell exits, the files $ZDOTDIR/.zlogout and then /etc/zsh/zlogout are read.\nThis happens with either an explicit exit via the exit or logout commands, or an implicit\nexit by reading end-of-file from the terminal. However, if the shell terminates due to\nexec'ing another process, the logout files are not read. These are also affected by the RCS\nand GLOBALRCS options. Note also that the RCS option affects the saving of history files,\ni.e. if RCS is unset when the shell exits, no history file will be saved.\n\nIf ZDOTDIR is unset, HOME is used instead. Files listed above as being in /etc may be in an‐\nother directory, depending on the installation.\n\nAs /etc/zsh/zshenv is run for all instances of zsh, it is important that it be kept as small\nas possible. In particular, it is a good idea to put code that does not need to be run for\nevery single shell behind a test of the form `if [[ -o rcs ]]; then ...' so that it will not\nbe executed when zsh is invoked with the `-f' option.\n\nAny of these files may be pre-compiled with the zcompile builtin command (see zsh‐\nbuiltins(1)). If a compiled file exists (named for the original file plus the .zwc exten‐\nsion) and it is newer than the original file, the compiled file will be used instead.\n\n\n\nZSHROADMAP(1) General Commands Manual ZSHROADMAP(1)\n\n\n", "subsections": [] }, "WHEN THE SHELL STARTS": { "content": "When it starts, the shell reads commands from various files. These can be created or edited\nto customize the shell. See the section Startup/Shutdown Files in zsh(1).\n\nIf no personal initialization files exist for the current user, a function is run to help you\nchange some of the most common settings. It won't appear if your administrator has disabled\nthe zsh/newuser module. The function is designed to be self-explanatory. You can run it by\nhand with `autoload -Uz zsh-newuser-install; zsh-newuser-install -f'. See also the section\nUser Configuration Functions in zshcontrib(1).\n", "subsections": [] }, "INTERACTIVE USE": { "content": "Interaction with the shell uses the builtin Zsh Line Editor, ZLE. This is described in de‐\ntail in zshzle(1).\n\nThe first decision a user must make is whether to use the Emacs or Vi editing mode as the\nkeys for editing are substantially different. Emacs editing mode is probably more natural\nfor beginners and can be selected explicitly with the command bindkey -e.\n\nA history mechanism for retrieving previously typed lines (most simply with the Up or Down\narrow keys) is available; note that, unlike other shells, zsh will not save these lines when\nthe shell exits unless you set appropriate variables, and the number of history lines re‐\ntained by default is quite small (30 lines). See the description of the shell variables (re‐\nferred to in the documentation as parameters) HISTFILE, HISTSIZE and SAVEHIST in zshparam(1).\nNote that it's currently only possible to read and write files saving history when the shell\nis interactive, i.e. it does not work from scripts.\n\nThe shell now supports the UTF-8 character set (and also others if supported by the operating\nsystem). This is (mostly) handled transparently by the shell, but the degree of support in\nterminal emulators is variable. There is some discussion of this in the shell FAQ,\nhttp://www.zsh.org/FAQ/. Note in particular that for combining characters to be handled the\noption COMBININGCHARS needs to be set. Because the shell is now more sensitive to the defi‐\nnition of the character set, note that if you are upgrading from an older version of the\nshell you should ensure that the appropriate variable, either LANG (to affect all aspects of\nthe shell's operation) or LCCTYPE (to affect only the handling of character sets) is set to\nan appropriate value. This is true even if you are using a single-byte character set includ‐\ning extensions of ASCII such as ISO-8859-1 or ISO-8859-15. See the description of LCCTYPE\nin zshparam(1).\n", "subsections": [ { "name": "Completion", "content": "Completion is a feature present in many shells. It allows the user to type only a part (usu‐\nally the prefix) of a word and have the shell fill in the rest. The completion system in zsh\nis programmable. For example, the shell can be set to complete email addresses in arguments\nto the mail command from your ~/.abook/addressbook; usernames, hostnames, and even remote\npaths in arguments to scp, and so on. Anything that can be written in or glued together with\nzsh can be the source of what the line editor offers as possible completions.\n\nZsh has two completion systems, an old, so called compctl completion (named after the builtin\ncommand that serves as its complete and only user interface), and a new one, referred to as\ncompsys, organized as library of builtin and user-defined functions. The two systems differ\nin their interface for specifying the completion behavior. The new system is more customiza‐\nble and is supplied with completions for many commonly used commands; it is therefore to be\npreferred.\n\nThe completion system must be enabled explicitly when the shell starts. For more information\nsee zshcompsys(1).\n" }, { "name": "Extending the line editor", "content": "Apart from completion, the line editor is highly extensible by means of shell functions.\nSome useful functions are provided with the shell; they provide facilities such as:\n" }, { "name": "insert-composed-char", "content": "composing characters not found on the keyboard\n" }, { "name": "match-words-by-style", "content": "configuring what the line editor considers a word when moving or deleting by word\n\nhistory-beginning-search-backward-end, etc.\nalternative ways of searching the shell history\n\nreplace-string, replace-pattern\nfunctions for replacing strings or patterns globally in the command line\n" }, { "name": "edit-command-line", "content": "edit the command line with an external editor.\n\nSee the section `ZLE Functions' in zshcontrib(1) for descriptions of these.\n" } ] }, "OPTIONS": { "content": "The shell has a large number of options for changing its behaviour. These cover all aspects\nof the shell; browsing the full documentation is the only good way to become acquainted with\nthe many possibilities. See zshoptions(1).\n", "subsections": [] }, "PATTERN MATCHING": { "content": "The shell has a rich set of patterns which are available for file matching (described in the\ndocumentation as `filename generation' and also known for historical reasons as `globbing')\nand for use when programming. These are described in the section `Filename Generation' in\nzshexpn(1).\n\nOf particular interest are the following patterns that are not commonly supported by other\nsystems of pattern matching:\n\nfor matching over multiple directories\n\n| for matching either of two alternatives\n\n~, ^ the ability to exclude patterns from matching when the EXTENDEDGLOB option is set\n\n(...) glob qualifiers, included in parentheses at the end of the pattern, which select files\nby type (such as directories) or attribute (such as size).\n", "subsections": [] }, "GENERAL COMMENTS ON SYNTAX": { "content": "Although the syntax of zsh is in ways similar to the Korn shell, and therefore more remotely\nto the original UNIX shell, the Bourne shell, its default behaviour does not entirely corre‐\nspond to those shells. General shell syntax is introduced in the section `Shell Grammar' in\nzshmisc(1).\n\nOne commonly encountered difference is that variables substituted onto the command line are\nnot split into words. See the description of the shell option SHWORDSPLIT in the section\n`Parameter Expansion' in zshexpn(1). In zsh, you can either explicitly request the splitting\n(e.g. ${=foo}) or use an array when you want a variable to expand to more than one word. See\nthe section `Array Parameters' in zshparam(1).\n", "subsections": [] }, "PROGRAMMING": { "content": "The most convenient way of adding enhancements to the shell is typically by writing a shell\nfunction and arranging for it to be autoloaded. Functions are described in the section\n`Functions' in zshmisc(1). Users changing from the C shell and its relatives should notice\nthat aliases are less used in zsh as they don't perform argument substitution, only simple\ntext replacement.\n\nA few general functions, other than those for the line editor described above, are provided\nwith the shell and are described in zshcontrib(1). Features include:\n", "subsections": [ { "name": "promptinit", "content": "a prompt theme system for changing prompts easily, see the section `Prompt Themes'\n\n" }, { "name": "zsh-mime-setup", "content": "a MIME-handling system which dispatches commands according to the suffix of a file as\ndone by graphical file managers\n\nzcalc a calculator\n\nzargs a version of xargs that makes the find command redundant\n\nzmv a command for renaming files by means of shell patterns.\n\n\n\nZSHMISC(1) General Commands Manual ZSHMISC(1)\n\n\n" } ] }, "PRECOMMAND MODIFIERS": { "content": "A simple command may be preceded by a precommand modifier, which will alter how the command\nis interpreted. These modifiers are shell builtin commands with the exception of nocorrect\nwhich is a reserved word.\n\n- The command is executed with a `-' prepended to its argv[0] string.\n", "subsections": [ { "name": "builtin", "content": "The command word is taken to be the name of a builtin command, rather than a shell\nfunction or external command.\n\ncommand [ -pvV ]\nThe command word is taken to be the name of an external command, rather than a shell\nfunction or builtin. If the POSIXBUILTINS option is set, builtins will also be exe‐\ncuted but certain special properties of them are suppressed. The -p flag causes a de‐\nfault path to be searched instead of that in $path. With the -v flag, command is simi‐\nlar to whence and with -V, it is equivalent to whence -v.\n\nexec [ -cl ] [ -a argv0 ]\nThe following command together with any arguments is run in place of the current\nprocess, rather than as a sub-process. The shell does not fork and is replaced. The\nshell does not invoke TRAPEXIT, nor does it source zlogout files. The options are\nprovided for compatibility with other shells.\n\nThe -c option clears the environment.\n\nThe -l option is equivalent to the - precommand modifier, to treat the replacement\ncommand as a login shell; the command is executed with a - prepended to its argv[0]\nstring. This flag has no effect if used together with the -a option.\n\nThe -a option is used to specify explicitly the argv[0] string (the name of the com‐\nmand as seen by the process itself) to be used by the replacement command and is di‐\nrectly equivalent to setting a value for the ARGV0 environment variable.\n" }, { "name": "nocorrect", "content": "Spelling correction is not done on any of the words. This must appear before any\nother precommand modifier, as it is interpreted immediately, before any parsing is\ndone. It has no effect in non-interactive shells.\n\nnoglob Filename generation (globbing) is not performed on any of the words.\n" } ] }, "COMPLEX COMMANDS": { "content": "A complex command in zsh is one of the following:\n\nif list then list [ elif list then list ] ... [ else list ] fi\nThe if list is executed, and if it returns a zero exit status, the then list is exe‐\ncuted. Otherwise, the elif list is executed and if its status is zero, the then list\nis executed. If each elif list returns nonzero status, the else list is executed.\n\nfor name ... [ in word ... ] term do list done\nExpand the list of words, and set the parameter name to each of them in turn, execut‐\ning list each time. If the `in word' is omitted, use the positional parameters in‐\nstead of the words.\n\nThe term consists of one or more newline or ; which terminate the words, and are op‐\ntional when the `in word' is omitted.\n\nMore than one parameter name can appear before the list of words. If N names are\ngiven, then on each execution of the loop the next N words are assigned to the corre‐\nsponding parameters. If there are more names than remaining words, the remaining pa‐\nrameters are each set to the empty string. Execution of the loop ends when there is\nno remaining word to assign to the first name. It is only possible for in to appear\nas the first name in the list, else it will be treated as marking the end of the list.\n\nfor (( [expr1] ; [expr2] ; [expr3] )) do list done\nThe arithmetic expression expr1 is evaluated first (see the section `Arithmetic Evalu‐\nation'). The arithmetic expression expr2 is repeatedly evaluated until it evaluates\nto zero and when non-zero, list is executed and the arithmetic expression expr3 evalu‐\nated. If any expression is omitted, then it behaves as if it evaluated to 1.\n\nwhile list do list done\nExecute the do list as long as the while list returns a zero exit status.\n\nuntil list do list done\nExecute the do list as long as until list returns a nonzero exit status.\n\nrepeat word do list done\nword is expanded and treated as an arithmetic expression, which must evaluate to a\nnumber n. list is then executed n times.\n\nThe repeat syntax is disabled by default when the shell starts in a mode emulating an‐\nother shell. It can be enabled with the command `enable -r repeat'\n\ncase word in [ [(] pattern [ | pattern ] ... ) list (;;|;&|;|) ] ... esac\nExecute the list associated with the first pattern that matches word, if any. The\nform of the patterns is the same as that used for filename generation. See the sec‐\ntion `Filename Generation'.\n\nNote further that, unless the SHGLOB option is set, the whole pattern with alterna‐\ntives is treated by the shell as equivalent to a group of patterns within parentheses,\nalthough white space may appear about the parentheses and the vertical bar and will be\nstripped from the pattern at those points. White space may appear elsewhere in the\npattern; this is not stripped. If the SHGLOB option is set, so that an opening\nparenthesis can be unambiguously treated as part of the case syntax, the expression is\nparsed into separate words and these are treated as strict alternatives (as in other\nshells).\n\nIf the list that is executed is terminated with ;& rather than ;;, the following list\nis also executed. The rule for the terminator of the following list ;;, ;& or ;| is\napplied unless the esac is reached.\n\nIf the list that is executed is terminated with ;| the shell continues to scan the\npatterns looking for the next match, executing the corresponding list, and applying\nthe rule for the corresponding terminator ;;, ;& or ;|. Note that word is not re-ex‐\npanded; all applicable patterns are tested with the same word.\n\nselect name [ in word ... term ] do list done\nwhere term is one or more newline or ; to terminate the words. Print the set of\nwords, each preceded by a number. If the in word is omitted, use the positional pa‐\nrameters. The PROMPT3 prompt is printed and a line is read from the line editor if\nthe shell is interactive and that is active, or else standard input. If this line\nconsists of the number of one of the listed words, then the parameter name is set to\nthe word corresponding to this number. If this line is empty, the selection list is\nprinted again. Otherwise, the value of the parameter name is set to null. The con‐\ntents of the line read from standard input is saved in the parameter REPLY. list is\nexecuted for each selection until a break or end-of-file is encountered.\n\n( list )\nExecute list in a subshell. Traps set by the trap builtin are reset to their default\nvalues while executing list.\n\n{ list }\nExecute list.\n\n{ try-list } always { always-list }\nFirst execute try-list. Regardless of errors, or break or continue commands encoun‐\ntered within try-list, execute always-list. Execution then continues from the result\nof the execution of try-list; in other words, any error, or break or continue command\nis treated in the normal way, as if always-list were not present. The two chunks of\ncode are referred to as the `try block' and the `always block'.\n\nOptional newlines or semicolons may appear after the always; note, however, that they\nmay not appear between the preceding closing brace and the always.\n\nAn `error' in this context is a condition such as a syntax error which causes the\nshell to abort execution of the current function, script, or list. Syntax errors en‐\ncountered while the shell is parsing the code do not cause the always-list to be exe‐\ncuted. For example, an erroneously constructed if block in try-list would cause the\nshell to abort during parsing, so that always-list would not be executed, while an er‐\nroneous substitution such as ${*foo*} would cause a run-time error, after which al‐\nways-list would be executed.\n\nAn error condition can be tested and reset with the special integer variable\nTRYBLOCKERROR. Outside an always-list the value is irrelevant, but it is ini‐\ntialised to -1. Inside always-list, the value is 1 if an error occurred in the\ntry-list, else 0. If TRYBLOCKERROR is set to 0 during the always-list, the error\ncondition caused by the try-list is reset, and shell execution continues normally af‐\nter the end of always-list. Altering the value during the try-list is not useful (un‐\nless this forms part of an enclosing always block).\n\nRegardless of TRYBLOCKERROR, after the end of always-list the normal shell status $?\nis the value returned from try-list. This will be non-zero if there was an error,\neven if TRYBLOCKERROR was set to zero.\n\nThe following executes the given code, ignoring any errors it causes. This is an al‐\nternative to the usual convention of protecting code by executing it in a subshell.\n\n{\n# code which may cause an error\n} always {\n# This code is executed regardless of the error.\n(( TRYBLOCKERROR = 0 ))\n}\n# The error condition has been reset.\n\nWhen a try block occurs outside of any function, a return or a exit encountered in\ntry-list does not cause the execution of always-list. Instead, the shell exits imme‐\ndiately after any EXIT trap has been executed. Otherwise, a return command encoun‐\ntered in try-list will cause the execution of always-list, just like break and con‐‐\ntinue.\n\nfunction word ... [ () ] [ term ] { list }\nword ... () [ term ] { list }\nword ... () [ term ] command\nwhere term is one or more newline or ;. Define a function which is referenced by any\none of word. Normally, only one word is provided; multiple words are usually only\nuseful for setting traps. The body of the function is the list between the { and }.\nSee the section `Functions'.\n\nIf the option SHGLOB is set for compatibility with other shells, then whitespace may\nappear between the left and right parentheses when there is a single word; otherwise,\nthe parentheses will be treated as forming a globbing pattern in that case.\n\nIn any of the forms above, a redirection may appear outside the function body, for ex‐\nample\n\nfunc() { ... } 2>&1\n\nThe redirection is stored with the function and applied whenever the function is exe‐\ncuted. Any variables in the redirection are expanded at the point the function is ex‐\necuted, but outside the function scope.\n\ntime [ pipeline ]\nThe pipeline is executed, and timing statistics are reported on the standard error in\nthe form specified by the TIMEFMT parameter. If pipeline is omitted, print statistics\nabout the shell process and its children.\n\n[[ exp ]]\nEvaluates the conditional expression exp and return a zero exit status if it is true.\nSee the section `Conditional Expressions' for a description of exp.\n", "subsections": [] }, "ALTERNATE FORMS FOR COMPLEX COMMANDS": { "content": "Many of zsh's complex commands have alternate forms. These are non-standard and are likely\nnot to be obvious even to seasoned shell programmers; they should not be used anywhere that\nportability of shell code is a concern.\n\nThe short versions below only work if sublist is of the form `{ list }' or if the SHORTLOOPS\noption is set. For the if, while and until commands, in both these cases the test part of\nthe loop must also be suitably delimited, such as by `[[ ... ]]' or `(( ... ))', else the end\nof the test will not be recognized. For the for, repeat, case and select commands no such\nspecial form for the arguments is necessary, but the other condition (the special form of\nsublist or use of the SHORTLOOPS option) still applies.\n\nif list { list } [ elif list { list } ] ... [ else { list } ]\nAn alternate form of if. The rules mean that\n\nif [[ -o ignorebraces ]] {\nprint yes\n}\n\nworks, but\n\nif true { # Does not work!\nprint yes\n}\n\ndoes not, since the test is not suitably delimited.\n\nif list sublist\nA short form of the alternate if. The same limitations on the form of list apply as\nfor the previous form.\n\nfor name ... ( word ... ) sublist\nA short form of for.\n\nfor name ... [ in word ... ] term sublist\nwhere term is at least one newline or ;. Another short form of for.\n\nfor (( [expr1] ; [expr2] ; [expr3] )) sublist\nA short form of the arithmetic for command.\n\nforeach name ... ( word ... ) list end\nAnother form of for.\n\nwhile list { list }\nAn alternative form of while. Note the limitations on the form of list mentioned\nabove.\n\nuntil list { list }\nAn alternative form of until. Note the limitations on the form of list mentioned\nabove.\n\nrepeat word sublist\nThis is a short form of repeat.\n\ncase word { [ [(] pattern [ | pattern ] ... ) list (;;|;&|;|) ] ... }\nAn alternative form of case.\n\nselect name [ in word ... term ] sublist\nwhere term is at least one newline or ;. A short form of select.\n\nfunction word ... [ () ] [ term ] sublist\nThis is a short form of function.\n", "subsections": [] }, "RESERVED WORDS": { "content": "The following words are recognized as reserved words when used as the first word of a command\nunless quoted or disabled using disable -r:\n\ndo done esac then elif else fi for case if while function repeat time until select coproc no‐‐", "subsections": [ { "name": "correct foreach end ! [[ { } declare export float integer local readonly typeset", "content": "Additionally, `}' is recognized in any position if neither the IGNOREBRACES option nor the\nIGNORECLOSEBRACES option is set.\n" } ] }, "ERRORS": { "content": "Certain errors are treated as fatal by the shell: in an interactive shell, they cause control\nto return to the command line, and in a non-interactive shell they cause the shell to be\naborted. In older versions of zsh, a non-interactive shell running a script would not abort\ncompletely, but would resume execution at the next command to be read from the script, skip‐\nping the remainder of any functions or shell constructs such as loops or conditions; this\nsomewhat illogical behaviour can be recovered by setting the option CONTINUEONERROR.\n\nFatal errors found in non-interactive shells include:\n\n• Failure to parse shell options passed when invoking the shell\n\n• Failure to change options with the set builtin\n\n• Parse errors of all sorts, including failures to parse mathematical expressions\n\n• Failures to set or modify variable behaviour with typeset, local, declare, export, in‐‐\nteger, float\n\n• Execution of incorrectly positioned loop control structures (continue, break)\n\n• Attempts to use regular expression with no regular expression module available\n\n• Disallowed operations when the RESTRICTED options is set\n\n• Failure to create a pipe needed for a pipeline\n\n• Failure to create a multio\n\n• Failure to autoload a module needed for a declared shell feature\n\n• Errors creating command or process substitutions\n\n• Syntax errors in glob qualifiers\n\n• File generation errors where not caught by the option BADPATTERN\n\n• All bad patterns used for matching within case statements\n\n• File generation failures where not caused by NOMATCH or similar options\n\n• All file generation errors where the pattern was used to create a multio\n\n• Memory errors where detected by the shell\n\n• Invalid subscripts to shell variables\n\n• Attempts to assign read-only variables\n\n• Logical errors with variables such as assignment to the wrong type\n\n• Use of invalid variable names\n\n• Errors in variable substitution syntax\n\n• Failure to convert characters in $'...' expressions\n\nIf the POSIXBUILTINS option is set, more errors associated with shell builtin commands are\ntreated as fatal, as specified by the POSIX standard.\n", "subsections": [] }, "COMMENTS": { "content": "In non-interactive shells, or in interactive shells with the INTERACTIVECOMMENTS option set,\na word beginning with the third character of the histchars parameter (`#' by default) causes\nthat word and all the following characters up to a newline to be ignored.\n", "subsections": [] }, "ALIASING": { "content": "Every eligible word in the shell input is checked to see if there is an alias defined for it.\nIf so, it is replaced by the text of the alias if it is in command position (if it could be\nthe first word of a simple command), or if the alias is global. If the replacement text ends\nwith a space, the next word in the shell input is always eligible for purposes of alias ex‐\npansion. An alias is defined using the alias builtin; global aliases may be defined using\nthe -g option to that builtin.\n\nA word is defined as:\n\n• Any plain string or glob pattern\n\n• Any quoted string, using any quoting method (note that the quotes must be part of the\nalias definition for this to be eligible)\n\n• Any parameter reference or command substitution\n\n• Any series of the foregoing, concatenated without whitespace or other tokens between\nthem\n\n• Any reserved word (case, do, else, etc.)\n\n• With global aliasing, any command separator, any redirection operator, and `(' or `)'\nwhen not part of a glob pattern\n\nAlias expansion is done on the shell input before any other expansion except history expan‐\nsion. Therefore, if an alias is defined for the word foo, alias expansion may be avoided by\nquoting part of the word, e.g. \\foo. Any form of quoting works, although there is nothing to\nprevent an alias being defined for the quoted form such as \\foo as well.\n\nWhen POSIXALIASES is set, only plain unquoted strings are eligible for aliasing. The alias\nbuiltin does not reject ineligible aliases, but they are not expanded.\n\nFor use with completion, which would remove an initial backslash followed by a character that\nisn't special, it may be more convenient to quote the word by starting with a single quote,\ni.e. 'foo; completion will automatically add the trailing single quote.\n", "subsections": [ { "name": "Alias difficulties", "content": "Although aliases can be used in ways that bend normal shell syntax, not every string of\nnon-white-space characters can be used as an alias.\n\nAny set of characters not listed as a word above is not a word, hence no attempt is made to\nexpand it as an alias, no matter how it is defined (i.e. via the builtin or the special pa‐\nrameter aliases described in the section THE ZSH/PARAMETER MODULE in zshmodules(1)). How‐\never, as noted in the case of POSIXALIASES above, the shell does not attempt to deduce\nwhether the string corresponds to a word at the time the alias is created.\n\nFor example, an expression containing an = at the start of a command line is an assignment\nand cannot be expanded as an alias; a lone = is not an assignment but can only be set as an\nalias using the parameter, as otherwise the = is taken part of the syntax of the builtin com‐\nmand.\n\nIt is not presently possible to alias the `((' token that introduces arithmetic expressions,\nbecause until a full statement has been parsed, it cannot be distinguished from two consecu‐\ntive `(' tokens introducing nested subshells. Also, if a separator such as && is aliased,\n\\&& turns into the two tokens \\& and &, each of which may have been aliased separately. Sim‐\nilarly for \\<<, \\>|, etc.\n\nThere is a commonly encountered problem with aliases illustrated by the following code:\n\nalias echobar='echo bar'; echobar\n\nThis prints a message that the command echobar could not be found. This happens because\naliases are expanded when the code is read in; the entire line is read in one go, so that\nwhen echobar is executed it is too late to expand the newly defined alias. This is often a\nproblem in shell scripts, functions, and code executed with `source' or `.'. Consequently,\nuse of functions rather than aliases is recommended in non-interactive code.\n\nNote also the unhelpful interaction of aliases and function definitions:\n\nalias func='noglob func'\nfunc() {\necho Do something with $*\n}\n\nBecause aliases are expanded in function definitions, this causes the following command to be\nexecuted:\n\nnoglob func() {\necho Do something with $*\n}\n\nwhich defines noglob as well as func as functions with the body given. To avoid this, either\nquote the name func or use the alternative function definition form `function func'. Ensur‐\ning the alias is defined after the function works but is problematic if the code fragment\nmight be re-executed.\n" } ] }, "QUOTING": { "content": "A character may be quoted (that is, made to stand for itself) by preceding it with a `\\'.\n`\\' followed by a newline is ignored.\n\nA string enclosed between `$'' and `'' is processed the same way as the string arguments of\nthe print builtin, and the resulting string is considered to be entirely quoted. A literal\n`'' character can be included in the string by using the `\\'' escape.\n\nAll characters enclosed between a pair of single quotes ('') that is not preceded by a `$'\nare quoted. A single quote cannot appear within single quotes unless the option RCQUOTES is\nset, in which case a pair of single quotes are turned into a single quote. For example,\n\nprint ''''\n\noutputs nothing apart from a newline if RCQUOTES is not set, but one single quote if it is\nset.\n\nInside double quotes (\"\"), parameter and command substitution occur, and `\\' quotes the char‐\nacters `\\', ``', `\"', `$', and the first character of $histchars (default `!').\n", "subsections": [] }, "REDIRECTION": { "content": "If a command is followed by & and job control is not active, then the default standard input\nfor the command is the empty file /dev/null. Otherwise, the environment for the execution of\na command contains the file descriptors of the invoking shell as modified by input/output\nspecifications.\n\nThe following may appear anywhere in a simple command or may precede or follow a complex com‐\nmand. Expansion occurs before word or digit is used except as noted below. If the result of\nsubstitution on word produces more than one filename, redirection occurs for each separate\nfilename in turn.\n\n< word Open file word for reading as standard input. It is an error to open a file in this\nfashion if it does not exist.\n\n<> word\nOpen file word for reading and writing as standard input. If the file does not exist\nthen it is created.\n\n> word Open file word for writing as standard output. If the file does not exist then it is\ncreated. If the file exists, and the CLOBBER option is unset, this causes an error;\notherwise, it is truncated to zero length.\n\n>| word\n>! word\nSame as >, except that the file is truncated to zero length if it exists, regardless\nof CLOBBER.\n\n>> word\nOpen file word for writing in append mode as standard output. If the file does not\nexist, and the CLOBBER and APPENDCREATE options are both unset, this causes an error;\notherwise, the file is created.\n\n>>| word\n>>! word\nSame as >>, except that the file is created if it does not exist, regardless of CLOB‐‐\nBER and APPENDCREATE.\n\n<<[-] word\nThe shell input is read up to a line that is the same as word, or to an end-of-file.\nNo parameter expansion, command substitution or filename generation is performed on\nword. The resulting document, called a here-document, becomes the standard input.\n\nIf any character of word is quoted with single or double quotes or a `\\', no interpre‐\ntation is placed upon the characters of the document. Otherwise, parameter and com‐\nmand substitution occurs, `\\' followed by a newline is removed, and `\\' must be used\nto quote the characters `\\', `$', ``' and the first character of word.\n\nNote that word itself does not undergo shell expansion. Backquotes in word do not\nhave their usual effect; instead they behave similarly to double quotes, except that\nthe backquotes themselves are passed through unchanged. (This information is given\nfor completeness and it is not recommended that backquotes be used.) Quotes in the\nform $'...' have their standard effect of expanding backslashed references to special\ncharacters.\n\nIf <<- is used, then all leading tabs are stripped from word and from the document.\n\n<<< word\nPerform shell expansion on word and pass the result to standard input. This is known\nas a here-string. Compare the use of word in here-documents above, where word does\nnot undergo shell expansion.\n\n<& number\n>& number\nThe standard input/output is duplicated from file descriptor number (see dup2(2)).\n", "subsections": [ { "name": "<& -", "content": ">& - Close the standard input/output.\n" }, { "name": "<& p", "content": ">& p The input/output from/to the coprocess is moved to the standard input/output.\n\n>& word\n&> word\n(Except where `>& word' matches one of the above syntaxes; `&>' can always be used to\navoid this ambiguity.) Redirects both standard output and standard error (file de‐\nscriptor 2) in the manner of `> word'. Note that this does not have the same effect\nas `> word 2>&1' in the presence of multios (see the section below).\n\n>&| word\n>&! word\n&>| word\n&>! word\nRedirects both standard output and standard error (file descriptor 2) in the manner of\n`>| word'.\n\n>>& word\n&>> word\nRedirects both standard output and standard error (file descriptor 2) in the manner of\n`>> word'.\n\n>>&| word\n>>&! word\n&>>| word\n&>>! word\nRedirects both standard output and standard error (file descriptor 2) in the manner of\n`>>| word'.\n\nIf one of the above is preceded by a digit, then the file descriptor referred to is that\nspecified by the digit instead of the default 0 or 1. The order in which redirections are\nspecified is significant. The shell evaluates each redirection in terms of the (file de‐\nscriptor, file) association at the time of evaluation. For example:\n\n... 1>fname 2>&1\n\nfirst associates file descriptor 1 with file fname. It then associates file descriptor 2\nwith the file associated with file descriptor 1 (that is, fname). If the order of redirec‐\ntions were reversed, file descriptor 2 would be associated with the terminal (assuming file\ndescriptor 1 had been) and then file descriptor 1 would be associated with file fname.\n\nThe `|&' command separator described in Simple Commands & Pipelines in zshmisc(1) is a short‐\nhand for `2>&1 |'.\n\nThe various forms of process substitution, `<(list)', and `=(list)' for input and `>(list)'\nfor output, are often used together with redirection. For example, if word in an output re‐\ndirection is of the form `>(list)' then the output is piped to the command represented by\nlist. See Process Substitution in zshexpn(1).\n" } ] }, "OPENING FILE DESCRIPTORS USING PARAMETERS": { "content": "When the shell is parsing arguments to a command, and the shell option IGNOREBRACES is not\nset, a different form of redirection is allowed: instead of a digit before the operator there\nis a valid shell identifier enclosed in braces. The shell will open a new file descriptor\nthat is guaranteed to be at least 10 and set the parameter named by the identifier to the\nfile descriptor opened. No whitespace is allowed between the closing brace and the redirect‐\nion character. For example:\n\n... {myfd}>&1\n\nThis opens a new file descriptor that is a duplicate of file descriptor 1 and sets the param‐\neter myfd to the number of the file descriptor, which will be at least 10. The new file de‐\nscriptor can be written to using the syntax >&$myfd. The file descriptor remains open in\nsubshells and forked external executables.\n\nThe syntax {varid}>&-, for example {myfd}>&-, may be used to close a file descriptor opened\nin this fashion. Note that the parameter given by varid must previously be set to a file de‐\nscriptor in this case.\n\nIt is an error to open or close a file descriptor in this fashion when the parameter is read‐\nonly. However, it is not an error to read or write a file descriptor using <&$param or\n>&$param if param is readonly.\n\nIf the option CLOBBER is unset, it is an error to open a file descriptor using a parameter\nthat is already set to an open file descriptor previously allocated by this mechanism. Un‐\nsetting the parameter before using it for allocating a file descriptor avoids the error.\n\nNote that this mechanism merely allocates or closes a file descriptor; it does not perform\nany redirections from or to it. It is usually convenient to allocate a file descriptor prior\nto use as an argument to exec. The syntax does not in any case work when used around complex\ncommands such as parenthesised subshells or loops, where the opening brace is interpreted as\npart of a command list to be executed in the current shell.\n\nThe following shows a typical sequence of allocation, use, and closing of a file descriptor:\n\ninteger myfd\nexec {myfd}>~/logs/mylogfile.txt\nprint This is a log message. >&$myfd\nexec {myfd}>&-\n\nNote that the expansion of the variable in the expression >&$myfd occurs at the point the re‐\ndirection is opened. This is after the expansion of command arguments and after any redirec‐\ntions to the left on the command line have been processed.\n", "subsections": [] }, "MULTIOS": { "content": "If the user tries to open a file descriptor for writing more than once, the shell opens the\nfile descriptor as a pipe to a process that copies its input to all the specified outputs,\nsimilar to tee, provided the MULTIOS option is set, as it is by default. Thus:\n\ndate >foo >bar\n\nwrites the date to two files, named `foo' and `bar'. Note that a pipe is an implicit redi‐\nrection; thus\n\ndate >foo | cat\n\nwrites the date to the file `foo', and also pipes it to cat.\n\nNote that the shell opens all the files to be used in the multio process immediately, not at\nthe point they are about to be written.\n\nNote also that redirections are always expanded in order. This happens regardless of the\nsetting of the MULTIOS option, but with the option in effect there are additional conse‐\nquences. For example, the meaning of the expression >&1 will change after a previous redi‐\nrection:\n\ndate >&1 >output\n\nIn the case above, the >&1 refers to the standard output at the start of the line; the result\nis similar to the tee command. However, consider:\n\ndate >output >&1\n\nAs redirections are evaluated in order, when the >&1 is encountered the standard output is\nset to the file output and another copy of the output is therefore sent to that file. This\nis unlikely to be what is intended.\n\nIf the MULTIOS option is set, the word after a redirection operator is also subjected to\nfilename generation (globbing). Thus\n\n: > *\n\nwill truncate all files in the current directory, assuming there's at least one. (Without\nthe MULTIOS option, it would create an empty file called `*'.) Similarly, you can do\n\necho exit 0 >> *.sh\n\nIf the user tries to open a file descriptor for reading more than once, the shell opens the\nfile descriptor as a pipe to a process that copies all the specified inputs to its output in\nthe order specified, provided the MULTIOS option is set. It should be noted that each file\nis opened immediately, not at the point where it is about to be read: this behaviour differs\nfrom cat, so if strictly standard behaviour is needed, cat should be used instead.\n\nThus\n\nsort &$myfd.\n\nNote that a pipe is an implicit redirection; thus\n\ncat bar | sort bar > baz\n\nwhen MULTIOS is unset will truncate `bar', and write `Hello' into `baz'.\n\nThere is a problem when an output multio is attached to an external program. A simple exam‐\nple shows this:\n\ncat file >file1 >file2\ncat file1 file2\n\nHere, it is possible that the second `cat' will not display the full contents of file1 and\nfile2 (i.e. the original contents of file repeated twice).\n\nThe reason for this is that the multios are spawned after the cat process is forked from the\nparent shell, so the parent shell does not wait for the multios to finish writing data. This\nmeans the command as shown can exit before file1 and file2 are completely written. As a\nworkaround, it is possible to run the cat process as part of a job in the current shell:\n\n{ cat file } >file >file2\n\nHere, the {...} job will pause to wait for both files to be written.\n", "subsections": [] }, "REDIRECTIONS WITH NO COMMAND": { "content": "When a simple command consists of one or more redirection operators and zero or more parame‐\nter assignments, but no command name, zsh can behave in several ways.\n\nIf the parameter NULLCMD is not set or the option CSHNULLCMD is set, an error is caused.\nThis is the csh behavior and CSHNULLCMD is set by default when emulating csh.\n\nIf the option SHNULLCMD is set, the builtin `:' is inserted as a command with the given\nredirections. This is the default when emulating sh or ksh.\n\nOtherwise, if the parameter NULLCMD is set, its value will be used as a command with the\ngiven redirections. If both NULLCMD and READNULLCMD are set, then the value of the latter\nwill be used instead of that of the former when the redirection is an input. The default for\nNULLCMD is `cat' and for READNULLCMD is `more'. Thus\n\n< file\n\nshows the contents of file on standard output, with paging if that is a terminal. NULLCMD\nand READNULLCMD may refer to shell functions.\n", "subsections": [] }, "COMMAND EXECUTION": { "content": "If a command name contains no slashes, the shell attempts to locate it. If there exists a\nshell function by that name, the function is invoked as described in the section `Functions'.\nIf there exists a shell builtin by that name, the builtin is invoked.\n\nOtherwise, the shell searches each element of $path for a directory containing an executable\nfile by that name. If the search is unsuccessful, the shell prints an error message and re‐\nturns a nonzero exit status.\n\nIf execution fails because the file is not in executable format, and the file is not a direc‐\ntory, it is assumed to be a shell script. /bin/sh is spawned to execute it. If the program\nis a file beginning with `#!', the remainder of the first line specifies an interpreter for\nthe program. The shell will execute the specified interpreter on operating systems that do\nnot handle this executable format in the kernel.\n\nIf no external command is found but a function commandnotfoundhandler exists the shell ex‐\necutes this function with all command line arguments. The return status of the function be‐\ncomes the status of the command. If the function wishes to mimic the behaviour of the shell\nwhen the command is not found, it should print the message `command not found: cmd' to stan‐\ndard error and return status 127. Note that the handler is executed in a subshell forked to\nexecute an external command, hence changes to directories, shell parameters, etc. have no ef‐\nfect on the main shell.\n", "subsections": [] }, "FUNCTIONS": { "content": "The sequence of operations in performing a file transfer is essentially the same as that in a\nstandard FTP client. Note that, due to a quirk of the shell's getopts builtin, for those\nfunctions that handle options you must use `--' rather than `-' to ensure the remaining argu‐\nments are treated literally (a single `-' is treated as an argument).\n", "subsections": [ { "name": "Opening a connection", "content": "zfparams [ host [ user [ password ... ] ] ]\nSet or show the parameters for a future zfopen with no arguments. If no arguments are\ngiven, the current parameters are displayed (the password will be shown as a line of\nasterisks). If a host is given, and either the user or password is not, they will be\nprompted for; also, any parameter given as `?' will be prompted for, and if the `?' is\nfollowed by a string, that will be used as the prompt. As zfopen calls zfparams to\nstore the parameters, this usually need not be called directly.\n\nA single argument `-' will delete the stored parameters. This will also cause the\nmemory of the last directory (and so on) on the other host to be deleted.\n\nzfopen [ -1 ] [ host [ user [ password [ account ] ] ] ]\nIf host is present, open a connection to that host under username user with password\npassword (and, on the rare occasions when it is necessary, account account). If a\nnecessary parameter is missing or given as `?' it will be prompted for. If host is\nnot present, use a previously stored set of parameters.\n\nIf the command was successful, and the terminal is compatible with xterm or is\nsun-cmd, a summary will appear in the title bar, giving the local host:directory and\nthe remote host:directory; this is handled by the function zftpchpwd, described be‐\nlow.\n\nNormally, the host, user and password are internally recorded for later re-opening,\neither by a zfopen with no arguments, or automatically (see below). With the option\n`-1', no information is stored. Also, if an open command with arguments failed, the\nparameters will not be retained (and any previous parameters will also be deleted). A\nzfopen on its own, or a zfopen -1, never alters the stored parameters.\n\nBoth zfopen and zfanon (but not zfparams) understand URLs of the form\nftp://host/path... as meaning to connect to the host, then change directory to path\n(which must be a directory, not a file). The `ftp://' can be omitted; the trailing\n`/' is enough to trigger recognition of the path. Note prefixes other than `ftp:' are\nnot recognized, and that all characters after the first slash beyond host are signifi‐\ncant in path.\n\nzfanon [ -1 ] host\nOpen a connection host for anonymous FTP. The username used is `anonymous'. The\npassword (which will be reported the first time) is generated as user@host; this is\nthen stored in the shell parameter $EMAILADDR which can alternatively be set manually\nto a suitable string.\n" }, { "name": "Directory management", "content": "zfcd [ dir ]" }, { "name": "zfcd -", "content": "zfcd old new\nChange the current directory on the remote server: this is implemented to have many\nof the features of the shell builtin cd.\n\nIn the first form with dir present, change to the directory dir. The command `zfcd\n..' is treated specially, so is guaranteed to work on non-UNIX servers (note this is\nhandled internally by zftp). If dir is omitted, has the effect of `zfcd ~'.\n\nThe second form changes to the directory previously current.\n\nThe third form attempts to change the current directory by replacing the first occur‐\nrence of the string old with the string new in the current directory.\n\nNote that in this command, and indeed anywhere a remote filename is expected, the\nstring which on the local host corresponds to `~' is converted back to a `~' before\nbeing passed to the remote machine. This is convenient because of the way expansion\nis performed on the command line before zfcd receives a string. For example, suppose\nthe command is `zfcd ~/foo'. The shell will expand this to a full path such as `zfcd\n/home/user2/pws/foo'. At this stage, zfcd recognises the initial path as correspond‐\ning to `~' and will send the directory to the remote host as ~/foo, so that the `~'\nwill be expanded by the server to the correct remote host directory. Other named di‐\nrectories of the form `~name' are not treated in this fashion.\n\nzfhere Change directory on the remote server to the one corresponding to the current local\ndirectory, with special handling of `~' as in zfcd. For example, if the current local\ndirectory is ~/foo/bar, then zfhere performs the effect of `zfcd ~/foo/bar'.\n\nzfdir [ -rfd ] [ - ] [ dir-options ] [ dir ]\nProduce a long directory listing. The arguments dir-options and dir are passed di‐\nrectly to the server and their effect is implementation dependent, but specifying a\nparticular remote directory dir is usually possible. The output is passed through a\npager given by the environment variable $PAGER, or `more' if that is not set.\n\nThe directory is usually cached for re-use. In fact, two caches are maintained. One\nis for use when there is no dir-options or dir, i.e. a full listing of the current re‐\nmote directory; it is flushed when the current remote directory changes. The other is\nkept for repeated use of zfdir with the same arguments; for example, repeated use of\n`zfdir /pub/gnu' will only require the directory to be retrieved on the first call.\nAlternatively, this cache can be re-viewed with the -r option. As relative directo‐\nries will confuse zfdir, the -f option can be used to force the cache to be flushed\nbefore the directory is listed. The option -d will delete both caches without showing\na directory listing; it will also delete the cache of file names in the current remote\ndirectory, if any.\n\nzfls [ ls-options ] [ dir ]\nList files on the remote server. With no arguments, this will produce a simple list\nof file names for the current remote directory. Any arguments are passed directly to\nthe server. No pager and no caching is used.\n" }, { "name": "Status commands", "content": "zftype [ type ]\nWith no arguments, show the type of data to be transferred, usually ASCII or binary.\nWith an argument, change the type: the types `A' or `ASCII' for ASCII data and `B' or\n`BINARY', `I' or `IMAGE' for binary data are understood case-insensitively.\n\nzfstat [ -v ]\nShow the status of the current or last connection, as well as the status of some of\nzftp's status variables. With the -v option, a more verbose listing is produced by\nquerying the server for its version of events, too.\n" }, { "name": "Retrieving files", "content": "The commands for retrieving files all take at least two options. -G suppresses remote file‐\nname expansion which would otherwise be performed (see below for a more detailed description\nof that). -t attempts to set the modification time of the local file to that of the remote\nfile: see the description of the function zfrtime below for more information.\n\nzfget [ -Gtc ] file1 ...\nRetrieve all the listed files file1 ... one at a time from the remote server. If a\nfile contains a `/', the full name is passed to the remote server, but the file is\nstored locally under the name given by the part after the final `/'. The option -c\n(cat) forces all files to be sent as a single stream to standard output; in this case\nthe -t option has no effect.\n\nzfuget [ -Gvst ] file1 ...\nAs zfget, but only retrieve files where the version on the remote server is newer (has\na later modification time), or where the local file does not exist. If the remote\nfile is older but the files have different sizes, or if the sizes are the same but the\nremote file is newer, the user will usually be queried. With the option -s, the com‐\nmand runs silently and will always retrieve the file in either of those two cases.\nWith the option -v, the command prints more information about the files while it is\nworking out whether or not to transfer them.\n\nzfcget [ -Gt ] file1 ...\nAs zfget, but if any of the local files exists, and is shorter than the corresponding\nremote file, the command assumes that it is the result of a partially completed trans‐\nfer and attempts to transfer the rest of the file. This is useful on a poor connec‐\ntion which keeps failing.\n\nNote that this requires a commonly implemented, but non-standard, version of the FTP\nprotocol, so is not guaranteed to work on all servers.\n\nzfgcp [ -Gt ] remote-file local-file\nzfgcp [ -Gt ] rfile1 ... ldir\nThis retrieves files from the remote server with arguments behaving similarly to the\ncp command.\n\nIn the first form, copy remote-file from the server to the local file local-file.\n\nIn the second form, copy all the remote files rfile1 ... into the local directory ldir\nretaining the same basenames. This assumes UNIX directory semantics.\n" }, { "name": "Sending files", "content": "zfput [ -r ] file1 ...\nSend all the file1 ... given separately to the remote server. If a filename contains\na `/', the full filename is used locally to find the file, but only the basename is\nused for the remote file name.\n\nWith the option -r, if any of the files are directories they are sent recursively with\nall their subdirectories, including files beginning with `.'. This requires that the\nremote machine understand UNIX file semantics, since `/' is used as a directory sepa‐\nrator.\n\nzfuput [ -vs ] file1 ...\nAs zfput, but only send files which are newer than their remote equivalents, or if the\nremote file does not exist. The logic is the same as for zfuget, but reversed between\nlocal and remote files.\n\nzfcput file1 ...\nAs zfput, but if any remote file already exists and is shorter than the local equiva‐\nlent, assume it is the result of an incomplete transfer and send the rest of the file\nto append to the existing part. As the FTP append command is part of the standard\nset, this is in principle more likely to work than zfcget.\n\nzfpcp local-file remote-file\nzfpcp lfile1 ... rdir\nThis sends files to the remote server with arguments behaving similarly to the cp com‐\nmand.\n\nWith two arguments, copy local-file to the server as remote-file.\n\nWith more than two arguments, copy all the local files lfile1 ... into the existing\nremote directory rdir retaining the same basenames. This assumes UNIX directory se‐\nmantics.\n\nA problem arises if you attempt to use zfpcp lfile1 rdir, i.e. the second form of\ncopying but with two arguments, as the command has no simple way of knowing if rdir\ncorresponds to a directory or a filename. It attempts to resolve this in various\nways. First, if the rdir argument is `.' or `..' or ends in a slash, it is assumed to\nbe a directory. Secondly, if the operation of copying to a remote file in the first\nform failed, and the remote server sends back the expected failure code 553 and a re‐\nply including the string `Is a directory', then zfpcp will retry using the second\nform.\n" }, { "name": "Closing the connection", "content": "" }, { "name": "zfclose", "content": "Close the connection.\n" }, { "name": "Session management", "content": "zfsession [ -lvod ] [ sessname ]\nAllows you to manage multiple FTP sessions at once. By default, connections take\nplace in a session called `default'; by giving the command `zfsession sessname' you\ncan change to a new or existing session with a name of your choice. The new session\nremembers its own connection, as well as associated shell parameters, and also the\nhost/user parameters set by zfparams. Hence you can have different sessions set up to\nconnect to different hosts, each remembering the appropriate host, user and password.\n\nWith no arguments, zfsession prints the name of the current session; with the option\n-l it lists all sessions which currently exist, and with the option -v it gives a ver‐\nbose list showing the host and directory for each session, where the current session\nis marked with an asterisk. With -o, it will switch to the most recent previous ses‐\nsion.\n\nWith -d, the given session (or else the current one) is removed; everything to do with\nit is completely forgotten. If it was the only session, a new session called `de‐‐\nfault' is created and made current. It is safest not to delete sessions while back‐\nground commands using zftp are active.\n\nzftransfer sess1:file1 sess2:file2\nTransfer files between two sessions; no local copy is made. The file is read from the\nsession sess1 as file1 and written to session sess2 as file file2; file1 and file2 may\nbe relative to the current directories of the session. Either sess1 or sess2 may be\nomitted (though the colon should be retained if there is a possibility of a colon ap‐\npearing in the file name) and defaults to the current session; file2 may be omitted or\nmay end with a slash, in which case the basename of file1 will be added. The sessions\nsess1 and sess2 must be distinct.\n\nThe operation is performed using pipes, so it is required that the connections still\nbe valid in a subshell, which is not the case under versions of some operating sys‐\ntems, presumably due to a system bug.\n" }, { "name": "Bookmarks", "content": "The two functions zfmark and zfgoto allow you to `bookmark' the present location (host, user\nand directory) of the current FTP connection for later use. The file to be used for storing\nand retrieving bookmarks is given by the parameter $ZFTPBMFILE; if not set when one of the\ntwo functions is called, it will be set to the file .zfbkmarks in the directory where your\nzsh startup files live (usually ~).\n\nzfmark [ bookmark ]\nIf given an argument, mark the current host, user and directory under the name book‐\nmark for later use by zfgoto. If there is no connection open, use the values for the\nlast connection immediately before it was closed; it is an error if there was none.\nAny existing bookmark under the same name will be silently replaced.\n\nIf not given an argument, list the existing bookmarks and the points to which they re‐\nfer in the form user@host:directory; this is the format in which they are stored, and\nthe file may be edited directly.\n\nzfgoto [ -n ] bookmark\nReturn to the location given by bookmark, as previously set by zfmark. If the loca‐\ntion has user `ftp' or `anonymous', open the connection with zfanon, so that no pass‐\nword is required. If the user and host parameters match those stored for the current\nsession, if any, those will be used, and again no password is required. Otherwise a\npassword will be prompted for.\n\nWith the option -n, the bookmark is taken to be a nickname stored by the ncftp program\nin its bookmark file, which is assumed to be ~/.ncftp/bookmarks. The function works\nidentically in other ways. Note that there is no mechanism for adding or modifying\nncftp bookmarks from the zftp functions.\n" }, { "name": "Other functions", "content": "Mostly, these functions will not be called directly (apart from zfinit), but are described\nhere for completeness. You may wish to alter zftpchpwd and zftpprogress, in particular.\n\nzfinit [ -n ]\nAs described above, this is used to initialize the zftp function system. The -n op‐\ntion should be used if the zftp command is already built into the shell.\n\nzfautocheck [ -dn ]\nThis function is called to implement automatic reopening behaviour, as described in\nmore detail below. The options must appear in the first argument; -n prevents the\ncommand from changing to the old directory, while -d prevents it from setting the\nvariable doclose, which it otherwise does as a flag for automatically closing the\nconnection after a transfer. The host and directory for the last session are stored\nin the variable $zflastsession, but the internal host/user/password parameters must\nalso be correctly set.\n\nzfcdmatch prefix suffix\nThis performs matching for completion of remote directory names. If the remote server\nis UNIX, it will attempt to persuade the server to list the remote directory with sub‐\ndirectories marked, which usually works but is not guaranteed. On other hosts it sim‐\nply calls zfgetmatch and hence completes all files, not just directories. On some\nsystems, directories may not even look like filenames.\n\nzfgetmatch prefix suffix\nThis performs matching for completion of remote filenames. It caches files for the\ncurrent directory (only) in the shell parameter $zftpfcache. It is in the form to be\ncalled by the -K option of compctl, but also works when called from a widget-style\ncompletion function with prefix and suffix set appropriately.\n\nzfrglob varname\nPerform remote globbing, as describes in more detail below. varname is the name of a\nvariable containing the pattern to be expanded; if there were any matches, the same\nvariable will be set to the expanded set of filenames on return.\n\nzfrtime lfile rfile [ time ]\nSet the local file lfile to have the same modification time as the remote file rfile,\nor the explicit time time in FTP format CCYYMMDDhhmmSS for the GMT timezone. This\nuses the shell's zsh/datetime module to perform the conversion from GMT to local time.\n\nzftpchpwd\nThis function is called every time a connection is opened, or closed, or the remote\ndirectory changes. This version alters the title bar of an xterm-compatible or\nsun-cmd terminal emulator to reflect the local and remote hostnames and current direc‐\ntories. It works best when combined with the function chpwd. In particular, a func‐\ntion of the form\n\nchpwd() {\nif [[ -n $ZFTPUSER ]]; then\nzftpchpwd\nelse\n# usual chpwd e.g put host:directory in title bar\nfi\n}\n\nfits in well.\n\nzftpprogress\nThis function shows the status of the transfer. It will not write anything unless the\noutput is going to a terminal; however, if you transfer files in the background, you\nshould turn off progress reports by hand using `zstyle ':zftp:*' progress none'. Note\nalso that if you alter it, any output must be to standard error, as standard output\nmay be a file being received. The form of the progress meter, or whether it is used\nat all, can be configured without altering the function, as described in the next sec‐\ntion.\n" }, { "name": "zffcache", "content": "This is used to implement caching of files in the current directory for each session\nseparately. It is used by zfgetmatch and zfrglob.\n" } ] }, "AUTOLOADING FUNCTIONS": { "content": "A function can be marked as undefined using the autoload builtin (or `functions -u' or `type‐‐\nset -fu'). Such a function has no body. When the function is first executed, the shell\nsearches for its definition using the elements of the fpath variable. Thus to define func‐\ntions for autoloading, a typical sequence is:\n\nfpath=(~/myfuncs $fpath)\nautoload myfunc1 myfunc2 ...\n\nThe usual alias expansion during reading will be suppressed if the autoload builtin or its\nequivalent is given the option -U. This is recommended for the use of functions supplied with\nthe zsh distribution. Note that for functions precompiled with the zcompile builtin command\nthe flag -U must be provided when the .zwc file is created, as the corresponding information\nis compiled into the latter.\n\nFor each element in fpath, the shell looks for three possible files, the newest of which is\nused to load the definition for the function:\n\nelement.zwc\nA file created with the zcompile builtin command, which is expected to contain the\ndefinitions for all functions in the directory named element. The file is treated in\nthe same manner as a directory containing files for functions and is searched for the\ndefinition of the function. If the definition is not found, the search for a defini‐\ntion proceeds with the other two possibilities described below.\n\nIf element already includes a .zwc extension (i.e. the extension was explicitly given\nby the user), element is searched for the definition of the function without comparing\nits age to that of other files; in fact, there does not need to be any directory named\nelement without the suffix. Thus including an element such as `/usr/local/funcs.zwc'\nin fpath will speed up the search for functions, with the disadvantage that functions\nincluded must be explicitly recompiled by hand before the shell notices any changes.\n\nelement/function.zwc\nA file created with zcompile, which is expected to contain the definition for func‐\ntion. It may include other function definitions as well, but those are neither loaded\nnor executed; a file found in this way is searched only for the definition of func‐\ntion.\n\nelement/function\nA file of zsh command text, taken to be the definition for function.\n\nIn summary, the order of searching is, first, in the parents of directories in fpath for the\nnewer of either a compiled directory or a directory in fpath; second, if more than one of\nthese contains a definition for the function that is sought, the leftmost in the fpath is\nchosen; and third, within a directory, the newer of either a compiled function or an ordinary\nfunction definition is used.\n\nIf the KSHAUTOLOAD option is set, or the file contains only a simple definition of the func‐\ntion, the file's contents will be executed. This will normally define the function in ques‐\ntion, but may also perform initialization, which is executed in the context of the function\nexecution, and may therefore define local parameters. It is an error if the function is not\ndefined by loading the file.\n\nOtherwise, the function body (with no surrounding `funcname() {...}') is taken to be the com‐\nplete contents of the file. This form allows the file to be used directly as an executable\nshell script. If processing of the file results in the function being re-defined, the func‐\ntion itself is not re-executed. To force the shell to perform initialization and then call\nthe function defined, the file should contain initialization code (which will be executed\nthen discarded) in addition to a complete function definition (which will be retained for\nsubsequent calls to the function), and a call to the shell function, including any arguments,\nat the end.\n\nFor example, suppose the autoload file func contains\n\nfunc() { print This is func; }\nprint func is initialized\n\nthen `func; func' with KSHAUTOLOAD set will produce both messages on the first call, but\nonly the message `This is func' on the second and subsequent calls. Without KSHAUTOLOAD\nset, it will produce the initialization message on the first call, and the other message on\nthe second and subsequent calls.\n\nIt is also possible to create a function that is not marked as autoloaded, but which loads\nits own definition by searching fpath, by using `autoload -X' within a shell function. For\nexample, the following are equivalent:\n\nmyfunc() {\nautoload -X\n}\nmyfunc args...\n\nand\n\nunfunction myfunc # if myfunc was defined\nautoload myfunc\nmyfunc args...\n\nIn fact, the functions command outputs `builtin autoload -X' as the body of an autoloaded\nfunction. This is done so that\n\neval \"$(functions)\"\n\nproduces a reasonable result. A true autoloaded function can be identified by the presence\nof the comment `# undefined' in the body, because all comments are discarded from defined\nfunctions.\n\nTo load the definition of an autoloaded function myfunc without executing myfunc, use:\n\nautoload +X myfunc\n", "subsections": [] }, "ANONYMOUS FUNCTIONS": { "content": "If no name is given for a function, it is `anonymous' and is handled specially. Either form\nof function definition may be used: a `()' with no preceding name, or a `function' with an\nimmediately following open brace. The function is executed immediately at the point of defi‐\nnition and is not stored for future use. The function name is set to `(anon)'.\n\nArguments to the function may be specified as words following the closing brace defining the\nfunction, hence if there are none no arguments (other than $0) are set. This is a difference\nfrom the way other functions are parsed: normal function definitions may be followed by cer‐\ntain keywords such as `else' or `fi', which will be treated as arguments to anonymous func‐\ntions, so that a newline or semicolon is needed to force keyword interpretation.\n\nNote also that the argument list of any enclosing script or function is hidden (as would be\nthe case for any other function called at this point).\n\nRedirections may be applied to the anonymous function in the same manner as to a cur‐\nrent-shell structure enclosed in braces. The main use of anonymous functions is to provide a\nscope for local variables. This is particularly convenient in start-up files as these do not\nprovide their own local variable scope.\n\nFor example,\n\nvariable=outside\nfunction {\nlocal variable=inside\nprint \"I am $variable with arguments $*\"\n} this and that\nprint \"I am $variable\"\n\noutputs the following:\n\nI am inside with arguments this and that\nI am outside\n\nNote that function definitions with arguments that expand to nothing, for example `name=;\nfunction $name { ... }', are not treated as anonymous functions. Instead, they are treated\nas normal function definitions where the definition is silently discarded.\n", "subsections": [] }, "SPECIAL FUNCTIONS": { "content": "Certain functions, if defined, have special meaning to the shell.\n", "subsections": [ { "name": "Hook Functions", "content": "For the functions below, it is possible to define an array that has the same name as the\nfunction with `functions' appended. Any element in such an array is taken as the name of a\nfunction to execute; it is executed in the same context and with the same arguments as the\nbasic function. For example, if $chpwdfunctions is an array containing the values `mych‐‐\npwd', `chpwdsavedirstack', then the shell attempts to execute the functions `chpwd', `mych‐‐\npwd' and `chpwdsavedirstack', in that order. Any function that does not exist is silently\nignored. A function found by this mechanism is referred to elsewhere as a `hook function'.\nAn error in any function causes subsequent functions not to be run. Note further that an er‐\nror in a precmd hook causes an immediately following periodic function not to run (though it\nmay run at the next opportunity).\n\nchpwd Executed whenever the current working directory is changed.\n" }, { "name": "periodic", "content": "If the parameter PERIOD is set, this function is executed every $PERIOD seconds, just\nbefore a prompt. Note that if multiple functions are defined using the array peri‐‐\nodicfunctions only one period is applied to the complete set of functions, and the\nscheduled time is not reset if the list of functions is altered. Hence the set of\nfunctions is always called together.\n\nprecmd Executed before each prompt. Note that precommand functions are not re-executed sim‐\nply because the command line is redrawn, as happens, for example, when a notification\nabout an exiting job is displayed.\n" }, { "name": "preexec", "content": "Executed just after a command has been read and is about to be executed. If the his‐\ntory mechanism is active (regardless of whether the line was discarded from the his‐\ntory buffer), the string that the user typed is passed as the first argument, other‐\nwise it is an empty string. The actual command that will be executed (including ex‐\npanded aliases) is passed in two different forms: the second argument is a sin‐\ngle-line, size-limited version of the command (with things like function bodies\nelided); the third argument contains the full text that is being executed.\n" }, { "name": "zshaddhistory", "content": "Executed when a history line has been read interactively, but before it is executed.\nThe sole argument is the complete history line (so that any terminating newline will\nstill be present).\n\nIf any of the hook functions returns status 1 (or any non-zero value other than 2,\nthough this is not guaranteed for future versions of the shell) the history line will\nnot be saved, although it lingers in the history until the next line is executed, al‐\nlowing you to reuse or edit it immediately.\n\nIf any of the hook functions returns status 2 the history line will be saved on the\ninternal history list, but not written to the history file. In case of a conflict,\nthe first non-zero status value is taken.\n\nA hook function may call `fc -p ...' to switch the history context so that the history\nis saved in a different file from the that in the global HISTFILE parameter. This is\nhandled specially: the history context is automatically restored after the processing\nof the history line is finished.\n\nThe following example function works with one of the options INCAPPENDHISTORY or\nSHAREHISTORY set, in order that the line is written out immediately after the history\nentry is added. It first adds the history line to the normal history with the newline\nstripped, which is usually the correct behaviour. Then it switches the history con‐\ntext so that the line will be written to a history file in the current directory.\n\nzshaddhistory() {\nprint -sr -- ${1%%$'\\n'}\nfc -p .zshlocalhistory\n}\n" }, { "name": "zshexit", "content": "Executed at the point where the main shell is about to exit normally. This is not\ncalled by exiting subshells, nor when the exec precommand modifier is used before an\nexternal command. Also, unlike TRAPEXIT, it is not called when functions exit.\n" }, { "name": "Trap Functions", "content": "The functions below are treated specially but do not have corresponding hook arrays.\n\nTRAPNAL\nIf defined and non-null, this function will be executed whenever the shell catches a\nsignal SIGNAL, where NAL is a signal name as specified for the kill builtin. The sig‐\nnal number will be passed as the first parameter to the function.\n\nIf a function of this form is defined and null, the shell and processes spawned by it\nwill ignore SIGNAL.\n\nThe return status from the function is handled specially. If it is zero, the signal\nis assumed to have been handled, and execution continues normally. Otherwise, the\nshell will behave as interrupted except that the return status of the trap is re‐\ntained.\n\nPrograms terminated by uncaught signals typically return the status 128 plus the sig‐\nnal number. Hence the following causes the handler for SIGINT to print a message,\nthen mimic the usual effect of the signal.\n\nTRAPINT() {\nprint \"Caught SIGINT, aborting.\"\nreturn $(( 128 + $1 ))\n}\n\nThe functions TRAPZERR, TRAPDEBUG and TRAPEXIT are never executed inside other traps.\n\nTRAPDEBUG\nIf the option DEBUGBEFORECMD is set (as it is by default), executed before each com‐\nmand; otherwise executed after each command. See the description of the trap builtin\nin zshbuiltins(1) for details of additional features provided in debug traps.\n\nTRAPEXIT\nExecuted when the shell exits, or when the current function exits if defined inside a\nfunction. The value of $? at the start of execution is the exit status of the shell\nor the return status of the function exiting.\n\nTRAPZERR\nExecuted whenever a command has a non-zero exit status. However, the function is not\nexecuted if the command occurred in a sublist followed by `&&' or `||'; only the final\ncommand in a sublist of this type causes the trap to be executed. The function TRAP‐‐\nERR acts the same as TRAPZERR on systems where there is no SIGERR (this is the usual\ncase).\n\nThe functions beginning `TRAP' may alternatively be defined with the trap builtin: this may\nbe preferable for some uses. Setting a trap with one form removes any trap of the other form\nfor the same signal; removing a trap in either form removes all traps for the same signal.\nThe forms\n\nTRAPNAL() {\n# code\n}\n\n('function traps') and\n\ntrap '\n# code\n' NAL\n\n('list traps') are equivalent in most ways, the exceptions being the following:\n\n• Function traps have all the properties of normal functions, appearing in the list of\nfunctions and being called with their own function context rather than the context\nwhere the trap was triggered.\n\n• The return status from function traps is special, whereas a return from a list trap\ncauses the surrounding context to return with the given status.\n\n• Function traps are not reset within subshells, in accordance with zsh behaviour; list\ntraps are reset, in accordance with POSIX behaviour.\n" } ] }, "JOBS": { "content": "If the MONITOR option is set, an interactive shell associates a job with each pipeline. It\nkeeps a table of current jobs, printed by the jobs command, and assigns them small integer\nnumbers. When a job is started asynchronously with `&', the shell prints a line to standard\nerror which looks like:\n\n[1] 1234\n\nindicating that the job which was started asynchronously was job number 1 and had one\n(top-level) process, whose process ID was 1234.\n\nIf a job is started with `&|' or `&!', then that job is immediately disowned. After startup,\nit does not have a place in the job table, and is not subject to the job control features de‐\nscribed here.\n\nIf you are running a job and wish to do something else you may hit the key ^Z (control-Z)\nwhich sends a TSTP signal to the current job: this key may be redefined by the susp option\nof the external stty command. The shell will then normally indicate that the job has been\n`suspended', and print another prompt. You can then manipulate the state of this job,\nputting it in the background with the bg command, or run some other commands and then eventu‐\nally bring the job back into the foreground with the foreground command fg. A ^Z takes ef‐\nfect immediately and is like an interrupt in that pending output and unread input are dis‐\ncarded when it is typed.\n\nA job being run in the background will suspend if it tries to read from the terminal.\n\nNote that if the job running in the foreground is a shell function, then suspending it will\nhave the effect of causing the shell to fork. This is necessary to separate the function's\nstate from that of the parent shell performing the job control, so that the latter can return\nto the command line prompt. As a result, even if fg is used to continue the job the function\nwill no longer be part of the parent shell, and any variables set by the function will not be\nvisible in the parent shell. Thus the behaviour is different from the case where the func‐\ntion was never suspended. Zsh is different from many other shells in this regard.\n\nOne additional side effect is that use of disown with a job created by suspending shell code\nin this fashion is delayed: the job can only be disowned once any process started from the\nparent shell has terminated. At that point, the disowned job disappears silently from the\njob list.\n\nThe same behaviour is found when the shell is executing code as the right hand side of a\npipeline or any complex shell construct such as if, for, etc., in order that the entire block\nof code can be managed as a single job. Background jobs are normally allowed to produce out‐\nput, but this can be disabled by giving the command `stty tostop'. If you set this tty op‐\ntion, then background jobs will suspend when they try to produce output like they do when\nthey try to read input.\n\nWhen a command is suspended and continued later with the fg or wait builtins, zsh restores\ntty modes that were in effect when it was suspended. This (intentionally) does not apply if\nthe command is continued via `kill -CONT', nor when it is continued with bg.\n\nThere are several ways to refer to jobs in the shell. A job can be referred to by the\nprocess ID of any process of the job or by one of the following:\n\n%number\nThe job with the given number.\n%string\nThe last job whose command line begins with string.\n%?string\nThe last job whose command line contains string.\n%% Current job.\n%+ Equivalent to `%%'.\n%- Previous job.\n\nThe shell learns immediately whenever a process changes state. It normally informs you when‐\never a job becomes blocked so that no further progress is possible. If the NOTIFY option is\nnot set, it waits until just before it prints a prompt before it informs you. All such noti‐\nfications are sent directly to the terminal, not to the standard output or standard error.\n\nWhen the monitor mode is on, each background job that completes triggers any trap set for\nCHLD.\n\nWhen you try to leave the shell while jobs are running or suspended, you will be warned that\n`You have suspended (running) jobs'. You may use the jobs command to see what they are. If\nyou do this or immediately try to exit again, the shell will not warn you a second time; the\nsuspended jobs will be terminated, and the running jobs will be sent a SIGHUP signal, if the\nHUP option is set.\n\nTo avoid having the shell terminate the running jobs, either use the nohup command (see no‐\nhup(1)) or the disown builtin.\n", "subsections": [] }, "SIGNALS": { "content": "The INT and QUIT signals for an invoked command are ignored if the command is followed by `&'\nand the MONITOR option is not active. The shell itself always ignores the QUIT signal. Oth‐\nerwise, signals have the values inherited by the shell from its parent (but see the TRAPNAL\nspecial functions in the section `Functions').\n\nCertain jobs are run asynchronously by the shell other than those explicitly put into the\nbackground; even in cases where the shell would usually wait for such jobs, an explicit exit\ncommand or exit due to the option ERREXIT will cause the shell to exit without waiting. Ex‐\namples of such asynchronous jobs are process substitution, see the section PROCESS SUBSTITU‐\nTION in the zshexpn(1) manual page, and the handler processes for multios, see the section\nMULTIOS in the zshmisc(1) manual page.\n", "subsections": [] }, "ARITHMETIC EVALUATION": { "content": "The shell can perform integer and floating point arithmetic, either using the builtin let, or\nvia a substitution of the form $((...)). For integers, the shell is usually compiled to use\n8-byte precision where this is available, otherwise precision is 4 bytes. This can be\ntested, for example, by giving the command `print - $(( 12345678901 ))'; if the number ap‐\npears unchanged, the precision is at least 8 bytes. Floating point arithmetic always uses\nthe `double' type with whatever corresponding precision is provided by the compiler and the\nlibrary.\n\nThe let builtin command takes arithmetic expressions as arguments; each is evaluated sepa‐\nrately. Since many of the arithmetic operators, as well as spaces, require quoting, an al‐\nternative form is provided: for any command which begins with a `((', all the characters un‐\ntil a matching `))' are treated as a quoted expression and arithmetic expansion performed as\nfor an argument of let. More precisely, `((...))' is equivalent to `let \"...\"'. The return\nstatus is 0 if the arithmetic value of the expression is non-zero, 1 if it is zero, and 2 if\nan error occurred.\n\nFor example, the following statement\n\n(( val = 2 + 1 ))\n\nis equivalent to\n\nlet \"val = 2 + 1\"\n\nboth assigning the value 3 to the shell variable val and returning a zero status.\n\nIntegers can be in bases other than 10. A leading `0x' or `0X' denotes hexadecimal and a\nleading `0b' or `0B' binary. Integers may also be of the form `base#n', where base is a dec‐\nimal number between two and thirty-six representing the arithmetic base and n is a number in\nthat base (for example, `16#ff' is 255 in hexadecimal). The base# may also be omitted, in\nwhich case base 10 is used. For backwards compatibility the form `[base]n' is also accepted.\n\nAn integer expression or a base given in the form `base#n' may contain underscores (`') af‐\nter the leading digit for visual guidance; these are ignored in computation. Examples are\n1000000 or 0xffffffff which are equivalent to 1000000 and 0xffffffff respectively.\n\nIt is also possible to specify a base to be used for output in the form `[#base]', for exam‐\nple `[#16]'. This is used when outputting arithmetical substitutions or when assigning to\nscalar parameters, but an explicitly defined integer or floating point parameter will not be\naffected. If an integer variable is implicitly defined by an arithmetic expression, any base\nspecified in this way will be set as the variable's output arithmetic base as if the option\n`-i base' to the typeset builtin had been used. The expression has no precedence and if it\noccurs more than once in a mathematical expression, the last encountered is used. For clar‐\nity it is recommended that it appear at the beginning of an expression. As an example:\n\ntypeset -i 16 y\nprint $(( [#8] x = 32, y = 32 ))\nprint $x $y\n\noutputs first `8#40', the rightmost value in the given output base, and then `8#40 16#20',\nbecause y has been explicitly declared to have output base 16, while x (assuming it does not\nalready exist) is implicitly typed by the arithmetic evaluation, where it acquires the output\nbase 8.\n\nThe base may be replaced or followed by an underscore, which may itself be followed by a pos‐\nitive integer (if it is missing the value 3 is used). This indicates that underscores should\nbe inserted into the output string, grouping the number for visual clarity. The following\ninteger specifies the number of digits to group together. For example:\n\nsetopt cbases\nprint $(( [#164] 65536 2 ))\n\noutputs `0x100000000'.\n\nThe feature can be used with floating point numbers, in which case the base must be omitted;\ngrouping is away from the decimal point. For example,\n\nzmodload zsh/mathfunc\nprint $(( [#] sqrt(1e7) ))\n\noutputs `3162.2776601683795' (the number of decimal places shown may vary).\n\nIf the CBASES option is set, hexadecimal numbers are output in the standard C format, for\nexample `0xFF' instead of the usual `16#FF'. If the option OCTALZEROES is also set (it is\nnot by default), octal numbers will be treated similarly and hence appear as `077' instead of\n`8#77'. This option has no effect on the output of bases other than hexadecimal and octal,\nand these formats are always understood on input.\n\nWhen an output base is specified using the `[#base]' syntax, an appropriate base prefix will\nbe output if necessary, so that the value output is valid syntax for input. If the # is dou‐\nbled, for example `[##16]', then no base prefix is output.\n\nFloating point constants are recognized by the presence of a decimal point or an exponent.\nThe decimal point may be the first character of the constant, but the exponent character e or\nE may not, as it will be taken for a parameter name. All numeric parts (before and after the\ndecimal point and in the exponent) may contain underscores after the leading digit for visual\nguidance; these are ignored in computation.\n\nAn arithmetic expression uses nearly the same syntax and associativity of expressions as in\nC.\n\nIn the native mode of operation, the following operators are supported (listed in decreasing\norder of precedence):\n", "subsections": [ { "name": "+ - ! ~ ++ --", "content": "unary plus/minus, logical NOT, complement, {pre,post}{in,de}crement\n<< >> bitwise shift left, right\n& bitwise AND\n^ bitwise XOR\n| bitwise OR\nexponentiation\n* / % multiplication, division, modulus (remainder)\n+ - addition, subtraction" }, { "name": "< > <= >=", "content": "comparison\n== != equality and inequality\n&& logical AND\n|| ^^ logical OR, XOR\n? : ternary operator\n= += -= *= /= %= &= ^= |= <<= >>= &&= ||= ^^= =\nassignment\n, comma operator\n\nThe operators `&&', `||', `&&=', and `||=' are short-circuiting, and only one of the latter\ntwo expressions in a ternary operator is evaluated. Note the precedence of the bitwise AND,\nOR, and XOR operators.\n\nWith the option CPRECEDENCES the precedences (but no other properties) of the operators are\naltered to be the same as those in most other languages that support the relevant operators:\n" }, { "name": "+ - ! ~ ++ --", "content": "unary plus/minus, logical NOT, complement, {pre,post}{in,de}crement\nexponentiation\n* / % multiplication, division, modulus (remainder)\n+ - addition, subtraction\n<< >> bitwise shift left, right" }, { "name": "< > <= >=", "content": "comparison\n== != equality and inequality\n& bitwise AND\n^ bitwise XOR\n| bitwise OR\n&& logical AND\n^^ logical XOR\n|| logical OR\n? : ternary operator\n= += -= *= /= %= &= ^= |= <<= >>= &&= ||= ^^= =\nassignment\n, comma operator\n\nNote the precedence of exponentiation in both cases is below that of unary operators, hence\n`-32' evaluates as `9', not `-9'. Use parentheses where necessary: `-(32)'. This is for\ncompatibility with other shells.\n\nMathematical functions can be called with the syntax `func(args)', where the function decides\nif the args is used as a string or a comma-separated list of arithmetic expressions. The\nshell currently defines no mathematical functions by default, but the module zsh/mathfunc may\nbe loaded with the zmodload builtin to provide standard floating point mathematical func‐\ntions.\n\nAn expression of the form `##x' where x is any character sequence such as `a', `^A', or\n`\\M-\\C-x' gives the value of this character and an expression of the form `#name' gives the\nvalue of the first character of the contents of the parameter name. Character values are ac‐\ncording to the character set used in the current locale; for multibyte character handling the\noption MULTIBYTE must be set. Note that this form is different from `$#name', a standard pa‐\nrameter substitution which gives the length of the parameter name. `#\\' is accepted instead\nof `##', but its use is deprecated.\n\nNamed parameters and subscripted arrays can be referenced by name within an arithmetic ex‐\npression without using the parameter expansion syntax. For example,\n\n((val2 = val1 * 2))\n\nassigns twice the value of $val1 to the parameter named val2.\n\nAn internal integer representation of a named parameter can be specified with the integer\nbuiltin. Arithmetic evaluation is performed on the value of each assignment to a named pa‐\nrameter declared integer in this manner. Assigning a floating point number to an integer re‐\nsults in rounding towards zero.\n\nLikewise, floating point numbers can be declared with the float builtin; there are two types,\ndiffering only in their output format, as described for the typeset builtin. The output for‐\nmat can be bypassed by using arithmetic substitution instead of the parameter substitution,\ni.e. `${float}' uses the defined format, but `$((float))' uses a generic floating point for‐\nmat.\n\nPromotion of integer to floating point values is performed where necessary. In addition, if\nany operator which requires an integer (`&', `|', `^', `<<', `>>' and their equivalents with\nassignment) is given a floating point argument, it will be silently rounded towards zero ex‐\ncept for `~' which rounds down.\n\nUsers should beware that, in common with many other programming languages but not software\ndesigned for calculation, the evaluation of an expression in zsh is taken a term at a time\nand promotion of integers to floating point does not occur in terms only containing integers.\nA typical result of this is that a division such as 6/8 is truncated, in this being rounded\ntowards 0. The FORCEFLOAT shell option can be used in scripts or functions where floating\npoint evaluation is required throughout.\n\nScalar variables can hold integer or floating point values at different times; there is no\nmemory of the numeric type in this case.\n\nIf a variable is first assigned in a numeric context without previously being declared, it\nwill be implicitly typed as integer or float and retain that type either until the type is\nexplicitly changed or until the end of the scope. This can have unforeseen consequences.\nFor example, in the loop\n\nfor (( f = 0; f < 1; f += 0.1 )); do\n# use $f\ndone\n\nif f has not already been declared, the first assignment will cause it to be created as an\ninteger, and consequently the operation `f += 0.1' will always cause the result to be trun‐\ncated to zero, so that the loop will fail. A simple fix would be to turn the initialization\ninto `f = 0.0'. It is therefore best to declare numeric variables with explicit types.\n" } ] }, "CONDITIONAL EXPRESSIONS": { "content": "A conditional expression is used with the [[ compound command to test attributes of files and\nto compare strings. Each expression can be constructed from one or more of the following\nunary or binary expressions:\n", "subsections": [ { "name": "-a", "content": "true if file exists.\n", "flag": "-a" }, { "name": "-b", "content": "true if file exists and is a block special file.\n", "flag": "-b" }, { "name": "-c", "content": "true if file exists and is a character special file.\n", "flag": "-c" }, { "name": "-d", "content": "true if file exists and is a directory.\n", "flag": "-d" }, { "name": "-e", "content": "true if file exists.\n", "flag": "-e" }, { "name": "-f", "content": "true if file exists and is a regular file.\n", "flag": "-f" }, { "name": "-g", "content": "true if file exists and has its setgid bit set.\n", "flag": "-g" }, { "name": "-h", "content": "true if file exists and is a symbolic link.\n", "flag": "-h" }, { "name": "-k", "content": "true if file exists and has its sticky bit set.\n", "flag": "-k" }, { "name": "-n", "content": "true if length of string is non-zero.\n", "flag": "-n" }, { "name": "-o", "content": "true if option named option is on. option may be a single character, in which case it\nis a single letter option name. (See the section `Specifying Options'.)\n\nWhen no option named option exists, and the POSIXBUILTINS option hasn't been set, re‐\nturn 3 with a warning. If that option is set, return 1 with no warning.\n", "flag": "-o" }, { "name": "-p", "content": "true if file exists and is a FIFO special file (named pipe).\n", "flag": "-p" }, { "name": "-r", "content": "true if file exists and is readable by current process.\n", "flag": "-r" }, { "name": "-s", "content": "true if file exists and has size greater than zero.\n", "flag": "-s" }, { "name": "-t", "content": "(note: fd is not optional)\n", "flag": "-t" }, { "name": "-u", "content": "true if file exists and has its setuid bit set.\n", "flag": "-u" }, { "name": "-v", "content": "true if shell variable varname is set.\n", "flag": "-v" }, { "name": "-w", "content": "true if file exists and is writable by current process.\n", "flag": "-w" }, { "name": "-x", "content": "true if file exists and is executable by current process. If file exists and is a di‐\nrectory, then the current process has permission to search in the directory.\n", "flag": "-x" }, { "name": "-z", "content": "true if length of string is zero.\n", "flag": "-z" }, { "name": "-L", "content": "true if file exists and is a symbolic link.\n", "flag": "-L" }, { "name": "-O", "content": "true if file exists and is owned by the effective user ID of this process.\n", "flag": "-O" }, { "name": "-G", "content": "true if file exists and its group matches the effective group ID of this process.\n", "flag": "-G" }, { "name": "-S", "content": "true if file exists and is a socket.\n", "flag": "-S" }, { "name": "-N", "content": "true if file exists and its access time is not newer than its modification time.\n\nfile1 -nt file2\ntrue if file1 exists and is newer than file2.\n\nfile1 -ot file2\ntrue if file1 exists and is older than file2.\n\nfile1 -ef file2\ntrue if file1 and file2 exist and refer to the same file.\n\nstring = pattern\nstring == pattern\ntrue if string matches pattern. The two forms are exactly equivalent. The `=' form\nis the traditional shell syntax (and hence the only one generally used with the test\nand [ builtins); the `==' form provides compatibility with other sorts of computer\nlanguage.\n\nstring != pattern\ntrue if string does not match pattern.\n\nstring =~ regexp\ntrue if string matches the regular expression regexp. If the option REMATCHPCRE is\nset regexp is tested as a PCRE regular expression using the zsh/pcre module, else it\nis tested as a POSIX extended regular expression using the zsh/regex module. Upon\nsuccessful match, some variables will be updated; no variables are changed if the\nmatching fails.\n\nIf the option BASHREMATCH is not set the scalar parameter MATCH is set to the sub‐\nstring that matched the pattern and the integer parameters MBEGIN and MEND to the in‐\ndex of the start and end, respectively, of the match in string, such that if string is\ncontained in variable var the expression `${var[$MBEGIN,$MEND]}' is identical to\n`$MATCH'. The setting of the option KSHARRAYS is respected. Likewise, the array\nmatch is set to the substrings that matched parenthesised subexpressions and the ar‐\nrays mbegin and mend to the indices of the start and end positions, respectively, of\nthe substrings within string. The arrays are not set if there were no parenthesised\nsubexpressions. For example, if the string `a short string' is matched against the\nregular expression `s(...)t', then (assuming the option KSHARRAYS is not set) MATCH,\nMBEGIN and MEND are `short', 3 and 7, respectively, while match, mbegin and mend are\nsingle entry arrays containing the strings `hor', `4' and `6', respectively.\n\nIf the option BASHREMATCH is set the array BASHREMATCH is set to the substring that\nmatched the pattern followed by the substrings that matched parenthesised subexpres‐\nsions within the pattern.\n\nstring1 < string2\ntrue if string1 comes before string2 based on ASCII value of their characters.\n\nstring1 > string2\ntrue if string1 comes after string2 based on ASCII value of their characters.\n\nexp1 -eq exp2\ntrue if exp1 is numerically equal to exp2. Note that for purely numeric comparisons\nuse of the ((...)) builtin described in the section `ARITHMETIC EVALUATION' is more\nconvenient than conditional expressions.\n\nexp1 -ne exp2\ntrue if exp1 is numerically not equal to exp2.\n\nexp1 -lt exp2\ntrue if exp1 is numerically less than exp2.\n\nexp1 -gt exp2\ntrue if exp1 is numerically greater than exp2.\n\nexp1 -le exp2\ntrue if exp1 is numerically less than or equal to exp2.\n\nexp1 -ge exp2\ntrue if exp1 is numerically greater than or equal to exp2.\n\n( exp )\ntrue if exp is true.\n\n! exp true if exp is false.\n\nexp1 && exp2\ntrue if exp1 and exp2 are both true.\n\nexp1 || exp2\ntrue if either exp1 or exp2 is true.\n\nFor compatibility, if there is a single argument that is not syntactically significant, typi‐\ncally a variable, the condition is treated as a test for whether the expression expands as a\nstring of non-zero length. In other words, [[ $var ]] is the same as [[ -n $var ]]. It is\nrecommended that the second, explicit, form be used where possible.\n\nNormal shell expansion is performed on the file, string and pattern arguments, but the result\nof each expansion is constrained to be a single word, similar to the effect of double quotes.\n\nFilename generation is not performed on any form of argument to conditions. However, it can\nbe forced in any case where normal shell expansion is valid and when the option EXTENDEDGLOB\nis in effect by using an explicit glob qualifier of the form (#q) at the end of the string.\nA normal glob qualifier expression may appear between the `q' and the closing parenthesis; if\nnone appears the expression has no effect beyond causing filename generation. The results of\nfilename generation are joined together to form a single word, as with the results of other\nforms of expansion.\n\nThis special use of filename generation is only available with the [[ syntax. If the condi‐\ntion occurs within the [ or test builtin commands then globbing occurs instead as part of\nnormal command line expansion before the condition is evaluated. In this case it may gener‐\nate multiple words which are likely to confuse the syntax of the test command.\n\nFor example,\n\n[[ -n file*(#qN) ]]\n\nproduces status zero if and only if there is at least one file in the current directory be‐\nginning with the string `file'. The globbing qualifier N ensures that the expression is\nempty if there is no matching file.\n\nPattern metacharacters are active for the pattern arguments; the patterns are the same as\nthose used for filename generation, see zshexpn(1), but there is no special behaviour of `/'\nnor initial dots, and no glob qualifiers are allowed.\n\nIn each of the above expressions, if file is of the form `/dev/fd/n', where n is an integer,\nthen the test applied to the open file whose descriptor number is n, even if the underlying\nsystem does not support the /dev/fd directory.\n\nIn the forms which do numeric comparison, the expressions exp undergo arithmetic expansion as\nif they were enclosed in $((...)).\n\nFor example, the following:\n\n[[ ( -f foo || -f bar ) && $report = y* ]] && print File exists.\n\ntests if either file foo or file bar exists, and if so, if the value of the parameter report\nbegins with `y'; if the complete condition is true, the message `File exists.' is printed.\n", "flag": "-N" } ] }, "EXPANSION OF PROMPT SEQUENCES": { "content": "Prompt sequences undergo a special form of expansion. This type of expansion is also avail‐\nable using the -P option to the print builtin.\n\nIf the PROMPTSUBST option is set, the prompt string is first subjected to parameter expan‐\nsion, command substitution and arithmetic expansion. See zshexpn(1).\n\nCertain escape sequences may be recognised in the prompt string.\n\nIf the PROMPTBANG option is set, a `!' in the prompt is replaced by the current history\nevent number. A literal `!' may then be represented as `!!'.\n\nIf the PROMPTPERCENT option is set, certain escape sequences that start with `%' are ex‐\npanded. Many escapes are followed by a single character, although some of these take an op‐\ntional integer argument that should appear between the `%' and the next character of the se‐\nquence. More complicated escape sequences are available to provide conditional expansion.\n", "subsections": [] }, "SIMPLE PROMPT ESCAPES": { "content": "", "subsections": [ { "name": "Special characters", "content": "%% A `%'.\n\n%) A `)'.\n" }, { "name": "Login information", "content": "%l The line (tty) the user is logged in on, without `/dev/' prefix. If the name starts\nwith `/dev/tty', that prefix is stripped.\n\n%M The full machine hostname.\n\n%m The hostname up to the first `.'. An integer may follow the `%' to specify how many\ncomponents of the hostname are desired. With a negative integer, trailing components\nof the hostname are shown.\n\n%n $USERNAME.\n\n%y The line (tty) the user is logged in on, without `/dev/' prefix. This does not treat\n`/dev/tty' names specially.\n" }, { "name": "Shell state", "content": "%# A `#' if the shell is running with privileges, a `%' if not. Equivalent to\n`%(!.#.%%)'. The definition of `privileged', for these purposes, is that either the\neffective user ID is zero, or, if POSIX.1e capabilities are supported, that at least\none capability is raised in either the Effective or Inheritable capability vectors.\n\n%? The return status of the last command executed just before the prompt.\n\n% The status of the parser, i.e. the shell constructs (like `if' and `for') that have\nbeen started on the command line. If given an integer number that many strings will be\nprinted; zero or negative or no integer means print as many as there are. This is\nmost useful in prompts PS2 for continuation lines and PS4 for debugging with the\nXTRACE option; in the latter case it will also work non-interactively.\n\n%^ The status of the parser in reverse. This is the same as `%' other than the order of\nstrings. It is often used in RPS2.\n\n%d\n%/ Current working directory. If an integer follows the `%', it specifies a number of\ntrailing components of the current working directory to show; zero means the whole\npath. A negative integer specifies leading components, i.e. %-1d specifies the first\ncomponent.\n\n%~ As %d and %/, but if the current working directory starts with $HOME, that part is re‐\nplaced by a `~'. Furthermore, if it has a named directory as its prefix, that part is\nreplaced by a `~' followed by the name of the directory, but only if the result is\nshorter than the full path; see Dynamic and Static named directories in zshexpn(1).\n\n%e Evaluation depth of the current sourced file, shell function, or eval. This is incre‐\nmented or decremented every time the value of %N is set or reverted to a previous\nvalue, respectively. This is most useful for debugging as part of $PS4.\n\n%h\n%! Current history event number.\n\n%i The line number currently being executed in the script, sourced file, or shell func‐\ntion given by %N. This is most useful for debugging as part of $PS4.\n\n%I The line number currently being executed in the file %x. This is similar to %i, but\nthe line number is always a line number in the file where the code was defined, even\nif the code is a shell function.\n\n%j The number of jobs.\n\n%L The current value of $SHLVL.\n\n%N The name of the script, sourced file, or shell function that zsh is currently execut‐\ning, whichever was started most recently. If there is none, this is equivalent to the\nparameter $0. An integer may follow the `%' to specify a number of trailing path com‐\nponents to show; zero means the full path. A negative integer specifies leading com‐\nponents.\n\n%x The name of the file containing the source code currently being executed. This be‐\nhaves as %N except that function and eval command names are not shown, instead the\nfile where they were defined.\n\n%c\n%.\n%C Trailing component of the current working directory. An integer may follow the `%' to\nget more than one component. Unless `%C' is used, tilde contraction is performed\nfirst. These are deprecated as %c and %C are equivalent to %1~ and %1/, respectively,\nwhile explicit positive integers have the same effect as for the latter two sequences.\n" }, { "name": "Date and time", "content": "%D The date in yy-mm-dd format.\n\n%T Current time of day, in 24-hour format.\n\n%t\n%@ Current time of day, in 12-hour, am/pm format.\n\n%* Current time of day in 24-hour format, with seconds.\n\n%w The date in day-dd format.\n\n%W The date in mm/dd/yy format.\n\n%D{string}\nstring is formatted using the strftime function. See strftime(3) for more details.\nVarious zsh extensions provide numbers with no leading zero or space if the number is\na single digit:\n\n%f a day of the month\n%K the hour of the day on the 24-hour clock\n%L the hour of the day on the 12-hour clock\n\nIn addition, if the system supports the POSIX gettimeofday system call, %. provides\ndecimal fractions of a second since the epoch with leading zeroes. By default three\ndecimal places are provided, but a number of digits up to 9 may be given following the\n%; hence %6. outputs microseconds, and %9. outputs nanoseconds. (The latter requires\na nanosecond-precision clockgettime; systems lacking this will return a value multi‐\nplied by the appropriate power of 10.) A typical example of this is the format\n`%D{%H:%M:%S.%.}'.\n\nThe GNU extension %N is handled as a synonym for %9..\n\nAdditionally, the GNU extension that a `-' between the % and the format character\ncauses a leading zero or space to be stripped is handled directly by the shell for the\nformat characters d, f, H, k, l, m, M, S and y; any other format characters are pro‐\nvided to the system's strftime(3) with any leading `-' present, so the handling is\nsystem dependent. Further GNU (or other) extensions are also passed to strftime(3)\nand may work if the system supports them.\n" }, { "name": "Visual effects", "content": "%B (%b)\nStart (stop) boldface mode.\n\n%E Clear to end of line.\n\n%U (%u)\nStart (stop) underline mode.\n\n%S (%s)\nStart (stop) standout mode.\n\n%F (%f)\nStart (stop) using a different foreground colour, if supported by the terminal. The\ncolour may be specified two ways: either as a numeric argument, as normal, or by a se‐\nquence in braces following the %F, for example %F{red}. In the latter case the values\nallowed are as described for the fg zlehighlight attribute; see Character Highlight‐\ning in zshzle(1). This means that numeric colours are allowed in the second format\nalso.\n\n%K (%k)\nStart (stop) using a different bacKground colour. The syntax is identical to that for\n%F and %f.\n\n%{...%}\nInclude a string as a literal escape sequence. The string within the braces should\nnot change the cursor position. Brace pairs can nest.\n\nA positive numeric argument between the % and the { is treated as described for %G be‐\nlow.\n\n%G Within a %{...%} sequence, include a `glitch': that is, assume that a single character\nwidth will be output. This is useful when outputting characters that otherwise cannot\nbe correctly handled by the shell, such as the alternate character set on some termi‐\nnals. The characters in question can be included within a %{...%} sequence together\nwith the appropriate number of %G sequences to indicate the correct width. An integer\nbetween the `%' and `G' indicates a character width other than one. Hence %{seq%2G%}\noutputs seq and assumes it takes up the width of two standard characters.\n\nMultiple uses of %G accumulate in the obvious fashion; the position of the %G is unim‐\nportant. Negative integers are not handled.\n\nNote that when prompt truncation is in use it is advisable to divide up output into\nsingle characters within each %{...%} group so that the correct truncation point can\nbe found.\n" } ] }, "CONDITIONAL SUBSTRINGS IN PROMPTS": { "content": "%v The value of the first element of the psvar array parameter. Following the `%' with\nan integer gives that element of the array. Negative integers count from the end of\nthe array.\n\n%(x.true-text.false-text)\nSpecifies a ternary expression. The character following the x is arbitrary; the same\ncharacter is used to separate the text for the `true' result from that for the `false'\nresult. This separator may not appear in the true-text, except as part of a %-escape\nsequence. A `)' may appear in the false-text as `%)'. true-text and false-text may\nboth contain arbitrarily-nested escape sequences, including further ternary expres‐\nsions.\n\nThe left parenthesis may be preceded or followed by a positive integer n, which de‐\nfaults to zero. A negative integer will be multiplied by -1, except as noted below\nfor `l'. The test character x may be any of the following:\n\n! True if the shell is running with privileges.\n# True if the effective uid of the current process is n.\n? True if the exit status of the last command was n.\nTrue if at least n shell constructs were started.\nC\n/ True if the current absolute path has at least n elements relative to the root\ndirectory, hence / is counted as 0 elements.\nc\n.\n~ True if the current path, with prefix replacement, has at least n elements rel‐\native to the root directory, hence / is counted as 0 elements.\nD True if the month is equal to n (January = 0).\nd True if the day of the month is equal to n.\ne True if the evaluation depth is at least n.\ng True if the effective gid of the current process is n.\nj True if the number of jobs is at least n.\nL True if the SHLVL parameter is at least n.\nl True if at least n characters have already been printed on the current line.\nWhen n is negative, true if at least abs(n) characters remain before the oppo‐\nsite margin (thus the left margin for RPROMPT).\nS True if the SECONDS parameter is at least n.\nT True if the time in hours is equal to n.\nt True if the time in minutes is equal to n.\nv True if the array psvar has at least n elements.\nV True if element n of the array psvar is set and non-empty.\nw True if the day of the week is equal to n (Sunday = 0).\n\n%string>\n%[xstring]\nSpecifies truncation behaviour for the remainder of the prompt string. The third,\ndeprecated, form is equivalent to `%xstringx', i.e. x may be `<' or `>'. The string\nwill be displayed in place of the truncated portion of any string; note this does not\nundergo prompt expansion.\n\nThe numeric argument, which in the third form may appear immediately after the `[',\nspecifies the maximum permitted length of the various strings that can be displayed in\nthe prompt. In the first two forms, this numeric argument may be negative, in which\ncase the truncation length is determined by subtracting the absolute value of the nu‐\nmeric argument from the number of character positions remaining on the current prompt\nline. If this results in a zero or negative length, a length of 1 is used. In other\nwords, a negative argument arranges that after truncation at least n characters remain\nbefore the right margin (left margin for RPROMPT).\n\nThe forms with `<' truncate at the left of the string, and the forms with `>' truncate\nat the right of the string. For example, if the current directory is `/home/pike',\nthe prompt `%8<..<%/' will expand to `..e/pike'. In this string, the terminating\ncharacter (`<', `>' or `]'), or in fact any character, may be quoted by a preceding\n`\\'; note when using print -P, however, that this must be doubled as the string is\nalso subject to standard print processing, in addition to any backslashes removed by a\ndouble quoted string: the worst case is therefore `print -P \"%<\\\\\\\\<<...\"'.\n\nIf the string is longer than the specified truncation length, it will appear in full,\ncompletely replacing the truncated string.\n\nThe part of the prompt string to be truncated runs to the end of the string, or to the\nend of the next enclosing group of the `%(' construct, or to the next truncation en‐\ncountered at the same grouping level (i.e. truncations inside a `%(' are separate),\nwhich ever comes first. In particular, a truncation with argument zero (e.g., `%<<')\nmarks the end of the range of the string to be truncated while turning off truncation\nfrom there on. For example, the prompt `%10<...<%~%<<%# ' will print a truncated rep‐\nresentation of the current directory, followed by a `%' or `#', followed by a space.\nWithout the `%<<', those two characters would be included in the string to be trun‐\ncated. Note that `%-0<<' is not equivalent to `%<<' but specifies that the prompt is\ntruncated at the right margin.\n\nTruncation applies only within each individual line of the prompt, as delimited by em‐\nbedded newlines (if any). If the total length of any line of the prompt after trunca‐\ntion is greater than the terminal width, or if the part to be truncated contains em‐\nbedded newlines, truncation behavior is undefined and may change in a future version\nof the shell. Use `%-n(l.true-text.false-text)' to remove parts of the prompt when\nthe available space is less than n.\n\n\n\nZSHEXPN(1) General Commands Manual ZSHEXPN(1)\n\n\n", "subsections": [] }, "HISTORY EXPANSION": { "content": "History expansion allows you to use words from previous command lines in the command line you\nare typing. This simplifies spelling corrections and the repetition of complicated commands\nor arguments.\n\nImmediately before execution, each command is saved in the history list, the size of which is\ncontrolled by the HISTSIZE parameter. The one most recent command is always retained in any\ncase. Each saved command in the history list is called a history event and is assigned a\nnumber, beginning with 1 (one) when the shell starts up. The history number that you may see\nin your prompt (see EXPANSION OF PROMPT SEQUENCES in zshmisc(1)) is the number that is to be\nassigned to the next command.\n", "subsections": [ { "name": "Overview", "content": "A history expansion begins with the first character of the histchars parameter, which is `!'\nby default, and may occur anywhere on the command line, including inside double quotes (but\nnot inside single quotes '...' or C-style quotes $'...' nor when escaped with a backslash).\n\nThe first character is followed by an optional event designator (see the section `Event Des‐\nignators') and then an optional word designator (the section `Word Designators'); if neither\nof these designators is present, no history expansion occurs.\n\nInput lines containing history expansions are echoed after being expanded, but before any\nother expansions take place and before the command is executed. It is this expanded form\nthat is recorded as the history event for later references.\n\nHistory expansions do not nest.\n\nBy default, a history reference with no event designator refers to the same event as any pre‐\nceding history reference on that command line; if it is the only history reference in a com‐\nmand, it refers to the previous command. However, if the option CSHJUNKIEHISTORY is set,\nthen every history reference with no event specification always refers to the previous com‐\nmand.\n\nFor example, `!' is the event designator for the previous command, so `!!:1' always refers to\nthe first word of the previous command, and `!!$' always refers to the last word of the pre‐\nvious command. With CSHJUNKIEHISTORY set, then `!:1' and `!$' function in the same manner\nas `!!:1' and `!!$', respectively. Conversely, if CSHJUNKIEHISTORY is unset, then `!:1'\nand `!$' refer to the first and last words, respectively, of the same event referenced by the\nnearest other history reference preceding them on the current command line, or to the previ‐\nous command if there is no preceding reference.\n\nThe character sequence `^foo^bar' (where `^' is actually the second character of the\nhistchars parameter) repeats the last command, replacing the string foo with bar. More pre‐\ncisely, the sequence `^foo^bar^' is synonymous with `!!:s^foo^bar^', hence other modifiers\n(see the section `Modifiers') may follow the final `^'. In particular, `^foo^bar^:G' per‐\nforms a global substitution.\n\nIf the shell encounters the character sequence `!\"' in the input, the history mechanism is\ntemporarily disabled until the current list (see zshmisc(1)) is fully parsed. The `!\"' is\nremoved from the input, and any subsequent `!' characters have no special significance.\n\nA less convenient but more comprehensible form of command history support is provided by the\nfc builtin.\n" }, { "name": "Event Designators", "content": "An event designator is a reference to a command-line entry in the history list. In the list\nbelow, remember that the initial `!' in each item may be changed to another character by set‐\nting the histchars parameter.\n\n! Start a history expansion, except when followed by a blank, newline, `=' or `('. If\nfollowed immediately by a word designator (see the section `Word Designators'), this\nforms a history reference with no event designator (see the section `Overview').\n\n!! Refer to the previous command. By itself, this expansion repeats the previous com‐\nmand.\n\n!n Refer to command-line n.\n\n!-n Refer to the current command-line minus n.\n\n!str Refer to the most recent command starting with str.\n\n!?str[?]\nRefer to the most recent command containing str. The trailing `?' is necessary if\nthis reference is to be followed by a modifier or followed by any text that is not to\nbe considered part of str.\n\n!# Refer to the current command line typed in so far. The line is treated as if it were\ncomplete up to and including the word before the one with the `!#' reference.\n\n!{...} Insulate a history reference from adjacent characters (if necessary).\n" }, { "name": "Word Designators", "content": "A word designator indicates which word or words of a given command line are to be included in\na history reference. A `:' usually separates the event specification from the word designa‐\ntor. It may be omitted only if the word designator begins with a `^', `$', `*', `-' or `%'.\nWord designators include:\n\n0 The first input word (command).\nn The nth argument.\n^ The first argument. That is, 1.\n$ The last argument.\n% The word matched by (the most recent) ?str search.\nx-y A range of words; x defaults to 0.\n* All the arguments, or a null value if there are none.\nx* Abbreviates `x-$'.\nx- Like `x*' but omitting word $.\n\nNote that a `%' word designator works only when used in one of `!%', `!:%' or `!?str?:%', and\nonly when used after a !? expansion (possibly in an earlier command). Anything else results\nin an error, although the error may not be the most obvious one.\n" }, { "name": "Modifiers", "content": "After the optional word designator, you can add a sequence of one or more of the following\nmodifiers, each preceded by a `:'. These modifiers also work on the result of filename gen‐\neration and parameter expansion, except where noted.\n\na Turn a file name into an absolute path: prepends the current directory, if necessary;\nremove `.' path segments; and remove `..' path segments and the segments that immedi‐\nately precede them.\n\nThis transformation is agnostic about what is in the filesystem, i.e. is on the logi‐\ncal, not the physical directory. It takes place in the same manner as when changing\ndirectories when neither of the options CHASEDOTS or CHASELINKS is set. For exam‐\nple, `/before/here/../after' is always transformed to `/before/after', regardless of\nwhether `/before/here' exists or what kind of object (dir, file, symlink, etc.) it is.\n\nA Turn a file name into an absolute path as the `a' modifier does, and then pass the re‐\nsult through the realpath(3) library function to resolve symbolic links.\n\nNote: on systems that do not have a realpath(3) library function, symbolic links are\nnot resolved, so on those systems `a' and `A' are equivalent.\n\nNote: foo:A and realpath(foo) are different on some inputs. For realpath(foo) seman‐\ntics, see the `P` modifier.\n\nc Resolve a command name into an absolute path by searching the command path given by\nthe PATH variable. This does not work for commands containing directory parts. Note\nalso that this does not usually work as a glob qualifier unless a file of the same\nname is found in the current directory.\n\ne Remove all but the part of the filename extension following the `.'; see the defini‐\ntion of the filename extension in the description of the r modifier below. Note that\naccording to that definition the result will be empty if the string ends with a `.'.\n\nh [ digits ]\nRemove a trailing pathname component, shortening the path by one directory level: this\nis the `head' of the pathname. This works like `dirname'. If the h is followed imme‐\ndiately (with no spaces or other separator) by any number of decimal digits, and the\nvalue of the resulting number is non-zero, that number of leading components is pre‐\nserved instead of the final component being removed. In an absolute path the leading\n`/' is the first component, so, for example, if var=/my/path/to/something, then\n${var:h3} substitutes /my/path. Consecutive `/'s are treated the same as a single\n`/'. In parameter substitution, digits may only be used if the expression is in\nbraces, so for example the short form substitution $var:h2 is treated as ${var:h}2,\nnot as ${var:h2}. No restriction applies to the use of digits in history substitution\nor globbing qualifiers. If more components are requested than are present, the entire\npath is substituted (so this does not trigger a `failed modifier' error in history ex‐\npansion).\n\nl Convert the words to all lowercase.\n\np Print the new command but do not execute it. Only works with history expansion.\n\nP Turn a file name into an absolute path, like realpath(3). The resulting path will be\nabsolute, have neither `.' nor `..' components, and refer to the same directory entry\nas the input filename.\n\nUnlike realpath(3), non-existent trailing components are permitted and preserved.\n\nq Quote the substituted words, escaping further substitutions. Works with history ex‐\npansion and parameter expansion, though for parameters it is only useful if the re‐\nsulting text is to be re-evaluated such as by eval.\n\nQ Remove one level of quotes from the substituted words.\n\nr Remove a filename extension leaving the root name. Strings with no filename extension\nare not altered. A filename extension is a `.' followed by any number of characters\n(including zero) that are neither `.' nor `/' and that continue to the end of the\nstring. For example, the extension of `foo.orig.c' is `.c', and `dir.c/foo' has no\nextension.\n\ns/l/r[/]\nSubstitute r for l as described below. The substitution is done only for the first\nstring that matches l. For arrays and for filename generation, this applies to each\nword of the expanded text. See below for further notes on substitutions.\n\nThe forms `gs/l/r' and `s/l/r/:G' perform global substitution, i.e. substitute every\noccurrence of r for l. Note that the g or :G must appear in exactly the position\nshown.\n\nSee further notes on this form of substitution below.\n\n& Repeat the previous s substitution. Like s, may be preceded immediately by a g. In\nparameter expansion the & must appear inside braces, and in filename generation it\nmust be quoted with a backslash.\n\nt [ digits ]\nRemove all leading pathname components, leaving the final component (tail). This\nworks like `basename'. Any trailing slashes are first removed. Decimal digits are\nhandled as described above for (h), but in this case that number of trailing compo‐\nnents is preserved instead of the default 1; 0 is treated the same as 1.\n\nu Convert the words to all uppercase.\n\nx Like q, but break into words at whitespace. Does not work with parameter expansion.\n\nThe s/l/r/ substitution works as follows. By default the left-hand side of substitutions are\nnot patterns, but character strings. Any character can be used as the delimiter in place of\n`/'. A backslash quotes the delimiter character. The character `&', in the right-hand-side\nr, is replaced by the text from the left-hand-side l. The `&' can be quoted with a back‐\nslash. A null l uses the previous string either from the previous l or from the contextual\nscan string s from `!?s'. You can omit the rightmost delimiter if a newline immediately fol‐\nlows r; the rightmost `?' in a context scan can similarly be omitted. Note the same record\nof the last l and r is maintained across all forms of expansion.\n\nNote that if a `&' is used within glob qualifiers an extra backslash is needed as a & is a\nspecial character in this case.\n\nAlso note that the order of expansions affects the interpretation of l and r. When used in a\nhistory expansion, which occurs before any other expansions, l and r are treated as literal\nstrings (except as explained for HISTSUBSTPATTERN below). When used in parameter expan‐\nsion, the replacement of r into the parameter's value is done first, and then any additional\nprocess, parameter, command, arithmetic, or brace references are applied, which may evaluate\nthose substitutions and expansions more than once if l appears more than once in the starting\nvalue. When used in a glob qualifier, any substitutions or expansions are performed once at\nthe time the qualifier is parsed, even before the `:s' expression itself is divided into l\nand r sides.\n\nIf the option HISTSUBSTPATTERN is set, l is treated as a pattern of the usual form de‐\nscribed in the section FILENAME GENERATION below. This can be used in all the places where\nmodifiers are available; note, however, that in globbing qualifiers parameter substitution\nhas already taken place, so parameters in the replacement string should be quoted to ensure\nthey are replaced at the correct time. Note also that complicated patterns used in globbing\nqualifiers may need the extended glob qualifier notation (#q:s/.../.../) in order for the\nshell to recognize the expression as a glob qualifier. Further, note that bad patterns in\nthe substitution are not subject to the NOBADPATTERN option so will cause an error.\n\nWhen HISTSUBSTPATTERN is set, l may start with a # to indicate that the pattern must match\nat the start of the string to be substituted, and a % may appear at the start or after an #\nto indicate that the pattern must match at the end of the string to be substituted. The % or\n# may be quoted with two backslashes.\n\nFor example, the following piece of filename generation code with the EXTENDEDGLOB option:\n\nprint -r -- *.c(#q:s/#%(#b)s(*).c/'S${match[1]}.C'/)\n\ntakes the expansion of *.c and applies the glob qualifiers in the (#q...) expression, which\nconsists of a substitution modifier anchored to the start and end of each word (#%). This\nturns on backreferences ((#b)), so that the parenthesised subexpression is available in the\nreplacement string as ${match[1]}. The replacement string is quoted so that the parameter is\nnot substituted before the start of filename generation.\n\nThe following f, F, w and W modifiers work only with parameter expansion and filename genera‐\ntion. They are listed here to provide a single point of reference for all modifiers.\n\nf Repeats the immediately (without a colon) following modifier until the resulting word\ndoesn't change any more.\n\nF:expr:\nLike f, but repeats only n times if the expression expr evaluates to n. Any character\ncan be used instead of the `:'; if `(', `[', or `{' is used as the opening delimiter,\nthe closing delimiter should be ')', `]', or `}', respectively.\n\nw Makes the immediately following modifier work on each word in the string.\n\nW:sep: Like w but words are considered to be the parts of the string that are separated by\nsep. Any character can be used instead of the `:'; opening parentheses are handled\nspecially, see above.\n" } ] }, "PROCESS SUBSTITUTION": { "content": "Each part of a command argument that takes the form `<(list)', `>(list)' or `=(list)' is sub‐\nject to process substitution. The expression may be preceded or followed by other strings\nexcept that, to prevent clashes with commonly occurring strings and patterns, the last form\nmust occur at the start of a command argument, and the forms are only expanded when first\nparsing command or assignment arguments. Process substitutions may be used following redi‐\nrection operators; in this case, the substitution must appear with no trailing string.\n\nNote that `<<(list)' is not a special syntax; it is equivalent to `< <(list)', redirecting\nstandard input from the result of process substitution. Hence all the following documenta‐\ntion applies. The second form (with the space) is recommended for clarity.\n\nIn the case of the < or > forms, the shell runs the commands in list as a subprocess of the\njob executing the shell command line. If the system supports the /dev/fd mechanism, the com‐\nmand argument is the name of the device file corresponding to a file descriptor; otherwise,\nif the system supports named pipes (FIFOs), the command argument will be a named pipe. If\nthe form with > is selected then writing on this special file will provide input for list.\nIf < is used, then the file passed as an argument will be connected to the output of the list\nprocess. For example,\n\npaste <(cut -f1 file1) <(cut -f3 file2) |\ntee >(process1) >(process2) >/dev/null\n\ncuts fields 1 and 3 from the files file1 and file2 respectively, pastes the results together,\nand sends it to the processes process1 and process2.\n\nIf =(...) is used instead of <(...), then the file passed as an argument will be the name of\na temporary file containing the output of the list process. This may be used instead of the\n< form for a program that expects to lseek (see lseek(2)) on the input file.\n\nThere is an optimisation for substitutions of the form =(<< >(process1) > >(process2)\n\nThe shell uses pipes instead of FIFOs to implement the latter two process substitutions in\nthe above example.\n\nThere is an additional problem with >(process); when this is attached to an external command,\nthe parent shell does not wait for process to finish and hence an immediately following com‐\nmand cannot rely on the results being complete. The problem and solution are the same as de‐\nscribed in the section MULTIOS in zshmisc(1). Hence in a simplified version of the example\nabove:\n\npaste <(cut -f1 file1) <(cut -f3 file2) > >(process)\n\n(note that no MULTIOS are involved), process will be run asynchronously as far as the parent\nshell is concerned. The workaround is:\n\n{ paste <(cut -f1 file1) <(cut -f3 file2) } > >(process)\n\nThe extra processes here are spawned from the parent shell which will wait for their comple‐\ntion.\n\nAnother problem arises any time a job with a substitution that requires a temporary file is\ndisowned by the shell, including the case where `&!' or `&|' appears at the end of a command\ncontaining a substitution. In that case the temporary file will not be cleaned up as the\nshell no longer has any memory of the job. A workaround is to use a subshell, for example,\n\n(mycmd =(myoutput)) &!\n\nas the forked subshell will wait for the command to finish then remove the temporary file.\n\nA general workaround to ensure a process substitution endures for an appropriate length of\ntime is to pass it as a parameter to an anonymous shell function (a piece of shell code that\nis run immediately with function scope). For example, this code:\n\n() {\nprint File $1:\ncat $1\n} =(print This be the verse)\n\noutputs something resembling the following\n\nFile /tmp/zsh6nU0kS:\nThis be the verse\n\nThe temporary file created by the process substitution will be deleted when the function ex‐\nits.\n", "subsections": [] }, "PARAMETER EXPANSION": { "content": "The character `$' is used to introduce parameter expansions. See zshparam(1) for a descrip‐\ntion of parameters, including arrays, associative arrays, and subscript notation to access\nindividual array elements.\n\nNote in particular the fact that words of unquoted parameters are not automatically split on\nwhitespace unless the option SHWORDSPLIT is set; see references to this option below for\nmore details. This is an important difference from other shells. However, as in other\nshells, null words are elided from unquoted parameters' expansions.\n\nWith default options, after the assignments:\n\narray=(\"first word\" \"\" \"third word\")\nscalar=\"only word\"\n\nthen $array substitutes two words, `first word' and `third word', and $scalar substitutes a\nsingle word `only word'. Note that second element of array was elided. Scalar parameters\ncan be elided too if their value is null (empty). To avoid elision, use quoting as follows:\n\"$scalar\" for scalars and \"${array[@]}\" or \"${(@)array}\" for arrays. (The last two forms are\nequivalent.)\n\nParameter expansions can involve flags, as in `${(@kv)aliases}', and other operators, such as\n`${PREFIX:-\"/usr/local\"}'. Parameter expansions can also be nested. These topics will be\nintroduced below. The full rules are complicated and are noted at the end.\n\nIn the expansions discussed below that require a pattern, the form of the pattern is the same\nas that used for filename generation; see the section `Filename Generation'. Note that these\npatterns, along with the replacement text of any substitutions, are themselves subject to pa‐\nrameter expansion, command substitution, and arithmetic expansion. In addition to the fol‐\nlowing operations, the colon modifiers described in the section `Modifiers' in the section\n`History Expansion' can be applied: for example, ${i:s/foo/bar/} performs string substitu‐\ntion on the expansion of parameter $i.\n\nIn the following descriptions, `word' refers to a single word substituted on the command\nline, not necessarily a space delimited word.\n\n${name}\nThe value, if any, of the parameter name is substituted. The braces are required if\nthe expansion is to be followed by a letter, digit, or underscore that is not to be\ninterpreted as part of name. In addition, more complicated forms of substitution usu‐\nally require the braces to be present; exceptions, which only apply if the option\nKSHARRAYS is not set, are a single subscript or any colon modifiers appearing after\nthe name, or any of the characters `^', `=', `~', `#' or `+' appearing before the\nname, all of which work with or without braces.\n\nIf name is an array parameter, and the KSHARRAYS option is not set, then the value of\neach element of name is substituted, one element per word. Otherwise, the expansion\nresults in one word only; with KSHARRAYS, this is the first element of an array. No\nfield splitting is done on the result unless the SHWORDSPLIT option is set. See\nalso the flags = and s:string:.\n\n${+name}\nIf name is the name of a set parameter `1' is substituted, otherwise `0' is substi‐\ntuted.\n\n${name-word}\n${name:-word}\nIf name is set, or in the second form is non-null, then substitute its value; other‐\nwise substitute word. In the second form name may be omitted, in which case word is\nalways substituted.\n\n${name+word}\n${name:+word}\nIf name is set, or in the second form is non-null, then substitute word; otherwise\nsubstitute nothing.\n\n${name=word}\n${name:=word}\n${name::=word}\nIn the first form, if name is unset then set it to word; in the second form, if name\nis unset or null then set it to word; and in the third form, unconditionally set name\nto word. In all forms, the value of the parameter is then substituted.\n\n${name?word}\n${name:?word}\nIn the first form, if name is set, or in the second form if name is both set and\nnon-null, then substitute its value; otherwise, print word and exit from the shell.\nInteractive shells instead return to the prompt. If word is omitted, then a standard\nmessage is printed.\n\nIn any of the above expressions that test a variable and substitute an alternate word, note\nthat you can use standard shell quoting in the word value to selectively override the split‐\nting done by the SHWORDSPLIT option and the = flag, but not splitting by the s:string:\nflag.\n\nIn the following expressions, when name is an array and the substitution is not quoted, or if\nthe `(@)' flag or the name[@] syntax is used, matching and replacement is performed on each\narray element separately.\n\n${name#pattern}\n${name##pattern}\nIf the pattern matches the beginning of the value of name, then substitute the value\nof name with the matched portion deleted; otherwise, just substitute the value of\nname. In the first form, the smallest matching pattern is preferred; in the second\nform, the largest matching pattern is preferred.\n\n${name%pattern}\n${name%%pattern}\nIf the pattern matches the end of the value of name, then substitute the value of name\nwith the matched portion deleted; otherwise, just substitute the value of name. In\nthe first form, the smallest matching pattern is preferred; in the second form, the\nlargest matching pattern is preferred.\n\n${name:#pattern}\nIf the pattern matches the value of name, then substitute the empty string; otherwise,\njust substitute the value of name. If name is an array the matching array elements\nare removed (use the `(M)' flag to remove the non-matched elements).\n\n${name:|arrayname}\nIf arrayname is the name (N.B., not contents) of an array variable, then any elements\ncontained in arrayname are removed from the substitution of name. If the substitution\nis scalar, either because name is a scalar variable or the expression is quoted, the\nelements of arrayname are instead tested against the entire expression.\n\n${name:*arrayname}\nSimilar to the preceding substitution, but in the opposite sense, so that entries\npresent in both the original substitution and as elements of arrayname are retained\nand others removed.\n\n${name:^arrayname}\n${name:^^arrayname}\nZips two arrays, such that the output array is twice as long as the shortest (longest\nfor `:^^') of name and arrayname, with the elements alternatingly being picked from\nthem. For `:^', if one of the input arrays is longer, the output will stop when the\nend of the shorter array is reached. Thus,\n\na=(1 2 3 4); b=(a b); print ${a:^b}\n\nwill output `1 a 2 b'. For `:^^', then the input is repeated until all of the longer\narray has been used up and the above will output `1 a 2 b 3 a 4 b'.\n\nEither or both inputs may be a scalar, they will be treated as an array of length 1\nwith the scalar as the only element. If either array is empty, the other array is out‐\nput with no extra elements inserted.\n\nCurrently the following code will output `a b' and `1' as two separate elements, which\ncan be unexpected. The second print provides a workaround which should continue to\nwork if this is changed.\n\na=(a b); b=(1 2); print -l \"${a:^b}\"; print -l \"${${a:^b}}\"\n\n${name:offset}\n${name:offset:length}\nThis syntax gives effects similar to parameter subscripting in the form\n$name[start,end], but is compatible with other shells; note that both offset and\nlength are interpreted differently from the components of a subscript.\n\nIf offset is non-negative, then if the variable name is a scalar substitute the con‐\ntents starting offset characters from the first character of the string, and if name\nis an array substitute elements starting offset elements from the first element. If\nlength is given, substitute that many characters or elements, otherwise the entire\nrest of the scalar or array.\n\nA positive offset is always treated as the offset of a character or element in name\nfrom the first character or element of the array (this is different from native zsh\nsubscript notation). Hence 0 refers to the first character or element regardless of\nthe setting of the option KSHARRAYS.\n\nA negative offset counts backwards from the end of the scalar or array, so that -1\ncorresponds to the last character or element, and so on.\n\nWhen positive, length counts from the offset position toward the end of the scalar or\narray. When negative, length counts back from the end. If this results in a position\nsmaller than offset, a diagnostic is printed and nothing is substituted.\n\nThe option MULTIBYTE is obeyed, i.e. the offset and length count multibyte characters\nwhere appropriate.\n\noffset and length undergo the same set of shell substitutions as for scalar assign‐\nment; in addition, they are then subject to arithmetic evaluation. Hence, for example\n\nprint ${foo:3}\nprint ${foo: 1 + 2}\nprint ${foo:$(( 1 + 2))}\nprint ${foo:$(echo 1 + 2)}\n\nall have the same effect, extracting the string starting at the fourth character of\n$foo if the substitution would otherwise return a scalar, or the array starting at the\nfourth element if $foo would return an array. Note that with the option KSHARRAYS\n$foo always returns a scalar (regardless of the use of the offset syntax) and a form\nsuch as ${foo[*]:3} is required to extract elements of an array named foo.\n\nIf offset is negative, the - may not appear immediately after the : as this indicates\nthe ${name:-word} form of substitution. Instead, a space may be inserted before the\n-. Furthermore, neither offset nor length may begin with an alphabetic character or &\nas these are used to indicate history-style modifiers. To substitute a value from a\nvariable, the recommended approach is to precede it with a $ as this signifies the in‐\ntention (parameter substitution can easily be rendered unreadable); however, as arith‐\nmetic substitution is performed, the expression ${var: offs} does work, retrieving the\noffset from $offs.\n\nFor further compatibility with other shells there is a special case for array offset\n0. This usually accesses the first element of the array. However, if the substitu‐\ntion refers to the positional parameter array, e.g. $@ or $*, then offset 0 instead\nrefers to $0, offset 1 refers to $1, and so on. In other words, the positional param‐\neter array is effectively extended by prepending $0. Hence ${*:0:1} substitutes $0\nand ${*:1:1} substitutes $1.\n\n${name/pattern/repl}\n${name//pattern/repl}\n${name:/pattern/repl}\nReplace the longest possible match of pattern in the expansion of parameter name by\nstring repl. The first form replaces just the first occurrence, the second form all\noccurrences, and the third form replaces only if pattern matches the entire string.\nBoth pattern and repl are subject to double-quoted substitution, so that expressions\nlike ${name/$opat/$npat} will work, but obey the usual rule that pattern characters in\n$opat are not treated specially unless either the option GLOBSUBST is set, or $opat\nis instead substituted as ${~opat}.\n\nThe pattern may begin with a `#', in which case the pattern must match at the start of\nthe string, or `%', in which case it must match at the end of the string, or `#%' in\nwhich case the pattern must match the entire string. The repl may be an empty string,\nin which case the final `/' may also be omitted. To quote the final `/' in other\ncases it should be preceded by a single backslash; this is not necessary if the `/'\noccurs inside a substituted parameter. Note also that the `#', `%' and `#% are not\nactive if they occur inside a substituted parameter, even at the start.\n\nIf, after quoting rules apply, ${name} expands to an array, the replacements act on\neach element individually. Note also the effect of the I and S parameter expansion\nflags below; however, the flags M, R, B, E and N are not useful.\n\nFor example,\n\nfoo=\"twinkle twinkle little star\" sub=\"t*e\" rep=\"spy\"\nprint ${foo//${~sub}/$rep}\nprint ${(S)foo//${~sub}/$rep}\n\nHere, the `~' ensures that the text of $sub is treated as a pattern rather than a\nplain string. In the first case, the longest match for t*e is substituted and the re‐\nsult is `spy star', while in the second case, the shortest matches are taken and the\nresult is `spy spy lispy star'.\n\n${#spec}\nIf spec is one of the above substitutions, substitute the length in characters of the\nresult instead of the result itself. If spec is an array expression, substitute the\nnumber of elements of the result. This has the side-effect that joining is skipped\neven in quoted forms, which may affect other sub-expressions in spec. Note that `^',\n`=', and `~', below, must appear to the left of `#' when these forms are combined.\n\nIf the option POSIXIDENTIFIERS is not set, and spec is a simple name, then the braces\nare optional; this is true even for special parameters so e.g. $#- and $#* take the\nlength of the string $- and the array $* respectively. If POSIXIDENTIFIERS is set,\nthen braces are required for the # to be treated in this fashion.\n\n${^spec}\nTurn on the RCEXPANDPARAM option for the evaluation of spec; if the `^' is doubled,\nturn it off. When this option is set, array expansions of the form foo${xx}bar, where\nthe parameter xx is set to (a b c), are substituted with `fooabar foobbar foocbar' in‐\nstead of the default `fooa b cbar'. Note that an empty array will therefore cause all\narguments to be removed.\n\nInternally, each such expansion is converted into the equivalent list for brace expan‐\nsion. E.g., ${^var} becomes {$var[1],$var[2],...}, and is processed as described in\nthe section `Brace Expansion' below: note, however, the expansion happens immediately,\nwith any explicit brace expansion happening later. If word splitting is also in ef‐\nfect the $var[N] may themselves be split into different list elements.\n\n${=spec}\nPerform word splitting using the rules for SHWORDSPLIT during the evaluation of\nspec, but regardless of whether the parameter appears in double quotes; if the `=' is\ndoubled, turn it off. This forces parameter expansions to be split into separate\nwords before substitution, using IFS as a delimiter. This is done by default in most\nother shells.\n\nNote that splitting is applied to word in the assignment forms of spec before the as‐\nsignment to name is performed. This affects the result of array assignments with the\nA flag.\n\n${~spec}\nTurn on the GLOBSUBST option for the evaluation of spec; if the `~' is doubled, turn\nit off. When this option is set, the string resulting from the expansion will be in‐\nterpreted as a pattern anywhere that is possible, such as in filename expansion and\nfilename generation and pattern-matching contexts like the right hand side of the `='\nand `!=' operators in conditions.\n\nIn nested substitutions, note that the effect of the ~ applies to the result of the\ncurrent level of substitution. A surrounding pattern operation on the result may can‐\ncel it. Hence, for example, if the parameter foo is set to *, ${~foo//\\*/*.c} is sub‐\nstituted by the pattern *.c, which may be expanded by filename generation, but\n${${~foo}//\\*/*.c} substitutes to the string *.c, which will not be further expanded.\n\nIf a ${...} type parameter expression or a $(...) type command substitution is used in place\nof name above, it is expanded first and the result is used as if it were the value of name.\nThus it is possible to perform nested operations: ${${foo#head}%tail} substitutes the value\nof $foo with both `head' and `tail' deleted. The form with $(...) is often useful in combi‐\nnation with the flags described next; see the examples below. Each name or nested ${...} in\na parameter expansion may also be followed by a subscript expression as described in Array\nParameters in zshparam(1).\n\nNote that double quotes may appear around nested expressions, in which case only the part in‐\nside is treated as quoted; for example, ${(f)\"$(foo)\"} quotes the result of $(foo), but the\nflag `(f)' (see below) is applied using the rules for unquoted expansions. Note further that\nquotes are themselves nested in this context; for example, in \"${(@f)\"$(foo)\"}\", there are\ntwo sets of quotes, one surrounding the whole expression, the other (redundant) surrounding\nthe $(foo) as before.\n", "subsections": [ { "name": "Parameter Expansion Flags", "content": "If the opening brace is directly followed by an opening parenthesis, the string up to the\nmatching closing parenthesis will be taken as a list of flags. In cases where repeating a\nflag is meaningful, the repetitions need not be consecutive; for example, `(q%q%q)' means the\nsame thing as the more readable `(%%qqq)'. The following flags are supported:\n\n# Evaluate the resulting words as numeric expressions and output the characters corre‐\nsponding to the resulting integer. Note that this form is entirely distinct from use\nof the # without parentheses.\n\nIf the MULTIBYTE option is set and the number is greater than 127 (i.e. not an ASCII\ncharacter) it is treated as a Unicode character.\n\n% Expand all % escapes in the resulting words in the same way as in prompts (see EXPAN‐\nSION OF PROMPT SEQUENCES in zshmisc(1)). If this flag is given twice, full prompt ex‐\npansion is done on the resulting words, depending on the setting of the PROMPTPER‐‐\nCENT, PROMPTSUBST and PROMPTBANG options.\n\n@ In double quotes, array elements are put into separate words. E.g., `\"${(@)foo}\"' is\nequivalent to `\"${foo[@]}\"' and `\"${(@)foo[1,2]}\"' is the same as `\"$foo[1]\"\n\"$foo[2]\"'. This is distinct from field splitting by the f, s or z flags, which still\napplies within each array element.\n\nA Convert the substitution into an array expression, even if it otherwise would be\nscalar. This has lower precedence than subscripting, so one level of nested expansion\nis required in order that subscripts apply to array elements. Thus ${${(A)name}[1]}\nyields the full value of name when name is scalar.\n\nThis assigns an array parameter with `${...=...}', `${...:=...}' or `${...::=...}'.\nIf this flag is repeated (as in `AA'), assigns an associative array parameter. As‐\nsignment is made before sorting or padding; if field splitting is active, the word\npart is split before assignment. The name part may be a subscripted range for ordi‐\nnary arrays; when assigning an associative array, the word part must be converted to\nan array, for example by using `${(AA)=name=...}' to activate field splitting.\n\nSurrounding context such as additional nesting or use of the value in a scalar assign‐\nment may cause the array to be joined back into a single string again.\n\na Sort in array index order; when combined with `O' sort in reverse array index order.\nNote that `a' is therefore equivalent to the default but `Oa' is useful for obtaining\nan array's elements in reverse order.\n\nb Quote with backslashes only characters that are special to pattern matching. This is\nuseful when the contents of the variable are to be tested using GLOBSUBST, including\nthe ${~...} switch.\n\nQuoting using one of the q family of flags does not work for this purpose since quotes\nare not stripped from non-pattern characters by GLOBSUBST. In other words,\n\npattern=${(q)str}\n[[ $str = ${~pattern} ]]\n\nworks if $str is `a*b' but not if it is `a b', whereas\n\npattern=${(b)str}\n[[ $str = ${~pattern} ]]\n\nis always true for any possible value of $str.\n\nc With ${#name}, count the total number of characters in an array, as if the elements\nwere concatenated with spaces between them. This is not a true join of the array, so\nother expressions used with this flag may have an effect on the elements of the array\nbefore it is counted.\n\nC Capitalize the resulting words. `Words' in this case refers to sequences of alphanu‐\nmeric characters separated by non-alphanumerics, not to words that result from field\nsplitting.\n\nD Assume the string or array elements contain directories and attempt to substitute the\nleading part of these by names. The remainder of the path (the whole of it if the\nleading part was not substituted) is then quoted so that the whole string can be used\nas a shell argument. This is the reverse of `~' substitution: see the section FILE‐\nNAME EXPANSION below.\n\ne Perform single word shell expansions, namely parameter expansion, command substitution\nand arithmetic expansion, on the result. Such expansions can be nested but too deep\nrecursion may have unpredictable effects.\n\nf Split the result of the expansion at newlines. This is a shorthand for `ps:\\n:'.\n\nF Join the words of arrays together using newline as a separator. This is a shorthand\nfor `pj:\\n:'.\n\ng:opts:\nProcess escape sequences like the echo builtin when no options are given (g::). With\nthe o option, octal escapes don't take a leading zero. With the c option, sequences\nlike `^X' are also processed. With the e option, processes `\\M-t' and similar se‐\nquences like the print builtin. With both of the o and e options, behaves like the\nprint builtin except that in none of these modes is `\\c' interpreted.\n\ni Sort case-insensitively. May be combined with `n' or `O'.\n\nk If name refers to an associative array, substitute the keys (element names) rather\nthan the values of the elements. Used with subscripts (including ordinary arrays),\nforce indices or keys to be substituted even if the subscript form refers to values.\nHowever, this flag may not be combined with subscript ranges. With the KSHARRAYS op‐\ntion a subscript `[*]' or `[@]' is needed to operate on the whole array, as usual.\n\nL Convert all letters in the result to lower case.\n\nn Sort decimal integers numerically; if the first differing characters of two test\nstrings are not digits, sorting is lexical. Integers with more initial zeroes are\nsorted before those with fewer or none. Hence the array `foo1 foo02 foo2 foo3 foo20\nfoo23' is sorted into the order shown. May be combined with `i' or `O'.\n\no Sort the resulting words in ascending order; if this appears on its own the sorting is\nlexical and case-sensitive (unless the locale renders it case-insensitive). Sorting\nin ascending order is the default for other forms of sorting, so this is ignored if\ncombined with `a', `i' or `n'.\n\nO Sort the resulting words in descending order; `O' without `a', `i' or `n' sorts in re‐\nverse lexical order. May be combined with `a', `i' or `n' to reverse the order of\nsorting.\n\nP This forces the value of the parameter name to be interpreted as a further parameter\nname, whose value will be used where appropriate. Note that flags set with one of the\ntypeset family of commands (in particular case transformations) are not applied to the\nvalue of name used in this fashion.\n\nIf used with a nested parameter or command substitution, the result of that will be\ntaken as a parameter name in the same way. For example, if you have `foo=bar' and\n`bar=baz', the strings ${(P)foo}, ${(P)${foo}}, and ${(P)$(echo bar)} will be expanded\nto `baz'.\n\nLikewise, if the reference is itself nested, the expression with the flag is treated\nas if it were directly replaced by the parameter name. It is an error if this nested\nsubstitution produces an array with more than one word. For example, if `name=assoc'\nwhere the parameter assoc is an associative array, then `${${(P)name}[elt]}' refers to\nthe element of the associative subscripted `elt'.\n\nq Quote characters that are special to the shell in the resulting words with back‐\nslashes; unprintable or invalid characters are quoted using the $'\\NNN' form, with\nseparate quotes for each octet.\n\nIf this flag is given twice, the resulting words are quoted in single quotes and if it\nis given three times, the words are quoted in double quotes; in these forms no special\nhandling of unprintable or invalid characters is attempted. If the flag is given four\ntimes, the words are quoted in single quotes preceded by a $. Note that in all three\nof these forms quoting is done unconditionally, even if this does not change the way\nthe resulting string would be interpreted by the shell.\n\nIf a q- is given (only a single q may appear), a minimal form of single quoting is\nused that only quotes the string if needed to protect special characters. Typically\nthis form gives the most readable output.\n\nIf a q+ is given, an extended form of minimal quoting is used that causes unprintable\ncharacters to be rendered using $'...'. This quoting is similar to that used by the\noutput of values by the typeset family of commands.\n\nQ Remove one level of quotes from the resulting words.\n\nt Use a string describing the type of the parameter where the value of the parameter\nwould usually appear. This string consists of keywords separated by hyphens (`-'). The\nfirst keyword in the string describes the main type, it can be one of `scalar', `ar‐‐\nray', `integer', `float' or `association'. The other keywords describe the type in\nmore detail:\n\nlocal for local parameters\n\nleft for left justified parameters\n\nrightblanks\nfor right justified parameters with leading blanks\n\nrightzeros\nfor right justified parameters with leading zeros\n\nlower for parameters whose value is converted to all lower case when it is expanded\n\nupper for parameters whose value is converted to all upper case when it is expanded\n\nreadonly\nfor readonly parameters\n\ntag for tagged parameters\n\nexport for exported parameters\n\nunique for arrays which keep only the first occurrence of duplicated values\n\nhide for parameters with the `hide' flag\n\nhideval\nfor parameters with the `hideval' flag\n\nspecial\nfor special parameters defined by the shell\n\nu Expand only the first occurrence of each unique word.\n\nU Convert all letters in the result to upper case.\n\nv Used with k, substitute (as two consecutive words) both the key and the value of each\nassociative array element. Used with subscripts, force values to be substituted even\nif the subscript form refers to indices or keys.\n\nV Make any special characters in the resulting words visible.\n\nw With ${#name}, count words in arrays or strings; the s flag may be used to set a word\ndelimiter.\n\nW Similar to w with the difference that empty words between repeated delimiters are also\ncounted.\n\nX With this flag, parsing errors occurring with the Q, e and # flags or the pattern\nmatching forms such as `${name#pattern}' are reported. Without the flag, errors are\nsilently ignored.\n\nz Split the result of the expansion into words using shell parsing to find the words,\ni.e. taking into account any quoting in the value. Comments are not treated specially\nbut as ordinary strings, similar to interactive shells with the INTERACTIVECOMMENTS\noption unset (however, see the Z flag below for related options)\n\nNote that this is done very late, even later than the `(s)' flag. So to access single\nwords in the result use nested expansions as in `${${(z)foo}[2]}'. Likewise, to remove\nthe quotes in the resulting words use `${(Q)${(z)foo}}'.\n\n0 Split the result of the expansion on null bytes. This is a shorthand for `ps:\\0:'.\n\nThe following flags (except p) are followed by one or more arguments as shown. Any charac‐\nter, or the matching pairs `(...)', `{...}', `[...]', or `<...>', may be used in place of a\ncolon as delimiters, but note that when a flag takes more than one argument, a matched pair\nof delimiters must surround each argument.\n\np Recognize the same escape sequences as the print builtin in string arguments to any of\nthe flags described below that follow this argument.\n\nAlternatively, with this option string arguments may be in the form $var in which case\nthe value of the variable is substituted. Note this form is strict; the string argu‐\nment does not undergo general parameter expansion.\n\nFor example,\n\nsep=:\nval=a:b:c\nprint ${(ps.$sep.)val}\n\nsplits the variable on a :.\n\n~ Strings inserted into the expansion by any of the flags below are to be treated as\npatterns. This applies to the string arguments of flags that follow ~ within the same\nset of parentheses. Compare with ~ outside parentheses, which forces the entire sub‐\nstituted string to be treated as a pattern. Hence, for example,\n\n[[ \"?\" = ${(~j.|.)array} ]]\n\ntreats `|' as a pattern and succeeds if and only if $array contains the string `?' as\nan element. The ~ may be repeated to toggle the behaviour; its effect only lasts to\nthe end of the parenthesised group.\n\nj:string:\nJoin the words of arrays together using string as a separator. Note that this occurs\nbefore field splitting by the s:string: flag or the SHWORDSPLIT option.\n\nl:expr::string1::string2:\nPad the resulting words on the left. Each word will be truncated if required and\nplaced in a field expr characters wide.\n\nThe arguments :string1: and :string2: are optional; neither, the first, or both may be\ngiven. Note that the same pairs of delimiters must be used for each of the three ar‐\nguments. The space to the left will be filled with string1 (concatenated as often as\nneeded) or spaces if string1 is not given. If both string1 and string2 are given,\nstring2 is inserted once directly to the left of each word, truncated if necessary,\nbefore string1 is used to produce any remaining padding.\n\nIf either of string1 or string2 is present but empty, i.e. there are two delimiters\ntogether at that point, the first character of $IFS is used instead.\n\nIf the MULTIBYTE option is in effect, the flag m may also be given, in which case\nwidths will be used for the calculation of padding; otherwise individual multibyte\ncharacters are treated as occupying one unit of width.\n\nIf the MULTIBYTE option is not in effect, each byte in the string is treated as occu‐\npying one unit of width.\n\nControl characters are always assumed to be one unit wide; this allows the mechanism\nto be used for generating repetitions of control characters.\n\nm Only useful together with one of the flags l or r or with the # length operator when\nthe MULTIBYTE option is in effect. Use the character width reported by the system in\ncalculating how much of the string it occupies or the overall length of the string.\nMost printable characters have a width of one unit, however certain Asian character\nsets and certain special effects use wider characters; combining characters have zero\nwidth. Non-printable characters are arbitrarily counted as zero width; how they would\nactually be displayed will vary.\n\nIf the m is repeated, the character either counts zero (if it has zero width), else\none. For printable character strings this has the effect of counting the number of\nglyphs (visibly separate characters), except for the case where combining characters\nthemselves have non-zero width (true in certain alphabets).\n\nr:expr::string1::string2:\nAs l, but pad the words on the right and insert string2 immediately to the right of\nthe string to be padded.\n\nLeft and right padding may be used together. In this case the strategy is to apply\nleft padding to the first half width of each of the resulting words, and right padding\nto the second half. If the string to be padded has odd width the extra padding is ap‐\nplied on the left.\n\ns:string:\nForce field splitting at the separator string. Note that a string of two or more\ncharacters means that all of them must match in sequence; this differs from the treat‐\nment of two or more characters in the IFS parameter. See also the = flag and the\nSHWORDSPLIT option. An empty string may also be given in which case every character\nwill be a separate element.\n\nFor historical reasons, the usual behaviour that empty array elements are retained in‐\nside double quotes is disabled for arrays generated by splitting; hence the following:\n\nline=\"one::three\"\nprint -l \"${(s.:.)line}\"\n\nproduces two lines of output for one and three and elides the empty field. To over‐\nride this behaviour, supply the `(@)' flag as well, i.e. \"${(@s.:.)line}\".\n\nZ:opts:\nAs z but takes a combination of option letters between a following pair of delimiter\ncharacters. With no options the effect is identical to z. (Z+c+) causes comments to\nbe parsed as a string and retained; any field in the resulting array beginning with an\nunquoted comment character is a comment. (Z+C+) causes comments to be parsed and re‐\nmoved. The rule for comments is standard: anything between a word starting with the\nthird character of $HISTCHARS, default #, up to the next newline is a comment. (Z+n+)\ncauses unquoted newlines to be treated as ordinary whitespace, else they are treated\nas if they are shell code delimiters and converted to semicolons. Options are com‐\nbined within the same set of delimiters, e.g. (Z+Cn+).\n\n:flags:\nThe underscore () flag is reserved for future use. As of this revision of zsh, there\nare no valid flags; anything following an underscore, other than an empty pair of de‐\nlimiters, is treated as an error, and the flag itself has no effect.\n\nThe following flags are meaningful with the ${...#...} or ${...%...} forms. The S and I\nflags may also be used with the ${.../...} forms.\n\nS With # or ##, search for the match that starts closest to the start of the string (a\n`substring match'). Of all matches at a particular position, # selects the shortest\nand ## the longest:\n\n% str=\"aXbXc\"\n% echo ${(S)str#X*}\nabXc\n% echo ${(S)str##X*}\na\n%\n\nWith % or %%, search for the match that starts closest to the end of the string:\n\n% str=\"aXbXc\"\n% echo ${(S)str%X*}\naXbc\n% echo ${(S)str%%X*}\naXb\n%\n\n(Note that % and %% don't search for the match that ends closest to the end of the\nstring, as one might expect.)\n\nWith substitution via ${.../...} or ${...//...}, specifies non-greedy matching, i.e.\nthat the shortest instead of the longest match should be replaced:\n\n% str=\"abab\"\n% echo ${str/*b/}\n\n% echo ${(S)str/*b/}\nab\n%\n\nI:expr:\nSearch the exprth match (where expr evaluates to a number). This only applies when\nsearching for substrings, either with the S flag, or with ${.../...} (only the exprth\nmatch is substituted) or ${...//...} (all matches from the exprth on are substituted).\nThe default is to take the first match.\n\nThe exprth match is counted such that there is either one or zero matches from each\nstarting position in the string, although for global substitution matches overlapping\nprevious replacements are ignored. With the ${...%...} and ${...%%...} forms, the\nstarting position for the match moves backwards from the end as the index increases,\nwhile with the other forms it moves forward from the start.\n\nHence with the string\nwhich switch is the right switch for Ipswich?\nsubstitutions of the form ${(SI:N:)string#w*ch} as N increases from 1 will match and\nremove `which', `witch', `witch' and `wich'; the form using `##' will match and remove\n`which switch is the right switch for Ipswich', `witch is the right switch for Ip‐‐\nswich', `witch for Ipswich' and `wich'. The form using `%' will remove the same\nmatches as for `#', but in reverse order, and the form using `%%' will remove the same\nmatches as for `##' in reverse order.\n\nB Include the index of the beginning of the match in the result.\n\nE Include the index one character past the end of the match in the result (note this is\ninconsistent with other uses of parameter index).\n\nM Include the matched portion in the result.\n\nN Include the length of the match in the result.\n\nR Include the unmatched portion in the result (the Rest).\n" }, { "name": "Rules", "content": "Here is a summary of the rules for substitution; this assumes that braces are present around\nthe substitution, i.e. ${...}. Some particular examples are given below. Note that the Zsh\nDevelopment Group accepts no responsibility for any brain damage which may occur during the\nreading of the following rules.\n\n1. Nested substitution\nIf multiple nested ${...} forms are present, substitution is performed from the inside\noutwards. At each level, the substitution takes account of whether the current value\nis a scalar or an array, whether the whole substitution is in double quotes, and what\nflags are supplied to the current level of substitution, just as if the nested substi‐\ntution were the outermost. The flags are not propagated up to enclosing substitu‐\ntions; the nested substitution will return either a scalar or an array as determined\nby the flags, possibly adjusted for quoting. All the following steps take place where\napplicable at all levels of substitution.\n\nNote that, unless the `(P)' flag is present, the flags and any subscripts apply di‐\nrectly to the value of the nested substitution; for example, the expansion ${${foo}}\nbehaves exactly the same as ${foo}. When the `(P)' flag is present in a nested sub‐\nstitution, the other substitution rules are applied to the value before it is inter‐\npreted as a name, so ${${(P)foo}} may differ from ${(P)foo}.\n\nAt each nested level of substitution, the substituted words undergo all forms of sin‐\ngle-word substitution (i.e. not filename generation), including command substitution,\narithmetic expansion and filename expansion (i.e. leading ~ and =). Thus, for exam‐\nple, ${${:-=cat}:h} expands to the directory where the cat program resides. (Explana‐\ntion: the internal substitution has no parameter but a default value =cat, which is\nexpanded by filename expansion to a full path; the outer substitution then applies the\nmodifier :h and takes the directory part of the path.)\n\n2. Internal parameter flags\nAny parameter flags set by one of the typeset family of commands, in particular the\n-L, -R, -Z, -u and -l options for padding and capitalization, are applied directly to\nthe parameter value. Note these flags are options to the command, e.g. `typeset -Z';\nthey are not the same as the flags used within parameter substitutions.\n\nAt the outermost level of substitution, the `(P)' flag (rule 4.) ignores these trans‐\nformations and uses the unmodified value of the parameter as the name to be replaced.\nThis is usually the desired behavior because padding may make the value syntactically\nillegal as a parameter name, but if capitalization changes are desired, use the\n${${(P)foo}} form (rule 25.).\n\n3. Parameter subscripting\nIf the value is a raw parameter reference with a subscript, such as ${var[3]}, the ef‐\nfect of subscripting is applied directly to the parameter. Subscripts are evaluated\nleft to right; subsequent subscripts apply to the scalar or array value yielded by the\nprevious subscript. Thus if var is an array, ${var[1][2]} is the second character of\nthe first word, but ${var[2,4][2]} is the entire third word (the second word of the\nrange of words two through four of the original array). Any number of subscripts may\nappear. Flags such as `(k)' and `(v)' which alter the result of subscripting are ap‐\nplied.\n\n4. Parameter name replacement\nAt the outermost level of nesting only, the `(P)' flag is applied. This treats the\nvalue so far as a parameter name (which may include a subscript expression) and re‐\nplaces that with the corresponding value. This replacement occurs later if the `(P)'\nflag appears in a nested substitution.\n\nIf the value so far names a parameter that has internal flags (rule 2.), those inter‐\nnal flags are applied to the new value after replacement.\n\n5. Double-quoted joining\nIf the value after this process is an array, and the substitution appears in double\nquotes, and neither an `(@)' flag nor a `#' length operator is present at the current\nlevel, then words of the value are joined with the first character of the parameter\n$IFS, by default a space, between each word (single word arrays are not modified). If\nthe `(j)' flag is present, that is used for joining instead of $IFS.\n\n6. Nested subscripting\nAny remaining subscripts (i.e. of a nested substitution) are evaluated at this point,\nbased on whether the value is an array or a scalar. As with 3., multiple subscripts\ncan appear. Note that ${foo[2,4][2]} is thus equivalent to ${${foo[2,4]}[2]} and also\nto \"${${(@)foo[2,4]}[2]}\" (the nested substitution returns an array in both cases),\nbut not to \"${${foo[2,4]}[2]}\" (the nested substitution returns a scalar because of\nthe quotes).\n\n7. Modifiers\nAny modifiers, as specified by a trailing `#', `%', `/' (possibly doubled) or by a set\nof modifiers of the form `:...' (see the section `Modifiers' in the section `History\nExpansion'), are applied to the words of the value at this level.\n\n8. Character evaluation\nAny `(#)' flag is applied, evaluating the result so far numerically as a character.\n\n9. Length\nAny initial `#' modifier, i.e. in the form ${#var}, is used to evaluate the length of\nthe expression so far.\n\n10. Forced joining\nIf the `(j)' flag is present, or no `(j)' flag is present but the string is to be\nsplit as given by rule 11., and joining did not take place at rule 5., any words in\nthe value are joined together using the given string or the first character of $IFS if\nnone. Note that the `(F)' flag implicitly supplies a string for joining in this man‐\nner.\n\n11. Simple word splitting\nIf one of the `(s)' or `(f)' flags are present, or the `=' specifier was present (e.g.\n${=var}), the word is split on occurrences of the specified string, or (for = with\nneither of the two flags present) any of the characters in $IFS.\n\nIf no `(s)', `(f)' or `=' was given, but the word is not quoted and the option\nSHWORDSPLIT is set, the word is split on occurrences of any of the characters in\n$IFS. Note this step, too, takes place at all levels of a nested substitution.\n\n12. Case modification\nAny case modification from one of the flags `(L)', `(U)' or `(C)' is applied.\n\n13. Escape sequence replacement\nFirst any replacements from the `(g)' flag are performed, then any prompt-style for‐\nmatting from the `(%)' family of flags is applied.\n\n14. Quote application\nAny quoting or unquoting using `(q)' and `(Q)' and related flags is applied.\n\n15. Directory naming\nAny directory name substitution using `(D)' flag is applied.\n\n16. Visibility enhancement\nAny modifications to make characters visible using the `(V)' flag are applied.\n\n17. Lexical word splitting\nIf the '(z)' flag or one of the forms of the '(Z)' flag is present, the word is split\nas if it were a shell command line, so that quotation marks and other metacharacters\nare used to decide what constitutes a word. Note this form of splitting is entirely\ndistinct from that described by rule 11.: it does not use $IFS, and does not cause\nforced joining.\n\n18. Uniqueness\nIf the result is an array and the `(u)' flag was present, duplicate elements are re‐\nmoved from the array.\n\n19. Ordering\nIf the result is still an array and one of the `(o)' or `(O)' flags was present, the\narray is reordered.\n\n20. RCEXPANDPARAM\nAt this point the decision is made whether any resulting array elements are to be com‐\nbined element by element with surrounding text, as given by either the RCEXPANDPARAM\noption or the `^' flag.\n\n21. Re-evaluation\nAny `(e)' flag is applied to the value, forcing it to be re-examined for new parameter\nsubstitutions, but also for command and arithmetic substitutions.\n\n22. Padding\nAny padding of the value by the `(l.fill.)' or `(r.fill.)' flags is applied.\n\n23. Semantic joining\nIn contexts where expansion semantics requires a single word to result, all words are\nrejoined with the first character of IFS between. So in `${(P)${(f)lines}}' the value\nof ${lines} is split at newlines, but then must be joined again before the `(P)' flag\ncan be applied.\n\nIf a single word is not required, this rule is skipped.\n\n24. Empty argument removal\nIf the substitution does not appear in double quotes, any resulting zero-length argu‐\nment, whether from a scalar or an element of an array, is elided from the list of ar‐\nguments inserted into the command line.\n\nStrictly speaking, the removal happens later as the same happens with other forms of\nsubstitution; the point to note here is simply that it occurs after any of the above\nparameter operations.\n\n25. Nested parameter name replacement\nIf the `(P)' flag is present and rule 4. has not applied, the value so far is treated\nas a parameter name (which may include a subscript expression) and replaced with the\ncorresponding value, with internal flags (rule 2.) applied to the new value.\n" }, { "name": "Examples", "content": "The flag f is useful to split a double-quoted substitution line by line. For example,\n${(f)\"$(\nMatches any number in the range x to y, inclusive. Either of the numbers may be omit‐\nted to make the range open-ended; hence `<->' matches any number. To match individual\ndigits, the [...] form is more efficient.\n\nBe careful when using other wildcards adjacent to patterns of this form; for example,\n<0-9>* will actually match any number whatsoever at the start of the string, since the\n`<0-9>' will match the first digit, and the `*' will match any others. This is a trap\nfor the unwary, but is in fact an inevitable consequence of the rule that the longest\npossible match always succeeds. Expressions such as `<0-9>[^[:digit:]]*' can be used\ninstead.\n\n(...) Matches the enclosed pattern. This is used for grouping. If the KSHGLOB option is\nset, then a `@', `*', `+', `?' or `!' immediately preceding the `(' is treated spe‐\ncially, as detailed below. The option SHGLOB prevents bare parentheses from being\nused in this way, though the KSHGLOB option is still available.\n\nNote that grouping cannot extend over multiple directories: it is an error to have a\n`/' within a group (this only applies for patterns used in filename generation).\nThere is one exception: a group of the form (pat/)# appearing as a complete path seg‐\nment can match a sequence of directories. For example, foo/(a*/)#bar matches foo/bar,\nfoo/any/bar, foo/any/anyother/bar, and so on.\n\nx|y Matches either x or y. This operator has lower precedence than any other. The `|'\ncharacter must be within parentheses, to avoid interpretation as a pipeline. The al‐\nternatives are tried in order from left to right.\n\n^x (Requires EXTENDEDGLOB to be set.) Matches anything except the pattern x. This has\na higher precedence than `/', so `^foo/bar' will search directories in `.' except\n`./foo' for a file named `bar'.\n\nx~y (Requires EXTENDEDGLOB to be set.) Match anything that matches the pattern x but\ndoes not match y. This has lower precedence than any operator except `|', so\n`*/*~foo/bar' will search for all files in all directories in `.' and then exclude\n`foo/bar' if there was such a match. Multiple patterns can be excluded by\n`foo~bar~baz'. In the exclusion pattern (y), `/' and `.' are not treated specially\nthe way they usually are in globbing.\n\nx# (Requires EXTENDEDGLOB to be set.) Matches zero or more occurrences of the pattern\nx. This operator has high precedence; `12#' is equivalent to `1(2#)', rather than\n`(12)#'. It is an error for an unquoted `#' to follow something which cannot be re‐\npeated; this includes an empty string, a pattern already followed by `##', or paren‐\ntheses when part of a KSHGLOB pattern (for example, `!(foo)#' is invalid and must be\nreplaced by `*(!(foo))').\n\nx## (Requires EXTENDEDGLOB to be set.) Matches one or more occurrences of the pattern x.\nThis operator has high precedence; `12##' is equivalent to `1(2##)', rather than\n`(12)##'. No more than two active `#' characters may appear together. (Note the po‐\ntential clash with glob qualifiers in the form `1(2##)' which should therefore be\navoided.)\n" }, { "name": "ksh-like Glob Operators", "content": "If the KSHGLOB option is set, the effects of parentheses can be modified by a preceding `@',\n`*', `+', `?' or `!'. This character need not be unquoted to have special effects, but the\n`(' must be.\n\n@(...) Match the pattern in the parentheses. (Like `(...)'.)\n\n*(...) Match any number of occurrences. (Like `(...)#', except that recursive directory\nsearching is not supported.)\n\n+(...) Match at least one occurrence. (Like `(...)##', except that recursive directory\nsearching is not supported.)\n\n?(...) Match zero or one occurrence. (Like `(|...)'.)\n\n!(...) Match anything but the expression in parentheses. (Like `(^(...))'.)\n" }, { "name": "Precedence", "content": "The precedence of the operators given above is (highest) `^', `/', `~', `|' (lowest); the re‐\nmaining operators are simply treated from left to right as part of a string, with `#' and\n`##' applying to the shortest possible preceding unit (i.e. a character, `?', `[...]',\n`<...>', or a parenthesised expression). As mentioned above, a `/' used as a directory sepa‐\nrator may not appear inside parentheses, while a `|' must do so; in patterns used in other\ncontexts than filename generation (for example, in case statements and tests within\n`[[...]]'), a `/' is not special; and `/' is also not special after a `~' appearing outside\nparentheses in a filename pattern.\n" }, { "name": "Globbing Flags", "content": "There are various flags which affect any text to their right up to the end of the enclosing\ngroup or to the end of the pattern; they require the EXTENDEDGLOB option. All take the form\n(#X) where X may have one of the following forms:\n\ni Case insensitive: upper or lower case characters in the pattern match upper or lower\ncase characters.\n\nl Lower case characters in the pattern match upper or lower case characters; upper case\ncharacters in the pattern still only match upper case characters.\n\nI Case sensitive: locally negates the effect of i or l from that point on.\n\nb Activate backreferences for parenthesised groups in the pattern; this does not work in\nfilename generation. When a pattern with a set of active parentheses is matched, the\nstrings matched by the groups are stored in the array $match, the indices of the be‐\nginning of the matched parentheses in the array $mbegin, and the indices of the end in\nthe array $mend, with the first element of each array corresponding to the first\nparenthesised group, and so on. These arrays are not otherwise special to the shell.\nThe indices use the same convention as does parameter substitution, so that elements\nof $mend and $mbegin may be used in subscripts; the KSHARRAYS option is respected.\nSets of globbing flags are not considered parenthesised groups; only the first nine\nactive parentheses can be referenced.\n\nFor example,\n\nfoo=\"astringwithamessage\"\nif [[ $foo = (a|an)(#b)(*) ]]; then\nprint ${foo[$mbegin[1],$mend[1]]}\nfi\n\nprints `stringwithamessage'. Note that the first set of parentheses is before the\n(#b) and does not create a backreference.\n\nBackreferences work with all forms of pattern matching other than filename generation,\nbut note that when performing matches on an entire array, such as ${array#pattern}, or\na global substitution, such as ${param//pat/repl}, only the data for the last match\nremains available. In the case of global replacements this may still be useful. See\nthe example for the m flag below.\n\nThe numbering of backreferences strictly follows the order of the opening parentheses\nfrom left to right in the pattern string, although sets of parentheses may be nested.\nThere are special rules for parentheses followed by `#' or `##'. Only the last match\nof the parenthesis is remembered: for example, in `[[ abab = (#b)([ab])# ]]', only the\nfinal `b' is stored in match[1]. Thus extra parentheses may be necessary to match the\ncomplete segment: for example, use `X((ab|cd)#)Y' to match a whole string of either\n`ab' or `cd' between `X' and `Y', using the value of $match[1] rather than $match[2].\n\nIf the match fails none of the parameters is altered, so in some cases it may be nec‐\nessary to initialise them beforehand. If some of the backreferences fail to match --\nwhich happens if they are in an alternate branch which fails to match, or if they are\nfollowed by # and matched zero times -- then the matched string is set to the empty\nstring, and the start and end indices are set to -1.\n\nPattern matching with backreferences is slightly slower than without.\n\nB Deactivate backreferences, negating the effect of the b flag from that point on.\n\ncN,M The flag (#cN,M) can be used anywhere that the # or ## operators can be used except in\nthe expressions `(*/)#' and `(*/)##' in filename generation, where `/' has special\nmeaning; it cannot be combined with other globbing flags and a bad pattern error oc‐\ncurs if it is misplaced. It is equivalent to the form {N,M} in regular expressions.\nThe previous character or group is required to match between N and M times, inclusive.\nThe form (#cN) requires exactly N matches; (#c,M) is equivalent to specifying N as 0;\n(#cN,) specifies that there is no maximum limit on the number of matches.\n\nm Set references to the match data for the entire string matched; this is similar to\nbackreferencing and does not work in filename generation. The flag must be in effect\nat the end of the pattern, i.e. not local to a group. The parameters $MATCH, $MBEGIN\nand $MEND will be set to the string matched and to the indices of the beginning and\nend of the string, respectively. This is most useful in parameter substitutions, as\notherwise the string matched is obvious.\n\nFor example,\n\narr=(veldt jynx grimps waqf zho buck)\nprint ${arr//(#m)[aeiou]/${(U)MATCH}}\n\nforces all the matches (i.e. all vowels) into uppercase, printing `vEldt jynx grImps\nwAqf zhO bUck'.\n\nUnlike backreferences, there is no speed penalty for using match references, other\nthan the extra substitutions required for the replacement strings in cases such as the\nexample shown.\n\nM Deactivate the m flag, hence no references to match data will be created.\n\nanum Approximate matching: num errors are allowed in the string matched by the pattern.\nThe rules for this are described in the next subsection.\n\ns, e Unlike the other flags, these have only a local effect, and each must appear on its\nown: `(#s)' and `(#e)' are the only valid forms. The `(#s)' flag succeeds only at\nthe start of the test string, and the `(#e)' flag succeeds only at the end of the test\nstring; they correspond to `^' and `$' in standard regular expressions. They are use‐\nful for matching path segments in patterns other than those in filename generation\n(where path segments are in any case treated separately). For example,\n`*((#s)|/)test((#e)|/)*' matches a path segment `test' in any of the following\nstrings: test, test/at/start, at/end/test, in/test/middle.\n\nAnother use is in parameter substitution; for example `${array/(#s)A*Z(#e)}' will re‐\nmove only elements of an array which match the complete pattern `A*Z'. There are\nother ways of performing many operations of this type, however the combination of the\nsubstitution operations `/' and `//' with the `(#s)' and `(#e)' flags provides a sin‐\ngle simple and memorable method.\n\nNote that assertions of the form `(^(#s))' also work, i.e. match anywhere except at\nthe start of the string, although this actually means `anything except a zero-length\nportion at the start of the string'; you need to use `(\"\"~(#s))' to match a\nzero-length portion of the string not at the start.\n\nq A `q' and everything up to the closing parenthesis of the globbing flags are ignored\nby the pattern matching code. This is intended to support the use of glob qualifiers,\nsee below. The result is that the pattern `(#b)(*).c(#q.)' can be used both for glob‐\nbing and for matching against a string. In the former case, the `(#q.)' will be\ntreated as a glob qualifier and the `(#b)' will not be useful, while in the latter\ncase the `(#b)' is useful for backreferences and the `(#q.)' will be ignored. Note\nthat colon modifiers in the glob qualifiers are also not applied in ordinary pattern\nmatching.\n\nu Respect the current locale in determining the presence of multibyte characters in a\npattern, provided the shell was compiled with MULTIBYTESUPPORT. This overrides the\nMULTIBYTE option; the default behaviour is taken from the option. Compare U. (Mne‐\nmonic: typically multibyte characters are from Unicode in the UTF-8 encoding, although\nany extension of ASCII supported by the system library may be used.)\n\nU All characters are considered to be a single byte long. The opposite of u. This\noverrides the MULTIBYTE option.\n\nFor example, the test string fooxx can be matched by the pattern (#i)FOOXX, but not by\n(#l)FOOXX, (#i)FOO(#I)XX or ((#i)FOOX)X. The string (#ia2)readme specifies case-insensitive\nmatching of readme with up to two errors.\n\nWhen using the ksh syntax for grouping both KSHGLOB and EXTENDEDGLOB must be set and the\nleft parenthesis should be preceded by @. Note also that the flags do not affect letters in‐\nside [...] groups, in other words (#i)[a-z] still matches only lowercase letters. Finally,\nnote that when examining whole paths case-insensitively every directory must be searched for\nall files which match, so that a pattern of the form (#i)/foo/bar/... is potentially slow.\n" }, { "name": "Approximate Matching", "content": "When matching approximately, the shell keeps a count of the errors found, which cannot exceed\nthe number specified in the (#anum) flags. Four types of error are recognised:\n\n1. Different characters, as in fooxbar and fooybar.\n\n2. Transposition of characters, as in banana and abnana.\n\n3. A character missing in the target string, as with the pattern road and target string\nrod.\n\n4. An extra character appearing in the target string, as with stove and strove.\n\nThus, the pattern (#a3)abcd matches dcba, with the errors occurring by using the first rule\ntwice and the second once, grouping the string as [d][cb][a] and [a][bc][d].\n\nNon-literal parts of the pattern must match exactly, including characters in character\nranges: hence (#a1)??? matches strings of length four, by applying rule 4 to an empty part\nof the pattern, but not strings of length two, since all the ? must match. Other characters\nwhich must match exactly are initial dots in filenames (unless the GLOBDOTS option is set),\nand all slashes in filenames, so that a/bc is two errors from ab/c (the slash cannot be\ntransposed with another character). Similarly, errors are counted separately for non-con‐\ntiguous strings in the pattern, so that (ab|cd)ef is two errors from aebf.\n\nWhen using exclusion via the ~ operator, approximate matching is treated entirely separately\nfor the excluded part and must be activated separately. Thus, (#a1)README~README matches\nREAD.ME but not README, as the trailing README is matched without approximation. However,\n(#a1)README~(#a1)README does not match any pattern of the form READ?ME as all such forms are\nnow excluded.\n\nApart from exclusions, there is only one overall error count; however, the maximum errors al‐\nlowed may be altered locally, and this can be delimited by grouping. For example,\n(#a1)cat((#a0)dog)fox allows one error in total, which may not occur in the dog section, and\nthe pattern (#a1)cat(#a0)dog(#a1)fox is equivalent. Note that the point at which an error is\nfirst found is the crucial one for establishing whether to use approximation; for example,\n(#a1)abc(#a0)xyz will not match abcdxyz, because the error occurs at the `x', where approxi‐\nmation is turned off.\n\nEntire path segments may be matched approximately, so that `(#a1)/foo/d/is/avail‐‐\nable/at/the/bar' allows one error in any path segment. This is much less efficient than\nwithout the (#a1), however, since every directory in the path must be scanned for a possible\napproximate match. It is best to place the (#a1) after any path segments which are known to\nbe correct.\n" }, { "name": "Recursive Globbing", "content": "A pathname component of the form `(foo/)#' matches a path consisting of zero or more directo‐\nries matching the pattern foo.\n\nAs a shorthand, `/' is equivalent to `(*/)#'; note that this therefore matches files in the\ncurrent directory as well as subdirectories. Thus:\n\nls -ld -- (*/)#bar\n\nor\n\nls -ld -- /bar\n\ndoes a recursive directory search for files named `bar' (potentially including the file `bar'\nin the current directory). This form does not follow symbolic links; the alternative form\n`*/' does, but is otherwise identical. Neither of these can be combined with other forms\nof globbing within the same path segment; in that case, the `*' operators revert to their\nusual effect.\n\nEven shorter forms are available when the option GLOBSTARSHORT is set. In that case if no\n/ immediately follows a or * they are treated as if both a / plus a further * are\npresent. Hence:\n\nsetopt GLOBSTARSHORT\nls -ld -- .c\n\nis equivalent to\n\nls -ld -- /*.c\n" }, { "name": "Glob Qualifiers", "content": "Patterns used for filename generation may end in a list of qualifiers enclosed in parenthe‐\nses. The qualifiers specify which filenames that otherwise match the given pattern will be\ninserted in the argument list.\n\nIf the option BAREGLOBQUAL is set, then a trailing set of parentheses containing no `|' or\n`(' characters (or `~' if it is special) is taken as a set of glob qualifiers. A glob subex‐\npression that would normally be taken as glob qualifiers, for example `(^x)', can be forced\nto be treated as part of the glob pattern by doubling the parentheses, in this case producing\n`((^x))'.\n\nIf the option EXTENDEDGLOB is set, a different syntax for glob qualifiers is available,\nnamely `(#qx)' where x is any of the same glob qualifiers used in the other format. The\nqualifiers must still appear at the end of the pattern. However, with this syntax multiple\nglob qualifiers may be chained together. They are treated as a logical AND of the individual\nsets of flags. Also, as the syntax is unambiguous, the expression will be treated as glob\nqualifiers just as long any parentheses contained within it are balanced; appearance of `|',\n`(' or `~' does not negate the effect. Note that qualifiers will be recognised in this form\neven if a bare glob qualifier exists at the end of the pattern, for example `*(#q*)(.)' will\nrecognise executable regular files if both options are set; however, mixed syntax should\nprobably be avoided for the sake of clarity. Note that within conditions using the `[[' form\nthe presence of a parenthesised expression (#q...) at the end of a string indicates that\nglobbing should be performed; the expression may include glob qualifiers, but it is also\nvalid if it is simply (#q). This does not apply to the right hand side of pattern match op‐\nerators as the syntax already has special significance.\n\nA qualifier may be any one of the following:\n\n/ directories\n\nF `full' (i.e. non-empty) directories. Note that the opposite sense (^F) expands to\nempty directories and all non-directories. Use (/^F) for empty directories.\n\n. plain files\n\n@ symbolic links\n\n= sockets\n\np named pipes (FIFOs)\n\n* executable plain files (0100 or 0010 or 0001)\n\n% device files (character or block special)\n\n%b block special files\n\n%c character special files\n\nr owner-readable files (0400)\n\nw owner-writable files (0200)\n\nx owner-executable files (0100)\n\nA group-readable files (0040)\n\nI group-writable files (0020)\n\nE group-executable files (0010)\n\nR world-readable files (0004)\n\nW world-writable files (0002)\n\nX world-executable files (0001)\n\ns setuid files (04000)\n\nS setgid files (02000)\n\nt files with the sticky bit (01000)\n\nfspec files with access rights matching spec. This spec may be a octal number optionally\npreceded by a `=', a `+', or a `-'. If none of these characters is given, the behavior\nis the same as for `='. The octal number describes the mode bits to be expected, if\ncombined with a `=', the value given must match the file-modes exactly, with a `+', at\nleast the bits in the given number must be set in the file-modes, and with a `-', the\nbits in the number must not be set. Giving a `?' instead of a octal digit anywhere in\nthe number ensures that the corresponding bits in the file-modes are not checked, this\nis only useful in combination with `='.\n\nIf the qualifier `f' is followed by any other character anything up to the next match‐\ning character (`[', `{', and `<' match `]', `}', and `>' respectively, any other char‐\nacter matches itself) is taken as a list of comma-separated sub-specs. Each sub-spec\nmay be either an octal number as described above or a list of any of the characters\n`u', `g', `o', and `a', followed by a `=', a `+', or a `-', followed by a list of any\nof the characters `r', `w', `x', `s', and `t', or an octal digit. The first list of\ncharacters specify which access rights are to be checked. If a `u' is given, those for\nthe owner of the file are used, if a `g' is given, those of the group are checked, a\n`o' means to test those of other users, and the `a' says to test all three groups. The\n`=', `+', and `-' again says how the modes are to be checked and have the same meaning\nas described for the first form above. The second list of characters finally says\nwhich access rights are to be expected: `r' for read access, `w' for write access, `x'\nfor the right to execute the file (or to search a directory), `s' for the setuid and\nsetgid bits, and `t' for the sticky bit.\n\nThus, `*(f70?)' gives the files for which the owner has read, write, and execute per‐\nmission, and for which other group members have no rights, independent of the permis‐\nsions for other users. The pattern `*(f-100)' gives all files for which the owner does\nnot have execute permission, and `*(f:gu+w,o-rx:)' gives the files for which the owner\nand the other members of the group have at least write permission, and for which other\nusers don't have read or execute permission.\n\nestring\n+cmd The string will be executed as shell code. The filename will be included in the list\nif and only if the code returns a zero status (usually the status of the last com‐\nmand).\n\nIn the first form, the first character after the `e' will be used as a separator and\nanything up to the next matching separator will be taken as the string; `[', `{', and\n`<' match `]', `}', and `>', respectively, while any other character matches itself.\nNote that expansions must be quoted in the string to prevent them from being expanded\nbefore globbing is done. string is then executed as shell code. The string globqual\nis appended to the array zshevalcontext the duration of execution.\n\nDuring the execution of string the filename currently being tested is available in the\nparameter REPLY; the parameter may be altered to a string to be inserted into the list\ninstead of the original filename. In addition, the parameter reply may be set to an\narray or a string, which overrides the value of REPLY. If set to an array, the latter\nis inserted into the command line word by word.\n\nFor example, suppose a directory contains a single file `lonely'. Then the expression\n`*(e:'reply=(${REPLY}{1,2})':)' will cause the words `lonely1' and `lonely2' to be in‐\nserted into the command line. Note the quoting of string.\n\nThe form +cmd has the same effect, but no delimiters appear around cmd. Instead, cmd\nis taken as the longest sequence of characters following the + that are alphanumeric\nor underscore. Typically cmd will be the name of a shell function that contains the\nappropriate test. For example,\n\nnt() { [[ $REPLY -nt $NTREF ]] }\nNTREF=reffile\nls -ld -- *(+nt)\n\nlists all files in the directory that have been modified more recently than reffile.\n\nddev files on the device dev\n\nl[-|+]ct\nfiles having a link count less than ct (-), greater than ct (+), or equal to ct\n\nU files owned by the effective user ID\n\nG files owned by the effective group ID\n\nuid files owned by user ID id if that is a number. Otherwise, id specifies a user name:\nthe character after the `u' will be taken as a separator and the string between it and\nthe next matching separator will be taken as a user name. The starting separators\n`[', `{', and `<' match the final separators `]', `}', and `>', respectively; any\nother character matches itself. The selected files are those owned by this user. For\nexample, `u:foo:' or `u[foo]' selects files owned by user `foo'.\n\ngid like uid but with group IDs or names\n\na[Mwhms][-|+]n\nfiles accessed exactly n days ago. Files accessed within the last n days are selected\nusing a negative value for n (-n). Files accessed more than n days ago are selected\nby a positive n value (+n). Optional unit specifiers `M', `w', `h', `m' or `s' (e.g.\n`ah5') cause the check to be performed with months (of 30 days), weeks, hours, minutes\nor seconds instead of days, respectively. An explicit `d' for days is also allowed.\n\nAny fractional part of the difference between the access time and the current part in\nthe appropriate units is ignored in the comparison. For instance, `echo *(ah-5)'\nwould echo files accessed within the last five hours, while `echo *(ah+5)' would echo\nfiles accessed at least six hours ago, as times strictly between five and six hours\nare treated as five hours.\n\nm[Mwhms][-|+]n\nlike the file access qualifier, except that it uses the file modification time.\n\nc[Mwhms][-|+]n\nlike the file access qualifier, except that it uses the file inode change time.\n\nL[+|-]n\nfiles less than n bytes (-), more than n bytes (+), or exactly n bytes in length.\n\nIf this flag is directly followed by a size specifier `k' (`K'), `m' (`M'), or `p'\n(`P') (e.g. `Lk-50') the check is performed with kilobytes, megabytes, or blocks (of\n512 bytes) instead. (On some systems additional specifiers are available for giga‐\nbytes, `g' or `G', and terabytes, `t' or `T'.) If a size specifier is used a file is\nregarded as \"exactly\" the size if the file size rounded up to the next unit is equal\nto the test size. Hence `*(Lm1)' matches files from 1 byte up to 1 Megabyte inclu‐\nsive. Note also that the set of files \"less than\" the test size only includes files\nthat would not match the equality test; hence `*(Lm-1)' only matches files of zero\nsize.\n\n^ negates all qualifiers following it\n\n- toggles between making the qualifiers work on symbolic links (the default) and the\nfiles they point to\n\nM sets the MARKDIRS option for the current pattern\n\nT appends a trailing qualifier mark to the filenames, analogous to the LISTTYPES op‐\ntion, for the current pattern (overrides M)\n\nN sets the NULLGLOB option for the current pattern\n\nD sets the GLOBDOTS option for the current pattern\n\nn sets the NUMERICGLOBSORT option for the current pattern\n\nYn enables short-circuit mode: the pattern will expand to at most n filenames. If more\nthan n matches exist, only the first n matches in directory traversal order will be\nconsidered.\n\nImplies oN when no oc qualifier is used.\n\noc specifies how the names of the files should be sorted. If c is n they are sorted by\nname; if it is L they are sorted depending on the size (length) of the files; if l\nthey are sorted by the number of links; if a, m, or c they are sorted by the time of\nthe last access, modification, or inode change respectively; if d, files in subdirec‐\ntories appear before those in the current directory at each level of the search --\nthis is best combined with other criteria, for example `odon' to sort on names for\nfiles within the same directory; if N, no sorting is performed. Note that a, m, and c\ncompare the age against the current time, hence the first name in the list is the\nyoungest file. Also note that the modifiers ^ and - are used, so `*(^-oL)' gives a\nlist of all files sorted by file size in descending order, following any symbolic\nlinks. Unless oN is used, multiple order specifiers may occur to resolve ties.\n\nThe default sorting is n (by name) unless the Y glob qualifier is used, in which case\nit is N (unsorted).\n\noe and o+ are special cases; they are each followed by shell code, delimited as for\nthe e glob qualifier and the + glob qualifier respectively (see above). The code is\nexecuted for each matched file with the parameter REPLY set to the name of the file on\nentry and globsort appended to zshevalcontext. The code should modify the parameter\nREPLY in some fashion. On return, the value of the parameter is used instead of the\nfile name as the string on which to sort. Unlike other sort operators, oe and o+ may\nbe repeated, but note that the maximum number of sort operators of any kind that may\nappear in any glob expression is 12.\n\nOc like `o', but sorts in descending order; i.e. `*(^oc)' is the same as `*(Oc)' and\n`*(^Oc)' is the same as `*(oc)'; `Od' puts files in the current directory before those\nin subdirectories at each level of the search.\n\n[beg[,end]]\nspecifies which of the matched filenames should be included in the returned list. The\nsyntax is the same as for array subscripts. beg and the optional end may be mathemati‐\ncal expressions. As in parameter subscripting they may be negative to make them count\nfrom the last match backward. E.g.: `*(-OL[1,3])' gives a list of the names of the\nthree largest files.\n\nPstring\nThe string will be prepended to each glob match as a separate word. string is delim‐\nited in the same way as arguments to the e glob qualifier described above. The quali‐\nfier can be repeated; the words are prepended separately so that the resulting command\nline contains the words in the same order they were given in the list of glob quali‐\nfiers.\n\nA typical use for this is to prepend an option before all occurrences of a file name;\nfor example, the pattern `*(P:-f:)' produces the command line arguments `-f file1 -f\nfile2 ...'\n\nIf the modifier ^ is active, then string will be appended instead of prepended.\nPrepending and appending is done independently so both can be used on the same glob\nexpression; for example by writing `*(P:foo:^P:bar:^P:baz:)' which produces the com‐\nmand line arguments `foo baz file1 bar ...'\n\nMore than one of these lists can be combined, separated by commas. The whole list matches if\nat least one of the sublists matches (they are `or'ed, the qualifiers in the sublists are\n`and'ed). Some qualifiers, however, affect all matches generated, independent of the sublist\nin which they are given. These are the qualifiers `M', `T', `N', `D', `n', `o', `O' and the\nsubscripts given in brackets (`[...]').\n\nIf a `:' appears in a qualifier list, the remainder of the expression in parenthesis is in‐\nterpreted as a modifier (see the section `Modifiers' in the section `History Expansion').\nEach modifier must be introduced by a separate `:'. Note also that the result after modifi‐\ncation does not have to be an existing file. The name of any existing file can be followed\nby a modifier of the form `(:...)' even if no actual filename generation is performed, al‐\nthough note that the presence of the parentheses causes the entire expression to be subjected\nto any global pattern matching options such as NULLGLOB. Thus:\n\nls -ld -- *(-/)\n\nlists all directories and symbolic links that point to directories, and\n\nls -ld -- *(-@)\n\nlists all broken symbolic links, and\n\nls -ld -- *(%W)\n\nlists all world-writable device files in the current directory, and\n\nls -ld -- *(W,X)\n\nlists all files in the current directory that are world-writable or world-executable, and\n\nprint -rC1 /tmp/foo*(u0^@:t)\n\noutputs the basename of all root-owned files beginning with the string `foo' in /tmp, ignor‐\ning symlinks, and\n\nls -ld -- *.*~(lex|parse).[ch](^D^l1)\n\nlists all files having a link count of one whose names contain a dot (but not those starting\nwith a dot, since GLOBDOTS is explicitly switched off) except for lex.c, lex.h, parse.c and\nparse.h.\n\nprint -rC1 b*.pro(#q:s/pro/shmo/)(#q.:s/builtin/shmiltin/)\n\ndemonstrates how colon modifiers and other qualifiers may be chained together. The ordinary\nqualifier `.' is applied first, then the colon modifiers in order from left to right. So if\nEXTENDEDGLOB is set and the base pattern matches the regular file builtin.pro, the shell\nwill print `shmiltin.shmo'.\n\n\n\nZSHPARAM(1) General Commands Manual ZSHPARAM(1)\n\n\n" } ] }, "ARRAY PARAMETERS": { "content": "To assign an array value, write one of:\n\nset -A name value ...\nname=(value ...)\nname=([key]=value ...)\n\nIf no parameter name exists, an ordinary array parameter is created. If the parameter name\nexists and is a scalar, it is replaced by a new array.\n\nIn the third form, key is an expression that will be evaluated in arithmetic context (in its\nsimplest form, an integer) that gives the index of the element to be assigned with value. In\nthis form any elements not explicitly mentioned that come before the largest index to which a\nvalue is assigned are assigned an empty string. The indices may be in any order. Note that\nthis syntax is strict: [ and ]= must not be quoted, and key may not consist of the unquoted\nstring ]=, but is otherwise treated as a simple string. The enhanced forms of subscript ex‐\npression that may be used when directly subscripting a variable name, described in the sec‐\ntion Array Subscripts below, are not available.\n\nThe syntaxes with and without the explicit key may be mixed. An implicit key is deduced by\nincrementing the index from the previously assigned element. Note that it is not treated as\nan error if latter assignments in this form overwrite earlier assignments.\n\nFor example, assuming the option KSHARRAYS is not set, the following:\n\narray=(one [3]=three four)\n\ncauses the array variable array to contain four elements one, an empty string, three and\nfour, in that order.\n\nIn the forms where only value is specified, full command line expansion is performed.\n\nIn the [key]=value form, both key and value undergo all forms of expansion allowed for single\nword shell expansions (this does not include filename generation); these are as performed by\nthe parameter expansion flag (e) as described in zshexpn(1). Nested parentheses may surround\nvalue and are included as part of the value, which is joined into a plain string; this dif‐\nfers from ksh which allows the values themselves to be arrays. A future version of zsh may\nsupport that. To cause the brackets to be interpreted as a character class for filename gen‐\neration, and therefore to treat the resulting list of files as a set of values, quote the\nequal sign using any form of quoting. Example:\n\nname=([a-z]'='*)\n\nTo append to an array without changing the existing values, use one of the following:\n\nname+=(value ...)\nname+=([key]=value ...)\n\nIn the second form key may specify an existing index as well as an index off the end of the\nold array; any existing value is overwritten by value. Also, it is possible to use\n[key]+=value to append to the existing value at that index.\n\nWithin the parentheses on the right hand side of either form of the assignment, newlines and\nsemicolons are treated the same as white space, separating individual values. Any consecu‐\ntive sequence of such characters has the same effect.\n\nOrdinary array parameters may also be explicitly declared with:\n\ntypeset -a name\n\nAssociative arrays must be declared before assignment, by using:\n\ntypeset -A name\n\nWhen name refers to an associative array, the list in an assignment is interpreted as alter‐\nnating keys and values:\n\nset -A name key value ...\nname=(key value ...)\nname=([key]=value ...)\n\nNote that only one of the two syntaxes above may be used in any given assignment; the forms\nmay not be mixed. This is unlike the case of numerically indexed arrays.\n\nEvery key must have a value in this case. Note that this assigns to the entire array, delet‐\ning any elements that do not appear in the list. The append syntax may also be used with an\nassociative array:\n\nname+=(key value ...)\nname+=([key]=value ...)\n\nThis adds a new key/value pair if the key is not already present, and replaces the value for\nthe existing key if it is. In the second form it is also possible to use [key]+=value to ap‐\npend to the existing value at that key. Expansion is performed identically to the corre‐\nsponding forms for normal arrays, as described above.\n\nTo create an empty array (including associative arrays), use one of:\n\nset -A name\nname=()\n", "subsections": [ { "name": "Array Subscripts", "content": "Individual elements of an array may be selected using a subscript. A subscript of the form\n`[exp]' selects the single element exp, where exp is an arithmetic expression which will be\nsubject to arithmetic expansion as if it were surrounded by `$((...))'. The elements are\nnumbered beginning with 1, unless the KSHARRAYS option is set in which case they are num‐\nbered from zero.\n\nSubscripts may be used inside braces used to delimit a parameter name, thus `${foo[2]}' is\nequivalent to `$foo[2]'. If the KSHARRAYS option is set, the braced form is the only one\nthat works, as bracketed expressions otherwise are not treated as subscripts.\n\nIf the KSHARRAYS option is not set, then by default accesses to an array element with a sub‐\nscript that evaluates to zero return an empty string, while an attempt to write such an ele‐\nment is treated as an error. For backward compatibility the KSHZEROSUBSCRIPT option can be\nset to cause subscript values 0 and 1 to be equivalent; see the description of the option in\nzshoptions(1).\n\nThe same subscripting syntax is used for associative arrays, except that no arithmetic expan‐\nsion is applied to exp. However, the parsing rules for arithmetic expressions still apply,\nwhich affects the way that certain special characters must be protected from interpretation.\nSee Subscript Parsing below for details.\n\nA subscript of the form `[*]' or `[@]' evaluates to all elements of an array; there is no\ndifference between the two except when they appear within double quotes. `\"$foo[*]\"' evalu‐\nates to `\"$foo[1] $foo[2] ...\"', whereas `\"$foo[@]\"' evaluates to `\"$foo[1]\" \"$foo[2]\" ...'.\nFor associative arrays, `[*]' or `[@]' evaluate to all the values, in no particular order.\nNote that this does not substitute the keys; see the documentation for the `k' flag under Pa‐\nrameter Expansion Flags in zshexpn(1) for complete details. When an array parameter is ref‐\nerenced as `$name' (with no subscript) it evaluates to `$name[*]', unless the KSHARRAYS op‐\ntion is set in which case it evaluates to `${name[0]}' (for an associative array, this means\nthe value of the key `0', which may not exist even if there are values for other keys).\n\nA subscript of the form `[exp1,exp2]' selects all elements in the range exp1 to exp2, inclu‐\nsive. (Associative arrays are unordered, and so do not support ranges.) If one of the sub‐\nscripts evaluates to a negative number, say -n, then the nth element from the end of the ar‐\nray is used. Thus `$foo[-3]' is the third element from the end of the array foo, and\n`$foo[1,-1]' is the same as `$foo[*]'.\n\nSubscripting may also be performed on non-array values, in which case the subscripts specify\na substring to be extracted. For example, if FOO is set to `foobar', then `echo $FOO[2,5]'\nprints `ooba'. Note that some forms of subscripting described below perform pattern match‐\ning, and in that case the substring extends from the start of the match of the first sub‐\nscript to the end of the match of the second subscript. For example,\n\nstring=\"abcdefghijklm\"\nprint ${string[(r)d?,(r)h?]}\n\nprints `defghi'. This is an obvious generalisation of the rule for single-character matches.\nFor a single subscript, only a single character is referenced (not the range of characters\ncovered by the match).\n\nNote that in substring operations the second subscript is handled differently by the r and R\nsubscript flags: the former takes the shortest match as the length and the latter the longest\nmatch. Hence in the former case a * at the end is redundant while in the latter case it\nmatches the whole remainder of the string. This does not affect the result of the single\nsubscript case as here the length of the match is irrelevant.\n" }, { "name": "Array Element Assignment", "content": "A subscript may be used on the left side of an assignment like so:\n\nname[exp]=value\n\nIn this form of assignment the element or range specified by exp is replaced by the expres‐\nsion on the right side. An array (but not an associative array) may be created by assignment\nto a range or element. Arrays do not nest, so assigning a parenthesized list of values to an\nelement or range changes the number of elements in the array, shifting the other elements to\naccommodate the new values. (This is not supported for associative arrays.)\n\nThis syntax also works as an argument to the typeset command:\n\ntypeset \"name[exp]\"=value\n\nThe value may not be a parenthesized list in this case; only single-element assignments may\nbe made with typeset. Note that quotes are necessary in this case to prevent the brackets\nfrom being interpreted as filename generation operators. The noglob precommand modifier\ncould be used instead.\n\nTo delete an element of an ordinary array, assign `()' to that element. To delete an element\nof an associative array, use the unset command:\n\nunset \"name[exp]\"\n" }, { "name": "Subscript Flags", "content": "If the opening bracket, or the comma in a range, in any subscript expression is directly fol‐\nlowed by an opening parenthesis, the string up to the matching closing one is considered to\nbe a list of flags, as in `name[(flags)exp]'.\n\nThe flags s, n and b take an argument; the delimiter is shown below as `:', but any charac‐\nter, or the matching pairs `(...)', `{...}', `[...]', or `<...>', may be used, but note that\n`<...>' can only be used if the subscript is inside a double quoted expression or a parameter\nsubstitution enclosed in braces as otherwise the expression is interpreted as a redirection.\n\nThe flags currently understood are:\n\nw If the parameter subscripted is a scalar then this flag makes subscripting work on\nwords instead of characters. The default word separator is whitespace. When combined\nwith the i or I flag, the effect is to produce the index of the first character of the\nfirst/last word which matches the given pattern; note that a failed match in this case\nalways yields 0.\n\ns:string:\nThis gives the string that separates words (for use with the w flag). The delimiter\ncharacter : is arbitrary; see above.\n\np Recognize the same escape sequences as the print builtin in the string argument of a\nsubsequent `s' flag.\n\nf If the parameter subscripted is a scalar then this flag makes subscripting work on\nlines instead of characters, i.e. with elements separated by newlines. This is a\nshorthand for `pws:\\n:'.\n\nr Reverse subscripting: if this flag is given, the exp is taken as a pattern and the re‐\nsult is the first matching array element, substring or word (if the parameter is an\narray, if it is a scalar, or if it is a scalar and the `w' flag is given, respec‐\ntively). The subscript used is the number of the matching element, so that pairs of\nsubscripts such as `$foo[(r)??,3]' and `$foo[(r)??,(r)f*]' are possible if the parame‐\nter is not an associative array. If the parameter is an associative array, only the\nvalue part of each pair is compared to the pattern, and the result is that value.\n\nIf a search through an ordinary array failed, the search sets the subscript to one\npast the end of the array, and hence ${array[(r)pattern]} will substitute the empty\nstring. Thus the success of a search can be tested by using the (i) flag, for example\n(assuming the option KSHARRAYS is not in effect):\n\n[[ ${array[(i)pattern]} -le ${#array} ]]\n\nIf KSHARRAYS is in effect, the -le should be replaced by -lt.\n\nR Like `r', but gives the last match. For associative arrays, gives all possible\nmatches. May be used for assigning to ordinary array elements, but not for assigning\nto associative arrays. On failure, for normal arrays this has the effect of returning\nthe element corresponding to subscript 0; this is empty unless one of the options\nKSHARRAYS or KSHZEROSUBSCRIPT is in effect.\n\nNote that in subscripts with both `r' and `R' pattern characters are active even if\nthey were substituted for a parameter (regardless of the setting of GLOBSUBST which\ncontrols this feature in normal pattern matching). The flag `e' can be added to in‐\nhibit pattern matching. As this flag does not inhibit other forms of substitution,\ncare is still required; using a parameter to hold the key has the desired effect:\n\nkey2='original key'\nprint ${array[(Re)$key2]}\n\ni Like `r', but gives the index of the match instead; this may not be combined with a\nsecond argument. On the left side of an assignment, behaves like `r'. For associa‐\ntive arrays, the key part of each pair is compared to the pattern, and the first\nmatching key found is the result. On failure substitutes the length of the array plus\none, as discussed under the description of `r', or the empty string for an associative\narray.\n\nI Like `i', but gives the index of the last match, or all possible matching keys in an\nassociative array. On failure substitutes 0, or the empty string for an associative\narray. This flag is best when testing for values or keys that do not exist.\n\nk If used in a subscript on an associative array, this flag causes the keys to be inter‐\npreted as patterns, and returns the value for the first key found where exp is matched\nby the key. Note this could be any such key as no ordering of associative arrays is\ndefined. This flag does not work on the left side of an assignment to an associative\narray element. If used on another type of parameter, this behaves like `r'.\n\nK On an associative array this is like `k' but returns all values where exp is matched\nby the keys. On other types of parameters this has the same effect as `R'.\n\nn:expr:\nIf combined with `r', `R', `i' or `I', makes them give the nth or nth last match (if\nexpr evaluates to n). This flag is ignored when the array is associative. The delim‐\niter character : is arbitrary; see above.\n\nb:expr:\nIf combined with `r', `R', `i' or `I', makes them begin at the nth or nth last ele‐\nment, word, or character (if expr evaluates to n). This flag is ignored when the ar‐\nray is associative. The delimiter character : is arbitrary; see above.\n\ne This flag causes any pattern matching that would be performed on the subscript to use\nplain string matching instead. Hence `${array[(re)*]}' matches only the array element\nwhose value is *. Note that other forms of substitution such as parameter substitu‐\ntion are not inhibited.\n\nThis flag can also be used to force * or @ to be interpreted as a single key rather\nthan as a reference to all values. It may be used for either purpose on the left side\nof an assignment.\n\nSee Parameter Expansion Flags (zshexpn(1)) for additional ways to manipulate the results of\narray subscripting.\n" }, { "name": "Subscript Parsing", "content": "This discussion applies mainly to associative array key strings and to patterns used for re‐\nverse subscripting (the `r', `R', `i', etc. flags), but it may also affect parameter substi‐\ntutions that appear as part of an arithmetic expression in an ordinary subscript.\n\nTo avoid subscript parsing limitations in assignments to associative array elements, use the\nappend syntax:\n\naa+=('key with \"*strange*\" characters' 'value string')\n\nThe basic rule to remember when writing a subscript expression is that all text between the\nopening `[' and the closing `]' is interpreted as if it were in double quotes (see zsh‐\nmisc(1)). However, unlike double quotes which normally cannot nest, subscript expressions\nmay appear inside double-quoted strings or inside other subscript expressions (or both!), so\nthe rules have two important differences.\n\nThe first difference is that brackets (`[' and `]') must appear as balanced pairs in a sub‐\nscript expression unless they are preceded by a backslash (`\\'). Therefore, within a sub‐\nscript expression (and unlike true double-quoting) the sequence `\\[' becomes `[', and simi‐\nlarly `\\]' becomes `]'. This applies even in cases where a backslash is not normally re‐\nquired; for example, the pattern `[^[]' (to match any character other than an open bracket)\nshould be written `[^\\[]' in a reverse-subscript pattern. However, note that `\\[^\\[\\]' and\neven `\\[^[]' mean the same thing, because backslashes are always stripped when they appear\nbefore brackets!\n\nThe same rule applies to parentheses (`(' and `)') and braces (`{' and `}'): they must appear\neither in balanced pairs or preceded by a backslash, and backslashes that protect parentheses\nor braces are removed during parsing. This is because parameter expansions may be surrounded\nby balanced braces, and subscript flags are introduced by balanced parentheses.\n\nThe second difference is that a double-quote (`\"') may appear as part of a subscript expres‐\nsion without being preceded by a backslash, and therefore that the two characters `\\\"' remain\nas two characters in the subscript (in true double-quoting, `\\\"' becomes `\"'). However, be‐\ncause of the standard shell quoting rules, any double-quotes that appear must occur in bal‐\nanced pairs unless preceded by a backslash. This makes it more difficult to write a sub‐\nscript expression that contains an odd number of double-quote characters, but the reason for\nthis difference is so that when a subscript expression appears inside true double-quotes, one\ncan still write `\\\"' (rather than `\\\\\\\"') for `\"'.\n\nTo use an odd number of double quotes as a key in an assignment, use the typeset builtin and\nan enclosing pair of double quotes; to refer to the value of that key, again use double\nquotes:\n\ntypeset -A aa\ntypeset \"aa[one\\\"two\\\"three\\\"quotes]\"=QQQ\nprint \"$aa[one\\\"two\\\"three\\\"quotes]\"\n\nIt is important to note that the quoting rules do not change when a parameter expansion with\na subscript is nested inside another subscript expression. That is, it is not necessary to\nuse additional backslashes within the inner subscript expression; they are removed only once,\nfrom the innermost subscript outwards. Parameters are also expanded from the innermost sub‐\nscript first, as each expansion is encountered left to right in the outer expression.\n\nA further complication arises from a way in which subscript parsing is not different from\ndouble quote parsing. As in true double-quoting, the sequences `\\*', and `\\@' remain as two\ncharacters when they appear in a subscript expression. To use a literal `*' or `@' as an as‐\nsociative array key, the `e' flag must be used:\n\ntypeset -A aa\naa[(e)*]=star\nprint $aa[(e)*]\n\nA last detail must be considered when reverse subscripting is performed. Parameters appear‐\ning in the subscript expression are first expanded and then the complete expression is inter‐\npreted as a pattern. This has two effects: first, parameters behave as if GLOBSUBST were on\n(and it cannot be turned off); second, backslashes are interpreted twice, once when parsing\nthe array subscript and again when parsing the pattern. In a reverse subscript, it's neces‐\nsary to use four backslashes to cause a single backslash to match literally in the pattern.\nFor complex patterns, it is often easiest to assign the desired pattern to a parameter and\nthen refer to that parameter in the subscript, because then the backslashes, brackets, paren‐\ntheses, etc., are seen only when the complete expression is converted to a pattern. To match\nthe value of a parameter literally in a reverse subscript, rather than as a pattern, use\n`${(q)name}' (see zshexpn(1)) to quote the expanded value.\n\nNote that the `k' and `K' flags are reverse subscripting for an ordinary array, but are not\nreverse subscripting for an associative array! (For an associative array, the keys in the\narray itself are interpreted as patterns by those flags; the subscript is a plain string in\nthat case.)\n\nOne final note, not directly related to subscripting: the numeric names of positional parame‐\nters (described below) are parsed specially, so for example `$2foo' is equivalent to\n`${2}foo'. Therefore, to use subscript syntax to extract a substring from a positional pa‐\nrameter, the expansion must be surrounded by braces; for example, `${2[3,5]}' evaluates to\nthe third through fifth characters of the second positional parameter, but `$2[3,5]' is the\nentire second parameter concatenated with the filename generation pattern `[3,5]'.\n" } ] }, "POSITIONAL PARAMETERS": { "content": "The positional parameters provide access to the command-line arguments of a shell function,\nshell script, or the shell itself; see the section `Invocation', and also the section `Func‐\ntions'. The parameter n, where n is a number, is the nth positional parameter. The parame‐\nter `$0' is a special case, see the section `Parameters Set By The Shell'.\n\nThe parameters *, @ and argv are arrays containing all the positional parameters; thus\n`$argv[n]', etc., is equivalent to simply `$n'. Note that the options KSHARRAYS or\nKSHZEROSUBSCRIPT apply to these arrays as well, so with either of those options set,\n`${argv[0]}' is equivalent to `$1' and so on.\n\nPositional parameters may be changed after the shell or function starts by using the set\nbuiltin, by assigning to the argv array, or by direct assignment of the form `n=value' where\nn is the number of the positional parameter to be changed. This also creates (with empty\nvalues) any of the positions from 1 to n that do not already have values. Note that, because\nthe positional parameters form an array, an array assignment of the form `n=(value ...)' is\nallowed, and has the effect of shifting all the values at positions greater than n by as many\npositions as necessary to accommodate the new values.\n", "subsections": [] }, "LOCAL PARAMETERS": { "content": "Shell function executions delimit scopes for shell parameters. (Parameters are dynamically\nscoped.) The typeset builtin, and its alternative forms declare, integer, local and readonly\n(but not export), can be used to declare a parameter as being local to the innermost scope.\n\nWhen a parameter is read or assigned to, the innermost existing parameter of that name is\nused. (That is, the local parameter hides any less-local parameter.) However, assigning to\na non-existent parameter, or declaring a new parameter with export, causes it to be created\nin the outermost scope.\n\nLocal parameters disappear when their scope ends. unset can be used to delete a parameter\nwhile it is still in scope; any outer parameter of the same name remains hidden.\n\nSpecial parameters may also be made local; they retain their special attributes unless either\nthe existing or the newly-created parameter has the -h (hide) attribute. This may have unex‐\npected effects: there is no default value, so if there is no assignment at the point the\nvariable is made local, it will be set to an empty value (or zero in the case of integers).\nThe following:\n\ntypeset PATH=/new/directory:$PATH\n\nis valid for temporarily allowing the shell or programmes called from it to find the programs\nin /new/directory inside a function.\n\nNote that the restriction in older versions of zsh that local parameters were never exported\nhas been removed.\n", "subsections": [] }, "PARAMETERS SET BY THE SHELL": { "content": "In the parameter lists that follow, the mark `' indicates that the parameter is special.\n`' indicates that the parameter does not exist when the shell initializes in sh or ksh em‐\nulation mode.\n\nThe following parameters are automatically set by the shell:\n\n! The process ID of the last command started in the background with &, put into the\nbackground with the bg builtin, or spawned with coproc.\n\n# The number of positional parameters in decimal. Note that some confusion may occur\nwith the syntax $#param which substitutes the length of param. Use ${#} to resolve\nambiguities. In particular, the sequence `$#-...' in an arithmetic expression is in‐\nterpreted as the length of the parameter -, q.v.\n\nARGC \nSame as #.\n\n$ The process ID of this shell. Note that this indicates the original shell started by\ninvoking zsh; all processes forked from the shells without executing a new program,\nsuch as subshells started by (...), substitute the same value.\n\n- Flags supplied to the shell on invocation or by the set or setopt commands.\n\n* An array containing the positional parameters.\n\nargv \nSame as *. Assigning to argv changes the local positional parameters, but argv is not\nitself a local parameter. Deleting argv with unset in any function deletes it every‐\nwhere, although only the innermost positional parameter array is deleted (so * and @\nin other scopes are not affected).\n\n@ Same as argv[@], even when argv is not set.\n\n? The exit status returned by the last command.\n\n0 The name used to invoke the current shell, or as set by the -c command line option\nupon invocation. If the FUNCTIONARGZERO option is set, $0 is set upon entry to a\nshell function to the name of the function, and upon entry to a sourced script to the\nname of the script, and reset to its previous value when the function or script re‐\nturns.\n\nstatus \nSame as ?.\n\npipestatus \nAn array containing the exit statuses returned by all commands in the last pipeline.\n\n The last argument of the previous command. Also, this parameter is set in the envi‐\nronment of every command executed to the full pathname of the command.\n\nCPUTYPE\nThe machine type (microprocessor class or machine model), as determined at run time.\n\nEGID \nThe effective group ID of the shell process. If you have sufficient privileges, you\nmay change the effective group ID of the shell process by assigning to this parameter.\nAlso (assuming sufficient privileges), you may start a single command with a different\neffective group ID by `(EGID=gid; command)'\n\nIf this is made local, it is not implicitly set to 0, but may be explicitly set lo‐\ncally.\n\nEUID \nThe effective user ID of the shell process. If you have sufficient privileges, you\nmay change the effective user ID of the shell process by assigning to this parameter.\nAlso (assuming sufficient privileges), you may start a single command with a different\neffective user ID by `(EUID=uid; command)'\n\nIf this is made local, it is not implicitly set to 0, but may be explicitly set lo‐\ncally.\n\nERRNO \nThe value of errno (see errno(3)) as set by the most recently failed system call.\nThis value is system dependent and is intended for debugging purposes. It is also\nuseful with the zsh/system module which allows the number to be turned into a name or\nmessage.\n\nFUNCNEST \nInteger. If greater than or equal to zero, the maximum nesting depth of shell func‐\ntions. When it is exceeded, an error is raised at the point where a function is\ncalled. The default value is determined when the shell is configured, but is typi‐\ncally 500. Increasing the value increases the danger of a runaway function recursion\ncausing the shell to crash. Setting a negative value turns off the check.\n\nGID \nThe real group ID of the shell process. If you have sufficient privileges, you may\nchange the group ID of the shell process by assigning to this parameter. Also (assum‐\ning sufficient privileges), you may start a single command under a different group ID\nby `(GID=gid; command)'\n\nIf this is made local, it is not implicitly set to 0, but may be explicitly set lo‐\ncally.\n\nHISTCMD\nThe current history event number in an interactive shell, in other words the event\nnumber for the command that caused $HISTCMD to be read. If the current history event\nmodifies the history, HISTCMD changes to the new maximum history event number.\n\nHOST The current hostname.\n\nLINENO \nThe line number of the current line within the current script, sourced file, or shell\nfunction being executed, whichever was started most recently. Note that in the case\nof shell functions the line number refers to the function as it appeared in the origi‐\nnal definition, not necessarily as displayed by the functions builtin.\n\nLOGNAME\nIf the corresponding variable is not set in the environment of the shell, it is ini‐\ntialized to the login name corresponding to the current login session. This parameter\nis exported by default but this can be disabled using the typeset builtin. The value\nis set to the string returned by the getlogin(3) system call if that is available.\n\nMACHTYPE\nThe machine type (microprocessor class or machine model), as determined at compile\ntime.\n\nOLDPWD The previous working directory. This is set when the shell initializes and whenever\nthe directory changes.\n\nOPTARG \nThe value of the last option argument processed by the getopts command.\n\nOPTIND \nThe index of the last option argument processed by the getopts command.\n\nOSTYPE The operating system, as determined at compile time.\n\nPPID \nThe process ID of the parent of the shell. As for $$, the value indicates the parent\nof the original shell and does not change in subshells.\n\nPWD The present working directory. This is set when the shell initializes and whenever\nthe directory changes.\n\nRANDOM \nA pseudo-random integer from 0 to 32767, newly generated each time this parameter is\nreferenced. The random number generator can be seeded by assigning a numeric value to\nRANDOM.\n\nThe values of RANDOM form an intentionally-repeatable pseudo-random sequence; sub‐\nshells that reference RANDOM will result in identical pseudo-random values unless the\nvalue of RANDOM is referenced or seeded in the parent shell in between subshell invo‐\ncations.\n\nSECONDS \nThe number of seconds since shell invocation. If this parameter is assigned a value,\nthen the value returned upon reference will be the value that was assigned plus the\nnumber of seconds since the assignment.\n\nUnlike other special parameters, the type of the SECONDS parameter can be changed us‐\ning the typeset command. Only integer and one of the floating point types are al‐\nlowed. For example, `typeset -F SECONDS' causes the value to be reported as a float‐\ning point number. The value is available to microsecond accuracy, although the shell\nmay show more or fewer digits depending on the use of typeset. See the documentation\nfor the builtin typeset in zshbuiltins(1) for more details.\n\nSHLVL \nIncremented by one each time a new shell is started.\n", "subsections": [ { "name": "signals", "content": "An array containing the names of the signals. Note that with the standard zsh number‐\ning of array indices, where the first element has index 1, the signals are offset by 1\nfrom the signal number used by the operating system. For example, on typical\nUnix-like systems HUP is signal number 1, but is referred to as $signals[2]. This is\nbecause of EXIT at position 1 in the array, which is used internally by zsh but is not\nknown to the operating system.\n\nTRYBLOCKERROR \nIn an always block, indicates whether the preceding list of code caused an error. The\nvalue is 1 to indicate an error, 0 otherwise. It may be reset, clearing the error\ncondition. See Complex Commands in zshmisc(1)\n\nTRYBLOCKINTERRUPT \nThis variable works in a similar way to TRYBLOCKERROR, but represents the status of\nan interrupt from the signal SIGINT, which typically comes from the keyboard when the\nuser types ^C. If set to 0, any such interrupt will be reset; otherwise, the inter‐\nrupt is propagated after the always block.\n\nNote that it is possible that an interrupt arrives during the execution of the always\nblock; this interrupt is also propagated.\n\nTTY The name of the tty associated with the shell, if any.\n\nTTYIDLE \nThe idle time of the tty associated with the shell in seconds or -1 if there is no\nsuch tty.\n\nUID \nThe real user ID of the shell process. If you have sufficient privileges, you may\nchange the user ID of the shell by assigning to this parameter. Also (assuming suffi‐\ncient privileges), you may start a single command under a different user ID by\n`(UID=uid; command)'\n\nIf this is made local, it is not implicitly set to 0, but may be explicitly set lo‐\ncally.\n\nUSERNAME \nThe username corresponding to the real user ID of the shell process. If you have suf‐\nficient privileges, you may change the username (and also the user ID and group ID) of\nthe shell by assigning to this parameter. Also (assuming sufficient privileges), you\nmay start a single command under a different username (and user ID and group ID) by\n`(USERNAME=username; command)'\n\nVENDOR The vendor, as determined at compile time.\n\nzshevalcontext (ZSHEVALCONTEXT )\nAn array (colon-separated list) indicating the context of shell code that is being\nrun. Each time a piece of shell code that is stored within the shell is executed a\nstring is temporarily appended to the array to indicate the type of operation that is\nbeing performed. Read in order the array gives an indication of the stack of opera‐\ntions being performed with the most immediate context last.\n\nNote that the variable does not give information on syntactic context such as pipe‐\nlines or subshells. Use $ZSHSUBSHELL to detect subshells.\n\nThe context is one of the following:\ncmdarg Code specified by the -c option to the command line that invoked the shell.\n\ncmdsubst\nCommand substitution using the `...` or $(...) construct.\n\nequalsubst\nFile substitution using the =(...) construct.\n\neval Code executed by the eval builtin.\n\nevalautofunc\nCode executed with the KSHAUTOLOAD mechanism in order to define an autoloaded\nfunction.\n\nfc Code from the shell history executed by the -e option to the fc builtin.\n\nfile Lines of code being read directly from a file, for example by the source\nbuiltin.\n\nfilecode\nLines of code being read from a .zwc file instead of directly from the source\nfile.\n\nglobqual\nCode executed by the e or + glob qualifier.\n\nglobsort\nCode executed to order files by the o glob qualifier.\n\ninsubst\nFile substitution using the <(...) construct.\n\nloadautofunc\nCode read directly from a file to define an autoloaded function.\n\noutsubst\nFile substitution using the >(...) construct.\n\nsched Code executed by the sched builtin.\n\nshfunc A shell function.\n\nstty Code passed to stty by the STTY environment variable. Normally this is passed\ndirectly to the system's stty command, so this value is unlikely to be seen in\npractice.\n\nstyle Code executed as part of a style retrieved by the zstyle builtin from the\nzsh/zutil module.\n\ntoplevel\nThe highest execution level of a script or interactive shell.\n\ntrap Code executed as a trap defined by the trap builtin. Traps defined as func‐\ntions have the context shfunc. As traps are asynchronous they may have a dif‐\nferent hierarchy from other code.\n\nzpty Code executed by the zpty builtin from the zsh/zpty module.\n\nzregexparse-guard\nCode executed as a guard by the zregexparse command from the zsh/zutil module.\n\nzregexparse-action\nCode executed as an action by the zregexparse command from the zsh/zutil mod‐\nule.\n\nZSHARGZERO\nIf zsh was invoked to run a script, this is the name of the script. Otherwise, it is\nthe name used to invoke the current shell. This is the same as the value of $0 when\nthe POSIXARGZERO option is set, but is always available.\n\nZSHEXECUTIONSTRING\nIf the shell was started with the option -c, this contains the argument passed to the\noption. Otherwise it is not set.\n\nZSHNAME\nExpands to the basename of the command used to invoke this instance of zsh.\n\nZSHPATCHLEVEL\nThe output of `git describe --tags --long' for the zsh repository used to build the\nshell. This is most useful in order to keep track of versions of the shell during de‐\nvelopment between releases; hence most users should not use it and should instead rely\non $ZSHVERSION.\n\nzshscheduledevents\nSee the section `The zsh/sched Module' in zshmodules(1).\n\nZSHSCRIPT\nIf zsh was invoked to run a script, this is the name of the script, otherwise it is\nunset.\n\nZSHSUBSHELL\nReadonly integer. Initially zero, incremented each time the shell forks to create a\nsubshell for executing code. Hence `(print $ZSHSUBSHELL)' and `print $(print\n$ZSHSUBSHELL)' output 1, while `( (print $ZSHSUBSHELL) )' outputs 2.\n\nZSHVERSION\nThe version number of the release of zsh.\n" } ] }, "PARAMETERS USED BY THE SHELL": { "content": "The following parameters are used by the shell. Again, `' indicates that the parameter is\nspecial and `' indicates that the parameter does not exist when the shell initializes in\nsh or ksh emulation mode.\n\nIn cases where there are two parameters with an upper- and lowercase form of the same name,\nsuch as path and PATH, the lowercase form is an array and the uppercase form is a scalar with\nthe elements of the array joined together by colons. These are similar to tied parameters\ncreated via `typeset -T'. The normal use for the colon-separated form is for exporting to\nthe environment, while the array form is easier to manipulate within the shell. Note that\nunsetting either of the pair will unset the other; they retain their special properties when\nrecreated, and recreating one of the pair will recreate the other.\n\nARGV0 If exported, its value is used as the argv[0] of external commands. Usually used in\nconstructs like `ARGV0=emacs nethack'.\n\nBAUD The rate in bits per second at which data reaches the terminal. The line editor will\nuse this value in order to compensate for a slow terminal by delaying updates to the\ndisplay until necessary. If the parameter is unset or the value is zero the compensa‐\ntion mechanism is turned off. The parameter is not set by default.\n\nThis parameter may be profitably set in some circumstances, e.g. for slow modems di‐\naling into a communications server, or on a slow wide area network. It should be set\nto the baud rate of the slowest part of the link for best performance.\n\ncdpath (CDPATH )\nAn array (colon-separated list) of directories specifying the search path for the cd\ncommand.\n\nCOLUMNS \nThe number of columns for this terminal session. Used for printing select lists and\nfor the line editor.\n\nCORRECTIGNORE\nIf set, is treated as a pattern during spelling correction. Any potential correction\nthat matches the pattern is ignored. For example, if the value is `*' then comple‐\ntion functions (which, by convention, have names beginning with `') will never be of‐\nfered as spelling corrections. The pattern does not apply to the correction of file\nnames, as applied by the CORRECTALL option (so with the example just given files be‐\nginning with `' in the current directory would still be completed).\n\nCORRECTIGNOREFILE\nIf set, is treated as a pattern during spelling correction of file names. Any file\nname that matches the pattern is never offered as a correction. For example, if the\nvalue is `.*' then dot file names will never be offered as spelling corrections. This\nis useful with the CORRECTALL option.\n\nDIRSTACKSIZE\nThe maximum size of the directory stack, by default there is no limit. If the stack\ngets larger than this, it will be truncated automatically. This is useful with the\nAUTOPUSHD option.\n\nENV If the ENV environment variable is set when zsh is invoked as sh or ksh, $ENV is\nsourced after the profile scripts. The value of ENV is subjected to parameter expan‐\nsion, command substitution, and arithmetic expansion before being interpreted as a\npathname. Note that ENV is not used unless the shell is interactive and zsh is emu‐\nlating sh or ksh.\n\nFCEDIT The default editor for the fc builtin. If FCEDIT is not set, the parameter EDITOR is\nused; if that is not set either, a builtin default, usually vi, is used.\n\nfignore (FIGNORE )\nAn array (colon separated list) containing the suffixes of files to be ignored during\nfilename completion. However, if completion only generates files with suffixes in\nthis list, then these files are completed anyway.\n\nfpath (FPATH )\nAn array (colon separated list) of directories specifying the search path for function\ndefinitions. This path is searched when a function with the -u attribute is refer‐\nenced. If an executable file is found, then it is read and executed in the current\nenvironment.\n\nhistchars \nThree characters used by the shell's history and lexical analysis mechanism. The\nfirst character signals the start of a history expansion (default `!'). The second\ncharacter signals the start of a quick history substitution (default `^'). The third\ncharacter is the comment character (default `#').\n\nThe characters must be in the ASCII character set; any attempt to set histchars to\ncharacters with a locale-dependent meaning will be rejected with an error message.\n\nHISTCHARS \nSame as histchars. (Deprecated.)\n\nHISTFILE\nThe file to save the history in when an interactive shell exits. If unset, the his‐\ntory is not saved.\n\nHISTORYIGNORE\nIf set, is treated as a pattern at the time history files are written. Any potential\nhistory entry that matches the pattern is skipped. For example, if the value is `fc\n*' then commands that invoke the interactive history editor are never written to the\nhistory file.\n\nNote that HISTORYIGNORE defines a single pattern: to specify alternatives use the\n`(first|second|...)' syntax.\n\nCompare the HISTNOSTORE option or the zshaddhistory hook, either of which would pre‐\nvent such commands from being added to the interactive history at all. If you wish to\nuse HISTORYIGNORE to stop history being added in the first place, you can define the\nfollowing hook:\n\nzshaddhistory() {\nemulate -L zsh\n## uncomment if HISTORYIGNORE\n## should use EXTENDEDGLOB syntax\n# setopt extendedglob\n[[ $1 != ${~HISTORYIGNORE} ]]\n}\n\nHISTSIZE \nThe maximum number of events stored in the internal history list. If you use the\nHISTEXPIREDUPSFIRST option, setting this value larger than the SAVEHIST size will\ngive you the difference as a cushion for saving duplicated history events.\n\nIf this is made local, it is not implicitly set to 0, but may be explicitly set lo‐\ncally.\n\nHOME \nThe default argument for the cd command. This is not set automatically by the shell\nin sh, ksh or csh emulation, but it is typically present in the environment anyway,\nand if it becomes set it has its usual special behaviour.\n\nIFS \nInternal field separators (by default space, tab, newline and NUL), that are used to\nseparate words which result from command or parameter expansion and words read by the\nread builtin. Any characters from the set space, tab and newline that appear in the\nIFS are called IFS white space. One or more IFS white space characters or one non-IFS\nwhite space character together with any adjacent IFS white space character delimit a\nfield. If an IFS white space character appears twice consecutively in the IFS, this\ncharacter is treated as if it were not an IFS white space character.\n\nIf the parameter is unset, the default is used. Note this has a different effect from\nsetting the parameter to an empty string.\n\nKEYBOARDHACK\nThis variable defines a character to be removed from the end of the command line be‐\nfore interpreting it (interactive shells only). It is intended to fix the problem with\nkeys placed annoyingly close to return and replaces the SUNKEYBOARDHACK option which\ndid this for backquotes only. Should the chosen character be one of singlequote, dou‐\nblequote or backquote, there must also be an odd number of them on the command line\nfor the last one to be removed.\n\nFor backward compatibility, if the SUNKEYBOARDHACK option is explicitly set, the value\nof KEYBOARDHACK reverts to backquote. If the option is explicitly unset, this vari‐\nable is set to empty.\n\nKEYTIMEOUT\nThe time the shell waits, in hundredths of seconds, for another key to be pressed when\nreading bound multi-character sequences.\n\nLANG \nThis variable determines the locale category for any category not specifically se‐\nlected via a variable starting with `LC'.\n\nLCALL \nThis variable overrides the value of the `LANG' variable and the value of any of the\nother variables starting with `LC'.\n\nLCCOLLATE \nThis variable determines the locale category for character collation information\nwithin ranges in glob brackets and for sorting.\n\nLCCTYPE \nThis variable determines the locale category for character handling functions. If the\nMULTIBYTE option is in effect this variable or LANG should contain a value that re‐\nflects the character set in use, even if it is a single-byte character set, unless\nonly the 7-bit subset (ASCII) is used. For example, if the character set is\nISO-8859-1, a suitable value might be enUS.iso88591 (certain Linux distributions) or\nenUS.ISO8859-1 (MacOS).\n\nLCMESSAGES \nThis variable determines the language in which messages should be written. Note that\nzsh does not use message catalogs.\n\nLCNUMERIC \nThis variable affects the decimal point character and thousands separator character\nfor the formatted input/output functions and string conversion functions. Note that\nzsh ignores this setting when parsing floating point mathematical expressions.\n\nLCTIME \nThis variable determines the locale category for date and time formatting in prompt\nescape sequences.\n\nLINES \nThe number of lines for this terminal session. Used for printing select lists and for\nthe line editor.\n\nLISTMAX\nIn the line editor, the number of matches to list without asking first. If the value\nis negative, the list will be shown if it spans at most as many lines as given by the\nabsolute value. If set to zero, the shell asks only if the top of the listing would\nscroll off the screen.\n\nLOGCHECK\nThe interval in seconds between checks for login/logout activity using the watch pa‐\nrameter.\n\nMAIL If this parameter is set and mailpath is not set, the shell looks for mail in the\nspecified file.\n\nMAILCHECK\nThe interval in seconds between checks for new mail.\n\nmailpath (MAILPATH )\nAn array (colon-separated list) of filenames to check for new mail. Each filename can\nbe followed by a `?' and a message that will be printed. The message will undergo pa‐\nrameter expansion, command substitution and arithmetic expansion with the variable $\ndefined as the name of the file that has changed. The default message is `You have\nnew mail'. If an element is a directory instead of a file the shell will recursively\ncheck every file in every subdirectory of the element.\n\nmanpath (MANPATH )\nAn array (colon-separated list) whose value is not used by the shell. The manpath ar‐\nray can be useful, however, since setting it also sets MANPATH, and vice versa.\n", "subsections": [ { "name": "match", "content": "" }, { "name": "mbegin", "content": "mend Arrays set by the shell when the b globbing flag is used in pattern matches. See the\nsubsection Globbing flags in the documentation for Filename Generation in zshexpn(1).\n\nMATCH\nMBEGIN\nMEND Set by the shell when the m globbing flag is used in pattern matches. See the subsec‐\ntion Globbing flags in the documentation for Filename Generation in zshexpn(1).\n\nmodulepath (MODULEPATH )\nAn array (colon-separated list) of directories that zmodload searches for dynamically\nloadable modules. This is initialized to a standard pathname, usually `/usr/lo‐‐\ncal/lib/zsh/$ZSHVERSION'. (The `/usr/local/lib' part varies from installation to in‐\nstallation.) For security reasons, any value set in the environment when the shell is\nstarted will be ignored.\n\nThese parameters only exist if the installation supports dynamic module loading.\n\nNULLCMD \nThe command name to assume if a redirection is specified with no command. Defaults to\ncat. For sh/ksh behavior, change this to :. For csh-like behavior, unset this param‐\neter; the shell will print an error message if null commands are entered.\n\npath (PATH )\nAn array (colon-separated list) of directories to search for commands. When this pa‐\nrameter is set, each directory is scanned and all files found are put in a hash table.\n\nPOSTEDIT \nThis string is output whenever the line editor exits. It usually contains termcap\nstrings to reset the terminal.\n\nPROMPT \nPROMPT2 \nPROMPT3 \nPROMPT4 \nSame as PS1, PS2, PS3 and PS4, respectively.\n\nprompt \nSame as PS1.\n\nPROMPTEOLMARK\nWhen the PROMPTCR and PROMPTSP options are set, the PROMPTEOLMARK parameter can be\nused to customize how the end of partial lines are shown. This parameter undergoes\nprompt expansion, with the PROMPTPERCENT option set. If not set, the default behav‐\nior is equivalent to the value `%B%S%#%s%b'.\n\nPS1 \nThe primary prompt string, printed before a command is read. It undergoes a special\nform of expansion before being displayed; see EXPANSION OF PROMPT SEQUENCES in zsh‐\nmisc(1). The default is `%m%# '.\n\nPS2 \nThe secondary prompt, printed when the shell needs more information to complete a com‐\nmand. It is expanded in the same way as PS1. The default is `%> ', which displays\nany shell constructs or quotation marks which are currently being processed.\n\nPS3 \nSelection prompt used within a select loop. It is expanded in the same way as PS1.\nThe default is `?# '.\n\nPS4 \nThe execution trace prompt. Default is `+%N:%i> ', which displays the name of the\ncurrent shell structure and the line number within it. In sh or ksh emulation, the\ndefault is `+ '.\n\npsvar (PSVAR )\nAn array (colon-separated list) whose elements can be used in PROMPT strings. Setting\npsvar also sets PSVAR, and vice versa.\n\nREADNULLCMD \nThe command name to assume if a single input redirection is specified with no command.\nDefaults to more.\n\nREPORTMEMORY\nIf nonnegative, commands whose maximum resident set size (roughly speaking, main mem‐\nory usage) in kilobytes is greater than this value have timing statistics reported.\nThe format used to output statistics is the value of the TIMEFMT parameter, which is\nthe same as for the REPORTTIME variable and the time builtin; note that by default\nthis does not output memory usage. Appending \" max RSS %M\" to the value of TIMEFMT\ncauses it to output the value that triggered the report. If REPORTTIME is also in\nuse, at most a single report is printed for both triggers. This feature requires the\ngetrusage() system call, commonly supported by modern Unix-like systems.\n\nREPORTTIME\nIf nonnegative, commands whose combined user and system execution times (measured in\nseconds) are greater than this value have timing statistics printed for them. Output\nis suppressed for commands executed within the line editor, including completion; com‐\nmands explicitly marked with the time keyword still cause the summary to be printed in\nthis case.\n\nREPLY This parameter is reserved by convention to pass string values between shell scripts\nand shell builtins in situations where a function call or redirection are impossible\nor undesirable. The read builtin and the select complex command may set REPLY, and\nfilename generation both sets and examines its value when evaluating certain expres‐\nsions. Some modules also employ REPLY for similar purposes.\n\nreply As REPLY, but for array values rather than strings.\n\nRPROMPT \nRPS1 \nThis prompt is displayed on the right-hand side of the screen when the primary prompt\nis being displayed on the left. This does not work if the SINGLELINEZLE option is\nset. It is expanded in the same way as PS1.\n\nRPROMPT2 \nRPS2 \nThis prompt is displayed on the right-hand side of the screen when the secondary\nprompt is being displayed on the left. This does not work if the SINGLELINEZLE op‐\ntion is set. It is expanded in the same way as PS2.\n\nSAVEHIST\nThe maximum number of history events to save in the history file.\n\nIf this is made local, it is not implicitly set to 0, but may be explicitly set lo‐\ncally.\n\nSPROMPT \nThe prompt used for spelling correction. The sequence `%R' expands to the string\nwhich presumably needs spelling correction, and `%r' expands to the proposed correc‐\ntion. All other prompt escapes are also allowed.\n\nThe actions available at the prompt are [nyae]:\nn (`no') (default)\nDiscard the correction and run the command.\ny (`yes')\nMake the correction and run the command.\na (`abort')\nDiscard the entire command line without running it.\ne (`edit')\nResume editing the command line.\n\nSTTY If this parameter is set in a command's environment, the shell runs the stty command\nwith the value of this parameter as arguments in order to set up the terminal before\nexecuting the command. The modes apply only to the command, and are reset when it fin‐\nishes or is suspended. If the command is suspended and continued later with the fg or\nwait builtins it will see the modes specified by STTY, as if it were not suspended.\nThis (intentionally) does not apply if the command is continued via `kill -CONT'.\nSTTY is ignored if the command is run in the background, or if it is in the environ‐\nment of the shell but not explicitly assigned to in the input line. This avoids run‐\nning stty at every external command by accidentally exporting it. Also note that STTY\nshould not be used for window size specifications; these will not be local to the com‐\nmand.\n\nTERM \nThe type of terminal in use. This is used when looking up termcap sequences. An as‐\nsignment to TERM causes zsh to re-initialize the terminal, even if the value does not\nchange (e.g., `TERM=$TERM'). It is necessary to make such an assignment upon any\nchange to the terminal definition database or terminal type in order for the new set‐\ntings to take effect.\n\nTERMINFO \nA reference to your terminfo database, used by the `terminfo' library when the system\nhas it; see terminfo(5). If set, this causes the shell to reinitialise the terminal,\nmaking the workaround `TERM=$TERM' unnecessary.\n\nTERMINFODIRS \nA colon-seprarated list of terminfo databases, used by the `terminfo' library when the\nsystem has it; see terminfo(5). This variable is only used by certain terminal li‐\nbraries, in particular ncurses; see terminfo(5) to check support on your system. If\nset, this causes the shell to reinitialise the terminal, making the workaround\n`TERM=$TERM' unnecessary. Note that unlike other colon-separated arrays this is not\ntied to a zsh array.\n\nTIMEFMT\nThe format of process time reports with the time keyword. The default is `%J %U user\n%S system %P cpu %*E total'. Recognizes the following escape sequences, although not\nall may be available on all systems, and some that are available may not be useful:\n\n%% A `%'.\n%U CPU seconds spent in user mode.\n%S CPU seconds spent in kernel mode.\n%E Elapsed time in seconds.\n%P The CPU percentage, computed as 100*(%U+%S)/%E.\n%W Number of times the process was swapped.\n%X The average amount in (shared) text space used in kilobytes.\n%D The average amount in (unshared) data/stack space used in kilobytes.\n%K The total space used (%X+%D) in kilobytes.\n%M The maximum memory the process had in use at any time in kilobytes.\n%F The number of major page faults (page needed to be brought from disk).\n%R The number of minor page faults.\n%I The number of input operations.\n%O The number of output operations.\n%r The number of socket messages received.\n%s The number of socket messages sent.\n%k The number of signals received.\n%w Number of voluntary context switches (waits).\n%c Number of involuntary context switches.\n%J The name of this job.\n\nA star may be inserted between the percent sign and flags printing time (e.g., `%*E');\nthis causes the time to be printed in `hh:mm:ss.ttt' format (hours and minutes are\nonly printed if they are not zero). Alternatively, `m' or `u' may be used (e.g.,\n`%mE') to produce time output in milliseconds or microseconds, respectively.\n\nTMOUT If this parameter is nonzero, the shell will receive an ALRM signal if a command is\nnot entered within the specified number of seconds after issuing a prompt. If there is\na trap on SIGALRM, it will be executed and a new alarm is scheduled using the value of\nthe TMOUT parameter after executing the trap. If no trap is set, and the idle time of\nthe terminal is not less than the value of the TMOUT parameter, zsh terminates. Oth‐\nerwise a new alarm is scheduled to TMOUT seconds after the last keypress.\n\nTMPPREFIX\nA pathname prefix which the shell will use for all temporary files. Note that this\nshould include an initial part for the file name as well as any directory names. The\ndefault is `/tmp/zsh'.\n\nTMPSUFFIX\nA filename suffix which the shell will use for temporary files created by process sub‐\nstitutions (e.g., `=(list)'). Note that the value should include a leading dot `.' if\nintended to be interpreted as a file extension. The default is not to append any suf‐\nfix, thus this parameter should be assigned only when needed and then unset again.\n\nwatch (WATCH )\nAn array (colon-separated list) of login/logout events to report.\n\nIf it contains the single word `all', then all login/logout events are reported. If\nit contains the single word `notme', then all events are reported as with `all' except\n$USERNAME.\n\nAn entry in this list may consist of a username, an `@' followed by a remote hostname,\nand a `%' followed by a line (tty). Any of these may be a pattern (be sure to quote\nthis during the assignment to watch so that it does not immediately perform file gen‐\neration); the setting of the EXTENDEDGLOB option is respected. Any or all of these\ncomponents may be present in an entry; if a login/logout event matches all of them, it\nis reported.\n\nFor example, with the EXTENDEDGLOB option set, the following:\n\nwatch=('^(pws|barts)')\n\ncauses reports for activity associated with any user other than pws or barts.\n\nWATCHFMT\nThe format of login/logout reports if the watch parameter is set. Default is `%n has\n%a %l from %m'. Recognizes the following escape sequences:\n\n%n The name of the user that logged in/out.\n\n%a The observed action, i.e. \"logged on\" or \"logged off\".\n\n%l The line (tty) the user is logged in on.\n\n%M The full hostname of the remote host.\n\n%m The hostname up to the first `.'. If only the IP address is available or the\nutmp field contains the name of an X-windows display, the whole name is\nprinted.\n\nNOTE: The `%m' and `%M' escapes will work only if there is a host name field in\nthe utmp on your machine. Otherwise they are treated as ordinary strings.\n\n%S (%s)\nStart (stop) standout mode.\n\n%U (%u)\nStart (stop) underline mode.\n\n%B (%b)\nStart (stop) boldface mode.\n\n%t\n%@ The time, in 12-hour, am/pm format.\n\n%T The time, in 24-hour format.\n\n%w The date in `day-dd' format.\n\n%W The date in `mm/dd/yy' format.\n\n%D The date in `yy-mm-dd' format.\n\n%D{string}\nThe date formatted as string using the strftime function, with zsh extensions\nas described by EXPANSION OF PROMPT SEQUENCES in zshmisc(1).\n\n%(x:true-text:false-text)\nSpecifies a ternary expression. The character following the x is arbitrary;\nthe same character is used to separate the text for the \"true\" result from that\nfor the \"false\" result. Both the separator and the right parenthesis may be\nescaped with a backslash. Ternary expressions may be nested.\n\nThe test character x may be any one of `l', `n', `m' or `M', which indicate a\n`true' result if the corresponding escape sequence would return a non-empty\nvalue; or it may be `a', which indicates a `true' result if the watched user\nhas logged in, or `false' if he has logged out. Other characters evaluate to\nneither true nor false; the entire expression is omitted in this case.\n\nIf the result is `true', then the true-text is formatted according to the rules\nabove and printed, and the false-text is skipped. If `false', the true-text is\nskipped and the false-text is formatted and printed. Either or both of the\nbranches may be empty, but both separators must be present in any case.\n\nWORDCHARS \nA list of non-alphanumeric characters considered part of a word by the line editor.\n\nZBEEP If set, this gives a string of characters, which can use all the same codes as the\nbindkey command as described in the zsh/zle module entry in zshmodules(1), that will\nbe output to the terminal instead of beeping. This may have a visible instead of an\naudible effect; for example, the string `\\e[?5h\\e[?5l' on a vt100 or xterm will have\nthe effect of flashing reverse video on and off (if you usually use reverse video, you\nshould use the string `\\e[?5l\\e[?5h' instead). This takes precedence over the NOBEEP\noption.\n\nZDOTDIR\nThe directory to search for shell startup files (.zshrc, etc), if not $HOME.\n\nzlebracketedpaste\nMany terminal emulators have a feature that allows applications to identify when text\nis pasted into the terminal rather than being typed normally. For ZLE, this means that\nspecial characters such as tabs and newlines can be inserted instead of invoking edi‐\ntor commands. Furthermore, pasted text forms a single undo event and if the region is\nactive, pasted text will replace the region.\n\nThis two-element array contains the terminal escape sequences for enabling and dis‐\nabling the feature. These escape sequences are used to enable bracketed paste when ZLE\nis active and disable it at other times. Unsetting the parameter has the effect of\nensuring that bracketed paste remains disabled.\n\nzlehighlight\nAn array describing contexts in which ZLE should highlight the input text. See Char‐\nacter Highlighting in zshzle(1).\n\nZLELINEABORTED\nThis parameter is set by the line editor when an error occurs. It contains the line\nthat was being edited at the point of the error. `print -zr -- $ZLELINEABORTED' can\nbe used to recover the line. Only the most recent line of this kind is remembered.\n\nZLEREMOVESUFFIXCHARS\nZLESPACESUFFIXCHARS\nThese parameters are used by the line editor. In certain circumstances suffixes (typ‐\nically space or slash) added by the completion system will be removed automatically,\neither because the next editing command was not an insertable character, or because\nthe character was marked as requiring the suffix to be removed.\n\nThese variables can contain the sets of characters that will cause the suffix to be\nremoved. If ZLEREMOVESUFFIXCHARS is set, those characters will cause the suffix to\nbe removed; if ZLESPACESUFFIXCHARS is set, those characters will cause the suffix\nto be removed and replaced by a space.\n\nIf ZLEREMOVESUFFIXCHARS is not set, the default behaviour is equivalent to:\n\nZLEREMOVESUFFIXCHARS=$' \\t\\n;&|'\n\nIf ZLEREMOVESUFFIXCHARS is set but is empty, no characters have this behaviour.\nZLESPACESUFFIXCHARS takes precedence, so that the following:\n\nZLESPACESUFFIXCHARS=$'&|'\n\ncauses the characters `&' and `|' to remove the suffix but to replace it with a space.\n\nTo illustrate the difference, suppose that the option AUTOREMOVESLASH is in effect\nand the directory DIR has just been completed, with an appended /, following which the\nuser types `&'. The default result is `DIR&'. With ZLEREMOVESUFFIXCHARS set but\nwithout including `&' the result is `DIR/&'. With ZLESPACESUFFIXCHARS set to in‐\nclude `&' the result is `DIR &'.\n\nNote that certain completions may provide their own suffix removal or replacement be‐\nhaviour which overrides the values described here. See the completion system documen‐\ntation in zshcompsys(1).\n\nZLERPROMPTINDENT \nIf set, used to give the indentation between the right hand side of the right prompt\nin the line editor as given by RPS1 or RPROMPT and the right hand side of the screen.\nIf not set, the value 1 is used.\n\nTypically this will be used to set the value to 0 so that the prompt appears flush\nwith the right hand side of the screen. This is not the default as many terminals do\nnot handle this correctly, in particular when the prompt appears at the extreme bottom\nright of the screen. Recent virtual terminals are more likely to handle this case\ncorrectly. Some experimentation is necessary.\n\n\n\nZSHOPTIONS(1) General Commands Manual ZSHOPTIONS(1)\n\n\n" } ] }, "SPECIFYING OPTIONS": { "content": "Options are primarily referred to by name. These names are case insensitive and underscores\nare ignored. For example, `allexport' is equivalent to `AlleXPort'.\n\nThe sense of an option name may be inverted by preceding it with `no', so `setopt NoBeep' is\nequivalent to `unsetopt beep'. This inversion can only be done once, so `nonobeep' is not a\nsynonym for `beep'. Similarly, `tify' is not a synonym for `nonotify' (the inversion of `no‐‐\ntify').\n\nSome options also have one or more single letter names. There are two sets of single letter\noptions: one used by default, and another used to emulate sh/ksh (used when the SHOP‐‐\nTIONLETTERS option is set). The single letter options can be used on the shell command\nline, or with the set, setopt and unsetopt builtins, as normal Unix options preceded by `-'.\n\nThe sense of the single letter options may be inverted by using `+' instead of `-'. Some of\nthe single letter option names refer to an option being off, in which case the inversion of\nthat name refers to the option being on. For example, `+n' is the short name of `exec', and\n`-n' is the short name of its inversion, `noexec'.\n\nIn strings of single letter options supplied to the shell at startup, trailing whitespace\nwill be ignored; for example the string `-f ' will be treated just as `-f', but the string\n`-f i' is an error. This is because many systems which implement the `#!' mechanism for\ncalling scripts do not strip trailing whitespace.\n", "subsections": [] }, "DESCRIPTION OF OPTIONS": { "content": "In the following list, options set by default in all emulations are marked ; those set by\ndefault only in csh, ksh, sh, or zsh emulations are marked , , , as appropriate.\nWhen listing options (by `setopt', `unsetopt', `set -o' or `set +o'), those turned on by de‐\nfault appear in the list prefixed with `no'. Hence (unless KSHOPTIONPRINT is set), `se‐‐\ntopt' shows all options whose settings are changed from the default.\n", "subsections": [ { "name": "Changing Directories", "content": "AUTOCD (-J)\nIf a command is issued that can't be executed as a normal command, and the command is\nthe name of a directory, perform the cd command to that directory. This option is\nonly applicable if the option SHINSTDIN is set, i.e. if commands are being read from\nstandard input. The option is designed for interactive use; it is recommended that cd\nbe used explicitly in scripts to avoid ambiguity.\n\nAUTOPUSHD (-N)\nMake cd push the old directory onto the directory stack.\n\nCDABLEVARS (-T)\nIf the argument to a cd command (or an implied cd with the AUTOCD option set) is not\na directory, and does not begin with a slash, try to expand the expression as if it\nwere preceded by a `~' (see the section `Filename Expansion').\n\nCDSILENT\nNever print the working directory after a cd (whether explicit or implied with the\nAUTOCD option set). cd normally prints the working directory when the argument given\nto it was -, a stack entry, or the name of a directory found under CDPATH. Note that\nthis is distinct from pushd's stack-printing behaviour, which is controlled by\nPUSHDSILENT. This option overrides the printing-related effects of POSIXCD.\n\nCHASEDOTS\nWhen changing to a directory containing a path segment `..' which would otherwise be\ntreated as canceling the previous segment in the path (in other words, `foo/..' would\nbe removed from the path, or if `..' is the first part of the path, the last part of\nthe current working directory would be removed), instead resolve the path to the phys‐\nical directory. This option is overridden by CHASELINKS.\n\nFor example, suppose /foo/bar is a link to the directory /alt/rod. Without this op‐\ntion set, `cd /foo/bar/..' changes to /foo; with it set, it changes to /alt. The same\napplies if the current directory is /foo/bar and `cd ..' is used. Note that all other\nsymbolic links in the path will also be resolved.\n\nCHASELINKS (-w)\nResolve symbolic links to their true values when changing directory. This also has\nthe effect of CHASEDOTS, i.e. a `..' path segment will be treated as referring to the\nphysical parent, even if the preceding path segment is a symbolic link.\n\nPOSIXCD \nModifies the behaviour of cd, chdir and pushd commands to make them more compatible\nwith the POSIX standard. The behaviour with the option unset is described in the docu‐\nmentation for the cd builtin in zshbuiltins(1). If the option is set, the shell does\nnot test for directories beneath the local directory (`.') until after all directories\nin cdpath have been tested, and the cd and chdir commands do not recognise arguments\nof the form `{+|-}n' as directory stack entries.\n\nAlso, if the option is set, the conditions under which the shell prints the new direc‐\ntory after changing to it are modified. It is no longer restricted to interactive\nshells (although printing of the directory stack with pushd is still limited to inter‐\nactive shells); and any use of a component of CDPATH, including a `.' but excluding an\nempty component that is otherwise treated as `.', causes the directory to be printed.\n\nPUSHDIGNOREDUPS\nDon't push multiple copies of the same directory onto the directory stack.\n\nPUSHDMINUS\nExchanges the meanings of `+' and `-' when used with a number to specify a directory\nin the stack.\n\nPUSHDSILENT (-E)\nDo not print the directory stack after pushd or popd.\n\nPUSHDTOHOME (-D)\nHave pushd with no arguments act like `pushd $HOME'.\n" }, { "name": "Completion", "content": "ALWAYSLASTPROMPT \nIf unset, key functions that list completions try to return to the last prompt if\ngiven a numeric argument. If set these functions try to return to the last prompt if\ngiven no numeric argument.\n\nALWAYSTOEND\nIf a completion is performed with the cursor within a word, and a full completion is\ninserted, the cursor is moved to the end of the word. That is, the cursor is moved to\nthe end of the word if either a single match is inserted or menu completion is per‐\nformed.\n\nAUTOLIST (-9) \nAutomatically list choices on an ambiguous completion.\n\nAUTOMENU \nAutomatically use menu completion after the second consecutive request for completion,\nfor example by pressing the tab key repeatedly. This option is overridden by MENUCOM‐‐\nPLETE.\n\nAUTONAMEDIRS\nAny parameter that is set to the absolute name of a directory immediately becomes a\nname for that directory, that will be used by the `%~' and related prompt sequences,\nand will be available when completion is performed on a word starting with `~'. (Oth‐\nerwise, the parameter must be used in the form `~param' first.)\n\nAUTOPARAMKEYS \nIf a parameter name was completed and a following character (normally a space) auto‐\nmatically inserted, and the next character typed is one of those that have to come di‐\nrectly after the name (like `}', `:', etc.), the automatically added character is\ndeleted, so that the character typed comes immediately after the parameter name. Com‐\npletion in a brace expansion is affected similarly: the added character is a `,',\nwhich will be removed if `}' is typed next.\n\nAUTOPARAMSLASH \nIf a parameter is completed whose content is the name of a directory, then add a\ntrailing slash instead of a space.\n\nAUTOREMOVESLASH \nWhen the last character resulting from a completion is a slash and the next character\ntyped is a word delimiter, a slash, or a character that ends a command (such as a\nsemicolon or an ampersand), remove the slash.\n\nBASHAUTOLIST\nOn an ambiguous completion, automatically list choices when the completion function is\ncalled twice in succession. This takes precedence over AUTOLIST. The setting of\nLISTAMBIGUOUS is respected. If AUTOMENU is set, the menu behaviour will then start\nwith the third press. Note that this will not work with MENUCOMPLETE, since repeated\ncompletion calls immediately cycle through the list in that case.\n\nCOMPLETEALIASES\nPrevents aliases on the command line from being internally substituted before comple‐\ntion is attempted. The effect is to make the alias a distinct command for completion\npurposes.\n\nCOMPLETEINWORD\nIf unset, the cursor is set to the end of the word if completion is started. Otherwise\nit stays there and completion is done from both ends.\n\nGLOBCOMPLETE\nWhen the current word has a glob pattern, do not insert all the words resulting from\nthe expansion but generate matches as for completion and cycle through them like\nMENUCOMPLETE. The matches are generated as if a `*' was added to the end of the word,\nor inserted at the cursor when COMPLETEINWORD is set. This actually uses pattern\nmatching, not globbing, so it works not only for files but for any completion, such as\noptions, user names, etc.\n\nNote that when the pattern matcher is used, matching control (for example, case-insen‐\nsitive or anchored matching) cannot be used. This limitation only applies when the\ncurrent word contains a pattern; simply turning on the GLOBCOMPLETE option does not\nhave this effect.\n\nHASHLISTALL \nWhenever a command completion or spelling correction is attempted, make sure the en‐\ntire command path is hashed first. This makes the first completion slower but avoids\nfalse reports of spelling errors.\n\nLISTAMBIGUOUS \nThis option works when AUTOLIST or BASHAUTOLIST is also set. If there is an unam‐\nbiguous prefix to insert on the command line, that is done without a completion list\nbeing displayed; in other words, auto-listing behaviour only takes place when nothing\nwould be inserted. In the case of BASHAUTOLIST, this means that the list will be\ndelayed to the third call of the function.\n\nLISTBEEP \nBeep on an ambiguous completion. More accurately, this forces the completion widgets\nto return status 1 on an ambiguous completion, which causes the shell to beep if the\noption BEEP is also set; this may be modified if completion is called from a user-de‐\nfined widget.\n\nLISTPACKED\nTry to make the completion list smaller (occupying less lines) by printing the matches\nin columns with different widths.\n\nLISTROWSFIRST\nLay out the matches in completion lists sorted horizontally, that is, the second match\nis to the right of the first one, not under it as usual.\n\nLISTTYPES (-X) \nWhen listing files that are possible completions, show the type of each file with a\ntrailing identifying mark.\n\nMENUCOMPLETE (-Y)\nOn an ambiguous completion, instead of listing possibilities or beeping, insert the\nfirst match immediately. Then when completion is requested again, remove the first\nmatch and insert the second match, etc. When there are no more matches, go back to\nthe first one again. reverse-menu-complete may be used to loop through the list in\nthe other direction. This option overrides AUTOMENU.\n\nRECEXACT (-S)\nIf the string on the command line exactly matches one of the possible completions, it\nis accepted, even if there is another completion (i.e. that string with something else\nadded) that also matches.\n" }, { "name": "Expansion and Globbing", "content": "BADPATTERN (+2) \nIf a pattern for filename generation is badly formed, print an error message. (If\nthis option is unset, the pattern will be left unchanged.)\n\nBAREGLOBQUAL \nIn a glob pattern, treat a trailing set of parentheses as a qualifier list, if it con‐\ntains no `|', `(' or (if special) `~' characters. See the section `Filename Genera‐\ntion'.\n\nBRACECCL\nExpand expressions in braces which would not otherwise undergo brace expansion to a\nlexically ordered list of all the characters. See the section `Brace Expansion'.\n\nCASEGLOB \nMake globbing (filename generation) sensitive to case. Note that other uses of pat‐\nterns are always sensitive to case. If the option is unset, the presence of any char‐\nacter which is special to filename generation will cause case-insensitive matching.\nFor example, cvs(/) can match the directory CVS owing to the presence of the globbing\nflag (unless the option BAREGLOBQUAL is unset).\n\nCASEMATCH \nMake regular expressions using the zsh/regex module (including matches with =~) sensi‐\ntive to case.\n\nCSHNULLGLOB \nIf a pattern for filename generation has no matches, delete the pattern from the argu‐\nment list; do not report an error unless all the patterns in a command have no\nmatches. Overrides NOMATCH.\n\nEQUALS \nPerform = filename expansion. (See the section `Filename Expansion'.)\n\nEXTENDEDGLOB\nTreat the `#', `~' and `^' characters as part of patterns for filename generation,\netc. (An initial unquoted `~' always produces named directory expansion.)\n\nFORCEFLOAT\nConstants in arithmetic evaluation will be treated as floating point even without the\nuse of a decimal point; the values of integer variables will be converted to floating\npoint when used in arithmetic expressions. Integers in any base will be converted.\n\nGLOB (+F, ksh: +f) \nPerform filename generation (globbing). (See the section `Filename Generation'.)\n\nGLOBASSIGN \nIf this option is set, filename generation (globbing) is performed on the right hand\nside of scalar parameter assignments of the form `name=pattern (e.g. `foo=*'). If the\nresult has more than one word the parameter will become an array with those words as\narguments. This option is provided for backwards compatibility only: globbing is al‐\nways performed on the right hand side of array assignments of the form `name=(value)'\n(e.g. `foo=(*)') and this form is recommended for clarity; with this option set, it is\nnot possible to predict whether the result will be an array or a scalar.\n\nGLOBDOTS (-4)\nDo not require a leading `.' in a filename to be matched explicitly.\n\nGLOBSTARSHORT\nWhen this option is set and the default zsh-style globbing is in effect, the pattern\n`/*' can be abbreviated to `' and the pattern `*/*' can be abbreviated to *.\nHence `.c' finds a file ending in .c in any subdirectory, and `*.c' does the same\nwhile also following symbolic links. A / immediately after the `' or `*' forces\nthe pattern to be treated as the unabbreviated form.\n\nGLOBSUBST \nTreat any characters resulting from parameter expansion as being eligible for filename\nexpansion and filename generation, and any characters resulting from command substitu‐\ntion as being eligible for filename generation. Braces (and commas in between) do not\nbecome eligible for expansion.\n\nHISTSUBSTPATTERN\nSubstitutions using the :s and :& history modifiers are performed with pattern match‐\ning instead of string matching. This occurs wherever history modifiers are valid, in‐\ncluding glob qualifiers and parameters. See the section Modifiers in zshexpn(1).\n\nIGNOREBRACES (-I) \nDo not perform brace expansion. For historical reasons this also includes the effect\nof the IGNORECLOSEBRACES option.\n\nIGNORECLOSEBRACES\nWhen neither this option nor IGNOREBRACES is set, a sole close brace character `}' is\nsyntactically significant at any point on a command line. This has the effect that no\nsemicolon or newline is necessary before the brace terminating a function or current\nshell construct. When either option is set, a closing brace is syntactically signifi‐\ncant only in command position. Unlike IGNOREBRACES, this option does not disable\nbrace expansion.\n\nFor example, with both options unset a function may be defined in the following fash‐\nion:\n\nargs() { echo $# }\n\nwhile if either option is set, this does not work and something equivalent to the fol‐\nlowing is required:\n\nargs() { echo $#; }\n\nKSHGLOB \nIn pattern matching, the interpretation of parentheses is affected by a preceding `@',\n`*', `+', `?' or `!'. See the section `Filename Generation'.\n\nMAGICEQUALSUBST\nAll unquoted arguments of the form `anything=expression' appearing after the command\nname have filename expansion (that is, where expression has a leading `~' or `=') per‐\nformed on expression as if it were a parameter assignment. The argument is not other‐\nwise treated specially; it is passed to the command as a single argument, and not used\nas an actual parameter assignment. For example, in echo foo=~/bar:~/rod, both occur‐\nrences of ~ would be replaced. Note that this happens anyway with typeset and similar\nstatements.\n\nThis option respects the setting of the KSHTYPESET option. In other words, if both\noptions are in effect, arguments looking like assignments will not undergo word split‐\nting.\n\nMARKDIRS (-8, ksh: -X)\nAppend a trailing `/' to all directory names resulting from filename generation (glob‐\nbing).\n\nMULTIBYTE \nRespect multibyte characters when found in strings. When this option is set, strings\nare examined using the system library to determine how many bytes form a character,\ndepending on the current locale. This affects the way characters are counted in pat‐\ntern matching, parameter values and various delimiters.\n\nThe option is on by default if the shell was compiled with MULTIBYTESUPPORT; other‐\nwise it is off by default and has no effect if turned on.\n\nIf the option is off a single byte is always treated as a single character. This set‐\nting is designed purely for examining strings known to contain raw bytes or other val‐\nues that may not be characters in the current locale. It is not necessary to unset\nthe option merely because the character set for the current locale does not contain\nmultibyte characters.\n\nThe option does not affect the shell's editor, which always uses the locale to deter‐\nmine multibyte characters. This is because the character set displayed by the termi‐\nnal emulator is independent of shell settings.\n\nNOMATCH (+3) \nIf a pattern for filename generation has no matches, print an error, instead of leav‐\ning it unchanged in the argument list. This also applies to file expansion of an ini‐\ntial `~' or `='.\n\nNULLGLOB (-G)\nIf a pattern for filename generation has no matches, delete the pattern from the argu‐\nment list instead of reporting an error. Overrides NOMATCH.\n\nNUMERICGLOBSORT\nIf numeric filenames are matched by a filename generation pattern, sort the filenames\nnumerically rather than lexicographically.\n\nRCEXPANDPARAM (-P)\nArray expansions of the form `foo${xx}bar', where the parameter xx is set to (a b c),\nare substituted with `fooabar foobbar foocbar' instead of the default `fooa b cbar'.\nNote that an empty array will therefore cause all arguments to be removed.\n\nREMATCHPCRE\nIf set, regular expression matching with the =~ operator will use Perl-Compatible Reg‐\nular Expressions from the PCRE library. (The zsh/pcre module must be available.) If\nnot set, regular expressions will use the extended regexp syntax provided by the sys‐\ntem libraries.\n\nSHGLOB \nDisables the special meaning of `(', `|', `)' and '<' for globbing the result of pa‐\nrameter and command substitutions, and in some other places where the shell accepts\npatterns. If SHGLOB is set but KSHGLOB is not, the shell allows the interpretation\nof subshell expressions enclosed in parentheses in some cases where there is no space\nbefore the opening parenthesis, e.g. !(true) is interpreted as if there were a space\nafter the !. This option is set by default if zsh is invoked as sh or ksh.\n\nUNSET (+u, ksh: +u) \nTreat unset parameters as if they were empty when substituting, and as if they were\nzero when reading their values in arithmetic expansion and arithmetic commands. Oth‐\nerwise they are treated as an error.\n\nWARNCREATEGLOBAL\nPrint a warning message when a global parameter is created in a function by an assign‐\nment or in math context. This often indicates that a parameter has not been declared\nlocal when it should have been. Parameters explicitly declared global from within a\nfunction using typeset -g do not cause a warning. Note that there is no warning when\na local parameter is assigned to in a nested function, which may also indicate an er‐\nror.\n\nWARNNESTEDVAR\nPrint a warning message when an existing parameter from an enclosing function scope,\nor global, is set in a function by an assignment or in math context. Assignment to\nshell special parameters does not cause a warning. This is the companion to WARNCRE‐‐\nATEGLOBAL as in this case the warning is only printed when a parameter is not cre‐\nated. Where possible, use of typeset -g to set the parameter suppresses the error,\nbut note that this needs to be used every time the parameter is set. To restrict the\neffect of this option to a single function scope, use `functions -W'.\n\nFor example, the following code produces a warning for the assignment inside the func‐\ntion nested as that overrides the value within toplevel\n\ntoplevel() {\nlocal foo=\"in fn\"\nnested\n}\nnested() {\nfoo=\"in nested\"\n}\nsetopt warnnestedvar\ntoplevel\n" }, { "name": "History", "content": "APPENDHISTORY \nIf this is set, zsh sessions will append their history list to the history file,\nrather than replace it. Thus, multiple parallel zsh sessions will all have the new en‐\ntries from their history lists added to the history file, in the order that they exit.\nThe file will still be periodically re-written to trim it when the number of lines\ngrows 20% beyond the value specified by $SAVEHIST (see also the HISTSAVEBYCOPY op‐\ntion).\n\nBANGHIST (+K) \nPerform textual history expansion, csh-style, treating the character `!' specially.\n\nEXTENDEDHISTORY \nSave each command's beginning timestamp (in seconds since the epoch) and the duration\n(in seconds) to the history file. The format of this prefixed data is:\n\n`: :;'.\n\nHISTALLOWCLOBBER\nAdd `|' to output redirections in the history. This allows history references to\nclobber files even when CLOBBER is unset.\n\nHISTBEEP \nBeep in ZLE when a widget attempts to access a history entry which isn't there.\n\nHISTEXPIREDUPSFIRST\nIf the internal history needs to be trimmed to add the current command line, setting\nthis option will cause the oldest history event that has a duplicate to be lost before\nlosing a unique event from the list. You should be sure to set the value of HISTSIZE\nto a larger number than SAVEHIST in order to give you some room for the duplicated\nevents, otherwise this option will behave just like HISTIGNOREALLDUPS once the his‐\ntory fills up with unique events.\n\nHISTFCNTLLOCK\nWhen writing out the history file, by default zsh uses ad-hoc file locking to avoid\nknown problems with locking on some operating systems. With this option locking is\ndone by means of the system's fcntl call, where this method is available. On recent\noperating systems this may provide better performance, in particular avoiding history\ncorruption when files are stored on NFS.\n\nHISTFINDNODUPS\nWhen searching for history entries in the line editor, do not display duplicates of a\nline previously found, even if the duplicates are not contiguous.\n\nHISTIGNOREALLDUPS\nIf a new command line being added to the history list duplicates an older one, the\nolder command is removed from the list (even if it is not the previous event).\n\nHISTIGNOREDUPS (-h)\nDo not enter command lines into the history list if they are duplicates of the previ‐\nous event.\n\nHISTIGNORESPACE (-g)\nRemove command lines from the history list when the first character on the line is a\nspace, or when one of the expanded aliases contains a leading space. Only normal\naliases (not global or suffix aliases) have this behaviour. Note that the command\nlingers in the internal history until the next command is entered before it vanishes,\nallowing you to briefly reuse or edit the line. If you want to make it vanish right\naway without entering another command, type a space and press return.\n\nHISTLEXWORDS\nBy default, shell history that is read in from files is split into words on all white\nspace. This means that arguments with quoted whitespace are not correctly handled,\nwith the consequence that references to words in history lines that have been read\nfrom a file may be inaccurate. When this option is set, words read in from a history\nfile are divided up in a similar fashion to normal shell command line handling. Al‐\nthough this produces more accurately delimited words, if the size of the history file\nis large this can be slow. Trial and error is necessary to decide.\n\nHISTNOFUNCTIONS\nRemove function definitions from the history list. Note that the function lingers in\nthe internal history until the next command is entered before it vanishes, allowing\nyou to briefly reuse or edit the definition.\n\nHISTNOSTORE\nRemove the history (fc -l) command from the history list when invoked. Note that the\ncommand lingers in the internal history until the next command is entered before it\nvanishes, allowing you to briefly reuse or edit the line.\n\nHISTREDUCEBLANKS\nRemove superfluous blanks from each command line being added to the history list.\n\nHISTSAVEBYCOPY \nWhen the history file is re-written, we normally write out a copy of the file named\n$HISTFILE.new and then rename it over the old one. However, if this option is unset,\nwe instead truncate the old history file and write out the new version in-place. If\none of the history-appending options is enabled, this option only has an effect when\nthe enlarged history file needs to be re-written to trim it down to size. Disable\nthis only if you have special needs, as doing so makes it possible to lose history en‐\ntries if zsh gets interrupted during the save.\n\nWhen writing out a copy of the history file, zsh preserves the old file's permissions\nand group information, but will refuse to write out a new file if it would change the\nhistory file's owner.\n\nHISTSAVENODUPS\nWhen writing out the history file, older commands that duplicate newer ones are omit‐\nted.\n\nHISTVERIFY\nWhenever the user enters a line with history expansion, don't execute the line di‐\nrectly; instead, perform history expansion and reload the line into the editing buf‐\nfer.\n\nINCAPPENDHISTORY\nThis option works like APPENDHISTORY except that new history lines are added to the\n$HISTFILE incrementally (as soon as they are entered), rather than waiting until the\nshell exits. The file will still be periodically re-written to trim it when the num‐\nber of lines grows 20% beyond the value specified by $SAVEHIST (see also the\nHISTSAVEBYCOPY option).\n\nINCAPPENDHISTORYTIME\nThis option is a variant of INCAPPENDHISTORY in which, where possible, the history\nentry is written out to the file after the command is finished, so that the time taken\nby the command is recorded correctly in the history file in EXTENDEDHISTORY format.\nThis means that the history entry will not be available immediately from other in‐\nstances of the shell that are using the same history file.\n\nThis option is only useful if INCAPPENDHISTORY and SHAREHISTORY are turned off.\nThe three options should be considered mutually exclusive.\n\nSHAREHISTORY \n\nThis option both imports new commands from the history file, and also causes your\ntyped commands to be appended to the history file (the latter is like specifying\nINCAPPENDHISTORY, which should be turned off if this option is in effect). The his‐\ntory lines are also output with timestamps ala EXTENDEDHISTORY (which makes it easier\nto find the spot where we left off reading the file after it gets re-written).\n\nBy default, history movement commands visit the imported lines as well as the local\nlines, but you can toggle this on and off with the set-local-history zle binding. It\nis also possible to create a zle widget that will make some commands ignore imported\ncommands, and some include them.\n\nIf you find that you want more control over when commands get imported, you may wish\nto turn SHAREHISTORY off, INCAPPENDHISTORY or INCAPPENDHISTORYTIME (see above)\non, and then manually import commands whenever you need them using `fc -RI'.\n" }, { "name": "Initialisation", "content": "ALLEXPORT (-a, ksh: -a)\nAll parameters subsequently defined are automatically exported.\n\nGLOBALEXPORT \nIf this option is set, passing the -x flag to the builtins declare, float, integer,\nreadonly and typeset (but not local) will also set the -g flag; hence parameters ex‐\nported to the environment will not be made local to the enclosing function, unless\nthey were already or the flag +g is given explicitly. If the option is unset, ex‐\nported parameters will be made local in just the same way as any other parameter.\n\nThis option is set by default for backward compatibility; it is not recommended that\nits behaviour be relied upon. Note that the builtin export always sets both the -x\nand -g flags, and hence its effect extends beyond the scope of the enclosing function;\nthis is the most portable way to achieve this behaviour.\n\nGLOBALRCS (-d) \nIf this option is unset, the startup files /etc/zsh/zprofile, /etc/zsh/zshrc,\n/etc/zsh/zlogin and /etc/zsh/zlogout will not be run. It can be disabled and re-en‐\nabled at any time, including inside local startup files (.zshrc, etc.).\n\nRCS (+f) \nAfter /etc/zsh/zshenv is sourced on startup, source the .zshenv, /etc/zsh/zprofile,\n.zprofile, /etc/zsh/zshrc, .zshrc, /etc/zsh/zlogin, .zlogin, and .zlogout files, as\ndescribed in the section `Files'. If this option is unset, the /etc/zsh/zshenv file\nis still sourced, but any of the others will not be; it can be set at any time to pre‐\nvent the remaining startup files after the currently executing one from being sourced.\n" }, { "name": "Input/Output", "content": "ALIASES \nExpand aliases.\n\nCLOBBER (+C, ksh: +C) \nAllows `>' redirection to truncate existing files. Otherwise `>!' or `>|' must be\nused to truncate a file.\n\nIf the option is not set, and the option APPENDCREATE is also not set, `>>!' or `>>|'\nmust be used to create a file. If either option is set, `>>' may be used.\n\nCORRECT (-0)\nTry to correct the spelling of commands. Note that, when the HASHLISTALL option is\nnot set or when some directories in the path are not readable, this may falsely report\nspelling errors the first time some commands are used.\n\nThe shell variable CORRECTIGNORE may be set to a pattern to match words that will\nnever be offered as corrections.\n\nCORRECTALL (-O)\nTry to correct the spelling of all arguments in a line.\n\nThe shell variable CORRECTIGNOREFILE may be set to a pattern to match file names\nthat will never be offered as corrections.\n\nDVORAK Use the Dvorak keyboard instead of the standard qwerty keyboard as a basis for examin‐\ning spelling mistakes for the CORRECT and CORRECTALL options and the spell-word edi‐\ntor command.\n\nFLOWCONTROL \nIf this option is unset, output flow control via start/stop characters (usually as‐\nsigned to ^S/^Q) is disabled in the shell's editor.\n\nIGNOREEOF (-7)\nDo not exit on end-of-file. Require the use of exit or logout instead. However, ten\nconsecutive EOFs will cause the shell to exit anyway, to avoid the shell hanging if\nits tty goes away.\n\nAlso, if this option is set and the Zsh Line Editor is used, widgets implemented by\nshell functions can be bound to EOF (normally Control-D) without printing the normal\nwarning message. This works only for normal widgets, not for completion widgets.\n\nINTERACTIVECOMMENTS (-k) \nAllow comments even in interactive shells.\n\nHASHCMDS \nNote the location of each command the first time it is executed. Subsequent invoca‐\ntions of the same command will use the saved location, avoiding a path search. If\nthis option is unset, no path hashing is done at all. However, when CORRECT is set,\ncommands whose names do not appear in the functions or aliases hash tables are hashed\nin order to avoid reporting them as spelling errors.\n\nHASHDIRS \nWhenever a command name is hashed, hash the directory containing it, as well as all\ndirectories that occur earlier in the path. Has no effect if neither HASHCMDS nor\nCORRECT is set.\n\nHASHEXECUTABLESONLY\nWhen hashing commands because of HASHCMDS, check that the file to be hashed is actu‐\nally an executable. This option is unset by default as if the path contains a large\nnumber of commands, or consists of many remote files, the additional tests can take a\nlong time. Trial and error is needed to show if this option is beneficial.\n\nMAILWARNING (-U)\nPrint a warning message if a mail file has been accessed since the shell last checked.\n\nPATHDIRS (-Q)\nPerform a path search even on command names with slashes in them. Thus if `/usr/lo‐‐\ncal/bin' is in the user's path, and he or she types `X11/xinit', the command `/usr/lo‐‐\ncal/bin/X11/xinit' will be executed (assuming it exists). Commands explicitly begin‐\nning with `/', `./' or `../' are not subject to the path search. This also applies to\nthe `.' and source builtins.\n\nNote that subdirectories of the current directory are always searched for executables\nspecified in this form. This takes place before any search indicated by this option,\nand regardless of whether `.' or the current directory appear in the command search\npath.\n\nPATHSCRIPT \nIf this option is not set, a script passed as the first non-option argument to the\nshell must contain the name of the file to open. If this option is set, and the\nscript does not specify a directory path, the script is looked for first in the cur‐\nrent directory, then in the command path. See the section INVOCATION in zsh(1).\n\nPRINTEIGHTBIT\nPrint eight bit characters literally in completion lists, etc. This option is not\nnecessary if your system correctly returns the printability of eight bit characters\n(see ctype(3)).\n\nPRINTEXITVALUE (-1)\nPrint the exit value of programs with non-zero exit status. This is only available at\nthe command line in interactive shells.\n\nRCQUOTES\nAllow the character sequence `''' to signify a single quote within singly quoted\nstrings. Note this does not apply in quoted strings using the format $'...', where a\nbackslashed single quote can be used.\n\nRMSTARSILENT (-H) \nDo not query the user before executing `rm *' or `rm path/*'.\n\nRMSTARWAIT\nIf querying the user before executing `rm *' or `rm path/*', first wait ten seconds\nand ignore anything typed in that time. This avoids the problem of reflexively an‐\nswering `yes' to the query when one didn't really mean it. The wait and query can al‐\nways be avoided by expanding the `*' in ZLE (with tab).\n\nSHORTLOOPS \nAllow the short forms of for, repeat, select, if, and function constructs.\n\nSUNKEYBOARDHACK (-L)\nIf a line ends with a backquote, and there are an odd number of backquotes on the\nline, ignore the trailing backquote. This is useful on some keyboards where the re‐\nturn key is too small, and the backquote key lies annoyingly close to it. As an al‐\nternative the variable KEYBOARDHACK lets you choose the character to be removed.\n" }, { "name": "Job Control", "content": "AUTOCONTINUE\nWith this option set, stopped jobs that are removed from the job table with the disown\nbuiltin command are automatically sent a CONT signal to make them running.\n\nAUTORESUME (-W)\nTreat single word simple commands without redirection as candidates for resumption of\nan existing job.\n\nBGNICE (-6) \nRun all background jobs at a lower priority. This option is set by default.\n\nCHECKJOBS \nReport the status of background and suspended jobs before exiting a shell with job\ncontrol; a second attempt to exit the shell will succeed. NOCHECKJOBS is best used\nonly in combination with NOHUP, else such jobs will be killed automatically.\n\nThe check is omitted if the commands run from the previous command line included a\n`jobs' command, since it is assumed the user is aware that there are background or\nsuspended jobs. A `jobs' command run from one of the hook functions defined in the\nsection SPECIAL FUNCTIONS in zshmisc(1) is not counted for this purpose.\n\nCHECKRUNNINGJOBS \nCheck for both running and suspended jobs when CHECKJOBS is enabled. When this op‐\ntion is disabled, zsh checks only for suspended jobs, which matches the default behav‐\nior of bash.\n\nThis option has no effect unless CHECKJOBS is set.\n\nHUP \nSend the HUP signal to running jobs when the shell exits.\n\nLONGLISTJOBS (-R)\nPrint job notifications in the long format by default.\n\nMONITOR (-m, ksh: -m)\nAllow job control. Set by default in interactive shells.\n\nNOTIFY (-5, ksh: -b) \nReport the status of background jobs immediately, rather than waiting until just be‐\nfore printing a prompt.\n\nPOSIXJOBS \nThis option makes job control more compliant with the POSIX standard.\n\nWhen the option is not set, the MONITOR option is unset on entry to subshells, so that\njob control is no longer active. When the option is set, the MONITOR option and job\ncontrol remain active in the subshell, but note that the subshell has no access to\njobs in the parent shell.\n\nWhen the option is not set, jobs put in the background or foreground with bg or fg are\ndisplayed with the same information that would be reported by jobs. When the option\nis set, only the text is printed. The output from jobs itself is not affected by the\noption.\n\nWhen the option is not set, job information from the parent shell is saved for output\nwithin a subshell (for example, within a pipeline). When the option is set, the out‐\nput of jobs is empty until a job is started within the subshell.\n\nIn previous versions of the shell, it was necessary to enable POSIXJOBS in order for\nthe builtin command wait to return the status of background jobs that had already ex‐\nited. This is no longer the case.\n" }, { "name": "Prompting", "content": "PROMPTBANG \nIf set, `!' is treated specially in prompt expansion. See EXPANSION OF PROMPT SE‐\nQUENCES in zshmisc(1).\n\nPROMPTCR (+V) \nPrint a carriage return just before printing a prompt in the line editor. This is on\nby default as multi-line editing is only possible if the editor knows where the start\nof the line appears.\n\nPROMPTSP \nAttempt to preserve a partial line (i.e. a line that did not end with a newline) that\nwould otherwise be covered up by the command prompt due to the PROMPTCR option. This\nworks by outputting some cursor-control characters, including a series of spaces, that\nshould make the terminal wrap to the next line when a partial line is present (note\nthat this is only successful if your terminal has automatic margins, which is typi‐\ncal).\n\nWhen a partial line is preserved, by default you will see an inverse+bold character at\nthe end of the partial line: a `%' for a normal user or a `#' for root. If set, the\nshell parameter PROMPTEOLMARK can be used to customize how the end of partial lines\nare shown.\n\nNOTE: if the PROMPTCR option is not set, enabling this option will have no effect.\nThis option is on by default.\n\nPROMPTPERCENT \nIf set, `%' is treated specially in prompt expansion. See EXPANSION OF PROMPT SE‐\nQUENCES in zshmisc(1).\n\nPROMPTSUBST \nIf set, parameter expansion, command substitution and arithmetic expansion are per‐\nformed in prompts. Substitutions within prompts do not affect the command status.\n\nTRANSIENTRPROMPT\nRemove any right prompt from display when accepting a command line. This may be use‐\nful with terminals with other cut/paste methods.\n" }, { "name": "Scripts and Functions", "content": "ALIASFUNCDEF \nBy default, zsh does not allow the definition of functions using the `name ()' syntax\nif name was expanded as an alias: this causes an error. This is usually the desired\nbehaviour, as otherwise the combination of an alias and a function based on the same\ndefinition can easily cause problems.\n\nWhen this option is set, aliases can be used for defining functions.\n\nFor example, consider the following definitions as they might occur in a startup file.\n\nalias foo=bar\nfoo() {\nprint This probably does not do what you expect.\n}\n\nHere, foo is expanded as an alias to bar before the () is encountered, so the function\ndefined would be named bar. By default this is instead an error in native mode. Note\nthat quoting any part of the function name, or using the keyword function, avoids the\nproblem, so is recommended when the function name can also be an alias.\n\nCBASES\nOutput hexadecimal numbers in the standard C format, for example `0xFF' instead of the\nusual `16#FF'. If the option OCTALZEROES is also set (it is not by default), octal\nnumbers will be treated similarly and hence appear as `077' instead of `8#77'. This\noption has no effect on the choice of the output base, nor on the output of bases\nother than hexadecimal and octal. Note that these formats will be understood on input\nirrespective of the setting of CBASES.\n\nCPRECEDENCES\nThis alters the precedence of arithmetic operators to be more like C and other pro‐\ngramming languages; the section ARITHMETIC EVALUATION in zshmisc(1) has an explicit\nlist.\n\nDEBUGBEFORECMD \nRun the DEBUG trap before each command; otherwise it is run after each command. Set‐\nting this option mimics the behaviour of ksh 93; with the option unset the behaviour\nis that of ksh 88.\n\nERREXIT (-e, ksh: -e)\nIf a command has a non-zero exit status, execute the ZERR trap, if set, and exit.\nThis is disabled while running initialization scripts.\n\nThe behaviour is also disabled inside DEBUG traps. In this case the option is handled\nspecially: it is unset on entry to the trap. If the option DEBUGBEFORECMD is set,\nas it is by default, and the option ERREXIT is found to have been set on exit, then\nthe command for which the DEBUG trap is being executed is skipped. The option is re‐\nstored after the trap exits.\n\nNon-zero status in a command list containing && or || is ignored for commands not at\nthe end of the list. Hence\n\nfalse && true\n\ndoes not trigger exit.\n\nExiting due to ERREXIT has certain interactions with asynchronous jobs noted in the\nsection JOBS in zshmisc(1).\n\nERRRETURN\nIf a command has a non-zero exit status, return immediately from the enclosing func‐\ntion. The logic is similar to that for ERREXIT, except that an implicit return\nstatement is executed instead of an exit. This will trigger an exit at the outermost\nlevel of a non-interactive script.\n\nNormally this option inherits the behaviour of ERREXIT that code followed by `&&'\n`||' does not trigger a return. Hence in the following:\n\nsummit || true\n\nno return is forced as the combined effect always has a zero return status.\n\nNote. however, that if summit in the above example is itself a function, code inside\nit is considered separately: it may force a return from summit (assuming the option\nremains set within summit), but not from the enclosing context. This behaviour is\ndifferent from ERREXIT which is unaffected by function scope.\n\nEVALLINENO \nIf set, line numbers of expressions evaluated using the builtin eval are tracked sepa‐\nrately of the enclosing environment. This applies both to the parameter LINENO and\nthe line number output by the prompt escape %i. If the option is set, the prompt es‐\ncape %N will output the string `(eval)' instead of the script or function name as an\nindication. (The two prompt escapes are typically used in the parameter PS4 to be\noutput when the option XTRACE is set.) If EVALLINENO is unset, the line number of\nthe surrounding script or function is retained during the evaluation.\n\nEXEC (+n, ksh: +n) \nDo execute commands. Without this option, commands are read and checked for syntax\nerrors, but not executed. This option cannot be turned off in an interactive shell,\nexcept when `-n' is supplied to the shell at startup.\n\nFUNCTIONARGZERO \nWhen executing a shell function or sourcing a script, set $0 temporarily to the name\nof the function/script. Note that toggling FUNCTIONARGZERO from on to off (or off to\non) does not change the current value of $0. Only the state upon entry to the func‐\ntion or script has an effect. Compare POSIXARGZERO.\n\nLOCALLOOPS\nWhen this option is not set, the effect of break and continue commands may propagate\noutside function scope, affecting loops in calling functions. When the option is set\nin a calling function, a break or a continue that is not caught within a called func‐\ntion (regardless of the setting of the option within that function) produces a warning\nand the effect is cancelled.\n\nLOCALOPTIONS \nIf this option is set at the point of return from a shell function, most options (in‐\ncluding this one) which were in force upon entry to the function are restored; options\nthat are not restored are PRIVILEGED and RESTRICTED. Otherwise, only this option, and\nthe LOCALLOOPS, XTRACE and PRINTEXITVALUE options are restored. Hence if this is\nexplicitly unset by a shell function the other options in force at the point of return\nwill remain so. A shell function can also guarantee itself a known shell configura‐\ntion with a formulation like `emulate -L zsh'; the -L activates LOCALOPTIONS.\n\nLOCALPATTERNS\nIf this option is set at the point of return from a shell function, the state of pat‐\ntern disables, as set with the builtin command `disable -p', is restored to what it\nwas when the function was entered. The behaviour of this option is similar to the ef‐\nfect of LOCALOPTIONS on options; hence `emulate -L sh' (or indeed any other emulation\nwith the -L option) activates LOCALPATTERNS.\n\nLOCALTRAPS \nIf this option is set when a signal trap is set inside a function, then the previous\nstatus of the trap for that signal will be restored when the function exits. Note\nthat this option must be set prior to altering the trap behaviour in a function; un‐\nlike LOCALOPTIONS, the value on exit from the function is irrelevant. However, it\ndoes not need to be set before any global trap for that to be correctly restored by a\nfunction. For example,\n\nunsetopt localtraps\ntrap - INT\nfn() { setopt localtraps; trap '' INT; sleep 3; }\n\nwill restore normal handling of SIGINT after the function exits.\n\nMULTIFUNCDEF \nAllow definitions of multiple functions at once in the form `fn1 fn2...()'; if the op‐\ntion is not set, this causes a parse error. Definition of multiple functions with the\nfunction keyword is always allowed. Multiple function definitions are not often used\nand can cause obscure errors.\n\nMULTIOS \nPerform implicit tees or cats when multiple redirections are attempted (see the sec‐\ntion `Redirection').\n\nOCTALZEROES \nInterpret any integer constant beginning with a 0 as octal, per IEEE Std 1003.2-1992\n(ISO 9945-2:1993). This is not enabled by default as it causes problems with parsing\nof, for example, date and time strings with leading zeroes.\n\nSequences of digits indicating a numeric base such as the `08' component in `08#77'\nare always interpreted as decimal, regardless of leading zeroes.\n\nPIPEFAIL\nBy default, when a pipeline exits the exit status recorded by the shell and returned\nby the shell variable $? reflects that of the rightmost element of a pipeline. If\nthis option is set, the exit status instead reflects the status of the rightmost ele‐\nment of the pipeline that was non-zero, or zero if all elements exited with zero sta‐\ntus.\n\nSOURCETRACE\nIf set, zsh will print an informational message announcing the name of each file it\nloads. The format of the output is similar to that for the XTRACE option, with the\nmessage . A file may be loaded by the shell itself when it starts up and\nshuts down (Startup/Shutdown Files) or by the use of the `source' and `dot' builtin\ncommands.\n\nTYPESETSILENT\nIf this is unset, executing any of the `typeset' family of commands with no options\nand a list of parameters that have no values to be assigned but already exist will\ndisplay the value of the parameter. If the option is set, they will only be shown\nwhen parameters are selected with the `-m' option. The option `-p' is available\nwhether or not the option is set.\n\nVERBOSE (-v, ksh: -v)\nPrint shell input lines as they are read.\n\nXTRACE (-x, ksh: -x)\nPrint commands and their arguments as they are executed. The output is preceded by\nthe value of $PS4, formatted as described in the section EXPANSION OF PROMPT SEQUENCES\nin zshmisc(1).\n" }, { "name": "Shell Emulation", "content": "APPENDCREATE \nThis option only applies when NOCLOBBER (-C) is in effect.\n\nIf this option is not set, the shell will report an error when a append redirection\n(>>) is used on a file that does not already exists (the traditional zsh behaviour of\nNOCLOBBER). If the option is set, no error is reported (POSIX behaviour).\n\nBASHREMATCH\nWhen set, matches performed with the =~ operator will set the BASHREMATCH array vari‐\nable, instead of the default MATCH and match variables. The first element of the\nBASHREMATCH array will contain the entire matched text and subsequent elements will\ncontain extracted substrings. This option makes more sense when KSHARRAYS is also\nset, so that the entire matched portion is stored at index 0 and the first substring\nis at index 1. Without this option, the MATCH variable contains the entire matched\ntext and the match array variable contains substrings.\n\nBSDECHO \nMake the echo builtin compatible with the BSD echo(1) command. This disables back‐\nslashed escape sequences in echo strings unless the -e option is specified.\n\nCONTINUEONERROR\nIf a fatal error is encountered (see the section ERRORS in zshmisc(1)), and the code\nis running in a script, the shell will resume execution at the next statement in the\nscript at the top level, in other words outside all functions or shell constructs such\nas loops and conditions. This mimics the behaviour of interactive shells, where the\nshell returns to the line editor to read a new command; it was the normal behaviour in\nversions of zsh before 5.0.1.\n\nCSHJUNKIEHISTORY \nA history reference without an event specifier will always refer to the previous com‐\nmand. Without this option, such a history reference refers to the same event as the\nprevious history reference on the current command line, defaulting to the previous\ncommand.\n\nCSHJUNKIELOOPS \nAllow loop bodies to take the form `list; end' instead of `do list; done'.\n\nCSHJUNKIEQUOTES \nChanges the rules for single- and double-quoted text to match that of csh. These re‐\nquire that embedded newlines be preceded by a backslash; unescaped newlines will cause\nan error message. In double-quoted strings, it is made impossible to escape `$', ``'\nor `\"' (and `\\' itself no longer needs escaping). Command substitutions are only ex‐\npanded once, and cannot be nested.\n\nCSHNULLCMD \nDo not use the values of NULLCMD and READNULLCMD when running redirections with no\ncommand. This make such redirections fail (see the section `Redirection').\n\nKSHARRAYS \nEmulate ksh array handling as closely as possible. If this option is set, array ele‐\nments are numbered from zero, an array parameter without subscript refers to the first\nelement instead of the whole array, and braces are required to delimit a subscript\n(`${path[2]}' rather than just `$path[2]') or to apply modifiers to any parameter\n(`${PWD:h}' rather than `$PWD:h').\n\nKSHAUTOLOAD \nEmulate ksh function autoloading. This means that when a function is autoloaded, the\ncorresponding file is merely executed, and must define the function itself. (By de‐\nfault, the function is defined to the contents of the file. However, the most common\nksh-style case - of the file containing only a simple definition of the function - is\nalways handled in the ksh-compatible manner.)\n\nKSHOPTIONPRINT \nAlters the way options settings are printed: instead of separate lists of set and un‐\nset options, all options are shown, marked `on' if they are in the non-default state,\n`off' otherwise.\n\nKSHTYPESET\nThis option is now obsolete: a better appropximation to the behaviour of other shells\nis obtained with the reserved word interface to declare, export, float, integer, lo‐‐\ncal, readonly and typeset. Note that the option is only applied when the reserved\nword interface is not in use.\n\nAlters the way arguments to the typeset family of commands, including declare, export,\nfloat, integer, local and readonly, are processed. Without this option, zsh will per‐\nform normal word splitting after command and parameter expansion in arguments of an\nassignment; with it, word splitting does not take place in those cases.\n\nKSHZEROSUBSCRIPT\nTreat use of a subscript of value zero in array or string expressions as a reference\nto the first element, i.e. the element that usually has the subscript 1. Ignored if\nKSHARRAYS is also set.\n\nIf neither this option nor KSHARRAYS is set, accesses to an element of an array or\nstring with subscript zero return an empty element or string, while attempts to set\nelement zero of an array or string are treated as an error. However, attempts to set\nan otherwise valid subscript range that includes zero will succeed. For example, if\nKSHZEROSUBSCRIPT is not set,\n\narray[0]=(element)\n\nis an error, while\n\narray[0,1]=(element)\n\nis not and will replace the first element of the array.\n\nThis option is for compatibility with older versions of the shell and is not recom‐\nmended in new code.\n\nPOSIXALIASES \nWhen this option is set, reserved words are not candidates for alias expansion: it is\nstill possible to declare any of them as an alias, but the alias will never be ex‐\npanded. Reserved words are described in the section RESERVED WORDS in zshmisc(1).\n\nAlias expansion takes place while text is being read; hence when this option is set it\ndoes not take effect until the end of any function or other piece of shell code parsed\nas one unit. Note this may cause differences from other shells even when the option\nis in effect. For example, when running a command with `zsh -c', or even `zsh -o\nposixaliases -c', the entire command argument is parsed as one unit, so aliases de‐\nfined within the argument are not available even in later lines. If in doubt, avoid\nuse of aliases in non-interactive code.\n\nPOSIXARGZERO\nThis option may be used to temporarily disable FUNCTIONARGZERO and thereby restore\nthe value of $0 to the name used to invoke the shell (or as set by the -c command line\noption). For compatibility with previous versions of the shell, emulations use\nNOFUNCTIONARGZERO instead of POSIXARGZERO, which may result in unexpected scoping\nof $0 if the emulation mode is changed inside a function or script. To avoid this,\nexplicitly enable POSIXARGZERO in the emulate command:\n\nemulate sh -o POSIXARGZERO\n\nNote that NOPOSIXARGZERO has no effect unless FUNCTIONARGZERO was already enabled\nupon entry to the function or script.\n\nPOSIXBUILTINS \nWhen this option is set the command builtin can be used to execute shell builtin com‐\nmands. Parameter assignments specified before shell functions and special builtins\nare kept after the command completes unless the special builtin is prefixed with the\ncommand builtin. Special builtins are ., :, break, continue, declare, eval, exit, ex‐‐\nport, integer, local, readonly, return, set, shift, source, times, trap and unset.\n\nIn addition, various error conditions associated with the above builtins or exec cause\na non-interactive shell to exit and an interactive shell to return to its top-level\nprocessing.\n\nFurthermore, functions and shell builtins are not executed after an exec prefix; the\ncommand to be executed must be an external command found in the path.\n\nFurthermore, the getopts builtin behaves in a POSIX-compatible fashion in that the as‐\nsociated variable OPTIND is not made local to functions.\n\nMoreover, the warning and special exit code from [[ -o nonexistentoption ]] are sup‐\npressed.\n\nPOSIXIDENTIFIERS \nWhen this option is set, only the ASCII characters a to z, A to Z, 0 to 9 and may be\nused in identifiers (names of shell parameters and modules).\n\nIn addition, setting this option limits the effect of parameter substitution with no\nbraces, so that the expression $# is treated as the parameter $# even if followed by a\nvalid parameter name. When it is unset, zsh allows expressions of the form $#name to\nrefer to the length of $name, even for special variables, for example in expressions\nsuch as $#- and $#*.\n\nAnother difference is that with the option set assignment to an unset variable in\narithmetic context causes the variable to be created as a scalar rather than a numeric\ntype. So after `unset t; (( t = 3 ))'. without POSIXIDENTIFIERS set t has integer\ntype, while with it set it has scalar type.\n\nWhen the option is unset and multibyte character support is enabled (i.e. it is com‐\npiled in and the option MULTIBYTE is set), then additionally any alphanumeric charac‐\nters in the local character set may be used in identifiers. Note that scripts and\nfunctions written with this feature are not portable, and also that both options must\nbe set before the script or function is parsed; setting them during execution is not\nsufficient as the syntax variable=value has already been parsed as a command rather\nthan an assignment.\n\nIf multibyte character support is not compiled into the shell this option is ignored;\nall octets with the top bit set may be used in identifiers. This is non-standard but\nis the traditional zsh behaviour.\n\nPOSIXSTRINGS \nThis option affects processing of quoted strings. Currently it only affects the be‐\nhaviour of null characters, i.e. character 0 in the portable character set correspond‐\ning to US ASCII.\n\nWhen this option is not set, null characters embedded within strings of the form\n$'...' are treated as ordinary characters. The entire string is maintained within the\nshell and output to files where necessary, although owing to restrictions of the li‐\nbrary interface the string is truncated at the null character in file names, environ‐\nment variables, or in arguments to external programs.\n\nWhen this option is set, the $'...' expression is truncated at the null character.\nNote that remaining parts of the same string beyond the termination of the quotes are\nnot truncated.\n\nFor example, the command line argument a$'b\\0c'd is treated with the option off as the\ncharacters a, b, null, c, d, and with the option on as the characters a, b, d.\n\nPOSIXTRAPS \nWhen this option is set, the usual zsh behaviour of executing traps for EXIT on exit\nfrom shell functions is suppressed. In that case, manipulating EXIT traps always al‐\nters the global trap for exiting the shell; the LOCALTRAPS option is ignored for the\nEXIT trap. Furthermore, a return statement executed in a trap with no argument passes\nback from the function the value from the surrounding context, not from code executed\nwithin the trap.\n\nSHFILEEXPANSION \nPerform filename expansion (e.g., ~ expansion) before parameter expansion, command\nsubstitution, arithmetic expansion and brace expansion. If this option is unset, it\nis performed after brace expansion, so things like `~$USERNAME' and `~{pfalstad,rc}'\nwill work.\n\nSHNULLCMD \nDo not use the values of NULLCMD and READNULLCMD when doing redirections, use `:' in‐\nstead (see the section `Redirection').\n\nSHOPTIONLETTERS \nIf this option is set the shell tries to interpret single letter options (which are\nused with set and setopt) like ksh does. This also affects the value of the - special\nparameter.\n\nSHWORDSPLIT (-y) \nCauses field splitting to be performed on unquoted parameter expansions. Note that\nthis option has nothing to do with word splitting. (See zshexpn(1).)\n\nTRAPSASYNC\nWhile waiting for a program to exit, handle signals and run traps immediately. Other‐\nwise the trap is run after a child process has exited. Note this does not affect the\npoint at which traps are run for any case other than when the shell is waiting for a\nchild process.\n" }, { "name": "Shell State", "content": "INTERACTIVE (-i, ksh: -i)\nThis is an interactive shell. This option is set upon initialisation if the standard\ninput is a tty and commands are being read from standard input. (See the discussion\nof SHINSTDIN.) This heuristic may be overridden by specifying a state for this op‐\ntion on the command line. The value of this option can only be changed via flags sup‐\nplied at invocation of the shell. It cannot be changed once zsh is running.\n\nLOGIN (-l, ksh: -l)\nThis is a login shell. If this option is not explicitly set, the shell becomes a lo‐\ngin shell if the first character of the argv[0] passed to the shell is a `-'.\n\nPRIVILEGED (-p, ksh: -p)\nTurn on privileged mode. Typically this is used when script is to be run with elevated\nprivileges. This should be done as follows directly with the -p option to zsh so that\nit takes effect during startup.\n\n#!/bin/zsh -p\n\nThe option is enabled automatically on startup if the effective user (group) ID is not\nequal to the real user (group) ID. In this case, turning the option off causes the ef‐\nfective user and group IDs to be set to the real user and group IDs. Be aware that if\nthat fails the shell may be running with different IDs than was intended so a script\nshould check for failure and act accordingly, for example:\n\nunsetopt privileged || exit\n\nThe PRIVILEGED option disables sourcing user startup files. If zsh is invoked as `sh'\nor `ksh' with this option set, /etc/suidprofile is sourced (after /etc/profile on in‐\nteractive shells). Sourcing ~/.profile is disabled and the contents of the ENV vari‐\nable is ignored. This option cannot be changed using the -m option of setopt and unse‐‐\ntopt, and changing it inside a function always changes it globally regardless of the\nLOCALOPTIONS option.\n\nRESTRICTED (-r)\nEnables restricted mode. This option cannot be changed using unsetopt, and setting it\ninside a function always changes it globally regardless of the LOCALOPTIONS option.\nSee the section `Restricted Shell'.\n\nSHINSTDIN (-s, ksh: -s)\nCommands are being read from the standard input. Commands are read from standard in‐\nput if no command is specified with -c and no file of commands is specified. If\nSHINSTDIN is set explicitly on the command line, any argument that would otherwise\nhave been taken as a file to run will instead be treated as a normal positional param‐\neter. Note that setting or unsetting this option on the command line does not neces‐\nsarily affect the state the option will have while the shell is running - that is\npurely an indicator of whether or not commands are actually being read from standard\ninput. The value of this option can only be changed via flags supplied at invocation\nof the shell. It cannot be changed once zsh is running.\n\nSINGLECOMMAND (-t, ksh: -t)\nIf the shell is reading from standard input, it exits after a single command has been\nexecuted. This also makes the shell non-interactive, unless the INTERACTIVE option is\nexplicitly set on the command line. The value of this option can only be changed via\nflags supplied at invocation of the shell. It cannot be changed once zsh is running.\n" }, { "name": "Zle", "content": "BEEP (+B) \nBeep on error in ZLE.\n\nCOMBININGCHARS\nAssume that the terminal displays combining characters correctly. Specifically, if a\nbase alphanumeric character is followed by one or more zero-width punctuation charac‐\nters, assume that the zero-width characters will be displayed as modifications to the\nbase character within the same width. Not all terminals handle this. If this option\nis not set, zero-width characters are displayed separately with special mark-up.\n\nIf this option is set, the pattern test [[:WORD:]] matches a zero-width punctuation\ncharacter on the assumption that it will be used as part of a word in combination with\na word character. Otherwise the base shell does not handle combining characters spe‐\ncially.\n\nEMACS If ZLE is loaded, turning on this option has the equivalent effect of `bindkey -e'.\nIn addition, the VI option is unset. Turning it off has no effect. The option set‐\nting is not guaranteed to reflect the current keymap. This option is provided for\ncompatibility; bindkey is the recommended interface.\n\nOVERSTRIKE\nStart up the line editor in overstrike mode.\n\nSINGLELINEZLE (-M) \nUse single-line command line editing instead of multi-line.\n\nNote that although this is on by default in ksh emulation it only provides superficial\ncompatibility with the ksh line editor and reduces the effectiveness of the zsh line\neditor. As it has no effect on shell syntax, many users may wish to disable this op‐\ntion when using ksh emulation interactively.\n\nVI If ZLE is loaded, turning on this option has the equivalent effect of `bindkey -v'.\nIn addition, the EMACS option is unset. Turning it off has no effect. The option\nsetting is not guaranteed to reflect the current keymap. This option is provided for\ncompatibility; bindkey is the recommended interface.\n\nZLE (-Z)\nUse the zsh line editor. Set by default in interactive shells connected to a termi‐\nnal.\n" } ] }, "OPTION ALIASES": { "content": "Some options have alternative names. These aliases are never used for output, but can be\nused just like normal option names when specifying options to the shell.\n\nBRACEEXPAND\nNOIGNOREBRACES (ksh and bash compatibility)\n\nDOTGLOB\nGLOBDOTS (bash compatibility)\n\nHASHALL\nHASHCMDS (bash compatibility)\n\nHISTAPPEND\nAPPENDHISTORY (bash compatibility)\n\nHISTEXPAND\nBANGHIST (bash compatibility)\n\nLOG NOHISTNOFUNCTIONS (ksh compatibility)\n\nMAILWARN\nMAILWARNING (bash compatibility)\n\nONECMD\nSINGLECOMMAND (bash compatibility)\n\nPHYSICAL\nCHASELINKS (ksh and bash compatibility)\n\nPROMPTVARS\nPROMPTSUBST (bash compatibility)\n\nSTDIN SHINSTDIN (ksh compatibility)\n\nTRACKALL\nHASHCMDS (ksh compatibility)\n", "subsections": [] }, "SINGLE LETTER OPTIONS": { "content": "", "subsections": [ { "name": "Default set", "content": "" }, { "name": "-0", "content": "", "flag": "-0" }, { "name": "-1", "content": "", "flag": "-1" }, { "name": "-2", "content": "", "flag": "-2" }, { "name": "-3", "content": "", "flag": "-3" }, { "name": "-4", "content": "", "flag": "-4" }, { "name": "-5", "content": "", "flag": "-5" }, { "name": "-6", "content": "", "flag": "-6" }, { "name": "-7", "content": "", "flag": "-7" }, { "name": "-8", "content": "", "flag": "-8" }, { "name": "-9", "content": "", "flag": "-9" }, { "name": "-B", "content": "", "flag": "-B" }, { "name": "-C", "content": "", "flag": "-C" }, { "name": "-D", "content": "", "flag": "-D" }, { "name": "-E", "content": "", "flag": "-E" }, { "name": "-F", "content": "", "flag": "-F" }, { "name": "-G", "content": "", "flag": "-G" }, { "name": "-H", "content": "", "flag": "-H" }, { "name": "-I", "content": "", "flag": "-I" }, { "name": "-J", "content": "", "flag": "-J" }, { "name": "-K", "content": "", "flag": "-K" }, { "name": "-L", "content": "", "flag": "-L" }, { "name": "-M", "content": "", "flag": "-M" }, { "name": "-N", "content": "", "flag": "-N" }, { "name": "-O", "content": "", "flag": "-O" }, { "name": "-P", "content": "", "flag": "-P" }, { "name": "-Q", "content": "", "flag": "-Q" }, { "name": "-R", "content": "", "flag": "-R" }, { "name": "-S", "content": "", "flag": "-S" }, { "name": "-T", "content": "", "flag": "-T" }, { "name": "-U", "content": "", "flag": "-U" }, { "name": "-V", "content": "", "flag": "-V" }, { "name": "-W", "content": "", "flag": "-W" }, { "name": "-X", "content": "", "flag": "-X" }, { "name": "-Y", "content": "", "flag": "-Y" }, { "name": "-Z", "content": "", "flag": "-Z" }, { "name": "-a", "content": "", "flag": "-a" }, { "name": "-e", "content": "", "flag": "-e" }, { "name": "-f", "content": "", "flag": "-f" }, { "name": "-g", "content": "", "flag": "-g" }, { "name": "-h", "content": "", "flag": "-h" }, { "name": "-i", "content": "", "flag": "-i" }, { "name": "-k", "content": "", "flag": "-k" }, { "name": "-l", "content": "", "flag": "-l" }, { "name": "-m", "content": "", "flag": "-m" }, { "name": "-n", "content": "", "flag": "-n" }, { "name": "-p", "content": "", "flag": "-p" }, { "name": "-r", "content": "", "flag": "-r" }, { "name": "-s", "content": "", "flag": "-s" }, { "name": "-t", "content": "", "flag": "-t" }, { "name": "-u", "content": "", "flag": "-u" }, { "name": "-v", "content": "", "flag": "-v" }, { "name": "-w", "content": "", "flag": "-w" }, { "name": "-x", "content": "", "flag": "-x" }, { "name": "-y", "content": "", "flag": "-y" }, { "name": "sh/ksh emulation set", "content": "" }, { "name": "-C", "content": "", "flag": "-C" }, { "name": "-T", "content": "", "flag": "-T" }, { "name": "-X", "content": "", "flag": "-X" }, { "name": "-a", "content": "", "flag": "-a" }, { "name": "-b", "content": "", "flag": "-b" }, { "name": "-e", "content": "", "flag": "-e" }, { "name": "-f", "content": "", "flag": "-f" }, { "name": "-i", "content": "", "flag": "-i" }, { "name": "-l", "content": "", "flag": "-l" }, { "name": "-m", "content": "", "flag": "-m" }, { "name": "-n", "content": "", "flag": "-n" }, { "name": "-p", "content": "", "flag": "-p" }, { "name": "-r", "content": "", "flag": "-r" }, { "name": "-s", "content": "", "flag": "-s" }, { "name": "-t", "content": "", "flag": "-t" }, { "name": "-u", "content": "", "flag": "-u" }, { "name": "-v", "content": "", "flag": "-v" }, { "name": "-x", "content": "", "flag": "-x" }, { "name": "Also note", "content": "" }, { "name": "-A", "content": "", "flag": "-A" }, { "name": "-b", "content": "", "flag": "-b" }, { "name": "-c", "content": "", "flag": "-c" }, { "name": "-m", "content": "", "flag": "-m" }, { "name": "-o", "content": "", "flag": "-o" }, { "name": "-s", "content": "ZSHBUILTINS(1) General Commands Manual ZSHBUILTINS(1)\n\n\n", "flag": "-s" } ] }, "SHELL BUILTIN COMMANDS": { "content": "Some shell builtin commands take options as described in individual entries; these are often\nreferred to in the list below as `flags' to avoid confusion with shell options, which may\nalso have an effect on the behaviour of builtin commands. In this introductory section, `op‐‐\ntion' always has the meaning of an option to a command that should be familiar to most com‐\nmand line users.\n\nTypically, options are single letters preceded by a hyphen (-). Options that take an argu‐\nment accept it either immediately following the option letter or after white space, for exam‐\nple `print -C3 {1..9}' or `print -C 3 {1..9}' are equivalent. Arguments to options are not\nthe same as arguments to the command; the documentation indicates which is which. Options\nthat do not take an argument may be combined in a single word, for example `print -rca -- *'\nand `print -r -c -a -- *' are equivalent.\n\nSome shell builtin commands also take options that begin with `+' instead of `-'. The list\nbelow makes clear which commands these are.\n\nOptions (together with their individual arguments, if any) must appear in a group before any\nnon-option arguments; once the first non-option argument has been found, option processing is\nterminated.\n\nAll builtin commands other than `echo' and precommand modifiers, even those that have no op‐\ntions, can be given the argument `--' to terminate option processing. This indicates that\nthe following words are non-option arguments, but is otherwise ignored. This is useful in\ncases where arguments to the command may begin with `-'. For historical reasons, most\nbuiltin commands (including `echo') also recognize a single `-' in a separate word for this\npurpose; note that this is less standard and use of `--' is recommended.\n\n- simple command\nSee the section `Precommand Modifiers' in zshmisc(1).\n\n. file [ arg ... ]\nRead commands from file and execute them in the current shell environment.\n\nIf file does not contain a slash, or if PATHDIRS is set, the shell looks in the com‐\nponents of $path to find the directory containing file. Files in the current direc‐\ntory are not read unless `.' appears somewhere in $path. If a file named `file.zwc'\nis found, is newer than file, and is the compiled form (created with the zcompile\nbuiltin) of file, then commands are read from that file instead of file.\n\nIf any arguments arg are given, they become the positional parameters; the old posi‐\ntional parameters are restored when the file is done executing. However, if no argu‐\nments are given, the positional parameters remain those of the calling context, and no\nrestoring is done.\n\nIf file was not found the return status is 127; if file was found but contained a syn‐\ntax error the return status is 126; else the return status is the exit status of the\nlast command executed.\n\n: [ arg ... ]\nThis command does nothing, although normal argument expansions is performed which may\nhave effects on shell parameters. A zero exit status is returned.\n\nalias [ {+|-}gmrsL ] [ name[=value] ... ]\nFor each name with a corresponding value, define an alias with that value. A trailing\nspace in value causes the next word to be checked for alias expansion. If the -g flag\nis present, define a global alias; global aliases are expanded even if they do not oc‐\ncur in command position.\n\nIf the -s flag is present, define a suffix alias: if the command word on a command\nline is in the form `text.name', where text is any non-empty string, it is replaced by\nthe text `value text.name'. Note that name is treated as a literal string, not a pat‐\ntern. A trailing space in value is not special in this case. For example,\n\nalias -s ps='gv --'\n\nwill cause the command `*.ps' to be expanded to `gv -- *.ps'. As alias expansion is\ncarried out earlier than globbing, the `*.ps' will then be expanded. Suffix aliases\nconstitute a different name space from other aliases (so in the above example it is\nstill possible to create an alias for the command ps) and the two sets are never\nlisted together.\n\nFor each name with no value, print the value of name, if any. With no arguments,\nprint all currently defined aliases other than suffix aliases. If the -m flag is\ngiven the arguments are taken as patterns (they should be quoted to preserve them from\nbeing interpreted as glob patterns), and the aliases matching these patterns are\nprinted. When printing aliases and one of the -g, -r or -s flags is present, restrict\nthe printing to global, regular or suffix aliases, respectively; a regular alias is\none which is neither a global nor a suffix alias. Using `+' instead of `-', or end‐\ning the option list with a single `+', prevents the values of the aliases from being\nprinted.\n\nIf the -L flag is present, then print each alias in a manner suitable for putting in a\nstartup script. The exit status is nonzero if a name (with no value) is given for\nwhich no alias has been defined.\n\nFor more on aliases, include common problems, see the section ALIASING in zshmisc(1).\n\nautoload [ {+|-}RTUXdkmrtWz ] [ -w ] [ name ... ]\nSee the section `Autoloading Functions' in zshmisc(1) for full details. The fpath pa‐\nrameter will be searched to find the function definition when the function is first\nreferenced.\n\nIf name consists of an absolute path, the function is defined to load from the file\ngiven (searching as usual for dump files in the given location). The name of the\nfunction is the basename (non-directory part) of the file. It is normally an error if\nthe function is not found in the given location; however, if the option -d is given,\nsearching for the function defaults to $fpath. If a function is loaded by absolute\npath, any functions loaded from it that are marked for autoload without an absolute\npath have the load path of the parent function temporarily prepended to $fpath.\n\nIf the option -r or -R is given, the function is searched for immediately and the lo‐\ncation is recorded internally for use when the function is executed; a relative path\nis expanded using the value of $PWD. This protects against a change to $fpath after\nthe call to autoload. With -r, if the function is not found, it is silently left un‐\nresolved until execution; with -R, an error message is printed and command processing\naborted immediately the search fails, i.e. at the autoload command rather than at\nfunction execution..\n\nThe flag -X may be used only inside a shell function. It causes the calling function\nto be marked for autoloading and then immediately loaded and executed, with the cur‐\nrent array of positional parameters as arguments. This replaces the previous defini‐\ntion of the function. If no function definition is found, an error is printed and the\nfunction remains undefined and marked for autoloading. If an argument is given, it is\nused as a directory (i.e. it does not include the name of the function) in which the\nfunction is to be found; this may be combined with the -d option to allow the function\nsearch to default to $fpath if it is not in the given location.\n\nThe flag +X attempts to load each name as an autoloaded function, but does not execute\nit. The exit status is zero (success) if the function was not previously defined and\na definition for it was found. This does not replace any existing definition of the\nfunction. The exit status is nonzero (failure) if the function was already defined or\nwhen no definition was found. In the latter case the function remains undefined and\nmarked for autoloading. If ksh-style autoloading is enabled, the function created\nwill contain the contents of the file plus a call to the function itself appended to\nit, thus giving normal ksh autoloading behaviour on the first call to the function.\nIf the -m flag is also given each name is treated as a pattern and all functions al‐\nready marked for autoload that match the pattern are loaded.\n\nWith the -t flag, turn on execution tracing; with -T, turn on execution tracing only\nfor the current function, turning it off on entry to any called functions that do not\nalso have tracing enabled.\n\nWith the -U flag, alias expansion is suppressed when the function is loaded.\n\nWith the -w flag, the names are taken as names of files compiled with the zcompile\nbuiltin, and all functions defined in them are marked for autoloading.\n\nThe flags -z and -k mark the function to be autoloaded using the zsh or ksh style, as\nif the option KSHAUTOLOAD were unset or were set, respectively. The flags override\nthe setting of the option at the time the function is loaded.\n\nNote that the autoload command makes no attempt to ensure the shell options set during\nthe loading or execution of the file have any particular value. For this, the emulate\ncommand can be used:\n\nemulate zsh -c 'autoload -Uz func'\n\narranges that when func is loaded the shell is in native zsh emulation, and this emu‐\nlation is also applied when func is run.\n\nSome of the functions of autoload are also provided by functions -u or functions -U,\nbut autoload is a more comprehensive interface.\n\nbg [ job ... ]\njob ... &\nPut each specified job in the background, or the current job if none is specified.\n", "subsections": [ { "name": "bindkey", "content": "See the section `Zle Builtins' in zshzle(1).\n\nbreak [ n ]\nExit from an enclosing for, while, until, select or repeat loop. If an arithmetic ex‐\npression n is specified, then break n levels instead of just one.\n\nbuiltin name [ args ... ]\nExecutes the builtin name, with the given args.\n\nbye Same as exit.\n\ncap See the section `The zsh/cap Module' in zshmodules(1).\n\ncd [ -qsLP ] [ arg ]\ncd [ -qsLP ] old new\ncd [ -qsLP ] {+|-}n\nChange the current directory. In the first form, change the current directory to arg,\nor to the value of $HOME if arg is not specified. If arg is `-', change to the previ‐\nous directory.\n\nOtherwise, if arg begins with a slash, attempt to change to the directory given by\narg.\n\nIf arg does not begin with a slash, the behaviour depends on whether the current di‐\nrectory `.' occurs in the list of directories contained in the shell parameter cdpath.\nIf it does not, first attempt to change to the directory arg under the current direc‐\ntory, and if that fails but cdpath is set and contains at least one element attempt to\nchange to the directory arg under each component of cdpath in turn until successful.\nIf `.' occurs in cdpath, then cdpath is searched strictly in order so that `.' is only\ntried at the appropriate point.\n\nThe order of testing cdpath is modified if the option POSIXCD is set, as described in\nthe documentation for the option.\n\nIf no directory is found, the option CDABLEVARS is set, and a parameter named arg ex‐\nists whose value begins with a slash, treat its value as the directory. In that case,\nthe parameter is added to the named directory hash table.\n\nThe second form of cd substitutes the string new for the string old in the name of the\ncurrent directory, and tries to change to this new directory.\n\nThe third form of cd extracts an entry from the directory stack, and changes to that\ndirectory. An argument of the form `+n' identifies a stack entry by counting from the\nleft of the list shown by the dirs command, starting with zero. An argument of the\nform `-n' counts from the right. If the PUSHDMINUS option is set, the meanings of\n`+' and `-' in this context are swapped. If the POSIXCD option is set, this form of\ncd is not recognised and will be interpreted as the first form.\n\nIf the -q (quiet) option is specified, the hook function chpwd and the functions in\nthe array chpwdfunctions are not called. This is useful for calls to cd that do not\nchange the environment seen by an interactive user.\n\nIf the -s option is specified, cd refuses to change the current directory if the given\npathname contains symlinks. If the -P option is given or the CHASELINKS option is\nset, symbolic links are resolved to their true values. If the -L option is given sym‐\nbolic links are retained in the directory (and not resolved) regardless of the state\nof the CHASELINKS option.\n\nchdir Same as cd.\n\nclone See the section `The zsh/clone Module' in zshmodules(1).\n\ncommand [ -pvV ] simple command\nThe simple command argument is taken as an external command instead of a function or\nbuiltin and is executed. If the POSIXBUILTINS option is set, builtins will also be\nexecuted but certain special properties of them are suppressed. The -p flag causes a\ndefault path to be searched instead of that in $path. With the -v flag, command is\nsimilar to whence and with -V, it is equivalent to whence -v.\n\nSee also the section `Precommand Modifiers' in zshmisc(1).\n" }, { "name": "comparguments", "content": "See the section `The zsh/computil Module' in zshmodules(1).\n" }, { "name": "compcall", "content": "See the section `The zsh/compctl Module' in zshmodules(1).\n" }, { "name": "compctl", "content": "See the section `The zsh/compctl Module' in zshmodules(1).\n" }, { "name": "compdescribe", "content": "See the section `The zsh/computil Module' in zshmodules(1).\n" }, { "name": "compfiles", "content": "See the section `The zsh/computil Module' in zshmodules(1).\n" }, { "name": "compgroups", "content": "See the section `The zsh/computil Module' in zshmodules(1).\n" }, { "name": "compquote", "content": "See the section `The zsh/computil Module' in zshmodules(1).\n" }, { "name": "comptags", "content": "See the section `The zsh/computil Module' in zshmodules(1).\n" }, { "name": "comptry", "content": "See the section `The zsh/computil Module' in zshmodules(1).\n" }, { "name": "compvalues", "content": "See the section `The zsh/computil Module' in zshmodules(1).\n\ncontinue [ n ]\nResume the next iteration of the enclosing for, while, until, select or repeat loop.\nIf an arithmetic expression n is specified, break out of n-1 loops and resume at the\nnth enclosing loop.\n" }, { "name": "declare", "content": "Same as typeset.\n\ndirs [ -c ] [ arg ... ]\ndirs [ -lpv ]\nWith no arguments, print the contents of the directory stack. Directories are added\nto this stack with the pushd command, and removed with the cd or popd commands. If\narguments are specified, load them onto the directory stack, replacing anything that\nwas there, and push the current directory onto the stack.\n\n-c clear the directory stack.\n\n-l print directory names in full instead of using of using ~ expressions (see Dy‐\nnamic and Static named directories in zshexpn(1)).\n\n-p print directory entries one per line.\n\n-v number the directories in the stack when printing.\n\ndisable [ -afmprs ] name ...\nTemporarily disable the named hash table elements or patterns. The default is to dis‐\nable builtin commands. This allows you to use an external command with the same name\nas a builtin command. The -a option causes disable to act on regular or global\naliases. The -s option causes disable to act on suffix aliases. The -f option causes\ndisable to act on shell functions. The -r options causes disable to act on reserved\nwords. Without arguments all disabled hash table elements from the corresponding hash\ntable are printed. With the -m flag the arguments are taken as patterns (which should\nbe quoted to prevent them from undergoing filename expansion), and all hash table ele‐\nments from the corresponding hash table matching these patterns are disabled. Dis‐\nabled objects can be enabled with the enable command.\n\nWith the option -p, name ... refer to elements of the shell's pattern syntax as de‐\nscribed in the section `Filename Generation'. Certain elements can be disabled sepa‐\nrately, as given below.\n\nNote that patterns not allowed by the current settings for the options EXTENDEDGLOB,\nKSHGLOB and SHGLOB are never enabled, regardless of the setting here. For example,\nif EXTENDEDGLOB is not active, the pattern ^ is ineffective even if `disable -p \"^\"'\nhas not been issued. The list below indicates any option settings that restrict the\nuse of the pattern. It should be noted that setting SHGLOB has a wider effect than\nmerely disabling patterns as certain expressions, in particular those involving paren‐\ntheses, are parsed differently.\n\nThe following patterns may be disabled; all the strings need quoting on the command\nline to prevent them from being interpreted immediately as patterns and the patterns\nare shown below in single quotes as a reminder.\n\n'?' The pattern character ? wherever it occurs, including when preceding a paren‐\nthesis with KSHGLOB.\n\n'*' The pattern character * wherever it occurs, including recursive globbing and\nwhen preceding a parenthesis with KSHGLOB.\n\n'[' Character classes.\n\n'<' (NOSHGLOB)\nNumeric ranges.\n\n'|' (NOSHGLOB)\nAlternation in grouped patterns, case statements, or KSHGLOB parenthesised ex‐\npressions.\n\n'(' (NOSHGLOB)\nGrouping using single parentheses. Disabling this does not disable the use of\nparentheses for KSHGLOB where they are introduced by a special character, nor\nfor glob qualifiers (use `setopt NOBAREGLOBQUAL' to disable glob qualifiers\nthat use parentheses only).\n\n'~' (EXTENDEDGLOB)\nExclusion in the form A~B.\n\n'^' (EXTENDEDGLOB)\nExclusion in the form A^B.\n\n'#' (EXTENDEDGLOB)\nThe pattern character # wherever it occurs, both for repetition of a previous\npattern and for indicating globbing flags.\n\n'?(' (KSHGLOB)\nThe grouping form ?(...). Note this is also disabled if '?' is disabled.\n\n'*(' (KSHGLOB)\nThe grouping form *(...). Note this is also disabled if '*' is disabled.\n\n'+(' (KSHGLOB)\nThe grouping form +(...).\n\n'!(' (KSHGLOB)\nThe grouping form !(...).\n\n'@(' (KSHGLOB)\nThe grouping form @(...).\n\ndisown [ job ... ]\njob ... &|\njob ... &!\nRemove the specified jobs from the job table; the shell will no longer report their\nstatus, and will not complain if you try to exit an interactive shell with them run‐\nning or stopped. If no job is specified, disown the current job.\n\nIf the jobs are currently stopped and the AUTOCONTINUE option is not set, a warning\nis printed containing information about how to make them running after they have been\ndisowned. If one of the latter two forms is used, the jobs will automatically be made\nrunning, independent of the setting of the AUTOCONTINUE option.\n\necho [ -neE ] [ arg ... ]\nWrite each arg on the standard output, with a space separating each one. If the -n\nflag is not present, print a newline at the end. echo recognizes the following escape\nsequences:\n\n\\a bell character\n\\b backspace\n\\c suppress subsequent characters and final newline\n\\e escape\n\\f form feed\n\\n linefeed (newline)\n\\r carriage return\n\\t horizontal tab\n\\v vertical tab\n\\\\ backslash\n\\0NNN character code in octal\n\\xNN character code in hexadecimal\n\\uNNNN unicode character code in hexadecimal\n\\UNNNNNNNN\nunicode character code in hexadecimal\n\nThe -E flag, or the BSDECHO option, can be used to disable these escape sequences.\nIn the latter case, -e flag can be used to enable them.\n\nNote that for standards compliance a double dash does not terminate option processing;\ninstead, it is printed directly. However, a single dash does terminate option pro‐\ncessing, so the first dash, possibly following options, is not printed, but everything\nfollowing it is printed as an argument. The single dash behaviour is different from\nother shells. For a more portable way of printing text, see printf, and for a more\ncontrollable way of printing text within zsh, see print.\n\nechotc See the section `The zsh/termcap Module' in zshmodules(1).\n\nechoti See the section `The zsh/terminfo Module' in zshmodules(1).\n\nemulate [ -lLR ] [ {zsh|sh|ksh|csh} [ flags ... ] ]\nWithout any argument print current emulation mode.\n\nWith single argument set up zsh options to emulate the specified shell as much as pos‐\nsible. csh will never be fully emulated. If the argument is not one of the shells\nlisted above, zsh will be used as a default; more precisely, the tests performed on\nthe argument are the same as those used to determine the emulation at startup based on\nthe shell name, see the section COMPATIBILITY in zsh(1) . In addition to setting\nshell options, the command also restores the pristine state of pattern enables, as if\nall patterns had been enabled using enable -p.\n\nIf the emulate command occurs inside a function that has been marked for execution\ntracing with functions -t then the xtrace option will be turned on regardless of emu‐\nlation mode or other options. Note that code executed inside the function by the .,\nsource, or eval commands is not considered to be running directly from the function,\nhence does not provoke this behaviour.\n\nIf the -R switch is given, all settable options are reset to their default value cor‐\nresponding to the specified emulation mode, except for certain options describing the\ninteractive environment; otherwise, only those options likely to cause portability\nproblems in scripts and functions are altered. If the -L switch is given, the options\nLOCALOPTIONS, LOCALPATTERNS and LOCALTRAPS will be set as well, causing the effects\nof the emulate command and any setopt, disable -p or enable -p, and trap commands to\nbe local to the immediately surrounding shell function, if any; normally these options\nare turned off in all emulation modes except ksh. The -L switch is mutually exclusive\nwith the use of -c in flags.\n\nIf there is a single argument and the -l switch is given, the options that would be\nset or unset (the latter indicated with the prefix `no') are listed. -l can be com‐\nbined with -L or -R and the list will be modified in the appropriate way. Note the\nlist does not depend on the current setting of options, i.e. it includes all options\nthat may in principle change, not just those that would actually change.\n\nThe flags may be any of the invocation-time flags described in the section INVOCATION\nin zsh(1), except that `-o EMACS' and `-o VI' may not be used. Flags such as `+r'/`+o\nRESTRICTED' may be prohibited in some circumstances.\n\nIf -c arg appears in flags, arg is evaluated while the requested emulation is tempo‐\nrarily in effect. In this case the emulation mode and all options are restored to\ntheir previous values before emulate returns. The -R switch may precede the name of\nthe shell to emulate; note this has a meaning distinct from including -R in flags.\n\nUse of -c enables `sticky' emulation mode for functions defined within the evaluated\nexpression: the emulation mode is associated thereafter with the function so that\nwhenever the function is executed the emulation (respecting the -R switch, if present)\nand all options are set (and pattern disables cleared) before entry to the function,\nand the state is restored after exit. If the function is called when the sticky emu‐\nlation is already in effect, either within an `emulate shell -c' expression or within\nanother function with the same sticky emulation, entry and exit from the function do\nnot cause options to be altered (except due to standard processing such as the LO‐‐\nCALOPTIONS option). This also applies to functions marked for autoload within the\nsticky emulation; the appropriate set of options will be applied at the point the\nfunction is loaded as well as when it is run.\n\nFor example:\n\nemulate sh -c 'fni() { setopt cshnullglob; }\nfno() { fni; }'\nfno\n\nThe two functions fni and fno are defined with sticky sh emulation. fno is then exe‐\ncuted, causing options associated with emulations to be set to their values in sh.\nfno then calls fni; because fni is also marked for sticky sh emulation, no option\nchanges take place on entry to or exit from it. Hence the option cshnullglob, turned\noff by sh emulation, will be turned on within fni and remain on return to fno. On\nexit from fno, the emulation mode and all options will be restored to the state they\nwere in before entry to the temporary emulation.\n\nThe documentation above is typically sufficient for the intended purpose of executing\ncode designed for other shells in a suitable environment. More detailed rules follow.\n1. The sticky emulation environment provided by `emulate shell -c' is identical to\nthat provided by entry to a function marked for sticky emulation as a conse‐\nquence of being defined in such an environment. Hence, for example, the sticky\nemulation is inherited by subfunctions defined within functions with sticky em‐\nulation.\n2. No change of options takes place on entry to or exit from functions that are\nnot marked for sticky emulation, other than those that would normally take\nplace, even if those functions are called within sticky emulation.\n3. No special handling is provided for functions marked for autoload nor for func‐\ntions present in wordcode created by the zcompile command.\n4. The presence or absence of the -R switch to emulate corresponds to different\nsticky emulation modes, so for example `emulate sh -c', `emulate -R sh -c' and\n`emulate csh -c' are treated as three distinct sticky emulations.\n5. Difference in shell options supplied in addition to the basic emulation also\nmean the sticky emulations are different, so for example `emulate zsh -c' and\n`emulate zsh -o cbases -c' are treated as distinct sticky emulations.\n\nenable [ -afmprs ] name ...\nEnable the named hash table elements, presumably disabled earlier with disable. The\ndefault is to enable builtin commands. The -a option causes enable to act on regular\nor global aliases. The -s option causes enable to act on suffix aliases. The -f op‐\ntion causes enable to act on shell functions. The -r option causes enable to act on\nreserved words. Without arguments all enabled hash table elements from the corre‐\nsponding hash table are printed. With the -m flag the arguments are taken as patterns\n(should be quoted) and all hash table elements from the corresponding hash table\nmatching these patterns are enabled. Enabled objects can be disabled with the disable\nbuiltin command.\n\nenable -p reenables patterns disabled with disable -p. Note that it does not override\nglobbing options; for example, `enable -p \"~\"' does not cause the pattern character ~\nto be active unless the EXTENDEDGLOB option is also set. To enable all possible pat‐\nterns (so that they may be individually disabled with disable -p), use `setopt EX‐‐\nTENDEDGLOB KSHGLOB NOSHGLOB'.\n\neval [ arg ... ]\nRead the arguments as input to the shell and execute the resulting command(s) in the\ncurrent shell process. The return status is the same as if the commands had been exe‐\ncuted directly by the shell; if there are no args or they contain no commands (i.e.\nare an empty string or whitespace) the return status is zero.\n\nexec [ -cl ] [ -a argv0 ] [ command [ arg ... ] ]\nReplace the current shell with command rather than forking. If command is a shell\nbuiltin command or a shell function, the shell executes it, and exits when the command\nis complete.\n\nWith -c clear the environment; with -l prepend - to the argv[0] string of the command\nexecuted (to simulate a login shell); with -a argv0 set the argv[0] string of the com‐\nmand executed. See the section `Precommand Modifiers' in zshmisc(1).\n\nIf the option POSIXBUILTINS is set, command is never interpreted as a shell builtin\ncommand or shell function. This means further precommand modifiers such as builtin\nand noglob are also not interpreted within the shell. Hence command is always found\nby searching the command path.\n\nIf command is omitted but any redirections are specified, then the redirections will\ntake effect in the current shell.\n\nexit [ n ]\nExit the shell with the exit status specified by an arithmetic expression n; if none\nis specified, use the exit status from the last command executed. An EOF condition\nwill also cause the shell to exit, unless the IGNOREEOF option is set.\n\nSee notes at the end of the section JOBS in zshmisc(1) for some possibly unexpected\ninteractions of the exit command with jobs.\n\nexport [ name[=value] ... ]\nThe specified names are marked for automatic export to the environment of subsequently\nexecuted commands. Equivalent to typeset -gx. If a parameter specified does not al‐\nready exist, it is created in the global scope.\n\nfalse [ arg ... ]\nDo nothing and return an exit status of 1.\n\n\nfc [ -e ename ] [ -LI ] [ -m match ] [ old=new ... ] [ first [ last ] ]\nfc -l [ -LI ] [ -nrdfEiD ] [ -t timefmt ] [ -m match ]\n[ old=new ... ] [ first [ last ] ]\nfc -p [ -a ] [ filename [ histsize [ savehistsize ] ] ]" }, { "name": "fc -P", "content": "fc -ARWI [ filename ]\nThe fc command controls the interactive history mechanism. Note that reading and\nwriting of history options is only performed if the shell is interactive. Usually\nthis is detected automatically, but it can be forced by setting the interactive option\nwhen starting the shell.\n\nThe first two forms of this command select a range of events from first to last from\nthe history list. The arguments first and last may be specified as a number or as a\nstring. A negative number is used as an offset to the current history event number.\nA string specifies the most recent event beginning with the given string. All substi‐\ntutions old=new, if any, are then performed on the text of the events.\n\nIn addition to the number range,\n-I restricts to only internal events (not from $HISTFILE)\n-L restricts to only local events (not from other shells, see SHAREHISTORY in\nzshoptions(1) -- note that $HISTFILE is considered local when read at startup)\n-m takes the first argument as a pattern (should be quoted) and only the history\nevents matching this pattern are considered\n\nIf first is not specified, it will be set to -1 (the most recent event), or to -16 if\nthe -l flag is given. If last is not specified, it will be set to first, or to -1 if\nthe -l flag is given. However, if the current event has added entries to the history\nwith `print -s' or `fc -R', then the default last for -l includes all new history en‐\ntries since the current event began.\n\nWhen the -l flag is given, the resulting events are listed on standard output. Other‐\nwise the editor program specified by -e ename is invoked on a file containing these\nhistory events. If -e is not given, the value of the parameter FCEDIT is used; if\nthat is not set the value of the parameter EDITOR is used; if that is not set a\nbuiltin default, usually `vi' is used. If ename is `-', no editor is invoked. When\nediting is complete, the edited command is executed.\n\nThe flag -r reverses the order of the events and the flag -n suppresses event numbers\nwhen listing.\n\nAlso when listing,\n-d prints timestamps for each event\n-f prints full time-date stamps in the US `MM/DD/YY hh:mm' format\n-E prints full time-date stamps in the European `dd.mm.yyyy hh:mm' format\n-i prints full time-date stamps in ISO8601 `yyyy-mm-dd hh:mm' format\n-t fmt prints time and date stamps in the given format; fmt is formatted with the\nstrftime function with the zsh extensions described for the %D{string} prompt\nformat in the section EXPANSION OF PROMPT SEQUENCES in zshmisc(1). The result‐\ning formatted string must be no more than 256 characters or will not be printed\n-D prints elapsed times; may be combined with one of the options above\n\n`fc -p' pushes the current history list onto a stack and switches to a new history\nlist. If the -a option is also specified, this history list will be automatically\npopped when the current function scope is exited, which is a much better solution than\ncreating a trap function to call `fc -P' manually. If no arguments are specified, the\nhistory list is left empty, $HISTFILE is unset, and $HISTSIZE & $SAVEHIST are set to\ntheir default values. If one argument is given, $HISTFILE is set to that filename,\n$HISTSIZE & $SAVEHIST are left unchanged, and the history file is read in (if it ex‐\nists) to initialize the new list. If a second argument is specified, $HISTSIZE &\n$SAVEHIST are instead set to the single specified numeric value. Finally, if a third\nargument is specified, $SAVEHIST is set to a separate value from $HISTSIZE. You are\nfree to change these environment values for the new history list however you desire in\norder to manipulate the new history list.\n\n`fc -P' pops the history list back to an older list saved by `fc -p'. The current\nlist is saved to its $HISTFILE before it is destroyed (assuming that $HISTFILE and\n$SAVEHIST are set appropriately, of course). The values of $HISTFILE, $HISTSIZE, and\n$SAVEHIST are restored to the values they had when `fc -p' was called. Note that this\nrestoration can conflict with making these variables \"local\", so your best bet is to\navoid local declarations for these variables in functions that use `fc -p'. The one\nother guaranteed-safe combination is declaring these variables to be local at the top\nof your function and using the automatic option (-a) with `fc -p'. Finally, note that\nit is legal to manually pop a push marked for automatic popping if you need to do so\nbefore the function exits.\n\n`fc -R' reads the history from the given file, `fc -W' writes the history out to the\ngiven file, and `fc -A' appends the history out to the given file. If no filename is\nspecified, the $HISTFILE is assumed. If the -I option is added to -R, only those\nevents that are not already contained within the internal history list are added. If\nthe -I option is added to -A or -W, only those events that are new since last incre‐\nmental append/write to the history file are appended/written. In any case, the cre‐\nated file will have no more than $SAVEHIST entries.\n\nfg [ job ... ]\njob ...\nBring each specified job in turn to the foreground. If no job is specified, resume\nthe current job.\n\nfloat [ {+|-}Hghlprtux ] [ {+|-}EFLRZ [ n ] ] [ name[=value] ... ]\nEquivalent to typeset -E, except that options irrelevant to floating point numbers are\nnot permitted.\n\nfunctions [ {+|-}UkmtTuWz ] [ -x num ] [ name ... ]\nfunctions -c oldfn newfn\nfunctions -M [-s] mathfn [ min [ max [ shellfn ] ] ]\nfunctions -M [ -m pattern ... ]\nfunctions +M [ -m ] mathfn ...\nEquivalent to typeset -f, with the exception of the -c, -x, -M and -W options. For\nfunctions -u and functions -U, see autoload, which provides additional options.\n\nThe -x option indicates that any functions output will have each leading tab for in‐\ndentation, added by the shell to show syntactic structure, expanded to the given num‐\nber num of spaces. num can also be 0 to suppress all indentation.\n\nThe -W option turns on the option WARNNESTEDVAR for the named function or functions\nonly. The option is turned off at the start of nested functions (apart from anonoy‐\nmous functions) unless the called function also has the -W attribute.\n\nThe -c option causes oldfn to be copied to newfn. The copy is efficiently handled in‐\nternally by reference counting. If oldfn was marked for autoload it is first loaded\nand if this fails the copy fails. Either function may subsequently be redefined with‐\nout affecting the other. A typical idiom is that oldfn is the name of a library shell\nfunction which is then redefined to call newfn, thereby installing a modified version\nof the function.\n\nUse of the -M option may not be combined with any of the options handled by typeset\n-f.\n\nfunctions -M mathfn defines mathfn as the name of a mathematical function recognised\nin all forms of arithmetical expressions; see the section `Arithmetic Evaluation' in\nzshmisc(1). By default mathfn may take any number of comma-separated arguments. If\nmin is given, it must have exactly min args; if min and max are both given, it must\nhave at least min and at most max args. max may be -1 to indicate that there is no\nupper limit.\n\nBy default the function is implemented by a shell function of the same name; if\nshellfn is specified it gives the name of the corresponding shell function while\nmathfn remains the name used in arithmetical expressions. The name of the function in\n$0 is mathfn (not shellfn as would usually be the case), provided the option FUNC‐‐\nTIONARGZERO is in effect. The positional parameters in the shell function correspond\nto the arguments of the mathematical function call. The result of the last arithmeti‐\ncal expression evaluated inside the shell function (even if it is a form that normally\nonly returns a status) gives the result of the mathematical function.\n\nIf the additional option -s is given to functions -M, the argument to the function is\na single string: anything between the opening and matching closing parenthesis is\npassed to the function as a single argument, even if it includes commas or white\nspace. The minimum and maximum argument specifiers must therefore be 1 if given. An\nempty argument list is passed as a zero-length string.\n\nfunctions -M with no arguments lists all such user-defined functions in the same form\nas a definition. With the additional option -m and a list of arguments, all functions\nwhose mathfn matches one of the pattern arguments are listed.\n\nfunction +M removes the list of mathematical functions; with the additional option -m\nthe arguments are treated as patterns and all functions whose mathfn matches the pat‐\ntern are removed. Note that the shell function implementing the behaviour is not re‐\nmoved (regardless of whether its name coincides with mathfn).\n\nFor example, the following prints the cube of 3:\n\nzmathcube() { (( $1 * $1 * $1 )) }\nfunctions -M cube 1 1 zmathcube\nprint $(( cube(3) ))\n\nThe following string function takes a single argument, including the commas, so prints\n11:\n\nstringfn() { (( $#1 )) }\nfunctions -Ms stringfn\nprint $(( stringfn(foo,bar,rod) ))\n\ngetcap See the section `The zsh/cap Module' in zshmodules(1).\n\ngetln [ -AclneE ] name ...\nRead the top value from the buffer stack and put it in the shell parameter name.\nEquivalent to read -zr.\n\ngetopts optstring name [ arg ... ]\nChecks the args for legal options. If the args are omitted, use the positional param‐\neters. A valid option argument begins with a `+' or a `-'. An argument not beginning\nwith a `+' or a `-', or the argument `--', ends the options. Note that a single `-'\nis not considered a valid option argument. optstring contains the letters that\ngetopts recognizes. If a letter is followed by a `:', that option requires an argu‐\nment. The options can be separated from the argument by blanks.\n\nEach time it is invoked, getopts places the option letter it finds in the shell param‐\neter name, prepended with a `+' when arg begins with a `+'. The index of the next arg\nis stored in OPTIND. The option argument, if any, is stored in OPTARG.\n\nThe first option to be examined may be changed by explicitly assigning to OPTIND.\nOPTIND has an initial value of 1, and is normally set to 1 upon entry to a shell func‐\ntion and restored upon exit (this is disabled by the POSIXBUILTINS option). OPTARG\nis not reset and retains its value from the most recent call to getopts. If either of\nOPTIND or OPTARG is explicitly unset, it remains unset, and the index or option argu‐\nment is not stored. The option itself is still stored in name in this case.\n\nA leading `:' in optstring causes getopts to store the letter of any invalid option in\nOPTARG, and to set name to `?' for an unknown option and to `:' when a required argu‐\nment is missing. Otherwise, getopts sets name to `?' and prints an error message when\nan option is invalid. The exit status is nonzero when there are no more options.\n\nhash [ -Ldfmrv ] [ name[=value] ] ...\nhash can be used to directly modify the contents of the command hash table, and the\nnamed directory hash table. Normally one would modify these tables by modifying one's\nPATH (for the command hash table) or by creating appropriate shell parameters (for the\nnamed directory hash table). The choice of hash table to work on is determined by the\n-d option; without the option the command hash table is used, and with the option the\nnamed directory hash table is used.\n\nA command name starting with a / is never hashed, whether by explicit use of the hash\ncommand or otherwise. Such a command is always found by direct look up in the file\nsystem.\n\nGiven no arguments, and neither the -r or -f options, the selected hash table will be\nlisted in full.\n\nThe -r option causes the selected hash table to be emptied. It will be subsequently\nrebuilt in the normal fashion. The -f option causes the selected hash table to be\nfully rebuilt immediately. For the command hash table this hashes all the absolute\ndirectories in the PATH, and for the named directory hash table this adds all users'\nhome directories. These two options cannot be used with any arguments.\n\nThe -m option causes the arguments to be taken as patterns (which should be quoted)\nand the elements of the hash table matching those patterns are printed. This is the\nonly way to display a limited selection of hash table elements.\n\nFor each name with a corresponding value, put `name' in the selected hash table, asso‐\nciating it with the pathname `value'. In the command hash table, this means that\nwhenever `name' is used as a command argument, the shell will try to execute the file\ngiven by `value'. In the named directory hash table, this means that `value' may be\nreferred to as `~name'.\n\nFor each name with no corresponding value, attempt to add name to the hash table,\nchecking what the appropriate value is in the normal manner for that hash table. If\nan appropriate value can't be found, then the hash table will be unchanged.\n\nThe -v option causes hash table entries to be listed as they are added by explicit\nspecification. If has no effect if used with -f.\n\nIf the -L flag is present, then each hash table entry is printed in the form of a call\nto hash.\n" }, { "name": "history", "content": "Same as fc -l.\n\ninteger [ {+|-}Hghlprtux ] [ {+|-}LRZi [ n ] ] [ name[=value] ... ]\nEquivalent to typeset -i, except that options irrelevant to integers are not permit‐\nted.\n\njobs [ -dlprs ] [ job ... ]\njobs -Z string\nLists information about each given job, or all jobs if job is omitted. The -l flag\nlists process IDs, and the -p flag lists process groups. If the -r flag is specified\nonly running jobs will be listed and if the -s flag is given only stopped jobs are\nshown. If the -d flag is given, the directory from which the job was started (which\nmay not be the current directory of the job) will also be shown.\n\nThe -Z option replaces the shell's argument and environment space with the given\nstring, truncated if necessary to fit. This will normally be visible in ps (ps(1))\nlistings. This feature is typically used by daemons, to indicate their state.\n\nkill [ -s signalname | -n signalnumber | -sig ] job ...\nkill -l [ sig ... ]\nSends either SIGTERM or the specified signal to the given jobs or processes. Signals\nare given by number or by names, with or without the `SIG' prefix. If the signal be‐\ning sent is not `KILL' or `CONT', then the job will be sent a `CONT' signal if it is\nstopped. The argument job can be the process ID of a job not in the job list. In the\nsecond form, kill -l, if sig is not specified the signal names are listed. Otherwise,\nfor each sig that is a name, the corresponding signal number is listed. For each sig\nthat is a signal number or a number representing the exit status of a process which\nwas terminated or stopped by a signal the name of the signal is printed.\n\nOn some systems, alternative signal names are allowed for a few signals. Typical ex‐\namples are SIGCHLD and SIGCLD or SIGPOLL and SIGIO, assuming they correspond to the\nsame signal number. kill -l will only list the preferred form, however kill -l alt\nwill show if the alternative form corresponds to a signal number. For example, under\nLinux kill -l IO and kill -l POLL both output 29, hence kill -IO and kill -POLL have\nthe same effect.\n\nMany systems will allow process IDs to be negative to kill a process group or zero to\nkill the current process group.\n\nlet arg ...\nEvaluate each arg as an arithmetic expression. See the section `Arithmetic Evalua‐\ntion' in zshmisc(1) for a description of arithmetic expressions. The exit status is 0\nif the value of the last expression is nonzero, 1 if it is zero, and 2 if an error oc‐\ncurred.\n\nlimit [ -hs ] [ resource [ limit ] ] ...\nSet or display resource limits. Unless the -s flag is given, the limit applies only\nthe children of the shell. If -s is given without other arguments, the resource lim‐\nits of the current shell is set to the previously set resource limits of the children.\n\nIf limit is not specified, print the current limit placed on resource, otherwise set\nthe limit to the specified value. If the -h flag is given, use hard limits instead of\nsoft limits. If no resource is given, print all limits.\n\nWhen looping over multiple resources, the shell will abort immediately if it detects a\nbadly formed argument. However, if it fails to set a limit for some other reason it\nwill continue trying to set the remaining limits.\n\nresource can be one of:\n\naddressspace\nMaximum amount of address space used.\naiomemorylocked\nMaximum amount of memory locked in RAM for AIO operations.\naiooperations\nMaximum number of AIO operations.\ncachedthreads\nMaximum number of cached threads.\ncoredumpsize\nMaximum size of a core dump.\ncputime\nMaximum CPU seconds per process.\ndatasize\nMaximum data size (including stack) for each process.\ndescriptors\nMaximum value for a file descriptor.\nfilesize\nLargest single file allowed.\nkqueues\nMaximum number of kqueues allocated.\nmaxproc\nMaximum number of processes.\nmaxpthreads\nMaximum number of threads per process.\nmemorylocked\nMaximum amount of memory locked in RAM.\nmemoryuse\nMaximum resident set size.\nmsgqueue\nMaximum number of bytes in POSIX message queues.\nposixlocks\nMaximum number of POSIX locks per user.\npseudoterminals\nMaximum number of pseudo-terminals.\nresident\nMaximum resident set size.\nsigpending\nMaximum number of pending signals.\nsockbufsize\nMaximum size of all socket buffers.\nstacksize\nMaximum stack size for each process.\nswapsize\nMaximum amount of swap used.\nvmemorysize\nMaximum amount of virtual memory.\n\nWhich of these resource limits are available depends on the system. resource can be\nabbreviated to any unambiguous prefix. It can also be an integer, which corresponds\nto the integer defined for the resource by the operating system.\n\nIf argument corresponds to a number which is out of the range of the resources config‐\nured into the shell, the shell will try to read or write the limit anyway, and will\nreport an error if this fails. As the shell does not store such resources internally,\nan attempt to set the limit will fail unless the -s option is present.\n\nlimit is a number, with an optional scaling factor, as follows:\n\nnh hours\nnk kilobytes (default)\nnm megabytes or minutes\nng gigabytes\n[mm:]ss\nminutes and seconds\n\nThe limit command is not made available by default when the shell starts in a mode em‐\nulating another shell. It can be made available with the command `zmodload -F\nzsh/rlimits b:limit'.\n\nlocal [ {+|-}AHUahlprtux ] [ {+|-}EFLRZi [ n ] ] [ name[=value] ... ]\nSame as typeset, except that the options -g, and -f are not permitted. In this case\nthe -x option does not force the use of -g, i.e. exported variables will be local to\nfunctions.\n\nlog List all users currently logged in who are affected by the current setting of the\nwatch parameter.\n\nlogout [ n ]\nSame as exit, except that it only works in a login shell.\n\nnoglob simple command\nSee the section `Precommand Modifiers' in zshmisc(1).\n\npopd [ -q ] [ {+|-}n ]\nRemove an entry from the directory stack, and perform a cd to the new top directory.\nWith no argument, the current top entry is removed. An argument of the form `+n'\nidentifies a stack entry by counting from the left of the list shown by the dirs com‐\nmand, starting with zero. An argument of the form -n counts from the right. If the\nPUSHDMINUS option is set, the meanings of `+' and `-' in this context are swapped.\n\nIf the -q (quiet) option is specified, the hook function chpwd and the functions in\nthe array $chpwdfunctions are not called, and the new directory stack is not printed.\nThis is useful for calls to popd that do not change the environment seen by an inter‐\nactive user.\n\nprint [ -abcDilmnNoOpPrsSz ] [ -u n ] [ -f format ] [ -C cols ]\n[ -v name ] [ -xX tabstop ] [ -R [ -en ]] [ arg ... ]\nWith the `-f' option the arguments are printed as described by printf. With no flags\nor with the flag `-', the arguments are printed on the standard output as described by\necho, with the following differences: the escape sequence `\\M-x' (or `\\Mx') metafies\nthe character x (sets the highest bit), `\\C-x' (or `\\Cx') produces a control character\n(`\\C-@' and `\\C-?' give the characters NULL and delete), a character code in octal is\nrepresented by `\\NNN' (instead of `\\0NNN'), and `\\E' is a synonym for `\\e'. Finally,\nif not in an escape sequence, `\\' escapes the following character and is not printed.\n\n-a Print arguments with the column incrementing first. Only useful with the -c\nand -C options.\n\n-b Recognize all the escape sequences defined for the bindkey command, see the\nsection `Zle Builtins' in zshzle(1).\n\n-c Print the arguments in columns. Unless -a is also given, arguments are printed\nwith the row incrementing first.\n\n-C cols\nPrint the arguments in cols columns. Unless -a is also given, arguments are\nprinted with the row incrementing first.\n\n-D Treat the arguments as paths, replacing directory prefixes with ~ expressions\ncorresponding to directory names, as appropriate.\n\n-i If given together with -o or -O, sorting is performed case-independently.\n\n-l Print the arguments separated by newlines instead of spaces. Note: if the list\nof arguments is empty, print -l will still output one empty line. To print a\npossibly-empty list of arguments one per line, use print -C1, as in `print -rC1\n-- \"$list[@]\"'.\n\n-m Take the first argument as a pattern (should be quoted), and remove it from the\nargument list together with subsequent arguments that do not match this pat‐\ntern.\n\n-n Do not add a newline to the output.\n\n-N Print the arguments separated and terminated by nulls. Again, print -rNC1 --\n\"$list[@]\" is a canonical way to print an arbitrary list as null-delimited\nrecords.\n\n-o Print the arguments sorted in ascending order.\n\n-O Print the arguments sorted in descending order.\n\n-p Print the arguments to the input of the coprocess.\n\n-P Perform prompt expansion (see EXPANSION OF PROMPT SEQUENCES in zshmisc(1)). In\ncombination with `-f', prompt escape sequences are parsed only within interpo‐\nlated arguments, not within the format string.\n\n-r Ignore the escape conventions of echo.\n\n-R Emulate the BSD echo command, which does not process escape sequences unless\nthe -e flag is given. The -n flag suppresses the trailing newline. Only the\n-e and -n flags are recognized after -R; all other arguments and options are\nprinted.\n\n-s Place the results in the history list instead of on the standard output. Each\nargument to the print command is treated as a single word in the history, re‐\ngardless of its content.\n\n-S Place the results in the history list instead of on the standard output. In\nthis case only a single argument is allowed; it will be split into words as if\nit were a full shell command line. The effect is similar to reading the line\nfrom a history file with the HISTLEXWORDS option active.\n\n-u n Print the arguments to file descriptor n.\n\n-v name\nStore the printed arguments as the value of the parameter name.\n\n-x tab-stop\nExpand leading tabs on each line of output in the printed string assuming a tab\nstop every tab-stop characters. This is appropriate for formatting code that\nmay be indented with tabs. Note that leading tabs of any argument to print,\nnot just the first, are expanded, even if print is using spaces to separate ar‐\nguments (the column count is maintained across arguments but may be incorrect\non output owing to previous unexpanded tabs).\n\nThe start of the output of each print command is assumed to be aligned with a\ntab stop. Widths of multibyte characters are handled if the option MULTIBYTE\nis in effect. This option is ignored if other formatting options are in ef‐\nfect, namely column alignment or printf style, or if output is to a special lo‐\ncation such as shell history or the command line editor.\n\n-X tab-stop\nThis is similar to -x, except that all tabs in the printed string are expanded.\nThis is appropriate if tabs in the arguments are being used to produce a table\nformat.\n\n-z Push the arguments onto the editing buffer stack, separated by spaces.\n\nIf any of `-m', `-o' or `-O' are used in combination with `-f' and there are no argu‐\nments (after the removal process in the case of `-m') then nothing is printed.\n\nprintf [ -v name ] format [ arg ... ]\nPrint the arguments according to the format specification. Formatting rules are the\nsame as used in C. The same escape sequences as for echo are recognised in the format.\nAll C conversion specifications ending in one of csdiouxXeEfgGn are handled. In addi‐\ntion to this, `%b' can be used instead of `%s' to cause escape sequences in the argu‐\nment to be recognised and `%q' can be used to quote the argument in such a way that\nallows it to be reused as shell input. With the numeric format specifiers, if the cor‐\nresponding argument starts with a quote character, the numeric value of the following\ncharacter is used as the number to print; otherwise the argument is evaluated as an\narithmetic expression. See the section `Arithmetic Evaluation' in zshmisc(1) for a de‐\nscription of arithmetic expressions. With `%n', the corresponding argument is taken as\nan identifier which is created as an integer parameter.\n\nNormally, conversion specifications are applied to each argument in order but they can\nexplicitly specify the nth argument is to be used by replacing `%' by `%n$' and `*' by\n`*n$'. It is recommended that you do not mix references of this explicit style with\nthe normal style and the handling of such mixed styles may be subject to future\nchange.\n\nIf arguments remain unused after formatting, the format string is reused until all ar‐\nguments have been consumed. With the print builtin, this can be suppressed by using\nthe -r option. If more arguments are required by the format than have been specified,\nthe behaviour is as if zero or an empty string had been specified as the argument.\n\nThe -v option causes the output to be stored as the value of the parameter name, in‐\nstead of printed. If name is an array and the format string is reused when consuming\narguments then one array element will be used for each use of the format string.\n\npushd [ -qsLP ] [ arg ]\npushd [ -qsLP ] old new\npushd [ -qsLP ] {+|-}n\nChange the current directory, and push the old current directory onto the directory\nstack. In the first form, change the current directory to arg. If arg is not speci‐\nfied, change to the second directory on the stack (that is, exchange the top two en‐\ntries), or change to $HOME if the PUSHDTOHOME option is set or if there is only one\nentry on the stack. Otherwise, arg is interpreted as it would be by cd. The meaning\nof old and new in the second form is also the same as for cd.\n\nThe third form of pushd changes directory by rotating the directory list. An argument\nof the form `+n' identifies a stack entry by counting from the left of the list shown\nby the dirs command, starting with zero. An argument of the form `-n' counts from the\nright. If the PUSHDMINUS option is set, the meanings of `+' and `-' in this context\nare swapped.\n\nIf the -q (quiet) option is specified, the hook function chpwd and the functions in\nthe array $chpwdfunctions are not called, and the new directory stack is not printed.\nThis is useful for calls to pushd that do not change the environment seen by an inter‐\nactive user.\n\nIf the option -q is not specified and the shell option PUSHDSILENT is not set, the\ndirectory stack will be printed after a pushd is performed.\n\nThe options -s, -L and -P have the same meanings as for the cd builtin.\n\npushln [ arg ... ]\nEquivalent to print -nz.\n\npwd [ -rLP ]\nPrint the absolute pathname of the current working directory. If the -r or the -P\nflag is specified, or the CHASELINKS option is set and the -L flag is not given, the\nprinted path will not contain symbolic links.\n\nr Same as fc -e -.\n\n\nread [ -rszpqAclneE ] [ -t [ num ] ] [ -k [ num ] ] [ -d delim ]\n[ -u n ] [ name[?prompt] ] [ name ... ]\nRead one line and break it into fields using the characters in $IFS as separators, ex‐\ncept as noted below. The first field is assigned to the first name, the second field\nto the second name, etc., with leftover fields assigned to the last name. If name is\nomitted then REPLY is used for scalars and reply for arrays.\n\n-r Raw mode: a `\\' at the end of a line does not signify line continuation and\nbackslashes in the line don't quote the following character and are not re‐\nmoved.\n\n-s Don't echo back characters if reading from the terminal.\n\n-q Read only one character from the terminal and set name to `y' if this character\nwas `y' or `Y' and to `n' otherwise. With this flag set the return status is\nzero only if the character was `y' or `Y'. This option may be used with a\ntimeout (see -t); if the read times out, or encounters end of file, status 2 is\nreturned. Input is read from the terminal unless one of -u or -p is present.\nThis option may also be used within zle widgets.\n\n-k [ num ]\nRead only one (or num) characters. All are assigned to the first name, without\nword splitting. This flag is ignored when -q is present. Input is read from\nthe terminal unless one of -u or -p is present. This option may also be used\nwithin zle widgets.\n\nNote that despite the mnemonic `key' this option does read full characters,\nwhich may consist of multiple bytes if the option MULTIBYTE is set.\n\n-z Read one entry from the editor buffer stack and assign it to the first name,\nwithout word splitting. Text is pushed onto the stack with `print -z' or with\npush-line from the line editor (see zshzle(1)). This flag is ignored when the\n-k or -q flags are present.\n\n-e\n-E The input read is printed (echoed) to the standard output. If the -e flag is\nused, no input is assigned to the parameters.\n\n-A The first name is taken as the name of an array and all words are assigned to\nit.\n\n-c\n-l These flags are allowed only if called inside a function used for completion\n(specified with the -K flag to compctl). If the -c flag is given, the words of\nthe current command are read. If the -l flag is given, the whole line is as‐\nsigned as a scalar. If both flags are present, -l is used and -c is ignored.\n\n-n Together with -c, the number of the word the cursor is on is read. With -l,\nthe index of the character the cursor is on is read. Note that the command\nname is word number 1, not word 0, and that when the cursor is at the end of\nthe line, its character index is the length of the line plus one.\n\n-u n Input is read from file descriptor n.\n\n-p Input is read from the coprocess.\n\n-d delim\nInput is terminated by the first character of delim instead of by newline.\n\n-t [ num ]\nTest if input is available before attempting to read. If num is present, it\nmust begin with a digit and will be evaluated to give a number of seconds,\nwhich may be a floating point number; in this case the read times out if input\nis not available within this time. If num is not present, it is taken to be\nzero, so that read returns immediately if no input is available. If no input\nis available, return status 1 and do not set any variables.\n\nThis option is not available when reading from the editor buffer with -z, when\ncalled from within completion with -c or -l, with -q which clears the input\nqueue before reading, or within zle where other mechanisms should be used to\ntest for input.\n\nNote that read does not attempt to alter the input processing mode. The de‐\nfault mode is canonical input, in which an entire line is read at a time, so\nusually `read -t' will not read anything until an entire line has been typed.\nHowever, when reading from the terminal with -k input is processed one key at a\ntime; in this case, only availability of the first character is tested, so that\ne.g. `read -t -k 2' can still block on the second character. Use two instances\nof `read -t -k' if this is not what is wanted.\n\nIf the first argument contains a `?', the remainder of this word is used as a prompt\non standard error when the shell is interactive.\n\nThe value (exit status) of read is 1 when an end-of-file is encountered, or when -c or\n-l is present and the command is not called from a compctl function, or as described\nfor -q. Otherwise the value is 0.\n\nThe behavior of some combinations of the -k, -p, -q, -u and -z flags is undefined.\nPresently -q cancels all the others, -p cancels -u, -k cancels -z, and otherwise -z\ncancels both -p and -u.\n\nThe -c or -l flags cancel any and all of -kpquz.\n" }, { "name": "readonly", "content": "Same as typeset -r. With the POSIXBUILTINS option set, same as typeset -gr.\n\nrehash Same as hash -r.\n\nreturn [ n ]\nCauses a shell function or `.' script to return to the invoking script with the return\nstatus specified by an arithmetic expression n. If n is omitted, the return status is\nthat of the last command executed.\n\nIf return was executed from a trap in a TRAPNAL function, the effect is different for\nzero and non-zero return status. With zero status (or after an implicit return at the\nend of the trap), the shell will return to whatever it was previously processing; with\na non-zero status, the shell will behave as interrupted except that the return status\nof the trap is retained. Note that the numeric value of the signal which caused the\ntrap is passed as the first argument, so the statement `return $((128+$1))' will re‐\nturn the same status as if the signal had not been trapped.\n\nsched See the section `The zsh/sched Module' in zshmodules(1).\n\n\nset [ {+|-}options | {+|-}o [ optionname ] ] ... [ {+|-}A [ name ] ]\n[ arg ... ]\nSet the options for the shell and/or set the positional parameters, or declare and set\nan array. If the -s option is given, it causes the specified arguments to be sorted\nbefore assigning them to the positional parameters (or to the array name if -A is\nused). With +s sort arguments in descending order. For the meaning of the other\nflags, see zshoptions(1). Flags may be specified by name using the -o option. If no\noption name is supplied with -o, the current option states are printed: see the de‐\nscription of setopt below for more information on the format. With +o they are\nprinted in a form that can be used as input to the shell.\n\nIf the -A flag is specified, name is set to an array containing the given args; if no\nname is specified, all arrays are printed together with their values.\n\nIf +A is used and name is an array, the given arguments will replace the initial ele‐\nments of that array; if no name is specified, all arrays are printed without their\nvalues.\n\nThe behaviour of arguments after -A name or +A name depends on whether the option\nKSHARRAYS is set. If it is not set, all arguments following name are treated as val‐\nues for the array, regardless of their form. If the option is set, normal option pro‐\ncessing continues at that point; only regular arguments are treated as values for the\narray. This means that\n\nset -A array -x -- foo\n\nsets array to `-x -- foo' if KSHARRAYS is not set, but sets the array to foo and\nturns on the option `-x' if it is set.\n\nIf the -A flag is not present, but there are arguments beyond the options, the posi‐\ntional parameters are set. If the option list (if any) is terminated by `--', and\nthere are no further arguments, the positional parameters will be unset.\n\nIf no arguments and no `--' are given, then the names and values of all parameters are\nprinted on the standard output. If the only argument is `+', the names of all parame‐\nters are printed.\n\nFor historical reasons, `set -' is treated as `set +xv' and `set - args' as `set +xv\n-- args' when in any other emulation mode than zsh's native mode.\n\nsetcap See the section `The zsh/cap Module' in zshmodules(1).\n\nsetopt [ {+|-}options | {+|-}o optionname ] [ -m ] [ name ... ]\nSet the options for the shell. All options specified either with flags or by name are\nset.\n\nIf no arguments are supplied, the names of all options currently set are printed. The\nform is chosen so as to minimize the differences from the default options for the cur‐\nrent emulation (the default emulation being native zsh, shown as in zshop‐\ntions(1)). Options that are on by default for the emulation are shown with the prefix\nno only if they are off, while other options are shown without the prefix no and only\nif they are on. In addition to options changed from the default state by the user,\nany options activated automatically by the shell (for example, SHINSTDIN or INTERAC‐‐\nTIVE) will be shown in the list. The format is further modified by the option KSHOP‐‐\nTIONPRINT, however the rationale for choosing options with or without the no prefix\nremains the same in this case.\n\nIf the -m flag is given the arguments are taken as patterns (which should be quoted to\nprotect them from filename expansion), and all options with names matching these pat‐\nterns are set.\n\nNote that a bad option name does not cause execution of subsequent shell code to be\naborted; this is behaviour is different from that of `set -o'. This is because set is\nregarded as a special builtin by the POSIX standard, but setopt is not.\n\nshift [ -p ] [ n ] [ name ... ]\nThe positional parameters ${n+1} ... are renamed to $1 ..., where n is an arithmetic\nexpression that defaults to 1. If any names are given then the arrays with these\nnames are shifted instead of the positional parameters.\n\nIf the option -p is given arguments are instead removed (popped) from the end rather\nthan the start of the array.\n\nsource file [ arg ... ]\nSame as `.', except that the current directory is always searched and is always\nsearched first, before directories in $path.\n\nstat See the section `The zsh/stat Module' in zshmodules(1).\n\nsuspend [ -f ]\nSuspend the execution of the shell (send it a SIGTSTP) until it receives a SIGCONT.\nUnless the -f option is given, this will refuse to suspend a login shell.\n\ntest [ arg ... ]\n[ [ arg ... ] ]\nLike the system version of test. Added for compatibility; use conditional expressions\ninstead (see the section `Conditional Expressions'). The main differences between the\nconditional expression syntax and the test and [ builtins are: these commands are not\nhandled syntactically, so for example an empty variable expansion may cause an argu‐\nment to be omitted; syntax errors cause status 2 to be returned instead of a shell er‐\nror; and arithmetic operators expect integer arguments rather than arithmetic expres‐\nsions.\n\nThe command attempts to implement POSIX and its extensions where these are specified.\nUnfortunately there are intrinsic ambiguities in the syntax; in particular there is no\ndistinction between test operators and strings that resemble them. The standard at‐\ntempts to resolve these for small numbers of arguments (up to four); for five or more\narguments compatibility cannot be relied on. Users are urged wherever possible to use\nthe `[[' test syntax which does not have these ambiguities.\n\ntimes Print the accumulated user and system times for the shell and for processes run from\nthe shell.\n\ntrap [ arg ] [ sig ... ]\narg is a series of commands (usually quoted to protect it from immediate evaluation by\nthe shell) to be read and executed when the shell receives any of the signals speci‐\nfied by one or more sig args. Each sig can be given as a number, or as the name of a\nsignal either with or without the string SIG in front (e.g. 1, HUP, and SIGHUP are all\nthe same signal).\n\nIf arg is `-', then the specified signals are reset to their defaults, or, if no sig\nargs are present, all traps are reset.\n\nIf arg is an empty string, then the specified signals are ignored by the shell (and by\nthe commands it invokes).\n\nIf arg is omitted but one or more sig args are provided (i.e. the first argument is a\nvalid signal number or name), the effect is the same as if arg had been specified as\n`-'.\n\nThe trap command with no arguments prints a list of commands associated with each sig‐\nnal.\n\nIf sig is ZERR then arg will be executed after each command with a nonzero exit sta‐\ntus. ERR is an alias for ZERR on systems that have no SIGERR signal (this is the\nusual case).\n\nIf sig is DEBUG then arg will be executed before each command if the option DEBUGBE‐‐\nFORECMD is set (as it is by default), else after each command. Here, a `command' is\nwhat is described as a `sublist' in the shell grammar, see the section SIMPLE COMMANDS\n& PIPELINES in zshmisc(1). If DEBUGBEFORECMD is set various additional features are\navailable. First, it is possible to skip the next command by setting the option\nERREXIT; see the description of the ERREXIT option in zshoptions(1). Also, the\nshell parameter ZSHDEBUGCMD is set to the string corresponding to the command to be\nexecuted following the trap. Note that this string is reconstructed from the internal\nformat and may not be formatted the same way as the original text. The parameter is\nunset after the trap is executed.\n\nIf sig is 0 or EXIT and the trap statement is executed inside the body of a function,\nthen the command arg is executed after the function completes. The value of $? at the\nstart of execution is the exit status of the shell or the return status of the func‐\ntion exiting. If sig is 0 or EXIT and the trap statement is not executed inside the\nbody of a function, then the command arg is executed when the shell terminates; the\ntrap runs before any zshexit hook functions.\n\nZERR, DEBUG, and EXIT traps are not executed inside other traps. ZERR and DEBUG traps\nare kept within subshells, while other traps are reset.\n\nNote that traps defined with the trap builtin are slightly different from those de‐\nfined as `TRAPNAL () { ... }', as the latter have their own function environment (line\nnumbers, local variables, etc.) while the former use the environment of the command in\nwhich they were called. For example,\n\ntrap 'print $LINENO' DEBUG\n\nwill print the line number of a command executed after it has run, while\n\nTRAPDEBUG() { print $LINENO; }\n\nwill always print the number zero.\n\nAlternative signal names are allowed as described under kill above. Defining a trap\nunder either name causes any trap under an alternative name to be removed. However,\nit is recommended that for consistency users stick exclusively to one name or another.\n\ntrue [ arg ... ]\nDo nothing and return an exit status of 0.\n\nttyctl [ -fu ]\nThe -f option freezes the tty (i.e. terminal or terminal emulator), and -u unfreezes\nit. When the tty is frozen, no changes made to the tty settings by external programs\nwill be honored by the shell, except for changes in the size of the screen; the shell\nwill simply reset the settings to their previous values as soon as each command exits\nor is suspended. Thus, stty and similar programs have no effect when the tty is\nfrozen. Freezing the tty does not cause the current state to be remembered: instead,\nit causes future changes to the state to be blocked.\n\nWithout options it reports whether the terminal is frozen or not.\n\nNote that, regardless of whether the tty is frozen or not, the shell needs to change\nthe settings when the line editor starts, so unfreezing the tty does not guarantee\nsettings made on the command line are preserved. Strings of commands run between\nediting the command line will see a consistent tty state. See also the shell variable\nSTTY for a means of initialising the tty before running external commands.\n\ntype [ -wfpamsS ] name ...\nEquivalent to whence -v.\n\n\ntypeset [ {+|-}AHUaghlmrtux ] [ {+|-}EFLRZip [ n ] ]\n[ + ] [ name[=value] ... ]\ntypeset -T [ {+|-}Uglrux ] [ {+|-}LRZp [ n ] ]\n[ + | SCALAR[=value] array[=(value ...)] [ sep ] ]\ntypeset -f [ {+|-}TUkmtuz ] [ + ] [ name ... ]\nSet or display attributes and values for shell parameters.\n\nExcept as noted below for control flags that change the behavior, a parameter is cre‐\nated for each name that does not already refer to one. When inside a function, a new\nparameter is created for every name (even those that already exist), and is unset\nagain when the function completes. See `Local Parameters' in zshparam(1). The same\nrules apply to special shell parameters, which retain their special attributes when\nmade local.\n\nFor each name=value assignment, the parameter name is set to value.\n\nIf the shell option TYPESETSILENT is not set, for each remaining name that refers to\na parameter that is already set, the name and value of the parameter are printed in\nthe form of an assignment. Nothing is printed for newly-created parameters, or when\nany attribute flags listed below are given along with the name. Using `+' instead of\nminus to introduce an attribute turns it off.\n\nIf no name is present, the names and values of all parameters are printed. In this\ncase the attribute flags restrict the display to only those parameters that have the\nspecified attributes, and using `+' rather than `-' to introduce the flag suppresses\nprinting of the values of parameters when there is no parameter name.\n\nAll forms of the command handle scalar assignment. Array assignment is possible if\nany of the reserved words declare, export, float, integer, local, readonly or typeset\nis matched when the line is parsed (N.B. not when it is executed). In this case the\narguments are parsed as assignments, except that the `+=' syntax and the GLOBASSIGN\noption are not supported, and scalar values after = are not split further into words,\neven if expanded (regardless of the setting of the KSHTYPESET option; this option is\nobsolete).\n\nExamples of the differences between command and reserved word parsing:\n\n# Reserved word parsing\ntypeset svar=$(echo one word) avar=(several words)\n\nThe above creates a scalar parameter svar and an array parameter avar as if the as‐\nsignments had been\n\nsvar=\"one word\"\navar=(several words)\n\nOn the other hand:\n\n# Normal builtin interface\nbuiltin typeset svar=$(echo two words)\n\nThe builtin keyword causes the above to use the standard builtin interface to typeset\nin which argument parsing is performed in the same way as for other commands. This\nexample creates a scalar svar containing the value two and another scalar parameter\nwords with no value. An array value in this case would either cause an error or be\ntreated as an obscure set of glob qualifiers.\n\nArbitrary arguments are allowed if they take the form of assignments after command\nline expansion; however, these only perform scalar assignment:\n\nvar='svar=val'\ntypeset $var\n\nThe above sets the scalar parameter svar to the value val. Parentheses around the\nvalue within var would not cause array assignment as they will be treated as ordinary\ncharacters when $var is substituted. Any non-trivial expansion in the name part of\nthe assignment causes the argument to be treated in this fashion:\n\ntypeset {var1,var2,var3}=name\n\nThe above syntax is valid, and has the expected effect of setting the three parameters\nto the same value, but the command line is parsed as a set of three normal command\nline arguments to typeset after expansion. Hence it is not possible to assign to mul‐\ntiple arrays by this means.\n\nNote that each interface to any of the commands my be disabled separately. For exam‐\nple, `disable -r typeset' disables the reserved word interface to typeset, exposing\nthe builtin interface, while `disable typeset' disables the builtin. Note that dis‐\nabling the reserved word interface for typeset may cause problems with the output of\n`typeset -p', which assumes the reserved word interface is available in order to re‐\nstore array and associative array values.\n\nUnlike parameter assignment statements, typeset's exit status on an assignment that\ninvolves a command substitution does not reflect the exit status of the command sub‐\nstitution. Therefore, to test for an error in a command substitution, separate the\ndeclaration of the parameter from its initialization:\n\n# WRONG\ntypeset var1=$(exit 1) || echo \"Trouble with var1\"\n\n# RIGHT\ntypeset var1 && var1=$(exit 1) || echo \"Trouble with var1\"\n\nTo initialize a parameter param to a command output and mark it readonly, use typeset\n-r param or readonly param after the parameter assignment statement.\n\nIf no attribute flags are given, and either no name arguments are present or the flag\n+m is used, then each parameter name printed is preceded by a list of the attributes\nof that parameter (array, association, exported, float, integer, readonly, or unde‐‐\nfined for autoloaded parameters not yet loaded). If +m is used with attribute flags,\nand all those flags are introduced with +, the matching parameter names are printed\nbut their values are not.\n\nThe following control flags change the behavior of typeset:\n\n+ If `+' appears by itself in a separate word as the last option, then the names\nof all parameters (functions with -f) are printed, but the values (function\nbodies) are not. No name arguments may appear, and it is an error for any\nother options to follow `+'. The effect of `+' is as if all attribute flags\nwhich precede it were given with a `+' prefix. For example, `typeset -U +' is\nequivalent to `typeset +U' and displays the names of all arrays having the\nuniqueness attribute, whereas `typeset -f -U +' displays the names of all au‐\ntoloadable functions. If + is the only option, then type information (array,\nreadonly, etc.) is also printed for each parameter, in the same manner as\n`typeset +m \"*\"'.\n\n-g The -g (global) means that any resulting parameter will not be restricted to\nlocal scope. Note that this does not necessarily mean that the parameter will\nbe global, as the flag will apply to any existing parameter (even if unset)\nfrom an enclosing function. This flag does not affect the parameter after cre‐\nation, hence it has no effect when listing existing parameters, nor does the\nflag +g have any effect except in combination with -m (see below).\n\n-m If the -m flag is given the name arguments are taken as patterns (use quoting\nto prevent these from being interpreted as file patterns). With no attribute\nflags, all parameters (or functions with the -f flag) with matching names are\nprinted (the shell option TYPESETSILENT is not used in this case).\n\nIf the +g flag is combined with -m, a new local parameter is created for every\nmatching parameter that is not already local. Otherwise -m applies all other\nflags or assignments to the existing parameters.\n\nExcept when assignments are made with name=value, using +m forces the matching\nparameters and their attributes to be printed, even inside a function. Note\nthat -m is ignored if no patterns are given, so `typeset -m' displays at‐\ntributes but `typeset -a +m' does not.\n\n-p [ n ]\nIf the -p option is given, parameters and values are printed in the form of a\ntypeset command with an assignment, regardless of other flags and options.\nNote that the -H flag on parameters is respected; no value will be shown for\nthese parameters.\n\n-p may be followed by an optional integer argument. Currently only the value 1\nis supported. In this case arrays and associative arrays are printed with new‐\nlines between indented elements for readability.\n\n-T [ scalar[=value] array[=(value ...)] [ sep ] ]\nThis flag has a different meaning when used with -f; see below. Otherwise the\n-T option requires zero, two, or three arguments to be present. With no argu‐\nments, the list of parameters created in this fashion is shown. With two or\nthree arguments, the first two are the name of a scalar and of an array parame‐\nter (in that order) that will be tied together in the manner of $PATH and\n$path. The optional third argument is a single-character separator which will\nbe used to join the elements of the array to form the scalar; if absent, a\ncolon is used, as with $PATH. Only the first character of the separator is\nsignificant; any remaining characters are ignored. Multibyte characters are\nnot yet supported.\n\nOnly one of the scalar and array parameters may be assigned an initial value\n(the restrictions on assignment forms described above also apply).\n\nBoth the scalar and the array may be manipulated as normal. If one is unset,\nthe other will automatically be unset too. There is no way of untying the\nvariables without unsetting them, nor of converting the type of one of them\nwith another typeset command; +T does not work, assigning an array to scalar is\nan error, and assigning a scalar to array sets it to be a single-element array.\n\nNote that both `typeset -xT ...' and `export -T ...' work, but only the scalar\nwill be marked for export. Setting the value using the scalar version causes a\nsplit on all separators (which cannot be quoted). It is possible to apply -T\nto two previously tied variables but with a different separator character, in\nwhich case the variables remain joined as before but the separator is changed.\n\nWhen an existing scalar is tied to a new array, the value of the scalar is pre‐\nserved but no attribute other than export will be preserved.\n\nAttribute flags that transform the final value (-L, -R, -Z, -l, -u) are only applied\nto the expanded value at the point of a parameter expansion expression using `$'.\nThey are not applied when a parameter is retrieved internally by the shell for any\npurpose.\n\nThe following attribute flags may be specified:\n\n-A The names refer to associative array parameters; see `Array Parameters' in zsh‐\nparam(1).\n\n-L [ n ]\nLeft justify and remove leading blanks from the value when the parameter is ex‐\npanded. If n is nonzero, it defines the width of the field. If n is zero, the\nwidth is determined by the width of the value of the first assignment. In the\ncase of numeric parameters, the length of the complete value assigned to the\nparameter is used to determine the width, not the value that would be output.\n\nThe width is the count of characters, which may be multibyte characters if the\nMULTIBYTE option is in effect. Note that the screen width of the character is\nnot taken into account; if this is required, use padding with parameter expan‐\nsion flags ${(ml...)...} as described in `Parameter Expansion Flags' in zsh‐\nexpn(1).\n\nWhen the parameter is expanded, it is filled on the right with blanks or trun‐\ncated if necessary to fit the field. Note truncation can lead to unexpected\nresults with numeric parameters. Leading zeros are removed if the -Z flag is\nalso set.\n\n-R [ n ]\nSimilar to -L, except that right justification is used; when the parameter is\nexpanded, the field is left filled with blanks or truncated from the end. May\nnot be combined with the -Z flag.\n\n-U For arrays (but not for associative arrays), keep only the first occurrence of\neach duplicated value. This may also be set for tied parameters (see -T) or\ncolon-separated special parameters like PATH or FIGNORE, etc. Note the flag\ntakes effect on assignment, and the type of the variable being assigned to is\ndeterminative; for variables with shared values it is therefore recommended to\nset the flag for all interfaces, e.g. `typeset -U PATH path'.\n\nThis flag has a different meaning when used with -f; see below.\n\n-Z [ n ]\nSpecially handled if set along with the -L flag. Otherwise, similar to -R, ex‐\ncept that leading zeros are used for padding instead of blanks if the first\nnon-blank character is a digit. Numeric parameters are specially handled: they\nare always eligible for padding with zeroes, and the zeroes are inserted at an\nappropriate place in the output.\n\n-a The names refer to array parameters. An array parameter may be created this\nway, but it may be assigned to in the typeset statement only if the reserved\nword form of typeset is enabled (as it is by default). When displaying, both\nnormal and associative arrays are shown.\n\n-f The names refer to functions rather than parameters. No assignments can be\nmade, and the only other valid flags are -t, -T, -k, -u, -U and -z. The flag\n-t turns on execution tracing for this function; the flag -T does the same, but\nturns off tracing for any named (not anonymous) function called from the\npresent one, unless that function also has the -t or -T flag. The -u and -U\nflags cause the function to be marked for autoloading; -U also causes alias ex‐\npansion to be suppressed when the function is loaded. See the description of\nthe `autoload' builtin for details.\n\nNote that the builtin functions provides the same basic capabilities as typeset\n-f but gives access to a few extra options; autoload gives further additional\noptions for the case typeset -fu and typeset -fU.\n\n-h Hide: only useful for special parameters (those marked `' in the table in\nzshparam(1)), and for local parameters with the same name as a special parame‐\nter, though harmless for others. A special parameter with this attribute will\nnot retain its special effect when made local. Thus after `typeset -h PATH', a\nfunction containing `typeset PATH' will create an ordinary local parameter\nwithout the usual behaviour of PATH. Alternatively, the local parameter may\nitself be given this attribute; hence inside a function `typeset -h PATH' cre‐\nates an ordinary local parameter and the special PATH parameter is not altered\nin any way. It is also possible to create a local parameter using `typeset +h\nspecial', where the local copy of special will retain its special properties\nregardless of having the -h attribute. Global special parameters loaded from\nshell modules (currently those in zsh/mapfile and zsh/parameter) are automati‐\ncally given the -h attribute to avoid name clashes.\n\n-H Hide value: specifies that typeset will not display the value of the parameter\nwhen listing parameters; the display for such parameters is always as if the\n`+' flag had been given. Use of the parameter is in other respects normal, and\nthe option does not apply if the parameter is specified by name, or by pattern\nwith the -m option. This is on by default for the parameters in the zsh/param‐‐\neter and zsh/mapfile modules. Note, however, that unlike the -h flag this is\nalso useful for non-special parameters.\n\n-i [ n ]\nUse an internal integer representation. If n is nonzero it defines the output\narithmetic base, otherwise it is determined by the first assignment. Bases\nfrom 2 to 36 inclusive are allowed.\n\n-E [ n ]\nUse an internal double-precision floating point representation. On output the\nvariable will be converted to scientific notation. If n is nonzero it defines\nthe number of significant figures to display; the default is ten.\n\n-F [ n ]\nUse an internal double-precision floating point representation. On output the\nvariable will be converted to fixed-point decimal notation. If n is nonzero it\ndefines the number of digits to display after the decimal point; the default is\nten.\n\n-l Convert the result to lower case whenever the parameter is expanded. The value\nis not converted when assigned.\n\n-r The given names are marked readonly. Note that if name is a special parameter,\nthe readonly attribute can be turned on, but cannot then be turned off.\n\nIf the POSIXBUILTINS option is set, the readonly attribute is more restric‐\ntive: unset variables can be marked readonly and cannot then be set; further‐\nmore, the readonly attribute cannot be removed from any variable.\n\nIt is still possible to change other attributes of the variable though, some of\nwhich like -U or -Z would affect the value. More generally, the readonly attri‐\nbute should not be relied on as a security mechanism.\n\nNote that in zsh (like in pdksh but unlike most other shells) it is still pos‐\nsible to create a local variable of the same name as this is considered a dif‐\nferent variable (though this variable, too, can be marked readonly). Special\nvariables that have been made readonly retain their value and readonly attri‐\nbute when made local.\n\n-t Tags the named parameters. Tags have no special meaning to the shell. This\nflag has a different meaning when used with -f; see above.\n\n-u Convert the result to upper case whenever the parameter is expanded. The value\nis not converted when assigned. This flag has a different meaning when used\nwith -f; see above.\n\n-x Mark for automatic export to the environment of subsequently executed commands.\nIf the option GLOBALEXPORT is set, this implies the option -g, unless +g is\nalso explicitly given; in other words the parameter is not made local to the\nenclosing function. This is for compatibility with previous versions of zsh.\n\nulimit [ -HSa ] [ { -bcdfiklmnpqrsTtvwx | -N resource } [ limit ] ... ]\nSet or display resource limits of the shell and the processes started by the shell.\nThe value of limit can be a number in the unit specified below or one of the values\n`unlimited', which removes the limit on the resource, or `hard', which uses the cur‐\nrent value of the hard limit on the resource.\n\nBy default, only soft limits are manipulated. If the -H flag is given use hard limits\ninstead of soft limits. If the -S flag is given together with the -H flag set both\nhard and soft limits.\n\nIf no options are used, the file size limit (-f) is assumed.\n\nIf limit is omitted the current value of the specified resources are printed. When\nmore than one resource value is printed, the limit name and unit is printed before\neach value.\n\nWhen looping over multiple resources, the shell will abort immediately if it detects a\nbadly formed argument. However, if it fails to set a limit for some other reason it\nwill continue trying to set the remaining limits.\n\nNot all the following resources are supported on all systems. Running ulimit -a will\nshow which are supported.\n\n-a Lists all of the current resource limits.\n-b Socket buffer size in bytes (N.B. not kilobytes)\n-c 512-byte blocks on the size of core dumps.\n-d Kilobytes on the size of the data segment.\n-f 512-byte blocks on the size of files written.\n-i The number of pending signals.\n-k The number of kqueues allocated.\n-l Kilobytes on the size of locked-in memory.\n-m Kilobytes on the size of physical memory.\n-n open file descriptors.\n-p The number of pseudo-terminals.\n-q Bytes in POSIX message queues.\n-r Maximum real time priority. On some systems where this is not available, such\nas NetBSD, this has the same effect as -T for compatibility with sh.\n-s Kilobytes on the size of the stack.\n-T The number of simultaneous threads available to the user.\n-t CPU seconds to be used.\n-u The number of processes available to the user.\n-v Kilobytes on the size of virtual memory. On some systems this refers to the\nlimit called `address space'.\n-w Kilobytes on the size of swapped out memory.\n-x The number of locks on files.\n\nA resource may also be specified by integer in the form `-N resource', where resource\ncorresponds to the integer defined for the resource by the operating system. This may\nbe used to set the limits for resources known to the shell which do not correspond to\noption letters. Such limits will be shown by number in the output of `ulimit -a'.\n\nThe number may alternatively be out of the range of limits compiled into the shell.\nThe shell will try to read or write the limit anyway, and will report an error if this\nfails.\n\numask [ -S ] [ mask ]\nThe umask is set to mask. mask can be either an octal number or a symbolic value as\ndescribed in chmod(1). If mask is omitted, the current value is printed. The -S op‐\ntion causes the mask to be printed as a symbolic value. Otherwise, the mask is\nprinted as an octal number. Note that in the symbolic form the permissions you spec‐\nify are those which are to be allowed (not denied) to the users specified.\n\nunalias [ -ams ] name ...\nRemoves aliases. This command works the same as unhash -a, except that the -a option\nremoves all regular or global aliases, or with -s all suffix aliases: in this case no\nname arguments may appear. The options -m (remove by pattern) and -s without -a (re‐\nmove listed suffix aliases) behave as for unhash -a. Note that the meaning of -a is\ndifferent between unalias and unhash.\n" }, { "name": "unfunction", "content": "Same as unhash -f.\n\nunhash [ -adfms ] name ...\nRemove the element named name from an internal hash table. The default is remove ele‐\nments from the command hash table. The -a option causes unhash to remove regular or\nglobal aliases; note when removing a global aliases that the argument must be quoted\nto prevent it from being expanded before being passed to the command. The -s option\ncauses unhash to remove suffix aliases. The -f option causes unhash to remove shell\nfunctions. The -d options causes unhash to remove named directories. If the -m flag\nis given the arguments are taken as patterns (should be quoted) and all elements of\nthe corresponding hash table with matching names will be removed.\n\nunlimit [ -hs ] resource ...\nThe resource limit for each resource is set to the hard limit. If the -h flag is\ngiven and the shell has appropriate privileges, the hard resource limit for each re‐\nsource is removed. The resources of the shell process are only changed if the -s flag\nis given.\n\nThe unlimit command is not made available by default when the shell starts in a mode\nemulating another shell. It can be made available with the command `zmodload -F\nzsh/rlimits b:unlimit'.\n\nunset [ -fmv ] name ...\nEach named parameter is unset. Local parameters remain local even if unset; they ap‐\npear unset within scope, but the previous value will still reappear when the scope\nends.\n\nIndividual elements of associative array parameters may be unset by using subscript\nsyntax on name, which should be quoted (or the entire command prefixed with noglob) to\nprotect the subscript from filename generation.\n\nIf the -m flag is specified the arguments are taken as patterns (should be quoted) and\nall parameters with matching names are unset. Note that this cannot be used when un‐\nsetting associative array elements, as the subscript will be treated as part of the\npattern.\n\nThe -v flag specifies that name refers to parameters. This is the default behaviour.\n\nunset -f is equivalent to unfunction.\n\nunsetopt [ {+|-}options | {+|-}o optionname ] [ name ... ]\nUnset the options for the shell. All options specified either with flags or by name\nare unset. If no arguments are supplied, the names of all options currently unset are\nprinted. If the -m flag is given the arguments are taken as patterns (which should be\nquoted to preserve them from being interpreted as glob patterns), and all options with\nnames matching these patterns are unset.\n\nvared See the section `Zle Builtins' in zshzle(1).\n\nwait [ job ... ]\nWait for the specified jobs or processes. If job is not given then all currently ac‐\ntive child processes are waited for. Each job can be either a job specification or\nthe process ID of a job in the job table. The exit status from this command is that\nof the job waited for. If job represents an unknown job or process ID, a warning is\nprinted (unless the POSIXBUILTINS option is set) and the exit status is 127.\n\nIt is possible to wait for recent processes (specified by process ID, not by job) that\nwere running in the background even if the process has exited. Typically the process\nID will be recorded by capturing the value of the variable $! immediately after the\nprocess has been started. There is a limit on the number of process IDs remembered by\nthe shell; this is given by the value of the system configuration parameter CHILDMAX.\nWhen this limit is reached, older process IDs are discarded, least recently started\nprocesses first.\n\nNote there is no protection against the process ID wrapping, i.e. if the wait is not\nexecuted soon enough there is a chance the process waited for is the wrong one. A\nconflict implies both process IDs have been generated by the shell, as other processes\nare not recorded, and that the user is potentially interested in both, so this problem\nis intrinsic to process IDs.\n\nwhence [ -vcwfpamsS ] [ -x num ] name ...\nFor each name, indicate how it would be interpreted if used as a command name.\n\nIf name is not an alias, built-in command, external command, shell function, hashed\ncommand, or a reserved word, the exit status shall be non-zero, and -- if -v, -c, or\n-w was passed -- a message will be written to standard output. (This is different\nfrom other shells that write that message to standard error.)\n\nwhence is most useful when name is only the last path component of a command, i.e.\ndoes not include a `/'; in particular, pattern matching only succeeds if just the\nnon-directory component of the command is passed.\n\n-v Produce a more verbose report.\n\n-c Print the results in a csh-like format. This takes precedence over -v.\n\n-w For each name, print `name: word' where word is one of alias, builtin, command,\nfunction, hashed, reserved or none, according as name corresponds to an alias,\na built-in command, an external command, a shell function, a command defined\nwith the hash builtin, a reserved word, or is not recognised. This takes\nprecedence over -v and -c.\n\n-f Causes the contents of a shell function to be displayed, which would otherwise\nnot happen unless the -c flag were used.\n\n-p Do a path search for name even if it is an alias, reserved word, shell function\nor builtin.\n\n-a Do a search for all occurrences of name throughout the command path. Normally\nonly the first occurrence is printed.\n\n-m The arguments are taken as patterns (pattern characters should be quoted), and\nthe information is displayed for each command matching one of these patterns.\n\n-s If a pathname contains symlinks, print the symlink-free pathname as well.\n\n-S As -s, but if the pathname had to be resolved by following multiple symlinks,\nthe intermediate steps are printed, too. The symlink resolved at each step\nmight be anywhere in the path.\n\n-x num Expand tabs when outputting shell functions using the -c option. This has the\nsame effect as the -x option to the functions builtin.\n\nwhere [ -wpmsS ] [ -x num ] name ...\nEquivalent to whence -ca.\n\nwhich [ -wpamsS ] [ -x num ] name ...\nEquivalent to whence -c.\n\nzcompile [ -U ] [ -z | -k ] [ -R | -M ] file [ name ... ]\nzcompile -ca [ -m ] [ -R | -M ] file [ name ... ]\nzcompile -t file [ name ... ]\nThis builtin command can be used to compile functions or scripts, storing the compiled\nform in a file, and to examine files containing the compiled form. This allows faster\nautoloading of functions and sourcing of scripts by avoiding parsing of the text when\nthe files are read.\n\nThe first form (without the -c, -a or -t options) creates a compiled file. If only\nthe file argument is given, the output file has the name `file.zwc' and will be placed\nin the same directory as the file. The shell will load the compiled file instead of\nthe normal function file when the function is autoloaded; see the section `Autoloading\nFunctions' in zshmisc(1) for a description of how autoloaded functions are searched.\nThe extension .zwc stands for `zsh word code'.\n\nIf there is at least one name argument, all the named files are compiled into the out‐\nput file given as the first argument. If file does not end in .zwc, this extension is\nautomatically appended. Files containing multiple compiled functions are called `di‐\ngest' files, and are intended to be used as elements of the FPATH/fpath special array.\n\nThe second form, with the -c or -a options, writes the compiled definitions for all\nthe named functions into file. For -c, the names must be functions currently defined\nin the shell, not those marked for autoloading. Undefined functions that are marked\nfor autoloading may be written by using the -a option, in which case the fpath is\nsearched and the contents of the definition files for those functions, if found, are\ncompiled into file. If both -c and -a are given, names of both defined functions and\nfunctions marked for autoloading may be given. In either case, the functions in files\nwritten with the -c or -a option will be autoloaded as if the KSHAUTOLOAD option were\nunset.\n\nThe reason for handling loaded and not-yet-loaded functions with different options is\nthat some definition files for autoloading define multiple functions, including the\nfunction with the same name as the file, and, at the end, call that function. In such\ncases the output of `zcompile -c' does not include the additional functions defined in\nthe file, and any other initialization code in the file is lost. Using `zcompile -a'\ncaptures all this extra information.\n\nIf the -m option is combined with -c or -a, the names are used as patterns and all\nfunctions whose names match one of these patterns will be written. If no name is\ngiven, the definitions of all functions currently defined or marked as autoloaded will\nbe written.\n\nNote the second form cannot be used for compiling functions that include redirections\nas part of the definition rather than within the body of the function; for example\n\nfn1() { { ... } >~/logfile }\n\ncan be compiled but\n\nfn1() { ... } >~/logfile\n\ncannot. It is possible to use the first form of zcompile to compile autoloadable\nfunctions that include the full function definition instead of just the body of the\nfunction.\n\nThe third form, with the -t option, examines an existing compiled file. Without fur‐\nther arguments, the names of the original files compiled into it are listed. The\nfirst line of output shows the version of the shell which compiled the file and how\nthe file will be used (i.e. by reading it directly or by mapping it into memory).\nWith arguments, nothing is output and the return status is set to zero if definitions\nfor all names were found in the compiled file, and non-zero if the definition for at\nleast one name was not found.\n\nOther options:\n\n-U Aliases are not expanded when compiling the named files.\n\n-R When the compiled file is read, its contents are copied into the shell's mem‐\nory, rather than memory-mapped (see -M). This happens automatically on systems\nthat do not support memory mapping.\n\nWhen compiling scripts instead of autoloadable functions, it is often desirable\nto use this option; otherwise the whole file, including the code to define\nfunctions which have already been defined, will remain mapped, consequently\nwasting memory.\n\n-M The compiled file is mapped into the shell's memory when read. This is done in\nsuch a way that multiple instances of the shell running on the same host will\nshare this mapped file. If neither -R nor -M is given, the zcompile builtin\ndecides what to do based on the size of the compiled file.\n\n-k\n-z These options are used when the compiled file contains functions which are to\nbe autoloaded. If -z is given, the function will be autoloaded as if the\nKSHAUTOLOAD option is not set, even if it is set at the time the compiled file\nis read, while if the -k is given, the function will be loaded as if KSHAU‐‐\nTOLOAD is set. These options also take precedence over any -k or -z options\nspecified to the autoload builtin. If neither of these options is given, the\nfunction will be loaded as determined by the setting of the KSHAUTOLOAD option\nat the time the compiled file is read.\n\nThese options may also appear as many times as necessary between the listed\nnames to specify the loading style of all following functions, up to the next\n-k or -z.\n\nThe created file always contains two versions of the compiled format, one for\nbig-endian machines and one for small-endian machines. The upshot of this is\nthat the compiled file is machine independent and if it is read or mapped, only\none half of the file is actually used (and mapped).\n" }, { "name": "zformat", "content": "See the section `The zsh/zutil Module' in zshmodules(1).\n\nzftp See the section `The zsh/zftp Module' in zshmodules(1).\n\nzle See the section `Zle Builtins' in zshzle(1).\n\nzmodload [ -dL ] [ -s ] [ ... ]\nzmodload -F [ -alLme -P param ] module [ [+-]feature ... ]\nzmodload -e [ -A ] [ ... ]\nzmodload [ -a [ -bcpf [ -I ] ] ] [ -iL ] ...\nzmodload -u [ -abcdpf [ -I ] ] [ -iL ] ...\nzmodload -A [ -L ] [ modalias[=module] ... ]\nzmodload -R modalias ...\nPerforms operations relating to zsh's loadable modules. Loading of modules while the\nshell is running (`dynamical loading') is not available on all operating systems, or\non all installations on a particular operating system, although the zmodload command\nitself is always available and can be used to manipulate modules built into versions\nof the shell executable without dynamical loading.\n\nWithout arguments the names of all currently loaded binary modules are printed. The\n-L option causes this list to be in the form of a series of zmodload commands. Forms\nwith arguments are:\n\nzmodload [ -is ] name ...\nzmodload -u [ -i ] name ...\nIn the simplest case, zmodload loads a binary module. The module must be in a\nfile with a name consisting of the specified name followed by a standard suf‐\nfix, usually `.so' (`.sl' on HPUX). If the module to be loaded is already\nloaded the duplicate module is ignored. If zmodload detects an inconsistency,\nsuch as an invalid module name or circular dependency list, the current code\nblock is aborted. If it is available, the module is loaded if necessary, while\nif it is not available, non-zero status is silently returned. The option -i is\naccepted for compatibility but has no effect.\n\nThe named module is searched for in the same way a command is, using $mod‐‐\nulepath instead of $path. However, the path search is performed even when the\nmodule name contains a `/', which it usually does. There is no way to prevent\nthe path search.\n\nIf the module supports features (see below), zmodload tries to enable all fea‐\ntures when loading a module. If the module was successfully loaded but not all\nfeatures could be enabled, zmodload returns status 2.\n\nIf the option -s is given, no error is printed if the module was not available\n(though other errors indicating a problem with the module are printed). The\nreturn status indicates if the module was loaded. This is appropriate if the\ncaller considers the module optional.\n\nWith -u, zmodload unloads modules. The same name must be given that was given\nwhen the module was loaded, but it is not necessary for the module to exist in\nthe file system. The -i option suppresses the error if the module is already\nunloaded (or was never loaded).\n\nEach module has a boot and a cleanup function. The module will not be loaded\nif its boot function fails. Similarly a module can only be unloaded if its\ncleanup function runs successfully.\n\nzmodload -F [ -almLe -P param ] module [ [+-]feature ... ]\nzmodload -F allows more selective control over the features provided by mod‐\nules. With no options apart from -F, the module named module is loaded, if it\nwas not already loaded, and the list of features is set to the required state.\nIf no features are specified, the module is loaded, if it was not already\nloaded, but the state of features is unchanged. Each feature may be preceded\nby a + to turn the feature on, or - to turn it off; the + is assumed if neither\ncharacter is present. Any feature not explicitly mentioned is left in its cur‐\nrent state; if the module was not previously loaded this means any such fea‐\ntures will remain disabled. The return status is zero if all features were\nset, 1 if the module failed to load, and 2 if some features could not be set\n(for example, a parameter couldn't be added because there was a different pa‐\nrameter of the same name) but the module was loaded.\n\nThe standard features are builtins, conditions, parameters and math functions;\nthese are indicated by the prefix `b:', `c:' (`C:' for an infix condition),\n`p:' and `f:', respectively, followed by the name that the corresponding fea‐\nture would have in the shell. For example, `b:strftime' indicates a builtin\nnamed strftime and p:EPOCHSECONDS indicates a parameter named EPOCHSECONDS.\nThe module may provide other (`abstract') features of its own as indicated by\nits documentation; these have no prefix.\n\nWith -l or -L, features provided by the module are listed. With -l alone, a\nlist of features together with their states is shown, one feature per line.\nWith -L alone, a zmodload -F command that would cause enabled features of the\nmodule to be turned on is shown. With -lL, a zmodload -F command that would\ncause all the features to be set to their current state is shown. If one of\nthese combinations is given with the option -P param then the parameter param\nis set to an array of features, either features together with their state or\n(if -L alone is given) enabled features.\n\nWith the option -L the module name may be omitted; then a list of all enabled\nfeatures for all modules providing features is printed in the form of zmodload\n-F commands. If -l is also given, the state of both enabled and disabled fea‐\ntures is output in that form.\n\nA set of features may be provided together with -l or -L and a module name; in\nthat case only the state of those features is considered. Each feature may be\npreceded by + or - but the character has no effect. If no set of features is\nprovided, all features are considered.\n\nWith -e, the command first tests that the module is loaded; if it is not, sta‐\ntus 1 is returned. If the module is loaded, the list of features given as an\nargument is examined. Any feature given with no prefix is simply tested to see\nif the module provides it; any feature given with a prefix + or - is tested to\nsee if is provided and in the given state. If the tests on all features in the\nlist succeed, status 0 is returned, else status 1.\n\nWith -m, each entry in the given list of features is taken as a pattern to be\nmatched against the list of features provided by the module. An initial + or -\nmust be given explicitly. This may not be combined with the -a option as au‐\ntoloads must be specified explicitly.\n\nWith -a, the given list of features is marked for autoload from the specified\nmodule, which may not yet be loaded. An optional + may appear before the fea‐\nture name. If the feature is prefixed with -, any existing autoload is re‐\nmoved. The options -l and -L may be used to list autoloads. Autoloading is\nspecific to individual features; when the module is loaded only the requested\nfeature is enabled. Autoload requests are preserved if the module is subse‐\nquently unloaded until an explicit `zmodload -Fa module -feature' is issued.\nIt is not an error to request an autoload for a feature of a module that is al‐\nready loaded.\n\nWhen the module is loaded each autoload is checked against the features actu‐\nally provided by the module; if the feature is not provided the autoload re‐\nquest is deleted. A warning message is output; if the module is being loaded\nto provide a different feature, and that autoload is successful, there is no\neffect on the status of the current command. If the module is already loaded\nat the time when zmodload -Fa is run, an error message is printed and status 1\nreturned.\n\nzmodload -Fa can be used with the -l, -L, -e and -P options for listing and\ntesting the existence of autoloadable features. In this case -l is ignored if\n-L is specified. zmodload -FaL with no module name lists autoloads for all\nmodules.\n\nNote that only standard features as described above can be autoloaded; other\nfeatures require the module to be loaded before enabling.\n\nzmodload -d [ -L ] [ name ]\nzmodload -d name dep ...\nzmodload -ud name [ dep ... ]\nThe -d option can be used to specify module dependencies. The modules named in\nthe second and subsequent arguments will be loaded before the module named in\nthe first argument.\n\nWith -d and one argument, all dependencies for that module are listed. With -d\nand no arguments, all module dependencies are listed. This listing is by de‐\nfault in a Makefile-like format. The -L option changes this format to a list\nof zmodload -d commands.\n\nIf -d and -u are both used, dependencies are removed. If only one argument is\ngiven, all dependencies for that module are removed.\n\nzmodload -ab [ -L ]\nzmodload -ab [ -i ] name [ builtin ... ]\nzmodload -ub [ -i ] builtin ...\nThe -ab option defines autoloaded builtins. It defines the specified builtins.\nWhen any of those builtins is called, the module specified in the first argu‐\nment is loaded and all its features are enabled (for selective control of fea‐\ntures use `zmodload -F -a' as described above). If only the name is given, one\nbuiltin is defined, with the same name as the module. -i suppresses the error\nif the builtin is already defined or autoloaded, but not if another builtin of\nthe same name is already defined.\n\nWith -ab and no arguments, all autoloaded builtins are listed, with the module\nname (if different) shown in parentheses after the builtin name. The -L option\nchanges this format to a list of zmodload -a commands.\n\nIf -b is used together with the -u option, it removes builtins previously de‐\nfined with -ab. This is only possible if the builtin is not yet loaded. -i\nsuppresses the error if the builtin is already removed (or never existed).\n\nAutoload requests are retained if the module is subsequently unloaded until an\nexplicit `zmodload -ub builtin' is issued.\n\nzmodload -ac [ -IL ]\nzmodload -ac [ -iI ] name [ cond ... ]\nzmodload -uc [ -iI ] cond ...\nThe -ac option is used to define autoloaded condition codes. The cond strings\ngive the names of the conditions defined by the module. The optional -I option\nis used to define infix condition names. Without this option prefix condition\nnames are defined.\n\nIf given no condition names, all defined names are listed (as a series of zmod‐‐\nload commands if the -L option is given).\n\nThe -uc option removes definitions for autoloaded conditions.\n\nzmodload -ap [ -L ]\nzmodload -ap [ -i ] name [ parameter ... ]\nzmodload -up [ -i ] parameter ...\nThe -p option is like the -b and -c options, but makes zmodload work on au‐\ntoloaded parameters instead.\n\nzmodload -af [ -L ]\nzmodload -af [ -i ] name [ function ... ]\nzmodload -uf [ -i ] function ...\nThe -f option is like the -b, -p, and -c options, but makes zmodload work on\nautoloaded math functions instead.\n\nzmodload -a [ -L ]\nzmodload -a [ -i ] name [ builtin ... ]\nzmodload -ua [ -i ] builtin ...\nEquivalent to -ab and -ub.\n\nzmodload -e [ -A ] [ string ... ]\nThe -e option without arguments lists all loaded modules; if the -A option is\nalso given, module aliases corresponding to loaded modules are also shown. If\narguments are provided, nothing is printed; the return status is set to zero if\nall strings given as arguments are names of loaded modules and to one if at\nleast on string is not the name of a loaded module. This can be used to test\nfor the availability of things implemented by modules. In this case, any\naliases are automatically resolved and the -A flag is not used.\n\nzmodload -A [ -L ] [ modalias[=module] ... ]\nFor each argument, if both modalias and module are given, define modalias to be\nan alias for the module module. If the module modalias is ever subsequently\nrequested, either via a call to zmodload or implicitly, the shell will attempt\nto load module instead. If module is not given, show the definition of\nmodalias. If no arguments are given, list all defined module aliases. When\nlisting, if the -L flag was also given, list the definition as a zmodload com‐\nmand to recreate the alias.\n\nThe existence of aliases for modules is completely independent of whether the\nname resolved is actually loaded as a module: while the alias exists, loading\nand unloading the module under any alias has exactly the same effect as using\nthe resolved name, and does not affect the connection between the alias and the\nresolved name which can be removed either by zmodload -R or by redefining the\nalias. Chains of aliases (i.e. where the first resolved name is itself an\nalias) are valid so long as these are not circular. As the aliases take the\nsame format as module names, they may include path separators: in this case,\nthere is no requirement for any part of the path named to exist as the alias\nwill be resolved first. For example, `any/old/alias' is always a valid alias.\n\nDependencies added to aliased modules are actually added to the resolved mod‐\nule; these remain if the alias is removed. It is valid to create an alias\nwhose name is one of the standard shell modules and which resolves to a differ‐\nent module. However, if a module has dependencies, it will not be possible to\nuse the module name as an alias as the module will already be marked as a load‐\nable module in its own right.\n\nApart from the above, aliases can be used in the zmodload command anywhere mod‐\nule names are required. However, aliases will not be shown in lists of loaded\nmodules with a bare `zmodload'.\n\nzmodload -R modalias ...\nFor each modalias argument that was previously defined as a module alias via\nzmodload -A, delete the alias. If any was not defined, an error is caused and\nthe remainder of the line is ignored.\n\nNote that zsh makes no distinction between modules that were linked into the shell and\nmodules that are loaded dynamically. In both cases this builtin command has to be used\nto make available the builtins and other things defined by modules (unless the module\nis autoloaded on these definitions). This is true even for systems that don't support\ndynamic loading of modules.\n" }, { "name": "zparseopts", "content": "See the section `The zsh/zutil Module' in zshmodules(1).\n\nzprof See the section `The zsh/zprof Module' in zshmodules(1).\n\nzpty See the section `The zsh/zpty Module' in zshmodules(1).\n" }, { "name": "zregexparse", "content": "See the section `The zsh/zutil Module' in zshmodules(1).\n" }, { "name": "zsocket", "content": "See the section `The zsh/net/socket Module' in zshmodules(1).\n\nzstyle See the section `The zsh/zutil Module' in zshmodules(1).\n\nztcp See the section `The zsh/net/tcp Module' in zshmodules(1).\n\n\n\nZSHZLE(1) General Commands Manual ZSHZLE(1)\n\n\n" } ] }, "KEYMAPS": { "content": "A keymap in ZLE contains a set of bindings between key sequences and ZLE commands. The empty\nkey sequence cannot be bound.\n\nThere can be any number of keymaps at any time, and each keymap has one or more names. If\nall of a keymap's names are deleted, it disappears. bindkey can be used to manipulate keymap\nnames.\n\nInitially, there are eight keymaps:\n\nemacs EMACS emulation\nviins vi emulation - insert mode\nvicmd vi emulation - command mode\nviopp vi emulation - operator pending\nvisual vi emulation - selection active", "subsections": [ { "name": "isearch", "content": "incremental search mode" }, { "name": "command", "content": "read a command name\n.safe fallback keymap\n\nThe `.safe' keymap is special. It can never be altered, and the name can never be removed.\nHowever, it can be linked to other names, which can be removed. In the future other special\nkeymaps may be added; users should avoid using names beginning with `.' for their own\nkeymaps.\n\nIn addition to these names, either `emacs' or `viins' is also linked to the name `main'. If\none of the VISUAL or EDITOR environment variables contain the string `vi' when the shell\nstarts up then it will be `viins', otherwise it will be `emacs'. bindkey's -e and -v options\nprovide a convenient way to override this default choice.\n\nWhen the editor starts up, it will select the `main' keymap. If that keymap doesn't exist,\nit will use `.safe' instead.\n\nIn the `.safe' keymap, each single key is bound to self-insert, except for ^J (line feed) and\n^M (return) which are bound to accept-line. This is deliberately not pleasant to use; if you\nare using it, it means you deleted the main keymap, and you should put it back.\n" }, { "name": "Reading Commands", "content": "When ZLE is reading a command from the terminal, it may read a sequence that is bound to some\ncommand and is also a prefix of a longer bound string. In this case ZLE will wait a certain\ntime to see if more characters are typed, and if not (or they don't match any longer string)\nit will execute the binding. This timeout is defined by the KEYTIMEOUT parameter; its de‐\nfault is 0.4 sec. There is no timeout if the prefix string is not itself bound to a command.\n\nThe key timeout is also applied when ZLE is reading the bytes from a multibyte character\nstring when it is in the appropriate mode. (This requires that the shell was compiled with\nmultibyte mode enabled; typically also the locale has characters with the UTF-8 encoding, al‐\nthough any multibyte encoding known to the operating system is supported.) If the second or\na subsequent byte is not read within the timeout period, the shell acts as if ? were typed\nand resets the input state.\n\nAs well as ZLE commands, key sequences can be bound to other strings, by using `bindkey -s'.\nWhen such a sequence is read, the replacement string is pushed back as input, and the command\nreading process starts again using these fake keystrokes. This input can itself invoke fur‐\nther replacement strings, but in order to detect loops the process will be stopped if there\nare twenty such replacements without a real command being read.\n\nA key sequence typed by the user can be turned into a command name for use in user-defined\nwidgets with the read-command widget, described in the subsection `Miscellaneous' of the sec‐\ntion `Standard Widgets' below.\n" }, { "name": "Local Keymaps", "content": "While for normal editing a single keymap is used exclusively, in many modes a local keymap\nallows for some keys to be customised. For example, in an incremental search mode, a binding\nin the isearch keymap will override a binding in the main keymap but all keys that are not\noverridden can still be used.\n\nIf a key sequence is defined in a local keymap, it will hide a key sequence in the global\nkeymap that is a prefix of that sequence. An example of this occurs with the binding of iw in\nviopp as this hides the binding of i in vicmd. However, a longer sequence in the global\nkeymap that shares the same prefix can still apply so for example the binding of ^Xa in the\nglobal keymap will be unaffected by the binding of ^Xb in the local keymap.\n" } ] }, "ZLE BUILTINS": { "content": "The ZLE module contains three related builtin commands. The bindkey command manipulates\nkeymaps and key bindings; the vared command invokes ZLE on the value of a shell parameter;\nand the zle command manipulates editing widgets and allows command line access to ZLE com‐\nmands from within shell functions.\n\nbindkey [ options ] -l [ -L ] [ keymap ... ]\nbindkey [ options ] -d\nbindkey [ options ] -D keymap ...\nbindkey [ options ] -A old-keymap new-keymap\nbindkey [ options ] -N new-keymap [ old-keymap ]\nbindkey [ options ] -m\nbindkey [ options ] -r in-string ...\nbindkey [ options ] -s in-string out-string ...\nbindkey [ options ] in-string command ...\nbindkey [ options ] [ in-string ]\nbindkey's options can be divided into three categories: keymap selection for the cur‐\nrent command, operation selection, and others. The keymap selection options are:\n\n-e Selects keymap `emacs' for any operations by the current command, and also\nlinks `emacs' to `main' so that it is selected by default the next time the ed‐\nitor starts.\n\n-v Selects keymap `viins' for any operations by the current command, and also\nlinks `viins' to `main' so that it is selected by default the next time the ed‐\nitor starts.\n\n-a Selects keymap `vicmd' for any operations by the current command.\n\n-M keymap\nThe keymap specifies a keymap name that is selected for any operations by the\ncurrent command.\n\nIf a keymap selection is required and none of the options above are used, the `main'\nkeymap is used. Some operations do not permit a keymap to be selected, namely:\n\n-l List all existing keymap names; if any arguments are given, list just those\nkeymaps.\n\nIf the -L option is also used, list in the form of bindkey commands to create\nor link the keymaps. `bindkey -lL main' shows which keymap is linked to\n`main', if any, and hence if the standard emacs or vi emulation is in effect.\nThis option does not show the .safe keymap because it cannot be created in that\nfashion; however, neither is `bindkey -lL .safe' reported as an error, it sim‐\nply outputs nothing.\n\n-d Delete all existing keymaps and reset to the default state.\n\n-D keymap ...\nDelete the named keymaps.\n\n-A old-keymap new-keymap\nMake the new-keymap name an alias for old-keymap, so that both names refer to\nthe same keymap. The names have equal standing; if either is deleted, the\nother remains. If there is already a keymap with the new-keymap name, it is\ndeleted.\n\n-N new-keymap [ old-keymap ]\nCreate a new keymap, named new-keymap. If a keymap already has that name, it\nis deleted. If an old-keymap name is given, the new keymap is initialized to\nbe a duplicate of it, otherwise the new keymap will be empty.\n\nTo use a newly created keymap, it should be linked to main. Hence the sequence of\ncommands to create and use a new keymap `mymap' initialized from the emacs keymap\n(which remains unchanged) is:\n\nbindkey -N mymap emacs\nbindkey -A mymap main\n\nNote that while `bindkey -A newmap main' will work when newmap is emacs or viins, it\nwill not work for vicmd, as switching from vi insert to command mode becomes impossi‐\nble.\n\nThe following operations act on the `main' keymap if no keymap selection option was\ngiven:\n\n-m Add the built-in set of meta-key bindings to the selected keymap. Only keys\nthat are unbound or bound to self-insert are affected.\n\n-r in-string ...\nUnbind the specified in-strings in the selected keymap. This is exactly equiv‐\nalent to binding the strings to undefined-key.\n\nWhen -R is also used, interpret the in-strings as ranges.\n\nWhen -p is also used, the in-strings specify prefixes. Any binding that has\nthe given in-string as a prefix, not including the binding for the in-string\nitself, if any, will be removed. For example,\n\nbindkey -rpM viins '^['\n\nwill remove all bindings in the vi-insert keymap beginning with an escape char‐\nacter (probably cursor keys), but leave the binding for the escape character\nitself (probably vi-cmd-mode). This is incompatible with the option -R.\n\n-s in-string out-string ...\nBind each in-string to each out-string. When in-string is typed, out-string\nwill be pushed back and treated as input to the line editor. When -R is also\nused, interpret the in-strings as ranges.\n\nNote that both in-string and out-string are subject to the same form of inter‐\npretation, as described below.\n\nin-string command ...\nBind each in-string to each command. When -R is used, interpret the in-strings\nas ranges.\n\n[ in-string ]\nList key bindings. If an in-string is specified, the binding of that string in\nthe selected keymap is displayed. Otherwise, all key bindings in the selected\nkeymap are displayed. (As a special case, if the -e or -v option is used\nalone, the keymap is not displayed - the implicit linking of keymaps is the\nonly thing that happens.)\n\nWhen the option -p is used, the in-string must be present. The listing shows\nall bindings which have the given key sequence as a prefix, not including any\nbindings for the key sequence itself.\n\nWhen the -L option is used, the list is in the form of bindkey commands to cre‐\nate the key bindings.\n\nWhen the -R option is used as noted above, a valid range consists of two characters,\nwith an optional `-' between them. All characters between the two specified, inclu‐\nsive, are bound as specified.\n\nFor either in-string or out-string, the following escape sequences are recognised:\n\n\\a bell character\n\\b backspace\n\\e, \\E escape\n\\f form feed\n\\n linefeed (newline)\n\\r carriage return\n\\t horizontal tab\n\\v vertical tab\n\\NNN character code in octal\n\\xNN character code in hexadecimal\n\\uNNNN unicode character code in hexadecimal\n\\UNNNNNNNN\nunicode character code in hexadecimal\n\\M[-]X character with meta bit set\n\\C[-]X control character\n^X control character\n\nIn all other cases, `\\' escapes the following character. Delete is written as `^?'.\nNote that `\\M^?' and `^\\M?' are not the same, and that (unlike emacs), the bindings\n`\\M-X' and `\\eX' are entirely distinct, although they are initialized to the same\nbindings by `bindkey -m'.\n\n\nvared [ -Aacghe ] [ -p prompt ] [ -r rprompt ]\n[ -M main-keymap ] [ -m vicmd-keymap ]\n[ -i init-widget ] [ -f finish-widget ]\n[ -t tty ] name\nThe value of the parameter name is loaded into the edit buffer, and the line editor is\ninvoked. When the editor exits, name is set to the string value returned by the edi‐\ntor. When the -c flag is given, the parameter is created if it doesn't already exist.\nThe -a flag may be given with -c to create an array parameter, or the -A flag to cre‐\nate an associative array. If the type of an existing parameter does not match the\ntype to be created, the parameter is unset and recreated. The -g flag may be given to\nsuppress warnings from the WARNCREATEGLOBAL and WARNNESTEDVAR options.\n\nIf an array or array slice is being edited, separator characters as defined in $IFS\nwill be shown quoted with a backslash, as will backslashes themselves. Conversely,\nwhen the edited text is split into an array, a backslash quotes an immediately follow‐\ning separator character or backslash; no other special handling of backslashes, or any\nhandling of quotes, is performed.\n\nIndividual elements of existing array or associative array parameters may be edited by\nusing subscript syntax on name. New elements are created automatically, even without\n-c.\n\nIf the -p flag is given, the following string will be taken as the prompt to display\nat the left. If the -r flag is given, the following string gives the prompt to dis‐\nplay at the right. If the -h flag is specified, the history can be accessed from ZLE.\nIf the -e flag is given, typing ^D (Control-D) on an empty line causes vared to exit\nimmediately with a non-zero return value.\n\nThe -M option gives a keymap to link to the main keymap during editing, and the -m op‐\ntion gives a keymap to link to the vicmd keymap during editing. For vi-style editing,\nthis allows a pair of keymaps to override viins and vicmd. For emacs-style editing,\nonly -M is normally needed but the -m option may still be used. On exit, the previous\nkeymaps will be restored.\n\nVared calls the usual `zle-line-init' and `zle-line-finish' hooks before and after it\ntakes control. Using the -i and -f options, it is possible to replace these with other\ncustom widgets.\n\nIf `-t tty' is given, tty is the name of a terminal device to be used instead of the\ndefault /dev/tty. If tty does not refer to a terminal an error is reported.\n", "subsections": [ { "name": "zle", "content": "zle -l [ -L | -a ] [ string ... ]\nzle -D widget ...\nzle -A old-widget new-widget\nzle -N widget [ function ]\nzle -f flag [ flag... ]\nzle -C widget completion-widget function\nzle -R [ -c ] [ display-string ] [ string ... ]\nzle -M string\nzle -U string\nzle -K keymap\nzle -F [ -L | -w ] [ fd [ handler ] ]" }, { "name": "zle -I", "content": "zle -T [ tc function | -r tc | -L ]\nzle widget [ -n num ] [ -Nw ] [ -K keymap ] args ...\nThe zle builtin performs a number of different actions concerning ZLE.\n\nWith no options and no arguments, only the return status will be set. It is zero if\nZLE is currently active and widgets could be invoked using this builtin command and\nnon-zero otherwise. Note that even if non-zero status is returned, zle may still be\nactive as part of the completion system; this does not allow direct calls to ZLE wid‐\ngets.\n\nOtherwise, which operation it performs depends on its options:\n\n-l [ -L | -a ] [ string ]\nList all existing user-defined widgets. If the -L option is used, list in the\nform of zle commands to create the widgets.\n\nWhen combined with the -a option, all widget names are listed, including the\nbuiltin ones. In this case the -L option is ignored.\n\nIf at least one string is given, and -a is present or -L is not used, nothing\nwill be printed. The return status will be zero if all strings are names of\nexisting widgets and non-zero if at least one string is not a name of a defined\nwidget. If -a is also present, all widget names are used for the comparison\nincluding builtin widgets, else only user-defined widgets are used.\n\nIf at least one string is present and the -L option is used, user-defined wid‐\ngets matching any string are listed in the form of zle commands to create the\nwidgets.\n\n-D widget ...\nDelete the named widgets.\n\n-A old-widget new-widget\nMake the new-widget name an alias for old-widget, so that both names refer to\nthe same widget. The names have equal standing; if either is deleted, the\nother remains. If there is already a widget with the new-widget name, it is\ndeleted.\n\n-N widget [ function ]\nCreate a user-defined widget. If there is already a widget with the specified\nname, it is overwritten. When the new widget is invoked from within the edi‐\ntor, the specified shell function is called. If no function name is specified,\nit defaults to the same name as the widget. For further information, see the\nsection `Widgets' below.\n\n-f flag [ flag... ]\nSet various flags on the running widget. Possible values for flag are:\n\nyank for indicating that the widget has yanked text into the buffer. If the\nwidget is wrapping an existing internal widget, no further action is necessary,\nbut if it has inserted the text manually, then it should also take care to set\nYANKSTART and YANKEND correctly. yankbefore does the same but is used when\nthe yanked text appears after the cursor.\n\nkill for indicating that text has been killed into the cutbuffer. When repeat‐\nedly invoking a kill widget, text is appended to the cutbuffer instead of re‐\nplacing it, but when wrapping such widgets, it is necessary to call `zle -f\nkill' to retain this effect.\n\nvichange for indicating that the widget represents a vi change that can be re‐\npeated as a whole with `vi-repeat-change'. The flag should be set early in the\nfunction before inspecting the value of NUMERIC or invoking other widgets. This\nhas no effect for a widget invoked from insert mode. If insert mode is active\nwhen the widget finishes, the change extends until next returning to command\nmode.\n\n-C widget completion-widget function\nCreate a user-defined completion widget named widget. The completion widget\nwill behave like the built-in completion-widget whose name is given as comple‐\ntion-widget. To generate the completions, the shell function function will be\ncalled. For further information, see zshcompwid(1).\n\n-R [ -c ] [ display-string ] [ string ... ]\nRedisplay the command line; this is to be called from within a user-defined\nwidget to allow changes to become visible. If a display-string is given and\nnot empty, this is shown in the status line (immediately below the line being\nedited).\n\nIf the optional strings are given they are listed below the prompt in the same\nway as completion lists are printed. If no strings are given but the -c option\nis used such a list is cleared.\n\nNote that this option is only useful for widgets that do not exit immediately\nafter using it because the strings displayed will be erased immediately after\nreturn from the widget.\n\nThis command can safely be called outside user defined widgets; if zle is ac‐\ntive, the display will be refreshed, while if zle is not active, the command\nhas no effect. In this case there will usually be no other arguments.\n\nThe status is zero if zle was active, else one.\n\n-M string\nAs with the -R option, the string will be displayed below the command line; un‐\nlike the -R option, the string will not be put into the status line but will\ninstead be printed normally below the prompt. This means that the string will\nstill be displayed after the widget returns (until it is overwritten by subse‐\nquent commands).\n\n-U string\nThis pushes the characters in the string onto the input stack of ZLE. After\nthe widget currently executed finishes ZLE will behave as if the characters in\nthe string were typed by the user.\n\nAs ZLE uses a stack, if this option is used repeatedly the last string pushed\nonto the stack will be processed first. However, the characters in each string\nwill be processed in the order in which they appear in the string.\n\n-K keymap\nSelects the keymap named keymap. An error message will be displayed if there\nis no such keymap.\n\nThis keymap selection affects the interpretation of following keystrokes within\nthis invocation of ZLE. Any following invocation (e.g., the next command line)\nwill start as usual with the `main' keymap selected.\n\n-F [ -L | -w ] [ fd [ handler ] ]\nOnly available if your system supports one of the `poll' or `select' system\ncalls; most modern systems do.\n\nInstalls handler (the name of a shell function) to handle input from file de‐\nscriptor fd. Installing a handler for an fd which is already handled causes\nthe existing handler to be replaced. Any number of handlers for any number of\nreadable file descriptors may be installed. Note that zle makes no attempt to\ncheck whether this fd is actually readable when installing the handler. The\nuser must make their own arrangements for handling the file descriptor when zle\nis not active.\n\nWhen zle is attempting to read data, it will examine both the terminal and the\nlist of handled fd's. If data becomes available on a handled fd, zle calls\nhandler with the fd which is ready for reading as the first argument. Under\nnormal circumstances this is the only argument, but if an error was detected, a\nsecond argument provides details: `hup' for a disconnect, `nval' for a closed\nor otherwise invalid descriptor, or `err' for any other condition. Systems\nthat support only the `select' system call always use `err'.\n\nIf the option -w is also given, the handler is instead a line editor widget,\ntypically a shell function made into a widget using `zle -N'. In that case\nhandler can use all the facilities of zle to update the current editing line.\nNote, however, that as handling fd takes place at a low level changes to the\ndisplay will not automatically appear; the widget should call `zle -R' to force\nredisplay. As of this writing, widget handlers only support a single argument\nand thus are never passed a string for error state, so widgets must be prepared\nto test the descriptor themselves.\n\nIf either type of handler produces output to the terminal, it should call `zle\n-I' before doing so (see below). Handlers should not attempt to read from the\nterminal.\n\nIf no handler is given, but an fd is present, any handler for that fd is re‐\nmoved. If there is none, an error message is printed and status 1 is returned.\n\nIf no arguments are given, or the -L option is supplied, a list of handlers is\nprinted in a form which can be stored for later execution.\n\nAn fd (but not a handler) may optionally be given with the -L option; in this\ncase, the function will list the handler if any, else silently return status 1.\n\nNote that this feature should be used with care. Activity on one of the fd's\nwhich is not properly handled can cause the terminal to become unusable. Re‐\nmoving an fd handler from within a signal trap may cause unpredictable behav‐\nior.\n\nHere is a simple example of using this feature. A connection to a remote TCP\nport is created using the ztcp command; see the description of the zsh/net/tcp\nmodule in zshmodules(1). Then a handler is installed which simply prints out\nany data which arrives on this connection. Note that `select' will indicate\nthat the file descriptor needs handling if the remote side has closed the con‐\nnection; we handle that by testing for a failed read.\n\nif ztcp pwspc 2811; then\ntcpfd=$REPLY\nhandler() {\nzle -I\nlocal line\nif ! read -r line <&$1; then\n# select marks this fd if we reach EOF,\n# so handle this specially.\nprint \"[Read on fd $1 failed, removing.]\" >&2\nzle -F $1\nreturn 1\nfi\nprint -r - $line\n}\nzle -F $tcpfd handler\nfi\n\n-I Unusually, this option is most useful outside ordinary widget functions, though\nit may be used within if normal output to the terminal is required. It invali‐\ndates the current zle display in preparation for output; typically this will be\nfrom a trap function. It has no effect if zle is not active. When a trap ex‐\nits, the shell checks to see if the display needs restoring, hence the follow‐\ning will print output in such a way as not to disturb the line being edited:\n\nTRAPUSR1() {\n# Invalidate zle display\n[[ -o zle ]] && zle -I\n# Show output\nprint Hello\n}\n\nIn general, the trap function may need to test whether zle is active before us‐\ning this method (as shown in the example), since the zsh/zle module may not\neven be loaded; if it is not, the command can be skipped.\n\nIt is possible to call `zle -I' several times before control is returned to the\neditor; the display will only be invalidated the first time to minimise disrup‐\ntion.\n\nNote that there are normally better ways of manipulating the display from\nwithin zle widgets; see, for example, `zle -R' above.\n\nThe returned status is zero if zle was invalidated, even though this may have\nbeen by a previous call to `zle -I' or by a system notification. To test if a\nzle widget may be called at this point, execute zle with no arguments and exam‐\nine the return status.\n\n-T This is used to add, list or remove internal transformations on the processing\nperformed by the line editor. It is typically used only for debugging or test‐\ning and is therefore of little interest to the general user.\n\n`zle -T transformation func' specifies that the given transformation (see be‐\nlow) is effected by shell function func.\n\n`zle -Tr transformation' removes the given transformation if it was present (it\nis not an error if none was).\n\n`zle -TL' can be used to list all transformations currently in operation.\n\nCurrently the only transformation is tc. This is used instead of outputting\ntermcap codes to the terminal. When the transformation is in operation the\nshell function is passed the termcap code that would be output as its first ar‐\ngument; if the operation required a numeric argument, that is passed as a sec‐\nond argument. The function should set the shell variable REPLY to the trans‐\nformed termcap code. Typically this is used to produce some simply formatted\nversion of the code and optional argument for debugging or testing. Note that\nthis transformation is not applied to other non-printing characters such as\ncarriage returns and newlines.\n\nwidget [ -n num ] [ -Nw ] [ -K keymap ] args ...\nInvoke the specified widget. This can only be done when ZLE is active; nor‐\nmally this will be within a user-defined widget.\n\nWith the options -n and -N, the current numeric argument will be saved and then\nrestored after the call to widget; `-n num' sets the numeric argument temporar‐\nily to num, while `-N' sets it to the default, i.e. as if there were none.\n\nWith the option -K, keymap will be used as the current keymap during the execu‐\ntion of the widget. The previous keymap will be restored when the widget ex‐\nits.\n\nNormally, calling a widget in this way does not set the special parameter WID‐‐\nGET and related parameters, so that the environment appears as if the top-level\nwidget called by the user were still active. With the option -w, WIDGET and\nrelated parameters are set to reflect the widget being executed by the zle\ncall.\n\nAny further arguments will be passed to the widget; note that as standard argu‐\nment handling is performed, any general argument list should be preceded by --.\nIf it is a shell function, these are passed down as positional parameters; for\nbuiltin widgets it is up to the widget in question what it does with them.\nCurrently arguments are only handled by the incremental-search commands, the\nhistory-search-forward and -backward and the corresponding functions prefixed\nby vi-, and by universal-argument. No error is flagged if the command does not\nuse the arguments, or only uses some of them.\n\nThe return status reflects the success or failure of the operation carried out\nby the widget, or if it is a user-defined widget the return status of the shell\nfunction.\n\nA non-zero return status causes the shell to beep when the widget exits, unless\nthe BEEP options was unset or the widget was called via the zle command. Thus\nif a user defined widget requires an immediate beep, it should call the beep\nwidget directly.\n" } ] }, "WIDGETS": { "content": "All actions in the editor are performed by `widgets'. A widget's job is simply to perform\nsome small action. The ZLE commands that key sequences in keymaps are bound to are in fact\nwidgets. Widgets can be user-defined or built in.\n\nThe standard widgets built into ZLE are listed in Standard Widgets below. Other built-in\nwidgets can be defined by other modules (see zshmodules(1)). Each built-in widget has two\nnames: its normal canonical name, and the same name preceded by a `.'. The `.' name is spe‐\ncial: it can't be rebound to a different widget. This makes the widget available even when\nits usual name has been redefined.\n\nUser-defined widgets are defined using `zle -N', and implemented as shell functions. When\nthe widget is executed, the corresponding shell function is executed, and can perform editing\n(or other) actions. It is recommended that user-defined widgets should not have names start‐\ning with `.'.\n", "subsections": [] }, "USER-DEFINED WIDGETS": { "content": "User-defined widgets, being implemented as shell functions, can execute any normal shell com‐\nmand. They can also run other widgets (whether built-in or user-defined) using the zle\nbuiltin command. The standard input of the function is redirected from /dev/null to prevent\nexternal commands from unintentionally blocking ZLE by reading from the terminal, but read -k\nor read -q can be used to read characters. Finally, they can examine and edit the ZLE buffer\nbeing edited by reading and setting the special parameters described below.\n\nThese special parameters are always available in widget functions, but are not in any way\nspecial outside ZLE. If they have some normal value outside ZLE, that value is temporarily\ninaccessible, but will return when the widget function exits. These special parameters in\nfact have local scope, like parameters created in a function using local.\n\nInside completion widgets and traps called while ZLE is active, these parameters are avail‐\nable read-only.\n\nNote that the parameters appear as local to any ZLE widget in which they appear. Hence if it\nis desired to override them this needs to be done within a nested function:\n\nwidget-function() {\n# $WIDGET here refers to the special variable\n# that is local inside widget-function\n() {\n# This anonymous nested function allows WIDGET\n# to be used as a local variable. The -h\n# removes the special status of the variable.\nlocal -h WIDGET\n}\n}\n", "subsections": [ { "name": "BUFFER (scalar)", "content": "The entire contents of the edit buffer. If it is written to, the cursor remains at\nthe same offset, unless that would put it outside the buffer.\n" }, { "name": "BUFFERLINES (integer)", "content": "The number of screen lines needed for the edit buffer currently displayed on screen\n(i.e. without any changes to the preceding parameters done after the last redisplay);\nread-only.\n" }, { "name": "CONTEXT (scalar)", "content": "The context in which zle was called to read a line; read-only. One of the values:\n\nstart The start of a command line (at prompt PS1).\n\ncont A continuation to a command line (at prompt PS2).\n\nselect In a select loop (at prompt PS3).\n\nvared Editing a variable in vared.\n" }, { "name": "CURSOR (integer)", "content": "The offset of the cursor, within the edit buffer. This is in the range 0 to $#BUFFER,\nand is by definition equal to $#LBUFFER. Attempts to move the cursor outside the buf‐\nfer will result in the cursor being moved to the appropriate end of the buffer.\n" }, { "name": "CUTBUFFER (scalar)", "content": "The last item cut using one of the `kill-' commands; the string which the next yank\nwould insert in the line. Later entries in the kill ring are in the array killring.\nNote that the command `zle copy-region-as-kill string' can be used to set the text of\nthe cut buffer from a shell function and cycle the kill ring in the same way as inter‐\nactively killing text.\n" }, { "name": "HISTNO (integer)", "content": "The current history number. Setting this has the same effect as moving up or down in\nthe history to the corresponding history line. An attempt to set it is ignored if the\nline is not stored in the history. Note this is not the same as the parameter\nHISTCMD, which always gives the number of the history line being added to the main\nshell's history. HISTNO refers to the line being retrieved within zle.\n" }, { "name": "ISEARCHMATCH___ACTIVE (integer)", "content": "" }, { "name": "ISEARCHMATCH___START (integer)", "content": "" }, { "name": "ISEARCHMATCH___END (integer)", "content": "ISEARCHMATCHACTIVE indicates whether a part of the BUFFER is currently matched by an\nincremental search pattern. ISEARCHMATCHSTART and ISEARCHMATCHEND give the location\nof the matched part and are in the same units as CURSOR. They are only valid for read‐\ning when ISEARCHMATCHACTIVE is non-zero.\n\nAll parameters are read-only.\n" }, { "name": "KEYMAP (scalar)", "content": "The name of the currently selected keymap; read-only.\n" }, { "name": "KEYS (scalar)", "content": "The keys typed to invoke this widget, as a literal string; read-only.\n" }, { "name": "KEYS___QUEUED___COUNT (integer)", "content": "The number of bytes pushed back to the input queue and therefore available for reading\nimmediately before any I/O is done; read-only. See also PENDING; the two values are\ndistinct.\n" }, { "name": "killring (array)", "content": "The array of previously killed items, with the most recently killed first. This gives\nthe items that would be retrieved by a yank-pop in the same order. Note, however,\nthat the most recently killed item is in $CUTBUFFER; $killring shows the array of pre‐\nvious entries.\n\nThe default size for the kill ring is eight, however the length may be changed by nor‐\nmal array operations. Any empty string in the kill ring is ignored by the yank-pop\ncommand, hence the size of the array effectively sets the maximum length of the kill\nring, while the number of non-zero strings gives the current length, both as seen by\nthe user at the command line.\n" }, { "name": "LASTABORTEDSEARCH (scalar)", "content": "The last search string used by an interactive search that was aborted by the user\n(status 3 returned by the search widget).\n" }, { "name": "LASTSEARCH (scalar)", "content": "The last search string used by an interactive search; read-only. This is set even if\nthe search failed (status 0, 1 or 2 returned by the search widget), but not if it was\naborted by the user.\n" }, { "name": "LASTWIDGET (scalar)", "content": "The name of the last widget that was executed; read-only.\n" }, { "name": "LBUFFER (scalar)", "content": "The part of the buffer that lies to the left of the cursor position. If it is as‐\nsigned to, only that part of the buffer is replaced, and the cursor remains between\nthe new $LBUFFER and the old $RBUFFER.\n" }, { "name": "MARK (integer)", "content": "Like CURSOR, but for the mark. With vi-mode operators that wait for a movement command\nto select a region of text, setting MARK allows the selection to extend in both direc‐\ntions from the initial cursor position.\n" }, { "name": "NUMERIC (integer)", "content": "The numeric argument. If no numeric argument was given, this parameter is unset. When\nthis is set inside a widget function, builtin widgets called with the zle builtin com‐\nmand will use the value assigned. If it is unset inside a widget function, builtin\nwidgets called behave as if no numeric argument was given.\n" }, { "name": "PENDING (integer)", "content": "The number of bytes pending for input, i.e. the number of bytes which have already\nbeen typed and can immediately be read. On systems where the shell is not able to get\nthis information, this parameter will always have a value of zero. Read-only. See\nalso KEYSQUEUEDCOUNT; the two values are distinct.\n" }, { "name": "PREBUFFER (scalar)", "content": "In a multi-line input at the secondary prompt, this read-only parameter contains the\ncontents of the lines before the one the cursor is currently in.\n" }, { "name": "PREDISPLAY (scalar)", "content": "Text to be displayed before the start of the editable text buffer. This does not have\nto be a complete line; to display a complete line, a newline must be appended explic‐\nitly. The text is reset on each new invocation (but not recursive invocation) of zle.\n" }, { "name": "POSTDISPLAY (scalar)", "content": "Text to be displayed after the end of the editable text buffer. This does not have to\nbe a complete line; to display a complete line, a newline must be prepended explic‐\nitly. The text is reset on each new invocation (but not recursive invocation) of zle.\n" }, { "name": "RBUFFER (scalar)", "content": "The part of the buffer that lies to the right of the cursor position. If it is as‐\nsigned to, only that part of the buffer is replaced, and the cursor remains between\nthe old $LBUFFER and the new $RBUFFER.\n" }, { "name": "REGION___ACTIVE (integer)", "content": "Indicates if the region is currently active. It can be assigned 0 or 1 to deactivate\nand activate the region respectively. A value of 2 activates the region in line-wise\nmode with the highlighted text extending for whole lines only; see Character High‐\nlighting below.\n" }, { "name": "region___highlight (array)", "content": "Each element of this array may be set to a string that describes highlighting for an\narbitrary region of the command line that will take effect the next time the command\nline is redisplayed. Highlighting of the non-editable parts of the command line in\nPREDISPLAY and POSTDISPLAY are possible, but note that the P flag is needed for char‐\nacter indexing to include PREDISPLAY.\n\nEach string consists of the following parts:\n\n• Optionally, a `P' to signify that the start and end offset that follow include\nany string set by the PREDISPLAY special parameter; this is needed if the pre‐\ndisplay string itself is to be highlighted. Whitespace may follow the `P'.\n\n• A start offset in the same units as CURSOR, terminated by whitespace.\n\n• An end offset in the same units as CURSOR, terminated by whitespace.\n\n• A highlight specification in the same format as used for contexts in the param‐\neter zlehighlight, see the section `Character Highlighting' below; for exam‐\nple, standout or fg=red,bold\n\nFor example,\n\nregionhighlight=(\"P0 20 bold\")\n\nspecifies that the first twenty characters of the text including any predisplay string\nshould be highlighted in bold.\n\nNote that the effect of regionhighlight is not saved and disappears as soon as the\nline is accepted.\n\nThe final highlighting on the command line depends on both regionhighlight and\nzlehighlight; see the section CHARACTER HIGHLIGHTING below for details.\n\nregisters (associative array)\nThe contents of each of the vi register buffers. These are typically set using\nvi-set-buffer followed by a delete, change or yank command.\n" }, { "name": "SUFFIX___ACTIVE (integer)", "content": "" }, { "name": "SUFFIX___START (integer)", "content": "" }, { "name": "SUFFIX___END (integer)", "content": "SUFFIXACTIVE indicates whether an auto-removable completion suffix is currently ac‐\ntive. SUFFIXSTART and SUFFIXEND give the location of the suffix and are in the same\nunits as CURSOR. They are only valid for reading when SUFFIXACTIVE is non-zero.\n\nAll parameters are read-only.\n" }, { "name": "UNDO___CHANGE___NO (integer)", "content": "A number representing the state of the undo history. The only use of this is passing\nas an argument to the undo widget in order to undo back to the recorded point.\nRead-only.\n" }, { "name": "UNDO___LIMIT___NO (integer)", "content": "A number corresponding to an existing change in the undo history; compare\nUNDOCHANGENO. If this is set to a value greater than zero, the undo command will\nnot allow the line to be undone beyond the given change number. It is still possible\nto use `zle undo change' in a widget to undo beyond that point; in that case, it will\nnot be possible to undo at all until UNDOLIMITNO is reduced. Set to 0 to disable\nthe limit.\n\nA typical use of this variable in a widget function is as follows (note the additional\nfunction scope is required):\n\n() {\nlocal UNDOLIMITNO=$UNDOCHANGENO\n# Perform some form of recursive edit.\n}\n" }, { "name": "WIDGET (scalar)", "content": "The name of the widget currently being executed; read-only.\n" }, { "name": "WIDGETFUNC (scalar)", "content": "The name of the shell function that implements a widget defined with either zle -N or\nzle -C. In the former case, this is the second argument to the zle -N command that\ndefined the widget, or the first argument if there was no second argument. In the\nlatter case this is the third argument to the zle -C command that defined the widget.\nRead-only.\n" }, { "name": "WIDGETSTYLE (scalar)", "content": "Describes the implementation behind the completion widget currently being executed;\nthe second argument that followed zle -C when the widget was defined. This is the\nname of a builtin completion widget. For widgets defined with zle -N this is set to\nthe empty string. Read-only.\n" }, { "name": "YANK___ACTIVE (integer)", "content": "" }, { "name": "YANK___START (integer)", "content": "" }, { "name": "YANK___END (integer)", "content": "YANKACTIVE indicates whether text has just been yanked (pasted) into the buffer.\nYANKSTART and YANKEND give the location of the pasted text and are in the same units\nas CURSOR. They are only valid for reading when YANKACTIVE is non-zero. They can\nalso be assigned by widgets that insert text in a yank-like fashion, for example wrap‐\npers of bracketed-paste. See also zle -f.\n\nYANKACTIVE is read-only.\n" }, { "name": "ZLE___RECURSIVE (integer)", "content": "Usually zero, but incremented inside any instance of recursive-edit. Hence indicates\nthe current recursion level.\n\nZLERECURSIVE is read-only.\n" }, { "name": "ZLE___STATE (scalar)", "content": "Contains a set of space-separated words that describe the current zle state.\n\nCurrently, the states shown are the insert mode as set by the overwrite-mode or vi-re‐‐\nplace widgets and whether history commands will visit imported entries as controlled\nby the set-local-history widget. The string contains `insert' if characters to be in‐\nserted on the command line move existing characters to the right or `overwrite' if\ncharacters to be inserted overwrite existing characters. It contains `localhistory' if\nonly local history commands will be visited or `globalhistory' if imported history\ncommands will also be visited.\n\nThe substrings are sorted in alphabetical order so that if you want to test for two\nspecific substrings in a future-proof way, you can do match by doing:\n\nif [[ $ZLESTATE == *globalhistory*insert* ]]; then ...; fi\n" }, { "name": "Special Widgets", "content": "There are a few user-defined widgets which are special to the shell. If they do not exist,\nno special action is taken. The environment provided is identical to that for any other\nediting widget.\n" }, { "name": "zle-isearch-exit", "content": "Executed at the end of incremental search at the point where the isearch prompt is re‐\nmoved from the display. See zle-isearch-update for an example.\n" }, { "name": "zle-isearch-update", "content": "Executed within incremental search when the display is about to be redrawn. Addi‐\ntional output below the incremental search prompt can be generated by using `zle -M'\nwithin the widget. For example,\n\nzle-isearch-update() { zle -M \"Line $HISTNO\"; }\nzle -N zle-isearch-update\n\nNote the line output by `zle -M' is not deleted on exit from incremental search. This\ncan be done from a zle-isearch-exit widget:\n\nzle-isearch-exit() { zle -M \"\"; }\nzle -N zle-isearch-exit\n" }, { "name": "zle-line-pre-redraw", "content": "Executed whenever the input line is about to be redrawn, providing an opportunity to\nupdate the regionhighlight array.\n" }, { "name": "zle-line-init", "content": "Executed every time the line editor is started to read a new line of input. The fol‐\nlowing example puts the line editor into vi command mode when it starts up.\n\nzle-line-init() { zle -K vicmd; }\nzle -N zle-line-init\n\n(The command inside the function sets the keymap directly; it is equivalent to zle\nvi-cmd-mode.)\n" }, { "name": "zle-line-finish", "content": "This is similar to zle-line-init but is executed every time the line editor has fin‐\nished reading a line of input.\n" }, { "name": "zle-history-line-set", "content": "Executed when the history line changes.\n" }, { "name": "zle-keymap-select", "content": "Executed every time the keymap changes, i.e. the special parameter KEYMAP is set to a\ndifferent value, while the line editor is active. Initialising the keymap when the\nline editor starts does not cause the widget to be called.\n\nThe value $KEYMAP within the function reflects the new keymap. The old keymap is\npassed as the sole argument.\n\nThis can be used for detecting switches between the vi command (vicmd) and insert\n(usually main) keymaps.\n" } ] }, "STANDARD WIDGETS": { "content": "The following is a list of all the standard widgets, and their default bindings in emacs\nmode, vi command mode and vi insert mode (the `emacs', `vicmd' and `viins' keymaps, respec‐\ntively).\n\nNote that cursor keys are bound to movement keys in all three keymaps; the shell assumes that\nthe cursor keys send the key sequences reported by the terminal-handling library (termcap or\nterminfo). The key sequences shown in the list are those based on the VT100, common on many\nmodern terminals, but in fact these are not necessarily bound. In the case of the viins\nkeymap, the initial escape character of the sequences serves also to return to the vicmd\nkeymap: whether this happens is determined by the KEYTIMEOUT parameter, see zshparam(1).\n", "subsections": [ { "name": "Movement", "content": "" }, { "name": "vi-backward-blank-word (unbound)", "content": "Move backward one word, where a word is defined as a series of non-blank characters.\n" }, { "name": "vi-backward-blank-word-end (unbound)", "content": "Move to the end of the previous word, where a word is defined as a series of non-blank\ncharacters.\n\nbackward-char (^B ESC-[D) (unbound) (unbound)\nMove backward one character.\n" }, { "name": "vi-backward-char (unbound)", "content": "Move backward one character, without changing lines.\n\nbackward-word (ESC-B ESC-b) (unbound) (unbound)\nMove to the beginning of the previous word.\n" }, { "name": "emacs-backward-word", "content": "Move to the beginning of the previous word.\n" }, { "name": "vi-backward-word (unbound)", "content": "Move to the beginning of the previous word, vi-style.\n" }, { "name": "vi-backward-word-end (unbound)", "content": "Move to the end of the previous word, vi-style.\n\nbeginning-of-line (^A) (unbound) (unbound)\nMove to the beginning of the line. If already at the beginning of the line, move to\nthe beginning of the previous line, if any.\n" }, { "name": "vi-beginning-of-line", "content": "Move to the beginning of the line, without changing lines.\n" }, { "name": "down-line (unbound)", "content": "Move down a line in the buffer.\n\nend-of-line (^E) (unbound) (unbound)\nMove to the end of the line. If already at the end of the line, move to the end of\nthe next line, if any.\n" }, { "name": "vi-end-of-line (unbound)", "content": "Move to the end of the line. If an argument is given to this command, the cursor will\nbe moved to the end of the line (argument - 1) lines down.\n" }, { "name": "vi-forward-blank-word (unbound)", "content": "Move forward one word, where a word is defined as a series of non-blank characters.\n" }, { "name": "vi-forward-blank-word-end (unbound)", "content": "Move to the end of the current word, or, if at the end of the current word, to the end\nof the next word, where a word is defined as a series of non-blank characters.\n\nforward-char (^F ESC-[C) (unbound) (unbound)\nMove forward one character.\n" }, { "name": "vi-forward-char (unbound)", "content": "Move forward one character.\n\nvi-find-next-char (^X^F) (f) (unbound)\nRead a character from the keyboard, and move to the next occurrence of it in the line.\n" }, { "name": "vi-find-next-char-skip (unbound)", "content": "Read a character from the keyboard, and move to the position just before the next oc‐\ncurrence of it in the line.\n" }, { "name": "vi-find-prev-char (unbound)", "content": "Read a character from the keyboard, and move to the previous occurrence of it in the\nline.\n" }, { "name": "vi-find-prev-char-skip (unbound)", "content": "Read a character from the keyboard, and move to the position just after the previous\noccurrence of it in the line.\n" }, { "name": "vi-first-non-blank (unbound)", "content": "Move to the first non-blank character in the line.\n" }, { "name": "vi-forward-word (unbound)", "content": "Move forward one word, vi-style.\n\nforward-word (ESC-F ESC-f) (unbound) (unbound)\nMove to the beginning of the next word. The editor's idea of a word is specified with\nthe WORDCHARS parameter.\n" }, { "name": "emacs-forward-word", "content": "Move to the end of the next word.\n" }, { "name": "vi-forward-word-end (unbound)", "content": "Move to the end of the next word.\n\nvi-goto-column (ESC-|) (|) (unbound)\nMove to the column specified by the numeric argument.\n" }, { "name": "vi-goto-mark (unbound)", "content": "Move to the specified mark.\n" }, { "name": "vi-goto-mark-line (unbound)", "content": "Move to beginning of the line containing the specified mark.\n" }, { "name": "vi-repeat-find (unbound)", "content": "Repeat the last vi-find command.\n" }, { "name": "vi-rev-repeat-find (unbound)", "content": "Repeat the last vi-find command in the opposite direction.\n" }, { "name": "up-line (unbound)", "content": "Move up a line in the buffer.\n" }, { "name": "History Control", "content": "beginning-of-buffer-or-history (ESC-<) (gg) (unbound)\nMove to the beginning of the buffer, or if already there, move to the first event in\nthe history list.\n" }, { "name": "beginning-of-line-hist", "content": "Move to the beginning of the line. If already at the beginning of the buffer, move to\nthe previous history line.\n" }, { "name": "beginning-of-history", "content": "Move to the first event in the history list.\n\ndown-line-or-history (^N ESC-[B) (j) (ESC-[B)\nMove down a line in the buffer, or if already at the bottom line, move to the next\nevent in the history list.\n" }, { "name": "vi-down-line-or-history (unbound)", "content": "Move down a line in the buffer, or if already at the bottom line, move to the next\nevent in the history list. Then move to the first non-blank character on the line.\n" }, { "name": "down-line-or-search", "content": "Move down a line in the buffer, or if already at the bottom line, search forward in\nthe history for a line beginning with the first word in the buffer.\n\nIf called from a function by the zle command with arguments, the first argument is\ntaken as the string for which to search, rather than the first word in the buffer.\n" }, { "name": "down-history (unbound)", "content": "Move to the next event in the history list.\n" }, { "name": "history-beginning-search-backward", "content": "Search backward in the history for a line beginning with the current line up to the\ncursor. This leaves the cursor in its original position.\n\nend-of-buffer-or-history (ESC->) (unbound) (unbound)\nMove to the end of the buffer, or if already there, move to the last event in the his‐\ntory list.\n" }, { "name": "end-of-line-hist", "content": "Move to the end of the line. If already at the end of the buffer, move to the next\nhistory line.\n" }, { "name": "end-of-history", "content": "Move to the last event in the history list.\n" }, { "name": "vi-fetch-history (unbound)", "content": "Fetch the history line specified by the numeric argument. This defaults to the cur‐\nrent history line (i.e. the one that isn't history yet).\n\nhistory-incremental-search-backward (^R ^Xr) (unbound) (unbound)\nSearch backward incrementally for a specified string. The search is case-insensitive\nif the search string does not have uppercase letters and no numeric argument was\ngiven. The string may begin with `^' to anchor the search to the beginning of the\nline. When called from a user-defined function returns the following statuses: 0, if\nthe search succeeded; 1, if the search failed; 2, if the search term was a bad pat‐\ntern; 3, if the search was aborted by the send-break command.\n\nA restricted set of editing functions is available in the mini-buffer. Keys are\nlooked up in the special isearch keymap, and if not found there in the main keymap\n(note that by default the isearch keymap is empty). An interrupt signal, as defined\nby the stty setting, will stop the search and go back to the original line. An unde‐\nfined key will have the same effect. Note that the following always perform the same\ntask within incremental searches and cannot be replaced by user defined widgets, nor\ncan the set of functions be extended. The supported functions are:\n\naccept-and-hold\naccept-and-infer-next-history\naccept-line\naccept-line-and-down-history\nPerform the usual function after exiting incremental search. The command line\ndisplayed is executed.\n\nbackward-delete-char\nvi-backward-delete-char\nBack up one place in the search history. If the search has been repeated this\ndoes not immediately erase a character in the minibuffer.\n\naccept-search\nExit incremental search, retaining the command line but performing no further\naction. Note that this function is not bound by default and has no effect out‐\nside incremental search.\n\nbackward-delete-word\nbackward-kill-word\nvi-backward-kill-word\nBack up one character in the minibuffer; if multiple searches have been per‐\nformed since the character was inserted the search history is rewound to the\npoint just before the character was entered. Hence this has the effect of re‐\npeating backward-delete-char.\n\nclear-screen\nClear the screen, remaining in incremental search mode.\n\nhistory-incremental-search-backward\nFind the next occurrence of the contents of the mini-buffer. If the mini-buffer\nis empty, the most recent previously used search string is reinstated.\n\nhistory-incremental-search-forward\nInvert the sense of the search.\n\nmagic-space\nInserts a non-magical space.\n\nquoted-insert\nvi-quoted-insert\nQuote the character to insert into the minibuffer.\n\nredisplay\nRedisplay the command line, remaining in incremental search mode.\n\nvi-cmd-mode\nSelect the `vicmd' keymap; the `main' keymap (insert mode) will be selected\ninitially.\n\nIn addition, the modifications that were made while in vi insert mode are\nmerged to form a single undo event.\n\nvi-repeat-search\nvi-rev-repeat-search\nRepeat the search. The direction of the search is indicated in the mini-buf‐\nfer.\n\nAny character that is not bound to one of the above functions, or self-insert or\nself-insert-unmeta, will cause the mode to be exited. The character is then looked up\nand executed in the keymap in effect at that point.\n\nWhen called from a widget function by the zle command, the incremental search commands\ncan take a string argument. This will be treated as a string of keys, as for argu‐\nments to the bindkey command, and used as initial input for the command. Any charac‐\nters in the string which are unused by the incremental search will be silently ig‐\nnored. For example,\n\nzle history-incremental-search-backward forceps\n\nwill search backwards for forceps, leaving the minibuffer containing the string `for‐‐\nceps'.\n\nhistory-incremental-search-forward (^S ^Xs) (unbound) (unbound)\nSearch forward incrementally for a specified string. The search is case-insensitive\nif the search string does not have uppercase letters and no numeric argument was\ngiven. The string may begin with `^' to anchor the search to the beginning of the\nline. The functions available in the mini-buffer are the same as for history-incre‐‐\nmental-search-backward.\n" }, { "name": "history-incremental-pattern-search-backward", "content": "" }, { "name": "history-incremental-pattern-search-forward", "content": "These widgets behave similarly to the corresponding widgets with no -pattern, but the\nsearch string typed by the user is treated as a pattern, respecting the current set‐\ntings of the various options affecting pattern matching. See FILENAME GENERATION in\nzshexpn(1) for a description of patterns. If no numeric argument was given lowercase\nletters in the search string may match uppercase letters in the history. The string\nmay begin with `^' to anchor the search to the beginning of the line.\n\nThe prompt changes to indicate an invalid pattern; this may simply indicate the pat‐\ntern is not yet complete.\n\nNote that only non-overlapping matches are reported, so an expression with wildcards\nmay return fewer matches on a line than are visible by inspection.\n\nhistory-search-backward (ESC-P ESC-p) (unbound) (unbound)\nSearch backward in the history for a line beginning with the first word in the buffer.\n\nIf called from a function by the zle command with arguments, the first argument is\ntaken as the string for which to search, rather than the first word in the buffer.\n" }, { "name": "vi-history-search-backward (unbound)", "content": "Search backward in the history for a specified string. The string may begin with `^'\nto anchor the search to the beginning of the line.\n\nA restricted set of editing functions is available in the mini-buffer. An interrupt\nsignal, as defined by the stty setting, will stop the search. The functions avail‐\nable in the mini-buffer are: accept-line, backward-delete-char, vi-back‐‐\nward-delete-char, backward-kill-word, vi-backward-kill-word, clear-screen, redisplay,\nquoted-insert and vi-quoted-insert.\n\nvi-cmd-mode is treated the same as accept-line, and magic-space is treated as a space.\nAny other character that is not bound to self-insert or self-insert-unmeta will beep\nand be ignored. If the function is called from vi command mode, the bindings of the\ncurrent insert mode will be used.\n\nIf called from a function by the zle command with arguments, the first argument is\ntaken as the string for which to search, rather than the first word in the buffer.\n\nhistory-search-forward (ESC-N ESC-n) (unbound) (unbound)\nSearch forward in the history for a line beginning with the first word in the buffer.\n\nIf called from a function by the zle command with arguments, the first argument is\ntaken as the string for which to search, rather than the first word in the buffer.\n" }, { "name": "vi-history-search-forward (unbound)", "content": "Search forward in the history for a specified string. The string may begin with `^'\nto anchor the search to the beginning of the line. The functions available in the\nmini-buffer are the same as for vi-history-search-backward. Argument handling is also\nthe same as for that command.\n\ninfer-next-history (^X^N) (unbound) (unbound)\nSearch in the history list for a line matching the current one and fetch the event\nfollowing it.\n\ninsert-last-word (ESC- ESC-.) (unbound) (unbound)\nInsert the last word from the previous history event at the cursor position. If a\npositive numeric argument is given, insert that word from the end of the previous his‐\ntory event. If the argument is zero or negative insert that word from the left (zero\ninserts the previous command word). Repeating this command replaces the word just in‐\nserted with the last word from the history event prior to the one just used; numeric\narguments can be used in the same way to pick a word from that event.\n\nWhen called from a shell function invoked from a user-defined widget, the command can\ntake one to three arguments. The first argument specifies a history offset which ap‐\nplies to successive calls to this widget: if it is -1, the default behaviour is used,\nwhile if it is 1, successive calls will move forwards through the history. The value\n0 can be used to indicate that the history line examined by the previous execution of\nthe command will be reexamined. Note that negative numbers should be preceded by a\n`--' argument to avoid confusing them with options.\n\nIf two arguments are given, the second specifies the word on the command line in nor‐\nmal array index notation (as a more natural alternative to the numeric argument).\nHence 1 is the first word, and -1 (the default) is the last word.\n\nIf a third argument is given, its value is ignored, but it is used to signify that the\nhistory offset is relative to the current history line, rather than the one remembered\nafter the previous invocations of insert-last-word.\n\nFor example, the default behaviour of the command corresponds to\n\nzle insert-last-word -- -1 -1\n\nwhile the command\n\nzle insert-last-word -- -1 1 -\n\nalways copies the first word of the line in the history immediately before the line\nbeing edited. This has the side effect that later invocations of the widget will be\nrelative to that line.\n" }, { "name": "vi-repeat-search (unbound)", "content": "Repeat the last vi history search.\n" }, { "name": "vi-rev-repeat-search (unbound)", "content": "Repeat the last vi history search, but in reverse.\n\nup-line-or-history (^P ESC-[A) (k) (ESC-[A)\nMove up a line in the buffer, or if already at the top line, move to the previous\nevent in the history list.\n" }, { "name": "vi-up-line-or-history (unbound)", "content": "Move up a line in the buffer, or if already at the top line, move to the previous\nevent in the history list. Then move to the first non-blank character on the line.\n" }, { "name": "up-line-or-search", "content": "Move up a line in the buffer, or if already at the top line, search backward in the\nhistory for a line beginning with the first word in the buffer.\n\nIf called from a function by the zle command with arguments, the first argument is\ntaken as the string for which to search, rather than the first word in the buffer.\n" }, { "name": "up-history (unbound)", "content": "Move to the previous event in the history list.\n" }, { "name": "history-beginning-search-forward", "content": "Search forward in the history for a line beginning with the current line up to the\ncursor. This leaves the cursor in its original position.\n" }, { "name": "set-local-history", "content": "By default, history movement commands visit the imported lines as well as the local\nlines. This widget lets you toggle this on and off, or set it with the numeric argu‐\nment. Zero for both local and imported lines and nonzero for only local lines.\n" }, { "name": "Modifying Text", "content": "" }, { "name": "vi-add-eol (unbound)", "content": "Move to the end of the line and enter insert mode.\n" }, { "name": "vi-add-next (unbound)", "content": "Enter insert mode after the current cursor position, without changing lines.\n\nbackward-delete-char (^H ^?) (unbound) (unbound)\nDelete the character behind the cursor.\n" }, { "name": "vi-backward-delete-char (unbound)", "content": "Delete the character behind the cursor, without changing lines. If in insert mode,\nthis won't delete past the point where insert mode was last entered.\n" }, { "name": "backward-delete-word", "content": "Delete the word behind the cursor.\n" }, { "name": "backward-kill-line", "content": "Kill from the beginning of the line to the cursor position.\n\nbackward-kill-word (^W ESC-^H ESC-^?) (unbound) (unbound)\nKill the word behind the cursor.\n" }, { "name": "vi-backward-kill-word (unbound)", "content": "Kill the word behind the cursor, without going past the point where insert mode was\nlast entered.\n\ncapitalize-word (ESC-C ESC-c) (unbound) (unbound)\nCapitalize the current word and move past it.\n" }, { "name": "vi-change (unbound)", "content": "Read a movement command from the keyboard, and kill from the cursor position to the\nendpoint of the movement. Then enter insert mode. If the command is vi-change,\nchange the current line.\n\nFor compatibility with vi, if the command is vi-forward-word or vi-forward-blank-word,\nthe whitespace after the word is not included. If you prefer the more consistent be‐\nhaviour with the whitespace included use the following key binding:\n\nbindkey -a -s cw dwi\n" }, { "name": "vi-change-eol (unbound)", "content": "Kill to the end of the line and enter insert mode.\n" }, { "name": "vi-change-whole-line (unbound)", "content": "Kill the current line and enter insert mode.\n\ncopy-region-as-kill (ESC-W ESC-w) (unbound) (unbound)\nCopy the area from the cursor to the mark to the kill buffer.\n\nIf called from a ZLE widget function in the form `zle copy-region-as-kill string' then\nstring will be taken as the text to copy to the kill buffer. The cursor, the mark and\nthe text on the command line are not used in this case.\n\ncopy-prev-word (ESC-^) (unbound) (unbound)\nDuplicate the word to the left of the cursor.\n" }, { "name": "copy-prev-shell-word", "content": "Like copy-prev-word, but the word is found by using shell parsing, whereas\ncopy-prev-word looks for blanks. This makes a difference when the word is quoted and\ncontains spaces.\n" }, { "name": "vi-delete (unbound)", "content": "Read a movement command from the keyboard, and kill from the cursor position to the\nendpoint of the movement. If the command is vi-delete, kill the current line.\n" }, { "name": "delete-char", "content": "Delete the character under the cursor.\n" }, { "name": "vi-delete-char (unbound)", "content": "Delete the character under the cursor, without going past the end of the line.\n" }, { "name": "delete-word", "content": "Delete the current word.\n\ndown-case-word (ESC-L ESC-l) (unbound) (unbound)\nConvert the current word to all lowercase and move past it.\n" }, { "name": "vi-down-case (unbound)", "content": "Read a movement command from the keyboard, and convert all characters from the cursor\nposition to the endpoint of the movement to lowercase. If the movement command is\nvi-down-case, swap the case of all characters on the current line.\n\nkill-word (ESC-D ESC-d) (unbound) (unbound)\nKill the current word.\n" }, { "name": "gosmacs-transpose-chars", "content": "Exchange the two characters behind the cursor.\n" }, { "name": "vi-indent (unbound)", "content": "Indent a number of lines.\n" }, { "name": "vi-insert (unbound)", "content": "Enter insert mode.\n" }, { "name": "vi-insert-bol (unbound)", "content": "Move to the first non-blank character on the line and enter insert mode.\n\nvi-join (^X^J) (J) (unbound)\nJoin the current line with the next one.\n\nkill-line (^K) (unbound) (unbound)\nKill from the cursor to the end of the line. If already on the end of the line, kill\nthe newline character.\n" }, { "name": "vi-kill-line (unbound)", "content": "Kill from the cursor back to wherever insert mode was last entered.\n" }, { "name": "vi-kill-eol (unbound)", "content": "Kill from the cursor to the end of the line.\n" }, { "name": "kill-region", "content": "Kill from the cursor to the mark.\n\nkill-buffer (^X^K) (unbound) (unbound)\nKill the entire buffer.\n\nkill-whole-line (^U) (unbound) (unbound)\nKill the current line.\n\nvi-match-bracket (^X^B) (%) (unbound)\nMove to the bracket character (one of {}, () or []) that matches the one under the\ncursor. If the cursor is not on a bracket character, move forward without going past\nthe end of the line to find one, and then go to the matching bracket.\n" }, { "name": "vi-open-line-above (unbound)", "content": "Open a line above the cursor and enter insert mode.\n" }, { "name": "vi-open-line-below (unbound)", "content": "Open a line below the cursor and enter insert mode.\n" }, { "name": "vi-oper-swap-case (unbound)", "content": "Read a movement command from the keyboard, and swap the case of all characters from\nthe cursor position to the endpoint of the movement. If the movement command is\nvi-oper-swap-case, swap the case of all characters on the current line.\n\noverwrite-mode (^X^O) (unbound) (unbound)\nToggle between overwrite mode and insert mode.\n" }, { "name": "vi-put-before (unbound)", "content": "Insert the contents of the kill buffer before the cursor. If the kill buffer contains\na sequence of lines (as opposed to characters), paste it above the current line.\n" }, { "name": "vi-put-after (unbound)", "content": "Insert the contents of the kill buffer after the cursor. If the kill buffer contains\na sequence of lines (as opposed to characters), paste it below the current line.\n" }, { "name": "put-replace-selection (unbound)", "content": "Replace the contents of the current region or selection with the contents of the kill\nbuffer. If the kill buffer contains a sequence of lines (as opposed to characters),\nthe current line will be split by the pasted lines.\n\nquoted-insert (^V) (unbound) (unbound)\nInsert the next character typed into the buffer literally. An interrupt character\nwill not be inserted.\n" }, { "name": "vi-quoted-insert (unbound)", "content": "Display a `^' at the cursor position, and insert the next character typed into the\nbuffer literally. An interrupt character will not be inserted.\n\nquote-line (ESC-') (unbound) (unbound)\nQuote the current line; that is, put a `'' character at the beginning and the end, and\nconvert all `'' characters to `'\\'''.\n\nquote-region (ESC-\") (unbound) (unbound)\nQuote the region from the cursor to the mark.\n" }, { "name": "vi-replace (unbound)", "content": "Enter overwrite mode.\n" }, { "name": "vi-repeat-change (unbound)", "content": "Repeat the last vi mode text modification. If a count was used with the modification,\nit is remembered. If a count is given to this command, it overrides the remembered\ncount, and is remembered for future uses of this command. The cut buffer specifica‐\ntion is similarly remembered.\n" }, { "name": "vi-replace-chars (unbound)", "content": "Replace the character under the cursor with a character read from the keyboard.\n\nself-insert (printable characters) (unbound) (printable characters and some control charac‐\nters)\nInsert a character into the buffer at the cursor position.\n\nself-insert-unmeta (ESC-^I ESC-^J ESC-^M) (unbound) (unbound)\nInsert a character into the buffer after stripping the meta bit and converting ^M to\n^J.\n" }, { "name": "vi-substitute (unbound)", "content": "Substitute the next character(s).\n" }, { "name": "vi-swap-case (unbound)", "content": "Swap the case of the character under the cursor and move past it.\n\ntranspose-chars (^T) (unbound) (unbound)\nExchange the two characters to the left of the cursor if at end of line, else exchange\nthe character under the cursor with the character to the left.\n\ntranspose-words (ESC-T ESC-t) (unbound) (unbound)\nExchange the current word with the one before it.\n\nWith a positive numeric argument N, the word around the cursor, or following it if the\ncursor is between words, is transposed with the preceding N words. The cursor is put\nat the end of the resulting group of words.\n\nWith a negative numeric argument -N, the effect is the same as using a positive argu‐\nment N except that the original cursor position is retained, regardless of how the\nwords are rearranged.\n" }, { "name": "vi-unindent (unbound)", "content": "Unindent a number of lines.\n" }, { "name": "vi-up-case (unbound)", "content": "Read a movement command from the keyboard, and convert all characters from the cursor\nposition to the endpoint of the movement to lowercase. If the movement command is\nvi-up-case, swap the case of all characters on the current line.\n\nup-case-word (ESC-U ESC-u) (unbound) (unbound)\nConvert the current word to all caps and move past it.\n\nyank (^Y) (unbound) (unbound)\nInsert the contents of the kill buffer at the cursor position.\n\nyank-pop (ESC-y) (unbound) (unbound)\nRemove the text just yanked, rotate the kill-ring (the history of previously killed\ntext) and yank the new top. Only works following yank, vi-put-before, vi-put-after or\nyank-pop.\n" }, { "name": "vi-yank (unbound)", "content": "Read a movement command from the keyboard, and copy the region from the cursor posi‐\ntion to the endpoint of the movement into the kill buffer. If the command is vi-yank,\ncopy the current line.\n" }, { "name": "vi-yank-whole-line (unbound)", "content": "Copy the current line into the kill buffer.\n" }, { "name": "vi-yank-eol", "content": "Copy the region from the cursor position to the end of the line into the kill buffer.\nArguably, this is what Y should do in vi, but it isn't what it actually does.\n" }, { "name": "Arguments", "content": "digit-argument (ESC-0..ESC-9) (1-9) (unbound)\nStart a new numeric argument, or add to the current one. See also vi-digit-or-begin‐‐\nning-of-line. This only works if bound to a key sequence ending in a decimal digit.\n\nInside a widget function, a call to this function treats the last key of the key se‐\nquence which called the widget as the digit.\n\nneg-argument (ESC--) (unbound) (unbound)\nChanges the sign of the following argument.\n" }, { "name": "universal-argument", "content": "Multiply the argument of the next command by 4. Alternatively, if this command is\nfollowed by an integer (positive or negative), use that as the argument for the next\ncommand. Thus digits cannot be repeated using this command. For example, if this\ncommand occurs twice, followed immediately by forward-char, move forward sixteen spa‐\nces; if instead it is followed by -2, then forward-char, move backward two spaces.\n\nInside a widget function, if passed an argument, i.e. `zle universal-argument num',\nthe numeric argument will be set to num; this is equivalent to `NUMERIC=num'.\n" }, { "name": "argument-base", "content": "Use the existing numeric argument as a numeric base, which must be in the range 2 to\n36 inclusive. Subsequent use of digit-argument and universal-argument will input a\nnew numeric argument in the given base. The usual hexadecimal convention is used: the\nletter a or A corresponds to 10, and so on. Arguments in bases requiring digits from\n10 upwards are more conveniently input with universal-argument, since ESC-a etc. are\nnot usually bound to digit-argument.\n\nThe function can be used with a command argument inside a user-defined widget. The\nfollowing code sets the base to 16 and lets the user input a hexadecimal argument un‐\ntil a key out of the digit range is typed:\n\nzle argument-base 16\nzle universal-argument\n" }, { "name": "Completion", "content": "" }, { "name": "accept-and-menu-complete", "content": "In a menu completion, insert the current completion into the buffer, and advance to\nthe next possible completion.\n" }, { "name": "complete-word", "content": "Attempt completion on the current word.\n\ndelete-char-or-list (^D) (unbound) (unbound)\nDelete the character under the cursor. If the cursor is at the end of the line, list\npossible completions for the current word.\n" }, { "name": "expand-cmd-path", "content": "Expand the current command to its full pathname.\n\nexpand-or-complete (TAB) (unbound) (TAB)\nAttempt shell expansion on the current word. If that fails, attempt completion.\n" }, { "name": "expand-or-complete-prefix", "content": "Attempt shell expansion on the current word up to cursor.\n\nexpand-history (ESC-space ESC-!) (unbound) (unbound)\nPerform history expansion on the edit buffer.\n\nexpand-word (^X*) (unbound) (unbound)\nAttempt shell expansion on the current word.\n\nlist-choices (ESC-^D) (^D =) (^D)\nList possible completions for the current word.\n\nlist-expand (^Xg ^XG) (^G) (^G)\nList the expansion of the current word.\n" }, { "name": "magic-space", "content": "Perform history expansion and insert a space into the buffer. This is intended to be\nbound to space.\n" }, { "name": "menu-complete", "content": "Like complete-word, except that menu completion is used. See the MENUCOMPLETE op‐\ntion.\n" }, { "name": "menu-expand-or-complete", "content": "Like expand-or-complete, except that menu completion is used.\n" }, { "name": "reverse-menu-complete", "content": "Perform menu completion, like menu-complete, except that if a menu completion is al‐\nready in progress, move to the previous completion rather than the next.\n" }, { "name": "end-of-list", "content": "When a previous completion displayed a list below the prompt, this widget can be used\nto move the prompt below the list.\n" }, { "name": "Miscellaneous", "content": "accept-and-hold (ESC-A ESC-a) (unbound) (unbound)\nPush the contents of the buffer on the buffer stack and execute it.\n" }, { "name": "accept-and-infer-next-history", "content": "Execute the contents of the buffer. Then search the history list for a line matching\nthe current one and push the event following onto the buffer stack.\n\naccept-line (^J ^M) (^J ^M) (^J ^M)\nFinish editing the buffer. Normally this causes the buffer to be executed as a shell\ncommand.\n\naccept-line-and-down-history (^O) (unbound) (unbound)\nExecute the current line, and push the next history event on the buffer stack.\n" }, { "name": "auto-suffix-remove", "content": "If the previous action added a suffix (space, slash, etc.) to the word on the command\nline, remove it. Otherwise do nothing. Removing the suffix ends any active menu com‐\npletion or menu selection.\n\nThis widget is intended to be called from user-defined widgets to enforce a desired\nsuffix-removal behavior.\n" }, { "name": "auto-suffix-retain", "content": "If the previous action added a suffix (space, slash, etc.) to the word on the command\nline, force it to be preserved. Otherwise do nothing. Retaining the suffix ends any\nactive menu completion or menu selection.\n\nThis widget is intended to be called from user-defined widgets to enforce a desired\nsuffix-preservation behavior.\n\nbeep Beep, unless the BEEP option is unset.\n" }, { "name": "bracketed-paste", "content": "This widget is invoked when text is pasted to the terminal emulator. It is not in‐\ntended to be bound to actual keys but instead to the special sequence generated by the\nterminal emulator when text is pasted.\n\nWhen invoked interactively, the pasted text is inserted to the buffer and placed in\nthe cutbuffer. If a numeric argument is given, shell quoting will be applied to the\npasted text before it is inserted.\n\nWhen a named buffer is specified with vi-set-buffer (\"x), the pasted text is stored in\nthat named buffer but not inserted.\n\nWhen called from a widget function as `bracketed-paste name`, the pasted text is as‐\nsigned to the variable name and no other processing is done.\n\nSee also the zlebracketedpaste parameter.\n\nvi-cmd-mode (^X^V) (unbound) (^[)\nEnter command mode; that is, select the `vicmd' keymap. Yes, this is bound by default\nin emacs mode.\n" }, { "name": "vi-caps-lock-panic", "content": "Hang until any lowercase key is pressed. This is for vi users without the mental ca‐\npacity to keep track of their caps lock key (like the author).\n\nclear-screen (^L ESC-^L) (^L) (^L)\nClear the screen and redraw the prompt.\n" }, { "name": "deactivate-region", "content": "Make the current region inactive. This disables vim-style visual selection mode if it\nis active.\n" }, { "name": "describe-key-briefly", "content": "Reads a key sequence, then prints the function bound to that sequence.\n\nexchange-point-and-mark (^X^X) (unbound) (unbound)\nExchange the cursor position (point) with the position of the mark. Unless a negative\nnumeric argument is given, the region between point and mark is activated so that it\ncan be highlighted. If a zero numeric argument is given, the region is activated but\npoint and mark are not swapped.\n\nexecute-named-cmd (ESC-x) (:) (unbound)\nRead the name of an editor command and execute it. Aliasing this widget with `zle -A'\nor replacing it with `zle -N' has no effect when interpreting key bindings, but `zle\nexecute-named-cmd' will invoke such an alias or replacement.\n\nA restricted set of editing functions is available in the mini-buffer. Keys are\nlooked up in the special command keymap, and if not found there in the main keymap.\nAn interrupt signal, as defined by the stty setting, will abort the function. Note\nthat the following always perform the same task within the executed-named-cmd environ‐\nment and cannot be replaced by user defined widgets, nor can the set of functions be\nextended. The allowed functions are: backward-delete-char, vi-backward-delete-char,\nclear-screen, redisplay, quoted-insert, vi-quoted-insert, backward-kill-word, vi-back‐‐\nward-kill-word, kill-whole-line, vi-kill-line, backward-kill-line, list-choices,\ndelete-char-or-list, complete-word, accept-line, expand-or-complete and expand-or-com‐‐\nplete-prefix.\n\nkill-region kills the last word, and vi-cmd-mode is treated the same as accept-line.\nThe space and tab characters, if not bound to one of these functions, will complete\nthe name and then list the possibilities if the AUTOLIST option is set. Any other\ncharacter that is not bound to self-insert or self-insert-unmeta will beep and be ig‐\nnored. The bindings of the current insert mode will be used.\n\nCurrently this command may not be redefined or called by name.\n\nexecute-last-named-cmd (ESC-z) (unbound) (unbound)\nRedo the last function executed with execute-named-cmd.\n\nLike execute-named-cmd, this command may not be redefined, but it may be called by\nname.\n\nget-line (ESC-G ESC-g) (unbound) (unbound)\nPop the top line off the buffer stack and insert it at the cursor position.\n" }, { "name": "pound-insert (unbound)", "content": "If there is no # character at the beginning of the buffer, add one to the beginning of\neach line. If there is one, remove a # from each line that has one. In either case,\naccept the current line. The INTERACTIVECOMMENTS option must be set for this to have\nany usefulness.\n" }, { "name": "vi-pound-insert", "content": "If there is no # character at the beginning of the current line, add one. If there is\none, remove it. The INTERACTIVECOMMENTS option must be set for this to have any use‐\nfulness.\n" }, { "name": "push-input", "content": "Push the entire current multiline construct onto the buffer stack and return to the\ntop-level (PS1) prompt. If the current parser construct is only a single line, this\nis exactly like push-line. Next time the editor starts up or is popped with get-line,\nthe construct will be popped off the top of the buffer stack and loaded into the edit‐\ning buffer.\n\npush-line (^Q ESC-Q ESC-q) (unbound) (unbound)\nPush the current buffer onto the buffer stack and clear the buffer. Next time the ed‐\nitor starts up, the buffer will be popped off the top of the buffer stack and loaded\ninto the editing buffer.\n" }, { "name": "push-line-or-edit", "content": "At the top-level (PS1) prompt, equivalent to push-line. At a secondary (PS2) prompt,\nmove the entire current multiline construct into the editor buffer. The latter is\nequivalent to push-input followed by get-line.\n" }, { "name": "read-command", "content": "Only useful from a user-defined widget. A keystroke is read just as in normal opera‐\ntion, but instead of the command being executed the name of the command that would be\nexecuted is stored in the shell parameter REPLY. This can be used as the argument of\na future zle command. If the key sequence is not bound, status 1 is returned; typi‐\ncally, however, REPLY is set to undefined-key to indicate a useless key sequence.\n" }, { "name": "recursive-edit", "content": "Only useful from a user-defined widget. At this point in the function, the editor re‐\ngains control until one of the standard widgets which would normally cause zle to exit\n(typically an accept-line caused by hitting the return key) is executed. Instead,\ncontrol returns to the user-defined widget. The status returned is non-zero if the\nreturn was caused by an error, but the function still continues executing and hence\nmay tidy up. This makes it safe for the user-defined widget to alter the command line\nor key bindings temporarily.\n\nThe following widget, caps-lock, serves as an example.\n\nself-insert-ucase() {\nLBUFFER+=${(U)KEYS[-1]}\n}\n\ninteger stat\n\nzle -N self-insert self-insert-ucase\nzle -A caps-lock save-caps-lock\nzle -A accept-line caps-lock\n\nzle recursive-edit\nstat=$?\n\nzle -A .self-insert self-insert\nzle -A save-caps-lock caps-lock\nzle -D save-caps-lock\n\n(( stat )) && zle send-break\n\nreturn $stat\n\nThis causes typed letters to be inserted capitalised until either accept-line (i.e.\ntypically the return key) is typed or the caps-lock widget is invoked again; the later\nis handled by saving the old definition of caps-lock as save-caps-lock and then re‐\nbinding it to invoke accept-line. Note that an error from the recursive edit is de‐\ntected as a non-zero return status and propagated by using the send-break widget.\n" }, { "name": "redisplay (unbound)", "content": "Redisplays the edit buffer.\n" }, { "name": "reset-prompt (unbound)", "content": "Force the prompts on both the left and right of the screen to be re-expanded, then re‐\ndisplay the edit buffer. This reflects changes both to the prompt variables them‐\nselves and changes in the expansion of the values (for example, changes in time or di‐\nrectory, or changes to the value of variables referred to by the prompt).\n\nOtherwise, the prompt is only expanded each time zle starts, and when the display has\nbeen interrupted by output from another part of the shell (such as a job notification)\nwhich causes the command line to be reprinted.\n\nreset-prompt doesn't alter the special parameter LASTWIDGET.\n\nsend-break (^G ESC-^G) (unbound) (unbound)\nAbort the current editor function, e.g. execute-named-command, or the editor itself,\ne.g. if you are in vared. Otherwise abort the parsing of the current line; in this\ncase the aborted line is available in the shell variable ZLELINEABORTED. If the ed‐\nitor is aborted from within vared, the variable ZLEVAREDABORTED is set.\n\nrun-help (ESC-H ESC-h) (unbound) (unbound)\nPush the buffer onto the buffer stack, and execute the command `run-help cmd', where\ncmd is the current command. run-help is normally aliased to man.\n" }, { "name": "vi-set-buffer (unbound)", "content": "Specify a buffer to be used in the following command. There are 37 buffers that can\nbe specified: the 26 `named' buffers \"a to \"z, the `yank' buffer \"0, the nine `queued'\nbuffers \"1 to \"9 and the `black hole' buffer \". The named buffers can also be speci‐\nfied as \"A to \"Z.\n\nWhen a buffer is specified for a cut, change or yank command, the text concerned re‐\nplaces the previous contents of the specified buffer. If a named buffer is specified\nusing a capital, the newly cut text is appended to the buffer instead of overwriting\nit. When using the \" buffer, nothing happens. This can be useful for deleting text\nwithout affecting any buffers.\n\nIf no buffer is specified for a cut or change command, \"1 is used, and the contents of\n\"1 to \"8 are each shifted along one buffer; the contents of \"9 is lost. If no buffer\nis specified for a yank command, \"0 is used. Finally, a paste command without a speci‐\nfied buffer will paste the text from the most recent command regardless of any buffer\nthat might have been used with that command.\n\nWhen called from a widget function by the zle command, the buffer can optionally be\nspecified with an argument. For example,\n\nzle vi-set-buffer A\n" }, { "name": "vi-set-mark (unbound)", "content": "Set the specified mark at the cursor position.\n\nset-mark-command (^@) (unbound) (unbound)\nSet the mark at the cursor position. If called with a negative numeric argument, do\nnot set the mark but deactivate the region so that it is no longer highlighted (it is\nstill usable for other purposes). Otherwise the region is marked as active.\n\nspell-word (ESC-$ ESC-S ESC-s) (unbound) (unbound)\nAttempt spelling correction on the current word.\n" }, { "name": "split-undo", "content": "Breaks the undo sequence at the current change. This is useful in vi mode as changes\nmade in insert mode are coalesced on entering command mode. Similarly, undo will nor‐\nmally revert as one all the changes made by a user-defined widget.\n" }, { "name": "undefined-key", "content": "This command is executed when a key sequence that is not bound to any command is\ntyped. By default it beeps.\n\nundo (^ ^Xu ^X^U) (u) (unbound)\nIncrementally undo the last text modification. When called from a user-defined wid‐\nget, takes an optional argument indicating a previous state of the undo history as re‐\nturned by the UNDOCHANGENO variable; modifications are undone until that state is\nreached, subject to any limit imposed by the UNDOLIMITNO variable.\n\nNote that when invoked from vi command mode, the full prior change made in insert mode\nis reverted, the changes having been merged when command mode was selected.\n" }, { "name": "redo (unbound)", "content": "Incrementally redo undone text modifications.\n" }, { "name": "vi-undo-change (unbound)", "content": "Undo the last text modification. If repeated, redo the modification.\n" }, { "name": "visual-mode (unbound)", "content": "Toggle vim-style visual selection mode. If line-wise visual mode is currently enabled\nthen it is changed to being character-wise. If used following an operator, it forces\nthe subsequent movement command to be treated as a character-wise movement.\n" }, { "name": "visual-line-mode (unbound)", "content": "Toggle vim-style line-wise visual selection mode. If character-wise visual mode is\ncurrently enabled then it is changed to being line-wise. If used following an opera‐\ntor, it forces the subsequent movement command to be treated as a line-wise movement.\n\nwhat-cursor-position (^X=) (ga) (unbound)\nPrint the character under the cursor, its code as an octal, decimal and hexadecimal\nnumber, the current cursor position within the buffer and the column of the cursor in\nthe current line.\n" }, { "name": "where-is", "content": "Read the name of an editor command and print the listing of key sequences that invoke\nthe specified command. A restricted set of editing functions is available in the\nmini-buffer. Keys are looked up in the special command keymap, and if not found there\nin the main keymap.\n\nwhich-command (ESC-?) (unbound) (unbound)\nPush the buffer onto the buffer stack, and execute the command `which-command cmd'.\nwhere cmd is the current command. which-command is normally aliased to whence.\n" }, { "name": "vi-digit-or-beginning-of-line (unbound)", "content": "If the last command executed was a digit as part of an argument, continue the argu‐\nment. Otherwise, execute vi-beginning-of-line.\n" }, { "name": "Text Objects", "content": "Text objects are commands that can be used to select a block of text according to some crite‐\nria. They are a feature of the vim text editor and so are primarily intended for use with vi\noperators or from visual selection mode. However, they can also be used from vi-insert or\nemacs mode. Key bindings listed below apply to the viopp and visual keymaps.\n\nselect-a-blank-word (aW)\nSelect a word including adjacent blanks, where a word is defined as a series of\nnon-blank characters. With a numeric argument, multiple words will be selected.\n\nselect-a-shell-word (aa)\nSelect the current command argument applying the normal rules for quoting.\n\nselect-a-word (aw)\nSelect a word including adjacent blanks, using the normal vi-style word definition.\nWith a numeric argument, multiple words will be selected.\n\nselect-in-blank-word (iW)\nSelect a word, where a word is defined as a series of non-blank characters. With a nu‐\nmeric argument, multiple words will be selected.\n\nselect-in-shell-word (ia)\nSelect the current command argument applying the normal rules for quoting. If the ar‐\ngument begins and ends with matching quote characters, these are not included in the\nselection.\n\nselect-in-word (iw)\nSelect a word, using the normal vi-style word definition. With a numeric argument,\nmultiple words will be selected.\n" } ] }, "CHARACTER HIGHLIGHTING": { "content": "The line editor has the ability to highlight characters or regions of the line that have a\nparticular significance. This is controlled by the array parameter zlehighlight, if it has\nbeen set by the user.\n\nIf the parameter contains the single entry none all highlighting is turned off. Note the pa‐\nrameter is still expected to be an array.\n\nOtherwise each entry of the array should consist of a word indicating a context for high‐\nlighting, then a colon, then a comma-separated list of the types of highlighting to apply in\nthat context.\n\nThe contexts available for highlighting are the following:\n", "subsections": [ { "name": "default", "content": "Any text within the command line not affected by any other highlighting. Text outside\nthe editable area of the command line is not affected.\n" }, { "name": "isearch", "content": "When one of the incremental history search widgets is active, the area of the command\nline matched by the search string or pattern.\n\nregion The currently selected text. In emacs terminology, this is referred to as the region\nand is bounded by the cursor (point) and the mark. The region is only highlighted if\nit is active, which is the case after the mark is modified with set-mark-command or\nexchange-point-and-mark. Note that whether or not the region is active has no effect\non its use within emacs style widgets, it simply determines whether it is highlighted.\nIn vi mode, the region corresponds to selected text in visual mode.\n" }, { "name": "special", "content": "Individual characters that have no direct printable representation but are shown in a\nspecial manner by the line editor. These characters are described below.\n\nsuffix This context is used in completion for characters that are marked as suffixes that\nwill be removed if the completion ends at that point, the most obvious example being a\nslash (/) after a directory name. Note that suffix removal is configurable; the cir‐\ncumstances under which the suffix will be removed may differ for different comple‐\ntions.\n\npaste Following a command to paste text, the characters that were inserted.\n\nWhen regionhighlight is set, the contexts that describe a region -- isearch, region, suffix,\nand paste -- are applied first, then regionhighlight is applied, then the remaining\nzlehighlight contexts are applied. If a particular character is affected by multiple speci‐\nfications, the last specification wins.\n\nzlehighlight may contain additional fields for controlling how terminal sequences to change\ncolours are output. Each of the following is followed by a colon and a string in the same\nform as for key bindings. This will not be necessary for the vast majority of terminals as\nthe defaults shown in parentheses are widely used.\n\nfgstartcode (\\e[3)\nThe start of the escape sequence for the foreground colour. This is followed by one\nto three ASCII digits representing the colour. Only used for palette colors, i.e. not\n24-bit colors specified via a color triplet.\n\nfgdefaultcode (9)\nThe number to use instead of the colour to reset the default foreground colour.\n\nfgendcode (m)\nThe end of the escape sequence for the foreground colour.\n\nbgstartcode (\\e[4)\nThe start of the escape sequence for the background colour. See fgstartcode above.\n\nbgdefaultcode (9)\nThe number to use instead of the colour to reset the default background colour.\n\nbgendcode (m)\nThe end of the escape sequence for the background colour.\n\nThe available types of highlighting are the following. Note that not all types of highlight‐\ning are available on all terminals:\n\nnone No highlighting is applied to the given context. It is not useful for this to appear\nwith other types of highlighting; it is used to override a default.\n\nfg=colour\nThe foreground colour should be set to colour, a decimal integer, the name of one of\nthe eight most widely-supported colours or as a `#' followed by an RGB triplet in\nhexadecimal format.\n\nNot all terminals support this and, of those that do, not all provide facilities to\ntest the support, hence the user should decide based on the terminal type. Most ter‐\nminals support the colours black, red, green, yellow, blue, magenta, cyan and white,\nwhich can be set by name. In addition. default may be used to set the terminal's de‐\nfault foreground colour. Abbreviations are allowed; b or bl selects black. Some ter‐\nminals may generate additional colours if the bold attribute is also present.\n\nOn recent terminals and on systems with an up-to-date terminal database the number of\ncolours supported may be tested by the command `echotc Co'; if this succeeds, it indi‐\ncates a limit on the number of colours which will be enforced by the line editor. The\nnumber of colours is in any case limited to 256 (i.e. the range 0 to 255).\n\nSome modern terminal emulators have support for 24-bit true colour (16 million\ncolours). In this case, the hex triplet format can be used. This consists of a `#'\nfollowed by either a three or six digit hexadecimal number describing the red, green\nand blue components of the colour. Hex triplets can also be used with 88 and 256\ncolour terminals via the zsh/nearcolor module (see zshmodules(1)).\n\nColour is also known as color.\n\nbg=colour\nThe background colour should be set to colour. This works similarly to the foreground\ncolour, except the background is not usually affected by the bold attribute.\n\nbold The characters in the given context are shown in a bold font. Not all terminals dis‐\ntinguish bold fonts.\n" }, { "name": "standout", "content": "The characters in the given context are shown in the terminal's standout mode. The\nactual effect is specific to the terminal; on many terminals it is inverse video. On\nsome such terminals, where the cursor does not blink it appears with standout mode\nnegated, making it less than clear where the cursor actually is. On such terminals\none of the other effects may be preferable for highlighting the region and matched\nsearch string.\n" }, { "name": "underline", "content": "The characters in the given context are shown underlined. Some terminals show the\nforeground in a different colour instead; in this case whitespace will not be high‐\nlighted.\n\nThe characters described above as `special' are as follows. The formatting described here is\nused irrespective of whether the characters are highlighted:\n\nASCII control characters\nControl characters in the ASCII range are shown as `^' followed by the base character.\n\nUnprintable multibyte characters\nThis item applies to control characters not in the ASCII range, plus other characters\nas follows. If the MULTIBYTE option is in effect, multibyte characters not in the\nASCII character set that are reported as having zero width are treated as combining\ncharacters when the option COMBININGCHARS is on. If the option is off, or if a char‐\nacter appears where a combining character is not valid, the character is treated as\nunprintable.\n\nUnprintable multibyte characters are shown as a hexadecimal number between angle\nbrackets. The number is the code point of the character in the wide character set;\nthis may or may not be Unicode, depending on the operating system.\n\nInvalid multibyte characters\nIf the MULTIBYTE option is in effect, any sequence of one or more bytes that does not\nform a valid character in the current character set is treated as a series of bytes\neach shown as a special character. This case can be distinguished from other unprint‐\nable characters as the bytes are represented as two hexadecimal digits between angle\nbrackets, as distinct from the four or eight digits that are used for unprintable\ncharacters that are nonetheless valid in the current character set.\n\nNot all systems support this: for it to work, the system's representation of wide\ncharacters must be code values from the Universal Character Set, as defined by IS0\n10646 (also known as Unicode).\n\nWrapped double-width characters\nWhen a double-width character appears in the final column of a line, it is instead\nshown on the next line. The empty space left in the original position is highlighted\nas a special character.\n\nIf zlehighlight is not set or no value applies to a particular context, the defaults applied\nare equivalent to\n\nzlehighlight=(region:standout special:standout\nsuffix:bold isearch:underline paste:standout)\n\ni.e. both the region and special characters are shown in standout mode.\n\nWithin widgets, arbitrary regions may be highlighted by setting the special array parameter\nregionhighlight; see above.\n\nZSHCOMPWID(1) General Commands Manual ZSHCOMPWID(1)\n\n\n" } ] }, "COMPLETION SPECIAL PARAMETERS": { "content": "The parameters ZLEREMOVESUFFIXCHARS and ZLESPACESUFFIXCHARS are used by the completion\nmechanism, but are not special. See Parameters Used By The Shell in zshparam(1).\n\nInside completion widgets, and any functions called from them, some parameters have special\nmeaning; outside these functions they are not special to the shell in any way. These parame‐\nters are used to pass information between the completion code and the completion widget. Some\nof the builtin commands and the condition codes use or change the current values of these pa‐\nrameters. Any existing values will be hidden during execution of completion widgets; except\nfor compstate, the parameters are reset on each function exit (including nested function\ncalls from within the completion widget) to the values they had when the function was en‐\ntered.\n\nCURRENT\nThis is the number of the current word, i.e. the word the cursor is currently on in\nthe words array. Note that this value is only correct if the ksharrays option is not\nset.\n\nIPREFIX\nInitially this will be set to the empty string. This parameter functions like PREFIX;\nit contains a string which precedes the one in PREFIX and is not considered part of\nthe list of matches. Typically, a string is transferred from the beginning of PREFIX\nto the end of IPREFIX, for example:\n\nIPREFIX=${PREFIX%%\\=*}=\nPREFIX=${PREFIX#*=}\n\ncauses the part of the prefix up to and including the first equal sign not to be\ntreated as part of a matched string. This can be done automatically by the compset\nbuiltin, see below.\n\nISUFFIX\nAs IPREFIX, but for a suffix that should not be considered part of the matches; note\nthat the ISUFFIX string follows the SUFFIX string.\n\nPREFIX Initially this will be set to the part of the current word from the beginning of the\nword up to the position of the cursor; it may be altered to give a common prefix for\nall matches.\n\nQIPREFIX\nThis parameter is read-only and contains the quoted string up to the word being com‐\npleted. E.g. when completing `\"foo', this parameter contains the double quote. If the\n-q option of compset is used (see below), and the original string was `\"foo bar' with\nthe cursor on the `bar', this parameter contains `\"foo '.\n\nQISUFFIX\nLike QIPREFIX, but containing the suffix.\n\nSUFFIX Initially this will be set to the part of the current word from the cursor position to\nthe end; it may be altered to give a common suffix for all matches. It is most useful\nwhen the option COMPLETEINWORD is set, as otherwise the whole word on the command\nline is treated as a prefix.\n", "subsections": [ { "name": "compstate", "content": "This is an associative array with various keys and values that the completion code\nuses to exchange information with the completion widget. The keys are:\n\nallquotes\nThe -q option of the compset builtin command (see below) allows a quoted string\nto be broken into separate words; if the cursor is on one of those words, that\nword will be completed, possibly invoking `compset -q' recursively. With this\nkey it is possible to test the types of quoted strings which are currently bro‐\nken into parts in this fashion. Its value contains one character for each\nquoting level. The characters are a single quote or a double quote for strings\nquoted with these characters, a dollars sign for strings quoted with $'...' and\na backslash for strings not starting with a quote character. The first charac‐\nter in the value always corresponds to the innermost quoting level.\n\ncontext\nThis will be set by the completion code to the overall context in which comple‐\ntion is attempted. Possible values are:\n\narrayvalue\nwhen completing inside the value of an array parameter assignment; in\nthis case the words array contains the words inside the parentheses.\n\nbraceparameter\nwhen completing the name of a parameter in a parameter expansion begin‐\nning with ${. This context will also be set when completing parameter\nflags following ${(; the full command line argument is presented and the\nhandler must test the value to be completed to ascertain that this is\nthe case.\n\nassignparameter\nwhen completing the name of a parameter in a parameter assignment.\n\ncommand\nwhen completing for a normal command (either in command position or for\nan argument of the command).\n\ncondition\nwhen completing inside a `[[...]]' conditional expression; in this case\nthe words array contains only the words inside the conditional expres‐\nsion.\n\nmath when completing in a mathematical environment such as a `((...))' con‐\nstruct.\n\nparameter\nwhen completing the name of a parameter in a parameter expansion begin‐\nning with $ but not ${.\n\nredirect\nwhen completing after a redirection operator.\n\nsubscript\nwhen completing inside a parameter subscript.\n\nvalue when completing the value of a parameter assignment.\n\nexact Controls the behaviour when the RECEXACT option is set. It will be set to ac‐‐\ncept if an exact match would be accepted, and will be unset otherwise.\n\nIf it was set when at least one match equal to the string on the line was gen‐\nerated, the match is accepted.\n\nexactstring\nThe string of an exact match if one was found, otherwise unset.\n\nignored\nThe number of words that were ignored because they matched one of the patterns\ngiven with the -F option to the compadd builtin command.\n\ninsert This controls the manner in which a match is inserted into the command line.\nOn entry to the widget function, if it is unset the command line is not to be\nchanged; if set to unambiguous, any prefix common to all matches is to be in‐\nserted; if set to automenu-unambiguous, the common prefix is to be inserted and\nthe next invocation of the completion code may start menu completion (due to\nthe AUTOMENU option being set); if set to menu or automenu menu completion\nwill be started for the matches currently generated (in the latter case this\nwill happen because the AUTOMENU is set). The value may also contain the\nstring `tab' when the completion code would normally not really do completion,\nbut only insert the TAB character.\n\nOn exit it may be set to any of the values above (where setting it to the empty\nstring is the same as unsetting it), or to a number, in which case the match\nwhose number is given will be inserted into the command line. Negative numbers\ncount backward from the last match (with `-1' selecting the last match) and\nout-of-range values are wrapped around, so that a value of zero selects the\nlast match and a value one more than the maximum selects the first. Unless the\nvalue of this key ends in a space, the match is inserted as in a menu comple‐\ntion, i.e. without automatically appending a space.\n\nBoth menu and automenu may also specify the number of the match to insert,\ngiven after a colon. For example, `menu:2' says to start menu completion, be‐\nginning with the second match.\n\nNote that a value containing the substring `tab' makes the matches generated be\nignored and only the TAB be inserted.\n\nFinally, it may also be set to all, which makes all matches generated be in‐\nserted into the line.\n\ninsertpositions\nWhen the completion system inserts an unambiguous string into the line, there\nmay be multiple places where characters are missing or where the character in‐\nserted differs from at least one match. The value of this key contains a colon\nseparated list of all these positions, as indexes into the command line.\n\nlastprompt\nIf this is set to a non-empty string for every match added, the completion code\nwill move the cursor back to the previous prompt after the list of completions\nhas been displayed. Initially this is set or unset according to the AL‐‐\nWAYSLASTPROMPT option.\n\nlist This controls whether or how the list of matches will be displayed. If it is\nunset or empty they will never be listed; if its value begins with list, they\nwill always be listed; if it begins with autolist or ambiguous, they will be\nlisted when the AUTOLIST or LISTAMBIGUOUS options respectively would normally\ncause them to be.\n\nIf the substring force appears in the value, this makes the list be shown even\nif there is only one match. Normally, the list would be shown only if there are\nat least two matches.\n\nThe value contains the substring packed if the LISTPACKED option is set. If\nthis substring is given for all matches added to a group, this group will show\nthe LISTPACKED behavior. The same is done for the LISTROWSFIRST option with\nthe substring rows.\n\nFinally, if the value contains the string explanations, only the explanation\nstrings, if any, will be listed and if it contains messages, only the messages\n(added with the -x option of compadd) will be listed. If it contains both ex‐‐\nplanations and messages both kinds of explanation strings will be listed. It\nwill be set appropriately on entry to a completion widget and may be changed\nthere.\n\nlistlines\nThis gives the number of lines that are needed to display the full list of com‐\npletions. Note that to calculate the total number of lines to display you need\nto add the number of lines needed for the command line to this value, this is\navailable as the value of the BUFFERLINES special parameter.\n\nlistmax\nInitially this is set to the value of the LISTMAX parameter. It may be set to\nany other value; when the widget exits this value will be used in the same way\nas the value of LISTMAX.\n\nnmatches\nThe number of matches generated and accepted by the completion code so far.\n\noldinsert\nOn entry to the widget this will be set to the number of the match of an old\nlist of completions that is currently inserted into the command line. If no\nmatch has been inserted, this is unset.\n\nAs with oldlist, the value of this key will only be used if it is the string\nkeep. If it was set to this value by the widget and there was an old match in‐\nserted into the command line, this match will be kept and if the value of the\ninsert key specifies that another match should be inserted, this will be in‐\nserted after the old one.\n\noldlist\nThis is set to yes if there is still a valid list of completions from a previ‐\nous completion at the time the widget is invoked. This will usually be the\ncase if and only if the previous editing operation was a completion widget or\none of the builtin completion functions. If there is a valid list and it is\nalso currently shown on the screen, the value of this key is shown.\n\nAfter the widget has exited the value of this key is only used if it was set to\nkeep. In this case the completion code will continue to use this old list. If\nthe widget generated new matches, they will not be used.\n\nparameter\nThe name of the parameter when completing in a subscript or in the value of a\nparameter assignment.\n\npatterninsert\nNormally this is set to menu, which specifies that menu completion will be used\nwhenever a set of matches was generated using pattern matching. If it is set\nto any other non-empty string by the user and menu completion is not selected\nby other option settings, the code will instead insert any common prefix for\nthe generated matches as with normal completion.\n\npatternmatch\nLocally controls the behaviour given by the GLOBCOMPLETE option. Initially it\nis set to `*' if and only if the option is set. The completion widget may set\nit to this value, to an empty string (which has the same effect as unsetting\nit), or to any other non-empty string. If it is non-empty, unquoted metachar‐\nacters on the command line will be treated as patterns; if it is `*', then ad‐\nditionally a wildcard `*' is assumed at the cursor position; if it is empty or\nunset, metacharacters will be treated literally.\n\nNote that the matcher specifications given to the compadd builtin command are\nnot used if this is set to a non-empty string.\n\nquote When completing inside quotes, this contains the quotation character (i.e. ei‐\nther a single quote, a double quote, or a backtick). Otherwise it is unset.\n\nquoting\nWhen completing inside single quotes, this is set to the string single; inside\ndouble quotes, the string double; inside backticks, the string backtick. Oth‐\nerwise it is unset.\n\nredirect\nThe redirection operator when completing in a redirection position, i.e. one of\n<, >, etc.\n\nrestore\nThis is set to auto before a function is entered, which forces the special pa‐\nrameters mentioned above (words, CURRENT, PREFIX, IPREFIX, SUFFIX, and ISUFFIX)\nto be restored to their previous values when the function exits. If a func‐\ntion unsets it or sets it to any other string, they will not be restored.\n\ntoend Specifies the occasions on which the cursor is moved to the end of a string\nwhen a match is inserted. On entry to a widget function, it may be single if\nthis will happen when a single unambiguous match was inserted or match if it\nwill happen any time a match is inserted (for example, by menu completion; this\nis likely to be the effect of the ALWAYSTOEND option).\n\nOn exit, it may be set to single as above. It may also be set to always, or to\nthe empty string or unset; in those cases the cursor will be moved to the end\nof the string always or never respectively. Any other string is treated as\nmatch.\n\nunambiguous\nThis key is read-only and will always be set to the common (unambiguous) prefix\nthe completion code has generated for all matches added so far.\n\nunambiguouscursor\nThis gives the position the cursor would be placed at if the common prefix in\nthe unambiguous key were inserted, relative to the value of that key. The cur‐\nsor would be placed before the character whose index is given by this key.\n\nunambiguouspositions\nThis contains all positions where characters in the unambiguous string are\nmissing or where the character inserted differs from at least one of the\nmatches. The positions are given as indexes into the string given by the value\nof the unambiguous key.\n\nvared If completion is called while editing a line using the vared builtin, the value\nof this key is set to the name of the parameter given as an argument to vared.\nThis key is only set while a vared command is active.\n\nwords This array contains the words present on the command line currently being edited.\n" } ] }, "COMPLETION BUILTIN COMMANDS": { "content": "compadd [ -akqQfenUl12C ] [ -F array ]\n[-P prefix ] [ -S suffix ]\n[-p hidden-prefix ] [ -s hidden-suffix ]\n[-i ignored-prefix ] [ -I ignored-suffix ]\n[-W file-prefix ] [ -d array ]\n[-J group-name ] [ -X explanation ] [ -x message ]\n[-V group-name ] [ -o [ order ] ]\n[-r remove-chars ] [ -R remove-func ]\n[-D array ] [ -O array ] [ -A array ]\n[-E number ]\n[-M match-spec ] [ -- ] [ words ... ]\n\nThis builtin command can be used to add matches directly and control all the informa‐\ntion the completion code stores with each possible match. The return status is zero if\nat least one match was added and non-zero if no matches were added.\n\nThe completion code breaks the string to complete into seven fields in the order:\n\n\n\nThe first field is an ignored prefix taken from the command line, the contents of the\nIPREFIX parameter plus the string given with the -i option. With the -U option, only\nthe string from the -i option is used. The field is an optional prefix string\ngiven with the -P option. The field is a string that is considered part of the\nmatch but that should not be shown when listing completions, given with the -p option;\nfor example, functions that do filename generation might specify a common path prefix\nthis way. is the part of the match that should appear in the list of comple‐\ntions, i.e. one of the words given at the end of the compadd command line. The suf‐\nfixes , and correspond to the prefixes , and \nand are given by the options -s, -S and -I, respectively.\n\nThe supported flags are:\n\n-P prefix\nThis gives a string to be inserted before the given words. The string given is\nnot considered as part of the match and any shell metacharacters in it will not\nbe quoted when the string is inserted.\n\n-S suffix\nLike -P, but gives a string to be inserted after the match.\n\n-p hidden-prefix\nThis gives a string that should be inserted into the command line before the\nmatch but that should not appear in the list of matches. Unless the -U option\nis given, this string must be matched as part of the string on the command\nline.\n\n-s hidden-suffix\nLike `-p', but gives a string to insert after the match.\n\n-i ignored-prefix\nThis gives a string to insert into the command line just before any string\ngiven with the `-P' option. Without `-P' the string is inserted before the\nstring given with `-p' or directly before the match.\n\n-I ignored-suffix\nLike -i, but gives an ignored suffix.\n\n-a With this flag the words are taken as names of arrays and the possible matches\nare their values. If only some elements of the arrays are needed, the words\nmay also contain subscripts, as in `foo[2,-1]'.\n\n-k With this flag the words are taken as names of associative arrays and the pos‐\nsible matches are their keys. As for -a, the words may also contain sub‐\nscripts, as in `foo[(R)*bar*]'.\n\n-d array\nThis adds per-match display strings. The array should contain one element per\nword given. The completion code will then display the first element instead of\nthe first word, and so on. The array may be given as the name of an array pa‐\nrameter or directly as a space-separated list of words in parentheses.\n\nIf there are fewer display strings than words, the leftover words will be dis‐\nplayed unchanged and if there are more display strings than words, the leftover\ndisplay strings will be silently ignored.\n\n-l This option only has an effect if used together with the -d option. If it is\ngiven, the display strings are listed one per line, not arrayed in columns.\n\n-o [ order ]\nThis controls the order in which matches are sorted. order is a comma-separated\nlist comprising the following possible values. These values can be abbreviated\nto their initial two or three characters. Note that the order forms part of\nthe group name space so matches with different orderings will not be in the\nsame group.\n\nmatch If given, the order of the output is determined by the match strings;\notherwise it is determined by the display strings (i.e. the strings\ngiven by the -d option). This is the default if `-o' is specified but\nthe order argument is omitted.\n\nnosort This specifies that the matches are pre-sorted and their order should be\npreserved. This value only makes sense alone and cannot be combined\nwith any others.\n\nnumeric\nIf the matches include numbers, sort them numerically rather than lexi‐\ncographically.\n\nreverse\nArrange the matches backwards by reversing the sort ordering.\n\n-J group-name\nGives the name of the group of matches the words should be stored in.\n\n-V group-name\nLike -J but naming an unsorted group. This option is identical to the combina‐\ntion of -J and -o nosort.\n\n-1 If given together with the -V option, makes only consecutive duplicates in the\ngroup be removed. If combined with the -J option, this has no visible effect.\nNote that groups with and without this flag are in different name spaces.\n\n-2 If given together with the -J or -V option, makes all duplicates be kept.\nAgain, groups with and without this flag are in different name spaces.\n\n-X explanation\nThe explanation string will be printed with the list of matches, above the\ngroup currently selected.\n\nWithin the explanation, the following sequences may be used to specify output\nattributes as described in the section EXPANSION OF PROMPT SEQUENCES in zsh‐\nmisc(1): `%B', `%S', `%U', `%F', `%K' and their lower case counterparts, as\nwell as `%{...%}'. `%F', `%K' and `%{...%}' take arguments in the same form as\nprompt expansion. (Note that the sequence `%G' is not available; an argument\nto `%{' should be used instead.) The sequence `%%' produces a literal `%'.\n\nThese sequences are most often employed by users when customising the format\nstyle (see zshcompsys(1)), but they must also be taken into account when writ‐\ning completion functions, as passing descriptions with unescaped `%' characters\nto utility functions such as arguments and message may produce unexpected re‐\nsults. If arbitrary text is to be passed in a description, it can be escaped\nusing e.g. ${mystr//\\%/%%}.\n\n-x message\nLike -X, but the message will be printed even if there are no matches in the\ngroup.\n\n-q The suffix given with -S will be automatically removed if the next character\ntyped is a blank or does not insert anything, or if the suffix consists of only\none character and the next character typed is the same character.\n\n-r remove-chars\nThis is a more versatile form of the -q option. The suffix given with -S or\nthe slash automatically added after completing directories will be automati‐\ncally removed if the next character typed inserts one of the characters given\nin the remove-chars. This string is parsed as a characters class and under‐\nstands the backslash sequences used by the print command. For example, `-r\n\"a-z\\t\"' removes the suffix if the next character typed inserts a lower case\ncharacter or a TAB, and `-r \"^0-9\"' removes the suffix if the next character\ntyped inserts anything but a digit. One extra backslash sequence is understood\nin this string: `\\-' stands for all characters that insert nothing. Thus `-S\n\"=\" -q' is the same as `-S \"=\" -r \"= \\t\\n\\-\"'.\n\nThis option may also be used without the -S option; then any automatically\nadded space will be removed when one of the characters in the list is typed.\n\n-R remove-func\nThis is another form of the -r option. When a suffix has been inserted and the\ncompletion accepted, the function remove-func will be called after the next\ncharacter typed. It is passed the length of the suffix as an argument and can\nuse the special parameters available in ordinary (non-completion) zle widgets\n(see zshzle(1)) to analyse and modify the command line.\n\n-f If this flag is given, all of the matches built from words are marked as being\nthe names of files. They are not required to be actual filenames, but if they\nare, and the option LISTTYPES is set, the characters describing the types of\nthe files in the completion lists will be shown. This also forces a slash to be\nadded when the name of a directory is completed.\n\n-e This flag can be used to tell the completion code that the matches added are\nparameter names for a parameter expansion. This will make the AUTOPARAMSLASH\nand AUTOPARAMKEYS options be used for the matches.\n\n-W file-prefix\nThis string is a pathname that will be prepended to each of the matches formed\nby the given words together with any prefix specified by the -p option to form\na complete filename for testing. Hence it is only useful if combined with the\n-f flag, as the tests will not otherwise be performed.\n\n-F array\nSpecifies an array containing patterns. Words matching one of these patterns\nare ignored, i.e. not considered to be possible matches.\n\nThe array may be the name of an array parameter or a list of literal patterns\nenclosed in parentheses and quoted, as in `-F \"(*?.o *?.h)\"'. If the name of an\narray is given, the elements of the array are taken as the patterns.\n\n-Q This flag instructs the completion code not to quote any metacharacters in the\nwords when inserting them into the command line.\n\n-M match-spec\nThis gives local match specifications as described below in the section `Com‐\npletion Matching Control'. This option may be given more than once. In this\ncase all match-specs given are concatenated with spaces between them to form\nthe specification string to use. Note that they will only be used if the -U\noption is not given.\n\n-n Specifies that the words added are to be used as possible matches, but are not\nto appear in the completion listing.\n\n-U If this flag is given, all words given will be accepted and no matching will be\ndone by the completion code. Normally this is used in functions that do the\nmatching themselves.\n\n-O array\nIf this option is given, the words are not added to the set of possible comple‐\ntions. Instead, matching is done as usual and all of the words given as argu‐\nments that match the string on the command line will be stored in the array pa‐\nrameter whose name is given as array.\n\n-A array\nAs the -O option, except that instead of those of the words which match being\nstored in array, the strings generated internally by the completion code are\nstored. For example, with a matching specification of `-M \"L:|no=\"', the string\n`nof' on the command line and the string `foo' as one of the words, this option\nstores the string `nofoo' in the array, whereas the -O option stores the `foo'\noriginally given.\n\n-D array\nAs with -O, the words are not added to the set of possible completions. In‐\nstead, the completion code tests whether each word in turn matches what is on\nthe line. If the nth word does not match, the nth element of the array is re‐\nmoved. Elements for which the corresponding word is matched are retained.\n\n-C This option adds a special match which expands to all other matches when in‐\nserted into the line, even those that are added after this option is used. To‐\ngether with the -d option it is possible to specify a string that should be\ndisplayed in the list for this special match. If no string is given, it will\nbe shown as a string containing the strings that would be inserted for the\nother matches, truncated to the width of the screen.\n\n-E number\nThis option adds number empty matches after the words have been added. An\nempty match takes up space in completion listings but will never be inserted in\nthe line and can't be selected with menu completion or menu selection. This\nmakes empty matches only useful to format completion lists and to make explana‐\ntory string be shown in completion lists (since empty matches can be given dis‐\nplay strings with the -d option). And because all but one empty string would\notherwise be removed, this option implies the -V and -2 options (even if an ex‐\nplicit -J option is given). This can be important to note as it affects the\nname space into which matches are added.\n\n-\n-- This flag ends the list of flags and options. All arguments after it will be\ntaken as the words to use as matches even if they begin with hyphens.\n\nExcept for the -M flag, if any of these flags is given more than once, the first one\n(and its argument) will be used.\n\ncompset -p number\ncompset -P [ number ] pattern\ncompset -s number\ncompset -S [ number ] pattern\ncompset -n begin [ end ]\ncompset -N beg-pat [ end-pat ]", "subsections": [ { "name": "compset -q", "content": "This command simplifies modification of the special parameters, while its return sta‐\ntus allows tests on them to be carried out.\n\nThe options are:\n\n-p number\nIf the value of the PREFIX parameter is at least number characters long, the\nfirst number characters are removed from it and appended to the contents of the\nIPREFIX parameter.\n\n-P [ number ] pattern\nIf the value of the PREFIX parameter begins with anything that matches the pat‐\ntern, the matched portion is removed from PREFIX and appended to IPREFIX.\n\nWithout the optional number, the longest match is taken, but if number is\ngiven, anything up to the numberth match is moved. If the number is negative,\nthe numberth longest match is moved. For example, if PREFIX contains the string\n`a=b=c', then compset -P '*\\=' will move the string `a=b=' into the IPREFIX pa‐\nrameter, but compset -P 1 '*\\=' will move only the string `a='.\n\n-s number\nAs -p, but transfer the last number characters from the value of SUFFIX to the\nfront of the value of ISUFFIX.\n\n-S [ number ] pattern\nAs -P, but match the last portion of SUFFIX and transfer the matched portion to\nthe front of the value of ISUFFIX.\n\n-n begin [ end ]\nIf the current word position as specified by the parameter CURRENT is greater\nthan or equal to begin, anything up to the beginth word is removed from the\nwords array and the value of the parameter CURRENT is decremented by begin.\n\nIf the optional end is given, the modification is done only if the current word\nposition is also less than or equal to end. In this case, the words from posi‐\ntion end onwards are also removed from the words array.\n\nBoth begin and end may be negative to count backwards from the last element of\nthe words array.\n\n-N beg-pat [ end-pat ]\nIf one of the elements of the words array before the one at the index given by\nthe value of the parameter CURRENT matches the pattern beg-pat, all elements up\nto and including the matching one are removed from the words array and the\nvalue of CURRENT is changed to point to the same word in the changed array.\n\nIf the optional pattern end-pat is also given, and there is an element in the\nwords array matching this pattern, the parameters are modified only if the in‐\ndex of this word is higher than the one given by the CURRENT parameter (so that\nthe matching word has to be after the cursor). In this case, the words starting\nwith the one matching end-pat are also removed from the words array. If words\ncontains no word matching end-pat, the testing and modification is performed as\nif it were not given.\n\n-q The word currently being completed is split on spaces into separate words, re‐\nspecting the usual shell quoting conventions. The resulting words are stored\nin the words array, and CURRENT, PREFIX, SUFFIX, QIPREFIX, and QISUFFIX are\nmodified to reflect the word part that is completed.\n\nIn all the above cases the return status is zero if the test succeeded and the parame‐\nters were modified and non-zero otherwise. This allows one to use this builtin in\ntests such as:\n\nif compset -P '*\\='; then ...\n\nThis forces anything up to and including the last equal sign to be ignored by the com‐\npletion code.\n\ncompcall [ -TD ]\nThis allows the use of completions defined with the compctl builtin from within com‐\npletion widgets. The list of matches will be generated as if one of the non-widget\ncompletion functions (complete-word, etc.) had been called, except that only compctls\ngiven for specific commands are used. To force the code to try completions defined\nwith the -T option of compctl and/or the default completion (whether defined by com‐‐\npctl -D or the builtin default) in the appropriate places, the -T and/or -D flags can\nbe passed to compcall.\n\nThe return status can be used to test if a matching compctl definition was found. It\nis non-zero if a compctl was found and zero otherwise.\n\nNote that this builtin is defined by the zsh/compctl module.\n" } ] }, "COMPLETION CONDITION CODES": { "content": "The following additional condition codes for use within the [[ ... ]] construct are available\nin completion widgets. These work on the special parameters. All of these tests can also be\nperformed by the compset builtin, but in the case of the condition codes the contents of the\nspecial parameters are not modified.\n", "subsections": [ { "name": "-prefix", "content": "true if the test for the -P option of compset would succeed.\n" }, { "name": "-suffix", "content": "true if the test for the -S option of compset would succeed.\n" }, { "name": "-after", "content": "true if the test of the -N option with only the beg-pat given would succeed.\n" }, { "name": "-between", "content": "true if the test for the -N option with both patterns would succeed.\n" } ] }, "COMPLETION MATCHING CONTROL": { "content": "It is possible by use of the -M option of the compadd builtin command to specify how the\ncharacters in the string to be completed (referred to here as the command line) map onto the\ncharacters in the list of matches produced by the completion code (referred to here as the\ntrial completions). Note that this is not used if the command line contains a glob pattern\nand the GLOBCOMPLETE option is set or the patternmatch of the compstate special association\nis set to a non-empty string.\n\nThe match-spec given as the argument to the -M option (see `Completion Builtin Commands'\nabove) consists of one or more matching descriptions separated by whitespace. Each descrip‐\ntion consists of a letter followed by a colon and then the patterns describing which charac‐\nter sequences on the line match which character sequences in the trial completion. Any se‐\nquence of characters not handled in this fashion must match exactly, as usual.\n\nThe forms of match-spec understood are as follows. In each case, the form with an upper case\ninitial character retains the string already typed on the command line as the final result of\ncompletion, while with a lower case initial character the string on the command line is\nchanged into the corresponding part of the trial completion.\n\nm:lpat=tpat\nM:lpat=tpat\nHere, lpat is a pattern that matches on the command line, corresponding to tpat which\nmatches in the trial completion.\n\nl:lanchor|lpat=tpat\nL:lanchor|lpat=tpat\nl:lanchor||ranchor=tpat\nL:lanchor||ranchor=tpat\nb:lpat=tpat\nB:lpat=tpat\nThese letters are for patterns that are anchored by another pattern on the left side.\nMatching for lpat and tpat is as for m and M, but the pattern lpat matched on the com‐\nmand line must be preceded by the pattern lanchor. The lanchor can be blank to anchor\nthe match to the start of the command line string; otherwise the anchor can occur any‐\nwhere, but must match in both the command line and trial completion strings.\n\nIf no lpat is given but a ranchor is, this matches the gap between substrings matched\nby lanchor and ranchor. Unlike lanchor, the ranchor only needs to match the trial com‐\npletion string.\n\nThe b and B forms are similar to l and L with an empty anchor, but need to match only\nthe beginning of the word on the command line or trial completion, respectively.\n\nr:lpat|ranchor=tpat\nR:lpat|ranchor=tpat\nr:lanchor||ranchor=tpat\nR:lanchor||ranchor=tpat\ne:lpat=tpat\nE:lpat=tpat\nAs l, L, b and B, with the difference that the command line and trial completion pat‐\nterns are anchored on the right side. Here an empty ranchor and the e and E forms\nforce the match to the end of the command line or trial completion string.\n\nx: This form is used to mark the end of matching specifications: subsequent specifica‐\ntions are ignored. In a single standalone list of specifications this has no use but\nwhere matching specifications are accumulated, such as from nested function calls, it\ncan allow one function to override another.\n\nEach lpat, tpat or anchor is either an empty string or consists of a sequence of literal\ncharacters (which may be quoted with a backslash), question marks, character classes, and\ncorrespondence classes; ordinary shell patterns are not used. Literal characters match only\nthemselves, question marks match any character, and character classes are formed as for glob‐\nbing and match any character in the given set.\n\nCorrespondence classes are defined like character classes, but with two differences: they are\ndelimited by a pair of braces, and negated classes are not allowed, so the characters ! and ^\nhave no special meaning directly after the opening brace. They indicate that a range of\ncharacters on the line match a range of characters in the trial completion, but (unlike ordi‐\nnary character classes) paired according to the corresponding position in the sequence. For\nexample, to make any ASCII lower case letter on the line match the corresponding upper case\nletter in the trial completion, you can use `m:{a-z}={A-Z}' (however, see below for the rec‐\nommended form for this). More than one pair of classes can occur, in which case the first\nclass before the = corresponds to the first after it, and so on. If one side has more such\nclasses than the other side, the superfluous classes behave like normal character classes.\nIn anchor patterns correspondence classes also behave like normal character classes.\n\nThe standard `[:name:]' forms described for standard shell patterns (see the section FILENAME\nGENERATION in zshexpn(1)) may appear in correspondence classes as well as normal character\nclasses. The only special behaviour in correspondence classes is if the form on the left and\nthe form on the right are each one of [:upper:], [:lower:]. In these cases the character in\nthe word and the character on the line must be the same up to a difference in case. Hence to\nmake any lower case character on the line match the corresponding upper case character in the\ntrial completion you can use `m:{[:lower:]}={[:upper:]}'. Although the matching system does\nnot yet handle multibyte characters, this is likely to be a future extension, at which point\nthis syntax will handle arbitrary alphabets; hence this form, rather than the use of explicit\nranges, is the recommended form. In other cases `[:name:]' forms are allowed. If the two\nforms on the left and right are the same, the characters must match exactly. In remaining\ncases, the corresponding tests are applied to both characters, but they are not otherwise\nconstrained; any matching character in one set goes with any matching character in the other\nset: this is equivalent to the behaviour of ordinary character classes.\n\nThe pattern tpat may also be one or two stars, `*' or `'. This means that the pattern on\nthe command line can match any number of characters in the trial completion. In this case the\npattern must be anchored (on either side); in the case of a single star, the anchor then de‐\ntermines how much of the trial completion is to be included -- only the characters up to the\nnext appearance of the anchor will be matched. With two stars, substrings matched by the an‐\nchor can be matched, too.\n\nExamples:\n\nThe keys of the options association defined by the parameter module are the option names in\nall-lower-case form, without underscores, and without the optional no at the beginning even\nthough the builtins setopt and unsetopt understand option names with upper case letters, un‐\nderscores, and the optional no. The following alters the matching rules so that the prefix\nno and any underscore are ignored when trying to match the trial completions generated and\nupper case letters on the line match the corresponding lower case letters in the words:\n\ncompadd -M 'L:|[nN][oO]= M:= M:{[:upper:]}={[:lower:]}' - \\\n${(k)options}\n\nThe first part says that the pattern `[nN][oO]' at the beginning (the empty anchor before the\npipe symbol) of the string on the line matches the empty string in the list of words gener‐\nated by completion, so it will be ignored if present. The second part does the same for an\nunderscore anywhere in the command line string, and the third part uses correspondence\nclasses so that any upper case letter on the line matches the corresponding lower case letter\nin the word. The use of the upper case forms of the specification characters (L and M) guar‐\nantees that what has already been typed on the command line (in particular the prefix no)\nwill not be deleted.\n\nNote that the use of L in the first part means that it matches only when at the beginning of\nboth the command line string and the trial completion. I.e., the string `NOf' would not be\ncompleted to `NOfoo', nor would `NONOf' be completed to `NONOfoo' because of the leading\nunderscore or the second `NO' on the line which makes the pattern fail even though they are\notherwise ignored. To fix this, one would use `B:[nN][oO]=' instead of the first part. As de‐\nscribed above, this matches at the beginning of the trial completion, independent of other\ncharacters or substrings at the beginning of the command line word which are ignored by the\nsame or other match-specs.\n\nThe second example makes completion case insensitive. This is just the same as in the option\nexample, except here we wish to retain the characters in the list of completions:\n\ncompadd -M 'm:{[:lower:]}={[:upper:]}' ...\n\nThis makes lower case letters match their upper case counterparts. To make upper case let‐\nters match the lower case forms as well:\n\ncompadd -M 'm:{[:lower:][:upper:]}={[:upper:][:lower:]}' ...\n\nA nice example for the use of * patterns is partial word completion. Sometimes you would like\nto make strings like `c.s.u' complete to strings like `comp.source.unix', i.e. the word on\nthe command line consists of multiple parts, separated by a dot in this example, where each\npart should be completed separately -- note, however, that the case where each part of the\nword, i.e. `comp', `source' and `unix' in this example, is to be completed from separate sets\nof matches is a different problem to be solved by the implementation of the completion wid‐\nget. The example can be handled by:\n\ncompadd -M 'r:|.=* r:|=*' \\\n- comp.sources.unix comp.sources.misc ...\n\nThe first specification says that lpat is the empty string, while anchor is a dot; tpat is *,\nso this can match anything except for the `.' from the anchor in the trial completion word.\nSo in `c.s.u', the matcher sees `c', followed by the empty string, followed by the anchor\n`.', and likewise for the second dot, and replaces the empty strings before the anchors, giv‐\ning `c[omp].s[ources].u[nix]', where the last part of the completion is just as normal.\n\nWith the pattern shown above, the string `c.u' could not be completed to `comp.sources.unix'\nbecause the single star means that no dot (matched by the anchor) can be skipped. By using\ntwo stars as in `r:|.=', however, `c.u' could be completed to `comp.sources.unix'. This\nalso shows that in some cases, especially if the anchor is a real pattern, like a character\nclass, the form with two stars may result in more matches than one would like.\n\nThe second specification is needed to make this work when the cursor is in the middle of the\nstring on the command line and the option COMPLETEINWORD is set. In this case the comple‐\ntion code would normally try to match trial completions that end with the string as typed so\nfar, i.e. it will only insert new characters at the cursor position rather than at the end.\nHowever in our example we would like the code to recognise matches which contain extra char‐\nacters after the string on the line (the `nix' in the example). Hence we say that the empty\nstring at the end of the string on the line matches any characters at the end of the trial\ncompletion.\n\nMore generally, the specification\n\ncompadd -M 'r:|[.,-]=* r:|=*' ...\n\nallows one to complete words with abbreviations before any of the characters in the square\nbrackets. For example, to complete veryverylongfile.c rather than veryverylongheader.h with\nthe above in effect, you can just type very.c before attempting completion.\n\nThe specifications with both a left and a right anchor are useful to complete partial words\nwhose parts are not separated by some special character. For example, in some places strings\nhave to be completed that are formed `LikeThis' (i.e. the separate parts are determined by a\nleading upper case letter) or maybe one has to complete strings with trailing numbers. Here\none could use the simple form with only one anchor as in:\n\ncompadd -M 'r:|[[:upper:]0-9]=* r:|=*' LikeTHIS FooHoo 5foo123 5bar234\n\nBut with this, the string `H' would neither complete to `FooHoo' nor to `LikeTHIS' because in\neach case there is an upper case letter before the `H' and that is matched by the anchor.\nLikewise, a `2' would not be completed. In both cases this could be changed by using\n`r:|[[:upper:]0-9]=', but then `H' completes to both `LikeTHIS' and `FooHoo' and a `2'\nmatches the other strings because characters can be inserted before every upper case letter\nand digit. To avoid this one would use:\n\ncompadd -M 'r:[^[:upper:]0-9]||[[:upper:]0-9]= r:|=*' \\\nLikeTHIS FooHoo foo123 bar234\n\nBy using these two anchors, a `H' matches only upper case `H's that are immediately preceded\nby something matching the left anchor `[^[:upper:]0-9]'. The effect is, of course, that `H'\nmatches only the string `FooHoo', a `2' matches only `bar234' and so on.\n\nWhen using the completion system (see zshcompsys(1)), users can define match specifications\nthat are to be used for specific contexts by using the matcher and matcher-list styles. The\nvalues for the latter will be used everywhere.\n", "subsections": [] }, "COMPLETION WIDGET EXAMPLE": { "content": "The first step is to define the widget:\n\nzle -C complete complete-word complete-files\n\nThen the widget can be bound to a key using the bindkey builtin command:\n\nbindkey '^X\\t' complete\n\nAfter that the shell function complete-files will be invoked after typing control-X and TAB.\nThe function should then generate the matches, e.g.:\n\ncomplete-files () { compadd - * }\n\nThis function will complete files in the current directory matching the current word.\n\n\n\nZSHCOMPSYS(1) General Commands Manual ZSHCOMPSYS(1)\n\n\n", "subsections": [] }, "INITIALIZATION": { "content": "If the system was installed completely, it should be enough to call the shell function\ncompinit from your initialization file; see the next section. However, the function compin‐‐\nstall can be run by a user to configure various aspects of the completion system.\n\nUsually, compinstall will insert code into .zshrc, although if that is not writable it will\nsave it in another file and tell you that file's location. Note that it is up to you to make\nsure that the lines added to .zshrc are actually run; you may, for example, need to move them\nto an earlier place in the file if .zshrc usually returns early. So long as you keep them\nall together (including the comment lines at the start and finish), you can rerun compinstall\nand it will correctly locate and modify these lines. Note, however, that any code you add to\nthis section by hand is likely to be lost if you rerun compinstall, although lines using the\ncommand `zstyle' should be gracefully handled.\n\nThe new code will take effect next time you start the shell, or run .zshrc by hand; there is\nalso an option to make them take effect immediately. However, if compinstall has removed\ndefinitions, you will need to restart the shell to see the changes.\n\nTo run compinstall you will need to make sure it is in a directory mentioned in your fpath\nparameter, which should already be the case if zsh was properly configured as long as your\nstartup files do not remove the appropriate directories from fpath. Then it must be au‐\ntoloaded (`autoload -U compinstall' is recommended). You can abort the installation any time\nyou are being prompted for information, and your .zshrc will not be altered at all; changes\nonly take place right at the end, where you are specifically asked for confirmation.\n", "subsections": [ { "name": "Use of compinit", "content": "This section describes the use of compinit to initialize completion for the current session\nwhen called directly; if you have run compinstall it will be called automatically from your\n.zshrc.\n\nTo initialize the system, the function compinit should be in a directory mentioned in the\nfpath parameter, and should be autoloaded (`autoload -U compinit' is recommended), and then\nrun simply as `compinit'. This will define a few utility functions, arrange for all the nec‐\nessary shell functions to be autoloaded, and will then re-define all widgets that do comple‐\ntion to use the new system. If you use the menu-select widget, which is part of the zsh/com‐‐\nplist module, you should make sure that that module is loaded before the call to compinit so\nthat that widget is also re-defined. If completion styles (see below) are set up to perform\nexpansion as well as completion by default, and the TAB key is bound to expand-or-complete,\ncompinit will rebind it to complete-word; this is necessary to use the correct form of expan‐\nsion.\n\nShould you need to use the original completion commands, you can still bind keys to the old\nwidgets by putting a `.' in front of the widget name, e.g. `.expand-or-complete'.\n\nTo speed up the running of compinit, it can be made to produce a dumped configuration that\nwill be read in on future invocations; this is the default, but can be turned off by calling\ncompinit with the option -D. The dumped file is .zcompdump in the same directory as the\nstartup files (i.e. $ZDOTDIR or $HOME); alternatively, an explicit file name can be given by\n`compinit -d dumpfile'. The next invocation of compinit will read the dumped file instead of\nperforming a full initialization.\n\nIf the number of completion files changes, compinit will recognise this and produce a new\ndump file. However, if the name of a function or the arguments in the first line of a #com‐‐\npdef function (as described below) change, it is easiest to delete the dump file by hand so\nthat compinit will re-create it the next time it is run. The check performed to see if there\nare new functions can be omitted by giving the option -C. In this case the dump file will\nonly be created if there isn't one already.\n\nThe dumping is actually done by another function, compdump, but you will only need to run\nthis yourself if you change the configuration (e.g. using compdef) and then want to dump the\nnew one. The name of the old dumped file will be remembered for this purpose.\n\nIf the parameter compdir is set, compinit uses it as a directory where completion functions\ncan be found; this is only necessary if they are not already in the function search path.\n\nFor security reasons compinit also checks if the completion system would use files not owned\nby root or by the current user, or files in directories that are world- or group-writable or\nthat are not owned by root or by the current user. If such files or directories are found,\ncompinit will ask if the completion system should really be used. To avoid these tests and\nmake all files found be used without asking, use the option -u, and to make compinit silently\nignore all insecure files and directories use the option -i. This security check is skipped\nentirely when the -C option is given.\n\nThe security check can be retried at any time by running the function compaudit. This is the\nsame check used by compinit, but when it is executed directly any changes to fpath are made\nlocal to the function so they do not persist. The directories to be checked may be passed as\narguments; if none are given, compaudit uses fpath and compdir to find completion system di‐\nrectories, adding missing ones to fpath as necessary. To force a check of exactly the direc‐\ntories currently named in fpath, set compdir to an empty string before calling compaudit or\ncompinit.\n\nThe function bashcompinit provides compatibility with bash's programmable completion system.\nWhen run it will define the functions, compgen and complete which correspond to the bash\nbuiltins with the same names. It will then be possible to use completion specifications and\nfunctions written for bash.\n" }, { "name": "Autoloaded files", "content": "The convention for autoloaded functions used in completion is that they start with an under‐\nscore; as already mentioned, the fpath/FPATH parameter must contain the directory in which\nthey are stored. If zsh was properly installed on your system, then fpath/FPATH automati‐\ncally contains the required directories for the standard functions.\n\nFor incomplete installations, if compinit does not find enough files beginning with an under‐\nscore (fewer than twenty) in the search path, it will try to find more by adding the direc‐\ntory compdir to the search path. If that directory has a subdirectory named Base, all sub‐\ndirectories will be added to the path. Furthermore, if the subdirectory Base has a subdirec‐\ntory named Core, compinit will add all subdirectories of the subdirectories to the path: this\nallows the functions to be in the same format as in the zsh source distribution.\n\nWhen compinit is run, it searches all such files accessible via fpath/FPATH and reads the\nfirst line of each of them. This line should contain one of the tags described below. Files\nwhose first line does not start with one of these tags are not considered to be part of the\ncompletion system and will not be treated specially.\n\nThe tags are:\n\n#compdef name ... [ -{p|P} pattern ... [ -N name ... ] ]\nThe file will be made autoloadable and the function defined in it will be called when\ncompleting names, each of which is either the name of a command whose arguments are to\nbe completed or one of a number of special contexts in the form -context- described\nbelow.\n\nEach name may also be of the form `cmd=service'. When completing the command cmd, the\nfunction typically behaves as if the command (or special context) service was being\ncompleted instead. This provides a way of altering the behaviour of functions that\ncan perform many different completions. It is implemented by setting the parameter\n$service when calling the function; the function may choose to interpret this how it\nwishes, and simpler functions will probably ignore it.\n\nIf the #compdef line contains one of the options -p or -P, the words following are\ntaken to be patterns. The function will be called when completion is attempted for a\ncommand or context that matches one of the patterns. The options -p and -P are used\nto specify patterns to be tried before or after other completions respectively. Hence\n-P may be used to specify default actions.\n\nThe option -N is used after a list following -p or -P; it specifies that remaining\nwords no longer define patterns. It is possible to toggle between the three options\nas many times as necessary.\n\n#compdef -k style key-sequence ...\nThis option creates a widget behaving like the builtin widget style and binds it to\nthe given key-sequences, if any. The style must be one of the builtin widgets that\nperform completion, namely complete-word, delete-char-or-list, expand-or-complete, ex‐‐\npand-or-complete-prefix, list-choices, menu-complete, menu-expand-or-complete, or re‐‐\nverse-menu-complete. If the zsh/complist module is loaded (see zshmodules(1)) the\nwidget menu-select is also available.\n\nWhen one of the key-sequences is typed, the function in the file will be invoked to\ngenerate the matches. Note that a key will not be re-bound if it already was (that\nis, was bound to something other than undefined-key). The widget created has the same\nname as the file and can be bound to any other keys using bindkey as usual.\n\n#compdef -K widget-name style key-sequence [ name style seq ... ]\nThis is similar to -k except that only one key-sequence argument may be given for each\nwidget-name style pair. However, the entire set of three arguments may be repeated\nwith a different set of arguments. Note in particular that the widget-name must be\ndistinct in each set. If it does not begin with `' this will be added. The wid‐\nget-name should not clash with the name of any existing widget: names based on the\nname of the function are most useful. For example,\n\n#compdef -K foocomplete complete-word \"^X^C\" \\\nfoolist list-choices \"^X^D\"\n\n(all on one line) defines a widget foocomplete for completion, bound to `^X^C', and\na widget foolist for listing, bound to `^X^D'.\n\n#autoload [ options ]\nFunctions with the #autoload tag are marked for autoloading but are not otherwise\ntreated specially. Typically they are to be called from within one of the completion\nfunctions. Any options supplied will be passed to the autoload builtin; a typical use\nis +X to force the function to be loaded immediately. Note that the -U and -z flags\nare always added implicitly.\n\nThe # is part of the tag name and no white space is allowed after it. The #compdef tags use\nthe compdef function described below; the main difference is that the name of the function is\nsupplied implicitly.\n\nThe special contexts for which completion functions can be defined are:\n" }, { "name": "-array-value-", "content": "The right hand side of an array-assignment (`name=(...)')\n" }, { "name": "-brace-parameter-", "content": "The name of a parameter expansion within braces (`${...}')\n" }, { "name": "-assign-parameter-", "content": "The name of a parameter in an assignment, i.e. on the left hand side of an `='\n" }, { "name": "-command-", "content": "A word in command position\n" }, { "name": "-condition-", "content": "A word inside a condition (`[[...]]')\n" }, { "name": "-default-", "content": "Any word for which no other completion is defined\n" }, { "name": "-equal-", "content": "A word beginning with an equals sign\n" }, { "name": "-first-", "content": "This is tried before any other completion function. The function called may set the\ncompskip parameter to one of various values: all: no further completion is attempted;\na string containing the substring patterns: no pattern completion functions will be\ncalled; a string containing default: the function for the `-default-' context will not\nbe called, but functions defined for commands will be.\n" }, { "name": "-math-", "content": "" }, { "name": "-parameter-", "content": "The name of a parameter expansion (`$...')\n" }, { "name": "-redirect-", "content": "The word after a redirection operator.\n" }, { "name": "-subscript-", "content": "The contents of a parameter subscript.\n" }, { "name": "-tilde-", "content": "After an initial tilde (`~'), but before the first slash in the word.\n" }, { "name": "-value-", "content": "On the right hand side of an assignment.\n\nDefault implementations are supplied for each of these contexts. In most cases the context\n-context- is implemented by a corresponding function context, for example the context\n`-tilde-' and the function `tilde').\n\nThe contexts -redirect- and -value- allow extra context-specific information. (Internally,\nthis is handled by the functions for each context calling the function dispatch.) The extra\ninformation is added separated by commas.\n\nFor the -redirect- context, the extra information is in the form `-redirect-,op,command',\nwhere op is the redirection operator and command is the name of the command on the line. If\nthere is no command on the line yet, the command field will be empty.\n\nFor the -value- context, the form is `-value-,name,command', where name is the name of the\nparameter on the left hand side of the assignment. In the case of elements of an associative\narray, for example `assoc=(key ', name is expanded to `name-key'. In certain special\ncontexts, such as completing after `make CFLAGS=', the command part gives the name of the\ncommand, here make; otherwise it is empty.\n\nIt is not necessary to define fully specific completions as the functions provided will try\nto generate completions by progressively replacing the elements with `-default-'. For exam‐\nple, when completing after `foo=', value will try the names `-value-,foo,' (note the\nempty command part), `-value-,foo,-default-' and`-value-,-default-,-default-', in that order,\nuntil it finds a function to handle the context.\n\nAs an example:\n\ncompdef 'files -g \"*.log\"' '-redirect-,2>,-default-'\n\ncompletes files matching `*.log' after `2> ' for any command with no more specific han‐\ndler defined.\n\nAlso:\n\ncompdef foo -value-,-default-,-default-\n\nspecifies that foo provides completions for the values of parameters for which no special\nfunction has been defined. This is usually handled by the function value itself.\n\nThe same lookup rules are used when looking up styles (as described below); for example\n\nzstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log'\n\nis another way to make completion after `2> ' complete files matching `*.log'.\n" }, { "name": "Functions", "content": "The following function is defined by compinit and may be called directly.\n\ncompdef [ -ane ] function name ... [ -{p|P} pattern ... [ -N name ...]]\ncompdef -d name ...\ncompdef -k [ -an ] function style key-sequence [ key-sequence ... ]\ncompdef -K [ -an ] function name style key-seq [ name style seq ... ]\nThe first form defines the function to call for completion in the given contexts as\ndescribed for the #compdef tag above.\n\nAlternatively, all the arguments may have the form `cmd=service'. Here service should\nalready have been defined by `cmd1=service' lines in #compdef files, as described\nabove. The argument for cmd will be completed in the same way as service.\n\nThe function argument may alternatively be a string containing almost any shell code.\nIf the string contains an equal sign, the above will take precedence. The option -e\nmay be used to specify the first argument is to be evaluated as shell code even if it\ncontains an equal sign. The string will be executed using the eval builtin command to\ngenerate completions. This provides a way of avoiding having to define a new comple‐\ntion function. For example, to complete files ending in `.h' as arguments to the com‐\nmand foo:\n\ncompdef 'files -g \"*.h\"' foo\n\nThe option -n prevents any completions already defined for the command or context from\nbeing overwritten.\n\nThe option -d deletes any completion defined for the command or contexts listed.\n\nThe names may also contain -p, -P and -N options as described for the #compdef tag.\nThe effect on the argument list is identical, switching between definitions of pat‐\nterns tried initially, patterns tried finally, and normal commands and contexts.\n\nThe parameter $compskip may be set by any function defined for a pattern context. If\nit is set to a value containing the substring `patterns' none of the pattern-functions\nwill be called; if it is set to a value containing the substring `all', no other func‐\ntion will be called. Setting $compskip in this manner is of particular utility when\nusing the -p option, as otherwise the dispatcher will move on to additional functions\n(likely the default one) after calling the pattern-context one, which can mangle the\ndisplay of completion possibilities if not handled properly.\n\nThe form with -k defines a widget with the same name as the function that will be\ncalled for each of the key-sequences; this is like the #compdef -k tag. The function\nshould generate the completions needed and will otherwise behave like the builtin wid‐\nget whose name is given as the style argument. The widgets usable for this are: com‐‐\nplete-word, delete-char-or-list, expand-or-complete, expand-or-complete-prefix,\nlist-choices, menu-complete, menu-expand-or-complete, and reverse-menu-complete, as\nwell as menu-select if the zsh/complist module is loaded. The option -n prevents the\nkey being bound if it is already to bound to something other than undefined-key.\n\nThe form with -K is similar and defines multiple widgets based on the same function,\neach of which requires the set of three arguments name, style and key-sequence, where\nthe latter two are as for -k and the first must be a unique widget name beginning with\nan underscore.\n\nWherever applicable, the -a option makes the function autoloadable, equivalent to au‐‐\ntoload -U function.\n\nThe function compdef can be used to associate existing completion functions with new com‐\nmands. For example,\n\ncompdef pids foo\n\nuses the function pids to complete process IDs for the command foo.\n\nNote also the gnugeneric function described below, which can be used to complete options\nfor commands that understand the `--help' option.\n" } ] }, "COMPLETION SYSTEM CONFIGURATION": { "content": "This section gives a short overview of how the completion system works, and then more detail\non how users can configure how and when matches are generated.\n", "subsections": [ { "name": "Overview", "content": "When completion is attempted somewhere on the command line the completion system begins\nbuilding the context. The context represents everything that the shell knows about the mean‐\ning of the command line and the significance of the cursor position. This takes account of a\nnumber of things including the command word (such as `grep' or `zsh') and options to which\nthe current word may be an argument (such as the `-o' option to zsh which takes a shell op‐\ntion as an argument).\n\nThe context starts out very generic (\"we are beginning a completion\") and becomes more spe‐\ncific as more is learned (\"the current word is in a position that is usually a command name\"\nor \"the current word might be a variable name\" and so on). Therefore the context will vary\nduring the same call to the completion system.\n\nThis context information is condensed into a string consisting of multiple fields separated\nby colons, referred to simply as `the context' in the remainder of the documentation. Note\nthat a user of the completion system rarely needs to compose a context string, unless for ex‐\nample a new function is being written to perform completion for a new command. What a user\nmay need to do is compose a style pattern, which is matched against a context when needed to\nlook up context-sensitive options that configure the completion system.\n\nThe next few paragraphs explain how a context is composed within the completion function\nsuite. Following that is discussion of how styles are defined. Styles determine such things\nas how the matches are generated, similarly to shell options but with much more control.\nThey are defined with the zstyle builtin command (see zshmodules(1)).\n\nThe context string always consists of a fixed set of fields, separated by colons and with a\nleading colon before the first. Fields which are not yet known are left empty, but the sur‐\nrounding colons appear anyway. The fields are always in the order :completion:function:com‐\npleter:command:argument:tag. These have the following meaning:\n\n• The literal string completion, saying that this style is used by the completion sys‐\ntem. This distinguishes the context from those used by, for example, zle widgets and\nZFTP functions.\n\n\n• The function, if completion is called from a named widget rather than through the nor‐\nmal completion system. Typically this is blank, but it is set by special widgets such\nas predict-on and the various functions in the Widget directory of the distribution to\nthe name of that function, often in an abbreviated form.\n\n\n• The completer currently active, the name of the function without the leading under‐\nscore and with other underscores converted to hyphens. A `completer' is in overall\ncontrol of how completion is to be performed; `complete' is the simplest, but other\ncompleters exist to perform related tasks such as correction, or to modify the behav‐\niour of a later completer. See the section `Control Functions' below for more infor‐\nmation.\n\n\n• The command or a special -context-, just at it appears following the #compdef tag or\nthe compdef function. Completion functions for commands that have sub-commands usu‐\nally modify this field to contain the name of the command followed by a minus sign and\nthe sub-command. For example, the completion function for the cvs command sets this\nfield to cvs-add when completing arguments to the add subcommand.\n\n\n• The argument; this indicates which command line or option argument we are completing.\nFor command arguments this generally takes the form argument-n, where n is the number\nof the argument, and for arguments to options the form option-opt-n where n is the\nnumber of the argument to option opt. However, this is only the case if the command\nline is parsed with standard UNIX-style options and arguments, so many completions do\nnot set this.\n\n\n• The tag. As described previously, tags are used to discriminate between the types of\nmatches a completion function can generate in a certain context. Any completion func‐\ntion may use any tag name it likes, but a list of the more common ones is given below.\n\n\nThe context is gradually put together as the functions are executed, starting with the main\nentry point, which adds :completion: and the function element if necessary. The completer\nthen adds the completer element. The contextual completion adds the command and argument op‐\ntions. Finally, the tag is added when the types of completion are known. For example, the\ncontext name\n\n:completion::complete:dvips:option-o-1:files\n\nsays that normal completion was attempted as the first argument to the option -o of the com‐\nmand dvips:\n\ndvips -o ...\n\nand the completion function will generate filenames.\n\nUsually completion will be tried for all possible tags in an order given by the completion\nfunction. However, this can be altered by using the tag-order style. Completion is then re‐\nstricted to the list of given tags in the given order.\n\nThe completehelp bindable command shows all the contexts and tags available for completion\nat a particular point. This provides an easy way of finding information for tag-order and\nother styles. It is described in the section `Bindable Commands' below.\n\nWhen looking up styles the completion system uses full context names, including the tag.\nLooking up the value of a style therefore consists of two things: the context, which is\nmatched to the most specific (best fitting) style pattern, and the name of the style itself,\nwhich must be matched exactly. The following examples demonstrate that style patterns may be\nloosely defined for styles that apply broadly, or as tightly defined as desired for styles\nthat apply in narrower circumstances.\n\nFor example, many completion functions can generate matches in a simple and a verbose form\nand use the verbose style to decide which form should be used. To make all such functions\nuse the verbose form, put\n\nzstyle ':completion:*' verbose yes\n\nin a startup file (probably .zshrc). This gives the verbose style the value yes in every\ncontext inside the completion system, unless that context has a more specific definition. It\nis best to avoid giving the context as `*' in case the style has some meaning outside the\ncompletion system.\n\nMany such general purpose styles can be configured simply by using the compinstall function.\n\nA more specific example of the use of the verbose style is by the completion for the kill\nbuiltin. If the style is set, the builtin lists full job texts and process command lines;\notherwise it shows the bare job numbers and PIDs. To turn the style off for this use only:\n\nzstyle ':completion:*:*:kill:*:*' verbose no\n\nFor even more control, the style can use one of the tags `jobs' or `processes'. To turn off\nverbose display only for jobs:\n\nzstyle ':completion:*:*:kill:*:jobs' verbose no\n\nThe -e option to zstyle even allows completion function code to appear as the argument to a\nstyle; this requires some understanding of the internals of completion functions (see see\nzshcompwid(1))). For example,\n\nzstyle -e ':completion:*' hosts 'reply=($myhosts)'\n\nThis forces the value of the hosts style to be read from the variable myhosts each time a\nhost name is needed; this is useful if the value of myhosts can change dynamically. For an‐\nother useful example, see the example in the description of the file-list style below. This\nform can be slow and should be avoided for commonly examined styles such as menu and\nlist-rows-first.\n\nNote that the order in which styles are defined does not matter; the style mechanism uses the\nmost specific possible match for a particular style to determine the set of values. More\nprecisely, strings are preferred over patterns (for example, `:completion::complete:::foo' is\nmore specific than `:completion::complete:::*'), and longer patterns are preferred over\nshorter patterns.\n\nA good rule of thumb is that any completion style pattern that needs to include more than one\nwildcard (*) and that does not end in a tag name, should include all six colons (:), possibly\nsurrounding additional wildcards.\n\nStyle names like those of tags are arbitrary and depend on the completion function. However,\nthe following two sections list some of the most common tags and styles.\n" }, { "name": "Standard Tags", "content": "Some of the following are only used when looking up particular styles and do not refer to a\ntype of match.\n" }, { "name": "accounts", "content": "used to look up the users-hosts style\n" }, { "name": "all-expansions", "content": "used by the expand completer when adding the single string containing all possible\nexpansions\n" }, { "name": "all-files", "content": "for the names of all files (as distinct from a particular subset, see the\nglobbed-files tag).\n" }, { "name": "arguments", "content": "for arguments to a command\n\narrays for names of array parameters\n" }, { "name": "association-keys", "content": "for keys of associative arrays; used when completing inside a subscript to a parameter\nof this type\n" }, { "name": "bookmarks", "content": "when completing bookmarks (e.g. for URLs and the zftp function suite)\n" }, { "name": "builtins", "content": "for names of builtin commands\n" }, { "name": "characters", "content": "for single characters in arguments of commands such as stty. Also used when complet‐\ning character classes after an opening bracket\n" }, { "name": "colormapids", "content": "for X colormap ids\n\ncolors for color names\n" }, { "name": "commands", "content": "for names of external commands. Also used by complex commands such as cvs when com‐\npleting names subcommands.\n" }, { "name": "contexts", "content": "for contexts in arguments to the zstyle builtin command\n" }, { "name": "corrections", "content": "used by the approximate and correct completers for possible corrections\n" }, { "name": "cursors", "content": "for cursor names used by X programs\n" }, { "name": "default", "content": "used in some contexts to provide a way of supplying a default when more specific tags\nare also valid. Note that this tag is used when only the function field of the con‐\ntext name is set\n" }, { "name": "descriptions", "content": "used when looking up the value of the format style to generate descriptions for types\nof matches\n" }, { "name": "devices", "content": "for names of device special files\n" }, { "name": "directories", "content": "for names of directories -- local-directories is used instead when completing argu‐\nments of cd and related builtin commands when the cdpath array is set\n" }, { "name": "directory-stack", "content": "for entries in the directory stack\n" }, { "name": "displays", "content": "for X display names\n" }, { "name": "domains", "content": "for network domains\n\nemail-plugin\nfor email addresses from the `email-plugin' backend of emailaddresses\n" }, { "name": "expansions", "content": "used by the expand completer for individual words (as opposed to the complete set of\nexpansions) resulting from the expansion of a word on the command line\n" }, { "name": "extensions", "content": "for X server extensions\n" }, { "name": "file-descriptors", "content": "for numbers of open file descriptors\n\nfiles the generic file-matching tag used by functions completing filenames\n\nfonts for X font names\n" }, { "name": "fstypes", "content": "for file system types (e.g. for the mount command)\n" }, { "name": "functions", "content": "names of functions -- normally shell functions, although certain commands may under‐\nstand other kinds of function\n" }, { "name": "globbed-files", "content": "for filenames when the name has been generated by pattern matching\n\ngroups for names of user groups\n" }, { "name": "history-words", "content": "for words from the history\n\nhosts for hostnames\n" }, { "name": "indexes", "content": "for array indexes\n\njobs for jobs (as listed by the `jobs' builtin)\n" }, { "name": "interfaces", "content": "for network interfaces\n" }, { "name": "keymaps", "content": "for names of zsh keymaps\n" }, { "name": "keysyms", "content": "for names of X keysyms\n" }, { "name": "libraries", "content": "for names of system libraries\n\nlimits for system limits\n" }, { "name": "local-directories", "content": "for names of directories that are subdirectories of the current working directory when\ncompleting arguments of cd and related builtin commands (compare path-directories) --\nwhen the cdpath array is unset, directories is used instead\n" }, { "name": "manuals", "content": "for names of manual pages\n" }, { "name": "mailboxes", "content": "for e-mail folders\n\nmaps for map names (e.g. NIS maps)\n" }, { "name": "messages", "content": "used to look up the format style for messages\n" }, { "name": "modifiers", "content": "for names of X modifiers\n" }, { "name": "modules", "content": "for modules (e.g. zsh modules)\n" }, { "name": "my-accounts", "content": "used to look up the users-hosts style\n" }, { "name": "named-directories", "content": "for named directories (you wouldn't have guessed that, would you?)\n\nnames for all kinds of names\n" }, { "name": "newsgroups", "content": "for USENET groups\n" }, { "name": "nicknames", "content": "for nicknames of NIS maps\n" }, { "name": "options", "content": "for command options\n" }, { "name": "original", "content": "used by the approximate, correct and expand completers when offering the original\nstring as a match\n" }, { "name": "other-accounts", "content": "used to look up the users-hosts style\n" }, { "name": "other-files", "content": "for the names of any non-directory files. This is used instead of all-files when the\nlist-dirs-first style is in effect.\n" }, { "name": "packages", "content": "for packages (e.g. rpm or installed Debian packages)\n" }, { "name": "parameters", "content": "for names of parameters\n" }, { "name": "path-directories", "content": "for names of directories found by searching the cdpath array when completing arguments\nof cd and related builtin commands (compare local-directories)\n\npaths used to look up the values of the expand, ambiguous and special-dirs styles\n\npods for perl pods (documentation files)\n\nports for communication ports\n" }, { "name": "prefixes", "content": "for prefixes (like those of a URL)\n" }, { "name": "printers", "content": "for print queue names\n" }, { "name": "processes", "content": "for process identifiers\n" }, { "name": "processes-names", "content": "used to look up the command style when generating the names of processes for killall\n" }, { "name": "sequences", "content": "for sequences (e.g. mh sequences)\n" }, { "name": "sessions", "content": "for sessions in the zftp function suite\n" }, { "name": "signals", "content": "for signal names\n" }, { "name": "strings", "content": "for strings (e.g. the replacement strings for the cd builtin command)\n\nstyles for styles used by the zstyle builtin command\n" }, { "name": "suffixes", "content": "for filename extensions\n\ntags for tags (e.g. rpm tags)\n" }, { "name": "targets", "content": "for makefile targets\n" }, { "name": "time-zones", "content": "for time zones (e.g. when setting the TZ parameter)\n\ntypes for types of whatever (e.g. address types for the xhost command)\n\nurls used to look up the urls and local styles when completing URLs\n\nusers for usernames\n\nvalues for one of a set of values in certain lists\n" }, { "name": "variant", "content": "used by pickvariant to look up the command to run when determining what program is\ninstalled for a particular command name.\n" }, { "name": "visuals", "content": "for X visuals\n" }, { "name": "warnings", "content": "used to look up the format style for warnings\n" }, { "name": "widgets", "content": "for zsh widget names\n" }, { "name": "windows", "content": "for IDs of X windows\n" }, { "name": "zsh-options", "content": "for shell options\n" }, { "name": "Standard Styles", "content": "Note that the values of several of these styles represent boolean values. Any of the strings\n`true', `on', `yes', and `1' can be used for the value `true' and any of the strings `false',\n`off', `no', and `0' for the value `false'. The behavior for any other value is undefined\nexcept where explicitly mentioned. The default value may be either `true' or `false' if the\nstyle is not set.\n\nSome of these styles are tested first for every possible tag corresponding to a type of\nmatch, and if no style was found, for the default tag. The most notable styles of this type\nare menu, list-colors and styles controlling completion listing such as list-packed and\nlast-prompt. When tested for the default tag, only the function field of the context will be\nset so that a style using the default tag will normally be defined along the lines of:\n\nzstyle ':completion:*:default' menu ...\n" }, { "name": "accept-exact", "content": "This is tested for the default tag in addition to the tags valid for the current con‐\ntext. If it is set to `true' and any of the trial matches is the same as the string\non the command line, this match will immediately be accepted (even if it would other‐\nwise be considered ambiguous).\n\nWhen completing pathnames (where the tag used is `paths') this style accepts any num‐\nber of patterns as the value in addition to the boolean values. Pathnames matching\none of these patterns will be accepted immediately even if the command line contains\nsome more partially typed pathname components and these match no file under the direc‐\ntory accepted.\n\nThis style is also used by the expand completer to decide if words beginning with a\ntilde or parameter expansion should be expanded. For example, if there are parameters\nfoo and foobar, the string `$foo' will only be expanded if accept-exact is set to\n`true'; otherwise the completion system will be allowed to complete $foo to $foobar.\nIf the style is set to `continue', expand will add the expansion as a match and the\ncompletion system will also be allowed to continue.\n" }, { "name": "accept-exact-dirs", "content": "This is used by filename completion. Unlike accept-exact it is a boolean. By de‐\nfault, filename completion examines all components of a path to see if there are com‐\npletions of that component, even if the component matches an existing directory. For\nexample, when completion after /usr/bin/, the function examines possible completions\nto /usr.\n\nWhen this style is `true', any prefix of a path that matches an existing directory is\naccepted without any attempt to complete it further. Hence, in the given example, the\npath /usr/bin/ is accepted immediately and completion tried in that directory.\n\nThis style is also useful when completing after directories that magically appear when\nreferenced, such as ZFS .zfs directories or NetApp .snapshot directories. When the\nstyle is set the shell does not check for the existence of the directory within the\nparent directory.\n\nIf you wish to inhibit this behaviour entirely, set the path-completion style (see be‐\nlow) to `false'.\n" }, { "name": "add-space", "content": "This style is used by the expand completer. If it is `true' (the default), a space\nwill be inserted after all words resulting from the expansion, or a slash in the case\nof directory names. If the value is `file', the completer will only add a space to\nnames of existing files. Either a boolean `true' or the value `file' may be combined\nwith `subst', in which case the completer will not add a space to words generated from\nthe expansion of a substitution of the form `$(...)' or `${...}'.\n\nThe prefix completer uses this style as a simple boolean value to decide if a space\nshould be inserted before the suffix.\n" }, { "name": "ambiguous", "content": "This applies when completing non-final components of filename paths, in other words\nthose with a trailing slash. If it is set, the cursor is left after the first ambigu‐\nous component, even if menu completion is in use. The style is always tested with the\npaths tag.\n" }, { "name": "assign-list", "content": "When completing after an equals sign that is being treated as an assignment, the com‐\npletion system normally completes only one filename. In some cases the value may be\na list of filenames separated by colons, as with PATH and similar parameters. This\nstyle can be set to a list of patterns matching the names of such parameters.\n\nThe default is to complete lists when the word on the line already contains a colon.\n" }, { "name": "auto-description", "content": "If set, this style's value will be used as the description for options that are not\ndescribed by the completion functions, but that have exactly one argument. The se‐\nquence `%d' in the value will be replaced by the description for this argument. De‐\npending on personal preferences, it may be useful to set this style to something like\n`specify: %d'. Note that this may not work for some commands.\n" }, { "name": "avoid-completer", "content": "This is used by the allmatches completer to decide if the string consisting of all\nmatches should be added to the list currently being generated. Its value is a list of\nnames of completers. If any of these is the name of the completer that generated the\nmatches in this completion, the string will not be added.\n\nThe default value for this style is `expand oldlist correct approximate', i.e. it\ncontains the completers for which a string with all matches will almost never be\nwanted.\n" }, { "name": "cache-path", "content": "This style defines the path where any cache files containing dumped completion data\nare stored. It defaults to `$ZDOTDIR/.zcompcache', or `$HOME/.zcompcache' if $ZDOTDIR\nis not defined. The completion cache will not be used unless the use-cache style is\nset.\n" }, { "name": "cache-policy", "content": "This style defines the function that will be used to determine whether a cache needs\nrebuilding. See the section on the cacheinvalid function below.\n" }, { "name": "call-command", "content": "This style is used in the function for commands such as make and ant where calling the\ncommand directly to generate matches suffers problems such as being slow or, as in the\ncase of make can potentially cause actions in the makefile to be executed. If it is\nset to `true' the command is called to generate matches. The default value of this\nstyle is `false'.\n" }, { "name": "command", "content": "In many places, completion functions need to call external commands to generate the\nlist of completions. This style can be used to override the command that is called in\nsome such cases. The elements of the value are joined with spaces to form a command\nline to execute. The value can also start with a hyphen, in which case the usual com‐\nmand will be added to the end; this is most useful for putting `builtin' or `command'\nin front to make sure the appropriate version of a command is called, for example to\navoid calling a shell function with the same name as an external command.\n\nAs an example, the completion function for process IDs uses this style with the pro‐‐\ncesses tag to generate the IDs to complete and the list of processes to display (if\nthe verbose style is `true'). The list produced by the command should look like the\noutput of the ps command. The first line is not displayed, but is searched for the\nstring `PID' (or `pid') to find the position of the process IDs in the following\nlines. If the line does not contain `PID', the first numbers in each of the other\nlines are taken as the process IDs to complete.\n\nNote that the completion function generally has to call the specified command for each\nattempt to generate the completion list. Hence care should be taken to specify only\ncommands that take a short time to run, and in particular to avoid any that may never\nterminate.\n" }, { "name": "command-path", "content": "This is a list of directories to search for commands to complete. The default for\nthis style is the value of the special parameter path.\n" }, { "name": "commands", "content": "This is used by the function completing sub-commands for the system initialisation\nscripts (residing in /etc/init.d or somewhere not too far away from that). Its values\ngive the default commands to complete for those commands for which the completion\nfunction isn't able to find them out automatically. The default for this style are\nthe two strings `start' and `stop'.\n" }, { "name": "complete", "content": "This is used by the expandalias function when invoked as a bindable command. If set\nto `true' and the word on the command line is not the name of an alias, matching alias\nnames will be completed.\n" }, { "name": "complete-options", "content": "This is used by the completer for cd, chdir and pushd. For these commands a - is used\nto introduce a directory stack entry and completion of these is far more common than\ncompleting options. Hence unless the value of this style is `true' options will not\nbe completed, even after an initial -. If it is `true', options will be completed af‐\nter an initial - unless there is a preceding -- on the command line.\n" }, { "name": "completer", "content": "The strings given as the value of this style provide the names of the completer func‐\ntions to use. The available completer functions are described in the section `Control\nFunctions' below.\n\nEach string may be either the name of a completer function or a string of the form\n`function:name'. In the first case the completer field of the context will contain\nthe name of the completer without the leading underscore and with all other under‐\nscores replaced by hyphens. In the second case the function is the name of the com‐\npleter to call, but the context will contain the user-defined name in the completer\nfield of the context. If the name starts with a hyphen, the string for the context\nwill be build from the name of the completer function as in the first case with the\nname appended to it. For example:\n\nzstyle ':completion:*' completer complete complete:-foo\n\nHere, completion will call the complete completer twice, once using `complete' and\nonce using `complete-foo' in the completer field of the context. Normally, using the\nsame completer more than once only makes sense when used with the `functions:name'\nform, because otherwise the context name will be the same in all calls to the com‐\npleter; possible exceptions to this rule are the ignored and prefix completers.\n\nThe default value for this style is `complete ignored': only completion will be\ndone, first using the ignored-patterns style and the $fignore array and then without\nignoring matches.\n" }, { "name": "condition", "content": "This style is used by the list completer function to decide if insertion of matches\nshould be delayed unconditionally. The default is `true'.\n" }, { "name": "delimiters", "content": "This style is used when adding a delimiter for use with history modifiers or glob\nqualifiers that have delimited arguments. It is an array of preferred delimiters to\nadd. Non-special characters are preferred as the completion system may otherwise be‐\ncome confused. The default list is :, +, /, -, %. The list may be empty to force a\ndelimiter to be typed.\n" }, { "name": "disabled", "content": "If this is set to `true', the expandalias completer and bindable command will try to\nexpand disabled aliases, too. The default is `false'.\n" }, { "name": "domains", "content": "A list of names of network domains for completion. If this is not set, domain names\nwill be taken from the file /etc/resolv.conf.\n" }, { "name": "environ", "content": "The environ style is used when completing for `sudo'. It is set to an array of\n`VAR=value' assignments to be exported into the local environment before the comple‐\ntion for the target command is invoked.\nzstyle ':completion:*:sudo::' environ \\\nPATH=\"/sbin:/usr/sbin:$PATH\" HOME=\"/root\"\n\nexpand This style is used when completing strings consisting of multiple parts, such as path\nnames.\n\nIf one of its values is the string `prefix', the partially typed word from the line\nwill be expanded as far as possible even if trailing parts cannot be completed.\n\nIf one of its values is the string `suffix', matching names for components after the\nfirst ambiguous one will also be added. This means that the resulting string is the\nlongest unambiguous string possible. However, menu completion can be used to cycle\nthrough all matches.\n\nfake This style may be set for any completion context. It specifies additional strings\nthat will always be completed in that context. The form of each string is `value:de‐\nscription'; the colon and description may be omitted, but any literal colons in value\nmust be quoted with a backslash. Any description provided is shown alongside the\nvalue in completion listings.\n\nIt is important to use a sufficiently restrictive context when specifying fake\nstrings. Note that the styles fake-files and fake-parameters provide additional fea‐\ntures when completing files or parameters.\n" }, { "name": "fake-always", "content": "This works identically to the fake style except that the ignored-patterns style is not\napplied to it. This makes it possible to override a set of matches completely by set‐\nting the ignored patterns to `*'.\n\nThe following shows a way of supplementing any tag with arbitrary data, but having it\nbehave for display purposes like a separate tag. In this example we use the features\nof the tag-order style to divide the named-directories tag into two when performing\ncompletion with the standard completer complete for arguments of cd. The tag\nnamed-directories-normal behaves as normal, but the tag named-directories-mine con‐\ntains a fixed set of directories. This has the effect of adding the match group `ex‐‐\ntra directories' with the given completions.\n\nzstyle ':completion::complete:cd:*' tag-order \\\n'named-directories:-mine:extra\\ directories\nnamed-directories:-normal:named\\ directories *'\nzstyle ':completion::complete:cd:*:named-directories-mine' \\\nfake-always mydir1 mydir2\nzstyle ':completion::complete:cd:*:named-directories-mine' \\\nignored-patterns '*'\n" }, { "name": "fake-files", "content": "This style is used when completing files and looked up without a tag. Its values are\nof the form `dir:names...'. This will add the names (strings separated by spaces) as\npossible matches when completing in the directory dir, even if no such files really\nexist. The dir may be a pattern; pattern characters or colons in dir should be quoted\nwith a backslash to be treated literally.\n\nThis can be useful on systems that support special file systems whose top-level path‐\nnames can not be listed or generated with glob patterns (but see accept-exact-dirs for\na more general way of dealing with this problem). It can also be used for directories\nfor which one does not have read permission.\n\nThe pattern form can be used to add a certain `magic' entry to all directories on a\nparticular file system.\n" }, { "name": "fake-parameters", "content": "This is used by the completion function for parameter names. Its values are names of\nparameters that might not yet be set but should be completed nonetheless. Each name\nmay also be followed by a colon and a string specifying the type of the parameter\n(like `scalar', `array' or `integer'). If the type is given, the name will only be\ncompleted if parameters of that type are required in the particular context. Names\nfor which no type is specified will always be completed.\n" }, { "name": "file-list", "content": "This style controls whether files completed using the standard builtin mechanism are\nto be listed with a long list similar to ls -l. Note that this feature uses the shell\nmodule zsh/stat for file information; this loads the builtin stat which will replace\nany external stat executable. To avoid this the following code can be included in an\ninitialization file:\n\nzmodload -i zsh/stat\ndisable stat\n\nThe style may either be set to a `true' value (or `all'), or one of the values `in‐‐\nsert' or `list', indicating that files are to be listed in long format in all circum‐\nstances, or when attempting to insert a file name, or when listing file names without\nattempting to insert one.\n\nMore generally, the value may be an array of any of the above values, optionally fol‐\nlowed by =num. If num is present it gives the maximum number of matches for which\nlong listing style will be used. For example,\n\nzstyle ':completion:*' file-list list=20 insert=10\n\nspecifies that long format will be used when listing up to 20 files or inserting a\nfile with up to 10 matches (assuming a listing is to be shown at all, for example on\nan ambiguous completion), else short format will be used.\n\nzstyle -e ':completion:*' file-list \\\n'(( ${+NUMERIC} )) && reply=(true)'\n\nspecifies that long format will be used any time a numeric argument is supplied, else\nshort format.\n" }, { "name": "file-patterns", "content": "This is used by the standard function for completing filenames, files. If the style\nis unset up to three tags are offered, `globbed-files',`directories' and `all-files',\ndepending on the types of files expected by the caller of files. The first two\n(`globbed-files' and `directories') are normally offered together to make it easier to\ncomplete files in sub-directories.\n\nThe file-patterns style provides alternatives to the default tags, which are not used.\nIts value consists of elements of the form `pattern:tag'; each string may contain any\nnumber of such specifications separated by spaces.\n\nThe pattern is a pattern that is to be used to generate filenames. Any occurrence of\nthe sequence `%p' is replaced by any pattern(s) passed by the function calling files.\nColons in the pattern must be preceded by a backslash to make them distinguishable\nfrom the colon before the tag. If more than one pattern is needed, the patterns can\nbe given inside braces, separated by commas.\n\nThe tags of all strings in the value will be offered by files and used when looking\nup other styles. Any tags in the same word will be offered at the same time and be‐\nfore later words. If no `:tag' is given the `files' tag will be used.\n\nThe tag may also be followed by an optional second colon and a description, which will\nbe used for the `%d' in the value of the format style (if that is set) instead of the\ndefault description supplied by the completion function. If the description given\nhere contains itself a `%d', that is replaced with the description supplied by the\ncompletion function.\n\nFor example, to make the rm command first complete only names of object files and then\nthe names of all files if there is no matching object file:\n\nzstyle ':completion:*:*:rm:*:*' file-patterns \\\n'*.o:object-files' '%p:all-files'\n\nTo alter the default behaviour of file completion -- offer files matching a pattern\nand directories on the first attempt, then all files -- to offer only matching files\non the first attempt, then directories, and finally all files:\n\nzstyle ':completion:*' file-patterns \\\n'%p:globbed-files' '*(-/):directories' '*:all-files'\n\nThis works even where there is no special pattern: files matches all files using the\npattern `*' at the first step and stops when it sees this pattern. Note also it will\nnever try a pattern more than once for a single completion attempt.\n\nDuring the execution of completion functions, the EXTENDEDGLOB option is in effect,\nso the characters `#', `~' and `^' have special meanings in the patterns.\n" }, { "name": "file-sort", "content": "The standard filename completion function uses this style without a tag to determine\nin which order the names should be listed; menu completion will cycle through them in\nthe same order. The possible values are: `size' to sort by the size of the file;\n`links' to sort by the number of links to the file; `modification' (or `time' or\n`date') to sort by the last modification time; `access' to sort by the last access\ntime; and `inode' (or `change') to sort by the last inode change time. If the style\nis set to any other value, or is unset, files will be sorted alphabetically by name.\nIf the value contains the string `reverse', sorting is done in the opposite order. If\nthe value contains the string `follow', timestamps are associated with the targets of\nsymbolic links; the default is to use the timestamps of the links themselves.\n" }, { "name": "file-split-chars", "content": "A set of characters that will cause all file completions for the given context to be\nsplit at the point where any of the characters occurs. A typical use is to set the\nstyle to :; then everything up to and including the last : in the string so far is ig‐\nnored when completing files. As this is quite heavy-handed, it is usually preferable\nto update completion functions for contexts where this behaviour is useful.\n\nfilter The ldap plugin of email address completion (see emailaddresses) uses this style to\nspecify the attributes to match against when filtering entries. So for example, if\nthe style is set to `sn', matching is done against surnames. Standard LDAP filtering\nis used so normal completion matching is bypassed. If this style is not set, the LDAP\nplugin is skipped. You may also need to set the command style to specify how to con‐\nnect to your LDAP server.\n" }, { "name": "force-list", "content": "This forces a list of completions to be shown at any point where listing is done, even\nin cases where the list would usually be suppressed. For example, normally the list\nis only shown if there are at least two different matches. By setting this style to\n`always', the list will always be shown, even if there is only a single match that\nwill immediately be accepted. The style may also be set to a number. In this case\nthe list will be shown if there are at least that many matches, even if they would all\ninsert the same string.\n\nThis style is tested for the default tag as well as for each tag valid for the current\ncompletion. Hence the listing can be forced only for certain types of match.\n\nformat If this is set for the descriptions tag, its value is used as a string to display\nabove matches in completion lists. The sequence `%d' in this string will be replaced\nwith a short description of what these matches are. This string may also contain the\noutput attribute sequences understood by compadd -X (see zshcompwid(1)).\n\nThe style is tested with each tag valid for the current completion before it is tested\nfor the descriptions tag. Hence different format strings can be defined for different\ntypes of match.\n\nNote also that some completer functions define additional `%'-sequences. These are\ndescribed for the completer functions that make use of them.\n\nSome completion functions display messages that may be customised by setting this\nstyle for the messages tag. Here, the `%d' is replaced with a message given by the\ncompletion function.\n\nFinally, the format string is looked up with the warnings tag, for use when no matches\ncould be generated at all. In this case the `%d' is replaced with the descriptions\nfor the matches that were expected separated by spaces. The sequence `%D' is replaced\nwith the same descriptions separated by newlines.\n\nIt is possible to use printf-style field width specifiers with `%d' and similar escape\nsequences. This is handled by the zformat builtin command from the zsh/zutil module,\nsee zshmodules(1).\n\nglob This is used by the expand completer. If it is set to `true' (the default), globbing\nwill be attempted on the words resulting from a previous substitution (see the substi‐‐\ntute style) or else the original string from the line.\n\nglobal If this is set to `true' (the default), the expandalias completer and bindable com‐\nmand will try to expand global aliases.\n" }, { "name": "group-name", "content": "The completion system can group different types of matches, which appear in separate\nlists. This style can be used to give the names of groups for particular tags. For\nexample, in command position the completion system generates names of builtin and ex‐\nternal commands, names of aliases, shell functions and parameters and reserved words\nas possible completions. To have the external commands and shell functions listed\nseparately:\n\nzstyle ':completion:*:*:-command-:*:commands' \\\ngroup-name commands\nzstyle ':completion:*:*:-command-:*:functions' \\\ngroup-name functions\n\nAs a consequence, any match with the same tag will be displayed in the same group.\n\nIf the name given is the empty string the name of the tag for the matches will be used\nas the name of the group. So, to have all different types of matches displayed sepa‐\nrately, one can just set:\n\nzstyle ':completion:*' group-name ''\n\nAll matches for which no group name is defined will be put in a group named -default-.\n" }, { "name": "group-order", "content": "This style is additional to the group-name style to specify the order for display of\nthe groups defined by that style (compare tag-order, which determines which comple‐\ntions appear at all). The groups named are shown in the given order; any other groups\nare shown in the order defined by the completion function.\n\nFor example, to have names of builtin commands, shell functions and external commands\nappear in that order when completing in command position:\n\nzstyle ':completion:*:*:-command-:*:*' group-order \\\nbuiltins functions commands\n\ngroups A list of names of UNIX groups. If this is not set, group names are taken from the YP\ndatabase or the file `/etc/group'.\n\nhidden If this is set to `true', matches for the given context will not be listed, although\nany description for the matches set with the format style will be shown. If it is set\nto `all', not even the description will be displayed.\n\nNote that the matches will still be completed; they are just not shown in the list.\nTo avoid having matches considered as possible completions at all, the tag-order style\ncan be modified as described below.\n\nhosts A list of names of hosts that should be completed. If this is not set, hostnames are\ntaken from the file `/etc/hosts'.\n" }, { "name": "hosts-ports", "content": "This style is used by commands that need or accept hostnames and network ports. The\nstrings in the value should be of the form `host:port'. Valid ports are determined by\nthe presence of hostnames; multiple ports for the same host may appear.\n" }, { "name": "ignore-line", "content": "This is tested for each tag valid for the current completion. If it is set to `true',\nnone of the words that are already on the line will be considered as possible comple‐\ntions. If it is set to `current', the word the cursor is on will not be considered as\na possible completion. The value `current-shown' is similar but only applies if the\nlist of completions is currently shown on the screen. Finally, if the style is set to\n`other', all words on the line except for the current one will be excluded from the\npossible completions.\n\nThe values `current' and `current-shown' are a bit like the opposite of the accept-ex‐‐\nact style: only strings with missing characters will be completed.\n\nNote that you almost certainly don't want to set this to `true' or `other' for a gen‐\neral context such as `:completion:*'. This is because it would disallow completion\nof, for example, options multiple times even if the command in question accepts the\noption more than once.\n" }, { "name": "ignore-parents", "content": "The style is tested without a tag by the function completing pathnames in order to de‐\ntermine whether to ignore the names of directories already mentioned in the current\nword, or the name of the current working directory. The value must include one or\nboth of the following strings:\n\nparent The name of any directory whose path is already contained in the word on the\nline is ignored. For example, when completing after foo/../, the directory foo\nwill not be considered a valid completion.\n\npwd The name of the current working directory will not be completed; hence, for ex‐\nample, completion after ../ will not use the name of the current directory.\n\nIn addition, the value may include one or both of:\n\n.. Ignore the specified directories only when the word on the line contains the\nsubstring `../'.\n\ndirectory\nIgnore the specified directories only when names of directories are completed,\nnot when completing names of files.\n\nExcluded values act in a similar fashion to values of the ignored-patterns style, so\nthey can be restored to consideration by the ignored completer.\n" }, { "name": "extra-verbose", "content": "If set, the completion listing is more verbose at the cost of a probable decrease in\ncompletion speed. Completion performance will suffer if this style is set to `true'.\n" }, { "name": "ignored-patterns", "content": "A list of patterns; any trial completion matching one of the patterns will be excluded\nfrom consideration. The ignored completer can appear in the list of completers to\nrestore the ignored matches. This is a more configurable version of the shell parame‐\nter $fignore.\n\nNote that the EXTENDEDGLOB option is set during the execution of completion func‐\ntions, so the characters `#', `~' and `^' have special meanings in the patterns.\n\ninsert This style is used by the allmatches completer to decide whether to insert the list\nof all matches unconditionally instead of adding the list as another match.\n" }, { "name": "insert-ids", "content": "When completing process IDs, for example as arguments to the kill and wait builtins\nthe name of a command may be converted to the appropriate process ID. A problem\narises when the process name typed is not unique. By default (or if this style is set\nexplicitly to `menu') the name will be converted immediately to a set of possible IDs,\nand menu completion will be started to cycle through them.\n\nIf the value of the style is `single', the shell will wait until the user has typed\nenough to make the command unique before converting the name to an ID; attempts at\ncompletion will be unsuccessful until that point. If the value is any other string,\nmenu completion will be started when the string typed by the user is longer than the\ncommon prefix to the corresponding IDs.\n" }, { "name": "insert-tab", "content": "If this is set to `true', the completion system will insert a TAB character (assuming\nthat was used to start completion) instead of performing completion when there is no\nnon-blank character to the left of the cursor. If it is set to `false', completion\nwill be done even there.\n\nThe value may also contain the substrings `pending' or `pending=val'. In this case,\nthe typed character will be inserted instead of starting completion when there is un‐\nprocessed input pending. If a val is given, completion will not be done if there are\nat least that many characters of unprocessed input. This is often useful when pasting\ncharacters into a terminal. Note however, that it relies on the $PENDING special pa‐\nrameter from the zsh/zle module being set properly which is not guaranteed on all\nplatforms.\n\nThe default value of this style is `true' except for completion within vared builtin\ncommand where it is `false'.\n" }, { "name": "insert-unambiguous", "content": "This is used by the match and approximate completers. These completers are often\nused with menu completion since the word typed may bear little resemblance to the fi‐\nnal completion. However, if this style is `true', the completer will start menu com‐\npletion only if it could find no unambiguous initial string at least as long as the\noriginal string typed by the user.\n\nIn the case of the approximate completer, the completer field in the context will al‐\nready have been set to one of correct-num or approximate-num, where num is the number\nof errors that were accepted.\n\nIn the case of the match completer, the style may also be set to the string `pat‐‐\ntern'. Then the pattern on the line is left unchanged if it does not match unambigu‐\nously.\n" }, { "name": "gain-privileges", "content": "If set to true, this style enables the use of commands like sudo or doas to gain extra\nprivileges when retrieving information for completion. This is only done when a com‐\nmand such as sudo appears on the command-line. To force the use of, e.g. sudo or to\noverride any prefix that might be added due to gain-privileges, the command style can\nbe used with a value that begins with a hyphen.\n" }, { "name": "keep-prefix", "content": "This style is used by the expand completer. If it is `true', the completer will try\nto keep a prefix containing a tilde or parameter expansion. Hence, for example, the\nstring `~/f*' would be expanded to `~/foo' instead of `/home/user/foo'. If the style\nis set to `changed' (the default), the prefix will only be left unchanged if there\nwere other changes between the expanded words and the original word from the command\nline. Any other value forces the prefix to be expanded unconditionally.\n\nThe behaviour of expand when this style is `true' is to cause expand to give up when\na single expansion with the restored prefix is the same as the original; hence any re‐\nmaining completers may be called.\n" }, { "name": "last-prompt", "content": "This is a more flexible form of the ALWAYSLASTPROMPT option. If it is `true', the\ncompletion system will try to return the cursor to the previous command line after\ndisplaying a completion list. It is tested for all tags valid for the current comple‐\ntion, then the default tag. The cursor will be moved back to the previous line if\nthis style is `true' for all types of match. Note that unlike the ALWAYSLASTPROMPT\noption this is independent of the numeric argument.\n" }, { "name": "known-hosts-files", "content": "This style should contain a list of files to search for host names and (if the use-ip\nstyle is set) IP addresses in a format compatible with ssh knownhosts files. If it\nis not set, the files /etc/ssh/sshknownhosts and ~/.ssh/knownhosts are used.\n\nlist This style is used by the historycompleteword bindable command. If it is set to\n`true' it has no effect. If it is set to `false' matches will not be listed. This\noverrides the setting of the options controlling listing behaviour, in particular\nAUTOLIST. The context always starts with `:completion:history-words'.\n" }, { "name": "list-colors", "content": "If the zsh/complist module is loaded, this style can be used to set color specifica‐\ntions. This mechanism replaces the use of the ZLSCOLORS and ZLSCOLOURS parameters\ndescribed in the section `The zsh/complist Module' in zshmodules(1), but the syntax is\nthe same.\n\nIf this style is set for the default tag, the strings in the value are taken as speci‐\nfications that are to be used everywhere. If it is set for other tags, the specifica‐\ntions are used only for matches of the type described by the tag. For this to work\nbest, the group-name style must be set to an empty string.\n\nIn addition to setting styles for specific tags, it is also possible to use group\nnames specified explicitly by the group-name tag together with the `(group)' syntax\nallowed by the ZLSCOLORS and ZLSCOLOURS parameters and simply using the default tag.\n\nIt is possible to use any color specifications already set up for the GNU version of\nthe ls command:\n\nzstyle ':completion:*:default' list-colors \\\n${(s.:.)LSCOLORS}\n\nThe default colors are the same as for the GNU ls command and can be obtained by set‐\nting the style to an empty string (i.e. '').\n" }, { "name": "list-dirs-first", "content": "This is used by file completion. If set, directories to be completed are listed sepa‐\nrately from and before completion for other files, regardless of tag ordering. In ad‐\ndition, the tag other-files is used in place of all-files for the remaining files, to\nindicate that no directories are presented with that tag.\n" }, { "name": "list-grouped", "content": "If this style is `true' (the default), the completion system will try to make certain\ncompletion listings more compact by grouping matches. For example, options for com‐\nmands that have the same description (shown when the verbose style is set to `true')\nwill appear as a single entry. However, menu selection can be used to cycle through\nall the matches.\n" }, { "name": "list-packed", "content": "This is tested for each tag valid in the current context as well as the default tag.\nIf it is set to `true', the corresponding matches appear in listings as if the\nLISTPACKED option were set. If it is set to `false', they are listed normally.\n" }, { "name": "list-prompt", "content": "If this style is set for the default tag, completion lists that don't fit on the\nscreen can be scrolled (see the description of the zsh/complist module in zshmod‐\nules(1)). The value, if not the empty string, will be displayed after every screenful\nand the shell will prompt for a key press; if the style is set to the empty string, a\ndefault prompt will be used.\n\nThe value may contain the escape sequences: `%l' or `%L', which will be replaced by\nthe number of the last line displayed and the total number of lines; `%m' or `%M', the\nnumber of the last match shown and the total number of matches; and `%p' and `%P',\n`Top' when at the beginning of the list, `Bottom' when at the end and the position\nshown as a percentage of the total length otherwise. In each case the form with the\nuppercase letter will be replaced by a string of fixed width, padded to the right\nwith spaces, while the lowercase form will be replaced by a variable width string. As\nin other prompt strings, the escape sequences `%S', `%s', `%B', `%b', `%U', `%u' for\nentering and leaving the display modes standout, bold and underline, and `%F', `%f',\n`%K', `%k' for changing the foreground background colour, are also available, as is\nthe form `%{...%}' for enclosing escape sequences which display with zero (or, with a\nnumeric argument, some other) width.\n\nAfter deleting this prompt the variable LISTPROMPT should be unset for the removal to\ntake effect.\n" }, { "name": "list-rows-first", "content": "This style is tested in the same way as the list-packed style and determines whether\nmatches are to be listed in a rows-first fashion as if the LISTROWSFIRST option were\nset.\n" }, { "name": "list-suffixes", "content": "This style is used by the function that completes filenames. If it is `true', and\ncompletion is attempted on a string containing multiple partially typed pathname com‐\nponents, all ambiguous components will be shown. Otherwise, completion stops at the\nfirst ambiguous component.\n" }, { "name": "list-separator", "content": "The value of this style is used in completion listing to separate the string to com‐\nplete from a description when possible (e.g. when completing options). It defaults to\n`--' (two hyphens).\n\nlocal This is for use with functions that complete URLs for which the corresponding files\nare available directly from the file system. Its value should consist of three\nstrings: a hostname, the path to the default web pages for the server, and the direc‐\ntory name used by a user placing web pages within their home area.\n\nFor example:\n\nzstyle ':completion:*' local toast \\\n/var/http/public/toast publichtml\n\nCompletion after `http://toast/stuff/' will look for files in the directory\n/var/http/public/toast/stuff, while completion after `http://toast/~yousir/' will\nlook for files in the directory ~yousir/publichtml.\n" }, { "name": "mail-directory", "content": "If set, zsh will assume that mailbox files can be found in the directory specified.\nIt defaults to `~/Mail'.\n" }, { "name": "match-original", "content": "This is used by the match completer. If it is set to only, match will try to gener‐\nate matches without inserting a `*' at the cursor position. If set to any other\nnon-empty value, it will first try to generate matches without inserting the `*' and\nif that yields no matches, it will try again with the `*' inserted. If it is unset or\nset to the empty string, matching will only be performed with the `*' inserted.\n" }, { "name": "matcher", "content": "This style is tested separately for each tag valid in the current context. Its value\nis placed before any match specifications given by the matcher-list style so can over‐\nride them via the use of an x: specification. The value should be in the form de‐\nscribed in the section `Completion Matching Control' in zshcompwid(1). For examples\nof this, see the description of the tag-order style.\n\nFor notes comparing the use of this and the matcher-list style, see under the descrip‐\ntion of the tag-order style.\n" }, { "name": "matcher-list", "content": "This style can be set to a list of match specifications that are to be applied every‐\nwhere. Match specifications are described in the section `Completion Matching Control'\nin zshcompwid(1). The completion system will try them one after another for each com‐\npleter selected. For example, to try first simple completion and, if that generates\nno matches, case-insensitive completion:\n\nzstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}'\n\nBy default each specification replaces the previous one; however, if a specification\nis prefixed with +, it is added to the existing list. Hence it is possible to create\nincreasingly general specifications without repetition:\n\nzstyle ':completion:*' matcher-list \\\n'' '+m:{a-z}={A-Z}' '+m:{A-Z}={a-z}'\n\nIt is possible to create match specifications valid for particular completers by using\nthe third field of the context. This applies only to completers that override the\nglobal matcher-list, which as of this writing includes only prefix and ignored. For\nexample, to use the completers complete and prefix but allow case-insensitive com‐\npletion only with complete:\n\nzstyle ':completion:*' completer complete prefix\nzstyle ':completion:*:complete:*:*:*' matcher-list \\\n'' 'm:{a-zA-Z}={A-Za-z}'\n\nUser-defined names, as explained for the completer style, are available. This makes\nit possible to try the same completer more than once with different match specifica‐\ntions each time. For example, to try normal completion without a match specification,\nthen normal completion with case-insensitive matching, then correction, and finally\npartial-word completion:\n\nzstyle ':completion:*' completer \\\ncomplete correct complete:foo\nzstyle ':completion:*:complete:*:*:*' matcher-list \\\n'' 'm:{a-zA-Z}={A-Za-z}'\nzstyle ':completion:*:foo:*:*:*' matcher-list \\\n'm:{a-zA-Z}={A-Za-z} r:|[-./]=* r:|=*'\n\nIf the style is unset in any context no match specification is applied. Note also\nthat some completers such as correct and approximate do not use the match specifica‐\ntions at all, though these completers will only ever be called once even if the\nmatcher-list contains more than one element.\n\nWhere multiple specifications are useful, note that the entire completion is done for\neach element of matcher-list, which can quickly reduce the shell's performance. As a\nrough rule of thumb, one to three strings will give acceptable performance. On the\nother hand, putting multiple space-separated values into the same string does not have\nan appreciable impact on performance.\n\nIf there is no current matcher or it is empty, and the option NOCASEGLOB is in ef‐\nfect, the matching for files is performed case-insensitively in any case. However,\nany matcher must explicitly specify case-insensitive matching if that is required.\n\nFor notes comparing the use of this and the matcher style, see under the description\nof the tag-order style.\n" }, { "name": "max-errors", "content": "This is used by the approximate and correct completer functions to determine the\nmaximum number of errors to allow. The completer will try to generate completions by\nfirst allowing one error, then two errors, and so on, until either a match or matches\nwere found or the maximum number of errors given by this style has been reached.\n\nIf the value for this style contains the string `numeric', the completer function will\ntake any numeric argument as the maximum number of errors allowed. For example, with\n\nzstyle ':completion:*:approximate:::' max-errors 2 numeric\n\ntwo errors are allowed if no numeric argument is given, but with a numeric argument of\nsix (as in `ESC-6 TAB'), up to six errors are accepted. Hence with a value of `0 nu‐‐\nmeric', no correcting completion will be attempted unless a numeric argument is given.\n\nIf the value contains the string `not-numeric', the completer will not try to generate\ncorrected completions when given a numeric argument, so in this case the number given\nshould be greater than zero. For example, `2 not-numeric' specifies that correcting\ncompletion with two errors will usually be performed, but if a numeric argument is\ngiven, correcting completion will not be performed.\n\nThe default value for this style is `2 numeric'.\n" }, { "name": "max-matches-width", "content": "This style is used to determine the trade off between the width of the display used\nfor matches and the width used for their descriptions when the verbose style is in ef‐\nfect. The value gives the number of display columns to reserve for the matches. The\ndefault is half the width of the screen.\n\nThis has the most impact when several matches have the same description and so will be\ngrouped together. Increasing the style will allow more matches to be grouped to‐\ngether; decreasing it will allow more of the description to be visible.\n\nmenu If this is `true' in the context of any of the tags defined for the current completion\nmenu completion will be used. The value for a specific tag will take precedence over\nthat for the `default' tag.\n\nIf none of the values found in this way is `true' but at least one is set to `auto',\nthe shell behaves as if the AUTOMENU option is set.\n\nIf one of the values is explicitly set to `false', menu completion will be explicitly\nturned off, overriding the MENUCOMPLETE option and other settings.\n\nIn the form `yes=num', where `yes' may be any of the `true' values (`yes', `true',\n`on' and `1'), menu completion will be turned on if there are at least num matches.\nIn the form `yes=long', menu completion will be turned on if the list does not fit on\nthe screen. This does not activate menu completion if the widget normally only lists\ncompletions, but menu completion can be activated in that case with the value\n`yes=long-list' (Typically, the value `select=long-list' described later is more use‐\nful as it provides control over scrolling.)\n\nSimilarly, with any of the `false' values (as in `no=10'), menu completion will not be\nused if there are num or more matches.\n\nThe value of this widget also controls menu selection, as implemented by the zsh/com‐‐\nplist module. The following values may appear either alongside or instead of the val‐\nues above.\n\nIf the value contains the string `select', menu selection will be started uncondition‐\nally.\n\nIn the form `select=num', menu selection will only be started if there are at least\nnum matches. If the values for more than one tag provide a number, the smallest num‐\nber is taken.\n\nMenu selection can be turned off explicitly by defining a value containing the\nstring`no-select'.\n\nIt is also possible to start menu selection only if the list of matches does not fit\non the screen by using the value `select=long'. To start menu selection even if the\ncurrent widget only performs listing, use the value `select=long-list'.\n\nTo turn on menu completion or menu selection when there are a certain number of\nmatches or the list of matches does not fit on the screen, both of `yes=' and `se‐‐\nlect=' may be given twice, once with a number and once with `long' or `long-list'.\n\nFinally, it is possible to activate two special modes of menu selection. The word\n`interactive' in the value causes interactive mode to be entered immediately when menu\nselection is started; see the description of the zsh/complist module in zshmodules(1)\nfor a description of interactive mode. Including the string `search' does the same\nfor incremental search mode. To select backward incremental search, include the\nstring `search-backward'.\n\nmuttrc If set, gives the location of the mutt configuration file. It defaults to `~/.mut‐‐\ntrc'.\n" }, { "name": "numbers", "content": "This is used with the jobs tag. If it is `true', the shell will complete job numbers\ninstead of the shortest unambiguous prefix of the job command text. If the value is a\nnumber, job numbers will only be used if that many words from the job descriptions are\nrequired to resolve ambiguities. For example, if the value is `1', strings will only\nbe used if all jobs differ in the first word on their command lines.\n" }, { "name": "old-list", "content": "This is used by the oldlist completer. If it is set to `always', then standard wid‐\ngets which perform listing will retain the current list of matches, however they were\ngenerated; this can be turned off explicitly with the value `never', giving the behav‐\niour without the oldlist completer. If the style is unset, or any other value, then\nthe existing list of completions is displayed if it is not already; otherwise, the\nstandard completion list is generated; this is the default behaviour of oldlist.\nHowever, if there is an old list and this style contains the name of the completer\nfunction that generated the list, then the old list will be used even if it was gener‐\nated by a widget which does not do listing.\n\nFor example, suppose you type ^Xc to use the correctword widget, which generates a\nlist of corrections for the word under the cursor. Usually, typing ^D would generate\na standard list of completions for the word on the command line, and show that. With\noldlist, it will instead show the list of corrections already generated.\n\nAs another example consider the match completer: with the insert-unambiguous style\nset to `true' it inserts only a common prefix string, if there is any. However, this\nmay remove parts of the original pattern, so that further completion could produce\nmore matches than on the first attempt. By using the oldlist completer and setting\nthis style to match, the list of matches generated on the first attempt will be used\nagain.\n" }, { "name": "old-matches", "content": "This is used by the allmatches completer to decide if an old list of matches should\nbe used if one exists. This is selected by one of the `true' values or by the string\n`only'. If the value is `only', allmatches will only use an old list and won't have\nany effect on the list of matches currently being generated.\n\nIf this style is set it is generally unwise to call the allmatches completer uncon‐\nditionally. One possible use is for either this style or the completer style to be\ndefined with the -e option to zstyle to make the style conditional.\n" }, { "name": "old-menu", "content": "This is used by the oldlist completer. It controls how menu completion behaves when\na completion has already been inserted and the user types a standard completion key\nsuch as TAB. The default behaviour of oldlist is that menu completion always contin‐\nues with the existing list of completions. If this style is set to `false', however,\na new completion is started if the old list was generated by a different completion\ncommand; this is the behaviour without the oldlist completer.\n\nFor example, suppose you type ^Xc to generate a list of corrections, and menu comple‐\ntion is started in one of the usual ways. Usually, or with this style set to `false',\ntyping TAB at this point would start trying to complete the line as it now appears.\nWith oldlist, it instead continues to cycle through the list of corrections.\n" }, { "name": "original", "content": "This is used by the approximate and correct completers to decide if the original\nstring should be added as a possible completion. Normally, this is done only if there\nare at least two possible corrections, but if this style is set to `true', it is al‐\nways added. Note that the style will be examined with the completer field in the con‐\ntext name set to correct-num or approximate-num, where num is the number of errors\nthat were accepted.\n" }, { "name": "packageset", "content": "This style is used when completing arguments of the Debian `dpkg' program. It con‐\ntains an override for the default package set for a given context. For example,\n\nzstyle ':completion:*:complete:dpkg:option--status-1:*' \\\npackageset avail\n\ncauses available packages, rather than only installed packages, to be completed for\n`dpkg --status'.\n\npath The function that completes color names uses this style with the colors tag. The\nvalue should be the pathname of a file containing color names in the format of an X11\nrgb.txt file. If the style is not set but this file is found in one of various stan‐\ndard locations it will be used as the default.\n" }, { "name": "path-completion", "content": "This is used by filename completion. By default, filename completion examines all\ncomponents of a path to see if there are completions of that component. For example,\n/u/b/z can be completed to /usr/bin/zsh. Explicitly setting this style to `false' in‐\nhibits this behaviour for path components up to the / before the cursor; this over‐\nrides the setting of accept-exact-dirs.\n\nEven with the style set to `false', it is still possible to complete multiple paths by\nsetting the option COMPLETEINWORD and moving the cursor back to the first component\nin the path to be completed. For example, /u/b/z can be completed to /usr/bin/zsh if\nthe cursor is after the /u.\n" }, { "name": "pine-directory", "content": "If set, specifies the directory containing PINE mailbox files. There is no default,\nsince recursively searching this directory is inconvenient for anyone who doesn't use\nPINE.\n\nports A list of Internet service names (network ports) to complete. If this is not set,\nservice names are taken from the file `/etc/services'.\n" }, { "name": "prefix-hidden", "content": "This is used for certain completions which share a common prefix, for example command\noptions beginning with dashes. If it is `true', the prefix will not be shown in the\nlist of matches.\n\nThe default value for this style is `false'.\n" }, { "name": "prefix-needed", "content": "This style is also relevant for matches with a common prefix. If it is set to `true'\nthis common prefix must be typed by the user to generate the matches.\n\nThe style is applicable to the options, signals, jobs, functions, and parameters com‐\npletion tags.\n\nFor command options, this means that the initial `-', `+', or `--' must be typed ex‐\nplicitly before option names will be completed.\n\nFor signals, an initial `-' is required before signal names will be completed.\n\nFor jobs, an initial `%' is required before job names will be completed.\n\nFor function and parameter names, an initial `' or `.' is required before function or\nparameter names starting with those characters will be completed.\n\nThe default value for this style is `false' for function and parameter completions,\nand `true' otherwise.\n" }, { "name": "preserve-prefix", "content": "This style is used when completing path names. Its value should be a pattern matching\nan initial prefix of the word to complete that should be left unchanged under all cir‐\ncumstances. For example, on some Unices an initial `//' (double slash) has a special\nmeaning; setting this style to the string `//' will preserve it. As another example,\nsetting this style to `?:/' under Cygwin would allow completion after `a:/...' and so\non.\n\nrange This is used by the history completer and the historycompleteword bindable command\nto decide which words should be completed.\n\nIf it is a single number, only the last N words from the history will be completed.\n\nIf it is a range of the form `max:slice', the last slice words will be completed; then\nif that yields no matches, the slice words before those will be tried and so on. This\nprocess stops either when at least one match has been found, or max words have been\ntried.\n\nThe default is to complete all words from the history at once.\n" }, { "name": "recursive-files", "content": "If this style is set, its value is an array of patterns to be tested against `$PWD/':\nnote the trailing slash, which allows directories in the pattern to be delimited unam‐\nbiguously by including slashes on both sides. If an ordinary file completion fails\nand the word on the command line does not yet have a directory part to its name, the\nstyle is retrieved using the same tag as for the completion just attempted, then the\nelements tested against $PWD/ in turn. If one matches, then the shell reattempts com‐\npletion by prepending the word on the command line with each directory in the expan‐\nsion of /*(/) in turn. Typically the elements of the style will be set to restrict\nthe number of directories beneath the current one to a manageable number, for example\n`*/.git/*'.\n\nFor example,\n\nzstyle ':completion:*' recursive-files '*/zsh/*'\n\nIf the current directory is /home/pws/zsh/Src, then zletrTAB can be completed to\nZle/zletricky.c.\n" }, { "name": "regular", "content": "This style is used by the expandalias completer and bindable command. If set to\n`true' (the default), regular aliases will be expanded but only in command position.\nIf it is set to `false', regular aliases will never be expanded. If it is set to\n`always', regular aliases will be expanded even if not in command position.\n\nrehash If this is set when completing external commands, the internal list (hash) of commands\nwill be updated for each search by issuing the rehash command. There is a speed pen‐\nalty for this which is only likely to be noticeable when directories in the path have\nslow file access.\n" }, { "name": "remote-access", "content": "If set to `false', certain commands will be prevented from making Internet connections\nto retrieve remote information. This includes the completion for the CVS command.\n\nIt is not always possible to know if connections are in fact to a remote site, so some\nmay be prevented unnecessarily.\n" }, { "name": "remove-all-dups", "content": "The historycompleteword bindable command and the history completer use this to de‐\ncide if all duplicate matches should be removed, rather than just consecutive dupli‐\ncates.\n" }, { "name": "select-prompt", "content": "If this is set for the default tag, its value will be displayed during menu selection\n(see the menu style above) when the completion list does not fit on the screen as a\nwhole. The same escapes as for the list-prompt style are understood, except that the\nnumbers refer to the match or line the mark is on. A default prompt is used when the\nvalue is the empty string.\n" }, { "name": "select-scroll", "content": "This style is tested for the default tag and determines how a completion list is\nscrolled during a menu selection (see the menu style above) when the completion list\ndoes not fit on the screen as a whole. If the value is `0' (zero), the list is\nscrolled by half-screenfuls; if it is a positive integer, the list is scrolled by the\ngiven number of lines; if it is a negative number, the list is scrolled by a screenful\nminus the absolute value of the given number of lines. The default is to scroll by\nsingle lines.\n" }, { "name": "separate-sections", "content": "This style is used with the manuals tag when completing names of manual pages. If it\nis `true', entries for different sections are added separately using tag names of the\nform `manual.X', where X is the section number. When the group-name style is also in\neffect, pages from different sections will appear separately. This style is also used\nsimilarly with the words style when completing words for the dict command. It allows\nwords from different dictionary databases to be added separately. The default for\nthis style is `false'.\n" }, { "name": "show-ambiguity", "content": "If the zsh/complist module is loaded, this style can be used to highlight the first\nambiguous character in completion lists. The value is either a color indication such\nas those supported by the list-colors style or, with a value of `true', a default of\nunderlining is selected. The highlighting is only applied if the completion display\nstrings correspond to the actual matches.\n" }, { "name": "show-completer", "content": "Tested whenever a new completer is tried. If it is `true', the completion system out‐\nputs a progress message in the listing area showing what completer is being tried.\nThe message will be overwritten by any output when completions are found and is re‐\nmoved after completion is finished.\n" }, { "name": "single-ignored", "content": "This is used by the ignored completer when there is only one match. If its value is\n`show', the single match will be displayed but not inserted. If the value is `menu',\nthen the single match and the original string are both added as matches and menu com‐\npletion is started, making it easy to select either of them.\n\nsort This allows the standard ordering of matches to be overridden.\n\nIf its value is `true' or `false', sorting is enabled or disabled. Additionally the\nvalues associated with the `-o' option to compadd can also be listed: match, nosort,\nnumeric, reverse. If it is not set for the context, the standard behaviour of the\ncalling widget is used.\n\nThe style is tested first against the full context including the tag, and if that\nfails to produce a value against the context without the tag.\n\nIn many cases where a calling widget explicitly selects a particular ordering in lieu\nof the default, a value of `true' is not honoured. An example of where this is not\nthe case is for command history where the default of sorting matches chronologically\nmay be overridden by setting the style to `true'.\n\nIn the expand completer, if it is set to `true', the expansions generated will always\nbe sorted. If it is set to `menu', then the expansions are only sorted when they are\noffered as single strings but not in the string containing all possible expansions.\n" }, { "name": "special-dirs", "content": "Normally, the completion code will not produce the directory names `.' and `..' as\npossible completions. If this style is set to `true', it will add both `.' and `..'\nas possible completions; if it is set to `..', only `..' will be added.\n\nThe following example sets special-dirs to `..' when the current prefix is empty, is a\nsingle `.', or consists only of a path beginning with `../'. Otherwise the value is\n`false'.\n\nzstyle -e ':completion:*' special-dirs \\\n'[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)'\n" }, { "name": "squeeze-slashes", "content": "If set to `true', sequences of slashes in filename paths (for example in `foo//bar')\nwill be treated as a single slash. This is the usual behaviour of UNIX paths. How‐\never, by default the file completion function behaves as if there were a `*' between\nthe slashes.\n\nstop If set to `true', the historycompleteword bindable command will stop once when\nreaching the beginning or end of the history. Invoking historycompleteword will\nthen wrap around to the opposite end of the history. If this style is set to `false'\n(the default), historycompleteword will loop immediately as in a menu completion.\n" }, { "name": "strip-comments", "content": "If set to `true', this style causes non-essential comment text to be removed from com‐\npletion matches. Currently it is only used when completing e-mail addresses where it\nremoves any display name from the addresses, cutting them down to plain user@host\nform.\n" }, { "name": "subst-globs-only", "content": "This is used by the expand completer. If it is set to `true', the expansion will\nonly be used if it resulted from globbing; hence, if expansions resulted from the use\nof the substitute style described below, but these were not further changed by glob‐\nbing, the expansions will be rejected.\n\nThe default for this style is `false'.\n" }, { "name": "substitute", "content": "This boolean style controls whether the expand completer will first try to expand all\nsubstitutions in the string (such as `$(...)' and `${...}').\n\nThe default is `true'.\n\nsuffix This is used by the expand completer if the word starts with a tilde or contains a\nparameter expansion. If it is set to `true', the word will only be expanded if it\ndoesn't have a suffix, i.e. if it is something like `~foo' or `$foo' rather than\n`~foo/' or `$foo/bar', unless that suffix itself contains characters eligible for ex‐\npansion. The default for this style is `true'.\n" }, { "name": "tag-order", "content": "This provides a mechanism for sorting how the tags available in a particular context\nwill be used.\n\nThe values for the style are sets of space-separated lists of tags. The tags in each\nvalue will be tried at the same time; if no match is found, the next value is used.\n(See the file-patterns style for an exception to this behavior.)\n\nFor example:\n\nzstyle ':completion:*:complete:-command-:*:*' tag-order \\\n'commands functions'\n\nspecifies that completion in command position first offers external commands and shell\nfunctions. Remaining tags will be tried if no completions are found.\n\nIn addition to tag names, each string in the value may take one of the following\nforms:\n\n- If any value consists of only a hyphen, then only the tags specified in the\nother values are generated. Normally all tags not explicitly selected are\ntried last if the specified tags fail to generate any matches. This means that\na single value consisting only of a single hyphen turns off completion.\n\n! tags...\nA string starting with an exclamation mark specifies names of tags that are not\nto be used. The effect is the same as if all other possible tags for the con‐\ntext had been listed.\n\ntag:label ...\nHere, tag is one of the standard tags and label is an arbitrary name. Matches\nare generated as normal but the name label is used in contexts instead of tag.\nThis is not useful in words starting with !.\n\nIf the label starts with a hyphen, the tag is prepended to the label to form\nthe name used for lookup. This can be used to make the completion system try a\ncertain tag more than once, supplying different style settings for each at‐\ntempt; see below for an example.\n\ntag:label:description\nAs before, but description will replace the `%d' in the value of the format\nstyle instead of the default description supplied by the completion function.\nSpaces in the description must be quoted with a backslash. A `%d' appearing in\ndescription is replaced with the description given by the completion function.\n\nIn any of the forms above the tag may be a pattern or several patterns in the form\n`{pat1,pat2...}'. In this case all matching tags will be used except for any given\nexplicitly in the same string.\n\nOne use of these features is to try one tag more than once, setting other styles dif‐\nferently on each attempt, but still to use all the other tags without having to repeat\nthem all. For example, to make completion of function names in command position ig‐\nnore all the completion functions starting with an underscore the first time comple‐\ntion is tried:\n\nzstyle ':completion:*:*:-command-:*:*' tag-order \\\n'functions:-non-comp *' functions\nzstyle ':completion:*:functions-non-comp' \\\nignored-patterns '*'\n\nOn the first attempt, all tags will be offered but the functions tag will be replaced\nby functions-non-comp. The ignored-patterns style is set for this tag to exclude\nfunctions starting with an underscore. If there are no matches, the second value of\nthe tag-order style is used which completes functions using the default tag, this time\npresumably including all function names.\n\nThe matches for one tag can be split into different groups. For example:\n\nzstyle ':completion:*' tag-order \\\n'options:-long:long\\ options\noptions:-short:short\\ options\noptions:-single-letter:single\\ letter\\ options'\nzstyle ':completion:*:options-long' \\\nignored-patterns '[-+](|-|[^-]*)'\nzstyle ':completion:*:options-short' \\\nignored-patterns '--*' '[-+]?'\nzstyle ':completion:*:options-single-letter' \\\nignored-patterns '???*'\n\nWith the group-names style set, options beginning with `--', options beginning with a\nsingle `-' or `+' but containing multiple characters, and single-letter options will\nbe displayed in separate groups with different descriptions.\n\nAnother use of patterns is to try multiple match specifications one after another.\nThe matcher-list style offers something similar, but it is tested very early in the\ncompletion system and hence can't be set for single commands nor for more specific\ncontexts. Here is how to try normal completion without any match specification and,\nif that generates no matches, try again with case-insensitive matching, restricting\nthe effect to arguments of the command foo:\n\nzstyle ':completion:*:*:foo:*:*' tag-order '*' '*:-case'\nzstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'\n\nFirst, all the tags offered when completing after foo are tried using the normal tag\nname. If that generates no matches, the second value of tag-order is used, which\ntries all tags again except that this time each has -case appended to its name for\nlookup of styles. Hence this time the value for the matcher style from the second\ncall to zstyle in the example is used to make completion case-insensitive.\n\nIt is possible to use the -e option of the zstyle builtin command to specify condi‐\ntions for the use of particular tags. For example:\n\nzstyle -e '*:-command-:*' tag-order '\nif [[ -n $PREFIX$SUFFIX ]]; then\nreply=( )\nelse\nreply=( - )\nfi'\n\nCompletion in command position will be attempted only if the string typed so far is\nnot empty. This is tested using the PREFIX special parameter; see zshcompwid for a\ndescription of parameters which are special inside completion widgets. Setting reply\nto an empty array provides the default behaviour of trying all tags at once; setting\nit to an array containing only a hyphen disables the use of all tags and hence of all\ncompletions.\n\nIf no tag-order style has been defined for a context, the strings `(|*-)argument-*\n(|*-)option-* values' and `options' plus all tags offered by the completion function\nwill be used to provide a sensible default behavior that causes arguments (whether\nnormal command arguments or arguments of options) to be completed before option names\nfor most commands.\n\nurls This is used together with the urls tag by functions completing URLs.\n\nIf the value consists of more than one string, or if the only string does not name a\nfile or directory, the strings are used as the URLs to complete.\n\nIf the value contains only one string which is the name of a normal file the URLs are\ntaken from that file (where the URLs may be separated by white space or newlines).\n\nFinally, if the only string in the value names a directory, the directory hierarchy\nrooted at this directory gives the completions. The top level directory should be the\nfile access method, such as `http', `ftp', `bookmark' and so on. In many cases the\nnext level of directories will be a filename. The directory hierarchy can descend as\ndeep as necessary.\n\nFor example,\n\nzstyle ':completion:*' urls ~/.urls\nmkdir -p ~/.urls/ftp/ftp.zsh.org/pub\n\nallows completion of all the components of the URL ftp://ftp.zsh.org/pub after suit‐\nable commands such as `netscape' or `lynx'. Note, however, that access methods and\nfiles are completed separately, so if the hosts style is set hosts can be completed\nwithout reference to the urls style.\n\nSee the description in the function urls itself for more information (e.g. `more\n$^fpath/urls(N)').\n" }, { "name": "use-cache", "content": "If this is set, the completion caching layer is activated for any completions which\nuse it (via the storecache, retrievecache, and cacheinvalid functions). The di‐\nrectory containing the cache files can be changed with the cache-path style.\n" }, { "name": "use-compctl", "content": "If this style is set to a string not equal to false, 0, no, and off, the completion\nsystem may use any completion specifications defined with the compctl builtin command.\nIf the style is unset, this is done only if the zsh/compctl module is loaded. The\nstring may also contain the substring `first' to use completions defined with `compctl\n-T', and the substring `default' to use the completion defined with `compctl -D'.\n\nNote that this is only intended to smooth the transition from compctl to the new com‐\npletion system and may disappear in the future.\n\nNote also that the definitions from compctl will only be used if there is no specific\ncompletion function for the command in question. For example, if there is a function\nfoo to complete arguments to the command foo, compctl will never be invoked for foo.\nHowever, the compctl version will be tried if foo only uses default completion.\n\nuse-ip By default, the function hosts that completes host names strips IP addresses from en‐\ntries read from host databases such as NIS and ssh files. If this style is `true',\nthe corresponding IP addresses can be completed as well. This style is not use in any\ncontext where the hosts style is set; note also it must be set before the cache of\nhost names is generated (typically the first completion attempt).\n\nusers This may be set to a list of usernames to be completed. If it is not set all user‐\nnames will be completed. Note that if it is set only that list of users will be com‐\npleted; this is because on some systems querying all users can take a prohibitive\namount of time.\n" }, { "name": "users-hosts", "content": "The values of this style should be of the form `user@host' or `user:host'. It is used\nfor commands that need pairs of user- and hostnames. These commands will complete\nusernames from this style (only), and will restrict subsequent hostname completion to\nhosts paired with that user in one of the values of the style.\n\nIt is possible to group values for sets of commands which allow a remote login, such\nas rlogin and ssh, by using the my-accounts tag. Similarly, values for sets of com‐\nmands which usually refer to the accounts of other people, such as talk and finger,\ncan be grouped by using the other-accounts tag. More ambivalent commands may use the\naccounts tag.\n" }, { "name": "users-hosts-ports", "content": "Like users-hosts but used for commands like telnet and containing strings of the form\n`user@host:port'.\n" }, { "name": "verbose", "content": "If set, as it is by default, the completion listing is more verbose. In particular\nmany commands show descriptions for options if this style is `true'.\n\nword This is used by the list completer, which prevents the insertion of completions until\na second completion attempt when the line has not changed. The normal way of finding\nout if the line has changed is to compare its entire contents between the two occa‐\nsions. If this style is `true', the comparison is instead performed only on the cur‐\nrent word. Hence if completion is performed on another word with the same contents,\ncompletion will not be delayed.\n" } ] }, "CONTROL FUNCTIONS": { "content": "The initialization script compinit redefines all the widgets which perform completion to call\nthe supplied widget function maincomplete. This function acts as a wrapper calling the\nso-called `completer' functions that generate matches. If maincomplete is called with ar‐\nguments, these are taken as the names of completer functions to be called in the order given.\nIf no arguments are given, the set of functions to try is taken from the completer style.\nFor example, to use normal completion and correction if that doesn't generate any matches:\n\nzstyle ':completion:*' completer complete correct\n\nafter calling compinit. The default value for this style is `complete ignored', i.e. nor‐\nmally only ordinary completion is tried, first with the effect of the ignored-patterns style\nand then without it. The maincomplete function uses the return status of the completer\nfunctions to decide if other completers should be called. If the return status is zero, no\nother completers are tried and the maincomplete function returns.\n\nIf the first argument to maincomplete is a single hyphen, the arguments will not be taken\nas names of completers. Instead, the second argument gives a name to use in the completer\nfield of the context and the other arguments give a command name and arguments to call to\ngenerate the matches.\n\nThe following completer functions are contained in the distribution, although users may write\ntheir own. Note that in contexts the leading underscore is stripped, for example basic com‐\npletion is performed in the context `:completion::complete:...'.\n\nallmatches\nThis completer can be used to add a string consisting of all other matches. As it in‐\nfluences later completers it must appear as the first completer in the list. The list\nof all matches is affected by the avoid-completer and old-matches styles described\nabove.\n\nIt may be useful to use the generic function described below to bind allmatches to\nits own keystroke, for example:\n\nzle -C all-matches complete-word generic\nbindkey '^Xa' all-matches\nzstyle ':completion:all-matches:*' old-matches only\nzstyle ':completion:all-matches::::' completer allmatches\n\nNote that this does not generate completions by itself: first use any of the standard\nways of generating a list of completions, then use ^Xa to show all matches. It is\npossible instead to add a standard completer to the list and request that the list of\nall matches should be directly inserted:\n\nzstyle ':completion:all-matches::::' completer \\\nallmatches complete\nzstyle ':completion:all-matches:*' insert true\n\nIn this case the old-matches style should not be set.\n\napproximate\nThis is similar to the basic complete completer but allows the completions to undergo\ncorrections. The maximum number of errors can be specified by the max-errors style;\nsee the description of approximate matching in zshexpn(1) for how errors are counted.\nNormally this completer will only be tried after the normal complete completer:\n\nzstyle ':completion:*' completer complete approximate\n\nThis will give correcting completion if and only if normal completion yields no possi‐\nble completions. When corrected completions are found, the completer will normally\nstart menu completion allowing you to cycle through these strings.\n\nThis completer uses the tags corrections and original when generating the possible\ncorrections and the original string. The format style for the former may contain the\nadditional sequences `%e' and `%o' which will be replaced by the number of errors ac‐\ncepted to generate the corrections and the original string, respectively.\n\nThe completer progressively increases the number of errors allowed up to the limit by\nthe max-errors style, hence if a completion is found with one error, no completions\nwith two errors will be shown, and so on. It modifies the completer name in the con‐\ntext to indicate the number of errors being tried: on the first try the completer\nfield contains `approximate-1', on the second try `approximate-2', and so on.\n\nWhen approximate is called from another function, the number of errors to accept may\nbe passed with the -a option. The argument is in the same format as the max-errors\nstyle, all in one string.\n\nNote that this completer (and the correct completer mentioned below) can be quite ex‐\npensive to call, especially when a large number of errors are allowed. One way to\navoid this is to set up the completer style using the -e option to zstyle so that some\ncompleters are only used when completion is attempted a second time on the same\nstring, e.g.:\n\nzstyle -e ':completion:*' completer '\nif [[ $lasttry != \"$HISTNO$BUFFER$CURSOR\" ]]; then\nlasttry=\"$HISTNO$BUFFER$CURSOR\"\nreply=(complete match prefix)\nelse\nreply=(ignored correct approximate)\nfi'\n\nThis uses the HISTNO parameter and the BUFFER and CURSOR special parameters that are\navailable inside zle and completion widgets to find out if the command line hasn't\nchanged since the last time completion was tried. Only then are the ignored, cor‐‐\nrect and approximate completers called.\n\ncanonicalpaths [ -A var ] [ -N ] [ -MJV12nfX ] tag descr [ paths ... ]\nThis completion function completes all paths given to it, and also tries to offer com‐\npletions which point to the same file as one of the paths given (relative path when an\nabsolute path is given, and vice versa; when ..'s are present in the word to be com‐\npleted; and some paths got from symlinks).\n\n-A, if specified, takes the paths from the array variable specified. Paths can also be\nspecified on the command line as shown above. -N, if specified, prevents canonicaliz‐\ning the paths given before using them for completion, in case they are already so. The\noptions -M, -J, -V, -1, -2, -n, -F, -X are passed to compadd.\n\nSee description for a description of tag and descr.\n\ncmdambivalent\nCompletes the remaining positional arguments as an external command. The external\ncommand and its arguments are completed as separate arguments (in a manner appropriate\nfor completing /usr/bin/env) if there are two or more remaining positional arguments\non the command line, and as a quoted command string (in the manner of system(...))\notherwise. See also cmdstring and precommand.\n\nThis function takes no arguments.\n\ncmdstring\nCompletes an external command as a single argument, as for system(...).\n\ncomplete\nThis completer generates all possible completions in a context-sensitive manner, i.e.\nusing the settings defined with the compdef function explained above and the current\nsettings of all special parameters. This gives the normal completion behaviour.\n\nTo complete arguments of commands, complete uses the utility function normal, which\nis in turn responsible for finding the particular function; it is described below.\nVarious contexts of the form -context- are handled specifically. These are all men‐\ntioned above as possible arguments to the #compdef tag.\n\nBefore trying to find a function for a specific context, complete checks if the pa‐\nrameter `compcontext' is set. Setting `compcontext' allows the usual completion dis‐\npatching to be overridden which is useful in places such as a function that uses vared\nfor input. If it is set to an array, the elements are taken to be the possible matches\nwhich will be completed using the tag `values' and the description `value'. If it is\nset to an associative array, the keys are used as the possible completions and the\nvalues (if non-empty) are used as descriptions for the matches. If `compcontext' is\nset to a string containing colons, it should be of the form `tag:descr:action'. In\nthis case the tag and descr give the tag and description to use and the action indi‐\ncates what should be completed in one of the forms accepted by the arguments utility\nfunction described below.\n\nFinally, if `compcontext' is set to a string without colons, the value is taken as the\nname of the context to use and the function defined for that context will be called.\nFor this purpose, there is a special context named -command-line- that completes whole\ncommand lines (commands and their arguments). This is not used by the completion sys‐\ntem itself but is nonetheless handled when explicitly called.\n\ncorrect\nGenerate corrections, but not completions, for the current word; this is similar to\napproximate but will not allow any number of extra characters at the cursor as that\ncompleter does. The effect is similar to spell-checking. It is based on approxi‐‐\nmate, but the completer field in the context name is correct.\n\nFor example, with:\n\nzstyle ':completion:::::' completer \\\ncomplete correct approximate\nzstyle ':completion:*:correct:::' max-errors 2 not-numeric\nzstyle ':completion:*:approximate:::' max-errors 3 numeric\n\ncorrection will accept up to two errors. If a numeric argument is given, correction\nwill not be performed, but correcting completion will be, and will accept as many er‐\nrors as given by the numeric argument. Without a numeric argument, first correction\nand then correcting completion will be tried, with the first one accepting two errors\nand the second one accepting three errors.\n\nWhen correct is called as a function, the number of errors to accept may be given\nfollowing the -a option. The argument is in the same form a values to the accept\nstyle, all in one string.\n\nThis completer function is intended to be used without the approximate completer or,\nas in the example, just before it. Using it after the approximate completer is use‐\nless since approximate will at least generate the corrected strings generated by the\ncorrect completer -- and probably more.\n\nexpand\nThis completer function does not really perform completion, but instead checks if the\nword on the command line is eligible for expansion and, if it is, gives detailed con‐\ntrol over how this expansion is done. For this to happen, the completion system needs\nto be invoked with complete-word, not expand-or-complete (the default binding for\nTAB), as otherwise the string will be expanded by the shell's internal mechanism be‐\nfore the completion system is started. Note also this completer should be called be‐\nfore the complete completer function.\n\nThe tags used when generating expansions are all-expansions for the string containing\nall possible expansions, expansions when adding the possible expansions as single\nmatches and original when adding the original string from the line. The order in\nwhich these strings are generated, if at all, can be controlled by the group-order and\ntag-order styles, as usual.\n\nThe format string for all-expansions and for expansions may contain the sequence `%o'\nwhich will be replaced by the original string from the line.\n\nThe kind of expansion to be tried is controlled by the substitute, glob and\nsubst-globs-only styles.\n\nIt is also possible to call expand as a function, in which case the different modes\nmay be selected with options: -s for substitute, -g for glob and -o for\nsubst-globs-only.\n\nexpandalias\nIf the word the cursor is on is an alias, it is expanded and no other completers are\ncalled. The types of aliases which are to be expanded can be controlled with the\nstyles regular, global and disabled.\n\nThis function is also a bindable command, see the section `Bindable Commands' below.\n\nextensions\nIf the cursor follows the string `*.', filename extensions are completed. The exten‐\nsions are taken from files in current directory or a directory specified at the begin‐\nning of the current word. For exact matches, completion continues to allow other com‐\npleters such as expand to expand the pattern. The standard add-space and prefix-hid‐‐\nden styles are observed.\n\nexternalpwds\nCompletes current directories of other zsh processes belonging to the current user.\n\nThis is intended to be used via generic, bound to a custom key combination. Note that\npattern matching is enabled so matching is performed similar to how it works with the\nmatch completer.\n\nhistory\nComplete words from the shell's command history. This completer can be controlled by\nthe remove-all-dups, and sort styles as for the historycompleteword bindable com‐\nmand, see the section `Bindable Commands' below and the section `Completion System\nConfiguration' above.\n\nignored\nThe ignored-patterns style can be set to a list of patterns which are compared against\npossible completions; matching ones are removed. With this completer those matches\ncan be reinstated, as if no ignored-patterns style were set. The completer actually\ngenerates its own list of matches; which completers are invoked is determined in the\nsame way as for the prefix completer. The single-ignored style is also available as\ndescribed above.\n\nlist This completer allows the insertion of matches to be delayed until completion is at‐\ntempted a second time without the word on the line being changed. On the first at‐\ntempt, only the list of matches will be shown. It is affected by the styles condition\nand word, see the section `Completion System Configuration' above.\n\nmatch This completer is intended to be used after the complete completer. It behaves simi‐\nlarly but the string on the command line may be a pattern to match against trial com‐\npletions. This gives the effect of the GLOBCOMPLETE option.\n\nNormally completion will be performed by taking the pattern from the line, inserting a\n`*' at the cursor position and comparing the resulting pattern with the possible com‐\npletions generated. This can be modified with the match-original style described\nabove.\n\nThe generated matches will be offered in a menu completion unless the insert-unambigu‐‐\nous style is set to `true'; see the description above for other options for this\nstyle.\n\nNote that matcher specifications defined globally or used by the completion functions\n(the styles matcher-list and matcher) will not be used.\n\nmenu This completer was written as simple example function to show how menu completion can\nbe enabled in shell code. However, it has the notable effect of disabling menu selec‐\ntion which can be useful with generic based widgets. It should be used as the first\ncompleter in the list. Note that this is independent of the setting of the MENUCOM‐‐\nPLETE option and does not work with the other menu completion widgets such as re‐‐\nverse-menu-complete, or accept-and-menu-complete.\n\noldlist\nThis completer controls how the standard completion widgets behave when there is an\nexisting list of completions which may have been generated by a special completion\n(i.e. a separately-bound completion command). It allows the ordinary completion keys\nto continue to use the list of completions thus generated, instead of producing a new\nlist of ordinary contextual completions. It should appear in the list of completers\nbefore any of the widgets which generate matches. It uses two styles: old-list and\nold-menu, see the section `Completion System Configuration' above.\n\nprecommand\nComplete an external command in word-separated arguments, as for exec and\n/usr/bin/env.\n\nprefix\nThis completer can be used to try completion with the suffix (everything after the\ncursor) ignored. In other words, the suffix will not be considered to be part of the\nword to complete. The effect is similar to the expand-or-complete-prefix command.\n\nThe completer style is used to decide which other completers are to be called to gen‐\nerate matches. If this style is unset, the list of completers set for the current\ncontext is used -- except, of course, the prefix completer itself. Furthermore, if\nthis completer appears more than once in the list of completers only those completers\nnot already tried by the last invocation of prefix will be called.\n\nFor example, consider this global completer style:\n\nzstyle ':completion:*' completer \\\ncomplete prefix correct prefix:foo\n\nHere, the prefix completer tries normal completion but ignoring the suffix. If that\ndoesn't generate any matches, and neither does the call to the correct completer af‐\nter it, prefix will be called a second time and, now only trying correction with the\nsuffix ignored. On the second invocation the completer part of the context appears as\n`foo'.\n\nTo use prefix as the last resort and try only normal completion when it is invoked:\n\nzstyle ':completion:*' completer complete ... prefix\nzstyle ':completion::prefix:*' completer complete\n\nThe add-space style is also respected. If it is set to `true' then prefix will in‐\nsert a space between the matches generated (if any) and the suffix.\n\nNote that this completer is only useful if the COMPLETEINWORD option is set; other‐\nwise, the cursor will be moved to the end of the current word before the completion\ncode is called and hence there will be no suffix.\n\nuserexpand\nThis completer behaves similarly to the expand completer but instead performs expan‐\nsions defined by users. The styles add-space and sort styles specific to the expand\ncompleter are usable with userexpand in addition to other styles handled more gener‐\nally by the completion system. The tag all-expansions is also available.\n\nThe expansion depends on the array style user-expand being defined for the current\ncontext; remember that the context for completers is less specific than that for con‐\ntextual completion as the full context has not yet been determined. Elements of the\narray may have one of the following forms:\n\n$hash\n\nhash is the name of an associative array. Note this is not a full parameter\nexpression, merely a $, suitably quoted to prevent immediate expansion, fol‐\nlowed by the name of an associative array. If the trial expansion word matches\na key in hash, the resulting expansion is the corresponding value.\nfunc\n\nfunc is the name of a shell function whose name must begin with but is not\notherwise special to the completion system. The function is called with the\ntrial word as an argument. If the word is to be expanded, the function should\nset the array reply to a list of expansions. Optionally, it can set REPLY to a\nword that will be used as a description for the set of expansions. The return\nstatus of the function is irrelevant.", "subsections": [] }, "BINDABLE COMMANDS": { "content": "In addition to the context-dependent completions provided, which are expected to work in an\nintuitively obvious way, there are a few widgets implementing special behaviour which can be\nbound separately to keys. The following is a list of these and their default bindings.\n\nbashcompletions\nThis function is used by two widgets, bashcomplete-word and bashlist-choices. It\nexists to provide compatibility with completion bindings in bash. The last character\nof the binding determines what is completed: `!', command names; `$', environment\nvariables; `@', host names; `/', file names; `~' user names. In bash, the binding\npreceded by `\\e' gives completion, and preceded by `^X' lists options. As some of\nthese bindings clash with standard zsh bindings, only `\\e~' and `^X~' are bound by de‐\nfault. To add the rest, the following should be added to .zshrc after compinit has\nbeen run:\n\nfor key in '!' '$' '@' '/' '~'; do\nbindkey \"\\e$key\" bashcomplete-word\nbindkey \"^X$key\" bashlist-choices\ndone\n\nThis includes the bindings for `~' in case they were already bound to something else;\nthe completion code does not override user bindings.\n\ncorrectfilename (^XC)\nCorrect the filename path at the cursor position. Allows up to six errors in the\nname. Can also be called with an argument to correct a filename path, independently\nof zle; the correction is printed on standard output.\n\ncorrectword (^Xc)\nPerforms correction of the current argument using the usual contextual completions as\npossible choices. This stores the string `correct-word' in the function field of the\ncontext name and then calls the correct completer.\n\nexpandalias (^Xa)\nThis function can be used as a completer and as a bindable command. It expands the\nword the cursor is on if it is an alias. The types of alias expanded can be con‐\ntrolled with the styles regular, global and disabled.\n\nWhen used as a bindable command there is one additional feature that can be selected\nby setting the complete style to `true'. In this case, if the word is not the name of\nan alias, expandalias tries to complete the word to a full alias name without ex‐\npanding it. It leaves the cursor directly after the completed word so that invoking\nexpandalias once more will expand the now-complete alias name.\n\nexpandword (^Xe)\nPerforms expansion on the current word: equivalent to the standard expand-word com‐\nmand, but using the expand completer. Before calling it, the function field of the\ncontext is set to `expand-word'.\n\ngeneric\nThis function is not defined as a widget and not bound by default. However, it can be\nused to define a widget and will then store the name of the widget in the function\nfield of the context and call the completion system. This allows custom completion\nwidgets with their own set of style settings to be defined easily. For example, to\ndefine a widget that performs normal completion and starts menu selection:\n\nzle -C foo complete-word generic\nbindkey '...' foo\nzstyle ':completion:foo:*' menu yes select=1\n\nNote in particular that the completer style may be set for the context in order to\nchange the set of functions used to generate possible matches. If generic is called\nwith arguments, those are passed through to maincomplete as the list of completers\nin place of those defined by the completer style.\n\nhistorycompleteword (\\e/)\nComplete words from the shell's command history. This uses the list, remove-all-dups,\nsort, and stop styles.\n\nmostrecentfile (^Xm)\nComplete the name of the most recently modified file matching the pattern on the com‐\nmand line (which may be blank). If given a numeric argument N, complete the Nth most\nrecently modified file. Note the completion, if any, is always unique.\n\nnexttags (^Xn)\nThis command alters the set of matches used to that for the next tag, or set of tags,\neither as given by the tag-order style or as set by default; these matches would oth‐\nerwise not be available. Successive invocations of the command cycle through all pos‐\nsible sets of tags.\n\nreadcomp (^X^R)\nPrompt the user for a string, and use that to perform completion on the current word.\nThere are two possibilities for the string. First, it can be a set of words beginning\n`', for example `files -/', in which case the function with any arguments will be\ncalled to generate the completions. Unambiguous parts of the function name will be\ncompleted automatically (normal completion is not available at this point) until a\nspace is typed.\n\nSecond, any other string will be passed as a set of arguments to compadd and should\nhence be an expression specifying what should be completed.\n\nA very restricted set of editing commands is available when reading the string: `DEL'\nand `^H' delete the last character; `^U' deletes the line, and `^C' and `^G' abort the\nfunction, while `RET' accepts the completion. Note the string is used verbatim as a\ncommand line, so arguments must be quoted in accordance with standard shell rules.\n\nOnce a string has been read, the next call to readcomp will use the existing string\ninstead of reading a new one. To force a new string to be read, call readcomp with\na numeric argument.\n\ncompletedebug (^X?)\nThis widget performs ordinary completion, but captures in a temporary file a trace of\nthe shell commands executed by the completion system. Each completion attempt gets\nits own file. A command to view each of these files is pushed onto the editor buffer\nstack.\n\ncompletehelp (^Xh)\nThis widget displays information about the context names, the tags, and the completion\nfunctions used when completing at the current cursor position. If given a numeric ar‐\ngument other than 1 (as in `ESC-2 ^Xh'), then the styles used and the contexts for\nwhich they are used will be shown, too.\n\nNote that the information about styles may be incomplete; it depends on the informa‐\ntion available from the completion functions called, which in turn is determined by\nthe user's own styles and other settings.\n\ncompletehelpgeneric\nUnlike other commands listed here, this must be created as a normal ZLE widget rather\nthan a completion widget (i.e. with zle -N). It is used for generating help with a\nwidget bound to the generic widget that is described above.\n\nIf this widget is created using the name of the function, as it is by default, then\nwhen executed it will read a key sequence. This is expected to be bound to a call to\na completion function that uses the generic widget. That widget will be executed,\nand information provided in the same format that the completehelp widget displays\nfor contextual completion.\n\nIf the widget's name contains debug, for example if it is created as `zle -N com‐‐\npletedebuggeneric completehelpgeneric', it will read and execute the keystring\nfor a generic widget as before, but then generate debugging information as done by\ncompletedebug for contextual completion.\n\nIf the widget's name contains noread, it will not read a keystring but instead arrange\nthat the next use of a generic widget run in the same shell will have the effect as\ndescribed above.\n\nThe widget works by setting the shell parameter ZSHTRACEGENERICWIDGET which is read\nby generic. Unsetting the parameter cancels any pending effect of the noread form.\n\nFor example, after executing the following:\n\nzle -N completedebuggeneric completehelpgeneric\nbindkey '^x:' completedebuggeneric\n\ntyping `C-x :' followed by the key sequence for a generic widget will cause trace out‐\nput for that widget to be saved to a file.\n\ncompletetag (^Xt)\nThis widget completes symbol tags created by the etags or ctags programmes (note there\nis no connection with the completion system's tags) stored in a file TAGS, in the for‐\nmat used by etags, or tags, in the format created by ctags. It will look back up the\npath hierarchy for the first occurrence of either file; if both exist, the file TAGS\nis preferred. You can specify the full path to a TAGS or tags file by setting the pa‐\nrameter $TAGSFILE or $tagsfile respectively. The corresponding completion tags used\nare etags and vtags, after emacs and vi respectively.\n", "subsections": [] }, "UTILITY FUNCTIONS": { "content": "calendarlockfiles\nAttempt to lock the files given in the argument. To prevent problems with network\nfile locking this is done in an ad hoc fashion by attempting to create a symbolic link\nto the file with the name file.lockfile. No other system level functions are used for\nlocking, i.e. the file can be accessed and modified by any utility that does not use\nthis mechanism. In particular, the user is not prevented from editing the calendar\nfile at the same time unless calendaredit is used.\n\nThree attempts are made to lock the file before giving up. If the module zsh/zselect\nis available, the times of the attempts are jittered so that multiple instances of the\ncalling function are unlikely to retry at the same time.\n\nThe files locked are appended to the array lockfiles, which should be local to the\ncaller.\n\nIf all files were successfully locked, status zero is returned, else status one.\n\nThis function may be used as a general file locking function, although this will only\nwork if only this mechanism is used to lock files.\n\ncalendarread\nThis is a backend used by various other functions to parse the calendar file, which is\npassed as the only argument. The array calendarentries is set to the list of events\nin the file; no pruning is done except that ampersands are removed from the start of\nthe line. Each entry may contain multiple lines.\n\ncalendarscandate\nThis is a generic function to parse dates and times that may be used separately from\nthe calendar system. The argument is a date or time specification as described in the\nsection FILE AND DATE FORMATS above. The parameter REPLY is set to the number of sec‐\nonds since the epoch corresponding to that date or time. By default, the date and\ntime may occur anywhere within the given argument.\n\nReturns status zero if the date and time were successfully parsed, else one.\n\nOptions:\n-a The date and time are anchored to the start of the argument; they will not be\nmatched if there is preceding text.\n\n-A The date and time are anchored to both the start and end of the argument; they\nwill not be matched if the is any other text in the argument.\n\n-d Enable additional debugging output.\n\n-m Minus. When -R anchortime is also given the relative time is calculated back‐\nwards from anchortime.\n\n-r The argument passed is to be parsed as a relative time.\n\n-R anchortime\nThe argument passed is to be parsed as a relative time. The time is relative\nto anchortime, a time in seconds since the epoch, and the returned value is\nthe absolute time corresponding to advancing anchortime by the relative time\ngiven. This allows lengths of months to be correctly taken into account. If\nthe final day does not exist in the given month, the last day of the final\nmonth is given. For example, if the anchor time is during 31st January 2007\nand the relative time is 1 month, the final time is the same time of day during\n28th February 2007.\n\n-s In addition to setting REPLY, set REPLY2 to the remainder of the argument after\nthe date and time have been stripped. This is empty if the option -A was\ngiven.\n\n-t Allow a time with no date specification. The date is assumed to be today. The\nbehaviour is unspecified if the iron tongue of midnight is tolling twelve.\n\ncalendarshow\nThe function used by default to display events. It accepts a start time and end time\nfor events, both in epoch seconds, and an event description.\n\nThe event is always printed to standard output. If the command line editor is active\n(which will usually be the case) the command line will be redisplayed after the out‐\nput.\n\nIf the parameter DISPLAY is set and the start and end times are the same (indicating a\nscheduled event), the function uses the command xmessage to display a window with the\nevent details.\n", "subsections": [] }, "COMPLETION SYSTEM VARIABLES": { "content": "There are some standard variables, initialised by the maincomplete function and then used\nfrom other functions.\n\nThe standard variables are:\n\ncompcalleroptions\nThe completion system uses setopt to set a number of options. This allows functions to\nbe written without concern for compatibility with every possible combination of user\noptions. However, sometimes completion needs to know what the user's option prefer‐\nences are. These are saved in the compcalleroptions associative array. Option\nnames, spelled in lowercase without underscores, are mapped to one or other of the\nstrings `on' and `off'.\n\ncompprivprefix\nCompletion functions such as sudo can set the compprivprefix array to a\ncommand prefix that may then be used by callprogram to match the privileges\nwhen calling programs to generate matches.\n\nTwo more features are offered by the maincomplete function. The arrays compprefuncs\nand comppostfuncs may contain names of functions that are to be called immediately be‐\nfore or after completion has been tried. A function will only be called once unless\nit explicitly reinserts itself into the array.\n", "subsections": [] }, "COMPLETION DIRECTORIES": { "content": "In the source distribution, the files are contained in various subdirectories of the Comple‐‐\ntion directory. They may have been installed in the same structure, or into one single func‐\ntion directory. The following is a description of the files found in the original directory\nstructure. If you wish to alter an installed file, you will need to copy it to some direc‐\ntory which appears earlier in your fpath than the standard directory where it appears.\n\nBase The core functions and special completion widgets automatically bound to keys. You\nwill certainly need most of these, though will probably not need to alter them. Many\nof these are documented above.\n\nZsh Functions for completing arguments of shell builtin commands and utility functions for\nthis. Some of these are also used by functions from the Unix directory.\n\nUnix Functions for completing arguments of external commands and suites of commands. They\nmay need modifying for your system, although in many cases some attempt is made to de‐\ncide which version of a command is present. For example, completion for the mount\ncommand tries to determine the system it is running on, while completion for many\nother utilities try to decide whether the GNU version of the command is in use, and\nhence whether the --help option is supported.\n\nX, AIX, BSD, ...\nCompletion and utility function for commands available only on some systems. These\nare not arranged hierarchically, so, for example, both the Linux and Debian directo‐\nries, as well as the X directory, may be useful on your system.\n\n\n\nZSHCOMPCTL(1) General Commands Manual ZSHCOMPCTL(1)\n\n\n", "subsections": [] }, "COMMAND FLAGS": { "content": "Completion of the arguments of a command may be different for each command or may use the de‐\nfault. The behavior when completing the command word itself may also be separately speci‐\nfied. These correspond to the following flags and arguments, all of which (except for -L)\nmay be combined with any combination of the options described subsequently in the section\n`Option Flags':\n\ncommand ...\ncontrols completion for the named commands, which must be listed last on the command\nline. If completion is attempted for a command with a pathname containing slashes and\nno completion definition is found, the search is retried with the last pathname compo‐\nnent. If the command starts with a =, completion is tried with the pathname of the\ncommand.\n\nAny of the command strings may be patterns of the form normally used for filename gen‐\neration. These should be quoted to protect them from immediate expansion; for example\nthe command string 'foo*' arranges for completion of the words of any command begin‐\nning with foo. When completion is attempted, all pattern completions are tried in the\nreverse order of their definition until one matches. By default, completion then pro‐\nceeds as normal, i.e. the shell will try to generate more matches for the specific\ncommand on the command line; this can be overridden by including -tn in the flags for\nthe pattern completion.\n\nNote that aliases are expanded before the command name is determined unless the COM‐‐\nPLETEALIASES option is set. Commands may not be combined with the -C, -D or -T\nflags.\n", "subsections": [ { "name": "-C -C", "content": "command has been issued, the names of any executable command (whether in the path or\nspecific to the shell, such as aliases or functions) are completed.\n", "flag": "-C" }, { "name": "-D", "content": "special behavior. If no compctl -D command has been issued, filenames are completed.\n", "flag": "-D" }, { "name": "-T", "content": "processing for compctls defined for specific commands. This is especially useful when\ncombined with extended completion (the -x flag, see the section `Extended Completion'\nbelow). Using this flag you can define default behavior which will apply to all com‐\nmands without exception, or you can alter the standard behavior for all commands. For\nexample, if your access to the user database is too slow and/or it contains too many\nusers (so that completion after `~' is too slow to be usable), you can use\n\ncompctl -T -x 's[~] C[0,[^/]#]' -k friends -S/ -tn\n\nto complete the strings in the array friends after a `~'. The C[...] argument is nec‐\nessary so that this form of ~-completion is not tried after the directory name is fin‐\nished.\n", "flag": "-T" }, { "name": "-L", "content": "start-up script; the existing behavior is not changed. Any combination of the above\nforms, or the -M flag (which must follow the -L flag), may be specified, otherwise all\ndefined completions are listed. Any other flags supplied are ignored.\n\nno argument\nIf no argument is given, compctl lists all defined completions in an abbreviated form;\nwith a list of options, all completions with those flags set (not counting extended\ncompletion) are listed.\n\nIf the + flag is alone and followed immediately by the command list, the completion behavior\nfor all the commands in the list is reset to the default. In other words, completion will\nsubsequently use the options specified by the -D flag.\n\nThe form with -M as the first and only option defines global matching specifications (see\nzshcompwid). The match specifications given will be used for every completion attempt (only\nwhen using compctl, not with the new completion system) and are tried in the order in which\nthey are defined until one generates at least one match. E.g.:\n\ncompctl -M '' 'm:{a-zA-Z}={A-Za-z}'\n\nThis will first try completion without any global match specifications (the empty string)\nand, if that generates no matches, will try case insensitive completion.\n", "flag": "-L" } ] }, "OPTION FLAGS": { "content": "[ -fcFBdeaRGovNAIOPZEnbjrzu/12 ]\n[ -k array ] [ -g globstring ] [ -s subststring ]\n[ -K function ]\n[ -Q ] [ -P prefix ] [ -S suffix ]\n[ -W file-prefix ] [ -H num pattern ]\n[ -q ] [ -X explanation ] [ -Y explanation ]\n[ -y func-or-var ] [ -l cmd ] [ -h cmd ] [ -U ]\n[ -t continue ] [ -J name ] [ -V name ]\n[ -M match-spec ]\n\nThe remaining options specify the type of command arguments to look for during completion.\nAny combination of these flags may be specified; the result is a sorted list of all the pos‐\nsibilities. The options are as follows.\n", "subsections": [ { "name": "Simple Flags", "content": "These produce completion lists made up by the shell itself:\n" }, { "name": "-f", "content": "-/ Just file system paths.\n", "flag": "-f" }, { "name": "-c", "content": "", "flag": "-c" }, { "name": "-F", "content": "", "flag": "-F" }, { "name": "-B", "content": "", "flag": "-B" }, { "name": "-m", "content": "", "flag": "-m" }, { "name": "-w", "content": "", "flag": "-w" }, { "name": "-a", "content": "", "flag": "-a" }, { "name": "-R", "content": "", "flag": "-R" }, { "name": "-G", "content": "", "flag": "-G" }, { "name": "-d -F -B -w -a -R -G", "content": "tions, builtins, reserved words or aliases.\n", "flag": "-G" }, { "name": "-e", "content": "with -d; -de in combination with -F, -B, -w, -a, -R and -G will complete names of\nfunctions, builtins, reserved words or aliases whether or not they are disabled.\n", "flag": "-e" }, { "name": "-o", "content": "", "flag": "-o" }, { "name": "-v", "content": "", "flag": "-v" }, { "name": "-N", "content": "", "flag": "-N" }, { "name": "-A", "content": "", "flag": "-A" }, { "name": "-I", "content": "", "flag": "-I" }, { "name": "-O", "content": "", "flag": "-O" }, { "name": "-p", "content": "", "flag": "-p" }, { "name": "-Z", "content": "", "flag": "-Z" }, { "name": "-E", "content": "", "flag": "-E" }, { "name": "-n", "content": "", "flag": "-n" }, { "name": "-b", "content": "", "flag": "-b" }, { "name": "-j", "content": "kill builtin.\n", "flag": "-j" }, { "name": "-r", "content": "", "flag": "-r" }, { "name": "-z", "content": "", "flag": "-z" }, { "name": "-u", "content": "", "flag": "-u" }, { "name": "Flags with Arguments", "content": "These have user supplied arguments to determine how the list of completions is to be made up:\n" }, { "name": "-k", "content": "Names taken from the elements of $array (note that the `$' does not appear on the com‐\nmand line). Alternatively, the argument array itself may be a set of space- or\ncomma-separated values in parentheses, in which any delimiter may be escaped with a\nbackslash; in this case the argument should be quoted. For example,\n\ncompctl -k \"(cputime filesize datasize stacksize\ncoredumpsize resident descriptors)\" limit\n", "flag": "-k" }, { "name": "-g", "content": "The globstring is expanded using filename globbing; it should be quoted to protect it\nfrom immediate expansion. The resulting filenames are taken as the possible comple‐\ntions. Use `*(/)' instead of `*/' for directories. The fignore special parameter is\nnot applied to the resulting files. More than one pattern may be given separated by\nblanks. (Note that brace expansion is not part of globbing. Use the syntax `(ei‐‐\nther|or)' to match alternatives.)\n", "flag": "-g" }, { "name": "-s", "content": "The subststring is split into words and these words are than expanded using all shell\nexpansion mechanisms (see zshexpn(1)). The resulting words are taken as possible com‐\npletions. The fignore special parameter is not applied to the resulting files. Note\nthat -g is faster for filenames.\n", "flag": "-s" }, { "name": "-K", "content": "Call the given function to get the completions. Unless the name starts with an under‐\nscore, the function is passed two arguments: the prefix and the suffix of the word on\nwhich completion is to be attempted, in other words those characters before the cursor\nposition, and those from the cursor position onwards. The whole command line can be\naccessed with the -c and -l flags of the read builtin. The function should set the\nvariable reply to an array containing the completions (one completion per element);\nnote that reply should not be made local to the function. From such a function the\ncommand line can be accessed with the -c and -l flags to the read builtin. For exam‐\nple,\n\nfunction whoson { reply=(`users`); }\ncompctl -K whoson talk\n\ncompletes only logged-on users after `talk'. Note that `whoson' must return an array,\nso `reply=`users`' would be incorrect.\n", "flag": "-K" }, { "name": "-H", "content": "The possible completions are taken from the last num history lines. Only words match‐\ning pattern are taken. If num is zero or negative the whole history is searched and\nif pattern is the empty string all words are taken (as with `*'). A typical use is\n\ncompctl -D -f + -H 0 ''\n\nwhich forces completion to look back in the history list for a word if no filename\nmatches.\n", "flag": "-H" }, { "name": "Control Flags", "content": "These do not directly specify types of name to be completed, but manipulate the options that\ndo:\n" }, { "name": "-Q", "content": "Normally the results of a completion are inserted into the command line with any\nmetacharacters quoted so that they are interpreted as normal characters. This is ap‐\npropriate for filenames and ordinary strings. However, for special effects, such as\ninserting a backquoted expression from a completion array (-k) so that the expression\nwill not be evaluated until the complete line is executed, this option must be used.\n", "flag": "-Q" }, { "name": "-P", "content": "The prefix is inserted just before the completed string; any initial part already\ntyped will be completed and the whole prefix ignored for completion purposes. For ex‐\nample,\n\ncompctl -j -P \"%\" kill\n\ninserts a `%' after the kill command and then completes job names.\n", "flag": "-P" }, { "name": "-S", "content": "When a completion is found the suffix is inserted after the completed string. In the\ncase of menu completion the suffix is inserted immediately, but it is still possible\nto cycle through the list of completions by repeatedly hitting the same key.\n", "flag": "-S" }, { "name": "-W", "content": "With directory file-prefix: for command, file, directory and globbing completion (op‐\ntions -c, -f, -/, -g), the file prefix is implicitly added in front of the completion.\nFor example,\n\ncompctl -/ -W ~/Mail maildirs\n\ncompletes any subdirectories to any depth beneath the directory ~/Mail, although that\nprefix does not appear on the command line. The file-prefix may also be of the form\naccepted by the -k flag, i.e. the name of an array or a literal list in parenthesis.\nIn this case all the directories in the list will be searched for possible comple‐\ntions.\n", "flag": "-W" }, { "name": "-q -S", "content": "moved if the next character typed is a blank or does not insert anything or if the\nsuffix consists of only one character and the next character typed is the same charac‐\nter; this the same rule used for the AUTOREMOVESLASH option. The option is most\nuseful for list separators (comma, colon, etc.).\n", "flag": "-S" }, { "name": "-l", "content": "ments. If combined with one of the extended completion patterns `p[...]', `r[...]',\nor `R[...]' (see the section `Extended Completion' below) the range is restricted to\nthe range of arguments specified in the brackets. Completion is then performed as if\nthese had been given as arguments to the cmd supplied with the option. If the cmd\nstring is empty the first word in the range is instead taken as the command name, and\ncommand name completion performed on the first word in the range. For example,\n\ncompctl -x 'r[-exec,;]' -l '' -- find\n\ncompletes arguments between `-exec' and the following `;' (or the end of the command\nline if there is no such string) as if they were a separate command line.\n", "flag": "-l" }, { "name": "-h", "content": "done separately on different parts of such strings. It works like the -l option but\nmakes the completion code work on the parts of the current word that are separated by\nspaces. These parts are completed as if they were arguments to the given cmd. If cmd\nis the empty string, the first part is completed as a command name, as with -l.\n", "flag": "-h" }, { "name": "-U", "content": "word on the command line. The word typed so far will be deleted. This is most useful\nwith a function (given by the -K option) which can examine the word components passed\nto it (or via the read builtin's -c and -l flags) and use its own criteria to decide\nwhat matches. If there is no completion, the original word is retained. Since the\nproduced possible completions seldom have interesting common prefixes and suffixes,\nmenu completion is started immediately if AUTOMENU is set and this flag is used.\n", "flag": "-U" }, { "name": "-y", "content": "The list provided by func-or-var is displayed instead of the list of completions when‐\never a listing is required; the actual completions to be inserted are not affected.\nIt can be provided in two ways. Firstly, if func-or-var begins with a $ it defines a\nvariable, or if it begins with a left parenthesis a literal array, which contains the\nlist. A variable may have been set by a call to a function using the -K option. Oth‐\nerwise it contains the name of a function which will be executed to create the list.\nThe function will be passed as an argument list all matching completions, including\nprefixes and suffixes expanded in full, and should set the array reply to the result.\nIn both cases, the display list will only be retrieved after a complete list of\nmatches has been created.\n\nNote that the returned list does not have to correspond, even in length, to the origi‐\nnal set of matches, and may be passed as a scalar instead of an array. No special\nformatting of characters is performed on the output in this case; in particular, new‐\nlines are printed literally and if they appear output in columns is suppressed.\n", "flag": "-y" }, { "name": "-X", "content": "Print explanation when trying completion on the current set of options. A `%n' in this\nstring is replaced by the number of matches that were added for this explanation\nstring. The explanation only appears if completion was tried and there was no unique\nmatch, or when listing completions. Explanation strings will be listed together with\nthe matches of the group specified together with the -X option (using the -J or -V op‐\ntion). If the same explanation string is given to multiple -X options, the string ap‐\npears only once (for each group) and the number of matches shown for the `%n' is the\ntotal number of all matches for each of these uses. In any case, the explanation\nstring will only be shown if there was at least one match added for the explanation\nstring.\n\nThe sequences %B, %b, %S, %s, %U, and %u specify output attributes (bold, standout,\nand underline), %F, %f, %K, %k specify foreground and background colours, and %{...%}\ncan be used to include literal escape sequences as in prompts.\n", "flag": "-X" }, { "name": "-Y", "content": "Identical to -X, except that the explanation first undergoes expansion following the\nusual rules for strings in double quotes. The expansion will be carried out after any\nfunctions are called for the -K or -y options, allowing them to set variables.\n", "flag": "-Y" }, { "name": "-t", "content": "The continue-string contains a character that specifies which set of completion flags\nshould be used next. It is useful:\n\n(i) With -T, or when trying a list of pattern completions, when compctl would usually\ncontinue with ordinary processing after finding matches; this can be suppressed with\n`-tn'.\n\n(ii) With a list of alternatives separated by +, when compctl would normally stop when\none of the alternatives generates matches. It can be forced to consider the next set\nof completions by adding `-t+' to the flags of the alternative before the `+'.\n\n(iii) In an extended completion list (see below), when compctl would normally continue\nuntil a set of conditions succeeded, then use only the immediately following flags.\nWith `-t-', compctl will continue trying extended completions after the next `-'; with\n`-tx' it will attempt completion with the default flags, in other words those before\nthe `-x'.\n", "flag": "-t" }, { "name": "-J", "content": "This gives the name of the group the matches should be placed in. Groups are listed\nand sorted separately; likewise, menu completion will offer the matches in the groups\nin the order in which the groups were defined. If no group name is explicitly given,\nthe matches are stored in a group named default. The first time a group name is en‐\ncountered, a group with that name is created. After that all matches with the same\ngroup name are stored in that group.\n\nThis can be useful with non-exclusive alternative completions. For example, in\n\ncompctl -f -J files -t+ + -v -J variables foo\n\nboth files and variables are possible completions, as the -t+ forces both sets of al‐\nternatives before and after the + to be considered at once. Because of the -J op‐\ntions, however, all files are listed before all variables.\n", "flag": "-J" }, { "name": "-V", "content": "Like -J, but matches within the group will not be sorted in listings nor in menu com‐\npletion. These unsorted groups are in a different name space from the sorted ones, so\ngroups defined as -J files and -V files are distinct.\n", "flag": "-V" }, { "name": "-1 -V", "content": "be removed. Note that groups with and without this flag are in different name spaces.\n", "flag": "-V" }, { "name": "-2 -J -V", "content": "groups with and without this flag are in different name spaces.\n", "flag": "-V" }, { "name": "-M", "content": "This defines additional matching control specifications that should be used only when\ntesting words for the list of flags this flag appears in. The format of the match-spec\nstring is described in zshcompwid.\n", "flag": "-M" } ] }, "ALTERNATIVE COMPLETION": { "content": "compctl [ -CDT ] options + options [ + ... ] [ + ] command ...\n\nThe form with `+' specifies alternative options. Completion is tried with the options before\nthe first `+'. If this produces no matches completion is tried with the flags after the `+'\nand so on. If there are no flags after the last `+' and a match has not been found up to that\npoint, default completion is tried. If the list of flags contains a -t with a + character,\nthe next list of flags is used even if the current list produced matches.\n\nAdditional options are available that restrict completion to some part of the command line;\nthis is referred to as `extended completion'.\n", "subsections": [] }, "EXTENDED COMPLETION": { "content": "compctl [ -CDT ] options -x pattern options - ... --\n[ command ... ]\ncompctl [ -CDT ] options [ -x pattern options - ... -- ]\n[ + options [ -x ... -- ] ... [+] ] [ command ... ]\n\nThe form with `-x' specifies extended completion for the commands given; as shown, it may be\ncombined with alternative completion using `+'. Each pattern is examined in turn; when a\nmatch is found, the corresponding options, as described in the section `Option Flags' above,\nare used to generate possible completions. If no pattern matches, the options given before\nthe -x are used.\n\nNote that each pattern should be supplied as a single argument and should be quoted to pre‐\nvent expansion of metacharacters by the shell.\n\nA pattern is built of sub-patterns separated by commas; it matches if at least one of these\nsub-patterns matches (they are `or'ed). These sub-patterns are in turn composed of other\nsub-patterns separated by white spaces which match if all of the sub-patterns match (they are\n`and'ed). An element of the sub-patterns is of the form `c[...][...]', where the pairs of\nbrackets may be repeated as often as necessary, and matches if any of the sets of brackets\nmatch (an `or'). The example below makes this clearer.\n\nThe elements may be any of the following:\n\ns[string]...\nMatches if the current word on the command line starts with one of the strings given\nin brackets. The string is not removed and is not part of the completion.\n\nS[string]...\nLike s[string] except that the string is part of the completion.\n\np[from,to]...\nMatches if the number of the current word is between one of the from and to pairs in‐\nclusive. The comma and to are optional; to defaults to the same value as from. The\nnumbers may be negative: -n refers to the n'th last word on the line.\n\nc[offset,string]...\nMatches if the string matches the word offset by offset from the current word posi‐\ntion. Usually offset will be negative.\n\nC[offset,pattern]...\nLike c but using pattern matching instead.\n\nw[index,string]...\nMatches if the word in position index is equal to the corresponding string. Note that\nthe word count is made after any alias expansion.\n\nW[index,pattern]...\nLike w but using pattern matching instead.\n\nn[index,string]...\nMatches if the current word contains string. Anything up to and including the indexth\noccurrence of this string will not be considered part of the completion, but the rest\nwill. index may be negative to count from the end: in most cases, index will be 1 or\n-1. For example,\n\ncompctl -s '`users`' -x 'n[1,@]' -k hosts -- talk\n\nwill usually complete usernames, but if you insert an @ after the name, names from the\narray hosts (assumed to contain hostnames, though you must make the array yourself)\nwill be completed. Other commands such as rcp can be handled similarly.\n\nN[index,string]...\nLike n except that the string will be taken as a character class. Anything up to and\nincluding the indexth occurrence of any of the characters in string will not be con‐\nsidered part of the completion.\n\nm[min,max]...\nMatches if the total number of words lies between min and max inclusive.\n\nr[str1,str2]...\nMatches if the cursor is after a word with prefix str1. If there is also a word with\nprefix str2 on the command line after the one matched by str1 it matches only if the\ncursor is before this word. If the comma and str2 are omitted, it matches if the cur‐\nsor is after a word with prefix str1.\n\nR[str1,str2]...\nLike r but using pattern matching instead.\n\nq[str]...\nMatches the word currently being completed is in single quotes and the str begins with\nthe letter `s', or if completion is done in double quotes and str starts with the let‐\nter `d', or if completion is done in backticks and str starts with a `b'.\n", "subsections": [] }, "EXAMPLE": { "content": "compctl -u -x 's[+] c[-1,-f],s[-f+]' \\\n-g '~/Mail/*(:t)' - 's[-f],c[-1,-f]' -f -- mail\n\nThis is to be interpreted as follows:\n\nIf the current command is mail, then\n\nif ((the current word begins with + and the previous word is -f)\nor (the current word begins with -f+)), then complete the\nnon-directory part (the `:t' glob modifier) of files in the directory\n~/Mail; else\n\nif the current word begins with -f or the previous word was -f, then\ncomplete any file; else\n\ncomplete user names.\n\n\n\n\nZSHMODULES(1) General Commands Manual ZSHMODULES(1)\n\n\n", "subsections": [] }, "THE ZSH/ATTR MODULE": { "content": "The zsh/attr module is used for manipulating extended attributes. The -h option causes all\ncommands to operate on symbolic links instead of their targets. The builtins in this module\nare:\n\nzgetattr [ -h ] filename attribute [ parameter ]\nGet the extended attribute attribute from the specified filename. If the optional ar‐\ngument parameter is given, the attribute is set on that parameter instead of being\nprinted to stdout.\n\nzsetattr [ -h ] filename attribute value\nSet the extended attribute attribute on the specified filename to value.\n\nzdelattr [ -h ] filename attribute\nRemove the extended attribute attribute from the specified filename.\n\nzlistattr [ -h ] filename [ parameter ]\nList the extended attributes currently set on the specified filename. If the optional\nargument parameter is given, the list of attributes is set on that parameter instead\nof being printed to stdout.\n\nzgetattr and zlistattr allocate memory dynamically. If the attribute or list of attributes\ngrows between the allocation and the call to get them, they return 2. On all other errors, 1\nis returned. This allows the calling function to check for this case and retry.\n", "subsections": [] }, "THE ZSH/CAP MODULE": { "content": "The zsh/cap module is used for manipulating POSIX.1e (POSIX.6) capability sets. If the oper‐\nating system does not support this interface, the builtins defined by this module will do\nnothing. The builtins in this module are:\n\ncap [ capabilities ]\nChange the shell's process capability sets to the specified capabilities, otherwise\ndisplay the shell's current capabilities.\n\ngetcap filename ...\nThis is a built-in implementation of the POSIX standard utility. It displays the ca‐\npability sets on each specified filename.\n\nsetcap capabilities filename ...\nThis is a built-in implementation of the POSIX standard utility. It sets the capabil‐\nity sets on each specified filename to the specified capabilities.\n", "subsections": [] }, "THE ZSH/CLONE MODULE": { "content": "The zsh/clone module makes available one builtin command:\n\nclone tty\nCreates a forked instance of the current shell, attached to the specified tty. In the\nnew shell, the PID, PPID and TTY special parameters are changed appropriately. $! is\nset to zero in the new shell, and to the new shell's PID in the original shell.\n\nThe return status of the builtin is zero in both shells if successful, and non-zero on\nerror.\n\nThe target of clone should be an unused terminal, such as an unused virtual console or\na virtual terminal created by\n\nxterm -e sh -c 'trap : INT QUIT TSTP; tty;\nwhile :; do sleep 100000000; done'\n\nSome words of explanation are warranted about this long xterm command line: when doing\nclone on a pseudo-terminal, some other session (\"session\" meant as a unix session\ngroup, or SID) is already owning the terminal. Hence the cloned zsh cannot acquire the\npseudo-terminal as a controlling tty. That means two things:\n\n• the job control signals will go to the sh-started-by-xterm process group\n(that's why we disable INT QUIT and TSTP with trap; otherwise the while loop\ncould get suspended or killed)\n\n• the cloned shell will have job control disabled, and the job control keys (con‐\ntrol-C, control-\\ and control-Z) will not work.\n\nThis does not apply when cloning to an unused vc.\n\nCloning to a used (and unprepared) terminal will result in two processes reading si‐\nmultaneously from the same terminal, with input bytes going randomly to either\nprocess.\n\nclone is mostly useful as a shell built-in replacement for openvt.\n", "subsections": [] }, "THE ZSH/COMPCTL MODULE": { "content": "The zsh/compctl module makes available two builtin commands. compctl, is the old, deprecated\nway to control completions for ZLE. See zshcompctl(1). The other builtin command, compcall\ncan be used in user-defined completion widgets, see zshcompwid(1).\n", "subsections": [] }, "THE ZSH/COMPLETE MODULE": { "content": "The zsh/complete module makes available several builtin commands which can be used in\nuser-defined completion widgets, see zshcompwid(1).\n", "subsections": [] }, "THE ZSH/COMPLIST MODULE": { "content": "The zsh/complist module offers three extensions to completion listings: the ability to high‐\nlight matches in such a list, the ability to scroll through long lists and a different style\nof menu completion.\n", "subsections": [ { "name": "Colored completion listings", "content": "Whenever one of the parameters ZLSCOLORS or ZLSCOLOURS is set and the zsh/complist module\nis loaded or linked into the shell, completion lists will be colored. Note, however, that\ncomplist will not automatically be loaded if it is not linked in: on systems with dynamic\nloading, `zmodload zsh/complist' is required.\n\nThe parameters ZLSCOLORS and ZLSCOLOURS describe how matches are highlighted. To turn on\nhighlighting an empty value suffices, in which case all the default values given below will\nbe used. The format of the value of these parameters is the same as used by the GNU version\nof the ls command: a colon-separated list of specifications of the form `name=value'. The\nname may be one of the following strings, most of which specify file types for which the\nvalue will be used. The strings and their default values are:\n\nno 0 for normal text (i.e. when displaying something other than a matched file)\n\nfi 0 for regular files\n\ndi 32 for directories\n\nln 36 for symbolic links. If this has the special value target, symbolic links are derefer‐\nenced and the target file used to determine the display format.\n\npi 31 for named pipes (FIFOs)\n\nso 33 for sockets\n" }, { "name": "bd 44;37", "content": "for block devices\n" }, { "name": "cd 44;37", "content": "for character devices\n\nor none\nfor a symlink to nonexistent file (default is the value defined for ln)\n\nmi none\nfor a non-existent file (default is the value defined for fi); this code is currently\nnot used\n" }, { "name": "su 37;41", "content": "for files with setuid bit set\n" }, { "name": "sg 30;43", "content": "for files with setgid bit set\n" }, { "name": "tw 30;42", "content": "for world writable directories with sticky bit set\n" }, { "name": "ow 34;43", "content": "for world writable directories without sticky bit set\n\nsa none\nfor files with an associated suffix alias; this is only tested after specific suf‐\nfixes, as described below\n" }, { "name": "st 37;44", "content": "for directories with sticky bit set but not world writable\n\nex 35 for executable files\n\nlc \\e[ for the left code (see below)\n\nrc m for the right code\n\ntc 0 for the character indicating the file type printed after filenames if the LISTTYPES\noption is set\n\nsp 0 for the spaces printed after matches to align the next column\n\nec none\nfor the end code\n\nApart from these strings, the name may also be an asterisk (`*') followed by any string. The\nvalue given for such a string will be used for all files whose name ends with the string.\nThe name may also be an equals sign (`=') followed by a pattern; the EXTENDEDGLOB option\nwill be turned on for evaluation of the pattern. The value given for this pattern will be\nused for all matches (not just filenames) whose display string are matched by the pattern.\nDefinitions for the form with the leading equal sign take precedence over the values defined\nfor file types, which in turn take precedence over the form with the leading asterisk (file\nextensions).\n\nThe leading-equals form also allows different parts of the displayed strings to be colored\ndifferently. For this, the pattern has to use the `(#b)' globbing flag and pairs of paren‐\ntheses surrounding the parts of the strings that are to be colored differently. In this case\nthe value may consist of more than one color code separated by equal signs. The first code\nwill be used for all parts for which no explicit code is specified and the following codes\nwill be used for the parts matched by the sub-patterns in parentheses. For example, the\nspecification `=(#b)(?)*(?)=0=3=7' will be used for all matches which are at least two char‐\nacters long and will use the code `3' for the first character, `7' for the last character and\n`0' for the rest.\n\nAll three forms of name may be preceded by a pattern in parentheses. If this is given, the\nvalue will be used only for matches in groups whose names are matched by the pattern given in\nthe parentheses. For example, `(g*)m*=43' highlights all matches beginning with `m' in\ngroups whose names begin with `g' using the color code `43'. In case of the `lc', `rc', and\n`ec' codes, the group pattern is ignored.\n\nNote also that all patterns are tried in the order in which they appear in the parameter\nvalue until the first one matches which is then used. Patterns may be matched against com‐\npletions, descriptions (possibly with spaces appended for padding), or lines consisting of a\ncompletion followed by a description. For consistent coloring it may be necessary to use\nmore than one pattern or a pattern with backreferences.\n\nWhen printing a match, the code prints the value of lc, the value for the file-type or the\nlast matching specification with a `*', the value of rc, the string to display for the match\nitself, and then the value of ec if that is defined or the values of lc, no, and rc if ec is\nnot defined.\n\nThe default values are ISO 6429 (ANSI) compliant and can be used on vt100 compatible termi‐\nnals such as xterms. On monochrome terminals the default values will have no visible effect.\nThe colors function from the contribution can be used to get associative arrays containing\nthe codes for ANSI terminals (see the section `Other Functions' in zshcontrib(1)). For exam‐\nple, after loading colors, one could use `$color[red]' to get the code for foreground color\nred and `$color[bg-green]' for the code for background color green.\n\nIf the completion system invoked by compinit is used, these parameters should not be set di‐\nrectly because the system controls them itself. Instead, the list-colors style should be\nused (see the section `Completion System Configuration' in zshcompsys(1)).\n" }, { "name": "Scrolling in completion listings", "content": "To enable scrolling through a completion list, the LISTPROMPT parameter must be set. Its\nvalue will be used as the prompt; if it is the empty string, a default prompt will be used.\nThe value may contain escapes of the form `%x'. It supports the escapes `%B', `%b', `%S',\n`%s', `%U', `%u', `%F', `%f', `%K', `%k' and `%{...%}' used also in shell prompts as well as\nthree pairs of additional sequences: a `%l' or `%L' is replaced by the number of the last\nline shown and the total number of lines in the form `number/total'; a `%m' or `%M' is re‐\nplaced with the number of the last match shown and the total number of matches; and `%p' or\n`%P' is replaced with `Top', `Bottom' or the position of the first line shown in percent of\nthe total number of lines, respectively. In each of these cases the form with the uppercase\nletter will be replaced with a string of fixed width, padded to the right with spaces, while\nthe lowercase form will not be padded.\n\nIf the parameter LISTPROMPT is set, the completion code will not ask if the list should be\nshown. Instead it immediately starts displaying the list, stopping after the first screen‐\nful, showing the prompt at the bottom, waiting for a keypress after temporarily switching to\nthe listscroll keymap. Some of the zle functions have a special meaning while scrolling\nlists:\n" }, { "name": "send-break", "content": "stops listing discarding the key pressed\n\naccept-line, down-history, down-line-or-history\ndown-line-or-search, vi-down-line-or-history\nscrolls forward one line\n\ncomplete-word, menu-complete, expand-or-complete\nexpand-or-complete-prefix, menu-complete-or-expand\nscrolls forward one screenful\n" }, { "name": "accept-search", "content": "stop listing but take no other action\n\nEvery other character stops listing and immediately processes the key as usual. Any key that\nis not bound in the listscroll keymap or that is bound to undefined-key is looked up in the\nkeymap currently selected.\n\nAs for the ZLSCOLORS and ZLSCOLOURS parameters, LISTPROMPT should not be set directly when\nusing the shell function based completion system. Instead, the list-prompt style should be\nused.\n" }, { "name": "Menu selection", "content": "The zsh/complist module also offers an alternative style of selecting matches from a list,\ncalled menu selection, which can be used if the shell is set up to return to the last prompt\nafter showing a completion list (see the ALWAYSLASTPROMPT option in zshoptions(1)).\n\nMenu selection can be invoked directly by the widget menu-select defined by this module.\nThis is a standard ZLE widget that can be bound to a key in the usual way as described in\nzshzle(1).\n\nAlternatively, the parameter MENUSELECT can be set to an integer, which gives the minimum\nnumber of matches that must be present before menu selection is automatically turned on.\nThis second method requires that menu completion be started, either directly from a widget\nsuch as menu-complete, or due to one of the options MENUCOMPLETE or AUTOMENU being set. If\nMENUSELECT is set, but is 0, 1 or empty, menu selection will always be started during an am‐\nbiguous menu completion.\n\nWhen using the completion system based on shell functions, the MENUSELECT parameter should\nnot be used (like the ZLSCOLORS and ZLSCOLOURS parameters described above). Instead, the\nmenu style should be used with the select=... keyword.\n\nAfter menu selection is started, the matches will be listed. If there are more matches than\nfit on the screen, only the first screenful is shown. The matches to insert into the command\nline can be selected from this list. In the list one match is highlighted using the value\nfor ma from the ZLSCOLORS or ZLSCOLOURS parameter. The default value for this is `7' which\nforces the selected match to be highlighted using standout mode on a vt100-compatible termi‐\nnal. If neither ZLSCOLORS nor ZLSCOLOURS is set, the same terminal control sequence as for\nthe `%S' escape in prompts is used.\n\nIf there are more matches than fit on the screen and the parameter MENUPROMPT is set, its\nvalue will be shown below the matches. It supports the same escape sequences as LISTPROMPT,\nbut the number of the match or line shown will be that of the one where the mark is placed.\nIf its value is the empty string, a default prompt will be used.\n\nThe MENUSCROLL parameter can be used to specify how the list is scrolled. If the parameter\nis unset, this is done line by line, if it is set to `0' (zero), the list will scroll half\nthe number of lines of the screen. If the value is positive, it gives the number of lines to\nscroll and if it is negative, the list will be scrolled the number of lines of the screen mi‐\nnus the (absolute) value.\n\nAs for the ZLSCOLORS, ZLSCOLOURS and LISTPROMPT parameters, neither MENUPROMPT nor\nMENUSCROLL should be set directly when using the shell function based completion system. In‐\nstead, the select-prompt and select-scroll styles should be used.\n\nThe completion code sometimes decides not to show all of the matches in the list. These hid‐\nden matches are either matches for which the completion function which added them explicitly\nrequested that they not appear in the list (using the -n option of the compadd builtin com‐\nmand) or they are matches which duplicate a string already in the list (because they differ\nonly in things like prefixes or suffixes that are not displayed). In the list used for menu\nselection, however, even these matches are shown so that it is possible to select them. To\nhighlight such matches the hi and du capabilities in the ZLSCOLORS and ZLSCOLOURS parame‐\nters are supported for hidden matches of the first and second kind, respectively.\n\nSelecting matches is done by moving the mark around using the zle movement functions. When\nnot all matches can be shown on the screen at the same time, the list will scroll up and down\nwhen crossing the top or bottom line. The following zle functions have special meaning dur‐\ning menu selection. Note that the following always perform the same task within the menu se‐\nlection map and cannot be replaced by user defined widgets, nor can the set of functions be\nextended:\n\naccept-line, accept-search\naccept the current match and leave menu selection (but do not cause the command line\nto be accepted)\n" }, { "name": "send-break", "content": "leaves menu selection and restores the previous contents of the command line\n\nredisplay, clear-screen\nexecute their normal function without leaving menu selection\n\naccept-and-hold, accept-and-menu-complete\naccept the currently inserted match and continue selection allowing to select the next\nmatch to insert into the line\n" }, { "name": "accept-and-infer-next-history", "content": "accepts the current match and then tries completion with menu selection again; in the\ncase of files this allows one to select a directory and immediately attempt to com‐\nplete files in it; if there are no matches, a message is shown and one can use undo\nto go back to completion on the previous level, every other key leaves menu selection\n(including the other zle functions which are otherwise special during menu selection)\n\nundo removes matches inserted during the menu selection by one of the three functions be‐\nfore\n\ndown-history, down-line-or-history\nvi-down-line-or-history, down-line-or-search\nmoves the mark one line down\n\nup-history, up-line-or-history\nvi-up-line-or-history, up-line-or-search\nmoves the mark one line up\n\nforward-char, vi-forward-char\nmoves the mark one column right\n\nbackward-char, vi-backward-char\nmoves the mark one column left\n\nforward-word, vi-forward-word\nvi-forward-word-end, emacs-forward-word\nmoves the mark one screenful down\n\nbackward-word, vi-backward-word, emacs-backward-word\nmoves the mark one screenful up\n\nvi-forward-blank-word, vi-forward-blank-word-end\nmoves the mark to the first line of the next group of matches\n" }, { "name": "vi-backward-blank-word", "content": "moves the mark to the last line of the previous group of matches\n" }, { "name": "beginning-of-history", "content": "moves the mark to the first line\n" }, { "name": "end-of-history", "content": "moves the mark to the last line\n\nbeginning-of-buffer-or-history, beginning-of-line\nbeginning-of-line-hist, vi-beginning-of-line\nmoves the mark to the leftmost column\n\nend-of-buffer-or-history, end-of-line\nend-of-line-hist, vi-end-of-line\nmoves the mark to the rightmost column\n\ncomplete-word, menu-complete, expand-or-complete\nexpand-or-complete-prefix, menu-expand-or-complete\nmoves the mark to the next match\n" }, { "name": "reverse-menu-complete", "content": "moves the mark to the previous match\n" }, { "name": "vi-insert", "content": "this toggles between normal and interactive mode; in interactive mode the keys bound\nto self-insert and self-insert-unmeta insert into the command line as in normal edit‐\ning mode but without leaving menu selection; after each character completion is tried\nagain and the list changes to contain only the new matches; the completion widgets\nmake the longest unambiguous string be inserted in the command line and undo and back‐‐\nward-delete-char go back to the previous set of matches\n" }, { "name": "history-incremental-search-forward", "content": "" }, { "name": "history-incremental-search-backward", "content": "this starts incremental searches in the list of completions displayed; in this mode,\naccept-line only leaves incremental search, going back to the normal menu selection\nmode\n\nAll movement functions wrap around at the edges; any other zle function not listed leaves\nmenu selection and executes that function. It is possible to make widgets in the above list\ndo the same by using the form of the widget with a `.' in front. For example, the widget\n`.accept-line' has the effect of leaving menu selection and accepting the entire command\nline.\n\nDuring this selection the widget uses the keymap menuselect. Any key that is not defined in\nthis keymap or that is bound to undefined-key is looked up in the keymap currently selected.\nThis is used to ensure that the most important keys used during selection (namely the cursor\nkeys, return, and TAB) have sensible defaults. However, keys in the menuselect keymap can be\nmodified directly using the bindkey builtin command (see zshmodules(1)). For example, to make\nthe return key leave menu selection without accepting the match currently selected one could\ncall\n\nbindkey -M menuselect '^M' send-break\n\nafter loading the zsh/complist module.\n" } ] }, "THE ZSH/COMPUTIL MODULE": { "content": "The zsh/computil module adds several builtin commands that are used by some of the completion\nfunctions in the completion system based on shell functions (see zshcompsys(1) ). Except for\ncompquote these builtin commands are very specialised and thus not very interesting when\nwriting your own completion functions. In summary, these builtin commands are:\n", "subsections": [ { "name": "comparguments", "content": "This is used by the arguments function to do the argument and command line parsing.\nLike compdescribe it has an option -i to do the parsing and initialize some internal\nstate and various options to access the state information to decide what should be\ncompleted.\n" }, { "name": "compdescribe", "content": "This is used by the describe function to build the displays for the matches and to\nget the strings to add as matches with their options. On the first call one of the\noptions -i or -I should be supplied as the first argument. In the first case, display\nstrings without the descriptions will be generated, in the second case, the string\nused to separate the matches from their descriptions must be given as the second argu‐\nment and the descriptions (if any) will be shown. All other arguments are like the\ndefinition arguments to describe itself.\n\nOnce compdescribe has been called with either the -i or the -I option, it can be re‐\npeatedly called with the -g option and the names of four parameters as its arguments.\nThis will step through the different sets of matches and store the value of comp‐‐\nstate[list] in the first scalar, the options for compadd in the second array, the\nmatches in the third array, and the strings to be displayed in the completion listing\nin the fourth array. The arrays may then be directly given to compadd to register the\nmatches with the completion code.\n" }, { "name": "compfiles", "content": "Used by the pathfiles function to optimize complex recursive filename generation\n(globbing). It does three things. With the -p and -P options it builds the glob pat‐\nterns to use, including the paths already handled and trying to optimize the patterns\nwith respect to the prefix and suffix from the line and the match specification cur‐\nrently used. The -i option does the directory tests for the ignore-parents style and\nthe -r option tests if a component for some of the matches are equal to the string on\nthe line and removes all other matches if that is true.\n" }, { "name": "compgroups", "content": "Used by the tags function to implement the internals of the group-order style. This\nonly takes its arguments as names of completion groups and creates the groups for it\n(all six types: sorted and unsorted, both without removing duplicates, with removing\nall duplicates and with removing consecutive duplicates).\n\ncompquote [ -p ] names ...\nThere may be reasons to write completion functions that have to add the matches using\nthe -Q option to compadd and perform quoting themselves. Instead of interpreting the\nfirst character of the allquotes key of the compstate special association and using\nthe q flag for parameter expansions, one can use this builtin command. The arguments\nare the names of scalar or array parameters and the values of these parameters are\nquoted as needed for the innermost quoting level. If the -p option is given, quoting\nis done as if there is some prefix before the values of the parameters, so that a\nleading equal sign will not be quoted.\n\nThe return status is non-zero in case of an error and zero otherwise.\n" }, { "name": "comptags", "content": "" }, { "name": "comptry", "content": "These implement the internals of the tags mechanism.\n" }, { "name": "compvalues", "content": "Like comparguments, but for the values function.\n" } ] }, "THE ZSH/CURSES MODULE": { "content": "The zsh/curses module makes available one builtin command and various parameters.\n", "subsections": [ { "name": "Builtin", "content": "" }, { "name": "zcurses init", "content": "" }, { "name": "zcurses end", "content": "zcurses addwin targetwin nlines ncols beginy beginx [ parentwin ]\nzcurses delwin targetwin\nzcurses refresh [ targetwin ... ]\nzcurses touch targetwin ...\nzcurses move targetwin newy newx\nzcurses clear targetwin [ redraw | eol | bot ]\nzcurses position targetwin array\nzcurses char targetwin character\nzcurses string targetwin string\nzcurses border targetwin border\nzcurses attr targetwin [ [+|-]attribute | fgcol/bgcol ] [...]\nzcurses bg targetwin [ [+|-]attribute | fgcol/bgcol | @char ] [...]\nzcurses scroll targetwin [ on | off | [+|-]lines ]\nzcurses input targetwin [ param [ kparam [ mparam ] ] ]\nzcurses mouse [ delay num | [+|-]motion ]\nzcurses timeout targetwin intval\nzcurses querychar targetwin [ param ]\nzcurses resize height width [ endwin | nosave | endwinnosave ]\nManipulate curses windows. All uses of this command should be bracketed by `zcurses\ninit' to initialise use of curses, and `zcurses end' to end it; omitting `zcurses end'\ncan cause the terminal to be in an unwanted state.\n\nThe subcommand addwin creates a window with nlines lines and ncols columns. Its upper\nleft corner will be placed at row beginy and column beginx of the screen. targetwin\nis a string and refers to the name of a window that is not currently assigned. Note\nin particular the curses convention that vertical values appear before horizontal val‐\nues.\n\nIf addwin is given an existing window as the final argument, the new window is created\nas a subwindow of parentwin. This differs from an ordinary new window in that the\nmemory of the window contents is shared with the parent's memory. Subwindows must be\ndeleted before their parent. Note that the coordinates of subwindows are relative to\nthe screen, not the parent, as with other windows.\n\nUse the subcommand delwin to delete a window created with addwin. Note that end does\nnot implicitly delete windows, and that delwin does not erase the screen image of the\nwindow.\n\nThe window corresponding to the full visible screen is called stdscr; it always exists\nafter `zcurses init' and cannot be delete with delwin.\n\nThe subcommand refresh will refresh window targetwin; this is necessary to make any\npending changes (such as characters you have prepared for output with char) visible on\nthe screen. refresh without an argument causes the screen to be cleared and redrawn.\nIf multiple windows are given, the screen is updated once at the end.\n\nThe subcommand touch marks the targetwins listed as changed. This is necessary before\nrefreshing windows if a window that was in front of another window (which may be std‐‐\nscr) is deleted.\n\nThe subcommand move moves the cursor position in targetwin to new coordinates newy\nand newx. Note that the subcommand string (but not the subcommand char) advances the\ncursor position over the characters added.\n\nThe subcommand clear erases the contents of targetwin. One (and no more than one) of\nthree options may be specified. With the option redraw, in addition the next refresh\nof targetwin will cause the screen to be cleared and repainted. With the option eol,\ntargetwin is only cleared to the end of the current cursor line. With the option bot,\ntargetwin is cleared to the end of the window, i.e everything to the right and below\nthe cursor is cleared.\n\nThe subcommand position writes various positions associated with targetwin into the\narray named array. These are, in order:\n- The y and x coordinates of the cursor relative to the top left of targetwin\n- The y and x coordinates of the top left of targetwin on the screen\n- The size of targetwin in y and x dimensions.\n\nOutputting characters and strings are achieved by char and string respectively.\n\nTo draw a border around window targetwin, use border. Note that the border is not\nsubsequently handled specially: in other words, the border is simply a set of charac‐\nters output at the edge of the window. Hence it can be overwritten, can scroll off\nthe window, etc.\n\nThe subcommand attr will set targetwin's attributes or foreground/background color\npair for any successive character output. Each attribute given on the line may be\nprepended by a + to set or a - to unset that attribute; + is assumed if absent. The\nattributes supported are blink, bold, dim, reverse, standout, and underline.\n\nEach fgcol/bgcol attribute (to be read as `fgcol on bgcol') sets the foreground\nand background color for character output. The color default is sometimes available\n(in particular if the library is ncurses), specifying the foreground or background\ncolor with which the terminal started. The color pair default/default is always\navailable. To use more than the 8 named colors (red, green, etc.) construct the\nfgcol/bgcol pairs where fgcol and bgcol are decimal integers, e.g 128/200. The\nmaximum color value is 254 if the terminal supports 256 colors.\n\nbg overrides the color and other attributes of all characters in the window. Its\nusual use is to set the background initially, but it will overwrite the attributes of\nany characters at the time when it is called. In addition to the arguments allowed\nwith attr, an argument @char specifies a character to be shown in otherwise blank ar‐\neas of the window. Owing to limitations of curses this cannot be a multibyte charac‐\nter (use of ASCII characters only is recommended). As the specified set of attributes\noverride the existing background, turning attributes off in the arguments is not use‐\nful, though this does not cause an error.\n\nThe subcommand scroll can be used with on or off to enabled or disable scrolling of a\nwindow when the cursor would otherwise move below the window due to typing or output.\nIt can also be used with a positive or negative integer to scroll the window up or\ndown the given number of lines without changing the current cursor position (which\ntherefore appears to move in the opposite direction relative to the window). In the\nsecond case, if scrolling is off it is temporarily turned on to allow the window to be\nscrolled.\n\nThe subcommand input reads a single character from the window without echoing it back.\nIf param is supplied the character is assigned to the parameter param, else it is as‐\nsigned to the parameter REPLY.\n\nIf both param and kparam are supplied, the key is read in `keypad' mode. In this mode\nspecial keys such as function keys and arrow keys return the name of the key in the\nparameter kparam. The key names are the macros defined in the curses.h or ncurses.h\nwith the prefix `KEY' removed; see also the description of the parameter zcurseskey‐‐\ncodes below. Other keys cause a value to be set in param as before. On a successful\nreturn only one of param or kparam contains a non-empty string; the other is set to an\nempty string.\n\nIf mparam is also supplied, input attempts to handle mouse input. This is only avail‐\nable with the ncurses library; mouse handling can be detected by checking for the exit\nstatus of `zcurses mouse' with no arguments. If a mouse button is clicked (or double-\nor triple-clicked, or pressed or released with a configurable delay from being\nclicked) then kparam is set to the string MOUSE, and mparam is set to an array con‐\nsisting of the following elements:\n- An identifier to discriminate different input devices; this is only rarely use‐\nful.\n- The x, y and z coordinates of the mouse click relative to the full screen, as\nthree elements in that order (i.e. the y coordinate is, unusually, after the x\ncoordinate). The z coordinate is only available for a few unusual input de‐\nvices and is otherwise set to zero.\n- Any events that occurred as separate items; usually there will be just one. An\nevent consists of PRESSED, RELEASED, CLICKED, DOUBLECLICKED or TRIPLECLICKED\nfollowed immediately (in the same element) by the number of the button.\n- If the shift key was pressed, the string SHIFT.\n- If the control key was pressed, the string CTRL.\n- If the alt key was pressed, the string ALT.\n\nNot all mouse events may be passed through to the terminal window; most terminal emu‐\nlators handle some mouse events themselves. Note that the ncurses manual implies that\nusing input both with and without mouse handling may cause the mouse cursor to appear\nand disappear.\n\nThe subcommand mouse can be used to configure the use of the mouse. There is no win‐\ndow argument; mouse options are global. `zcurses mouse' with no arguments returns\nstatus 0 if mouse handling is possible, else status 1. Otherwise, the possible argu‐\nments (which may be combined on the same command line) are as follows. delay num sets\nthe maximum delay in milliseconds between press and release events to be considered as\na click; the value 0 disables click resolution, and the default is one sixth of a sec‐\nond. motion proceeded by an optional `+' (the default) or - turns on or off reporting\nof mouse motion in addition to clicks, presses and releases, which are always re‐\nported. However, it appears reports for mouse motion are not currently implemented.\n\nThe subcommand timeout specifies a timeout value for input from targetwin. If intval\nis negative, `zcurses input' waits indefinitely for a character to be typed; this is\nthe default. If intval is zero, `zcurses input' returns immediately; if there is ty‐\npeahead it is returned, else no input is done and status 1 is returned. If intval is\npositive, `zcurses input' waits intval milliseconds for input and if there is none at\nthe end of that period returns status 1.\n\nThe subcommand querychar queries the character at the current cursor position. The\nreturn values are stored in the array named param if supplied, else in the array re‐‐\nply. The first value is the character (which may be a multibyte character if the sys‐\ntem supports them); the second is the color pair in the usual fgcol/bgcol notation,\nor 0 if color is not supported. Any attributes other than color that apply to the\ncharacter, as set with the subcommand attr, appear as additional elements.\n\nThe subcommand resize resizes stdscr and all windows to given dimensions (windows that\nstick out from the new dimensions are resized down). The underlying curses extension\n(resizeterm call) can be unavailable. To verify, zeroes can be used for height and\nwidth. If the result of the subcommand is 0, resizeterm is available (2 otherwise).\nTests show that resizing can be normally accomplished by calling zcurses end and\nzcurses refresh. The resize subcommand is provided for versatility. Multiple system\nconfigurations have been checked and zcurses end and zcurses refresh are still needed\nfor correct terminal state after resize. To invoke them with resize, use endwin argu‐\nment. Using nosave argument will cause new terminal state to not be saved internally\nby zcurses. This is also provided for versatility and should normally be not needed.\n" }, { "name": "Parameters", "content": "ZCURSESCOLORS\nReadonly integer. The maximum number of colors the terminal supports. This value is\ninitialised by the curses library and is not available until the first time zcurses\ninit is run.\n\nZCURSESCOLORPAIRS\nReadonly integer. The maximum number of color pairs fgcol/bgcol that may be defined\nin `zcurses attr' commands; note this limit applies to all color pairs that have been\nused whether or not they are currently active. This value is initialised by the\ncurses library and is not available until the first time zcurses init is run.\n\nzcursesattrs\nReadonly array. The attributes supported by zsh/curses; available as soon as the mod‐\nule is loaded.\n\nzcursescolors\nReadonly array. The colors supported by zsh/curses; available as soon as the module\nis loaded.\n\nzcurseskeycodes\nReadonly array. The values that may be returned in the second parameter supplied to\n`zcurses input' in the order in which they are defined internally by curses. Not all\nfunction keys are listed, only F0; curses reserves space for F0 up to F63.\n\nzcurseswindows\nReadonly array. The current list of windows, i.e. all windows that have been created\nwith `zcurses addwin' and not removed with `zcurses delwin'.\n" } ] }, "THE ZSH/DATETIME MODULE": { "content": "The zsh/datetime module makes available one builtin command:\n\nstrftime [ -s scalar ] format [ epochtime [ nanoseconds ] ]\nstrftime -r [ -q ] [ -s scalar ] format timestring\nOutput the date in the format specified. With no epochtime, the current system\ndate/time is used; optionally, epochtime may be used to specify the number of seconds\nsince the epoch, and nanoseconds may additionally be used to specify the number of\nnanoseconds past the second (otherwise that number is assumed to be 0). See strf‐\ntime(3) for details. The zsh extensions described in the section EXPANSION OF PROMPT\nSEQUENCES in zshmisc(1) are also available.\n\n-q Run quietly; suppress printing of all error messages described below. Errors\nfor invalid epochtime values are always printed.\n\n-r With the option -r (reverse), use format to parse the input string timestring\nand output the number of seconds since the epoch at which the time occurred.\nThe parsing is implemented by the system function strptime; see strptime(3).\nThis means that zsh format extensions are not available, but for reverse lookup\nthey are not required.\n\nIn most implementations of strftime any timezone in the timestring is ignored\nand the local timezone declared by the TZ environment variable is used; other\nparameters are set to zero if not present.\n\nIf timestring does not match format the command returns status 1 and prints an\nerror message. If timestring matches format but not all characters in\ntimestring were used, the conversion succeeds but also prints an error message.\n\nIf either of the system functions strptime or mktime is not available, status 2\nis returned and an error message is printed.\n\n-s scalar\nAssign the date string (or epoch time in seconds if -r is given) to scalar in‐\nstead of printing it.\n\nNote that depending on the system's declared integral time type, strftime may produce\nincorrect results for epoch times greater than 2147483647 which corresponds to\n2038-01-19 03:14:07 +0000.\n\nThe zsh/datetime module makes available several parameters; all are readonly:\n\nEPOCHREALTIME\nA floating point value representing the number of seconds since the epoch. The no‐\ntional accuracy is to nanoseconds if the clockgettime call is available and to mi‐\ncroseconds otherwise, but in practice the range of double precision floating point and\nshell scheduling latencies may be significant effects.\n\nEPOCHSECONDS\nAn integer value representing the number of seconds since the epoch.\n", "subsections": [ { "name": "epochtime", "content": "An array value containing the number of seconds since the epoch in the first element\nand the remainder of the time since the epoch in nanoseconds in the second element.\nTo ensure the two elements are consistent the array should be copied or otherwise ref‐\nerenced as a single substitution before the values are used. The following idiom may\nbe used:\n\nfor secs nsecs in $epochtime; do\n...\ndone\n" } ] }, "THE ZSH/DB/GDBM MODULE": { "content": "The zsh/db/gdbm module is used to create \"tied\" associative arrays that interface to database\nfiles. If the GDBM interface is not available, the builtins defined by this module will re‐\nport an error. This module is also intended as a prototype for creating additional database\ninterfaces, so the ztie builtin may move to a more generic module in the future.\n\nThe builtins in this module are:\n\nztie -d db/gdbm -f filename [ -r ] arrayname\nOpen the GDBM database identified by filename and, if successful, create the associa‐\ntive array arrayname linked to the file. To create a local tied array, the parameter\nmust first be declared, so commands similar to the following would be executed inside\na function scope:\n\nlocal -A sampledb\nztie -d db/gdbm -f sample.gdbm sampledb\n\nThe -r option opens the database file for reading only, creating a parameter with the\nreadonly attribute. Without this option, using `ztie' on a file for which the user\ndoes not have write permission is an error. If writable, the database is opened syn‐\nchronously so fields changed in arrayname are immediately written to filename.\n\nChanges to the file modes filename after it has been opened do not alter the state of\narrayname, but `typeset -r arrayname' works as expected.\n\nzuntie [ -u ] arrayname ...\nClose the GDBM database associated with each arrayname and then unset the parameter.\nThe -u option forces an unset of parameters made readonly with `ztie -r'.\n\nThis happens automatically if the parameter is explicitly unset or its local scope\n(function) ends. Note that a readonly parameter may not be explicitly unset, so the\nonly way to unset a global parameter created with `ztie -r' is to use `zuntie -u'.\n\nzgdbmpath parametername\nPut path to database file assigned to parametername into REPLY scalar.\n\nzgdbmtied\nArray holding names of all tied parameters.\n\nThe fields of an associative array tied to GDBM are neither cached nor otherwise stored in\nmemory, they are read from or written to the database on each reference. Thus, for example,\nthe values in a readonly array may be changed by a second writer of the same database file.\n", "subsections": [] }, "THE ZSH/DELTOCHAR MODULE": { "content": "The zsh/deltochar module makes available two ZLE functions:\n", "subsections": [ { "name": "delete-to-char", "content": "Read a character from the keyboard, and delete from the cursor position up to and in‐\ncluding the next (or, with repeat count n, the nth) instance of that character. Nega‐\ntive repeat counts mean delete backwards.\n" }, { "name": "zap-to-char", "content": "This behaves like delete-to-char, except that the final occurrence of the character\nitself is not deleted.\n" } ] }, "THE ZSH/EXAMPLE MODULE": { "content": "The zsh/example module makes available one builtin command:\n\nexample [ -flags ] [ args ... ]\nDisplays the flags and arguments it is invoked with.\n\nThe purpose of the module is to serve as an example of how to write a module.\n", "subsections": [] }, "THE ZSH/FILES MODULE": { "content": "The zsh/files module makes available some common commands for file manipulation as builtins;\nthese commands are probably not needed for many normal situations but can be useful in emer‐\ngency recovery situations with constrained resources. The commands do not implement all fea‐\ntures now required by relevant standards committees.\n\nFor all commands, a variant beginning zf is also available and loaded automatically. Using\nthe features capability of zmodload will let you load only those names you want. Note that\nit's possible to load only the builtins with zsh-specific names using the following command:\n\nzmodload -m -F zsh/files b:zf\\*\n\nThe commands loaded by default are:\n\nchgrp [ -hRs ] group filename ...\nChanges group of files specified. This is equivalent to chown with a user-spec argu‐\nment of `:group'.\n\nchmod [ -Rs ] mode filename ...\nChanges mode of files specified.\n\nThe specified mode must be in octal.\n\nThe -R option causes chmod to recursively descend into directories, changing the mode\nof all files in the directory after changing the mode of the directory itself.\n\nThe -s option is a zsh extension to chmod functionality. It enables paranoid behav‐\niour, intended to avoid security problems involving a chmod being tricked into affect‐\ning files other than the ones intended. It will refuse to follow symbolic links, so\nthat (for example) ``chmod 600 /tmp/foo/passwd'' can't accidentally chmod /etc/passwd\nif /tmp/foo happens to be a link to /etc. It will also check where it is after leav‐\ning directories, so that a recursive chmod of a deep directory tree can't end up re‐\ncursively chmoding /usr as a result of directories being moved up the tree.\n\nchown [ -hRs ] user-spec filename ...\nChanges ownership and group of files specified.\n\nThe user-spec can be in four forms:\n\nuser change owner to user; do not change group\nuser:: change owner to user; do not change group\nuser: change owner to user; change group to user's primary group\nuser:group\nchange owner to user; change group to group\n:group do not change owner; change group to group\n\nIn each case, the `:' may instead be a `.'. The rule is that if there is a `:' then\nthe separator is `:', otherwise if there is a `.' then the separator is `.', otherwise\nthere is no separator.\n\nEach of user and group may be either a username (or group name, as appropriate) or a\ndecimal user ID (group ID). Interpretation as a name takes precedence, if there is an\nall-numeric username (or group name).\n\nIf the target is a symbolic link, the -h option causes chown to set the ownership of\nthe link instead of its target.\n\nThe -R option causes chown to recursively descend into directories, changing the own‐\nership of all files in the directory after changing the ownership of the directory it‐\nself.\n\nThe -s option is a zsh extension to chown functionality. It enables paranoid behav‐\niour, intended to avoid security problems involving a chown being tricked into affect‐\ning files other than the ones intended. It will refuse to follow symbolic links, so\nthat (for example) ``chown luser /tmp/foo/passwd'' can't accidentally chown\n/etc/passwd if /tmp/foo happens to be a link to /etc. It will also check where it is\nafter leaving directories, so that a recursive chown of a deep directory tree can't\nend up recursively chowning /usr as a result of directories being moved up the tree.\n\nln [ -dfhins ] filename dest\nln [ -dfhins ] filename ... dir\nCreates hard (or, with -s, symbolic) links. In the first form, the specified destina‐\ntion is created, as a link to the specified filename. In the second form, each of the\nfilenames is taken in turn, and linked to a pathname in the specified directory that\nhas the same last pathname component.\n\nNormally, ln will not attempt to create hard links to directories. This check can be\noverridden using the -d option. Typically only the super-user can actually succeed in\ncreating hard links to directories. This does not apply to symbolic links in any\ncase.\n\nBy default, existing files cannot be replaced by links. The -i option causes the user\nto be queried about replacing existing files. The -f option causes existing files to\nbe silently deleted, without querying. -f takes precedence.\n\nThe -h and -n options are identical and both exist for compatibility; either one indi‐\ncates that if the target is a symlink then it should not be dereferenced. Typically\nthis is used in combination with -sf so that if an existing link points to a directory\nthen it will be removed, instead of followed. If this option is used with multiple\nfilenames and the target is a symbolic link pointing to a directory then the result is\nan error.\n\nmkdir [ -p ] [ -m mode ] dir ...\nCreates directories. With the -p option, non-existing parent directories are first\ncreated if necessary, and there will be no complaint if the directory already exists.\nThe -m option can be used to specify (in octal) a set of file permissions for the cre‐\nated directories, otherwise mode 777 modified by the current umask (see umask(2)) is\nused.\n\nmv [ -fi ] filename dest\nmv [ -fi ] filename ... dir\nMoves files. In the first form, the specified filename is moved to the specified des‐\ntination. In the second form, each of the filenames is taken in turn, and moved to a\npathname in the specified directory that has the same last pathname component.\n\nBy default, the user will be queried before replacing any file that the user cannot\nwrite to, but writable files will be silently removed. The -i option causes the user\nto be queried about replacing any existing files. The -f option causes any existing\nfiles to be silently deleted, without querying. -f takes precedence.\n\nNote that this mv will not move files across devices. Historical versions of mv, when\nactual renaming is impossible, fall back on copying and removing files; if this behav‐\niour is desired, use cp and rm manually. This may change in a future version.\n\nrm [ -dfiRrs ] filename ...\nRemoves files and directories specified.\n\nNormally, rm will not remove directories (except with the -R or -r options). The -d\noption causes rm to try removing directories with unlink (see unlink(2)), the same\nmethod used for files. Typically only the super-user can actually succeed in unlink‐\ning directories in this way. -d takes precedence over -R and -r.\n\nBy default, the user will be queried before removing any file that the user cannot\nwrite to, but writable files will be silently removed. The -i option causes the user\nto be queried about removing any files. The -f option causes files to be silently\ndeleted, without querying, and suppresses all error indications. -f takes precedence.\n\nThe -R and -r options cause rm to recursively descend into directories, deleting all\nfiles in the directory before removing the directory with the rmdir system call (see\nrmdir(2)).\n\nThe -s option is a zsh extension to rm functionality. It enables paranoid behaviour,\nintended to avoid common security problems involving a root-run rm being tricked into\nremoving files other than the ones intended. It will refuse to follow symbolic links,\nso that (for example) ``rm /tmp/foo/passwd'' can't accidentally remove /etc/passwd if\n/tmp/foo happens to be a link to /etc. It will also check where it is after leaving\ndirectories, so that a recursive removal of a deep directory tree can't end up recur‐\nsively removing /usr as a result of directories being moved up the tree.\n\nrmdir dir ...\nRemoves empty directories specified.\n\nsync Calls the system call of the same name (see sync(2)), which flushes dirty buffers to\ndisk. It might return before the I/O has actually been completed.\n", "subsections": [] }, "THE ZSH/LANGINFO MODULE": { "content": "The zsh/langinfo module makes available one parameter:\n", "subsections": [ { "name": "langinfo", "content": "An associative array that maps langinfo elements to their values.\n\nYour implementation may support a number of the following keys:\n\nCODESET, DTFMT, DFMT, TFMT, RADIXCHAR, THOUSEP, YESEXPR, NOEXPR, CRNCYSTR, AB‐‐\nDAY{1..7}, DAY{1..7}, ABMON{1..12}, MON{1..12}, TFMTAMPM, AMSTR, PMSTR, ERA,\nERADFMT, ERADTFMT, ERATFMT, ALTDIGITS\n" } ] }, "THE ZSH/MAPFILE MODULE": { "content": "The zsh/mapfile module provides one special associative array parameter of the same name.\n", "subsections": [ { "name": "mapfile", "content": "This associative array takes as keys the names of files; the resulting value is the\ncontent of the file. The value is treated identically to any other text coming from a\nparameter. The value may also be assigned to, in which case the file in question is\nwritten (whether or not it originally existed); or an element may be unset, which will\ndelete the file in question. For example, `vared mapfile[myfile]' works as expected,\nediting the file `myfile'.\n\nWhen the array is accessed as a whole, the keys are the names of files in the current\ndirectory, and the values are empty (to save a huge overhead in memory). Thus\n${(k)mapfile} has the same effect as the glob operator *(D), since files beginning\nwith a dot are not special. Care must be taken with expressions such as rm ${(k)map‐‐\nfile}, which will delete every file in the current directory without the usual `rm *'\ntest.\n\nThe parameter mapfile may be made read-only; in that case, files referenced may not be\nwritten or deleted.\n\nA file may conveniently be read into an array as one line per element with the form\n`array=(\"${(f@)mapfile[filename]}\")'. The double quotes and the `@' are necessary to\nprevent empty lines from being removed. Note that if the file ends with a newline,\nthe shell will split on the final newline, generating an additional empty field; this\ncan be suppressed by using `array=(\"${(f@)${mapfile[filename]%$'\\n'}}\")'.\n" }, { "name": "Limitations", "content": "Although reading and writing of the file in question is efficiently handled, zsh's internal\nmemory management may be arbitrarily baroque; however, mapfile is usually very much more ef‐\nficient than anything involving a loop. Note in particular that the whole contents of the\nfile will always reside physically in memory when accessed (possibly multiple times, due to\nstandard parameter substitution operations). In particular, this means handling of suffi‐\nciently long files (greater than the machine's swap space, or than the range of the pointer\ntype) will be incorrect.\n\nNo errors are printed or flagged for non-existent, unreadable, or unwritable files, as the\nparameter mechanism is too low in the shell execution hierarchy to make this convenient.\n\nIt is unfortunate that the mechanism for loading modules does not yet allow the user to spec‐\nify the name of the shell parameter to be given the special behaviour.\n" } ] }, "THE ZSH/MATHFUNC MODULE": { "content": "The zsh/mathfunc module provides standard mathematical functions for use when evaluating\nmathematical formulae. The syntax agrees with normal C and FORTRAN conventions, for example,\n\n(( f = sin(0.3) ))\n\nassigns the sine of 0.3 to the parameter f.\n\nMost functions take floating point arguments and return a floating point value. However, any\nnecessary conversions from or to integer type will be performed automatically by the shell.\nApart from atan with a second argument and the abs, int and float functions, all functions\nbehave as noted in the manual page for the corresponding C function, except that any argu‐\nments out of range for the function in question will be detected by the shell and an error\nreported.\n\nThe following functions take a single floating point argument: acos, acosh, asin, asinh,\natan, atanh, cbrt, ceil, cos, cosh, erf, erfc, exp, expm1, fabs, floor, gamma, j0, j1,\nlgamma, log, log10, log1p, log2, logb, sin, sinh, sqrt, tan, tanh, y0, y1. The atan function\ncan optionally take a second argument, in which case it behaves like the C function atan2.\nThe ilogb function takes a single floating point argument, but returns an integer.\n\nThe function signgam takes no arguments, and returns an integer, which is the C variable of\nthe same name, as described in gamma(3). Note that it is therefore only useful immediately\nafter a call to gamma or lgamma. Note also that `signgam()' and `signgam' are distinct ex‐\npressions.\n\nThe functions min, max, and sum are defined not in this module but in the zmathfunc autoload‐\nable function, described in the section `Mathematical Functions' in zshcontrib(1).\n\nThe following functions take two floating point arguments: copysign, fmod, hypot, nextafter.\n\nThe following take an integer first argument and a floating point second argument: jn, yn.\n\nThe following take a floating point first argument and an integer second argument: ldexp,\nscalb.\n\nThe function abs does not convert the type of its single argument; it returns the absolute\nvalue of either a floating point number or an integer. The functions float and int convert\ntheir arguments into a floating point or integer value (by truncation) respectively.\n\nNote that the C pow function is available in ordinary math evaluation as the `' operator\nand is not provided here.\n\nThe function rand48 is available if your system's mathematical library has the function\nerand48(3). It returns a pseudo-random floating point number between 0 and 1. It takes a\nsingle string optional argument.\n\nIf the argument is not present, the random number seed is initialised by three calls to the\nrand(3) function --- this produces the same random numbers as the next three values of $RAN‐‐\nDOM.\n\nIf the argument is present, it gives the name of a scalar parameter where the current random\nnumber seed will be stored. On the first call, the value must contain at least twelve hexa‐\ndecimal digits (the remainder of the string is ignored), or the seed will be initialised in\nthe same manner as for a call to rand48 with no argument. Subsequent calls to rand48(param)\nwill then maintain the seed in the parameter param as a string of twelve hexadecimal digits,\nwith no base signifier. The random number sequences for different parameters are completely\nindependent, and are also independent from that used by calls to rand48 with no argument.\n\nFor example, consider\n\nprint $(( rand48(seed) ))\nprint $(( rand48() ))\nprint $(( rand48(seed) ))\n\nAssuming $seed does not exist, it will be initialised by the first call. In the second call,\nthe default seed is initialised; note, however, that because of the properties of rand()\nthere is a correlation between the seeds used for the two initialisations, so for more secure\nuses, you should generate your own 12-byte seed. The third call returns to the same sequence\nof random numbers used in the first call, unaffected by the intervening rand48().\n", "subsections": [] }, "THE ZSH/NEARCOLOR MODULE": { "content": "The zsh/nearcolor module replaces colours specified as hex triplets with the nearest colour\nin the 88 or 256 colour palettes that are widely used by terminal emulators. By default,\n24-bit true colour escape codes are generated when colours are specified using hex triplets.\nThese are not supported by all terminals. The purpose of this module is to make it easier to\ndefine colour preferences in a form that can work across a range of terminal emulators.\n\nAside from the default colour, the ANSI standard for terminal escape codes provides for eight\ncolours. The bright attribute brings this to sixteen. These basic colours are commonly used\nin terminal applications due to being widely supported. Expanded 88 and 256 colour palettes\nare also common and, while the first sixteen colours vary somewhat between terminals and con‐\nfigurations, these add a generally consistent and predictable set of colours.\n\nIn order to use the zsh/nearcolor module, it only needs to be loaded. Thereafter, whenever a\ncolour is specified using a hex triplet, it will be compared against each of the available\ncolours and the closest will be selected. The first sixteen colours are never matched in this\nprocess due to being unpredictable.\n\nIt isn't possible to reliably detect support for true colour in the terminal emulator. It is\ntherefore recommended to be selective in loading the zsh/nearcolor module. For example, the\nfollowing checks the COLORTERM environment variable:\n\n[[ $COLORTERM = *(24bit|truecolor)* ]] || zmodload zsh/nearcolor\n\nNote that some terminals accept the true color escape codes but map them internally to a more\nlimited palette in a similar manner to the zsh/nearcolor module.\n", "subsections": [] }, "THE ZSH/NEWUSER MODULE": { "content": "The zsh/newuser module is loaded at boot if it is available, the RCS option is set, and the\nPRIVILEGED option is not set (all three are true by default). This takes place immediately\nafter commands in the global zshenv file (typically /etc/zsh/zshenv), if any, have been exe‐\ncuted. If the module is not available it is silently ignored by the shell; the module may\nsafely be removed from $MODULEPATH by the administrator if it is not required.\n\nOn loading, the module tests if any of the start-up files .zshenv, .zprofile, .zshrc or .zlo‐‐\ngin exist in the directory given by the environment variable ZDOTDIR, or the user's home di‐\nrectory if that is not set. The test is not performed and the module halts processing if the\nshell was in an emulation mode (i.e. had been invoked as some other shell than zsh).\n\nIf none of the start-up files were found, the module then looks for the file newuser first in\na sitewide directory, usually the parent directory of the site-functions directory, and if\nthat is not found the module searches in a version-specific directory, usually the parent of\nthe functions directory containing version-specific functions. (These directories can be\nconfigured when zsh is built using the --enable-site-scriptdir=dir and --enable-scriptdir=dir\nflags to configure, respectively; the defaults are prefix/share/zsh and pre‐\nfix/share/zsh/$ZSHVERSION where the default prefix is /usr/local.)\n\nIf the file newuser is found, it is then sourced in the same manner as a start-up file. The\nfile is expected to contain code to install start-up files for the user, however any valid\nshell code will be executed.\n\nThe zsh/newuser module is then unconditionally unloaded.\n\nNote that it is possible to achieve exactly the same effect as the zsh/newuser module by\nadding code to /etc/zsh/zshenv. The module exists simply to allow the shell to make arrange‐\nments for new users without the need for intervention by package maintainers and system ad‐\nministrators.\n\nThe script supplied with the module invokes the shell function zsh-newuser-install. This may\nbe invoked directly by the user even if the zsh/newuser module is disabled. Note, however,\nthat if the module is not installed the function will not be installed either. The function\nis documented in the section User Configuration Functions in zshcontrib(1).\n", "subsections": [] }, "THE ZSH/PARAMETER MODULE": { "content": "The zsh/parameter module gives access to some of the internal hash tables used by the shell\nby defining some special parameters.\n", "subsections": [ { "name": "options", "content": "The keys for this associative array are the names of the options that can be set and\nunset using the setopt and unsetopt builtins. The value of each key is either the\nstring on if the option is currently set, or the string off if the option is unset.\nSetting a key to one of these strings is like setting or unsetting the option, respec‐\ntively. Unsetting a key in this array is like setting it to the value off.\n" }, { "name": "commands", "content": "This array gives access to the command hash table. The keys are the names of external\ncommands, the values are the pathnames of the files that would be executed when the\ncommand would be invoked. Setting a key in this array defines a new entry in this ta‐\nble in the same way as with the hash builtin. Unsetting a key as in `unset \"com‐‐\nmands[foo]\"' removes the entry for the given key from the command hash table.\n" }, { "name": "functions", "content": "This associative array maps names of enabled functions to their definitions. Setting a\nkey in it is like defining a function with the name given by the key and the body\ngiven by the value. Unsetting a key removes the definition for the function named by\nthe key.\n\ndisfunctions\nLike functions but for disabled functions.\n\nfunctionssource\nThis readonly associative array maps names of enabled functions to the name of the\nfile containing the source of the function.\n\nFor an autoloaded function that has already been loaded, or marked for autoload with\nan absolute path, or that has had its path resolved with `functions -r', this is the\nfile found for autoloading, resolved to an absolute path.\n\nFor a function defined within the body of a script or sourced file, this is the name\nof that file. In this case, this is the exact path originally used to that file,\nwhich may be a relative path.\n\nFor any other function, including any defined at an interactive prompt or an autoload\nfunction whose path has not yet been resolved, this is the empty string. However, the\nhash element is reported as defined just so long as the function is present: the keys\nto this hash are the same as those to $functions.\n\ndisfunctionssource\nLike functionssource but for disabled functions.\n" }, { "name": "builtins", "content": "This associative array gives information about the builtin commands currently enabled.\nThe keys are the names of the builtin commands and the values are either `undefined'\nfor builtin commands that will automatically be loaded from a module if invoked or\n`defined' for builtin commands that are already loaded.\n\ndisbuiltins\nLike builtins but for disabled builtin commands.\n" }, { "name": "reswords", "content": "This array contains the enabled reserved words.\n\ndisreswords\nLike reswords but for disabled reserved words.\n" }, { "name": "patchars", "content": "This array contains the enabled pattern characters.\n\ndispatchars\nLike patchars but for disabled pattern characters.\n" }, { "name": "aliases", "content": "This maps the names of the regular aliases currently enabled to their expansions.\n\ndisaliases\nLike aliases but for disabled regular aliases.\n" }, { "name": "galiases", "content": "Like aliases, but for global aliases.\n\ndisgaliases\nLike galiases but for disabled global aliases.\n" }, { "name": "saliases", "content": "Like raliases, but for suffix aliases.\n\ndissaliases\nLike saliases but for disabled suffix aliases.\n" }, { "name": "parameters", "content": "The keys in this associative array are the names of the parameters currently defined.\nThe values are strings describing the type of the parameter, in the same format used\nby the t parameter flag, see zshexpn(1) . Setting or unsetting keys in this array is\nnot possible.\n" }, { "name": "modules", "content": "An associative array giving information about modules. The keys are the names of the\nmodules loaded, registered to be autoloaded, or aliased. The value says which state\nthe named module is in and is one of the strings `loaded', `autoloaded', or\n`alias:name', where name is the name the module is aliased to.\n\nSetting or unsetting keys in this array is not possible.\n" }, { "name": "dirstack", "content": "A normal array holding the elements of the directory stack. Note that the output of\nthe dirs builtin command includes one more directory, the current working directory.\n" }, { "name": "history", "content": "This associative array maps history event numbers to the full history lines. Although\nit is presented as an associative array, the array of all values (${history[@]}) is\nguaranteed to be returned in order from most recent to oldest history event, that is,\nby decreasing history event number.\n" }, { "name": "historywords", "content": "A special array containing the words stored in the history. These also appear in most\nto least recent order.\n" }, { "name": "jobdirs", "content": "This associative array maps job numbers to the directories from which the job was\nstarted (which may not be the current directory of the job).\n\nThe keys of the associative arrays are usually valid job numbers, and these are the\nvalues output with, for example, ${(k)jobdirs}. Non-numeric job references may be\nused when looking up a value; for example, ${jobdirs[%+]} refers to the current job.\n" }, { "name": "jobtexts", "content": "This associative array maps job numbers to the texts of the command lines that were\nused to start the jobs.\n\nHandling of the keys of the associative array is as described for jobdirs above.\n" }, { "name": "jobstates", "content": "This associative array gives information about the states of the jobs currently known.\nThe keys are the job numbers and the values are strings of the form\n`job-state:mark:pid=state...'. The job-state gives the state the whole job is cur‐\nrently in, one of `running', `suspended', or `done'. The mark is `+' for the current\njob, `-' for the previous job and empty otherwise. This is followed by one\n`:pid=state' for every process in the job. The pids are, of course, the process IDs\nand the state describes the state of that process.\n\nHandling of the keys of the associative array is as described for jobdirs above.\n" }, { "name": "nameddirs", "content": "This associative array maps the names of named directories to the pathnames they stand\nfor.\n" }, { "name": "userdirs", "content": "This associative array maps user names to the pathnames of their home directories.\n" }, { "name": "usergroups", "content": "This associative array maps names of system groups of which the current user is a mem‐\nber to the corresponding group identifiers. The contents are the same as the groups\noutput by the id command.\n" }, { "name": "funcfiletrace", "content": "This array contains the absolute line numbers and corresponding file names for the\npoint where the current function, sourced file, or (if EVALLINENO is set) eval com‐\nmand was called. The array is of the same length as funcsourcetrace and functrace,\nbut differs from funcsourcetrace in that the line and file are the point of call, not\nthe point of definition, and differs from functrace in that all values are absolute\nline numbers in files, rather than relative to the start of a function, if any.\n" }, { "name": "funcsourcetrace", "content": "This array contains the file names and line numbers of the points where the functions,\nsourced files, and (if EVALLINENO is set) eval commands currently being executed were\ndefined. The line number is the line where the `function name' or `name ()' started.\nIn the case of an autoloaded function the line number is reported as zero. The for‐\nmat of each element is filename:lineno.\n\nFor functions autoloaded from a file in native zsh format, where only the body of the\nfunction occurs in the file, or for files that have been executed by the source or `.'\nbuiltins, the trace information is shown as filename:0, since the entire file is the\ndefinition. The source file name is resolved to an absolute path when the function is\nloaded or the path to it otherwise resolved.\n\nMost users will be interested in the information in the funcfiletrace array instead.\n" }, { "name": "funcstack", "content": "This array contains the names of the functions, sourced files, and (if EVALLINENO is\nset) eval commands. currently being executed. The first element is the name of the\nfunction using the parameter.\n\nThe standard shell array zshevalcontext can be used to determine the type of shell\nconstruct being executed at each depth: note, however, that is in the opposite order,\nwith the most recent item last, and it is more detailed, for example including an en‐\ntry for toplevel, the main shell code being executed either interactively or from a\nscript, which is not present in $funcstack.\n" }, { "name": "functrace", "content": "This array contains the names and line numbers of the callers corresponding to the\nfunctions currently being executed. The format of each element is name:lineno. Call‐\ners are also shown for sourced files; the caller is the point where the source or `.'\ncommand was executed.\n" } ] }, "THE ZSH/PCRE MODULE": { "content": "The zsh/pcre module makes some commands available as builtins:\n\npcrecompile [ -aimxs ] PCRE\nCompiles a perl-compatible regular expression.\n\nOption -a will force the pattern to be anchored. Option -i will compile a case-insen‐\nsitive pattern. Option -m will compile a multi-line pattern; that is, ^ and $ will\nmatch newlines within the pattern. Option -x will compile an extended pattern,\nwherein whitespace and # comments are ignored. Option -s makes the dot metacharacter\nmatch all characters, including those that indicate newline.\n\npcrestudy\nStudies the previously-compiled PCRE which may result in faster matching.\n\npcrematch [ -v var ] [ -a arr ] [ -n offset ] [ -b ] string\nReturns successfully if string matches the previously-compiled PCRE.\n\nUpon successful match, if the expression captures substrings within parentheses,\npcrematch will set the array match to those substrings, unless the -a option is\ngiven, in which case it will set the array arr. Similarly, the variable MATCH will be\nset to the entire matched portion of the string, unless the -v option is given, in\nwhich case the variable var will be set. No variables are altered if there is no suc‐\ncessful match. A -n option starts searching for a match from the byte offset position\nin string. If the -b option is given, the variable ZPCREOP will be set to an offset\npair string, representing the byte offset positions of the entire matched portion\nwithin the string. For example, a ZPCREOP set to \"32 45\" indicates that the matched\nportion began on byte offset 32 and ended on byte offset 44. Here, byte offset posi‐\ntion 45 is the position directly after the matched portion. Keep in mind that the\nbyte position isn't necessarily the same as the character position when UTF-8 charac‐\nters are involved. Consequently, the byte offset positions are only to be relied on\nin the context of using them for subsequent searches on string, using an offset posi‐\ntion as an argument to the -n option. This is mostly used to implement the \"find all\nnon-overlapping matches\" functionality.\n\nA simple example of \"find all non-overlapping matches\":\n\nstring=\"The following zip codes: 78884 90210 99513\"\npcrecompile -m \"\\d{5}\"\naccum=()\npcrematch -b -- $string\nwhile [[ $? -eq 0 ]] do\nb=($=ZPCREOP)\naccum+=$MATCH\npcrematch -b -n $b[2] -- $string\ndone\nprint -l $accum\n\nThe zsh/pcre module makes available the following test condition:\n\nexpr -pcre-match pcre\nMatches a string against a perl-compatible regular expression.\n\nFor example,\n\n[[ \"$text\" -pcre-match ^d+$ ]] &&\nprint text variable contains only \"d's\".\n\nIf the REMATCHPCRE option is set, the =~ operator is equivalent to -pcre-match, and\nthe NOCASEMATCH option may be used. Note that NOCASEMATCH never applies to the\npcrematch builtin, instead use the -i switch of pcrecompile.\n", "subsections": [] }, "THE ZSH/PARAM/PRIVATE MODULE": { "content": "The zsh/param/private module is used to create parameters whose scope is limited to the cur‐\nrent function body, and not to other functions called by the current function.\n\nThis module provides a single autoloaded builtin:\n\nprivate [ {+|-}AHUahlprtux ] [ {+|-}EFLRZi [ n ] ] [ name[=value] ... ]\nThe private builtin accepts all the same options and arguments as local (zsh‐\nbuiltins(1)) except for the `-T' option. Tied parameters may not be made private.\n\nIf used at the top level (outside a function scope), private creates a normal parame‐\nter in the same manner as declare or typeset. A warning about this is printed if\nWARNCREATEGLOBAL is set (zshoptions(1)). Used inside a function scope, private cre‐\nates a local parameter similar to one declared with local, except having special prop‐\nerties noted below.\n\nSpecial parameters which expose or manipulate internal shell state, such as ARGC,\nargv, COLUMNS, LINES, UID, EUID, IFS, PROMPT, RANDOM, SECONDS, etc., cannot be made\nprivate unless the `-h' option is used to hide the special meaning of the parameter.\nThis may change in the future.\n\nAs with other typeset equivalents, private is both a builtin and a reserved word, so arrays\nmay be assigned with parenthesized word list name=(value...) syntax. However, the reserved\nword `private' is not available until zsh/param/private is loaded, so care must be taken with\norder of execution and parsing for function definitions which use private. To compensate for\nthis, the module also adds the option `-P' to the `local' builtin to declare private parame‐\nters.\n\nFor example, this construction fails if zsh/param/private has not yet been loaded when\n`baddeclaration' is defined:\nbaddeclaration() {\nzmodload zsh/param/private\nprivate array=( one two three )\n}\n\nThis construction works because local is already a keyword, and the module is loaded before\nthe statement is executed:\ngooddeclaration() {\nzmodload zsh/param/private\nlocal -P array=( one two three )\n}\n\nThe following is usable in scripts but may have trouble with autoload:\nzmodload zsh/param/private\niffydeclaration() {\nprivate array=( one two three )\n}\n\nThe private builtin may always be used with scalar assignments and for declarations without\nassignments.\n\nParameters declared with private have the following properties:\n\n• Within the function body where it is declared, the parameter behaves as a local, ex‐\ncept as noted above for tied or special parameters.\n\n• The type of a parameter declared private cannot be changed in the scope where it was\ndeclared, even if the parameter is unset. Thus an array cannot be assigned to a pri‐\nvate scalar, etc.\n\n• Within any other function called by the declaring function, the private parameter does\nNOT hide other parameters of the same name, so for example a global parameter of the\nsame name is visible and may be assigned or unset. This includes calls to anonymous\nfunctions, although that may also change in the future.\n\n• An exported private remains in the environment of inner scopes but appears unset for\nthe current shell in those scopes. Generally, exporting private parameters should be\navoided.\n\nNote that this differs from the static scope defined by compiled languages derived from C, in\nthat the a new call to the same function creates a new scope, i.e., the parameter is still\nassociated with the call stack rather than with the function definition. It differs from ksh\n`typeset -S' because the syntax used to define the function has no bearing on whether the pa‐\nrameter scope is respected.\n", "subsections": [] }, "THE ZSH/REGEX MODULE": { "content": "The zsh/regex module makes available the following test condition:\n\nexpr -regex-match regex\nMatches a string against a POSIX extended regular expression. On successful match,\nmatched portion of the string will normally be placed in the MATCH variable. If there\nare any capturing parentheses within the regex, then the match array variable will\ncontain those. If the match is not successful, then the variables will not be al‐\ntered.\n\nFor example,\n\n[[ alphabetical -regex-match ^a([^a]+)a([^a]+)a ]] &&\nprint -l $MATCH X $match\n\nIf the option REMATCHPCRE is not set, then the =~ operator will automatically load\nthis module as needed and will invoke the -regex-match operator.\n\nIf BASHREMATCH is set, then the array BASHREMATCH will be set instead of MATCH and\nmatch.\n", "subsections": [] }, "THE ZSH/SCHED MODULE": { "content": "The zsh/sched module makes available one builtin command and one parameter.\n\nsched [-o] [+]hh:mm[:ss] command ...\nsched [-o] [+]seconds command ...\nsched [ -item ]\nMake an entry in the scheduled list of commands to execute. The time may be specified\nin either absolute or relative time, and either as hours, minutes and (optionally)\nseconds separated by a colon, or seconds alone. An absolute number of seconds indi‐\ncates the time since the epoch (1970/01/01 00:00); this is useful in combination with\nthe features in the zsh/datetime module, see the zsh/datetime module entry in zshmod‐\nules(1).\n\nWith no arguments, prints the list of scheduled commands. If the scheduled command\nhas the -o flag set, this is shown at the start of the command.\n\nWith the argument `-item', removes the given item from the list. The numbering of the\nlist is continuous and entries are in time order, so the numbering can change when en‐\ntries are added or deleted.\n\nCommands are executed either immediately before a prompt, or while the shell's line\neditor is waiting for input. In the latter case it is useful to be able to produce\noutput that does not interfere with the line being edited. Providing the option -o\ncauses the shell to clear the command line before the event and redraw it afterwards.\nThis should be used with any scheduled event that produces visible output to the ter‐\nminal; it is not needed, for example, with output that updates a terminal emulator's\ntitle bar.\n\nTo effect changes to the editor buffer when an event executes, use the `zle' command\nwith no arguments to test whether the editor is active, and if it is, then use `zle\nwidget' to access the editor via the named widget.\n\nThe sched builtin is not made available by default when the shell starts in a mode em‐\nulating another shell. It can be made available with the command `zmodload -F\nzsh/sched b:sched'.\n\nzshscheduledevents\nA readonly array corresponding to the events scheduled by the sched builtin. The in‐\ndices of the array correspond to the numbers shown when sched is run with no arguments\n(provided that the KSHARRAYS option is not set). The value of the array consists of\nthe scheduled time in seconds since the epoch (see the section `The zsh/datetime Mod‐\nule' for facilities for using this number), followed by a colon, followed by any op‐\ntions (which may be empty but will be preceded by a `-' otherwise), followed by a\ncolon, followed by the command to be executed.\n\nThe sched builtin should be used for manipulating the events. Note that this will\nhave an immediate effect on the contents of the array, so that indices may become in‐\nvalid.\n", "subsections": [] }, "THE ZSH/NET/SOCKET MODULE": { "content": "The zsh/net/socket module makes available one builtin command:\n\nzsocket [ -altv ] [ -d fd ] [ args ]\nzsocket is implemented as a builtin to allow full use of shell command line editing,\nfile I/O, and job control mechanisms.\n", "subsections": [ { "name": "Outbound Connections", "content": "zsocket [ -v ] [ -d fd ] filename\nOpen a new Unix domain connection to filename. The shell parameter REPLY will be set\nto the file descriptor associated with that connection. Currently, only stream con‐\nnections are supported.\n\nIf -d is specified, its argument will be taken as the target file descriptor for the\nconnection.\n\nIn order to elicit more verbose output, use -v.\n\nFile descriptors can be closed with normal shell syntax when no longer needed, for ex‐\nample:\n\nexec {REPLY}>&-\n" }, { "name": "Inbound Connections", "content": "zsocket -l [ -v ] [ -d fd ] filename\nzsocket -l will open a socket listening on filename. The shell parameter REPLY will\nbe set to the file descriptor associated with that listener. The file descriptor re‐\nmains open in subshells and forked external executables.\n\nIf -d is specified, its argument will be taken as the target file descriptor for the\nconnection.\n\nIn order to elicit more verbose output, use -v.\n\nzsocket -a [ -tv ] [ -d targetfd ] listenfd\nzsocket -a will accept an incoming connection to the socket associated with listenfd.\nThe shell parameter REPLY will be set to the file descriptor associated with the in‐\nbound connection. The file descriptor remains open in subshells and forked external\nexecutables.\n\nIf -d is specified, its argument will be taken as the target file descriptor for the\nconnection.\n\nIf -t is specified, zsocket will return if no incoming connection is pending. Other‐\nwise it will wait for one.\n\nIn order to elicit more verbose output, use -v.\n" } ] }, "THE ZSH/STAT MODULE": { "content": "The zsh/stat module makes available one builtin command under two possible names:\n\nzstat [ -gnNolLtTrs ] [ -f fd ] [ -H hash ] [ -A array ] [ -F fmt ]\n[ +element ] [ file ... ]\nstat ...\nThe command acts as a front end to the stat system call (see stat(2)). The same com‐\nmand is provided with two names; as the name stat is often used by an external command\nit is recommended that only the zstat form of the command is used. This can be ar‐\nranged by loading the module with the command `zmodload -F zsh/stat b:zstat'.\n\nIf the stat call fails, the appropriate system error message printed and status 1 is\nreturned. The fields of struct stat give information about the files provided as ar‐\nguments to the command. In addition to those available from the stat call, an extra\nelement `link' is provided. These elements are:\n\ndevice The number of the device on which the file resides.\n\ninode The unique number of the file on this device (`inode' number).\n\nmode The mode of the file; that is, the file's type and access permissions. With\nthe -s option, this will be returned as a string corresponding to the first\ncolumn in the display of the ls -l command.\n\nnlink The number of hard links to the file.\n\nuid The user ID of the owner of the file. With the -s option, this is displayed as\na user name.\n\ngid The group ID of the file. With the -s option, this is displayed as a group\nname.\n\nrdev The raw device number. This is only useful for special devices.\n\nsize The size of the file in bytes.\n\natime\nmtime\nctime The last access, modification and inode change times of the file, respectively,\nas the number of seconds since midnight GMT on 1st January, 1970. With the -s\noption, these are printed as strings for the local time zone; the format can be\naltered with the -F option, and with the -g option the times are in GMT.\n\nblksize\nThe number of bytes in one allocation block on the device on which the file re‐\nsides.\n\nblock The number of disk blocks used by the file.\n\nlink If the file is a link and the -L option is in effect, this contains the name of\nthe file linked to, otherwise it is empty. Note that if this element is se‐\nlected (``zstat +link'') then the -L option is automatically used.\n\nA particular element may be selected by including its name preceded by a `+' in the\noption list; only one element is allowed. The element may be shortened to any unique\nset of leading characters. Otherwise, all elements will be shown for all files.\n\nOptions:\n\n-A array\nInstead of displaying the results on standard output, assign them to an array,\none struct stat element per array element for each file in order. In this case\nneither the name of the element nor the name of the files appears in array un‐\nless the -t or -n options were given, respectively. If -t is given, the ele‐\nment name appears as a prefix to the appropriate array element; if -n is given,\nthe file name appears as a separate array element preceding all the others.\nOther formatting options are respected.\n\n-H hash\nSimilar to -A, but instead assign the values to hash. The keys are the ele‐\nments listed above. If the -n option is provided then the name of the file is\nincluded in the hash with key name.\n\n-f fd Use the file on file descriptor fd instead of named files; no list of file\nnames is allowed in this case.\n\n-F fmt Supplies a strftime (see strftime(3)) string for the formatting of the time el‐\nements. The format string supports all of the zsh extensions described in the\nsection EXPANSION OF PROMPT SEQUENCES in zshmisc(1). The -s option is implied.\n\n-g Show the time elements in the GMT time zone. The -s option is implied.\n\n-l List the names of the type elements (to standard output or an array as appro‐\npriate) and return immediately; arguments, and options other than -A, are ig‐\nnored.\n\n-L Perform an lstat (see lstat(2)) rather than a stat system call. In this case,\nif the file is a link, information about the link itself rather than the target\nfile is returned. This option is required to make the link element useful.\nIt's important to note that this is the exact opposite from ls(1), etc.\n\n-n Always show the names of files. Usually these are only shown when output is to\nstandard output and there is more than one file in the list.\n\n-N Never show the names of files.\n\n-o If a raw file mode is printed, show it in octal, which is more useful for human\nconsumption than the default of decimal. A leading zero will be printed in\nthis case. Note that this does not affect whether a raw or formatted file mode\nis shown, which is controlled by the -r and -s options, nor whether a mode is\nshown at all.\n\n-r Print raw data (the default format) alongside string data (the -s format); the\nstring data appears in parentheses after the raw data.\n\n-s Print mode, uid, gid and the three time elements as strings instead of numbers.\nIn each case the format is like that of ls -l.\n\n-t Always show the type names for the elements of struct stat. Usually these are\nonly shown when output is to standard output and no individual element has been\nselected.\n\n-T Never show the type names of the struct stat elements.\n", "subsections": [] }, "THE ZSH/SYSTEM MODULE": { "content": "The zsh/system module makes available various builtin commands and parameters.\n", "subsections": [ { "name": "Builtins", "content": "syserror [ -e errvar ] [ -p prefix ] [ errno | errname ]\nThis command prints out the error message associated with errno, a system error num‐\nber, followed by a newline to standard error.\n\nInstead of the error number, a name errname, for example ENOENT, may be used. The set\nof names is the same as the contents of the array errnos, see below.\n\nIf the string prefix is given, it is printed in front of the error message, with no\nintervening space.\n\nIf errvar is supplied, the entire message, without a newline, is assigned to the pa‐\nrameter names errvar and nothing is output.\n\nA return status of 0 indicates the message was successfully printed (although it may\nnot be useful if the error number was out of the system's range), a return status of 1\nindicates an error in the parameters, and a return status of 2 indicates the error\nname was not recognised (no message is printed for this).\n\n\nsysopen [ -arw ] [ -m permissions ] [ -o options ]\n-u fd file\nThis command opens a file. The -r, -w and -a flags indicate whether the file should be\nopened for reading, writing and appending, respectively. The -m option allows the ini‐\ntial permissions to use when creating a file to be specified in octal form. The file\ndescriptor is specified with -u. Either an explicit file descriptor in the range 0 to\n9 can be specified or a variable name can be given to which the file descriptor number\nwill be assigned.\n\nThe -o option allows various system specific options to be specified as a comma-sepa‐\nrated list. The following is a list of possible options. Note that, depending on the\nsystem, some may not be available.\ncloexec\nmark file to be closed when other programs are executed (else the file descrip‐\ntor remains open in subshells and forked external executables)\n\ncreate\ncreat create file if it does not exist\n\nexcl create file, error if it already exists\n\nnoatime\nsuppress updating of the file atime\n\nnofollow\nfail if file is a symbolic link\n\nsync request that writes wait until data has been physically written\n\ntruncate\ntrunc truncate file to size 0\n\nTo close the file, use one of the following:\n\nexec {fd}<&-\nexec {fd}>&-\n\n\nsysread [ -c countvar ] [ -i infd ] [ -o outfd ]\n[ -s bufsize ] [ -t timeout ] [ param ]\nPerform a single system read from file descriptor infd, or zero if that is not given.\nThe result of the read is stored in param or REPLY if that is not given. If countvar\nis given, the number of bytes read is assigned to the parameter named by countvar.\n\nThe maximum number of bytes read is bufsize or 8192 if that is not given, however the\ncommand returns as soon as any number of bytes was successfully read.\n\nIf timeout is given, it specifies a timeout in seconds, which may be zero to poll the\nfile descriptor. This is handled by the poll system call if available, otherwise the\nselect system call if available.\n\nIf outfd is given, an attempt is made to write all the bytes just read to the file de‐\nscriptor outfd. If this fails, because of a system error other than EINTR or because\nof an internal zsh error during an interrupt, the bytes read but not written are\nstored in the parameter named by param if supplied (no default is used in this case),\nand the number of bytes read but not written is stored in the parameter named by\ncountvar if that is supplied. If it was successful, countvar contains the full number\nof bytes transferred, as usual, and param is not set.\n\nThe error EINTR (interrupted system call) is handled internally so that shell inter‐\nrupts are transparent to the caller. Any other error causes a return.\n\nThe possible return statuses are\n0 At least one byte of data was successfully read and, if appropriate, written.\n\n1 There was an error in the parameters to the command. This is the only error\nfor which a message is printed to standard error.\n\n2 There was an error on the read, or on polling the input file descriptor for a\ntimeout. The parameter ERRNO gives the error.\n\n3 Data were successfully read, but there was an error writing them to outfd. The\nparameter ERRNO gives the error.\n\n4 The attempt to read timed out. Note this does not set ERRNO as this is not a\nsystem error.\n\n5 No system error occurred, but zero bytes were read. This usually indicates end\nof file. The parameters are set according to the usual rules; no write to\noutfd is attempted.\n\nsysseek [ -u fd ] [ -w start|end|current ] offset\nThe current file position at which future reads and writes will take place is adjusted\nto the specified byte offset. The offset is evaluated as a math expression. The -u op‐\ntion allows the file descriptor to be specified. By default the offset is specified\nrelative to the start or the file but, with the -w option, it is possible to specify\nthat the offset should be relative to the current position or the end of the file.\n\nsyswrite [ -c countvar ] [ -o outfd ] data\nThe data (a single string of bytes) are written to the file descriptor outfd, or 1 if\nthat is not given, using the write system call. Multiple write operations may be used\nif the first does not write all the data.\n\nIf countvar is given, the number of byte written is stored in the parameter named by\ncountvar; this may not be the full length of data if an error occurred.\n\nThe error EINTR (interrupted system call) is handled internally by retrying; otherwise\nan error causes the command to return. For example, if the file descriptor is set to\nnon-blocking output, an error EAGAIN (on some systems, EWOULDBLOCK) may result in the\ncommand returning early.\n\nThe return status may be 0 for success, 1 for an error in the parameters to the com‐\nmand, or 2 for an error on the write; no error message is printed in the last case,\nbut the parameter ERRNO will reflect the error that occurred.\n\nzsystem flock [ -t timeout ] [ -f var ] [-er] file\nzsystem flock -u fdexpr\nThe builtin zsystem's subcommand flock performs advisory file locking (via the fc‐\nntl(2) system call) over the entire contents of the given file. This form of locking\nrequires the processes accessing the file to cooperate; its most obvious use is be‐\ntween two instances of the shell itself.\n\nIn the first form the named file, which must already exist, is locked by opening a\nfile descriptor to the file and applying a lock to the file descriptor. The lock ter‐\nminates when the shell process that created the lock exits; it is therefore often con‐\nvenient to create file locks within subshells, since the lock is automatically re‐\nleased when the subshell exits. Note that use of the print builtin with the -u option\nwill, as a side effect, release the lock, as will redirection to the file in the shell\nholding the lock. To work around this use a subshell, e.g. `(print message) >> file'.\nStatus 0 is returned if the lock succeeds, else status 1.\n\nIn the second form the file descriptor given by the arithmetic expression fdexpr is\nclosed, releasing a lock. The file descriptor can be queried by using the `-f var'\nform during the lock; on a successful lock, the shell variable var is set to the file\ndescriptor used for locking. The lock will be released if the file descriptor is\nclosed by any other means, for example using `exec {var}>&-'; however, the form de‐\nscribed here performs a safety check that the file descriptor is in use for file lock‐\ning.\n\nBy default the shell waits indefinitely for the lock to succeed. The option -t time‐\nout specifies a timeout for the lock in seconds; currently this must be an integer.\nThe shell will attempt to lock the file once a second during this period. If the at‐\ntempt times out, status 2 is returned.\n\nIf the option -e is given, the file descriptor for the lock is preserved when the\nshell uses exec to start a new process; otherwise it is closed at that point and the\nlock released.\n\nIf the option -r is given, the lock is only for reading, otherwise it is for reading\nand writing. The file descriptor is opened accordingly.\n\nzsystem supports subcommand\nThe builtin zsystem's subcommand supports tests whether a given subcommand is sup‐\nported. It returns status 0 if so, else status 1. It operates silently unless there\nwas a syntax error (i.e. the wrong number of arguments), in which case status 255 is\nreturned. Status 1 can indicate one of two things: subcommand is known but not sup‐\nported by the current operating system, or subcommand is not known (possibly because\nthis is an older version of the shell before it was implemented).\n" }, { "name": "Math Functions", "content": "systell(fd)\nThe systell math function returns the current file position for the file descriptor\npassed as an argument.\n" }, { "name": "Parameters", "content": "errnos A readonly array of the names of errors defined on the system. These are typically\nmacros defined in C by including the system header file errno.h. The index of each\nname (assuming the option KSHARRAYS is unset) corresponds to the error number. Error\nnumbers num before the last known error which have no name are given the name Enum in\nthe array.\n\nNote that aliases for errors are not handled; only the canonical name is used.\n" }, { "name": "sysparams", "content": "A readonly associative array. The keys are:\n\npid Returns the process ID of the current process, even in subshells. Compare $$,\nwhich returns the process ID of the main shell process.\n\nppid Returns the process ID of the parent of the current process, even in subshells.\nCompare $PPID, which returns the process ID of the parent of the main shell\nprocess.\n\nprocsubstpid\nReturns the process ID of the last process started for process substitution,\ni.e. the <(...) and >(...) expansions.\n" } ] }, "THE ZSH/NET/TCP MODULE": { "content": "The zsh/net/tcp module makes available one builtin command:\n\nztcp [ -acflLtv ] [ -d fd ] [ args ]\nztcp is implemented as a builtin to allow full use of shell command line editing, file\nI/O, and job control mechanisms.\n\nIf ztcp is run with no options, it will output the contents of its session table.\n\nIf it is run with only the option -L, it will output the contents of the session table\nin a format suitable for automatic parsing. The option is ignored if given with a\ncommand to open or close a session. The output consists of a set of lines, one per\nsession, each containing the following elements separated by spaces:\n\nFile descriptor\nThe file descriptor in use for the connection. For normal inbound (I) and out‐\nbound (O) connections this may be read and written by the usual shell mecha‐\nnisms. However, it should only be close with `ztcp -c'.\n\nConnection type\nA letter indicating how the session was created:\n\nZ A session created with the zftp command.\n\nL A connection opened for listening with `ztcp -l'.\n\nI An inbound connection accepted with `ztcp -a'.\n\nO An outbound connection created with `ztcp host ...'.\n\nThe local host\nThis is usually set to an all-zero IP address as the address of the localhost\nis irrelevant.\n\nThe local port\nThis is likely to be zero unless the connection is for listening.\n\nThe remote host\nThis is the fully qualified domain name of the peer, if available, else an IP\naddress. It is an all-zero IP address for a session opened for listening.\n\nThe remote port\nThis is zero for a connection opened for listening.\n", "subsections": [ { "name": "Outbound Connections", "content": "ztcp [ -v ] [ -d fd ] host [ port ]\nOpen a new TCP connection to host. If the port is omitted, it will default to port\n23. The connection will be added to the session table and the shell parameter REPLY\nwill be set to the file descriptor associated with that connection.\n\nIf -d is specified, its argument will be taken as the target file descriptor for the\nconnection.\n\nIn order to elicit more verbose output, use -v.\n" }, { "name": "Inbound Connections", "content": "ztcp -l [ -v ] [ -d fd ] port\nztcp -l will open a socket listening on TCP port. The socket will be added to the\nsession table and the shell parameter REPLY will be set to the file descriptor associ‐\nated with that listener.\n\nIf -d is specified, its argument will be taken as the target file descriptor for the\nconnection.\n\nIn order to elicit more verbose output, use -v.\n\nztcp -a [ -tv ] [ -d targetfd ] listenfd\nztcp -a will accept an incoming connection to the port associated with listenfd. The\nconnection will be added to the session table and the shell parameter REPLY will be\nset to the file descriptor associated with the inbound connection.\n\nIf -d is specified, its argument will be taken as the target file descriptor for the\nconnection.\n\nIf -t is specified, ztcp will return if no incoming connection is pending. Otherwise\nit will wait for one.\n\nIn order to elicit more verbose output, use -v.\n" }, { "name": "Closing Connections", "content": "ztcp -cf [ -v ] [ fd ]\nztcp -c [ -v ] [ fd ]\nztcp -c will close the socket associated with fd. The socket will be removed from the\nsession table. If fd is not specified, ztcp will close everything in the session ta‐\nble.\n\nNormally, sockets registered by zftp (see zshmodules(1) ) cannot be closed this way.\nIn order to force such a socket closed, use -f.\n\nIn order to elicit more verbose output, use -v.\n" }, { "name": "Example", "content": "Here is how to create a TCP connection between two instances of zsh. We need to pick an\nunassigned port; here we use the randomly chosen 5123.\n\nOn host1,\nzmodload zsh/net/tcp\nztcp -l 5123\nlistenfd=$REPLY\nztcp -a $listenfd\nfd=$REPLY\nThe second from last command blocks until there is an incoming connection.\n\nNow create a connection from host2 (which may, of course, be the same machine):\nzmodload zsh/net/tcp\nztcp host1 5123\nfd=$REPLY\n\nNow on each host, $fd contains a file descriptor for talking to the other. For example, on\nhost1:\nprint This is a message >&$fd\nand on host2:\nread -r line <&$fd; print -r - $line\nprints `This is a message'.\n\nTo tidy up, on host1:\nztcp -c $listenfd\nztcp -c $fd\nand on host2\nztcp -c $fd\n" } ] }, "THE ZSH/TERMCAP MODULE": { "content": "The zsh/termcap module makes available one builtin command:\n\nechotc cap [ arg ... ]\nOutput the termcap value corresponding to the capability cap, with optional arguments.\n\nThe zsh/termcap module makes available one parameter:\n", "subsections": [ { "name": "termcap", "content": "An associative array that maps termcap capability codes to their values.\n" } ] }, "THE ZSH/TERMINFO MODULE": { "content": "The zsh/terminfo module makes available one builtin command:\n\nechoti cap [ arg ]\nOutput the terminfo value corresponding to the capability cap, instantiated with arg\nif applicable.\n\nThe zsh/terminfo module makes available one parameter:\n", "subsections": [ { "name": "terminfo", "content": "An associative array that maps terminfo capability names to their values.\n" } ] }, "THE ZSH/ZFTP MODULE": { "content": "The zsh/zftp module makes available one builtin command:\n\nzftp subcommand [ args ]\nThe zsh/zftp module is a client for FTP (file transfer protocol). It is implemented\nas a builtin to allow full use of shell command line editing, file I/O, and job con‐\ntrol mechanisms. Often, users will access it via shell functions providing a more\npowerful interface; a set is provided with the zsh distribution and is described in\nzshzftpsys(1). However, the zftp command is entirely usable in its own right.\n\nAll commands consist of the command name zftp followed by the name of a subcommand.\nThese are listed below. The return status of each subcommand is supposed to reflect\nthe success or failure of the remote operation. See a description of the variable\nZFTPVERBOSE for more information on how responses from the server may be printed.\n", "subsections": [ { "name": "Subcommands", "content": "open host[:port] [ user [ password [ account ] ] ]\nOpen a new FTP session to host, which may be the name of a TCP/IP connected host or an\nIP number in the standard dot notation. If the argument is in the form host:port,\nopen a connection to TCP port port instead of the standard FTP port 21. This may be\nthe name of a TCP service or a number: see the description of ZFTPPORT below for\nmore information.\n\nIf IPv6 addresses in colon format are used, the host should be surrounded by quoted\nsquare brackets to distinguish it from the port, for example\n'[fe80::203:baff:fe02:8b56]'. For consistency this is allowed with all forms of host.\n\nRemaining arguments are passed to the login subcommand. Note that if no arguments be‐\nyond host are supplied, open will not automatically call login. If no arguments at\nall are supplied, open will use the parameters set by the params subcommand.\n\nAfter a successful open, the shell variables ZFTPHOST, ZFTPPORT, ZFTPIP and\nZFTPSYSTEM are available; see `Variables' below.\n\nlogin [ name [ password [ account ] ] ]\nuser [ name [ password [ account ] ] ]\nLogin the user name with parameters password and account. Any of the parameters can\nbe omitted, and will be read from standard input if needed (name is always needed).\nIf standard input is a terminal, a prompt for each one will be printed on standard er‐\nror and password will not be echoed. If any of the parameters are not used, a warning\nmessage is printed.\n\nAfter a successful login, the shell variables ZFTPUSER, ZFTPACCOUNT and ZFTPPWD are\navailable; see `Variables' below.\n\nThis command may be re-issued when a user is already logged in, and the server will\nfirst be reinitialized for a new user.\n\nparams [ host [ user [ password [ account ] ] ] ]" }, { "name": "params -", "content": "Store the given parameters for a later open command with no arguments. Only those\ngiven on the command line will be remembered. If no arguments are given, the parame‐\nters currently set are printed, although the password will appear as a line of stars;\nthe return status is one if no parameters were set, zero otherwise.\n\nAny of the parameters may be specified as a `?', which may need to be quoted to pro‐\ntect it from shell expansion. In this case, the appropriate parameter will be read\nfrom stdin as with the login subcommand, including special handling of password. If\nthe `?' is followed by a string, that is used as the prompt for reading the parameter\ninstead of the default message (any necessary punctuation and whitespace should be in‐\ncluded at the end of the prompt). The first letter of the parameter (only) may be\nquoted with a `\\'; hence an argument \"\\\\$word\" guarantees that the string from the\nshell parameter $word will be treated literally, whether or not it begins with a `?'.\n\nIf instead a single `-' is given, the existing parameters, if any, are deleted. In\nthat case, calling open with no arguments will cause an error.\n\nThe list of parameters is not deleted after a close, however it will be deleted if the\nzsh/zftp module is unloaded.\n\nFor example,\n\nzftp params ftp.elsewhere.xx juser '?Password for juser: '\n\nwill store the host ftp.elsewhere.xx and the user juser and then prompt the user for\nthe corresponding password with the given prompt.\n\ntest Test the connection; if the server has reported that it has closed the connection\n(maybe due to a timeout), return status 2; if no connection was open anyway, return\nstatus 1; else return status 0. The test subcommand is silent, apart from messages\nprinted by the $ZFTPVERBOSE mechanism, or error messages if the connection closes.\nThere is no network overhead for this test.\n\nThe test is only supported on systems with either the select(2) or poll(2) system\ncalls; otherwise the message `not supported on this system' is printed instead.\n\nThe test subcommand will automatically be called at the start of any other subcommand\nfor the current session when a connection is open.\n\ncd directory\nChange the remote directory to directory. Also alters the shell variable ZFTPPWD.\n\ncdup Change the remote directory to the one higher in the directory tree. Note that cd ..\nwill also work correctly on non-UNIX systems.\n\ndir [ arg ... ]\nGive a (verbose) listing of the remote directory. The args are passed directly to the\nserver. The command's behaviour is implementation dependent, but a UNIX server will\ntypically interpret args as arguments to the ls command and with no arguments return\nthe result of `ls -l'. The directory is listed to standard output.\n\nls [ arg ... ]\nGive a (short) listing of the remote directory. With no arg, produces a raw list of\nthe files in the directory, one per line. Otherwise, up to vagaries of the server im‐\nplementation, behaves similar to dir.\n\ntype [ type ]\nChange the type for the transfer to type, or print the current type if type is absent.\nThe allowed values are `A' (ASCII), `I' (Image, i.e. binary), or `B' (a synonym for\n`I').\n\nThe FTP default for a transfer is ASCII. However, if zftp finds that the remote host\nis a UNIX machine with 8-bit byes, it will automatically switch to using binary for\nfile transfers upon open. This can subsequently be overridden.\n\nThe transfer type is only passed to the remote host when a data connection is estab‐\nlished; this command involves no network overhead.\n\nascii The same as type A.\n\nbinary The same as type I.\n\nmode [ S | B ]\nSet the mode type to stream (S) or block (B). Stream mode is the default; block mode\nis not widely supported.\n\nremote file ...\nlocal [ file ... ]\nPrint the size and last modification time of the remote or local files. If there is\nmore than one item on the list, the name of the file is printed first. The first num‐\nber is the file size, the second is the last modification time of the file in the for‐\nmat CCYYMMDDhhmmSS consisting of year, month, date, hour, minutes and seconds in GMT.\nNote that this format, including the length, is guaranteed, so that time strings can\nbe directly compared via the [[ builtin's < and > operators, even if they are too long\nto be represented as integers.\n\nNot all servers support the commands for retrieving this information. In that case,\nthe remote command will print nothing and return status 2, compared with status 1 for\na file not found.\n\nThe local command (but not remote) may be used with no arguments, in which case the\ninformation comes from examining file descriptor zero. This is the same file as seen\nby a put command with no further redirection.\n\nget file ...\nRetrieve all files from the server, concatenating them and sending them to standard\noutput.\n\nput file ...\nFor each file, read a file from standard input and send that to the remote host with\nthe given name.\n\nappend file ...\nAs put, but if the remote file already exists, data is appended to it instead of over‐\nwriting it.\n\ngetat file point\nputat file point\nappendat file point\nVersions of get, put and append which will start the transfer at the given point in\nthe remote file. This is useful for appending to an incomplete local file. However,\nnote that this ability is not universally supported by servers (and is not quite the\nbehaviour specified by the standard).\n\ndelete file ...\nDelete the list of files on the server.\n\nmkdir directory\nCreate a new directory directory on the server.\n\nrmdir directory\nDelete the directory directory on the server.\n\nrename old-name new-name\nRename file old-name to new-name on the server.\n\nsite arg ...\nSend a host-specific command to the server. You will probably only need this if in‐\nstructed by the server to use it.\n\nquote arg ...\nSend the raw FTP command sequence to the server. You should be familiar with the FTP\ncommand set as defined in RFC959 before doing this. Useful commands may include STAT\nand HELP. Note also the mechanism for returning messages as described for the vari‐\nable ZFTPVERBOSE below, in particular that all messages from the control connection\nare sent to standard error.\n" }, { "name": "close", "content": "quit Close the current data connection. This unsets the shell parameters ZFTPHOST,\nZFTPPORT, ZFTPIP, ZFTPSYSTEM, ZFTPUSER, ZFTPACCOUNT, ZFTPPWD, ZFTPTYPE and\nZFTPMODE.\n\nsession [ sessname ]\nAllows multiple FTP sessions to be used at once. The name of the session is an arbi‐\ntrary string of characters; the default session is called `default'. If this command\nis called without an argument, it will list all the current sessions; with an argu‐\nment, it will either switch to the existing session called sessname, or create a new\nsession of that name.\n\nEach session remembers the status of the connection, the set of connection-specific\nshell parameters (the same set as are unset when a connection closes, as given in the\ndescription of close), and any user parameters specified with the params subcommand.\nChanging to a previous session restores those values; changing to a new session ini‐\ntialises them in the same way as if zftp had just been loaded. The name of the cur‐\nrent session is given by the parameter ZFTPSESSION.\n\nrmsession [ sessname ]\nDelete a session; if a name is not given, the current session is deleted. If the cur‐\nrent session is deleted, the earliest existing session becomes the new current ses‐\nsion, otherwise the current session is not changed. If the session being deleted is\nthe only one, a new session called `default' is created and becomes the current ses‐\nsion; note that this is a new session even if the session being deleted is also called\n`default'. It is recommended that sessions not be deleted while background commands\nwhich use zftp are still active.\n" }, { "name": "Parameters", "content": "The following shell parameters are used by zftp. Currently none of them are special.\n\nZFTPTMOUT\nInteger. The time in seconds to wait for a network operation to complete before re‐\nturning an error. If this is not set when the module is loaded, it will be given the\ndefault value 60. A value of zero turns off timeouts. If a timeout occurs on the\ncontrol connection it will be closed. Use a larger value if this occurs too fre‐\nquently.\n\nZFTPIP\nReadonly. The IP address of the current connection in dot notation.\n\nZFTPHOST\nReadonly. The hostname of the current remote server. If the host was opened as an IP\nnumber, ZFTPHOST contains that instead; this saves the overhead for a name lookup, as\nIP numbers are most commonly used when a nameserver is unavailable.\n\nZFTPPORT\nReadonly. The number of the remote TCP port to which the connection is open (even if\nthe port was originally specified as a named service). Usually this is the standard\nFTP port, 21.\n\nIn the unlikely event that your system does not have the appropriate conversion func‐\ntions, this appears in network byte order. If your system is little-endian, the port\nthen consists of two swapped bytes and the standard port will be reported as 5376. In\nthat case, numeric ports passed to zftp open will also need to be in this format.\n\nZFTPSYSTEM\nReadonly. The system type string returned by the server in response to an FTP SYST\nrequest. The most interesting case is a string beginning \"UNIX Type: L8\", which en‐\nsures maximum compatibility with a local UNIX host.\n\nZFTPTYPE\nReadonly. The type to be used for data transfers , either `A' or `I'. Use the type\nsubcommand to change this.\n\nZFTPUSER\nReadonly. The username currently logged in, if any.\n\nZFTPACCOUNT\nReadonly. The account name of the current user, if any. Most servers do not require\nan account name.\n\nZFTPPWD\nReadonly. The current directory on the server.\n\nZFTPCODE\nReadonly. The three digit code of the last FTP reply from the server as a string.\nThis can still be read after the connection is closed, and is not changed when the\ncurrent session changes.\n\nZFTPREPLY\nReadonly. The last line of the last reply sent by the server. This can still be read\nafter the connection is closed, and is not changed when the current session changes.\n\nZFTPSESSION\nReadonly. The name of the current FTP session; see the description of the session\nsubcommand.\n\nZFTPPREFS\nA string of preferences for altering aspects of zftp's behaviour. Each preference is\na single character. The following are defined:\n\nP Passive: attempt to make the remote server initiate data transfers. This is\nslightly more efficient than sendport mode. If the letter S occurs later in\nthe string, zftp will use sendport mode if passive mode is not available.\n\nS Sendport: initiate transfers by the FTP PORT command. If this occurs before\nany P in the string, passive mode will never be attempted.\n\nD Dumb: use only the bare minimum of FTP commands. This prevents the variables\nZFTPSYSTEM and ZFTPPWD from being set, and will mean all connections default\nto ASCII type. It may prevent ZFTPSIZE from being set during a transfer if\nthe server does not send it anyway (many servers do).\n\nIf ZFTPPREFS is not set when zftp is loaded, it will be set to a default of `PS',\ni.e. use passive mode if available, otherwise fall back to sendport mode.\n\nZFTPVERBOSE\nA string of digits between 0 and 5 inclusive, specifying which responses from the\nserver should be printed. All responses go to standard error. If any of the numbers\n1 to 5 appear in the string, raw responses from the server with reply codes beginning\nwith that digit will be printed to standard error. The first digit of the three digit\nreply code is defined by RFC959 to correspond to:\n\n1. A positive preliminary reply.\n\n2. A positive completion reply.\n\n3. A positive intermediate reply.\n\n4. A transient negative completion reply.\n\n5. A permanent negative completion reply.\n\nIt should be noted that, for unknown reasons, the reply `Service not available', which\nforces termination of a connection, is classified as 421, i.e. `transient negative',\nan interesting interpretation of the word `transient'.\n\nThe code 0 is special: it indicates that all but the last line of multiline replies\nread from the server will be printed to standard error in a processed format. By con‐\nvention, servers use this mechanism for sending information for the user to read. The\nappropriate reply code, if it matches the same response, takes priority.\n\nIf ZFTPVERBOSE is not set when zftp is loaded, it will be set to the default value\n450, i.e., messages destined for the user and all errors will be printed. A null\nstring is valid and specifies that no messages should be printed.\n" }, { "name": "Functions", "content": "zftpchpwd\nIf this function is set by the user, it is called every time the directory changes on\nthe server, including when a user is logged in, or when a connection is closed. In\nthe last case, $ZFTPPWD will be unset; otherwise it will reflect the new directory.\n\nzftpprogress\nIf this function is set by the user, it will be called during a get, put or append op‐\neration each time sufficient data has been received from the host. During a get, the\ndata is sent to standard output, so it is vital that this function should write to\nstandard error or directly to the terminal, not to standard output.\n\nWhen it is called with a transfer in progress, the following additional shell parame‐\nters are set:\n\nZFTPFILE\nThe name of the remote file being transferred from or to.\n\nZFTPTRANSFER\nA G for a get operation and a P for a put operation.\n\nZFTPSIZE\nThe total size of the complete file being transferred: the same as the first\nvalue provided by the remote and local subcommands for a particular file. If\nthe server cannot supply this value for a remote file being retrieved, it will\nnot be set. If input is from a pipe the value may be incorrect and correspond\nsimply to a full pipe buffer.\n\nZFTPCOUNT\nThe amount of data so far transferred; a number between zero and $ZFTPSIZE, if\nthat is set. This number is always available.\n\nThe function is initially called with ZFTPTRANSFER set appropriately and ZFTPCOUNT\nset to zero. After the transfer is finished, the function will be called one more\ntime with ZFTPTRANSFER set to GF or PF, in case it wishes to tidy up. It is other‐\nwise never called twice with the same value of ZFTPCOUNT.\n\nSometimes the progress meter may cause disruption. It is up to the user to decide\nwhether the function should be defined and to use unfunction when necessary.\n" }, { "name": "Problems", "content": "A connection may not be opened in the left hand side of a pipe as this occurs in a subshell\nand the file information is not updated in the main shell. In the case of type or mode\nchanges or closing the connection in a subshell, the information is returned but variables\nare not updated until the next call to zftp. Other status changes in subshells will not be\nreflected by changes to the variables (but should be otherwise harmless).\n\nDeleting sessions while a zftp command is active in the background can have unexpected ef‐\nfects, even if it does not use the session being deleted. This is because all shell subpro‐\ncesses share information on the state of all connections, and deleting a session changes the\nordering of that information.\n\nOn some operating systems, the control connection is not valid after a fork(), so that opera‐\ntions in subshells, on the left hand side of a pipeline, or in the background are not possi‐\nble, as they should be. This is presumably a bug in the operating system.\n" } ] }, "THE ZSH/ZLE MODULE": { "content": "The zsh/zle module contains the Zsh Line Editor. See zshzle(1).\n", "subsections": [] }, "THE ZSH/ZLEPARAMETER MODULE": { "content": "The zsh/zleparameter module defines two special parameters that can be used to access inter‐\nnal information of the Zsh Line Editor (see zshzle(1)).\n", "subsections": [ { "name": "keymaps", "content": "This array contains the names of the keymaps currently defined.\n" }, { "name": "widgets", "content": "This associative array contains one entry per widget. The name of the widget is the\nkey and the value gives information about the widget. It is either\nthe string `builtin' for builtin widgets,\na string of the form `user:name' for user-defined widgets,\nwhere name is the name of the shell function implementing the widget,\na string of the form `completion:type:name'\nfor completion widgets,\nor a null value if the widget is not yet fully defined. In the penultimate case,\ntype is the name of the builtin widget the completion widget imitates in its behavior\nand name is the name of the shell function implementing the completion widget.\n" } ] }, "THE ZSH/ZPROF MODULE": { "content": "When loaded, the zsh/zprof causes shell functions to be profiled. The profiling results can\nbe obtained with the zprof builtin command made available by this module. There is no way to\nturn profiling off other than unloading the module.\n\nzprof [ -c ]\nWithout the -c option, zprof lists profiling results to standard output. The format\nis comparable to that of commands like gprof.\n\nAt the top there is a summary listing all functions that were called at least once.\nThis summary is sorted in decreasing order of the amount of time spent in each. The\nlines contain the number of the function in order, which is used in other parts of the\nlist in suffixes of the form `[num]', then the number of calls made to the function.\nThe next three columns list the time in milliseconds spent in the function and its de‐\nscendants, the average time in milliseconds spent in the function and its descendants\nper call and the percentage of time spent in all shell functions used in this function\nand its descendants. The following three columns give the same information, but\ncounting only the time spent in the function itself. The final column shows the name\nof the function.\n\nAfter the summary, detailed information about every function that was invoked is\nlisted, sorted in decreasing order of the amount of time spent in each function and\nits descendants. Each of these entries consists of descriptions for the functions\nthat called the function described, the function itself, and the functions that were\ncalled from it. The description for the function itself has the same format as in the\nsummary (and shows the same information). The other lines don't show the number of\nthe function at the beginning and have their function named indented to make it easier\nto distinguish the line showing the function described in the section from the sur‐\nrounding lines.\n\nThe information shown in this case is almost the same as in the summary, but only\nrefers to the call hierarchy being displayed. For example, for a calling function the\ncolumn showing the total running time lists the time spent in the described function\nand its descendants only for the times when it was called from that particular calling\nfunction. Likewise, for a called function, this columns lists the total time spent in\nthe called function and its descendants only for the times when it was called from the\nfunction described.\n\nAlso in this case, the column showing the number of calls to a function also shows a\nslash and then the total number of invocations made to the called function.\n\nAs long as the zsh/zprof module is loaded, profiling will be done and multiple invoca‐\ntions of the zprof builtin command will show the times and numbers of calls since the\nmodule was loaded. With the -c option, the zprof builtin command will reset its in‐\nternal counters and will not show the listing.\n", "subsections": [] }, "THE ZSH/ZPTY MODULE": { "content": "The zsh/zpty module offers one builtin:\n\nzpty [ -e ] [ -b ] name [ arg ... ]\nThe arguments following name are concatenated with spaces between, then executed as a\ncommand, as if passed to the eval builtin. The command runs under a newly assigned\npseudo-terminal; this is useful for running commands non-interactively which expect an\ninteractive environment. The name is not part of the command, but is used to refer to\nthis command in later calls to zpty.\n\nWith the -e option, the pseudo-terminal is set up so that input characters are echoed.\n\nWith the -b option, input to and output from the pseudo-terminal are made non-block‐\ning.\n\nThe shell parameter REPLY is set to the file descriptor assigned to the master side of\nthe pseudo-terminal. This allows the terminal to be monitored with ZLE descriptor\nhandlers (see zshzle(1)) or manipulated with sysread and syswrite (see THE ZSH/SYSTEM\nMODULE in zshmodules(1)). Warning: Use of sysread and syswrite is not recommended;\nuse zpty -r and zpty -w unless you know exactly what you are doing.\n\nzpty -d [ name ... ]\nThe second form, with the -d option, is used to delete commands previously started, by\nsupplying a list of their names. If no name is given, all commands are deleted.\nDeleting a command causes the HUP signal to be sent to the corresponding process.\n\nzpty -w [ -n ] name [ string ... ]\nThe -w option can be used to send the to command name the given strings as input (sep‐\narated by spaces). If the -n option is not given, a newline is added at the end.\n\nIf no string is provided, the standard input is copied to the pseudo-terminal; this\nmay stop before copying the full input if the pseudo-terminal is non-blocking. The\nexact input is always copied: the -n option is not applied.\n\nNote that the command under the pseudo-terminal sees this input as if it were typed,\nso beware when sending special tty driver characters such as word-erase, line-kill,\nand end-of-file.\n\nzpty -r [ -mt ] name [ param [ pattern ] ]\nThe -r option can be used to read the output of the command name. With only a name\nargument, the output read is copied to the standard output. Unless the pseudo-termi‐\nnal is non-blocking, copying continues until the command under the pseudo-terminal ex‐\nits; when non-blocking, only as much output as is immediately available is copied.\nThe return status is zero if any output is copied.\n\nWhen also given a param argument, at most one line is read and stored in the parameter\nnamed param. Less than a full line may be read if the pseudo-terminal is non-block‐\ning. The return status is zero if at least one character is stored in param.\n\nIf a pattern is given as well, output is read until the whole string read matches the\npattern, even in the non-blocking case. The return status is zero if the string read\nmatches the pattern, or if the command has exited but at least one character could\nstill be read. If the option -m is present, the return status is zero only if the\npattern matches. As of this writing, a maximum of one megabyte of output can be con‐\nsumed this way; if a full megabyte is read without matching the pattern, the return\nstatus is non-zero.\n\nIn all cases, the return status is non-zero if nothing could be read, and is 2 if this\nis because the command has finished.\n\nIf the -r option is combined with the -t option, zpty tests whether output is avail‐\nable before trying to read. If no output is available, zpty immediately returns the\nstatus 1. When used with a pattern, the behaviour on a failed poll is similar to when\nthe command has exited: the return value is zero if at least one character could\nstill be read even if the pattern failed to match.\n\nzpty -t name\nThe -t option without the -r option can be used to test whether the command name is\nstill running. It returns a zero status if the command is running and a non-zero\nvalue otherwise.\n\nzpty [ -L ]\nThe last form, without any arguments, is used to list the commands currently defined.\nIf the -L option is given, this is done in the form of calls to the zpty builtin.\n", "subsections": [] }, "THE ZSH/ZSELECT MODULE": { "content": "The zsh/zselect module makes available one builtin command:\n\nzselect [ -rwe ] [ -t timeout ] [ -a array ] [ -A assoc ] [ fd ... ]\nThe zselect builtin is a front-end to the `select' system call, which blocks until a\nfile descriptor is ready for reading or writing, or has an error condition, with an\noptional timeout. If this is not available on your system, the command prints an er‐\nror message and returns status 2 (normal errors return status 1). For more informa‐\ntion, see your systems documentation for select(3). Note there is no connection with\nthe shell builtin of the same name.\n\nArguments and options may be intermingled in any order. Non-option arguments are file\ndescriptors, which must be decimal integers. By default, file descriptors are to be\ntested for reading, i.e. zselect will return when data is available to be read from\nthe file descriptor, or more precisely, when a read operation from the file descriptor\nwill not block. After a -r, -w and -e, the given file descriptors are to be tested\nfor reading, writing, or error conditions. These options and an arbitrary list of\nfile descriptors may be given in any order.\n\n(The presence of an `error condition' is not well defined in the documentation for\nmany implementations of the select system call. According to recent versions of the\nPOSIX specification, it is really an exception condition, of which the only standard\nexample is out-of-band data received on a socket. So zsh users are unlikely to find\nthe -e option useful.)\n\nThe option `-t timeout' specifies a timeout in hundredths of a second. This may be\nzero, in which case the file descriptors will simply be polled and zselect will return\nimmediately. It is possible to call zselect with no file descriptors and a non-zero\ntimeout for use as a finer-grained replacement for `sleep'; note, however, the return\nstatus is always 1 for a timeout.\n\nThe option `-a array' indicates that array should be set to indicate the file descrip‐\ntor(s) which are ready. If the option is not given, the array reply will be used for\nthis purpose. The array will contain a string similar to the arguments for zselect.\nFor example,\n\nzselect -t 0 -r 0 -w 1\n\nmight return immediately with status 0 and $reply containing `-r 0 -w 1' to show that\nboth file descriptors are ready for the requested operations.\n\nThe option `-A assoc' indicates that the associative array assoc should be set to in‐\ndicate the file descriptor(s) which are ready. This option overrides the option -a,\nnor will reply be modified. The keys of assoc are the file descriptors, and the cor‐\nresponding values are any of the characters `rwe' to indicate the condition.\n\nThe command returns status 0 if some file descriptors are ready for reading. If the\noperation timed out, or a timeout of 0 was given and no file descriptors were ready,\nor there was an error, it returns status 1 and the array will not be set (nor modified\nin any way). If there was an error in the select operation the appropriate error mes‐\nsage is printed.\n", "subsections": [] }, "THE ZSH/ZUTIL MODULE": { "content": "The zsh/zutil module only adds some builtins:\n\nzstyle [ -L [ metapattern [ style ] ] ]\nzstyle [ -e | - | -- ] pattern style string ...\nzstyle -d [ pattern [ style ... ] ]\nzstyle -g name [ pattern [ style ] ]\nzstyle -{a|b|s} context style name [ sep ]\nzstyle -{T|t} context style [ string ... ]\nzstyle -m context style pattern\nThis builtin command is used to define and lookup styles. Styles are pairs of names\nand values, where the values consist of any number of strings. They are stored to‐\ngether with patterns and lookup is done by giving a string, called the `context',\nwhich is matched against the patterns. The definition stored for the most specific\npattern that matches will be returned.\n\nA pattern is considered to be more specific than another if it contains more compo‐\nnents (substrings separated by colons) or if the patterns for the components are more\nspecific, where simple strings are considered to be more specific than patterns and\ncomplex patterns are considered to be more specific than the pattern `*'. A `*' in\nthe pattern will match zero or more characters in the context; colons are not treated\nspecially in this regard. If two patterns are equally specific, the tie is broken in\nfavour of the pattern that was defined first.\n\nExample\n\nFor example, to define your preferred form of precipitation depending on which city\nyou're in, you might set the following in your zshrc:\n\nzstyle ':weather:europe:*' preferred-precipitation rain\nzstyle ':weather:europe:germany:* preferred-precipitation none\nzstyle ':weather:europe:germany:*:munich' preferred-precipitation snow\n\nThen, the fictional `weather' plugin might run under the hood a command such as\n\nzstyle -s \":weather:${continent}:${country}:${county}:${city}\" preferred-precipitation REPLY\n\nin order to retrieve your preference into the scalar variable $REPLY.\n\nUsage\n\nThe forms that operate on patterns are the following.\n\nzstyle [ -L [ metapattern [ style ] ] ]\nWithout arguments, lists style definitions. Styles are shown in alphabetic or‐\nder and patterns are shown in the order zstyle will test them.\n\nIf the -L option is given, listing is done in the form of calls to zstyle. The\noptional first argument, metapattern, is a pattern which will be matched\nagainst the string supplied as pattern when the style was defined. Note: this\nmeans, for example, `zstyle -L \":completion:*\"' will match any supplied pattern\nbeginning `:completion:', not just \":completion:*\": use ':completion:\\*' to\nmatch that. The optional second argument limits the output to a specific style\n(not a pattern). -L is not compatible with any other options.\n\nzstyle [ - | -- | -e ] pattern style string ...\nDefines the given style for the pattern with the strings as the value. If the\n-e option is given, the strings will be concatenated (separated by spaces) and\nthe resulting string will be evaluated (in the same way as it is done by the\neval builtin command) when the style is looked up. In this case the parameter\n`reply' must be assigned to set the strings returned after the evaluation. Be‐\nfore evaluating the value, reply is unset, and if it is still unset after the\nevaluation, the style is treated as if it were not set.\n\nzstyle -d [ pattern [ style ... ] ]\nDelete style definitions. Without arguments all definitions are deleted, with a\npattern all definitions for that pattern are deleted and if any styles are\ngiven, then only those styles are deleted for the pattern.\n\nzstyle -g name [ pattern [ style ] ]\nRetrieve a style definition. The name is used as the name of an array in which\nthe results are stored. Without any further arguments, all patterns defined are\nreturned. With a pattern the styles defined for that pattern are returned and\nwith both a pattern and a style, the value strings of that combination is re‐\nturned.\n\nThe other forms can be used to look up or test styles for a given context.\n\nzstyle -s context style name [ sep ]\nThe parameter name is set to the value of the style interpreted as a string.\nIf the value contains several strings they are concatenated with spaces (or\nwith the sep string if that is given) between them.\n\nReturn 0 if the style is set, 1 otherwise.\n\nzstyle -b context style name\nThe value is stored in name as a boolean, i.e. as the string `yes' if the value\nhas only one string and that string is equal to one of `yes', `true', `on', or\n`1'. If the value is any other string or has more than one string, the parame‐\nter is set to `no'.\n\nReturn 0 if name is set to `yes', 1 otherwise.\n\nzstyle -a context style name\nThe value is stored in name as an array. If name is declared as an associative\narray, the first, third, etc. strings are used as the keys and the other\nstrings are used as the values.\n\nReturn 0 if the style is set, 1 otherwise.\n\nzstyle -t context style [ string ... ]\nzstyle -T context style [ string ... ]\nTest the value of a style, i.e. the -t option only returns a status (sets $?).\nWithout any string the return status is zero if the style is defined for at\nleast one matching pattern, has only one string in its value, and that is equal\nto one of `true', `yes', `on' or `1'. If any strings are given the status is\nzero if and only if at least one of the strings is equal to at least one of the\nstrings in the value. If the style is defined but doesn't match, the return\nstatus is 1. If the style is not defined, the status is 2.\n\nThe -T option tests the values of the style like -t, but it returns status zero\n(rather than 2) if the style is not defined for any matching pattern.\n\nzstyle -m context style pattern\nMatch a value. Returns status zero if the pattern matches at least one of the\nstrings in the value.\n\nzformat -f param format spec ...\nzformat -a array sep spec ...\nThis builtin provides two different forms of formatting. The first form is selected\nwith the -f option. In this case the format string will be modified by replacing se‐\nquences starting with a percent sign in it with strings from the specs. Each spec\nshould be of the form `char:string' which will cause every appearance of the sequence\n`%char' in format to be replaced by the string. The `%' sequence may also contain op‐\ntional minimum and maximum field width specifications between the `%' and the `char'\nin the form `%min.maxc', i.e. the minimum field width is given first and if the maxi‐\nmum field width is used, it has to be preceded by a dot. Specifying a minimum field\nwidth makes the result be padded with spaces to the right if the string is shorter\nthan the requested width. Padding to the left can be achieved by giving a negative\nminimum field width. If a maximum field width is specified, the string will be trun‐\ncated after that many characters. After all `%' sequences for the given specs have\nbeen processed, the resulting string is stored in the parameter param.\n\nThe %-escapes also understand ternary expressions in the form used by prompts. The %\nis followed by a `(' and then an ordinary format specifier character as described\nabove. There may be a set of digits either before or after the `('; these specify a\ntest number, which defaults to zero. Negative numbers are also allowed. An arbitrary\ndelimiter character follows the format specifier, which is followed by a piece of\n`true' text, the delimiter character again, a piece of `false' text, and a closing\nparenthesis. The complete expression (without the digits) thus looks like\n`%(X.text1.text2)', except that the `.' character is arbitrary. The value given for\nthe format specifier in the char:string expressions is evaluated as a mathematical ex‐\npression, and compared with the test number. If they are the same, text1 is output,\nelse text2 is output. A parenthesis may be escaped in text2 as %). Either of text1\nor text2 may contain nested %-escapes.\n\nFor example:\n\nzformat -f REPLY \"The answer is '%3(c.yes.no)'.\" c:3\n\noutputs \"The answer is 'yes'.\" to REPLY since the value for the format specifier c is\n3, agreeing with the digit argument to the ternary expression.\n\nThe second form, using the -a option, can be used for aligning strings. Here, the\nspecs are of the form `left:right' where `left' and `right' are arbitrary strings.\nThese strings are modified by replacing the colons by the sep string and padding the\nleft strings with spaces to the right so that the sep strings in the result (and hence\nthe right strings after them) are all aligned if the strings are printed below each\nother. All strings without a colon are left unchanged and all strings with an empty\nright string have the trailing colon removed. In both cases the lengths of the\nstrings are not used to determine how the other strings are to be aligned. A colon in\nthe left string can be escaped with a backslash. The resulting strings are stored in\nthe array.\n", "subsections": [ { "name": "zregexparse", "content": "This implements some internals of the regexarguments function.\n\nzparseopts [ -D -E -F -K -M ] [ -a array ] [ -A assoc ] [ - ] spec ...\nThis builtin simplifies the parsing of options in positional parameters, i.e. the set\nof arguments given by $*. Each spec describes one option and must be of the form\n`opt[=array]'. If an option described by opt is found in the positional parameters it\nis copied into the array specified with the -a option; if the optional `=array' is\ngiven, it is instead copied into that array, which should be declared as a normal ar‐\nray and never as an associative array.\n\nNote that it is an error to give any spec without an `=array' unless one of the -a or\n-A options is used.\n\nUnless the -E option is given, parsing stops at the first string that isn't described\nby one of the specs. Even with -E, parsing always stops at a positional parameter\nequal to `-' or `--'. See also -F.\n\nThe opt description must be one of the following. Any of the special characters can\nappear in the option name provided it is preceded by a backslash.\n\nname\nname+ The name is the name of the option without the leading `-'. To specify a\nGNU-style long option, one of the usual two leading `-' must be included in\nname; for example, a `--file' option is represented by a name of `-file'.\n\nIf a `+' appears after name, the option is appended to array each time it is\nfound in the positional parameters; without the `+' only the last occurrence of\nthe option is preserved.\n\nIf one of these forms is used, the option takes no argument, so parsing stops\nif the next positional parameter does not also begin with `-' (unless the -E\noption is used).\n\nname:\nname:-\nname:: If one or two colons are given, the option takes an argument; with one colon,\nthe argument is mandatory and with two colons it is optional. The argument is\nappended to the array after the option itself.\n\nAn optional argument is put into the same array element as the option name\n(note that this makes empty strings as arguments indistinguishable). A manda‐\ntory argument is added as a separate element unless the `:-' form is used, in\nwhich case the argument is put into the same element.\n\nA `+' as described above may appear between the name and the first colon.\n\nIn all cases, option-arguments must appear either immediately following the option in\nthe same positional parameter or in the next one. Even an optional argument may appear\nin the next parameter, unless it begins with a `-'. There is no special handling of\n`=' as with GNU-style argument parsers; given the spec `-foo:', the positional parame‐\nter `--foo=bar' is parsed as `--foo' with an argument of `=bar'.\n\nWhen the names of two options that take no arguments overlap, the longest one wins, so\nthat parsing for the specs `-foo -foobar' (for example) is unambiguous. However, due\nto the aforementioned handling of option-arguments, ambiguities may arise when at\nleast one overlapping spec takes an argument, as in `-foo: -foobar'. In that case, the\nlast matching spec wins.\n\nThe options of zparseopts itself cannot be stacked because, for example, the stack\n`-DEK' is indistinguishable from a spec for the GNU-style long option `--DEK'. The\noptions of zparseopts itself are:\n\n-a array\nAs described above, this names the default array in which to store the recog‐\nnised options.\n\n-A assoc\nIf this is given, the options and their values are also put into an associative\narray with the option names as keys and the arguments (if any) as the values.\n\n-D If this option is given, all options found are removed from the positional pa‐\nrameters of the calling shell or shell function, up to but not including any\nnot described by the specs. If the first such parameter is `-' or `--', it is\nremoved as well. This is similar to using the shift builtin.\n\n-E This changes the parsing rules to not stop at the first string that isn't de‐\nscribed by one of the specs. It can be used to test for or (if used together\nwith -D) extract options and their arguments, ignoring all other options and\narguments that may be in the positional parameters. As indicated above, pars‐\ning still stops at the first `-' or `--' not described by a spec, but it is not\nremoved when used with -D.\n\n-F If this option is given, zparseopts immediately stops at the first option-like\nparameter not described by one of the specs, prints an error message, and re‐\nturns status 1. Removal (-D) and extraction (-E) are not performed, and option\narrays are not updated. This provides basic validation for the given options.\n\nNote that the appearance in the positional parameters of an option without its\nrequired argument always aborts parsing and returns an error as described above\nregardless of whether this option is used.\n\n-K With this option, the arrays specified with the -a option and with the `=array'\nforms are kept unchanged when none of the specs for them is used. Otherwise\nthe entire array is replaced when any of the specs is used. Individual ele‐\nments of associative arrays specified with the -A option are preserved by -K.\nThis allows assignment of default values to arrays before calling zparseopts.\n\n-M This changes the assignment rules to implement a map among equivalent option\nnames. If any spec uses the `=array' form, the string array is interpreted as\nthe name of another spec, which is used to choose where to store the values.\nIf no other spec is found, the values are stored as usual. This changes only\nthe way the values are stored, not the way $* is parsed, so results may be un‐\npredictable if the `name+' specifier is used inconsistently.\n\nFor example,\n\nset -- -a -bx -c y -cz baz -cend\nzparseopts a=foo b:=bar c+:=bar\n\nwill have the effect of\n\nfoo=(-a)\nbar=(-b x -c y -c z)\n\nThe arguments from `baz' on will not be used.\n\nAs an example for the -E option, consider:\n\nset -- -a x -b y -c z arg1 arg2\nzparseopts -E -D b:=bar\n\nwill have the effect of\n\nbar=(-b y)\nset -- -a x -c z arg1 arg2\n\nI.e., the option -b and its arguments are taken from the positional parameters and put\ninto the array bar.\n\nThe -M option can be used like this:\n\nset -- -a -bx -c y -cz baz -cend\nzparseopts -A bar -M a=foo b+: c:=b\n\nto have the effect of\n\nfoo=(-a)\nbar=(-a '' -b xyz)\n\n\n\nZSHCALSYS(1) General Commands Manual ZSHCALSYS(1)\n\n\n" } ] }, "FILE AND DATE FORMATS": { "content": "", "subsections": [ { "name": "Calendar File Format", "content": "The calendar file is by default ~/calendar. This can be configured by the calendar-file\nstyle, see the section STYLES below. The basic format consists of a series of separate\nlines, with no indentation, each including a date and time specification followed by a de‐\nscription of the event.\n\nVarious enhancements to this format are supported, based on the syntax of Emacs calendar\nmode. An indented line indicates a continuation line that continues the description of the\nevent from the preceding line (note the date may not be continued in this way). An initial\nampersand (&) is ignored for compatibility.\n\nAn indented line on which the first non-whitespace character is # is not displayed with the\ncalendar entry, but is still scanned for information. This can be used to hide information\nuseful to the calendar system but not to the user, such as the unique identifier used by cal‐‐\nendaradd.\n\nThe Emacs extension that a date with no description may refer to a number of succeeding\nevents at different times is not supported.\n\nUnless the done-file style has been altered, any events which have been processed are ap‐\npended to the file with the same name as the calendar file with the suffix .done, hence\n~/calendar.done by default.\n\nAn example is shown below.\n" }, { "name": "Date Format", "content": "The format of the date and time is designed to allow flexibility without admitting ambiguity.\n(The words `date' and `time' are both used in the documentation below; except where specifi‐\ncally noted this implies a string that may include both a date and a time specification.)\nNote that there is no localization support; month and day names must be in English and sepa‐\nrator characters are fixed. Matching is case insensitive, and only the first three letters\nof the names are significant, although as a special case a form beginning \"month\" does not\nmatch \"Monday\". Furthermore, time zones are not handled; all times are assumed to be local.\n\nIt is recommended that, rather than exploring the intricacies of the system, users find a\ndate format that is natural to them and stick to it. This will avoid unexpected effects.\nVarious key facts should be noted.\n\n• In particular, note the confusion between month/day/year and day/month/year when the\nmonth is numeric; these formats should be avoided if at all possible. Many alterna‐\ntives are available.\n\n• The year must be given in full to avoid confusion, and only years from 1900 to 2099\ninclusive are matched.\n\nThe following give some obvious examples; users finding here a format they like and not sub‐\nject to vagaries of style may skip the full description. As dates and times are matched sep‐\narately (even though the time may be embedded in the date), any date format may be mixed with\nany format for the time of day provide the separators are clear (whitespace, colons, commas).\n\n2007/04/03 13:13\n2007/04/03:13:13\n2007/04/03 1:13 pm\n3rd April 2007, 13:13\nApril 3rd 2007 1:13 p.m.\nApr 3, 2007 13:13\nTue Apr 03 13:13:00 2007\n13:13 2007/apr/3\n\nMore detailed rules follow.\n\nTimes are parsed and extracted before dates. They must use colons to separate hours and min‐\nutes, though a dot is allowed before seconds if they are present. This limits time formats\nto the following:\n\n• HH:MM[:SS[.FFFFF]] [am|pm|a.m.|p.m.]\n\n• HH:MM.SS[.FFFFF] [am|pm|a.m.|p.m.]\n\nHere, square brackets indicate optional elements, possibly with alternatives. Fractions of a\nsecond are recognised but ignored. For absolute times (the normal format require by the cal‐‐\nendar file and the age, before and after functions) a date is mandatory but a time of day is\nnot; the time returned is at the start of the date. One variation is allowed: if a.m. or\np.m. or one of their variants is present, an hour without a minute is allowed, e.g. 3 p.m..\n\nTime zones are not handled, though if one is matched following a time specification it will\nbe removed to allow a surrounding date to be parsed. This only happens if the format of the\ntimezone is not too unusual. The following are examples of forms that are understood:\n\n+0100\nGMT\nGMT-7\nCET+1CDT\n\nAny part of the timezone that is not numeric must have exactly three capital letters in the\nname.\n\nDates suffer from the ambiguity between DD/MM/YYYY and MM/DD/YYYY. It is recommended this\nform is avoided with purely numeric dates, but use of ordinals, eg. 3rd/04/2007, will resolve\nthe ambiguity as the ordinal is always parsed as the day of the month. Years must be four\ndigits (and the first two must be 19 or 20); 03/04/08 is not recognised. Other numbers may\nhave leading zeroes, but they are not required. The following are handled:\n\n• YYYY/MM/DD\n\n• YYYY-MM-DD\n\n• YYYY/MNM/DD\n\n• YYYY-MNM-DD\n\n• DD[th|st|rd] MNM[,] [ YYYY ]\n\n• MNM DD[th|st|rd][,] [ YYYY ]\n\n• DD[th|st|rd]/MM[,] YYYY\n\n• DD[th|st|rd]/MM/YYYY\n\n• MM/DD[th|st|rd][,] YYYY\n\n• MM/DD[th|st|rd]/YYYY\n\nHere, MNM is at least the first three letters of a month name, matched case-insensitively.\nThe remainder of the month name may appear but its contents are irrelevant, so janissary,\nfebrile, martial, apricot, maybe, junta, etc. are happily handled.\n\nWhere the year is shown as optional, the current year is assumed. There are only two such\ncases, the form Jun 20 or 14 September (the only two commonly occurring forms, apart from a\n\"the\" in some forms of English, which isn't currently supported). Such dates will of course\nbecome ambiguous in the future, so should ideally be avoided.\n\nTimes may follow dates with a colon, e.g. 1965/07/12:09:45; this is in order to provide a\nformat with no whitespace. A comma and whitespace are allowed, e.g. 1965/07/12, 09:45. Cur‐\nrently the order of these separators is not checked, so illogical formats such as 1965/07/12,\n: ,09:45 will also be matched. For simplicity such variations are not shown in the list\nabove. Otherwise, a time is only recognised as being associated with a date if there is only\nwhitespace in between, or if the time was embedded in the date.\n\nDays of the week are not normally scanned, but will be ignored if they occur at the start of\nthe date pattern only. However, in contexts where it is useful to specify dates relative to\ntoday, days of the week with no other date specification may be given. The day is assumed to\nbe either today or within the past week. Likewise, the words yesterday, today and tomorrow\nare handled. All matches are case-insensitive. Hence if today is Monday, then Sunday is\nequivalent to yesterday, Monday is equivalent to today, but Tuesday gives a date six days\nago. This is not generally useful within the calendar file. Dates in this format may be\ncombined with a time specification; for example Tomorrow, 8 p.m..\n\nFor example, the standard date format:\n\nFri Aug 18 17:00:48 BST 2006\n\nis handled by matching HH:MM:SS and removing it together with the matched (but unused) time\nzone. This leaves the following:\n\nFri Aug 18 2006\n\nFri is ignored and the rest is matched according to the standard rules.\n" }, { "name": "Relative Time Format", "content": "In certain places relative times are handled. Here, a date is not allowed; instead a combi‐\nnation of various supported periods are allowed, together with an optional time. The periods\nmust be in order from most to least significant.\n\nIn some cases, a more accurate calculation is possible when there is an anchor date: offsets\nof months or years pick the correct day, rather than being rounded, and it is possible to\npick a particular day in a month as `(1st Friday)', etc., as described in more detail below.\n\nAnchors are available in the following cases. If one or two times are passed to the function\ncalendar, the start time acts an anchor for the end time when the end time is relative (even\nif the start time is implicit). When examining calendar files, the scheduled event being ex‐\namined anchors the warning time when it is given explicitly by means of the WARN keyword;\nlikewise, the scheduled event anchors a repetition period when given by the RPT keyword, so\nthat specifications such as RPT 2 months, 3rd Thursday are handled properly. Finally, the -R\nargument to calendarscandate directly provides an anchor for relative calculations.\n\nThe periods handled, with possible abbreviations are:\n\nYears years, yrs, ys, year, yr, y, yearly. A year is 365.25 days unless there is an anchor.\n\nMonths months, mons, mnths, mths, month, mon, mnth, mth, monthly. Note that m, ms, mn, mns\nare ambiguous and are not handled. A month is a period of 30 days rather than a cal‐\nendar month unless there is an anchor.\n\nWeeks weeks, wks, ws, week, wk, w, weekly\n\nDays days, dys, ds, day, dy, d, daily\n\nHours hours, hrs, hs, hour, hr, h, hourly\n\nMinutes\nminutes, mins, minute, min, but not m, ms, mn or mns\n\nSeconds\nseconds, secs, ss, second, sec, s\n\nSpaces between the numbers are optional, but are required between items, although a comma may\nbe used (with or without spaces).\n\nThe forms yearly to hourly allow the number to be omitted; it is assumed to be 1. For exam‐\nple, 1 d and daily are equivalent. Note that using those forms with plurals is confusing; 2\nyearly is the same as 2 years, not twice yearly, so it is recommended they only be used with‐\nout numbers.\n\nWhen an anchor time is present, there is an extension to handle regular events in the form of\nthe nth someday of the month. Such a specification must occur immediately after any year and\nmonth specification, but before any time of day, and must be in the form n(th|st|rd) day, for\nexample 1st Tuesday or 3rd Monday. As in other places, days are matched case insensitively,\nmust be in English, and only the first three letters are significant except that a form be‐\nginning `month' does not match `Monday'. No attempt is made to sanitize the resulting date;\nattempts to squeeze too many occurrences into a month will push the day into the next month\n(but in the obvious fashion, retaining the correct day of the week).\n\nHere are some examples:\n\n30 years 3 months 4 days 3:42:41\n14 days 5 hours\nMonthly, 3rd Thursday\n4d,10hr\n" }, { "name": "Example", "content": "Here is an example calendar file. It uses a consistent date format, as recommended above.\n\nFeb 1, 2006 14:30 Pointless bureaucratic meeting\nMar 27, 2006 11:00 Mutual recrimination and finger pointing\nBring water pistol and waterproofs\nMar 31, 2006 14:00 Very serious managerial pontification\n# UID 12C7878A9A50\nApr 10, 2006 13:30 Even more pointless blame assignment exercise WARN 30 mins\nMay 18, 2006 16:00 Regular moaning session RPT monthly, 3rd Thursday\n\nThe second entry has a continuation line. The third entry has a continuation line that will\nnot be shown when the entry is displayed, but the unique identifier will be used by the cal‐‐\nendaradd function when updating the event. The fourth entry will produce a warning 30 min‐\nutes before the event (to allow you to equip yourself appropriately). The fifth entry re‐\npeats after a month on the 3rd Thursday, i.e. June 15, 2006, at the same time.\n" } ] }, "USER FUNCTIONS": { "content": "This section describes functions that are designed to be called directly by the user. The\nfirst part describes those functions associated with the user's calendar; the second part de‐\nscribes the use in glob qualifiers.\n", "subsections": [ { "name": "Calendar system functions", "content": "calendar [ -abdDsv ] [ -C calfile ] [ -n num ] [ -S showprog ]\n[ [ start ] end ]\ncalendar -r [ -abdDrsv ] [ -C calfile ] [ -n num ] [ -S showprog ]\n[ start ]\nShow events in the calendar.\n\nWith no arguments, show events from the start of today until the end of the next work‐\ning day after today. In other words, if today is Friday, Saturday, or Sunday, show up\nto the end of the following Monday, otherwise show today and tomorrow.\n\nIf end is given, show events from the start of today up to the time and date given,\nwhich is in the format described in the previous section. Note that if this is a date\nthe time is assumed to be midnight at the start of the date, so that effectively this\nshows all events before the given date.\n\nend may start with a +, in which case the remainder of the specification is a relative\ntime format as described in the previous section indicating the range of time from the\nstart time that is to be included.\n\nIf start is also given, show events starting from that time and date. The word now\ncan be used to indicate the current time.\n\nTo implement an alert when events are due, include calendar -s in your ~/.zshrc file.\n\nOptions:\n\n-a Show all items in the calendar, regardless of the start and end.\n\n-b Brief: don't display continuation lines (i.e. indented lines following the\nline with the date/time), just the first line.\n\n-B lines\nBrief: display at most the first lines lines of the calendar entry. `-B 1' is\nequivalent to `-b'.\n\n-C calfile\nExplicitly specify a calendar file instead of the value of the calendar-file\nstyle or the default ~/calendar.\n\n-d Move any events that have passed from the calendar file to the \"done\" file, as\ngiven by the done-file style or the default which is the calendar file with\n.done appended. This option is implied by the -s option.\n\n-D Turns off the option -d, even if the -s option is also present.\n\n-n num, -num\nShow at least num events, if present in the calendar file, regardless of the\nstart and end.\n\n-r Show all the remaining options in the calendar, ignoring the given end time.\nThe start time is respected; any argument given is treated as a start time.\n\n-s Use the shell's sched command to schedule a timed event that will warn the user\nwhen an event is due. Note that the sched command only runs if the shell is at\nan interactive prompt; a foreground task blocks the scheduled task from running\nuntil it is finished.\n\nThe timed event usually runs the programme calendarshow to show the event, as\ndescribed in the section UTILITY FUNCTIONS below.\n\nBy default, a warning of the event is shown five minutes before it is due. The\nwarning period can be configured by the style warn-time or for a single calen‐\ndar entry by including WARN reltime in the first line of the entry, where rel‐\ntime is one of the usual relative time formats.\n\nA repeated event may be indicated by including RPT reldate in the first line of\nthe entry. After the scheduled event has been displayed it will be re-entered\ninto the calendar file at a time reldate after the existing event. Note that\nthis is currently the only use made of the repeat count, so that it is not pos‐\nsible to query the schedule for a recurrence of an event in the calendar until\nthe previous event has passed.\n\nIf RPT is used, it is also possible to specify that certain recurrences of an\nevent are rescheduled or cancelled. This is done with the OCCURRENCE keyword,\nfollowed by whitespace and the date and time of the occurrence in the regular\nsequence, followed by whitespace and either the date and time of the resched‐\nuled event or the exact string CANCELLED. In this case the date and time must\nbe in exactly the \"date with local time\" format used by the text/calendar MIME\ntype (RFC 2445),
T (note the presence of the literal\ncharacter T). The first word (the regular recurrence) may be something other\nthan a proper date/time to indicate that the event is additional to the normal\nsequence; a convention that retains the formatting appearance is\nXXXXXXXXTXXXXXX.\n\nFurthermore, it is useful to record the next regular recurrence (as then the\ndisplayed date may be for a rescheduled event so cannot be used for calculating\nthe regular sequence). This is specified by RECURRENCE and a time or date in\nthe same format. calendaradd adds such an indication when it encounters a re‐\ncurring event that does not include one, based on the headline date/time.\n\nIf calendaradd is used to update occurrences the UID keyword described there\nshould be present in both the existing entry and the added occurrence in order\nto identify recurring event sequences.\n\nFor example,\n\nThu May 6, 2010 11:00 Informal chat RPT 1 week\n# RECURRENCE 20100506T110000\n# OCCURRENCE 20100513T110000 20100513T120000\n# OCCURRENCE 20100520T110000 CANCELLED\n\nThe event that occurs at 11:00 on 13th May 2010 is rescheduled an hour later.\nThe event that occurs a week later is cancelled. The occurrences are given on\na continuation line starting with a # character so will not usually be dis‐\nplayed as part of the event. As elsewhere, no account of time zones is taken\nwith the times. After the next event occurs the headline date/time will be `Thu\nMay 13, 2010 12:00' while the RECURRENCE date/time will be `20100513T110000'\n(note that cancelled and moved events are not taken account of in the RECUR‐‐\nRENCE, which records what the next regular recurrence is, but they are ac‐\ncounted for in the headline date/time).\n\nIt is safe to run calendar -s to reschedule an existing event (if the calendar\nfile has changed, for example), and also to have it running in multiples in‐\nstances of the shell since the calendar file is locked when in use.\n\nBy default, expired events are moved to the \"done\" file; see the -d option.\nUse -D to prevent this.\n\n-S showprog\nExplicitly specify a programme to be used for showing events instead of the\nvalue of the show-prog style or the default calendarshow.\n\n-v Verbose: show more information about stages of processing. This is useful for\nconfirming that the function has successfully parsed the dates in the calendar\nfile.\n\ncalendaradd [ -BL ] event ...\nAdds a single event to the calendar in the appropriate location. The event can con‐\ntain multiple lines, as described in the section Calendar File Format above. Using\nthis function ensures that the calendar file is sorted in date and time order. It\nalso makes special arrangements for locking the file while it is altered. The old\ncalendar is left in a file with the suffix .old.\n\nThe option -B indicates that backing up the calendar file will be handled by the\ncaller and should not be performed by calendaradd. The option -L indicates that cal‐‐\nendaradd does not need to lock the calendar file as it is already locked. These op‐\ntions will not usually be needed by users.\n\nIf the style reformat-date is true, the date and time of the new entry will be rewrit‐\nten into the standard date format: see the descriptions of this style and the style\ndate-format.\n\nThe function can use a unique identifier stored with each event to ensure that updates\nto existing events are treated correctly. The entry should contain the word UID, fol‐\nlowed by whitespace, followed by a word consisting entirely of hexadecimal digits of\narbitrary length (all digits are significant, including leading zeroes). As the UID\nis not directly useful to the user, it is convenient to hide it on an indented contin‐\nuation line starting with a #, for example:\n\nAug 31, 2007 09:30 Celebrate the end of the holidays\n# UID 045B78A0\n\nThe second line will not be shown by the calendar function.\n\nIt is possible to specify the RPT keyword followed by CANCELLED instead of a relative\ntime. This causes any matched event or series of events to be cancelled (the original\nevent does not have to be marked as recurring in order to be cancelled by this\nmethod). A UID is required in order to match an existing event in the calendar.\n\ncalendaradd will attempt to manage recurrences and occurrences of repeating events as\ndescribed for event scheduling by calendar -s above. To reschedule or cancel a single\nevent calendaradd should be called with an entry that includes the correct UID but\ndoes not include the RPT keyword as this is taken to mean the entry applies to a se‐\nries of repeating events and hence replaces all existing information. Each resched‐\nuled or cancelled occurrence must have an OCCURRENCE keyword in the entry passed to\ncalendaradd which will be merged into the calendar file. Any existing reference to\nthe occurrence is replaced. An occurrence that does not refer to a valid existing\nevent is added as a one-off occurrence to the same calendar entry.\n\ncalendaredit\nThis calls the user's editor to edit the calendar file. If there are arguments, they\nare taken as the editor to use (the file name is appended to the commands); otherwise,\nthe editor is given by the variable VISUAL, if set, else the variable EDITOR.\n\nIf the calendar scheduler was running, then after editing the file calendar -s is\ncalled to update it.\n\nThis function locks out the calendar system during the edit. Hence it should be used\nto edit the calendar file if there is any possibility of a calendar event occurring\nmeanwhile. Note this can lead to another shell with calendar functions enabled hang‐\ning waiting for a lock, so it is necessary to quit the editor as soon as possible.\n\ncalendarparse calendar-entry\nThis is the internal function that analyses the parts of a calendar entry, which is\npassed as the only argument. The function returns status 1 if the argument could not\nbe parsed as a calendar entry and status 2 if the wrong number of arguments were\npassed; it also sets the parameter reply to an empty associative array. Otherwise, it\nreturns status 0 and sets elements of the associative array reply as follows:\n\ntime The time as a string of digits in the same units as $EPOCHSECONDS\nschedtime\nThe regularly scheduled time. This may differ from the actual event time time\nif this is a recurring event and the next occurrence has been rescheduled.\nThen time gives the actual time and schedtime the time of the regular recur‐\nrence before modification.\ntext1 The text from the line not including the date and time of the event, but in‐\ncluding any WARN or RPT keywords and values.\nwarntime\nAny warning time given by the WARN keyword as a string of digits containing the\ntime at which to warn in the same units as $EPOCHSECONDS. (Note this is an ab‐\nsolute time, not the relative time passed down.) Not set no WARN keyword and\nvalue were matched.\nwarnstr\nThe raw string matched after the WARN keyword, else unset.\nrpttime\nAny recurrence time given by the RPT keyword as a string of digits containing\nthe time of the recurrence in the same units as $EPOCHSECONDS. (Note this is\nan absolute time.) Not set if no RPT keyword and value were matched.\nschedrpttime\nThe next regularly scheduled occurrence of a recurring event before modifica‐\ntion. This may differ from rpttime, which is the actual time of the event that\nmay have been rescheduled from the regular time.\nrptstr The raw string matched after the RPT keyword, else unset.\ntext2 The text from the line after removal of the date and any keywords and values.\n\ncalendarshowdate [ -r ] [ -f fmt ] date-spec ...\nThe given date-spec is interpreted and the corresponding date and time printed. If\nthe initial date-spec begins with a + or - it is treated as relative to the current\ntime; date-specs after the first are treated as relative to the date calculated so far\nand a leading + is optional in that case. This allows one to use the system as a date\ncalculator. For example, calendarshowdate '+1 month, 1st Friday' shows the date of\nthe first Friday of next month.\n\nWith the option -r nothing is printed but the value of the date and time in seconds\nsince the epoch is stored in the parameter REPLY.\n\nWith the option -f fmt the given date/time conversion format is passed to strftime;\nsee notes on the date-format style below.\n\nIn order to avoid ambiguity with negative relative date specifications, options must\noccur in separate words; in other words, -r and -f should not be combined in the same\nword.\n\ncalendarsort\nSorts the calendar file into date and time order. The old calendar is left in a\nfile with the suffix .old.\n" }, { "name": "Glob qualifiers", "content": "age The function age can be autoloaded and use separately from the calendar system, al‐\nthough it uses the function calendarscandate for date formatting. It requires the\nzsh/stat builtin, but uses only the builtin zstat.\n\nage selects files having a given modification time for use as a glob qualifier. The\nformat of the date is the same as that understood by the calendar system, described in\nthe section FILE AND DATE FORMATS above.\n\nThe function can take one or two arguments, which can be supplied either directly as\ncommand or arguments, or separately as shell parameters.\n\nprint *(e:age 2006/10/04 2006/10/09:)\n\nThe example above matches all files modified between the start of those dates. The\nsecond argument may alternatively be a relative time introduced by a +:\n\nprint *(e:age 2006/10/04 +5d:)\n\nThe example above is equivalent to the previous example.\n\nIn addition to the special use of days of the week, today and yesterday, times with no\ndate may be specified; these apply to today. Obviously such uses become problematic\naround midnight.\n\nprint *(e-age 12:00 13:30-)\n\nThe example above shows files modified between 12:00 and 13:00 today.\n\nprint *(e:age 2006/10/04:)\n\nThe example above matches all files modified on that date. If the second argument is\nomitted it is taken to be exactly 24 hours after the first argument (even if the first\nargument contains a time).\n\nprint *(e-age 2006/10/04:10:15 2006/10/04:10:45-)\n\nThe example above supplies times. Note that whitespace within the time and date spec‐\nification must be quoted to ensure age receives the correct arguments, hence the use\nof the additional colon to separate the date and time.\n\nAGEREF=2006/10/04:10:15\nAGEREF2=2006/10/04:10:45\nprint *(+age)\n\nThis shows the same example before using another form of argument passing. The dates\nand times in the parameters AGEREF and AGEREF2 stay in effect until unset, but will be\noverridden if any argument is passed as an explicit argument to age. Any explicit ar‐\ngument causes both parameters to be ignored.\n\nInstead of an explicit date and time, it's possible to use the modification time of a\nfile as the date and time for either argument by introducing the file name with a\ncolon:\n\nprint *(e-age :file1-)\n\nmatches all files created on the same day (24 hours starting from midnight) as file1.\n\nprint *(e-age :file1 :file2-)\n\nmatches all files modified no earlier than file1 and no later than file2; precision\nhere is to the nearest second.\n" }, { "name": "after", "content": "before The functions after and before are simpler versions of age that take just one argu‐\nment. The argument is parsed similarly to an argument of age; if it is not given the\nvariable AGEREF is consulted. As the names of the functions suggest, a file matches\nif its modification time is after or before the time and date specified. If a time\nonly is given the date is today.\n\nThe two following examples are therefore equivalent:\nprint *(e-after 12:00-)\nprint *(e-after today:12:00-)\n" } ] }, "STYLES": { "content": "The zsh style mechanism using the zstyle command is describe in zshmodules(1). This is the\nsame mechanism used in the completion system.\n\nThe styles below are all examined in the context :datetime:function:, for example :date‐‐\ntime:calendar:.\n", "subsections": [ { "name": "calendar-file", "content": "The location of the main calendar. The default is ~/calendar.\n" }, { "name": "date-format", "content": "A strftime format string (see strftime(3)) with the zsh extensions providing various\nnumbers with no leading zero or space if the number is a single digit as described for\nthe %D{string} prompt format in the section EXPANSION OF PROMPT SEQUENCES in zsh‐\nmisc(1).\n\nThis is used for outputting dates in calendar, both to support the -v option and when\nadding recurring events back to the calendar file, and in calendarshowdate as the fi‐\nnal output format.\n\nIf the style is not set, the default used is similar the standard system format as\noutput by the date command (also known as `ctime format'): `%a %b %d %H:%M:%S %Z %Y'.\n" }, { "name": "done-file", "content": "The location of the file to which events which have passed are appended. The default\nis the calendar file location with the suffix .done. The style may be set to an empty\nstring in which case a \"done\" file will not be maintained.\n" }, { "name": "reformat-date", "content": "Boolean, used by calendaradd. If it is true, the date and time of new entries added\nto the calendar will be reformatted to the format given by the style date-format or\nits default. Only the date and time of the event itself is reformatted; any sub‐\nsidiary dates and times such as those associated with repeat and warning times are\nleft alone.\n" }, { "name": "show-prog", "content": "The programme run by calendar for showing events. It will be passed the start time\nand stop time of the events requested in seconds since the epoch followed by the event\ntext. Note that calendar -s uses a start time and stop time equal to one another to\nindicate alerts for specific events.\n\nThe default is the function calendarshow.\n" }, { "name": "warn-time", "content": "The time before an event at which a warning will be displayed, if the first line of\nthe event does not include the text EVENT reltime. The default is 5 minutes.\n" } ] }, "BUGS": { "content": "As the system is based entirely on shell functions (with a little support from the zsh/date‐‐\ntime module) the mechanisms used are not as robust as those provided by a dedicated calendar\nutility. Consequently the user should not rely on the shell for vital alerts.\n\nThere is no calendardelete function.\n\nThere is no localization support for dates and times, nor any support for the use of time\nzones.\n\nRelative periods of months and years do not take into account the variable number of days.\n\nThe calendarshow function is currently hardwired to use xmessage for displaying alerts on X\nWindow System displays. This should be configurable and ideally integrate better with the\ndesktop.\n\ncalendarlockfiles hangs the shell while waiting for a lock on a file. If called from a\nscheduled task, it should instead reschedule the event that caused it.\n\n\n\nZSHTCPSYS(1) General Commands Manual ZSHTCPSYS(1)\n\n\n", "subsections": [] }, "TCP USER FUNCTIONS": { "content": "", "subsections": [ { "name": "Basic I/O", "content": "tcpopen [ -qz ] host port [ sess ]\ntcpopen [ -qz ] [ -s sess | -l sess[,...] ] ...\ntcpopen [ -qz ] [ -a fd | -f fd ] [ sess ]\nOpen a new session. In the first and simplest form, open a TCP connection to host\nhost at port port; numeric and symbolic forms are understood for both.\n\nIf sess is given, this becomes the name of the session which can be used to refer to\nmultiple different TCP connections. If sess is not given, the function will invent a\nnumeric name value (note this is not the same as the file descriptor to which the ses‐\nsion is attached). It is recommended that session names not include `funny' charac‐\nters, where funny characters are not well-defined but certainly do not include al‐\nphanumerics or underscores, and certainly do include whitespace.\n\nIn the second case, one or more sessions to be opened are given by name. A single\nsession name is given after -s and a comma-separated list after -l; both options may\nbe repeated as many times as necessary. A failure to open any session causes tcpopen\nto abort. The host and port are read from the file .ztcpsessions in the same direc‐\ntory as the user's zsh initialisation files, i.e. usually the home directory, but\n$ZDOTDIR if that is set. The file consists of lines each giving a session name and\nthe corresponding host and port, in that order (note the session name comes first, not\nlast), separated by whitespace.\n\nThe third form allows passive and fake TCP connections. If the option -a is used, its\nargument is a file descriptor open for listening for connections. No function\nfront-end is provided to open such a file descriptor, but a call to `ztcp -l port'\nwill create one with the file descriptor stored in the parameter $REPLY. The listen‐\ning port can be closed with `ztcp -c fd'. A call to `tcpopen -a fd' will block until\na remote TCP connection is made to port on the local machine. At this point, a ses‐\nsion is created in the usual way and is largely indistinguishable from an active con‐\nnection created with one of the first two forms.\n\nIf the option -f is used, its argument is a file descriptor which is used directly as\nif it were a TCP session. How well the remainder of the TCP function system copes\nwith this depends on what actually underlies this file descriptor. A regular file is\nlikely to be unusable; a FIFO (pipe) of some sort will work better, but note that it\nis not a good idea for two different sessions to attempt to read from the same FIFO at\nonce.\n\nIf the option -q is given with any of the three forms, tcpopen will not print infor‐\nmational messages, although it will in any case exit with an appropriate status.\n\nIf the line editor (zle) is in use, which is typically the case if the shell is inter‐\nactive, tcpopen installs a handler inside zle which will check for new data at the\nsame time as it checks for keyboard input. This is convenient as the shell consumes\nno CPU time while waiting; the test is performed by the operating system. Giving the\noption -z to any of the forms of tcpopen prevents the handler from being installed,\nso data must be read explicitly. Note, however, this is not necessary for executing\ncomplete sets of send and read commands from a function, as zle is not active at this\npoint. Generally speaking, the handler is only active when the shell is waiting for\ninput at a command prompt or in the vared builtin. The option has no effect if zle is\nnot active; `[[ -o zle]]' will test for this.\n\nThe first session to be opened becomes the current session and subsequent calls to\ntcpopen do not change it. The current session is stored in the parameter $TCPSESS;\nsee below for more detail about the parameters used by the system.\n\nThe function tcponopen, if defined, is called when a session is opened. See the de‐\nscription below.\n\ntcpclose [ -qn ] [ -a | -l sess[,...] | sess ... ]\nClose the named sessions, or the current session if none is given, or all open ses‐\nsions if -a is given. The options -l and -s are both handled for consistency with\ntcpopen, although the latter is redundant.\n\nIf the session being closed is the current one, $TCPSESS is unset, leaving no current\nsession, even if there are other sessions still open.\n\nIf the session was opened with tcpopen -f, the file descriptor is closed so long as\nit is in the range 0 to 9 accessible directly from the command line. If the option -n\nis given, no attempt will be made to close file descriptors in this case. The -n op‐\ntion is not used for genuine ztcp session; the file descriptors are always closed with\nthe session.\n\nIf the option -q is given, no informational messages will be printed.\n\n\ntcpread [ -bdq ] [ -t TO ] [ -T TO ]\n[ -a | -u fd[,...] | -l sess[,...] | -s sess ... ]\nPerform a read operation on the current session, or on a list of sessions if any are\ngiven with -u, -l or -s, or all open sessions if the option -a is given. Any of the\n-u, -l or -s options may be repeated or mixed together. The -u option specifies a\nfile descriptor directly (only those managed by this system are useful), the other two\nspecify sessions as described for tcpopen above.\n\nThe function checks for new data available on all the sessions listed. Unless the -b\noption is given, it will not block waiting for new data. Any one line of data from\nany of the available sessions will be read, stored in the parameter $TCPLINE, and\ndisplayed to standard output unless $TCPSILENT contains a non-empty string. When\nprinted to standard output the string $TCPPROMPT will be shown at the start of the\nline; the default form for this includes the name of the session being read. See be‐\nlow for more information on these parameters. In this mode, tcpread can be called\nrepeatedly until it returns status 2 which indicates all pending input from all speci‐\nfied sessions has been handled.\n\nWith the option -b, equivalent to an infinite timeout, the function will block until a\nline is available to read from one of the specified sessions. However, only a single\nline is returned.\n\nThe option -d indicates that all pending input should be drained. In this case\ntcpread may process multiple lines in the manner given above; only the last is stored\nin $TCPLINE, but the complete set is stored in the array $tcplines. This is cleared\nat the start of each call to tcpread.\n\nThe options -t and -T specify a timeout in seconds, which may be a floating point num‐\nber for increased accuracy. With -t the timeout is applied before each line read.\nWith -T, the timeout applies to the overall operation, possibly including multiple\nread operations if the option -d is present; without this option, there is no distinc‐\ntion between -t and -T.\n\nThe function does not print informational messages, but if the option -q is given, no\nerror message is printed for a non-existent session.\n\nA return status of 2 indicates a timeout or no data to read. Any other non-zero re‐\nturn status indicates some error condition.\n\nSee tcplog for how to control where data is sent by tcpread.\n\ntcpsend [ -cnq ] [ -s sess | -l sess[,...] ] data ...\ntcpsend [ -cnq ] -a data ...\nSend the supplied data strings to all the specified sessions in turn. The underlying\noperation differs little from a `print -r' to the session's file descriptor, although\nit attempts to prevent the shell from dying owing to a SIGPIPE caused by an attempt to\nwrite to a defunct session.\n\nThe option -c causes tcpsend to behave like cat. It reads lines from standard input\nuntil end of input and sends them in turn to the specified session(s) exactly as if\nthey were given as data arguments to individual tcpsend commands.\n\nThe option -n prevents tcpsend from putting a newline at the end of the data strings.\n\nThe remaining options all behave as for tcpread.\n\nThe data arguments are not further processed once they have been passed to tcpsend;\nthey are simply passed down to print -r.\n\nIf the parameter $TCPOUTPUT is a non-empty string and logging is enabled then the\ndata sent to each session will be echoed to the log file(s) with $TCPOUTPUT in front\nwhere appropriate, much in the manner of $TCPPROMPT.\n" }, { "name": "Session Management", "content": "tcpalias [ -q ] alias=sess ...\ntcpalias [ -q ] [ alias ... ]\ntcpalias -d [ -q ] alias ...\nThis function is not particularly well tested.\n\nThe first form creates an alias for a session name; alias can then be used to refer to\nthe existing session sess. As many aliases may be listed as required.\n\nThe second form lists any aliases specified, or all aliases if none.\n\nThe third form deletes all the aliases listed. The underlying sessions are not af‐\nfected.\n\nThe option -q suppresses an inconsistently chosen subset of error messages.\n\ntcplog [ -asc ] [ -n | -N ] [ logfile ]\nWith an argument logfile, all future input from tcpread will be logged to the named\nfile. Unless -a (append) is given, this file will first be truncated or created\nempty. With no arguments, show the current status of logging.\n\nWith the option -s, per-session logging is enabled. Input from tcpread is output to\nthe file logfile.sess. As the session is automatically discriminated by the filename,\nthe contents are raw (no $TCPPROMPT). The option -a applies as above. Per-session\nlogging and logging of all data in one file are not mutually exclusive.\n\nThe option -c closes all logging, both complete and per-session logs.\n\nThe options -n and -N respectively turn off or restore output of data read by tcpread\nto standard output; hence `tcplog -cn' turns off all output by tcpread.\n\nThe function is purely a convenient front end to setting the parameters $TCPLOG,\n$TCPLOGSESS, $TCPSILENT, which are described below.\n\ntcprename old new\nRename session old to session new. The old name becomes invalid.\n\ntcpsess [ sess [ command [ arg ... ] ] ]\nWith no arguments, list all the open sessions and associated file descriptors. The\ncurrent session is marked with a star. For use in functions, direct access to the pa‐\nrameters $tcpbyname, $tcpbyfd and $TCPSESS is probably more convenient; see be‐\nlow.\n\nWith a sess argument, set the current session to sess. This is equivalent to changing\n$TCPSESS directly.\n\nWith additional arguments, temporarily set the current session while executing `com‐\nmand arg ...'. command is re-evaluated so as to expand aliases etc., but the remain‐\ning args are passed through as that appear to tcpsess. The original session is re‐\nstored when tcpsess exits.\n" }, { "name": "Advanced I/O", "content": "tcpcommand send-option ... send-argument ...\nThis is a convenient front-end to tcpsend. All arguments are passed to tcpsend,\nthen the function pauses waiting for data. While data is arriving at least every\n$TCPTIMEOUT (default 0.3) seconds, data is handled and printed out according to the\ncurrent settings. Status 0 is always returned.\n\nThis is generally only useful for interactive use, to prevent the display becoming\nfragmented by output returned from the connection. Within a programme or function it\nis generally better to handle reading data by a more explicit method.\n\n\ntcpexpect [ -q ] [ -p var | -P var ] [ -t TO | -T TO ]\n[ -a | -s sess | -l sess[,...] ] pattern ...\nWait for input matching any of the given patterns from any of the specified sessions.\nInput is ignored until an input line matches one of the given patterns; at this point\nstatus zero is returned, the matching line is stored in $TCPLINE, and the full set of\nlines read during the call to tcpexpect is stored in the array $tcpexpectlines.\n\nSessions are specified in the same way as tcpread: the default is to use the current\nsession, otherwise the sessions specified by -a, -s, or -l are used.\n\nEach pattern is a standard zsh extended-globbing pattern; note that it needs to be\nquoted to avoid it being expanded immediately by filename generation. It must match\nthe full line, so to match a substring there must be a `*' at the start and end. The\nline matched against includes the $TCPPROMPT added by tcpread. It is possible to\ninclude the globbing flags `#b' or `#m' in the patterns to make backreferences avail‐\nable in the parameters $MATCH, $match, etc., as described in the base zsh documenta‐\ntion on pattern matching.\n\nUnlike tcpread, the default behaviour of tcpexpect is to block indefinitely until\nthe required input is found. This can be modified by specifying a timeout with -t or\n-T; these function as in tcpread, specifying a per-read or overall timeout, respec‐\ntively, in seconds, as an integer or floating-point number. As tcpread, the function\nreturns status 2 if a timeout occurs.\n\nThe function returns as soon as any one of the patterns given match. If the caller\nneeds to know which of the patterns matched, the option -p var can be used; on return,\n$var is set to the number of the pattern using ordinary zsh indexing, i.e. the first\nis 1, and so on. Note the absence of a `$' in front of var. To avoid clashes, the\nparameter cannot begin with `expect'. The index -1 is used if there is a timeout and\n0 if there is no match.\n\nThe option -P var works similarly to -p, but instead of numerical indexes the regular\narguments must begin with a prefix followed by a colon: that prefix is then used as a\ntag to which var is set when the argument matches. The tag timeout is used if there\nis a timeout and the empty string if there is no match. Note it is acceptable for\ndifferent arguments to start with the same prefix if the matches do not need to be\ndistinguished.\n\nThe option -q is passed directly down to tcpread.\n\nAs all input is done via tcpread, all the usual rules about output of lines read ap‐\nply. One exception is that the parameter $tcplines will only reflect the line actu‐\nally matched by tcpexpect; use $tcpexpectlines for the full set of lines read dur‐\ning the function call.\n\ntcpproxy\nThis is a simple-minded function to accept a TCP connection and execute a command with\nI/O redirected to the connection. Extreme caution should be taken as there is no se‐\ncurity whatsoever and this can leave your computer open to the world. Ideally, it\nshould only be used behind a firewall.\n\nThe first argument is a TCP port on which the function will listen.\n\nThe remaining arguments give a command and its arguments to execute with standard in‐\nput, standard output and standard error redirected to the file descriptor on which the\nTCP session has been accepted. If no command is given, a new zsh is started. This\ngives everyone on your network direct access to your account, which in many cases will\nbe a bad thing.\n\nThe command is run in the background, so tcpproxy can then accept new connections.\nIt continues to accept new connections until interrupted.\n\ntcpspam [ -ertv ] [ -a | -s sess | -l sess[,...] ] cmd [ arg ... ]\nExecute `cmd [ arg ... ]' for each session in turn. Note this executes the command\nand arguments; it does not send the command line as data unless the -t (transmit) op‐\ntion is given.\n\nThe sessions may be selected explicitly with the standard -a, -s or -l options, or may\nbe chosen implicitly. If none of the three options is given the rules are: first, if\nthe array $tcpspamlist is set, this is taken as the list of sessions, otherwise all\nsessions are taken. Second, any sessions given in the array $tcpnospamlist are re‐\nmoved from the list of sessions.\n\nNormally, any sessions added by the `-a' flag or when all sessions are chosen implic‐\nitly are spammed in alphabetic order; sessions given by the $tcpspamlist array or on\nthe command line are spammed in the order given. The -r flag reverses the order how‐\never it was arrived it.\n\nThe -v flag specifies that a $TCPPROMPT will be output before each session. This is\noutput after any modification to TCPSESS by the user-defined tcponspam function de‐\nscribed below. (Obviously that function is able to generate its own output.)\n\nIf the option -e is present, the line given as `cmd [ arg ... ]' is executed using\neval, otherwise it is executed without any further processing.\n\ntcptalk\nThis is a fairly simple-minded attempt to force input to the line editor to go\nstraight to the default TCPSESS.\n\nAn escape string, $TCPTALKESCAPE, default `:', is used to allow access to normal\nshell operation. If it is on its own at the start of the line, or followed only by\nwhitespace, the line editor returns to normal operation. Otherwise, the string and\nany following whitespace are skipped and the remainder of the line executed as shell\ninput without any change of the line editor's operating mode.\n\nThe current implementation is somewhat deficient in terms of use of the command his‐\ntory. For this reason, many users will prefer to use some form of alternative ap‐\nproach for sending data easily to the current session. One simple approach is to\nalias some special character (such as `%') to `tcpcommand --'.\n\ntcpwait\nThe sole argument is an integer or floating point number which gives the seconds to\ndelay. The shell will do nothing for that period except wait for input on all TCP\nsessions by calling tcpread -a. This is similar to the interactive behaviour at the\ncommand prompt when zle handlers are installed.\n" }, { "name": "`One-shot' file transfer", "content": "tcppoint port\ntcpshoot host port\nThis pair of functions provide a simple way to transfer a file between two hosts\nwithin the shell. Note, however, that bulk data transfer is currently done using cat.\ntcppoint reads any data arriving at port and sends it to standard output; tcpshoot\nconnects to port on host and sends its standard input. Any unused port may be used;\nthe standard mechanism for picking a port is to think of a random four-digit number\nabove 1024 until one works.\n\nTo transfer a file from host woodcock to host springes, on springes:\n\ntcppoint 8091 >outputfile\n\nand on woodcock:\n\ntcpshoot springes 8091 zsh.report\n\nYou should check the zsh.report file for any sensitive information such as passwords and\ndelete them by hand before sending the script to the developers. Also, as the output can be\nvoluminous, it's best to wait for the developers to ask for this information before sending\nit.\n\nYou can also use reporter to dump only a subset of the shell state. This is sometimes useful\nfor creating startup files for the first time. Most of the output from reporter is far more\ndetailed than usually is necessary for a startup file, but the aliases, options, and zstyles\nstates may be useful because they include only changes from the defaults. The bindings state\nmay be useful if you have created any of your own keymaps, because reporter arranges to dump\nthe keymap creation commands as well as the bindings for every keymap.\n\nAs is usual with automated tools, if you create a startup file with reporter, you should edit\nthe results to remove unnecessary commands. Note that if you're using the new completion\nsystem, you should not dump 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 shell state. The state\narguments 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 covered by functions and\nzstyles.\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 for any environment\nvariables.\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 prefix, even a single let‐\nter; thus a is the same as aliases, z is the same as zstyles, etc.\n" }, { "name": "Manipulating Hook Functions", "content": "add-zsh-hook [ -L | -dD ] [ -Uzk ] hook function\nSeveral functions are special to the shell, as described in the section SPECIAL FUNC‐\nTIONS, see zshmisc(1), in that they are automatically called at specific points during\nshell execution. Each has an associated array consisting of names of functions to be\ncalled at the same point; these are so-called `hook functions'. The shell function\nadd-zsh-hook provides a simple way of adding or removing functions from the array.\n\nhook is one of chpwd, periodic, precmd, preexec, zshaddhistory, zshexit, or zshdirec‐‐\ntoryname, the special functions in question. Note that zshdirectoryname is called\nin a different way from the other functions, but may still be manipulated as a hook.\n\nfunction is name of an ordinary shell function. If no options are given this will be\nadded to the array of functions to be executed in the given context. Functions are\ninvoked in the order they were added.\n\nIf the option -L is given, the current values for the hook arrays are listed with\ntypeset.\n\nIf the option -d is given, the function is removed from the array of functions to be\nexecuted.\n\nIf the option -D is given, the function is treated as a pattern and any matching names\nof functions are removed from the array of functions to be executed.\n\nThe options -U, -z and -k are passed as arguments to autoload for function. For func‐\ntions contributed with zsh, the options -Uz are appropriate.\n\nadd-zle-hook-widget [ -L | -dD ] [ -Uzk ] hook widgetname\nSeveral widget names are special to the line editor, as described in the section Spe‐\ncial Widgets, see zshzle(1), in that they are automatically called at specific points\nduring editing. Unlike function hooks, these do not use a predefined array of other\nnames to call at the same point; the shell function add-zle-hook-widget maintains a\nsimilar array and arranges for the special widget to invoke those additional widgets.\n\nhook is one of isearch-exit, isearch-update, line-pre-redraw, line-init, line-finish,\nhistory-line-set, or keymap-select, corresponding to each of the special widgets\nzle-isearch-exit, etc. The special widget names are also accepted as the hook argu‐\nment.\n\nwidgetname is the name of a ZLE widget. If no options are given this is added to the\narray of widgets to be invoked in the given hook context. Widgets are invoked in the\norder they were added, with\nzle widgetname -Nw -- \"$@\"\n\nNote that this means that the `WIDGET' special parameter tracks the widgetname when\nthe widget function is called, rather than tracking the name of the corresponding spe‐\ncial hook widget.\n\nIf the option -d is given, the widgetname is removed from the array of widgets to be\nexecuted.\n\nIf the option -D is given, the widgetname is treated as a pattern and any matching\nnames of widgets are removed from the array.\n\nIf widgetname does not name an existing widget when added to the array, it is assumed\nthat a shell function also named widgetname is meant to provide the implementation of\nthe widget. This name is therefore marked for autoloading, and the options -U, -z and\n-k are passed as arguments to autoload as with add-zsh-hook. The widget is also cre‐\nated with `zle -N widgetname' to cause the corresponding function to be loaded the\nfirst time the hook is called.\n\nThe arrays of widgetname are currently maintained in zstyle contexts, one for each\nhook context, with a style of `widgets'. If the -L option is given, this set of\nstyles is listed with `zstyle -L'. This implementation may change, and the special\nwidgets that refer to the styles are created only if add-zle-hook-widget is called to\nadd at least one widget, so if this function is used for any hooks, then all hooks\nshould be managed only via this function.\n" } ] }, "REMEMBERING RECENT DIRECTORIES": { "content": "The function cdr allows you to change the working directory to a previous working directory\nfrom a list maintained automatically. It is similar in concept to the directory stack con‐\ntrolled by the pushd, popd and dirs builtins, but is more configurable, and as it stores all\nentries in files it is maintained across sessions and (by default) between terminal emulators\nin the current session. Duplicates are automatically removed, so that the list reflects the\nsingle most recent use of each directory.\n\nNote that the pushd directory stack is not actually modified or used by cdr unless you con‐\nfigure it to do so as described in the configuration section below.\n", "subsections": [ { "name": "Installation", "content": "The system works by means of a hook function that is called every time the directory changes.\nTo install the system, autoload the required functions and use the add-zsh-hook function de‐\nscribed 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 command you use, the direc‐\ntory to which you change will be remembered in most-recent-first order.\n" }, { "name": "Use", "content": "All direct user interaction is via the cdr function.\n\nThe argument to cdr is a number N corresponding to the Nth most recently changed-to direc‐\ntory. 1 is the immediately preceding directory; the current directory is remembered but is\nnot offered as a destination. Note that if you have multiple windows open 1 may refer to a\ndirectory changed to in another window; you can avoid this by having per-terminal files for\nstoring directory as described for the recent-dirs-file style below.\n\nIf you set the recent-dirs-default style described below cdr will behave the same as cd if\ngiven a non-numeric argument, or more than one argument. The recent directory list is up‐\ndated just the same however you change directory.\n\nIf the argument is omitted, 1 is assumed. This is similar to pushd's behaviour of swapping\nthe two most recent directories on the stack.\n\nCompletion for the argument to cdr is available if compinit has been run; menu selection is\nrecommended, using:\n\nzstyle ':completion:*:*:cdr:*:*' menu selection\n\nto allow you to cycle through recent directories; the order is preserved, so the first choice\nis the most recent directory before the current one. The verbose style is also recommended\nto ensure the directory is shown; this style is on by default so no action is required unless\nyou have changed it.\n" }, { "name": "Options", "content": "The behaviour of cdr may be modified by the following options.\n" }, { "name": "-l", "content": "substitution reapplied), one per line. The directories here are not quoted (this\nwould only be an issue if a directory name contained a newline). This is used by the\ncompletion system.\n", "flag": "-l" }, { "name": "-r", "content": "directory is not changed.\n", "flag": "-r" }, { "name": "-e", "content": "any extent you like; no sanity checking is performed. Completion is available. No\nquoting is necessary (except for newlines, where I have in any case no sympathy); di‐\nrectories are in unabbreviated from and contain an absolute path, i.e. they start with\n/. Usually the first entry should be left as the current directory.\n", "flag": "-e" }, { "name": "-p", "content": "Prunes any items in the directory list that match the given extended glob pattern; the\npattern needs to be quoted from immediate expansion on the command line. The pattern\nis matched against each completely expanded file name in the list; the full string\nmust match, so wildcards at the end (e.g. '*removeme*') are needed to remove entries\nwith a given substring.\n\nIf output is to a terminal, then the function will print the new list after pruning\nand prompt for confirmation by the user. This output and confirmation step can be\nskipped by using -P instead of -p.\n", "flag": "-p" }, { "name": "Configuration", "content": "Configuration is by means of the styles mechanism that should be familiar from completion; if\nnot, see the description of the zstyle command in see zshmodules(1). The context for setting\nstyles should be ':chpwd:*' in case the meaning of the context is extended in future, for ex‐\nample:\n\nzstyle ':chpwd:*' recent-dirs-max 0\n\nsets the value of the recent-dirs-max style to 0. In practice the style name is specific\nenough that a context of '*' should be fine.\n\nAn exception is recent-dirs-insert, which is used exclusively by the completion system and so\nhas the usual completion system context (':completion:*' if nothing more specific is needed),\nthough again '*' should be fine in practice.\n" }, { "name": "recent-dirs-default", "content": "If true, and the command is expecting a recent directory index, and either there is\nmore than one argument or the argument is not an integer, then fall through to \"cd\".\nThis allows the lazy to use only one command for directory changing. Completion\nrecognises this, too; see recent-dirs-insert for how to control completion when this\noption is in use.\n" }, { "name": "recent-dirs-file", "content": "The file where the list of directories is saved. The default is ${ZDOT‐‐\nDIR:-$HOME}/.chpwd-recent-dirs, i.e. this is in your home directory unless you have\nset the variable ZDOTDIR to point somewhere else. Directory names are saved in $'...'\nquoted form, so each line in the file can be supplied directly to the shell as an ar‐\ngument.\n\nThe value of this style may be an array. In this case, the first file in the list\nwill always be used for saving directories while any other files are left untouched.\nWhen reading the recent directory list, if there are fewer than the maximum number of\nentries in the first file, the contents of later files in the array will be appended\nwith duplicates removed from the list shown. The contents of the two files are not\nsorted together, i.e. all the entries in the first file are shown first. The special\nvalue + can appear in the list to indicate the default file should be read at that\npoint. This allows effects like the following:\n\nzstyle ':chpwd:*' recent-dirs-file \\\n~/.chpwd-recent-dirs-${TTY##*/} +\n\nRecent directories are read from a file numbered according to the terminal. If there\nare insufficient entries the list is supplemented from the default file.\n\nIt is possible to use zstyle -e to make the directory configurable 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 directory under it,\nthen use a special file for saving recent directories, else use the default.\n" }, { "name": "recent-dirs-insert", "content": "Used by completion. If recent-dirs-default is true, then setting this to true causes\nthe actual directory, rather than its index, to be inserted on the command line; this\nhas the same effect as using the corresponding index, but makes the history clearer\nand the line easier to edit. With this setting, if part of an argument was already\ntyped, normal directory completion rather than recent directory completion is done;\nthis is because recent directory completion is expected to be done by cycling through\nentries menu fashion.\n\nIf the value of the style is always, then only recent directories will be completed;\nin that case, use the cd command when you want to complete other directories.\n\nIf the value is fallback, recent directories will be tried first, then normal direc‐\ntory completion is performed if recent directory completion failed to find a match.\n\nFinally, if the value is both then both sets of completions are presented; the usual\ntag mechanism can be used to distinguish results, with recent directories tagged as\nrecent-dirs. Note that the recent directories inserted are abbreviated with directory\nnames where appropriate.\n" }, { "name": "recent-dirs-max", "content": "The maximum number of directories to save to the file. If this is zero or negative\nthere is no maximum. The default is 20. Note this includes the current directory,\nwhich isn't offered, so the highest number of directories you will be offered is one\nless than the maximum.\n" }, { "name": "recent-dirs-prune", "content": "This style is an array determining what directories should (or should not) be added to\nthe recent list. Elements of the array can include:\n\nparent Prune parents (more accurately, ancestors) from the recent list. If present,\nchanging directly down by any number of directories causes the current direc‐\ntory to be overwritten. For example, changing from ~pws to ~pws/some/other/dir\ncauses ~pws not to be left on the recent directory stack. This only applies to\ndirect changes to descendant directories; earlier directories on the list are\nnot pruned. For example, changing from ~pws/yet/another to ~pws/some/other/dir\ndoes not cause ~pws to be pruned.\n\npattern:pattern\nGives a zsh pattern for directories that should not be added to the recent list\n(if not already there). This element can be repeated to add different pat‐\nterns. For example, 'pattern:/tmp(|/*)' stops /tmp or its descendants from be‐\ning added. The EXTENDEDGLOB option is always turned on for these patterns.\n" }, { "name": "recent-dirs-pushd", "content": "If set to true, cdr will use pushd instead of cd to change the directory, so the di‐\nrectory is saved on the directory stack. As the directory stack is completely sepa‐\nrate from the list of files saved by the mechanism used in this file there is no obvi‐\nous reason to do this.\n" }, { "name": "Use with dynamic directory naming", "content": "It is possible to refer to recent directories using the dynamic directory name syntax by us‐\ning the supplied function zshdirectorynamecdr a 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 than $PWD, and so on.\nCompletion after ~[... also works.\n" }, { "name": "Details of directory handling", "content": "This section is for the curious or confused; most users will not need to know this informa‐\ntion.\n\nRecent directories are saved to a file immediately and hence are preserved across sessions.\nNote currently no file locking is applied: the list is updated immediately on interactive\ncommands and nowhere else (unlike history), and it is assumed you are only going to change\ndirectory in one window at once. This is not safe on shared accounts, but in any case the\nsystem has limited utility when someone else is changing to a different set of directories\nbehind your back.\n\nTo make this a little safer, only directory changes instituted from the command line, either\ndirectly or indirectly through shell function calls (but not through subshells, evals, traps,\ncompletion functions and 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 at the command line.\nSee the contents of the function chpwdrecentdirs for more details.\n" } ] }, "ABBREVIATED DYNAMIC REFERENCES TO DIRECTORIES": { "content": "The dynamic directory naming system is described in the subsection Dynamic named directories\nof the section Filename Expansion in expn(1). In this, a reference to ~[...] is expanded by\na function found by the hooks mechanism.\n\nThe contributed function zshdirectorynamegeneric provides a system allowing the user to\nrefer to directories with only a limited amount of new code. It supports all three of the\nstandard interfaces for directory naming: converting from a name to a directory, converting\nin the reverse direction to find a short name, and completion of names.\n\nThe main feature of this function is a path-like syntax, combining abbreviations at multiple\nlevels separated by \":\". As an example, ~[g:p:s] might specify:\ng The top level directory for your git area. This first component has to match, or the\nfunction will return indicating another directory 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 collapse references to long\nhierarchies to a very compact form, particularly if the hierarchies are similar across\ndifferent areas of the disk.\n\nName components may be completed: if a description is shown at the top of the list of comple‐\ntions, it includes the path to which previous components expand, while the description for an\nindividual completion shows the path segment it would add. No additional configuration is\nneeded for this as the completion system is aware of the dynamic directory name mechanism.\n", "subsections": [ { "name": "Usage", "content": "To use the function, first define a wrapper function for your specific case. We'll assume\nit's to be autoloaded. This can have any name but we'll refer to it as zdnmywrapper. This\nwrapper function will define various variables and then call this function with the same ar‐\nguments that 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" }, { "name": "Configuration", "content": "The wrapper function should define a local associative array zdntop. Alternatively, this\ncan be set with a style called mapping. The context for the style is :zdn:wrapper-name where\nwrapper-name is the function calling zshdirectorynamegeneric; for example:\n\nzstyle :zdn:zdnmywrapper: mapping zdnmywrappertop\n\nThe keys in this associative array correspond to the first component of the name. The values\nare matching directories. They may have an optional suffix with a slash followed by a colon\nand the name of a variable 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 path for a drive. There\nis otherwise no syntax for escaping this, so path components whose names start with a colon\nare not supported.) A special component :default: specifies a variable in the form /:var\n(the path section is ignored and so is usually empty) that will be used for the next compo‐\nnent if no variable is given for the path. Variables referred to within zdntop have the\nsame format as zdntop itself, but contain 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 ~[ga:...] or\n~[gs:...]. Later path components are optional; in that case ~[g] expands to ~/git, and so\non. gs expands to /scratch/$USER/git and uses the associative array second2 to match the\nsecond component; g and ga use the associative array second1 to match the second component.\n\nWhen expanding a name to a directory, if the first component is not g or ga or gs, it is not\nan error; the function simply returns 1 so that a later hook function can be tried. However,\nmatching the first component commits the function, so if a later component does not match, an\nerror is printed (though this still does not stop later hooks from being executed).\n\nFor components after the first, a relative path is expected, but note that multiple levels\nmay 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, so ~[g:p] becomes\n~/git/myproject. The slash between is added automatically (it's not possible to have a later\ncomponent modify the name of a directory already matched). Only os specifies a variable for\na third component, and there's no :default:, so it's an error to use a name like ~[g:p:x] or\n~[ga:s:y] because there's nowhere to look up the x or y.\n\nThe associative arrays need to be visible within this function; the generic function there‐\nfore uses internal variable names beginning zdn in order to avoid clashes. Note that the\nvariable reply needs to be passed back to the shell, so should not be local in the calling\nfunction.\n\nThe function does not test whether directories assembled by component actually exist; this\nallows the system to work across automounted file systems. The error from the command trying\nto use a non-existent directory should be sufficient to indicate the problem.\n" }, { "name": "Complete example", "content": "Here is a full fictitious but usable autoloadable definition of the example function defined\nby the code above. So ~[gs:p:s] expands to /scratch/$USER/git/myscratchproject/top/srcdir\n(with $USER also expanded).\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, and set the style for\nthe context of your wrapper function to refer to this. Then your set up code would contain\nthe 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" } ] }, "GATHERING INFORMATION FROM VERSION CONTROL SYSTEMS": { "content": "In a lot of cases, it is nice to automatically retrieve information from version control sys‐\ntems (VCSs), such as subversion, CVS or git, to be able to provide it to the user; possibly\nin the user's prompt. So that you can instantly tell which branch you are currently on, for\nexample.\n\nIn order to do that, you may use the vcsinfo function.\n\nThe following VCSs are supported, showing the abbreviated name by which they are referred to\nwithin 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 (https://savan‐‐\nnah.nongnu.org/projects/quilt). See Quilt Support below for details.\n\nTo load vcsinfo:\n\nautoload -Uz vcsinfo\n\nIt can be used in any existing prompt, because it does not require any specific $psvar en‐\ntries to be available.\n", "subsections": [ { "name": "Quickstart", "content": "To get this feature working quickly (including colors), you can do the following (assuming,\nyou 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 call vcsinfo from\nyour precmd function. Once that is done you need a single quoted '${vcsinfomsg0}' in your\nprompt.\n\nTo be able to use '${vcsinfomsg0}' directly in your prompt like this, you will need to\nhave 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 code to detect systems\nyou do not use. So there is a way to disable some 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 see the backends listed\nin the disable style (or backends not in the enable style - if you used that) marked as dis‐\nabled by a hash sign. That means the detection of these systems is skipped completely. No\nwasted time there.\n" }, { "name": "Configuration", "content": "The 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, hg-hgsvn, darcs, bzr,\ncdv, mtn, svn, cvs, svk, tla, p4 or fossil. This is followed by `.quilt-quilt-mode'\nin Quilt mode (see Quilt Support for details) and by `+hook-name' while hooks are ac‐\ntive (see Hooks in vcsinfo for details).\n\nCurrently, hooks in quilt mode don't add the `.quilt-quilt-mode' information. This\nmay change in the future.\n\nuser-context\nis a freely configurable string, assignable by the user as the first argument to\nvcsinfo (see its description below).\n\nrepo-root-name\nis the name of a repository in which you want a style to match. So, if you want a set‐\nting specific to /usr/src/zsh, with that being a CVS checkout, you can set\nrepo-root-name to zsh to make it so.\n\nThere are three special values for vcs-string: The first is named -init-, that is in effect\nas long as there was no decision what VCS backend to use. The second is -preinit-; it is used\nbefore vcsinfo is run, when initializing the data exporting variables. The third special\nvalue is formats and is used by the vcsinfolastmsg for looking up its styles.\n\nThe initial value of repo-root-name is -all- and it is replaced with the actual name, as soon\nas it is known. Only use this part of the context for defining the formats, actionformats or\nbranchformat styles, as it 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:" }, { "name": "default", "content": "the one used if none is specified" }, { "name": "command", "content": "used by vcsinfolastmsg to lookup its styles\n\nYou can of course use ':vcsinfo:*' to match all VCSs in all user-contexts at once.\n\nThis is a description of all styles that are looked up.\n" }, { "name": "formats", "content": "A list of formats, used when actionformats is not used (which is most of the time).\n" }, { "name": "actionformats", "content": "A list of formats, used if there is a special action going on in your current reposi‐\ntory; like an interactive rebase or a merge conflict.\n" }, { "name": "branchformat", "content": "Some backends replace %b in the formats and actionformats styles above, not only by a\nbranch name but also by a revision number. This style lets you modify how that string\nshould look.\n" }, { "name": "nvcsformats", "content": "These \"formats\" are set when we didn't detect a version control system for the current\ndirectory or vcsinfo was disabled. This is useful if you want vcsinfo to completely\ntake over the generation of your prompt. You would do something like\nPS1='${vcsinfomsg0}' to accomplish that.\n" }, { "name": "hgrevformat", "content": "hg uses both a hash and a revision number to reference a specific changeset in a\nrepository. With this style you can format the revision string (see branchformat) to\ninclude either or both. It's only useful when get-revision is true. Note, the full\n40-character revision id is not available (except when using the use-simple option)\nbecause executing hg more than once per prompt is too slow; you may customize this be‐\nhavior using hooks.\n" }, { "name": "max-exports", "content": "Defines the maximum number of vcsinfomsg* variables vcsinfo will set.\n\nenable A list of backends you want to use. Checked in the -init- context. If this list con‐\ntains an item called NONE no backend is used at all and vcsinfo will do nothing. If\nthis list contains ALL, vcsinfo will use all known backends. Only with ALL in enable\nwill the disable style have any effect. ALL and NONE are case insensitive.\n" }, { "name": "disable", "content": "A list of VCSs you don't want vcsinfo to test for repositories (checked in the -init-\ncontext, too). Only used if enable contains ALL.\n" }, { "name": "disable-patterns", "content": "A list of patterns that are checked against $PWD. If a pattern matches, vcsinfo will\nbe disabled. This style is checked in the :vcsinfo:-init-:*:-all- context.\n\nSay, ~/.zsh is a directory under version control, in which you do not want vcsinfo to\nbe active, do:\nzstyle ':vcsinfo:*' disable-patterns \"${(b)HOME}/.zsh(|/*)\"\n" }, { "name": "use-quilt", "content": "If enabled, the quilt support code is active in `addon' mode. See Quilt Support for\ndetails.\n" }, { "name": "quilt-standalone", "content": "If enabled, `standalone' mode detection is attempted if no VCS is active in a given\ndirectory. See Quilt Support for details.\n" }, { "name": "quilt-patch-dir", "content": "Overwrite the value of the $QUILTPATCHES environment variable. See Quilt Support for\ndetails.\n" }, { "name": "quiltcommand", "content": "When quilt itself is called in quilt support, the value of this style is used as the\ncommand name.\n" }, { "name": "check-for-changes", "content": "If enabled, this style causes the %c and %u format escapes to show when the working\ndirectory has uncommitted changes. The strings displayed by these escapes can be con‐\ntrolled via the stagedstr and unstagedstr styles. The only backends that currently\nsupport this option are git, hg, and bzr (the latter two only support unstaged).\n\nFor this style to be evaluated with the hg backend, the get-revision style needs to be\nset and the use-simple style needs to be unset. The latter is the default; the former\nis not.\n\nWith the bzr backend, lightweight checkouts only honor this style if the use-server\nstyle is set.\n\nNote, the actions taken if this style is enabled are potentially expensive (read: they\nmay be slow, depending on how big the current repository is). Therefore, it is dis‐\nabled by default.\n" }, { "name": "check-for-staged-changes", "content": "This style is like check-for-changes, but it never checks the worktree files, only the\nmetadata in the .${vcs} dir. Therefore, this style initializes only the %c escape\n(with stagedstr) but not the %u escape. This style is faster than check-for-changes.\n\nIn the git backend, this style checks for changes in the index. Other backends do not\ncurrently implement this style.\n\nThis style is disabled by default.\n" }, { "name": "stagedstr", "content": "This string will be used in the %c escape if there are staged changes in the reposi‐\ntory.\n" }, { "name": "unstagedstr", "content": "This string will be used in the %u escape if there are unstaged changes in the reposi‐\ntory.\n" }, { "name": "command", "content": "This style causes vcsinfo to use the supplied string as the command to use as the\nVCS's binary. Note, that setting this in ':vcsinfo:*' is not a good idea.\n\nIf the value of this style is empty (which is the default), the used binary name is\nthe name of the backend in use (e.g. svn is used in an svn repository).\n\nThe repo-root-name part in the context is always the default -all- when this style is\nlooked up.\n\nFor example, this style can be used to use binaries from non-default installation di‐\nrectories. Assume, git is installed in /usr/bin but your sysadmin installed a newer\nversion in /usr/local/bin. Instead of changing the order of your $PATH parameter, you\ncan do this:\nzstyle ':vcsinfo:git:*:-all-' command /usr/local/bin/git\n" }, { "name": "use-server", "content": "This is used by the Perforce backend (p4) to decide if it should contact the Perforce\nserver to find out if a directory is managed by Perforce. This is the only reliable\nway of doing this, but runs the risk of a delay if the server name cannot be found.\nIf the server (more specifically, the host:port pair describing the server) cannot be\ncontacted, its name is put into the associative array vcsinfop4deadservers and is\nnot contacted again during the session until it is removed by hand. If you do not set\nthis style, the p4 backend is only usable if you have set the environment variable\nP4CONFIG to a file name and have corresponding files in the root directories of each\nPerforce client. See comments in the function VCSINFOdetectp4 for more detail.\n\nThe Bazaar backend (bzr) uses this to permit contacting the server about lightweight\ncheckouts, see the check-for-changes style.\n" }, { "name": "use-simple", "content": "If there are two different ways of gathering information, you can select the simpler\none by setting this style to true; the default is to use the not-that-simple code,\nwhich is potentially a 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 it will invoke the\nexternal hexdump program to parse the binary dirstate cache file; this method will not\nreturn the local revision number.\n" }, { "name": "get-revision", "content": "If set to true, vcsinfo goes the extra mile to figure out the revision of a reposi‐\ntory's work tree (currently for the git and hg backends, where this kind of informa‐\ntion is not always vital). For git, the hash value of the currently checked out commit\nis available via the %i expansion. With hg, the local revision number and the corre‐\nsponding global hash are available via %i.\n\nget-mq If set to true, the hg backend will look for a Mercurial Queue (mq) patch directory.\nInformation will be available via the `%m' replacement.\n" }, { "name": "get-bookmarks", "content": "If set to true, the hg backend will try to get a list of current bookmarks. They will\nbe available via the `%m' replacement.\n\nThe default is to generate a comma-separated list of all bookmark names that refer to\nthe currently checked out revision. If a bookmark is active, its name is suffixed an\nasterisk and placed first in the list.\n" }, { "name": "use-prompt-escapes", "content": "Determines if we assume that the assembled string from vcsinfo includes prompt es‐\ncapes. (Used by vcsinfolastmsg.)\n\ndebug Enable debugging output to track possible problems. Currently this style is only used\nby vcsinfo's hooks system.\n\nhooks A list style that defines hook-function names. See Hooks in vcsinfo below for de‐\ntails.\n" }, { "name": "patch-format", "content": "" }, { "name": "nopatch-format", "content": "This pair of styles format the patch information used by the %m expando in formats and\nactionformats for the git and hg backends. The value is subject to certain %-expan‐\nsions described below. The expanded value is made available in the global back‐‐\nendmisc array as ${backendmisc[patches]} (also if a set-patch-format hook is used).\n" }, { "name": "get-unapplied", "content": "This boolean style controls whether a backend should attempt to gather a list of unap‐\nplied patches (for example with Mercurial Queue patches).\n\nUsed by the quilt and hg backends.\n\nThe default values for these styles in all contexts are:\n" }, { "name": "formats", "content": "\" (%s)-[%b]%u%c-\"" }, { "name": "actionformats", "content": "\" (%s)-[%b|%a]%u%c-\"" }, { "name": "branchformat", "content": "\"%b:%r\" (for bzr, svn, svk and hg)" }, { "name": "nvcsformats", "content": "\"\"" }, { "name": "hgrevformat", "content": "\"%r:%h\"" }, { "name": "max-exports", "content": "2\nenable ALL" }, { "name": "disable", "content": "(empty list)" }, { "name": "disable-patterns", "content": "(empty list)" }, { "name": "check-for-changes", "content": "false" }, { "name": "check-for-staged-changes", "content": "false" }, { "name": "stagedstr", "content": "(string: \"S\")" }, { "name": "unstagedstr", "content": "(string: \"U\")" }, { "name": "command", "content": "(empty string)" }, { "name": "use-server", "content": "false" }, { "name": "use-simple", "content": "false" }, { "name": "get-revision", "content": "false\nget-mq true" }, { "name": "get-bookmarks", "content": "false" }, { "name": "use-prompt-escapes", "content": "true\ndebug false\nhooks (empty list)" }, { "name": "use-quilt", "content": "false" }, { "name": "quilt-standalone", "content": "false" }, { "name": "quilt-patch-dir", "content": "empty - use $QUILTPATCHES" }, { "name": "quiltcommand", "content": "quilt" }, { "name": "patch-format", "content": "backend dependent" }, { "name": "nopatch-format", "content": "backend dependent" }, { "name": "get-unapplied", "content": "false\n\nIn normal formats and actionformats the following replacements are done:\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 actionformats.\n%i The current revision number or identifier. For hg the hgrevformat style may be used to\ncustomize the output.\n%c The string from the stagedstr style if there are staged changes in the repository.\n%u The string from the unstagedstr style if there are unstaged changes 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/repoXY/beer/tasty, %S is\nbeer/tasty.\n%m A \"misc\" replacement. It is at the discretion of the backend to decide what this re‐\nplacement expands to.\n\nThe hg and git backends use this expando to display patch information. hg sources\npatch information from the mq extensions; git from in-progress rebase and cherry-pick\noperations and from the stgit extension. The patch-format and nopatch-format styles\ncontrol the generated string. The former is used when at least one patch from the\npatch queue has been applied, and the latter otherwise.\n\nThe hg backend displays bookmark information in this expando (in addition to mq infor‐\nmation). See the get-mq and get-bookmarks styles. Both of these styles may be en‐\nabled at the same time. If both are enabled, both resulting strings will be shown\nseparated by a semicolon (that cannot currently be customized).\n\nThe quilt `standalone' backend sets this expando to the same value as the %Q expando.\n\n%Q Quilt series information. When quilt is used (either in `addon' mode or as a `stand‐\nalone' backend), this expando is set to quilt series' patch-format string. The\nset-patch-format hook and nopatch-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 applied-string hook.\n%u The number of unapplied patches; may be overridden by the unapplied-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 no replacements are\nperformed at all, it is just a string.\n" }, { "name": "Oddities", "content": "If you want to use the %b (bold off) prompt expansion in formats, which expands %b itself,\nuse %%b. That will cause the vcsinfo expansion to replace %%b with %b, so that zsh's prompt\nexpansion mechanism can handle it. Similarly, to hand down %b from branchformat, use %%%%b.\nSorry for this inconvenience, but it cannot be easily avoided. Luckily we do not clash with a\nlot of prompt expansions and this only needs to be done for those.\n\nWhen one of the gen-applied-string, gen-unapplied-string, and set-patch-format hooks is de‐\nfined, applying %-escaping (`foo=${foo//'%'/%%}') to the interpolated values for use in the\nprompt is the responsibility of those hooks (jointly); when neither of those hooks is de‐\nfined, vcsinfo handles escaping by itself. We regret this coupling, but it was required for\nbackwards compatibility.\n" }, { "name": "Quilt Support", "content": "Quilt is not a version control system, therefore this is not implemented as a backend. It can\nhelp keeping track of a series of patches. People use it to keep a set of changes they want\nto use on top of software packages (which is tightly integrated into the package build\nprocess - the Debian project does this for a large number of packages). Quilt can also help\nindividual developers keep track of their own patches on top of real version control systems.\n\nThe vcsinfo integration tries to support both ways of using quilt by having two slightly\ndifferent modes of operation: `addon' mode and `standalone' mode).\n\nQuilt integration is off by default; to enable it, set the use-quilt style, and add %Q to\nyour formats or actionformats style:\nzstyle ':vcsinfo:*' use-quilt true\n\nStyles looked up from the Quilt support code include `.quilt-quilt-mode' in the vcs-string\npart of the context, where quilt-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 real version control\nsystem controlling the directory. If that is the case, a directory that holds quilt's patches\nneeds to be found. That directory is configurable via the `QUILTPATCHES' environment vari‐\nable. If that variable exists its value is used, otherwise the value `patches' is assumed.\nThe value from $QUILTPATCHES can be overwritten using the `quilt-patches' style. (Note: you\ncan use vcsinfo to keep the 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. To gather more infor‐\nmation, vcsinfo looks for a directory called `.pc'; Quilt uses that directory to track its\ncurrent state. If this directory 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 want to know which\npatches of a series are not yet applied, you need to activate the get-unapplied style in the\nappropriate context.\n\nvcsinfo allows for very detailed control over how the gathered information is presented (see\nthe Configuration and Hooks in vcsinfo sections), all of which are documented below. Note\nthere are a number of other 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 systems like that are\ngenerally configured the same way as the quilt support.\n\nIf the quilt support is working in `addon' mode, the produced string is available as a simple\nformat replacement (%Q to be precise), which can be used in formats and actionformats; see\nbelow for details).\n\nIf, on the other hand, the support code is working in `standalone' mode, vcsinfo will pre‐\ntend as if quilt were an actual version control system. That means that the version control\nsystem identifier (which otherwise would be something like `svn' or `cvs') will be set to\n`-quilt-'. This has implications on the used style context where this identifier is the sec‐\nond element. vcsinfo will have filled in a proper value for the \"repository's\" root direc‐\ntory and the string containing the information about quilt's state will be available as the\n`misc' replacement (and %Q for compatibility with `addon' mode).\n\nWhat is left to discuss is how `standalone' mode is detected. The detection itself is a se‐\nries of searches for directories. You can have this detection enabled all the time in every\ndirectory that is not otherwise under version control. If you know there is only a limited\nset of trees where you would like vcsinfo to try and look for Quilt in `standalone' mode to\nminimise the amount of searching on every call to vcsinfo, there are a number of ways to do\nthat:\n\nEssentially, `standalone' mode detection is controlled by a style called `quilt-standalone'.\nIt is a string style and its value can have different effects. The simplest values are: `al‐‐\nways' to run detection every 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 differently. If the\nvalue is the name of a scalar variable the value of that variable is checked and that value\nis used in the same `always'/`never' way as described above.\n\nIf the value of quilt-standalone is an array, the elements of that array are used as direc‐\ntory names under which you want the detection to be active.\n\nIf quilt-standalone is an associative array, the keys are taken as directory names under\nwhich you want the detection to be active, but only if the corresponding value is the string\n`true'.\n\nLast, but not least, if the value of quilt-standalone is the name of a function, the function\nis called without arguments and the return value decides whether detection should be active.\nA `0' return value is true; a non-zero return value is interpreted as false.\n\nNote, if there is both a function and a variable by the name of quilt-standalone, the func‐\ntion will take precedence.\n" }, { "name": "Function Descriptions (Public API)", "content": "vcsinfo [user-context]\nThe main function, that runs all backends and assembles all data into\n${vcsinfomsg*}. This is the function you want to call from precmd if you want to\ninclude up-to-date information in your prompt (see Variable Description below). If an\nargument is given, that string will be used instead of default in the user-context\nfield of the style context.\n\nvcsinfohookadd\nStatically registers a number of functions to a given hook. The hook needs to be given\nas the first argument; what follows is a list of hook-function names to register to\nthe hook. The `+vi-' prefix needs to be left out here. See Hooks in vcsinfo below for\ndetails.\n\nvcsinfohookdel\nRemove hook-functions from a given hook. The hook needs to be given as the first\nnon-option argument; what follows is a list of hook-function names to un-register from\nthe hook. If `-a' is used as the first argument, all occurrences of the functions are\nunregistered. Otherwise only the last occurrence is removed (if a function was regis‐\ntered to a hook more than once). The `+vi-' prefix needs to be left out here. See\nHooks in vcsinfo below for details.\n\nvcsinfolastmsg\nOutputs the last ${vcsinfomsg*} value. Takes into account the value of the\nuse-prompt-escapes style in ':vcsinfo:formats:command:-all-'. It also only prints\nmax-exports values.\n\nvcsinfoprintsys [user-context]\nPrints a list of all supported version control systems. Useful to find out possible\ncontexts (and which of them are enabled) or values for the disable style.\n\nvcsinfosetsys\nInitializes vcsinfo's internal list of available backends. With this function, you\ncan add support for new VCSs without restarting the shell.\n\nAll functions named VCSINFO* are for internal use only.\n" }, { "name": "Variable Description", "content": "${vcsinfomsgN} (Note the trailing underscore)\nWhere N is an integer, e.g., vcsinfomsg0. These variables are the storage for the\ninformational message the last vcsinfo call has assembled. These are strongly con‐\nnected to the formats, actionformats and nvcsformats styles described above. Those\nstyles are lists. The first member of that list gets expanded into ${vcsinfomsg0},\nthe second into ${vcsinfomsg1} and the Nth into ${vcsinfomsgN-1}. (See the\nmax-exports style above.)\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 can communicate with\nthe code that called it and through that, change the 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 style in the appropriate\ncontext.\n\nExample:\nzstyle ':vcsinfo:*+foo:*' hooks bar baz\n\nThis registers functions to the hook `foo' for all backends. In order to avoid namespace\nproblems, all registered function names are prepended by a `+vi-', so the actual functions\ncalled for the `foo' hook are `+vi-bar' and `+vi-baz'.\n\nIf you would like to register a function to a hook regardless of the current context, you may\nuse the vcsinfohookadd function. To remove a function that was added like that, the\nvcsinfohookdel function can be used.\n\nIf something seems weird, you can enable the `debug' boolean style in the proper context and\nthe hook-calling code will print what it tried to execute and whether the function in ques‐\ntion existed.\n\nWhen you register more than one function to a hook, all functions are executed one after an‐\nother until one function returns non-zero or until all functions have been called. Con‐\ntext-sensitive hook functions are executed before statically registered ones (the ones added\nby vcsinfohookadd).\n\nYou may pass data between functions via an associative array, userdata. 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 caller. The default is an\ninteger `zero'. If and how a changed ret value changes the execution of the caller de‐\npends on the specific hook. See the hook documentation below for details.\n\nhookcom\nAn associated array which is used for bidirectional communication from the caller to\nhook functions. The used keys depend on the specific hook.\n" }, { "name": "context", "content": "The active context of the hook. Functions that wish to change this variable should\nmake it local scope first.\n\nvcs The current VCS after it was detected. The same values as in the enable/disable style\nare used. Available in all hooks except start-up.\n\nFinally, the full list of currently available hooks:\n" }, { "name": "start-up", "content": "Called after starting vcsinfo but before the VCS in this directory is determined. It\ncan be used to deactivate vcsinfo temporarily if necessary. When ret is set to 1,\nvcsinfo aborts and does nothing; when set to 2, vcsinfo sets up everything as if no\nversion control were active and exits.\n" }, { "name": "pre-get-data", "content": "Same as start-up but after the VCS was detected.\n" }, { "name": "gen-hg-bookmark-string", "content": "Called in the Mercurial backend when a bookmark string is generated; the get-revision\nand get-bookmarks styles must be true.\n\nThis hook gets the names of the Mercurial bookmarks that vcsinfo collected from `hg'.\n\nIf a bookmark is active, the key ${hookcom[hg-active-bookmark]} is set to its name.\nThe key is otherwise unset.\n\nWhen setting ret to non-zero, the string in ${hookcom[hg-bookmark-string]} will be\nused in the %m escape in formats and actionformats and will be available in the global\nbackendmisc array as ${backendmisc[bookmarks]}.\n" }, { "name": "gen-applied-string", "content": "Called in the git (with stgit or during rebase or merge), and hg (with mq) backends\nand in quilt support when the applied-string is generated; the use-quilt zstyle must\nbe true for quilt (the mq and stgit backends are active by default).\n\nThis hook gets the names of all applied patches which vcsinfo collected so far in the\nopposite order, which means that the first argument is the top-most patch and so\nforth.\n\nWhen setting ret to non-zero, the string in ${hookcom[applied-string]} will be avail‐\nable as %p in the patch-format and nopatch-format styles. This hook is, in concert\nwith set-patch-format, responsible for %-escaping that value for use in the prompt.\n(See the Oddities section.)\n" }, { "name": "gen-unapplied-string", "content": "Called in the git (with stgit or during rebase), and hg (with mq) backend and in quilt\nsupport when the unapplied-string is generated; the get-unapplied style must be true.\n\nThis hook gets the names of all unapplied patches which vcsinfo collected so far in\norder, which means that the first argument is the patch next-in-line to be applied and\nso forth.\n\nWhen setting ret to non-zero, the string in ${hookcom[unapplied-string]} will be\navailable as %u in the patch-format and nopatch-format styles. This hook is, in con‐\ncert with set-patch-format, responsible for %-escaping that value for use in the\nprompt. (See the Oddities section.)\n" }, { "name": "gen-mqguards-string", "content": "Called in the hg backend when guards-string is generated; the get-mq style must be\ntrue (default).\n\nThis hook gets the names of any active mq guards.\n\nWhen setting ret to non-zero, the string in ${hookcom[guards-string]} will be used in\nthe %g escape in the patch-format and nopatch-format styles.\n\nno-vcs This hooks is called when no version control system was detected.\n\nThe `hookcom' parameter is not used.\n" }, { "name": "post-backend", "content": "Called as soon as the backend has finished collecting information.\n\nThe `hookcom' keys available are as for the set-message hook.\n" }, { "name": "post-quilt", "content": "Called after the quilt support is done. The following information is passed as argu‐\nments to the hook: 1. the quilt-support mode (`addon' or `standalone'); 2. the direc‐\ntory that contains the patch series; 3. the directory that holds quilt's status infor‐\nmation (the `.pc' directory) or the string \"-nopc-\" if that directory wasn't found.\n\nThe `hookcom' parameter is not used.\n" }, { "name": "set-branch-format", "content": "Called before `branchformat' is set. The only argument to the hook is the format that\nis configured at this point.\n\nThe `hookcom' keys considered are `branch' and `revision'. They are set to the val‐\nues figured out so far by vcsinfo and any change will be used directly when the ac‐\ntual replacement is done.\n\nIf ret is set to non-zero, the string in ${hookcom[branch-replace]} will be used un‐\nchanged as the `%b' replacement in the variables set by vcsinfo.\n" }, { "name": "set-hgrev-format", "content": "Called before a `hgrevformat' is set. The only argument to the hook is the format that\nis configured at this point.\n\nThe `hookcom' keys considered are `hash' and `localrev'. They are set to the values\nfigured out so far by vcsinfo and any change will be used directly when the actual\nreplacement is done.\n\nIf ret is set to non-zero, the string in ${hookcom[rev-replace]} will be used un‐\nchanged as the `%i' replacement in the variables set by vcsinfo.\n" }, { "name": "pre-addon-quilt", "content": "This hook is used when vcsinfo's quilt functionality is active in \"addon\" mode (quilt\nused on top of a real version control system). It is activated right before any quilt\nspecific action is taken.\n\nSetting the `ret' variable in this hook to a non-zero value avoids any quilt specific\nactions from being run at all.\n" }, { "name": "set-patch-format", "content": "This hook is used to control some of the possible expansions in patch-format and\nnopatch-format styles with patch queue systems such 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 %u (${hookcom[unap‐‐\nplied]}) expansion in all backends that use the hook. With the mercurial backend, the\n%g (${hookcom[guards]}) expansion is controllable in addition to that.\n\nIf ret is set to non-zero, the string in ${hookcom[patch-replace]} will be used un‐\nchanged instead of an expanded format from patch-format or nopatch-format.\n\nThis hook is, in concert with the gen-applied-string or gen-unapplied-string hooks if\nthey are defined, responsible for %-escaping the final patch-format value for use in\nthe prompt. (See the Oddities section.)\n" }, { "name": "set-message", "content": "Called each time before a `vcsinfomsgN' message is set. It takes two arguments;\nthe first being the `N' in the message variable name, the second is the currently con‐\nfigured formats or actionformats.\n\nThere are a number of `hookcom' keys, that are used here: `action', `branch', `base',\n`base-name', `subdir', `staged', `unstaged', `revision', `misc', `vcs' and one `miscN'\nentry for each backend-specific data field (N starting at zero). They are set to the\nvalues figured out so far by vcsinfo and any change will be used directly when the\nactual replacement is done.\n\nSince this hook is triggered multiple times (once for each configured formats or ac‐‐\ntionformats), each of the `hookcom' keys mentioned above (except for the miscN en‐\ntries) has an `orig' counterpart, so even if you changed a value to your liking you\ncan still get the original value in the next run. Changing the `orig' values is prob‐\nably not a good idea.\n\nIf ret is set to non-zero, the string in ${hookcom[message]} will be used unchanged\nas the message by vcsinfo.\n\nIf all of this sounds rather confusing, take a look at the Examples section below and also in\nthe Misc/vcsinfo-examples file in the Zsh source. They contain some explanatory code.\n" }, { "name": "Examples", "content": "Don'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, branchformat, you name it)\nare done using the `zformat' builtin from the `zsh/zutil' module. That means you can do ev‐\nerything with these %x items what zformat supports. In particular, if you want something that\nis really long to have a fixed width, like a hash in a mercurial branchformat, you can do\nthis: %12.12i. That'll shrink the 40 character hash to its 12 leading characters. The form is\nactually `%min.maxx'. More 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 `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 you want to use the\nstring provided by vcsinfo in prompts.\n\nHere is how to print the VCS information as a command (not in a prompt):\nalias vcsi='vcsinfo command; vcsinfolastmsg'\n\nThis way, you can even define different formats for output via vcsinfolastmsg in the\n':vcsinfo:*:command:*' namespace.\n\nNow as promised, some code that uses hooks: say, you'd like to replace the string `svn' by\n`subversion' in vcsinfo's %s formats replacement.\n\nFirst, we will tell vcsinfo to call a function when populating the message variables with\nthe gathered information:\nzstyle ':vcsinfo:*+set-message:*' hooks svn2subversion\n\nNothing happens. Which is reasonable, since we didn't define the actual function yet. To see\nwhat the hooks subsystem is trying to do, enable the `debug' style:\nzstyle ':vcsinfo:*+*:*' debug true\n\nThat should give you an idea what is going on. Specifically, the function that we are looking\nfor is `+vi-svn2subversion'. Note, the `+vi-' prefix. So, everything is in order, just as\ndocumented. When you are done 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 registered our function in\na less generic context. If we do it only in the `svn' backend's context, we don't need to\ntest which the active backend is:\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 a customised bookmark\nstring 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 available in the examples\nfile located at Misc/vcsinfo-examples in the Zsh source directory.\n\nThis concludes our guided tour through zsh's vcsinfo.\n" } ] }, "PROMPT THEMES": { "content": "", "subsections": [ { "name": "Installation", "content": "You should make sure all the functions from the Functions/Prompts directory of the source\ndistribution are available; they all begin with the string `prompt' except for the special\nfunction`promptinit'. You also need the `colors' and `add-zsh-hook' functions from Func‐‐\ntions/Misc. All these functions may already be installed on your system; if not, you will\nneed to find them and copy them. The directory should appear as one of the elements of the\nfpath array (this should already be the case if they were installed), and at least the func‐\ntion promptinit should be autoloaded; it will autoload the rest. Finally, to initialize the\nuse of the system you need to call the promptinit function. The following code in your\n.zshrc will arrange for this; assume the functions are stored in the directory ~/myfns:\n\nfpath=(~/myfns $fpath)\nautoload -U promptinit\npromptinit\n" }, { "name": "Theme Selection", "content": "Use the prompt command to select your preferred theme. This command may be added to your\n.zshrc following the call to promptinit in order to 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 argument, the theme with\nthat name is set as the current theme. The available themes are determined at run\ntime; use the -l option to see a list. The special theme `random' selects at random\none of the available themes and sets your prompt to that.\n\nIn some cases the theme may be modified by one or more arguments, which should be\ngiven after the theme name. See the help for each theme for descriptions of these ar‐\nguments.\n\nOptions are:\n\n-c Show the currently selected theme and its parameters, if any.\n-l List all available prompt themes.\n-p Preview the theme named by theme, or all themes if no theme is given.\n-h Show help for the theme named by theme, or for the prompt function if no theme\nis 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 prompt function to\ninstall that theme. This function may define other functions as necessary to maintain\nthe prompt, including functions used to preview the prompt or provide help for its\nuse. You should not normally call a theme's setup function directly.\n" }, { "name": "Utility Themes", "content": "" }, { "name": "prompt off", "content": "The theme `off' sets all the prompt variables to minimal values with no special ef‐\nfects.\n" }, { "name": "prompt default", "content": "The theme `default' sets all prompt variables to the same state as if an interactive\nzsh was started with no initialization files.\n" }, { "name": "prompt restore", "content": "The special theme `restore' erases all theme settings and sets prompt variables to\ntheir state before the first time the `prompt' function was run, provided each theme\nhas properly defined its cleanup (see below).\n\nNote that you can undo `prompt off' and `prompt default' with `prompt restore', but a\nsecond restore does not undo the first.\n" }, { "name": "Writing Themes", "content": "The first step for adding your own theme is to choose a name for it, and create a file\n`promptnamesetup' in a directory in your fpath, such as ~/myfns in the example above. The\nfile should at minimum contain assignments for the prompt variables that your theme wishes to\nmodify. By convention, themes use PS1, PS2, RPS1, etc., rather than the longer PROMPT and\nRPROMPT.\n\nThe file is autoloaded as a function in the current shell context, so it may contain any nec‐\nessary commands to customize your theme, including defining additional functions. To make\nsome complex tasks easier, your setup function may also do any of the following:\n\nAssign promptopts\nThe array promptopts may be assigned any of \"bang\", \"cr\", \"percent\", \"sp\", and/or\n\"subst\" as values. The corresponding setopts (promptbang, etc.) are turned on, all\nother prompt-related options are turned off. The promptopts array preserves setopts\neven beyond the scope of localoptions, should your function need that.\n\nModify precmd and preexec\nUse of add-zsh-hook is recommended. The precmd and preexec hooks are automatically\nadjusted if the prompt theme changes or is disabled.\n\nDeclare cleanup\nIf your function makes any other changes that should be undone when the theme is dis‐\nabled, your setup function may call\npromptcleanup command\nwhere command should be suitably quoted. If your theme is ever disabled or replaced by an‐\nother, command is executed with eval. You may declare more than one such cleanup hook.\n\nDefine preview\nDefine or autoload a function promptnamepreview to display a simulated version of\nyour prompt. A simple default previewer is defined by promptinit for themes that do\nnot define their own. This preview function is called by `prompt -p'.\n\nProvide help\nDefine or autoload a function promptnamehelp to display documentation or help text\nfor your theme. This help function is called by `prompt -h'.\n" } ] }, "ZLE FUNCTIONS": { "content": "", "subsections": [ { "name": "Widgets", "content": "These functions all implement user-defined ZLE widgets (see zshzle(1)) which can be bound to\nkeystrokes in interactive shells. To use them, your .zshrc should contain lines of the form\n\nautoload function\nzle -N function\n\nfollowed by an appropriate bindkey command to associate the function with a key sequence.\nSuggested bindings are described below.\n\nbash-style word functions\nIf you are looking for functions to implement moving over and editing words in the\nmanner of bash, where only alphanumeric characters are considered word characters, you\ncan use the functions described in the next section. The following is sufficient:\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 the builtin widgets\nwithout the suffix. By default they behave in a similar way. However, by the use of\nstyles and the function select-word-style, the way words are matched can be altered.\nselect-word-match is intended to be used as a text object in vi mode but with custom\nword styles. For comparison, the widgets described in zshzle(1) under Text Objects use\nfixed definitions of words, compatible with the vim editor.\n\nThe simplest way of configuring the functions is to use select-word-style, which can\neither be called as a normal function with the appropriate argument, or invoked as a\nuser-defined widget that will prompt for the first character of the word style to be\nused. The first time it is invoked, the first eight -match functions will automati‐\ncally replace the builtin versions, so they do not need to be loaded explicitly.\n\nThe word styles available are as follows. Only the first character is examined.\n\nbash Word characters are alphanumeric characters only.\n\nnormal As in normal shell operation: word characters are alphanumeric characters plus\nany characters present in the string given by the parameter $WORDCHARS.\n\nshell Words are complete shell command arguments, possibly including complete quoted\nstrings, or any tokens special to the shell.\n\nwhitespace\nWords are any set of characters delimited by whitespace.\n\ndefault\nRestore the default settings; this is usually the same as `normal'.\n\nAll but `default' can be input as an upper case character, which has the same effect\nbut with subword matching turned on. In this case, words with upper case characters\nare treated specially: each separate run of upper case characters, or an upper case\ncharacter followed by any number of other characters, is considered a word. The style\nsubword-range can supply an alternative character range to the default `[:upper:]';\nthe value of the style is treated as the contents of a `[...]' pattern (note that the\nouter brackets should not be supplied, only those surrounding named ranges).\n\nMore control can be obtained using the zstyle command, as described in zshmodules(1).\nEach style is looked up in the context :zle:widget where widget is the name of the\nuser-defined widget, not the name of the function implementing it, so in the case of\nthe definitions supplied by select-word-style the appropriate contexts are :zle:for‐‐\nward-word, and so on. The function select-word-style itself always defines styles for\nthe context `:zle:*' which can be overridden by more specific (longer) patterns as\nwell as explicit contexts.\n\nThe style word-style specifies the rules to use. This may have the following values.\n\nnormal Use the standard shell rules, i.e. alphanumerics and $WORDCHARS, unless over‐\nridden by the styles word-chars or word-class.\n\nspecified\nSimilar to normal, but only the specified characters, and not also alphanumer‐\nics, are considered word characters.\n\nunspecified\nThe negation of specified. The given characters are those which will not be\nconsidered part of a word.\n\nshell Words are obtained by using the syntactic rules for generating shell command\narguments. In addition, special tokens which are never command arguments such\nas `()' are also treated as words.\n\nwhitespace\nWords are whitespace-delimited strings of characters.\n\nThe first three of those rules usually use $WORDCHARS, but the value in the parameter\ncan be overridden by the style word-chars, which works in exactly the same way as\n$WORDCHARS. In addition, the style word-class uses character class syntax to group\ncharacters and takes precedence over word-chars if both are set. The word-class style\ndoes not include the surrounding brackets of the character class; for example,\n`-:[:alnum:]' is a valid word-class to include all alphanumerics plus the characters\n`-' and `:'. Be careful including `]', `^' and `-' as these are special inside char‐\nacter classes.\n\nword-style may also have `-subword' appended to its value to turn on subword matching,\nas described above.\n\nThe style skip-chars is mostly useful for transpose-words and similar functions. If\nset, it gives a count of characters starting at the cursor position which will not be\nconsidered part of the word and are treated as space, regardless of what they actually\nare. For example, if\n\nzstyle ':zle:transpose-words' skip-chars 1\n\nhas been set, and transpose-words-match is called with the cursor on the X of fooXbar,\nwhere X can be any character, then the resulting expression is barXfoo.\n\nFiner grained control can be obtained by setting the style word-context to an array of\npairs of entries. Each pair of entries consists of a pattern and a subcontext. The\nshell argument the cursor is on is matched against each pattern in turn until one\nmatches; if it does, the context is extended by a colon and the corresponding subcon‐\ntext. Note that the test is made against the original word on the line, with no\nstripping of quotes. Special handling is done between words: the current context is\nexamined and if it contains the string between the word is set to a single space; else\nif it is contains the string back, the word before the cursor is considered, else the\nword after cursor is considered. Some examples are given below.\n\nThe style skip-whitespace-first is only used with the forward-word widget. If it is\nset to true, then forward-word skips any non-word-characters, followed by any\nnon-word-characters: this is similar to the behaviour of other word-orientated wid‐\ngets, and also that used by other editors, however it differs from the standard zsh\nbehaviour. When using select-word-style the widget is set in the context :zle:* to\ntrue if the word style is bash and false otherwise. It may be overridden by setting\nit in the more specific context :zle:forward-word*.\n\nIt is possible to create widgets with specific behaviour by defining a new widget im‐\nplemented by the appropriate generic function, then setting a style for the context of\nthe specific widget. For example, the following defines a widget back‐‐\nward-kill-space-word using backward-kill-word-match, the generic widget implementing\nbackward-kill-word behaviour, and ensures that the new widget always implements\nspace-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 taken from the simpli‐\nfied 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 alphanumerics are word\ncharacters; equivalent to setting the parameter 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 the name. Neither of\nthe styles word-chars nor word-class is used in this case.\n\nHere are some examples of use of the word-context style to extend 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 depending on whether the\ncursor is on whitespace between words or on a filename, here any word containing a /.\nOn whitespace, complete arguments as defined by standard shell rules will be trans‐\nposed. In a filename, only alphanumerics will be transposed. Elsewhere, words will\nbe transposed using the default style for :zle:transpose-words.\n\nThe word matching and all the handling of zstyle settings is actually implemented by\nthe function match-words-by-style. This can be used to create new user-defined wid‐\ngets. The calling function should set the local parameter curcontext to :zle:widget,\ncreate the local parameter matchedwords and call match-words-by-style with no argu‐\nments. On return, matchedwords will be set to an array with the elements: (1) the\nstart of the line (2) the word before the cursor (3) any non-word characters between\nthat word and the cursor (4) any non-word character at the cursor position plus any\nremaining non-word characters before the next word, including all characters specified\nby the skip-chars style, (5) the word at or following the cursor (6) any non-word\ncharacters following that word (7) the remainder of the line. Any of the elements may\nbe an empty string; the calling function should test for this to decide whether it can\nperform its function.\n\nIf the variable matchedwords is defined by the caller to match-words-by-style as an\nassociative array (local -A matchedwords), then the seven values given above should\nbe retrieved from it as elements named start, word-before-cursor, ws-before-cursor,\nws-after-cursor, word-after-cursor, ws-after-word, and end. In addition the element\nis-word-start is 1 if 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 ws-after-cursor ele‐\nment) and 0 otherwise. This form is recommended for future compatibility.\n\nIt is possible to pass options with arguments to match-words-by-style to override the\nuse of styles. The options are:\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 extract the command ar‐\ngument around the cursor.\n\nThe word-context style is implemented by the function match-word-context. This should\nnot usually need to be called directly.\n" }, { "name": "bracketed-paste-magic", "content": "The bracketed-paste widget (see subsection Miscellaneous in zshzle(1)) inserts pasted\ntext literally into the editor buffer rather than interpret it as keystrokes. This\ndisables some common usages where the self-insert widget is replaced in order to ac‐\ncomplish some extra processing. An example is the contributed url-quote-magic widget\ndescribed below.\n\nThe bracketed-paste-magic widget is meant to replace bracketed-paste with a wrapper\nthat re-enables these self-insert actions, and other actions as selected by zstyles.\nTherefore this widget is installed with\n\nautoload -Uz bracketed-paste-magic\nzle -N bracketed-paste bracketed-paste-magic\n\nOther than enabling some widget processing, bracketed-paste-magic attempts to repli‐\ncate bracketed-paste as faithfully as possible.\n\nThe following zstyles may be set to control processing of pasted text. All are looked\nup in the context `:bracketed-paste-magic'.\n\nactive-widgets\nA list of patterns matching widget names that should be activated during the\npaste. All other key sequences are processed as self-insert-unmeta. The de‐\nfault is `self-*' so any user-defined widgets named with that prefix are active\nalong with the builtin self-insert.\n\nIf this style is not set (explicitly deleted) or set to an empty value, no wid‐\ngets are active and the pasted text is inserted literally. If the value in‐\ncludes `undefined-key', any unknown sequences are discarded from the pasted\ntext.\n\ninactive-keys\nThe inverse of active-widgets, a list of key sequences that always use self-in‐‐\nsert-unmeta even when bound to an active widget. Note that this is a list of\nliteral key sequences, not patterns.\n\npaste-init\nA list of function names, called in widget context (but not as widgets). The\nfunctions are called in order until one of them returns a non-zero status. The\nparameter `PASTED' contains the initial state of the pasted text. All other\nZLE parameters such as `BUFFER' have their normal values and side-effects, and\nfull history is available, so for example paste-init functions may move words\nfrom BUFFER into PASTED to make those words visible to the active-widgets.\n\nA non-zero return from a paste-init function does not prevent the paste itself\nfrom proceeding.\n\nLoading bracketed-paste-magic defines backward-extend-paste, a helper function\nfor 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 append text to a word\nalready on the line, backward-extend-paste moves the prefix from LBUFFER into\nPASTED so that the active-widgets see the full word so far. This may be useful\nwith url-quote-magic.\n\npaste-finish\nAnother list of function names called in order until one returns non-zero.\nThese functions are called after the pasted text has been processed by the ac‐‐\ntive-widgets, but before 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 prevent the paste it‐\nself from proceeding.\n\nLoading bracketed-paste-magic also defines quote-paste, a helper function for\nuse 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 quoted per the quote-style\nvalue. To forcibly turn off the built-in numeric prefix quoting of brack‐‐\neted-paste, use:\n\nzstyle :bracketed-paste-magic:finish quote-style \\\nnone\n\nImportant: During active-widgets processing of the paste (after paste-init and before\npaste-finish), BUFFER starts empty and history is restricted, so cursor motions, etc.,\nmay not pass outside of the pasted content. Text assigned to BUFFER by the active\nwidgets is copied back into PASTED before paste-finish.\n" }, { "name": "copy-earlier-word", "content": "This widget works like a combination of insert-last-word and copy-prev-shell-word.\nRepeated invocations of the widget retrieve earlier words on the relevant history\nline. With a numeric argument N, insert the Nth word from the history line; N may be\nnegative to count from the end of the line.\n\nIf insert-last-word has been used to retrieve the last word on a previous history\nline, repeated invocations will replace that word with earlier words from the same\nline.\n\nOtherwise, the widget applies to words on the line currently being edited. The widget\nstyle can be set to the name of another widget that should be called to retrieve\nwords. This widget must accept the same three arguments as insert-last-word.\n" }, { "name": "cycle-completion-positions", "content": "After inserting an unambiguous string into the command line, the new function based\ncompletion system may know about multiple places in this string where characters are\nmissing or differ from at least one of the possible matches. It will then place the\ncursor on the position it considers to be the most interesting one, i.e. the one where\none can disambiguate between as many matches as possible with as little typing as pos‐\nsible.\n\nThis widget allows the cursor to be easily moved to the other interesting spots. It\ncan be invoked repeatedly to cycle between all positions reported by the completion\nsystem.\n" }, { "name": "delete-whole-word-match", "content": "This is another function which works like the -match functions described immediately\nabove, i.e. using styles to decide the word boundaries. However, it is not a replace‐\nment for any existing function.\n\nThe basic behaviour is to delete the word around the cursor. There is no numeric ar‐\ngument handling; only the single word around the cursor is considered. If the widget\ncontains the string kill, the removed text will be placed in the cutbuffer for future\nyanking. This can be obtained by defining kill-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 up-line-or-search and\ndown-line-or-search: if in a multiline buffer they move up or down within the buffer,\notherwise they search for a history line matching the start of the current line. In\nthis case, however, they search for a line which matches the current line up to the\ncurrent cursor position, in the manner of history-beginning-search-backward and -for‐‐\nward, rather than the first word on the line.\n" }, { "name": "edit-command-line", "content": "Edit the command line using your visual editor, as in ksh.\n\nbindkey -M vicmd v edit-command-line\n" }, { "name": "expand-absolute-path", "content": "Expand the file name under the cursor to an absolute path, resolving symbolic links.\nWhere possible, the initial path segment is turned into a named directory or reference\nto a user's home directory.\n" }, { "name": "history-search-end", "content": "This function implements the widgets history-beginning-search-backward-end and his‐‐\ntory-beginning-search-forward-end. These commands work by first calling the corre‐\nsponding builtin widget (see `History Control' in zshzle(1)) and then moving the cur‐\nsor to the end of the line. The original cursor position is remembered and restored\nbefore calling the builtin widget a second time, so that the same search is repeated\nto look farther through the history.\n\nAlthough you autoload only one function, the commands to use it are slightly different\nbecause 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" }, { "name": "history-beginning-search-menu", "content": "This function implements yet another form of history searching. The text before the\ncursor is used to select lines from the history, as for history-beginning-search-back‐‐\nward except that all matches are shown in a numbered menu. Typing the appropriate\ndigits inserts the full history line. Note that leading zeroes must be typed (they\nare only shown when necessary for removing ambiguity). The entire history is\nsearched; there is no distinction between forwards and backwards.\n\nWith a numeric argument, the search is not anchored to the start of the line; the\nstring typed by the use may appear anywhere in the line in the history.\n\nIf the widget name contains `-end' the cursor is moved to the end of the line in‐\nserted. If the widget name contains `-space' any space in the text typed is treated\nas a wildcard and can match 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" }, { "name": "history-pattern-search", "content": "The function history-pattern-search implements widgets which prompt for a pattern with\nwhich to search the history backwards or forwards. The pattern is in the usual zsh\nformat, however the first character may be ^ to anchor the search to the start of the\nline, and the last character may be $ to anchor the search to the end of the line. If\nthe search was not anchored to the end of the line the cursor is positioned just after\nthe pattern found.\n\nThe commands to create bindable widgets are similar to those in the example immedi‐\nately 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 or to the left of an\ninteger causes that integer to be incremented by one. With a numeric argument, the\nnumber is incremented by the amount of the argument (decremented if the numeric argu‐\nment is negative). The shell parameter incarg may be set to change the default incre‐\nment to something other than one.\n\nbindkey '^X+' incarg\n" }, { "name": "incremental-complete-word", "content": "This allows incremental completion of a word. After starting this command, a list of\ncompletion choices can be shown after every character you type, which you can delete\nwith ^H or DEL. Pressing return accepts the completion so far and returns you to nor‐\nmal editing (that is, the command line is not immediately executed). You can hit TAB\nto do normal completion, ^G to abort back to the state when you started, and ^D to\nlist the matches.\n\nThis works only with the new function based completion system.\n\nbindkey '^Xi' incremental-complete-word\n" }, { "name": "insert-composed-char", "content": "This function allows you to compose characters that don't appear on the keyboard to be\ninserted into the command line. The command is followed by two keys corresponding to\nASCII characters (there is no prompt). For accented characters, the two keys are a\nbase character followed by a code for the accent, while for other special characters\nthe two characters together form a mnemonic for the character to be inserted. The\ntwo-character codes are 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 which replace one or\nboth of the characters read from the keyboard; if both characters are supplied, no in‐\nput is read. For example, insert-composed-char a: can be used within a widget to in‐\nsert an a with umlaut into the command line. This has the advantages over use of a\nliteral character that it is more portable.\n\nFor best results zsh should have been built with support for multibyte characters\n(configured with --enable-multibyte); however, the function works for the limited\nrange of characters available in single-byte character sets such as ISO-8859-1.\n\nThe character is converted into the local representation and inserted into the command\nline at the cursor position. (The conversion is done within the shell, using whatever\nfacilities the C library provides.) With a numeric argument, the character and its\ncode are previewed in the status line\n\nThe function may be run outside zle in which case it prints the character (together\nwith a newline) to standard output. Input is still read from keystrokes.\n\nSee insert-unicode-char for an alternative way of inserting Unicode characters using\ntheir hexadecimal character number.\n\nThe set of accented characters is reasonably complete up to Unicode character U+0180,\nthe set of special characters less so. However, it is very sporadic from that point.\nAdding new characters 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 are as follows. Note\nthat not every character can take every accent.\n! Grave.\n' Acute.\n> Circumflex.\n? Tilde. (This is not ~ as RFC 1345 does not assume that character is present on\nthe 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, or in the case of L\nand l a centered dot.\n: Diaeresis (Umlaut).\nc Cedilla.\nUnderline, however there are currently no underlined characters.\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 right 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 Hebrew alphabets are\navailable; consult RFC 1345 for the appropriate sequences. In addition, a set of two\nletter codes not in RFC 1345 are available for the double-width characters correspond‐\ning to ASCII characters from ! to ~ (0x21 to 0x7e) by preceding the character with ^,\nfor example ^A for a double-width A.\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 alphabet:\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 rather than 6) rather\nthan their grammatical use. (For example, a \"right\" low double quote is used\nto open quotations 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 note), semiquavers\n(sixteenth notes), flag sign, natural sign, 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" }, { "name": "insert-files", "content": "This function allows you type a file pattern, and see the results of the expansion at\neach step. When you hit return, all expansions are inserted into the command line.\n\nbindkey '^Xf' insert-files\n" }, { "name": "insert-unicode-char", "content": "When first executed, the user inputs a set of hexadecimal digits. This is terminated\nwith another call to insert-unicode-char. The digits are then turned into the corre‐\nsponding Unicode character. For example, if the widget is bound to ^XU, the character\nsequence `^XU 4 c ^XU' inserts L (Unicode U+004c).\n\nSee insert-composed-char for a way of inserting characters using a two-character mne‐\nmonic.\n\n\nnarrow-to-region [ -p pre ] [ -P post ]\n[ -S statepm | -R statepm | [ -l lbufvar ] [ -r rbufvar ] ]\n[ -n ] [ start end ]" }, { "name": "narrow-to-region-invisible", "content": "Narrow the editable portion of the buffer to the region between the cursor and the\nmark, which may be in either order. The region may not be empty.\n\nnarrow-to-region may be used as a widget or called as a function from a user-defined\nwidget; by default, the text outside the editable area remains visible. A recur‐‐\nsive-edit is performed and the original widening status is then restored. Various op‐\ntions and arguments are available when it is called as a function.\n\nThe options -p pretext and -P posttext may be used to replace the text before and af‐\nter the display for the duration of the function; either or both may be an empty\nstring.\n\nIf the option -n is also given, pretext or posttext will only be inserted if there is\ntext before or after the region respectively which will be made invisible.\n\nTwo numeric arguments may be given which will be used instead of the cursor and mark\npositions.\n\nThe option -S statepm is used to narrow according to the other options while saving\nthe original state in the parameter with name statepm, while the option -R statepm is\nused to restore the state from the parameter; note in both cases the name of the pa‐\nrameter is required. In the second case, other options and arguments are irrelevant.\nWhen this method is used, no recursive-edit is performed; the calling widget should\ncall this function with the option -S, perform its own editing on the command line or\npass control to the user via `zle recursive-edit', then call this function with the\noption -R. The argument statepm must be a suitable name for an ordinary parameter,\nexcept that parameters beginning with the prefix ntr are reserved for use within\nnarrow-to-region. Typically the parameter will be local to the calling function.\n\nThe options -l lbufvar and -r rbufvar may be used to specify parameters where the wid‐\nget will store the resulting text from the operation. The parameter lbufvar will con‐\ntain LBUFFER and rbufvar 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 narrow-to-region with argu‐\nments which replace any text outside the region with `...'. It does not take any ar‐\nguments.\n\nThe display is restored (and the widget returns) upon any zle command which would usu‐\nally cause the line to be accepted or aborted. Hence an additional such command is\nrequired to accept or abort the current line.\n\nThe return status of both widgets is zero if the line was accepted, 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" }, { "name": "predict-on", "content": "This set of functions implements predictive typing using history search. After pre‐‐\ndict-on, typing characters causes the editor to look backward in the history for the\nfirst line beginning with what you have typed so far. After predict-off, editing re‐\nturns to normal for the line found. In fact, you often don't even need to use pre‐‐\ndict-off, because if the line doesn't match something in the history, adding a key\nperforms standard completion, and then inserts itself if no completions were found.\nHowever, editing in the middle of a line is liable to confuse prediction; see the tog‐‐\ngle style below.\n\nWith the function based completion system (which is needed for this), you should be\nable to type TAB at almost any point to advance the cursor to the next ``interesting''\ncharacter position (usually the end of the current word, but sometimes somewhere in\nthe middle of the word). And of course as soon as the entire line is what you want,\nyou can accept with return, without needing to move the cursor to the end first.\n\nThe first time predict-on is used, it creates several additional widget functions:\n\ndelete-backward-and-predict\nReplaces the backward-delete-char widget. You do not need to bind this your‐\nself.\ninsert-and-predict\nImplements predictive typing by replacing the self-insert widget. You do not\nneed to bind this yourself.\npredict-off\nTurns off predictive typing.\n\nAlthough you autoload only the predict-on function, it is necessary to create a key‐\nbinding for predict-off as well.\n\nzle -N predict-on\nzle -N predict-off\nbindkey '^X^Z' predict-on\nbindkey '^Z' predict-off\n" }, { "name": "read-from-minibuffer", "content": "This is most useful when called as a function from inside a widget, but will work cor‐\nrectly as a widget in its own right. It prompts for a value below the current command\nline; a value may be input using all of the standard zle operations (and not merely\nthe restricted set available when executing, for example, execute-named-cmd). The\nvalue is then returned to the calling function in the parameter $REPLY and the editing\nbuffer restored to its previous state. If the read was aborted by a keyboard break\n(typically ^G), the function returns status 1 and $REPLY is not set.\n\nIf one argument is supplied to the function it is taken as a prompt, otherwise `? ' is\nused. If two arguments are supplied, they are the prompt and the initial value of\n$LBUFFER, and if a third argument is given it is the initial value of $RBUFFER. This\nprovides a default value and starting cursor placement. Upon return the entire buffer\nis the value of $REPLY.\n\nOne option is available: `-k num' specifies that num characters are to be read instead\nof a whole line. The line editor is not invoked recursively in this case, so depend‐\ning on the terminal settings the input may not be visible, and only the input keys are\nplaced in $REPLY, not the entire buffer. Note that unlike the read builtin num must\nbe given; there is no default.\n\nThe name is a slight misnomer, as in fact the shell's own minibuffer is not used.\nHence it is still possible to call executed-named-cmd and similar functions while\nreading a value.\n\nreplace-argument, replace-argument-edit\nThe function replace-argument can be used to replace a command line argument in the\ncurrent command line or, if the current command line is empty, in the last command\nline executed (the new command line is not executed). Arguments are as delimited by\nstandard shell syntax,\n\nIf a numeric argument is given, that specifies the argument to be replaced. 0 means\nthe command name, as in history expansion. A negative numeric argument counts back‐\nward from the last word.\n\nIf no numeric argument is given, the current argument is replaced; this is the last\nargument if the previous history line is being used.\n\nThe function prompts for a replacement argument.\n\nIf the widget contains the string edit, for example is defined as\n\nzle -N replace-argument-edit replace-argument\n\nthen the function presents the current value of the argument for editing, otherwise\nthe editing buffer for the replacement is initially empty.\n\nreplace-string, replace-pattern\nreplace-string-again, replace-pattern-again\nThe function replace-string implements three widgets. If defined under the same name\nas the function, it prompts for two strings; the first (source) string will be re‐\nplaced by the second everywhere it occurs in the line editing buffer.\n\nIf the widget name contains the word `pattern', for example by defining the widget us‐\ning the command `zle -N replace-pattern replace-string', then the matching is per‐\nformed using zsh patterns. All zsh extended globbing patterns can be used in the\nsource string; note that unlike filename generation the pattern does not need to match\nan entire word, nor do glob qualifiers have any effect. In addition, the replacement\nstring can contain parameter or command substitutions. Furthermore, a `&' in the re‐\nplacement string will be replaced with the matched source string, and a backquoted\ndigit `\\N' will be replaced by the Nth parenthesised expression matched. The form\n`\\{N}' may be used to protect the digit from following digits.\n\nIf the widget instead contains the word `regex' (or `regexp'), then the matching is\nperformed using regular expressions, respecting the setting of the option\nREMATCHPCRE (see the description of the function regexp-replace below). The special\nreplacement facilities described above for pattern matching are available.\n\nBy default the previous source or replacement string will not be offered for editing.\nHowever, this feature can be activated by setting the style edit-previous in the con‐\ntext :zle:widget (for example, :zle:replace-string) to true. In addition, a positive\nnumeric argument forces the previous values to be offered, a negative or zero argument\nforces them not to be.\n\nThe function replace-string-again can be used to repeat the previous replacement; no\nprompting is done. As with replace-string, if the name of the widget contains the\nword `pattern' or `regex', pattern or regular expression matching is performed, else a\nliteral string replacement. Note that the previous source and replacement text are\nthe same whether pattern, regular expression or string matching is used.\n\nIn addition, replace-string shows the previous replacement above the prompt, so long\nas there was one during the current session; if the source string is empty, that re‐\nplacement will be repeated without 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 the replacement string\n`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 narrow-to-region-in‐‐\nvisible widget. One limitation of the current version is that undo will cycle through\nchanges to the replacement and source strings before undoing the replacement itself.\n" }, { "name": "send-invisible", "content": "This is similar to read-from-minibuffer in that it may be called as a function from a\nwidget or as a widget of its own, and interactively reads input from the keyboard.\nHowever, the input being typed is concealed and a string of asterisks (`*') is shown\ninstead. The value is saved in the parameter $INVISIBLE to which a reference is in‐\nserted into the editing buffer at the restored cursor position. If the read was\naborted by a keyboard break (typically ^G) or another escape from editing such as\npush-line, $INVISIBLE is set to empty and the original buffer is restored unchanged.\n\nIf one argument is supplied to the function it is taken as a prompt, otherwise\n`Non-echoed text: ' is used (as in emacs). If a second and third argument are sup‐\nplied they are used to begin and end the reference to $INVISIBLE that is inserted into\nthe buffer. The default is to open with ${, then INVISIBLE, and close with }, but\nmany other effects are possible.\n" }, { "name": "smart-insert-last-word", "content": "This 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 in a call from another\nwidget, it behaves like insert-last-word, except that words in comments are ignored\nwhen INTERACTIVECOMMENTS is set.\n\nOtherwise, the rightmost ``interesting'' word from the previous command is found and\ninserted. The default definition of ``interesting'' is that the word contains at\nleast one alphabetic character, slash, or backslash. This definition may be overrid‐\nden by use of the match style. The context used to look up the style is the widget\nname, so usually the context is :insert-last-word. However, you can bind this func‐\ntion to different 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 set to a true value,\nthe search continues upward through the history. When auto-previous is unset or false\n(the default), the widget must be invoked repeatedly in order to search earlier his‐\ntory lines.\n" }, { "name": "transpose-lines", "content": "Only useful with a multi-line editing buffer; the lines here are lines within the cur‐\nrent on-screen buffer, not history lines. The effect is similar to the function of\nthe same name in Emacs.\n\nTranspose the current line with the previous line and move the cursor to the start of\nthe next line. Repeating this (which can be done by providing a positive numeric ar‐\ngument) has the effect of moving the line above the cursor down by a number of lines.\n\nWith a negative numeric argument, requires two lines above the cursor. These two\nlines are transposed and the cursor moved to the start of the previous line. Using a\nnumeric argument less than -1 has the effect of moving the line above the cursor up by\nminus that number of lines.\n" }, { "name": "url-quote-magic", "content": "This widget replaces the built-in self-insert to make it easier to type URLs as com‐\nmand line arguments. As you type, the input character is analyzed and, if it may need\nquoting, the current word is checked for a URI scheme. If one is found and the cur‐\nrent word is not already in quotes, a backslash is inserted before the input charac‐\nter.\n\nStyles to control quoting behavior:\n\nurl-metas\nThis style is looked up in the context `:url-quote-magic:scheme' (where scheme\nis that of the current URL, e.g. \"ftp\"). The value is a string listing the\ncharacters to be treated as globbing metacharacters when appearing in a URL us‐\ning that scheme. The default is to quote all zsh extended globbing characters,\nexcluding '<' and '>' but including braces (as in brace expansion). See also\nurl-seps.\n\nurl-seps\nLike url-metas, but lists characters that should be considered command separa‐\ntors, redirections, history references, etc. The default is to quote the stan‐\ndard set of shell separators, excluding those that overlap with the extended\nglobbing characters, but including '<' and '>' and the first character of\n$histchars.\n\nurl-globbers\nThis style is looked up in the context `:url-quote-magic'. The values form a\nlist of command names that are expected to do their own globbing on the URL\nstring. This implies that they are aliased to use the `noglob' modifier. When\nthe first word on the line matches one of the values and the URL refers to a\nlocal file (see url-local-schema), only the url-seps characters are quoted; the\nurl-metas are left alone, allowing them to affect command-line parsing, comple‐\ntion, etc. The default values are a literal `noglob' plus (when the zsh/param‐‐\neter module is available) any commands aliased to the helper function `urlglob‐‐\nber' or its alias `globurl'.\n\nurl-local-schema\nThis style is always looked up in the context `:urlglobber', even though it is\nused by both url-quote-magic and urlglobber. The values form a list of URI\nschema that should be treated as referring to local files by their real local\npath names, as opposed to files which are specified relative to a\nweb-server-defined document root. The defaults are \"ftp\" and \"file\".\n\nurl-other-schema\nLike url-local-schema, but lists all other URI schema upon which urlglobber and\nurl-quote-magic should act. If the URI on the command line does not have a\nscheme appearing either in this list or in url-local-schema, it is not magi‐\ncally quoted. The default values are \"http\", \"https\", and \"ftp\". When a\nscheme appears both here and in url-local-schema, it is quoted differently de‐\npending on whether the command name appears in url-globbers.\n\nLoading url-quote-magic also defines a helper function `urlglobber' and aliases\n`globurl' to `noglob urlglobber'. This function takes a local URL apart, attempts to\npattern-match the local file portion of the URL path, and then puts the results back\ninto URL format again.\n" }, { "name": "vi-pipe", "content": "This function reads a movement command from the keyboard and then prompts for an ex‐\nternal command. The part of the buffer covered by the movement is piped to the exter‐\nnal command and then replaced by the command's output. If the movement command is\nbound to vi-pipe, the current line is used.\n\nThe function serves as an example for reading a vi movement command from within a\nuser-defined widget.\n" }, { "name": "which-command", "content": "This function is a drop-in replacement for the builtin widget which-command. It has\nenhanced behaviour, in that it correctly detects whether or not the command word needs\nto be expanded as an alias; if so, it continues tracing the command word from the ex‐\npanded alias until it reaches the command that will be executed.\n\nThe style whence is available in the context :zle:$WIDGET; this may be set to an array\nto give the command and options that will be used to investigate the command word\nfound. The default is whence -c.\n" }, { "name": "zcalc-auto-insert", "content": "This function is useful together with the zcalc function described in the section\nMathematical Functions. It should be bound to a key representing a binary operator\nsuch as `+', `-', `*' or `/'. When running in zcalc, if the key occurs at the start\nof the line or immediately following an open parenthesis, the text \"ans \" is inserted\nbefore the representation of the key itself. This allows easy use of the answer from\nthe previous calculation in the current line. The text to be inserted before the sym‐\nbol typed can be modified by setting the variable ZCALCAUTOINSERTPREFIX.\n\nHence, for example, typing `+12' followed by return adds 12 to the previous result.\n\nIf zcalc is in RPN mode (-r option) the effect of this binding is automatically sup‐\npressed as operators alone on a line are meaningful.\n\nWhen not in zcalc, the key simply inserts the symbol itself.\n" }, { "name": "Utility Functions", "content": "These functions are useful in constructing widgets. They should be loaded with `autoload -U\nfunction' and called as indicated from user-defined widgets.\n" }, { "name": "split-shell-arguments", "content": "This function splits the line currently being edited into shell arguments and white‐\nspace. The result is stored in the array reply. The array contains all the parts of\nthe line in order, starting with any whitespace before the first argument, and finish‐\ning with any whitespace after the last argument. Hence (so long as the option KSHAR‐‐\nRAYS is not set) whitespace is given by odd indices in the array and arguments by even\nindices. Note that no stripping of quotes is done; joining together all the elements\nof reply in order is guaranteed to produce the original line.\n\nThe parameter REPLY is set to the index of the word in reply which contains the char‐\nacter after the cursor, where the first element has index 1. The parameter REPLY2 is\nset to the index of the character under the cursor in that word, where the first char‐\nacter has index 1.\n\nHence reply, REPLY and REPLY2 should all be made local to the enclosing function.\n\nSee the function modify-current-argument, described below, for an example of how to\ncall this function.\n\nmodify-current-argument [ expr-using-$ARG | func ]\nThis function provides a simple method of allowing user-defined widgets to modify the\ncommand line argument under the cursor (or immediately to the left of the cursor if\nthe cursor is between arguments).\n\nThe argument can be an expression which when evaluated operates on the shell parameter\nARG, which will have been set to the command line argument under the cursor. The ex‐\npression should be suitably quoted to prevent it being evaluated too early.\n\nAlternatively, if the argument does not contain the string ARG, it is assumed to be a\nshell function, to which the current command line argument is passed as the only argu‐\nment. The function should set the variable REPLY to the new value for the command\nline argument. If the function returns non-zero status, so does the calling function.\n\nFor example, a user-defined widget containing the following code converts the charac‐\nters in the argument under the cursor into all upper case:\n\nmodify-current-argument '${(U)ARG}'\n\nThe following strips any quoting from the current word (whether backslashes or one of\nthe styles of quotes), and replaces it with single quoting throughout:\n\nmodify-current-argument '${(qq)${(Q)ARG}}'\n\nThe following performs directory expansion on the command line argument and replaces\nit 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 defined within the widget\nwhere modify-current-argument is called.\n" }, { "name": "Styles", "content": "The behavior of several of the above widgets can be controlled by the use of the zstyle mech‐\nanism. In particular, widgets that interact with the completion system pass along their con‐\ntext to any completions that they invoke.\n" }, { "name": "break-keys", "content": "This style is used by the incremental-complete-word widget. Its value should be a pat‐\ntern, and all keys matching this pattern will cause the widget to stop incremental\ncompletion without the key having any further effect. Like all styles used directly by\nincremental-complete-word, this style is looked up using the context `:incremental'.\n" }, { "name": "completer", "content": "The incremental-complete-word and insert-and-predict widgets set up their top-level\ncontext name before calling completion. This allows one to define different sets of\ncompleter functions for normal completion and for these widgets. For example, to use\ncompletion, approximation and correction for normal completion, completion and correc‐\ntion for incremental completion and only completion 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, because they may be\nautomatically invoked as you type. The list and menu completers should never be\nused with prediction. The approximate, correct, expand, and match completers may\nbe used, but be aware that they may change characters anywhere in the word behind the\ncursor, so you need to watch carefully that the result is what you intended.\n\ncursor The insert-and-predict widget uses this style, in the context `:predict', to decide\nwhere to place the cursor after completion has been tried. Values are:\n\ncomplete\nThe cursor is left where it was when completion finished, but only if it is af‐\nter a character equal to the one just inserted by the user. If it is after an‐\nother character, this value is the same as `key'.\n\nkey The cursor is left after the nth occurrence of the character just inserted,\nwhere n is the number of times that character appeared in the word before com‐\npletion was attempted. In short, this has the effect of leaving the cursor af‐\nter the character just typed even if the completion code found out that no\nother characters need to be inserted at that position.\n\nAny other value for this style unconditionally leaves the cursor at the position where\nthe completion code left it.\n\nlist When using the incremental-complete-word widget, this style says if the matches should\nbe listed on every key press (if they fit on the screen). Use the context prefix\n`:completion:incremental'.\n\nThe insert-and-predict widget uses this style to decide if the completion should be\nshown even if there is only one possible completion. This is done if the value of\nthis style is the string always. In this case the context is `:predict' (not `:com‐‐\npletion:predict').\n\nmatch This style is used by smart-insert-last-word to provide a pattern (using full EX‐‐\nTENDEDGLOB syntax) that matches an interesting word. The context is the name of the\nwidget to which smart-insert-last-word is bound (see above). The default behavior of\nsmart-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 characters 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 style in the status line\nduring incremental completion. The string value may contain any of the following sub‐\nstrings in the manner of the PS1 and other prompt parameters:\n\n%c Replaced by the name of the completer function that generated the matches\n(without the leading underscore).\n\n%l When the list style is set, replaced by `...' if the list of matches is too\nlong to fit on the screen and with an empty string otherwise. If the list\nstyle is `false' or not 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 string if there is no com‐\npletion matching the word on the line, if the matches have no common prefix\ndifferent from the word on the line, or if there is such a common prefix, re‐\nspectively.\n\n%u Replaced by the unambiguous part of all matches, if there is any, and if it is\ndifferent from the word on the line.\n\nLike `break-keys', this uses the `:incremental' context.\n" }, { "name": "stop-keys", "content": "This style is used by the incremental-complete-word widget. Its value is treated sim‐\nilarly to the one for the break-keys style (and uses the same context: `:incremen‐‐\ntal'). However, in this case all keys matching the pattern given as its value will\nstop incremental completion and will then execute their usual function.\n\ntoggle This boolean style is used by predict-on and its related widgets in the context `:pre‐‐\ndict'. If set to one of the standard `true' values, predictive typing is automati‐\ncally toggled off in situations where it is unlikely to be useful, such as when edit‐\ning a multi-line buffer or after moving into the middle of a line and then deleting a\ncharacter. The default is to leave prediction turned on until an explicit call to\npredict-off.\n" }, { "name": "verbose", "content": "This boolean style is used by predict-on and its related widgets in the context `:pre‐‐\ndict'. If set to one of the standard `true' values, these widgets display a message\nbelow the prompt when the predictive state is toggled. This is most useful in combi‐\nnation with the toggle style. The default does not display these messages.\n\nwidget This style is similar to the command style: For widget functions that use zle to call\nother widgets, this style can sometimes be used to override the widget which is\ncalled. The context for this style is the name of the calling widget (not the name of\nthe calling function, because one function may be bound to multiple widget names).\n\nzstyle :copy-earlier-word widget smart-insert-last-word\n\nCheck the documentation for the calling widget or function to determine whether the\nwidget style is used.\n" } ] }, "EXCEPTION HANDLING": { "content": "Two functions are provided to enable zsh to provide exception handling in a form that should\nbe familiar from other languages.\n\nthrow exception\nThe function throw throws the named exception. The name is an arbitrary string and is\nonly used by the throw and catch functions. An exception is for the most part treated\nthe same as a shell error, i.e. an unhandled exception will cause the shell to abort\nall processing in a function or script and to return to the top level in an interac‐\ntive shell.\n\ncatch exception-pattern\nThe function catch returns status zero if an exception was thrown and the pattern ex‐\nception-pattern matches its name. Otherwise it returns status 1. exception-pattern\nis a standard shell pattern, respecting the current setting of the EXTENDEDGLOB op‐\ntion. An alias catch is also defined to prevent the argument to the function from\nmatching filenames, so patterns may be used unquoted. Note that as exceptions are not\nfundamentally different from other shell errors it is possible to catch shell errors\nby using an empty string as the exception name. The shell variable CAUGHT is set by\ncatch to the name of the exception caught. It is possible to rethrow an exception by\ncalling the throw function again once an exception has been caught.\n\nThe functions are designed to be used together with the always construct described in zsh‐\nmisc(1). This is important as only this construct provides the required support for excep‐\ntions. A typical example is 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 preferable.\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 be thrown by code\ndeeply nested inside the `try' block. However, note that it must be thrown inside the cur‐\nrent shell, not in a subshell forked for a pipeline, parenthesised current-shell construct,\nor some form of command or process substitution.\n\nThe system internally uses the shell variable EXCEPTION to record the name of the exception\nbetween throwing and catching. One drawback of this scheme is that if the exception is not\nhandled the variable EXCEPTION remains set and may be incorrectly recognised as the name of\nan exception if a shell error subsequently occurs. Adding unset EXCEPTION at the start of\nthe outermost layer of any code that uses exception handling will eliminate this problem.\n", "subsections": [] }, "MIME FUNCTIONS": { "content": "Three functions are available to provide handling of files recognised by extension, for exam‐\nple to dispatch a file text.ps when executed as a command 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 /etc/mime.types, which associate\ntypes and extensions, as well as ~/.mailcap and /etc/mailcap files, which associate\ntypes and the programs that handle them. These are provided on many systems with the\nMultimedia Internet Mail Extensions.\n\nTo enable the system, the function zsh-mime-setup should be autoloaded and run. This\nallows files with extensions to be treated as executable; such files be completed by\nthe function completion system. The function zsh-mime-handler should not need to be\ncalled by the user.\n\nThe system works by setting up suffix aliases with `alias -s'. Suffix aliases already\ninstalled by the user will not be overwritten.\n\nFor suffixes defined in lower case, upper case variants will also automatically be\nhandled (e.g. PDF is automatically handled if handling for the suffix pdf is defined),\nbut not vice versa.\n\nRepeated calls to zsh-mime-setup do not override the existing mapping between suffixes\nand executable files unless the option -f is given. Note, however, that this does not\noverride existing suffix aliases assigned to handlers other than zsh-mime-handler.\n\nCalling zsh-mime-setup with the option -l lists the existing mappings without altering\nthem. Suffixes to list (which may contain pattern characters that should be quoted\nfrom immediate interpretation on the command line) may be given as additional argu‐\nments, otherwise all suffixes are listed.\n\nCalling zsh-mime-setup with the option -v causes verbose output to be shown during the\nsetup operation.\n\nThe system respects the mailcap flags needsterminal and copiousoutput, see mailcap(4).\n\nThe functions use the following styles, which are defined with the zstyle builtin com‐\nmand (see zshmodules(1)). They should be defined before zsh-mime-setup is run. The\ncontexts used all start with :mime:, with additional components in some cases. It is\nrecommended that a trailing * (suitably quoted) be appended to style patterns in case\nthe system is extended in future. Some examples are given below.\n\nFor files that have multiple suffixes, e.g. .pdf.gz, where the context includes the\nsuffix it will be looked up starting with the longest possible suffix until a match\nfor the style is found. For example, if .pdf.gz produces a match for the handler,\nthat will be used; otherwise the handler for .gz will be used. Note that, owing to\nthe way suffix aliases work, it is always required that there be a handler for the\nshortest possible suffix, so in this example .pdf.gz can only be handled if .gz is\nalso handled (though not necessarily in the same way). Alternatively, if no handling\nfor .gz on its own is needed, simply adding the command\n\nalias -s gz=zsh-mime-handler\n\nto the initialisation code is sufficient; .gz will not be handled on its own, but may\nbe in combination with other suffixes.\n\ncurrent-shell\nIf this boolean style is true, the mailcap handler for the context in question\nis run using the eval builtin instead of by starting a new sh process. This is\nmore efficient, but may not work in the occasional cases where the mailcap han‐\ndler uses strict POSIX syntax.\n\ndisown If this boolean style is true, mailcap handlers started in the background will\nbe disowned, i.e. not subject to job control within the parent shell. Such\nhandlers nearly always produce their own windows, so the only likely harmful\nside effect of setting the style is that it becomes harder to kill jobs from\nwithin the shell.\n\nexecute-as-is\nThis style gives a list of patterns to be matched against files passed for exe‐\ncution with a handler program. If the file matches the pattern, the entire\ncommand line is executed in its current form, with no handler. This is useful\nfor files which might have suffixes but nonetheless be executable in their own\nright. If the style is not set, the pattern *(*) *(/) is used; hence exe‐\ncutable files are executed directly and not passed to a handler, and the option\nAUTOCD may be used to change to directories that happen to have MIME suffixes.\n\nexecute-never\nThis style is useful in combination with execute-as-is. It is set to an array\nof patterns corresponding to full paths to files that should never be treated\nas executable, even if the file passed to the MIME handler matches exe‐‐\ncute-as-is. This is useful for file systems that don't handle execute permis‐\nsion or that contain executables from another operating system. For example,\nif /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 executed as MIME types\neven if they are executable. As this example shows, the complete file name is\nmatched against the pattern, regardless of how the file was passed to the han‐\ndler. The file is resolved to a full path using the :P modifier described in\nthe subsection Modifiers in zshexpn(1); this means that symbolic links are re‐\nsolved where possible, so that links into other file systems behave in the cor‐\nrect fashion.\n\nfile-path\nUsed if the style find-file-in-path is true for the same context. Set to an\narray of directories that are used for searching for the file to be handled;\nthe default is the command path given by the special parameter path. The shell\noption PATHDIRS is respected; if that is set, the appropriate path will be\nsearched even if the name of the file to be handled as it appears on the com‐\nmand line contains a `/'. The full context is :mime:.suffix:, as described for\nthe style handler.\n\nfind-file-in-path\nIf set, allows files whose names do not contain absolute paths to be searched\nfor in the command path or the path specified by the file-path style. If the\nfile is not found in the path, it is looked for locally (whether or not the\ncurrent directory is in the path); if it is not found locally, the handler will\nabort unless the handle-nonexistent style is set. Files found in the path are\ntested as described for the style execute-as-is. The full context is\n:mime:.suffix:, as described for the style handler.\n\nflags Defines flags to go with a handler; the context is as for the handler style,\nand the format is as for the flags in mailcap.\n\nhandle-nonexistent\nBy default, arguments that don't correspond to files are not passed to the MIME\nhandler in order to prevent it from intercepting commands found in the path\nthat happen to have suffixes. This style may be set to an array of extended\nglob patterns for arguments that will be passed to the handler even if they\ndon't exist. If it is not explicitly set it defaults to [[:alpha:]]#:/* which\nallows URLs to be passed to the MIME handler even though they don't exist in\nthat format in the file system. The full context is :mime:.suffix:, as de‐\nscribed for the style handler.\n\nhandler\nSpecifies a handler for a suffix; the suffix is given by the context as\n:mime:.suffix:, and the format of the handler is exactly that in mailcap. Note\nin particular the `.' and trailing colon to distinguish this use of the con‐\ntext. This overrides any handler specified by the mailcap files. If the han‐\ndler requires a terminal, the flags style should be set to include the word\nneedsterminal, or if the output is to be displayed through a pager (but not if\nthe handler is itself a pager), it should include copiousoutput.\n\nmailcap\nA list of files in the format of ~/.mailcap and /etc/mailcap to be read during\nsetup, replacing the default list which consists of those two files. The con‐\ntext is :mime:. A + in the list will be replaced by the default files.\n\nmailcap-priorities\nThis style is used to resolve multiple mailcap entries for the same MIME type.\nIt consists of an array of the following elements, in descending order of pri‐\nority; later entries will be used if earlier entries are unable to resolve the\nentries being compared. If none of the tests resolve the entries, the first\nentry encountered is retained.\n\nfiles The order of files (entries in the mailcap style) read. Earlier files\nare preferred. (Note this does not resolve entries in the same file.)\n\npriority\nThe priority flag from the mailcap entry. The priority is an integer\nfrom 0 to 9 with the default value being 5.\n\nflags The test given by the mailcap-prio-flags option is used to resolve en‐\ntries.\n\nplace Later entries are preferred; as the entries are strictly ordered, this\ntest always succeeds.\n\nNote that as this style is handled during initialisation, the context is always\n:mime:, with no discrimination by suffix.\n\nmailcap-prio-flags\nThis style is used when the keyword flags is encountered in the list of tests\nspecified by the mailcap-priorities style. It should be set to a list of pat‐\nterns, each of which is tested against the flags specified in the mailcap entry\n(in other words, the sets of assignments found with some entries in the mailcap\nfile). Earlier patterns in the list are preferred to later ones, and matched\npatterns are preferred to unmatched ones.\n\nmime-types\nA list of files in the format of ~/.mime.types and /etc/mime.types to be read\nduring setup, replacing the default list which consists of those two files.\nThe context is :mime:. A + in the list will be replaced by the default files.\n\nnever-background\nIf this boolean style is set, the handler for the given context is always run\nin the foreground, even if the flags provided in the mailcap entry suggest it\nneed not be (for example, it doesn't require a terminal).\n\npager If set, will be used instead of $PAGER or more to handle suffixes where the co‐‐\npiousoutput flag is set. The context is as for handler, i.e. :mime:.suffix:\nfor handling a 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 mailcap entries in the two\nfiles given. Files of suffix .txt will be handled by running `less file.txt'. The\nflag needsterminal is set to show that this program must run attached to a terminal.\n\nAs there are several steps to dispatching a command, the following should be checked\nif attempting to execute a file by extension .ext does not have the expected effect.\n\nThe command `alias -s ext' should show `ps=zsh-mime-handler'. If it shows something\nelse, another suffix alias was already installed and was not overwritten. If it shows\nnothing, no handler was installed: this is most likely because no handler was found\nin the .mime.types and mailcap combination for .ext files. In that case, appropriate\nhandling should be added to ~/.mime.types and mailcap.\n\nIf the extension is handled by zsh-mime-handler but the file is not opened correctly,\neither the handler defined for the type is incorrect, or the flags associated with it\nare in appropriate. Running zsh-mime-setup -l will show the handler and, if there are\nany, the flags. A %s in the handler is replaced by the file (suitably quoted if nec‐\nessary). Check that the handler program listed lists and can be run in the way shown.\nAlso check that the flags needsterminal or copiousoutput are set if the handler needs\nto be run under a terminal; the second flag is used if the output should be sent to a\npager. An example of a suitable mailcap 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 line that would be exe‐\ncuted, simplified to remove the effect of any flags, and quoted so that the output can\nbe run as a complete zsh command line. This is used by the completion system to de‐\ncide how to complete after a file handled by zsh-mime-setup.\n", "subsections": [ { "name": "pick-web-browser", "content": "This function is separate from the two MIME functions described above and can be as‐\nsigned 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 browser. It may be run\nas either a function or a shell script. The status 255 is returned if no browser\ncould be started.\n\nVarious styles are available to customize the choice of browsers:\n\nbrowser-style\nThe value of the style is an array giving preferences in decreasing order for\nthe type of browser to use. The values of elements may be\n\nrunning\nUse a GUI browser that is already running when an X Window display is\navailable. The browsers listed in the x-browsers style are tried in or‐\nder until one is found; if it is, the file will be displayed in that\nbrowser, so the user may need to check whether it has appeared. If no\nrunning browser is found, one is not started. Browsers other than Fire‐\nfox, Opera and Konqueror are assumed to understand the Mozilla syntax\nfor opening a URL remotely.\n\nx Start a new GUI browser when an X Window display is available. Search\nfor the availability of one of the browsers listed in the x-browsers\nstyle and start the first one that is found. No check is made for an\nalready running browser.\n\ntty Start a terminal-based browser. Search for the availability of one of\nthe browsers listed in the tty-browsers style and start the first one\nthat is found.\n\nIf the style is not set the default running x tty is used.\n\nx-browsers\nAn array in decreasing order of preference of browsers to use when running un‐\nder the X Window System. The array consists of the command name under which to\nstart the browser. They are looked up in the context :mime: (which may be ex‐\ntended in future, so appending `*' is recommended). For example,\n\nzstyle ':mime:*' x-browsers opera konqueror firefox\n\nspecifies that pick-web-browser should first look for a running instance of\nOpera, Konqueror or Firefox, in that order, and if it fails to find any should\nattempt to start Opera. The default is firefox mozilla netscape opera kon‐‐\nqueror.\n\ntty-browsers\nAn array similar to x-browsers, except that it gives browsers to use when no X\nWindow display is available. The default is elinks links lynx.\n\ncommand\nIf it is set this style is used to pick the command used to open a page for a\nbrowser. The context is :mime:browser:new:$browser: to start a new browser or\n:mime:browser:running:$browser: to open a URL in a browser already running on\nthe current X display, where $browser is the value matched in the x-browsers or\ntty-browsers style. The escape sequence %b in the style's value will be re‐\nplaced by the browser, while %u will be replaced by the URL. If the style is\nnot set, the default for all new instances is equivalent to %b %u and the de‐\nfaults for using running browsers are equivalent to the values kfmclient\nopenURL %u for Konqueror, firefox -new-tab %u for Firefox, opera -newpage %u\nfor Opera, and %b -remote \"openUrl(%u)\" for all others.\n" } ] }, "MATHEMATICAL FUNCTIONS": { "content": "zcalc [ -erf ] [ expression ... ]\nA reasonably powerful calculator based on zsh's arithmetic evaluation facility. The\nsyntax is similar to that of formulae in most programming languages; see the section\n`Arithmetic Evaluation' in zshmisc(1) for details.\n\nNon-programmers should note that, as in many other programming languages, expressions\ninvolving only integers (whether constants without a `.', variables containing such\nconstants as strings, or variables declared to be integers) are by default evaluated\nusing integer arithmetic, which is not how an ordinary desk calculator operates. To\nforce floating point operation, pass the option -f; see further notes below.\n\nIf the file ~/.zcalcrc exists it will be sourced inside the function once it is set up\nand about to process the command line. This can be used, for example, to set shell\noptions; emulate -L zsh and setopt extendedglob are in effect at this point. Any\nfailure to source the file if it exists is treated as fatal. As with other initiali‐\nsation files, the directory $ZDOTDIR is used instead of $HOME if it is set.\n\nThe mathematical library zsh/mathfunc will be loaded if it is available; see the sec‐\ntion `The zsh/mathfunc Module' in zshmodules(1). The mathematical functions corre‐\nspond to the raw system libraries, so trigonometric functions are evaluated using ra‐\ndians, and so on.\n\nEach line typed is evaluated as an expression. The prompt shows a number, which cor‐\nresponds to a positional parameter where the result of that calculation is stored.\nFor example, the result of the calculation on the line preceded by `4> ' is available\nas $4. The last value calculated is available as ans. Full command line editing, in‐\ncluding the history of previous calculations, is available; the history is saved in\nthe file ~/.zcalchistory. To exit, enter a blank line or type `:q' on its own (`q'\nis allowed for historical compatibility).\n\nA line ending with a single backslash is treated in the same fashion as it is in com‐\nmand line editing: the backslash is removed, the function prompts for more input (the\nprompt is preceded by `...' to indicate this), and the lines are combined into one to\nget the final result. In addition, if the input so far contains more open than close\nparentheses zcalc will prompt for more input.\n\nIf arguments are given to zcalc on start up, they are used to prime the first few po‐\nsitional parameters. A visual indication of this is given when the calculator starts.\n\nThe constants PI (3.14159...) and E (2.71828...) are provided. Parameter assignment\nis possible, but note that all parameters will be put into the global namespace unless\nthe :local special command is used. The function creates local variables whose names\nstart with , so users should avoid doing so. The variables ans (the last answer) and\nstack (the stack in RPN mode) may be referred to directly; stack is an array but ele‐\nments of it are numeric. Various other special variables are used locally with their\nstandard meaning, for example compcontext, match, mbegin, mend, psvar.\n\nThe output base can be initialised by passing the option `-#base', for example `zcalc\n-#16' (the `#' may have to be quoted, depending on the globbing options set).\n\nIf the option `-e' is set, the function runs non-interactively: the arguments are\ntreated as expressions to be evaluated as if entered interactively line by line.\n\nIf the option `-f' is set, all numbers are treated as floating point, hence for exam‐\nple the expression `3/4' evaluates to 0.75 rather than 0. Options must appear in sep‐\narate words.\n\nIf the option `-r' is set, RPN (Reverse Polish Notation) mode is entered. This has\nvarious additional properties:\nStack Evaluated values are maintained in a stack; this is contained in an array named\nstack with the most recent value in ${stack[1]}.\n\nOperators and functions\nIf the line entered matches an operator (+, -, *, /, , ^, | or &) or a func‐\ntion supplied by the zsh/mathfunc library, the bottom element or elements of\nthe stack are popped to use as the argument or arguments. The higher elements\nof stack (least recent) are used as earlier arguments. The result is then\npushed into ${stack[1]}.\n\nExpressions\nOther expressions are evaluated normally, printed, and added to the stack as\nnumeric values. The syntax within expressions on a single line is normal shell\narithmetic (not RPN).\n\nStack listing\nIf an integer follows the option -r with no space, then on every evaluation\nthat many elements of the stack, where available, are printed instead of just\nthe most recent result. Hence, for example, zcalc -r4 shows $stack[4] to\n$stack[1] each time results are printed.\n\nDuplication: =\nThe pseudo-operator = causes the most recent element of the stack to be dupli‐\ncated onto the stack.\n\npop The pseudo-function pop causes the most recent element of the stack to be\npopped. A `>' on its own has the same effect.\n\n>ident The expression > followed (with no space) by a shell identifier causes the most\nrecent element of the stack to be popped and assigned to the variable with that\nname. The variable is local to the zcalc function.\n\n in the standard zcalc prompt) is put on the stack.\n\nExchange: xy\nThe pseudo-function xy causes the most recent two elements of the stack to be\nexchanged. `<>' has the same effect.\n\nThe prompt is configurable via the parameter ZCALCPROMPT, which undergoes standard\nprompt expansion. The index of the current entry is stored locally in the first ele‐\nment of the array psvar, which can be referred to in ZCALCPROMPT as `%1v'. The de‐\nfault prompt is `%1v> '.\n\nThe variable ZCALCACTIVE is set within the function and can be tested by nested func‐\ntions; it has the value rpn if RPN mode is active, else 1.\n\nA few special commands are available; these are introduced by a colon. For backward\ncompatibility, the colon may be omitted for certain commands. Completion is available\nif compinit has been run.\n\nThe output precision may be specified within zcalc by special commands familiar from\nmany calculators.\n:norm The default output format. It corresponds to the printf %g specification.\nTypically this shows six decimal digits.\n\n:sci digits\nScientific notation, corresponding to the printf %g output format with the pre‐\ncision given by digits. This produces either fixed point or exponential nota‐\ntion depending on the value output.\n\n:fix digits\nFixed point notation, corresponding to the printf %f output format with the\nprecision given by digits.\n\n:eng digits\nExponential notation, corresponding to the printf %E output format with the\nprecision given by digits.\n\n:raw Raw output: this is the default form of the output from a math evaluation.\nThis may show more precision than the number actually possesses.\n\nOther special commands:\n:!line...\nExecute line... as a normal shell command line. Note that it is executed in\nthe context of the function, i.e. with local variables. Space is optional af‐\nter :!.\n\n:local arg ...\nDeclare variables local to the function. Other variables may be used, too, but\nthey will be taken from or put into the global scope.\n\n:function name [ body ]\nDefine a mathematical function or (with no body) delete it. :function may be\nabbreviated to :func or simply :f. The name may contain the same characters as\na shell function name. The function is defined using zmathfuncdef, see below.\n\nNote that zcalc takes care of all quoting. Hence for example:\n\n:f cube $1 * $1 * $1\n\ndefines a function to cube the sole argument. Functions so defined, or indeed\nany functions defined directly or indirectly using functions -M, are available\nto execute by typing only the name on the line in RPN mode; this pops the ap‐\npropriate number of arguments off the stack to pass to the function, i.e. 1 in\nthe case of the example cube function. If there are optional arguments only\nthe mandatory arguments are supplied by this means.\n\n[#base]\nThis is not a special command, rather part of normal arithmetic syntax; how‐\never, when this form appears on a line by itself the default output radix is\nset to base. Use, for example, `[#16]' to display hexadecimal output preceded\nby an indication of the base, or `[##16]' just to display the raw number in the\ngiven base. Bases themselves are always specified in decimal. `[#]' restores\nthe normal output format. Note that setting an output base suppresses floating\npoint output; use `[#]' to return to normal operation.\n\n$var Print out the value of var literally; does not affect the calculation. To use\nthe value of var, omit the leading `$'.\n\nSee the comments in the function for a few extra tips.\n\nmin(arg, ...)\nmax(arg, ...)\nsum(arg, ...)", "subsections": [ { "name": "zmathfunc", "content": "The function zmathfunc defines the three mathematical functions min, max, and sum.\nThe functions min and max take one or more arguments. The function sum takes zero or\nmore arguments. Arguments can be of different types (ints and floats).\n\nNot to be confused with the zsh/mathfunc module, described in the section `The\nzsh/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 mathfunc which can be used in\nany form of arithmetic evaluation. body is a mathematical expression to implement the\nfunction. It may contain references to position parameters $1, $2, ... to refer to\nmandatory parameters and ${1:-defvalue} ... to refer to optional parameters. Note\nthat the forms must be strictly adhered to for the function to calculate the correct\nnumber of arguments. The implementation is held in a shell function named\nzshmathfuncmathfunc; usually the user will not need to refer to the shell function\ndirectly. Any existing function of the same name is silently replaced.\n\nWith one argument, remove the mathematical function mathfunc as well as the shell\nfunction implementation.\n\nWith no arguments, list all mathfunc functions in a form suitable for restoring the\ndefinition. The functions have not necessarily been defined by zmathfuncdef.\n" } ] }, "USER CONFIGURATION FUNCTIONS": { "content": "The zsh/newuser module comes with a function to aid in configuring shell options for new\nusers. If the module is installed, this function can also be run by hand. It is available\neven if the module's default behaviour, namely running the function for a new user logging in\nwithout startup files, is inhibited.\n\nzsh-newuser-install [ -f ]\nThe function presents the user with various options for customizing their initializa‐\ntion scripts. Currently only ~/.zshrc is handled. $ZDOTDIR/.zshrc is used instead if\nthe parameter ZDOTDIR is set; this provides a way for the user to configure a file\nwithout altering an existing .zshrc.\n\nBy default the function exits immediately if it finds any of the files .zshenv, .zpro‐‐\nfile, .zshrc, or .zlogin in the appropriate directory. The option -f is required in\norder to force the function to continue. Note this may happen even if .zshrc itself\ndoes not exist.\n\nAs currently configured, the function will exit immediately if the user has root priv‐\nileges; this behaviour cannot be overridden.\n\nOnce activated, the function's behaviour is supposed to be self-explanatory. Menus\nare present allowing the user to alter the value of options and parameters. Sugges‐\ntions for improvements are always welcome.\n\nWhen the script exits, the user is given the opportunity to save the new file or not;\nchanges are not irreversible until this point. However, the script is careful to re‐\nstrict changes to the file only to a group marked by the lines `# Lines configured by\nzsh-newuser-install' and `# End of lines configured by zsh-newuser-install'. In addi‐\ntion, the old version of .zshrc is saved to a file with the suffix .zni appended.\n\nIf the function edits an existing .zshrc, it is up to the user to ensure that the\nchanges made will take effect. For example, if control usually returns early from the\nexisting .zshrc the lines will not be executed; or a later initialization file may\noverride options or parameters, and so on. The function itself does not attempt to\ndetect any such conflicts.\n", "subsections": [] }, "OTHER FUNCTIONS": { "content": "There are a large number of helpful functions in the Functions/Misc directory of the zsh dis‐\ntribution. Most are very simple and do not require documentation here, but a few are worthy\nof special mention.\n", "subsections": [ { "name": "Descriptions", "content": "colors This function initializes several associative arrays to map color names to (and from)\nthe ANSI standard eight-color terminal codes. These are used by the prompt theme sys‐\ntem (see above). You seldom should need to run colors more than once.\n\nThe eight base colors are: black, red, green, yellow, blue, magenta, cyan, and white.\nEach of these has codes for foreground and background. In addition there are seven\nintensity attributes: bold, faint, standout, underline, blink, reverse, and conceal.\nFinally, there are seven codes used to negate attributes: none (reset all attributes\nto the defaults), normal (neither bold nor faint), no-standout, no-underline,\nno-blink, no-reverse, and no-conceal.\n\nSome terminals do not support all combinations of colors and intensities.\n\nThe associative arrays are:\n\ncolor\ncolour Map all the color names to their integer codes, and integer codes to the color\nnames. The eight base names map to the foreground color codes, as do names\nprefixed with `fg-', such as `fg-red'. Names prefixed with `bg-', such as\n`bg-blue', refer to the background codes. The reverse mapping from code to\ncolor yields base name for foreground codes and the bg- form for backgrounds.\n\nAlthough it is a misnomer to call them `colors', these arrays also map the\nother fourteen attributes from names to codes and codes to names.\n\nfg\nfgbold\nfgnobold\nMap the eight basic color names to ANSI terminal escape sequences that set the\ncorresponding foreground text properties. The fg sequences change the color\nwithout changing the eight intensity attributes.\n\nbg\nbgbold\nbgnobold\nMap the eight basic color names to ANSI terminal escape sequences that set the\ncorresponding background properties. The bg sequences change the color without\nchanging the eight intensity attributes.\n\nIn addition, the scalar parameters resetcolor and boldcolor are set to the ANSI ter‐\nminal escapes that turn off all attributes and turn on bold intensity, respectively.\n\nfned [ -x num ] name\nSame as zed -f. This function does not appear in the zsh distribution, but can be\ncreated by linking zed to the name fned in some directory in your fpath.\n\nis-at-least needed [ present ]\nPerform a greater-than-or-equal-to comparison of two strings having the format of a\nzsh version number; that is, a string of numbers and text with segments separated by\ndots or dashes. If the present string is not provided, $ZSHVERSION is used. Seg‐\nments are paired left-to-right in the two strings with leading non-number parts ig‐\nnored. If one string has fewer segments than the other, the missing segments are con‐\nsidered zero.\n\nThis is useful in startup files to set options and other state that are not available\nin 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 zsh/zpty module (see zsh‐\nmodules(1)). It behaves exactly like the standard nslookup except that it provides\ncustomizable prompts (including a right-side prompt) and completion of nslookup com‐\nmands, host names, etc. (if you use the function-based completion system). Completion\nstyles may be set with 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 operation on a vari‐\nable. POSIX extended regular expressions are used, unless the option REMATCHPCRE\nhas been set, in which case Perl-compatible regular expressions are used (this re‐\nquires the shell to be linked against the pcre library).\n\nvar is the name of the variable containing the string to be matched. The variable\nwill be modified directly by the function. The variables MATCH, MBEGIN, MEND, match,\nmbegin, mend should be avoided as these are used by the regular expression code.\n\nregexp is the regular expression to match against the string.\n\nreplace is the replacement text. This can contain parameter, command and arithmetic\nexpressions which will be replaced: in particular, a reference to $MATCH will be re‐\nplaced by the text matched by the pattern.\n\nThe return status is 0 if at least one match was performed, else 1.\n\nrun-help cmd\nThis function is designed to be invoked by the run-help ZLE widget, in place of the\ndefault alias. See `Accessing On-Line Help' above for setup instructions.\n\nIn the discussion which follows, if cmd is a file system path, it is first reduced to\nits rightmost component (the file name).\n\nHelp is first sought by looking for a file named cmd in the directory named by the\nHELPDIR parameter. If no file is found, an assistant function, alias, or command\nnamed run-help-cmd is sought. If found, the assistant is executed with the rest of\nthe current command line (everything after the command name cmd) as its arguments.\nWhen neither file nor assistant is found, the external 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 directory. These must\nbe autoloaded, or placed as executable scripts in your search path, in order to be\nfound and used by run-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, svk, and svn, commands.\n\ntetris Zsh was once accused of not being as complete as Emacs, because it lacked a Tetris\ngame. This function was written to refute this 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. Whatever command line you\nwere editing disappears temporarily, and your keymap is also temporarily replaced by\nthe Tetris control keys. The previous editor state is restored when you quit the game\n(by pressing `q') or when you lose.\n\nIf you quit in the middle of a game, the next invocation of the tetris widget will\ncontinue where you left off. If you lost, it will start a new game.\n" }, { "name": "tetriscurses", "content": "This is a port of the above to zcurses. The input handling is improved a bit so that\nmoving a block sideways doesn't automatically advance a timestep, and the graphics use\nunicode block graphics.\n\nThis version does not save the game state between invocations, and is not invoked as a\nwidget, 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 reading lines of argu‐\nments from the standard input, it takes them from the command line. This is useful\nbecause zsh, especially with recursive glob operators, often can construct a command\nline for a shell function that is longer than can be accepted by an external command.\n\nThe option list represents options of the zargs command itself, which are the same as\nthose of xargs. The input list is the collection of strings (often file names) that\nbecome the arguments of the command, analogous to the standard input of xargs. Fi‐\nnally, the arg list consists of those arguments (usually options) that are passed to\nthe command each time it runs. The arg list precedes the elements from the input list\nin each run. If no command is provided, then no arg list may be provided, and in that\nevent the default command is `print' with arguments `-r --'.\n\nFor example, to get a long ls listing of all non-hidden plain files in the current di‐\nrectory or its subdirectories:\n\nautoload -U zargs\nzargs -- /*(.) -- ls -ld --\n\nThe first and third occurrences of `--' are used to mark the end of options for zargs\nand ls respectively to guard against filenames starting with `-', while the second is\nused to separate the list of files from the command to run (`ls -ld --').\n\nThe first `--' would also be needed if there was a chance the list might be empty as\nin:\n\nzargs -r -- ./*.back(#qN) -- rm -f\n\nIn the event that the string `--' is or may be an input, the -e option may be used to\nchange the end-of-inputs marker. Note that this does not change the end-of-options\nmarker. For example, to use `..' as the marker:\n\nzargs -e.. -- /*(.) .. ls -ld --\n\nThis is a good choice in that example because no plain file can be named `..', but the\nbest end-marker depends on the circumstances.\n\nThe options -i, -I, -l, -L, and -n differ slightly from their usage in xargs. There\nare no input lines for zargs to count, so -l and -L count through the input list, and\n-n counts the number of arguments passed to each execution of command, including any\narg list. Also, any time -i or -I is used, each input is processed separately as if\nby `-L 1'.\n\nFor details of the other zargs options, see xargs(1) (but note the difference in func‐\ntion between zargs and xargs) or run zargs with 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, the name is taken to be\nthat of a function; if the function is marked for autoloading, zed searches for it in\nthe fpath and loads it. Note that functions edited this way are installed into the\ncurrent shell, but not written back to the autoload file. In this case the -x option\nspecifies that leading tabs indenting the function according to syntax should be con‐\nverted into the given number of spaces; `-x 2' is consistent with the layout of func‐\ntions distributed with the shell.\n\nWithout -f, name is the path name of the file to edit, which need not exist; it is\ncreated on write, if necessary.\n\nWhile editing, the function sets the main keymap to zed and the vi command keymap to\nzed-vicmd. These will be copied from the existing main and vicmd keymaps if they do\nnot exist the first time zed is run. They can be used to provide special key bindings\nused only in zed.\n\nIf it creates the keymap, zed rebinds the return key to insert a line break and `^X^W'\nto accept the edit in the zed keymap, and binds `ZZ' to accept the edit in the\nzed-vicmd keymap.\n\nThe bindings alone can be installed by running `zed -b'. This is suitable for putting\ninto a startup file. Note that, if rerun, this will overwrite the existing zed and\nzed-vicmd keymaps.\n\nCompletion is available, and styles may be set with the context prefix `:comple‐‐\ntion:zed'.\n\nA zle widget zed-set-file-name is available. This can be called by name from within\nzed using `\\ex zed-set-file-name' (note, however, that because of zed's rebindings you\nwill have to type ^j at the end instead of the return key), or can be bound to a key\nin either of the zed or zed-vicmd keymaps after `zed -b' has been run. When the wid‐\nget is called, it prompts for a new name for the file being edited. When zed exits\nthe file will be written under that name and the original file will be left alone.\nThe widget has no effect with `zed -f'.\n\nWhile zed-set-file-name is running, zed uses the keymap zed-normal-keymap, which is\nlinked from the main keymap in effect at the time zed initialised its bindings. (This\nis to make the return key operate normally.) The result is that if the main keymap\nhas been changed, the widget won't notice. This is not a concern for most users.\n\nzcp [ -finqQvwW ] srcpat dest\nzln [ -finqQsvwW ] srcpat dest\nSame as zmv -C and zmv -L, respectively. These functions do not appear in the zsh\ndistribution, but can be created by linking zmv to the names zcp and zln in some di‐\nrectory in your fpath.\n\nzkbd See `Keyboard Definition' above.\n\n\nzmv [ -finqQsvwW ] [ -C | -L | -M | -{p|P} program ] [ -o optstring ]\nsrcpat dest\nMove (usually, rename) files matching the pattern srcpat to corresponding files having\nnames of the form given by dest, where srcpat contains parentheses surrounding pat‐\nterns which will be replaced 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 `my.old.stuff.txt', and so on.\n\nThe pattern is always treated as an EXTENDEDGLOB pattern. Any file whose name is not\nchanged by the substitution is simply ignored. Any error (a substitution resulted in\nan empty string, two substitutions gave the same result, the destination was an exist‐\ning regular file and -f was not given) causes the entire function to abort without do‐\ning anything.\n\nIn addition to pattern replacement, the variable $f can be referrred to in the second\n(replacement) argument. This makes it possible to use variable substitution to alter\nthe argument; see examples below.\n\nOptions:\n\n-f Force overwriting of destination files. Not currently passed down to the\nmv/cp/ln command due to vagaries of implementations (but you can use -o-f to do\nthat).\n-i Interactive: show each line to be executed and ask the user whether to execute\nit. `Y' or `y' will execute it, anything else will skip it. Note that you\njust need to type 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 this has no effect.\n-Q Force bare glob qualifiers on. Don't turn this on unless you are actually us‐\ning 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 above, and implicitly add\nparentheses for referring to them.\n-W Just like -w, with the addition of turning wildcards in the replacement pattern\ninto sequential ${1} .. ${N} references.\n-C\n-L\n-M Force cp, ln or mv, respectively, regardless of the name of the function.\n-p program\nCall program instead of cp, ln or mv. Whatever it does, it should at least un‐\nderstand the form `program -- oldname newname' where oldname and newname are\nfilenames generated by zmv. program will be split into words, so might be e.g.\nthe name of an archive tool plus a copy or rename subcommand.\n-P program\nAs -p program, except that program does not accept a following -- to indicate\nthe end of options. In this case filenames must already be in a sane form for\nthe program in question.\n-o optstring\nThe optstring is split into words and passed down verbatim to the cp, ln or mv\ncommand called to perform the work. 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 the name, replace ev‐\nery space by an underscore and display the commands executed.\n\nzmv -v '* *' '${f// /}'\n\nThis does exactly the same by referring to the file name stored in $f.\n\nFor more complete examples and other implementation details, see the zmv source file,\nusually located in one of the directories named in your fpath, or in Func‐‐\ntions/Misc/zmv in the zsh distribution.\n" }, { "name": "zrecompile", "content": "See `Recompiling Functions' above.\n\nzstyle+ context style value [ + subcontext style value ... ]\nThis makes defining styles a bit simpler by using a single `+' as a special token that\nallows you to append a context name to the 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 usual, but it also defines\nstyle2 with value2 for the context :foo:bar:baz and style3 with value3 for\n:foo:bar:frob. Any subcontext may be the empty string to re-use the first context un‐\nchanged.\n" }, { "name": "Styles", "content": "" }, { "name": "insert-tab", "content": "The zed function sets this style in context `:completion:zed:*' to turn off completion\nwhen TAB is typed at the beginning of a line. You may override this by setting your\nown value for this context and style.\n\npager The nslookup function looks up this style in the context `:nslookup' to determine the\nprogram used to display output that does not fit on a single screen.\n" }, { "name": "prompt", "content": "" }, { "name": "rprompt", "content": "The nslookup function looks up this style in the context `:nslookup' to set the prompt\nand the right-side prompt, respectively. The usual expansions for the PS1 and RPS1\nparameters may be used (see EXPANSION OF PROMPT SEQUENCES in zshmisc(1)).\n\n\n\nZSHALL(1) General Commands Manual ZSHALL(1)\n\n\n" } ] }, "FILES": { "content": "", "subsections": [ { "name": "$ZDOTDIR/.zshenv", "content": "" }, { "name": "$ZDOTDIR/.zprofile", "content": "" }, { "name": "$ZDOTDIR/.zshrc", "content": "" }, { "name": "$ZDOTDIR/.zlogin", "content": "" }, { "name": "$ZDOTDIR/.zlogout", "content": "${TMPPREFIX}* (default is /tmp/zsh*)" }, { "name": "/etc/zsh/zshenv", "content": "" }, { "name": "/etc/zsh/zprofile", "content": "" }, { "name": "/etc/zsh/zshrc", "content": "" }, { "name": "/etc/zsh/zlogin", "content": "/etc/zsh/zlogout (installation-specific - /etc is the default)\n" } ] }, "SEE ALSO": { "content": "sh(1), csh(1), tcsh(1), rc(1), bash(1), ksh(1)\n", "subsections": [ { "name": "IEEE Standard for information Technology - Portable Operating System Interface (POSIX) - Part", "content": "2: Shell and Utilities, IEEE Inc, 1993, ISBN 1-55937-255-9.\n\n\n\nzsh 5.8.1 February 12, 2022 ZSHALL(1)" } ] } }, "summary": "zshall - the Z shell meta-man page", "flags": [], "examples": [ "compctl -u -x 's[+] c[-1,-f],s[-f+]' \\", "-g '~/Mail/*(:t)' - 's[-f],c[-1,-f]' -f -- mail", "This is to be interpreted as follows:", "If the current command is mail, then", "if ((the current word begins with + and the previous word is -f)", "or (the current word begins with -f+)), then complete the", "non-directory part (the `:t' glob modifier) of files in the directory", "~/Mail; else", "if the current word begins with -f or the previous word was -f, then", "complete any file; else", "complete user names.", "ZSHMODULES(1) General Commands Manual ZSHMODULES(1)" ], "see_also": [ { "name": "sh", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/sh/1/json" }, { "name": "csh", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/csh/1/json" }, { "name": "tcsh", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/tcsh/1/json" }, { "name": "rc", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/rc/1/json" }, { "name": "bash", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/bash/1/json" }, { "name": "ksh", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/ksh/1/json" } ] }