diff options
Diffstat (limited to 'Doc/zsh.texi')
| -rw-r--r-- | Doc/zsh.texi | 40574 |
1 files changed, 40574 insertions, 0 deletions
diff --git a/Doc/zsh.texi b/Doc/zsh.texi new file mode 100644 index 000000000..2a57fdf35 --- /dev/null +++ b/Doc/zsh.texi @@ -0,0 +1,40574 @@ +\input texinfo.tex +@c %**start of header +@iftex +@setchapternewpage off +@end iftex +@setfilename zsh.info +@settitle zsh +@c %**end of header + +@ifinfo +@set dsq '@:' +@set dsbq `@:` +@end ifinfo +@iftex +@set dsq '{}' +@set dsbq `{}` +@end iftex +@ifinfo +@dircategory Utilities +@direntry +* ZSH: (zsh). The Z Shell Manual. +@end direntry +@end ifinfo + +@iftex +@finalout +@end iftex +@titlepage +@title The Z Shell Manual +@subtitle Version 5.8 +@subtitle Updated February 14, 2020 +@author Original documentation by Paul Falstad +@page +This is a texinfo version of the documentation for the Z Shell, originally by +Paul Falstad. + +@noindent +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@noindent +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +@noindent +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end titlepage +@contents +@c Yodl file: Zsh/manual.yo +@ifnottex +@node Top, The Z Shell Manual, (dir), (dir) +@top The Z Shell Manual +@end ifnottex +@ifinfo +This Info file documents Zsh, a freely available UNIX command interpreter +(shell), which of the standard shells most closely resembles the Korn shell +(ksh), although it is not completely compatible. Zsh is able to emulate +POSIX shells, but its default mode is not POSIX compatible, either. + +@noindent +@cindex version +Version 5.8, last updated February 14, 2020. +@end ifinfo + +@menu +* The Z Shell Manual:: +* Introduction:: +* Roadmap:: +* Invocation:: +* Files:: +* Shell Grammar:: +* Redirection:: +* Command Execution:: +* Functions:: +* Jobs & Signals:: +* Arithmetic Evaluation:: +* Conditional Expressions:: +* Prompt Expansion:: +* Expansion:: +* Parameters:: +* Options:: +* Shell Builtin Commands:: +* Zsh Line Editor:: +* Completion Widgets:: +* Completion System:: +* Completion Using compctl:: +* Zsh Modules:: +* Calendar Function System:: +* TCP Function System:: +* Zftp Function System:: +* User Contributions:: + +@noindent +--- Indices --- + +@noindent +* Concept Index:: +* Variables Index:: +* Options Index:: +* Functions Index:: +* Editor Functions Index:: +* Style and Tag Index:: + +@noindent +--- The Detailed Node Listing --- + +@noindent +Introduction + +@noindent +* Author:: +* Availability:: +* Mailing Lists:: +* The Zsh FAQ:: +* The Zsh Web Page:: +* The Zsh Userguide:: +* See Also:: + +@noindent +Invocation + +@noindent +* Compatibility:: +* Restricted Shell:: + +@noindent +Shell Grammar + +@noindent +* Simple Commands & Pipelines:: +* Precommand Modifiers:: +* Complex Commands:: +* Alternate Forms For Complex Commands:: +* Reserved Words:: +* Comments:: +* Aliasing:: +* Quoting:: + +@noindent +Expansion + +@noindent +* History Expansion:: +* Process Substitution:: +* Parameter Expansion:: +* Command Substitution:: +* Arithmetic Expansion:: +* Brace Expansion:: +* Filename Expansion:: +* Filename Generation:: + +@noindent +Parameters + +@noindent +* Array Parameters:: +* Positional Parameters:: +* Local Parameters:: +* Parameters Set By The Shell:: +* Parameters Used By The Shell:: + +@noindent +Options + +@noindent +* Specifying Options:: +* Description of Options:: +* Option Aliases:: +* Single Letter Options:: + +@noindent +Zsh Line Editor + +@noindent +* Keymaps:: +* Zle Builtins:: +* Zle Widgets:: +* Character Highlighting:: + +@noindent +Completion Widgets + +@noindent +* Completion Special Parameters:: +* Completion Builtin Commands:: +* Completion Condition Codes:: +* Completion Matching Control:: +* Completion Widget Example:: + +@noindent +Completion System + +@noindent +* Initialization:: +* Completion System Configuration:: +* Control Functions:: +* Bindable Commands:: +* Completion Functions:: +* Completion Directories:: + +@noindent +Completion Using compctl + +@noindent +* Command Flags:: +* Option Flags:: +* Alternative Completion:: +* Extended Completion:: +* Example:: + +@noindent +Zsh Modules + +@noindent +@c Yodl file: Zsh/manmodmenu.yo +* The zsh/attr Module:: +* The zsh/cap Module:: +* The zsh/clone Module:: +* The zsh/compctl Module:: +* The zsh/complete Module:: +* The zsh/complist Module:: +* The zsh/computil Module:: +* The zsh/curses Module:: +* The zsh/datetime Module:: +* The zsh/db/gdbm Module:: +* The zsh/deltochar Module:: +* The zsh/example Module:: +* The zsh/files Module:: +* The zsh/langinfo Module:: +* The zsh/mapfile Module:: +* The zsh/mathfunc Module:: +* The zsh/nearcolor Module:: +* The zsh/newuser Module:: +* The zsh/parameter Module:: +* The zsh/pcre Module:: +* The zsh/param/private Module:: +* The zsh/regex Module:: +* The zsh/sched Module:: +* The zsh/net/socket Module:: +* The zsh/stat Module:: +* The zsh/system Module:: +* The zsh/net/tcp Module:: +* The zsh/termcap Module:: +* The zsh/terminfo Module:: +* The zsh/zftp Module:: +* The zsh/zle Module:: +* The zsh/zleparameter Module:: +* The zsh/zprof Module:: +* The zsh/zpty Module:: +* The zsh/zselect Module:: +* The zsh/zutil Module:: +@c (avoiding a yodl bug) + +@noindent +Calendar Function System + +@noindent +* Calendar File and Date Formats:: +* Calendar System User Functions:: +* Calendar Styles:: +* Calendar Utility Functions:: +* Calendar Bugs:: + +@noindent +TCP Function System + +@noindent +* TCP Functions:: +* TCP Parameters:: +* TCP Examples:: +* TCP Bugs:: + +@noindent +Zftp Function System + +@noindent +* Installation:: +* Zftp Functions:: +* Miscellaneous Features:: + +@noindent +User Contributions + +@noindent +* Utilities:: +* Recent Directories:: +* Other Directory Functions:: +* Version Control Information:: +* Prompt Themes:: +* ZLE Functions:: +* Exception Handling:: +* MIME Functions:: +* Mathematical Functions:: +* User Configuration Functions:: +* Other Functions:: + +@noindent +@end menu +@node The Z Shell Manual, Introduction, Top, Top + +@chapter The Z Shell Manual +@noindent +This document has been produced from the texinfo file @t{zsh.texi}, +included in the @t{Doc} sub-directory of the Zsh distribution. + +@section Producing documentation from zsh.texi +@noindent +The texinfo source may be converted into several formats: + +@noindent +@table @asis +@item The Info manual +The Info format allows searching for topics, commands, functions, etc. +from the many Indices. The command `@t{makeinfo zsh.texi}' is used to +produce the Info documentation. + +@item The printed manual +The command `@t{texi2dvi zsh.texi}' will output @t{zsh.dvi} which can +then be processed with @cite{dvips} and optionally @cite{gs} (Ghostscript) to +produce a nicely formatted printed manual. + +@item The HTML manual +An HTML version of this manual is available at the Zsh web site via: + +@noindent +@t{@uref{http://zsh.sourceforge.net/Doc/}}. + +@noindent +(The HTML version is produced with @cite{texi2html}, which may be obtained +from @t{@uref{http://www.nongnu.org/texi2html/}}. The command is +`@t{texi2html --output . --ifinfo --split=chapter --node-files zsh.texi}'. +If necessary, upgrade to version 1.78 of texi2html.) + +@end table + +@noindent +For those who do not have the necessary tools to process texinfo, +precompiled documentation (PostScript, dvi, PDF, info and HTML formats) +is available from the zsh archive site or its mirrors, in the file +@t{zsh-doc.tar.gz}. (See @ref{Availability} for a list of sites.) +@c (avoiding a yodl bug) +@c Yodl file: Zsh/intro.yo +@node Introduction, Roadmap, The Z Shell Manual, Top + +@chapter Introduction +@noindent +@cindex introduction +Zsh is a UNIX command interpreter (shell) usable as an interactive +login shell and as a shell script command processor. Of the standard shells, +zsh most closely resembles @cite{ksh} but includes many enhancements. It +does not provide compatibility with POSIX or other shells in its +default operating mode: see +the section @ref{Compatibility}. + +@noindent +Zsh has command line editing, builtin spelling correction, programmable +command completion, shell functions (with autoloading), a history +mechanism, and a host of other features. +@c Yodl file: Zsh/metafaq.yo +@menu +* Author:: +* Availability:: +* Mailing Lists:: +* The Zsh FAQ:: +* The Zsh Web Page:: +* The Zsh Userguide:: +* See Also:: +@end menu +@node Author, Availability, , Introduction + +@section Author +@noindent +@cindex author +Zsh was originally written by Paul Falstad @t{<pf@@zsh.org>}. +Zsh is now maintained by the members of the zsh-workers mailing +list @t{<zsh-workers@@zsh.org>}. The development is currently +coordinated by Peter Stephenson @t{<pws@@zsh.org>}. The coordinator +can be contacted at @t{<coordinator@@zsh.org>}, but matters relating to +the code should generally go to the mailing list. +@node Availability, Mailing Lists, Author, Introduction + +@section Availability +@noindent +Zsh is available from the following HTTP and anonymous FTP site. + +@noindent +@cindex FTP sites for zsh +@cindex acquiring zsh by FTP +@cindex availability of zsh +@t{@uref{ftp://ftp.zsh.org/pub/}}@* +@t{@uref{https://www.zsh.org/pub/}} +) + +@noindent +The up-to-date source code is available via Git from Sourceforge. See +@t{@uref{https://sourceforge.net/projects/zsh/}} for details. A summary of +instructions for the archive can be found at +@t{@uref{http://zsh.sourceforge.net/}}. + +@noindent +@node Mailing Lists, The Zsh FAQ, Availability, Introduction + +@section Mailing Lists +@noindent +@cindex mailing lists +Zsh has 3 mailing lists: + +@noindent +@table @asis +@item @t{<zsh-announce@@zsh.org>} +Announcements about releases, major changes in the shell and the +monthly posting of the Zsh FAQ. (moderated) + +@item @t{<zsh-users@@zsh.org>} +User discussions. + +@item @t{<zsh-workers@@zsh.org>} +Hacking, development, bug reports and patches. + +@end table + +@noindent +To subscribe or unsubscribe, send mail +to the associated administrative address for the mailing list. + +@noindent +@table @asis +@item @t{<zsh-announce-subscribe@@zsh.org>} +@item @t{<zsh-users-subscribe@@zsh.org>} +@item @t{<zsh-workers-subscribe@@zsh.org>} + +@noindent +@item @t{<zsh-announce-unsubscribe@@zsh.org>} +@item @t{<zsh-users-unsubscribe@@zsh.org>} +@item @t{<zsh-workers-unsubscribe@@zsh.org>} +@end table +@sp 1 + +@noindent +YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED. +All submissions to @cite{zsh-announce} are automatically forwarded to +@cite{zsh-users}. All submissions to @cite{zsh-users} are automatically +forwarded to @cite{zsh-workers}. + +@noindent +If you have problems subscribing/unsubscribing to any of the mailing +lists, send mail to @t{<listmaster@@zsh.org>}. The mailing lists are +maintained by Karsten Thygesen @t{<karthy@@kom.auc.dk>}. + +@noindent +The mailing lists are archived; the archives can be accessed via the +administrative addresses listed above. There is also a hypertext +archive, maintained by Geoff Wing @t{<gcw@@zsh.org>}, available at +@t{@uref{https://www.zsh.org/mla/}}. +@node The Zsh FAQ, The Zsh Web Page, Mailing Lists, Introduction + +@section The Zsh FAQ +@noindent +Zsh has a list of Frequently Asked Questions (FAQ), maintained by +Peter Stephenson @t{<pws@@zsh.org>}. It is regularly posted to the +newsgroup @cite{comp.unix.shell} and the @cite{zsh-announce} mailing list. +The latest version can be found at any of the Zsh FTP sites, or at +@t{@uref{http://www.zsh.org/FAQ/}}. The contact address for FAQ-related matters +is @t{<faqmaster@@zsh.org>}. +@node The Zsh Web Page, The Zsh Userguide, The Zsh FAQ, Introduction + +@section The Zsh Web Page +@noindent +Zsh has a web page which is located at @t{@uref{https://www.zsh.org/}}. This is +maintained by Karsten Thygesen @t{<karthy@@zsh.org>}, of SunSITE Denmark. +The contact address for web-related matters is @t{<webmaster@@zsh.org>}. +@node The Zsh Userguide, See Also, The Zsh Web Page, Introduction + +@section The Zsh Userguide +@noindent +A userguide is currently in preparation. It is intended to complement the +manual, with explanations and hints on issues where the manual can be +cabbalistic, hierographic, or downright mystifying (for example, the word +`hierographic' does not exist). It can be viewed in its current state at +@t{@uref{http://zsh.sourceforge.net/Guide/}}. At the time of writing, chapters +dealing with startup files and their contents and the new completion system +were essentially complete. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/seealso.yo +@node See Also, , The Zsh Userguide, Introduction + +@section See Also +@noindent +man page sh(1), +man page csh(1), +man page tcsh(1), +man page rc(1), +man page bash(1), +man page ksh(1) + +@noindent +@cite{IEEE Standard for information Technology - +Portable Operating System Interface (POSIX) - +Part 2: Shell and Utilities}, +IEEE Inc, 1993, ISBN 1-55937-255-9. +@c (avoiding a yodl bug) +@c (avoiding a yodl bug) +@c Yodl file: Zsh/roadmap.yo +@node Roadmap, Invocation, Introduction, Top + +@chapter Roadmap +@noindent +@cindex roadmap +The Zsh Manual, like the shell itself, is large and often complicated. +This section of the manual provides some pointers to areas of the shell +that are likely to be of particular interest to new users, and indicates +where in the rest of the manual the documentation is to be found. + +@noindent + +@section When the shell starts +@noindent + +@noindent +When it starts, the shell reads commands from various files. These can +be created or edited to customize the shell. See @ref{Files}. + +@noindent +If no personal initialization files exist for the current user, a function +is run to help you change some of the most common settings. It won't +appear if your administrator has disabled the @t{zsh/newuser} module. +The function is designed to be self-explanatory. You can run it by hand +with `@t{autoload -Uz zsh-newuser-install; zsh-newuser-install -f}'. +See also +@ref{User Configuration Functions}. + +@noindent + +@section Interactive Use +@noindent + +@noindent +Interaction with the shell uses the builtin Zsh Line Editor, ZLE. This is +described in detail in @ref{Zsh Line Editor}. + +@noindent +The first decision a user must make is whether to use the Emacs or Vi +editing mode as the keys for editing are substantially different. Emacs +editing mode is probably more natural for beginners and can be selected +explicitly with the command @t{bindkey -e}. + +@noindent +A history mechanism for retrieving previously typed lines (most simply +with the Up or Down arrow keys) is available; note that, unlike other +shells, zsh will not save these lines when the shell exits unless you +set appropriate variables, and the number of history lines retained by +default is quite small (30 lines). See the description of the shell +variables (referred to in the documentation as parameters) @t{HISTFILE}, +@t{HISTSIZE} and @t{SAVEHIST} in @ref{Parameters Used By The Shell}. Note that it's +currently only possible to read and write files saving history +when the shell is interactive, i.e. it does not work from scripts. + +@noindent +The shell now supports the UTF-8 character set (and also others if +supported by the operating system). This is (mostly) handled transparently +by the shell, but the degree of support in terminal emulators is variable. +There is some discussion of this in the shell FAQ, +@t{@uref{http://www.zsh.org/FAQ/}}. Note in particular that for combining +characters to be handled the option @t{COMBINING_CHARS} needs to be set. +Because the shell is now more sensitive to the definition of the +character set, note that if you are upgrading from an older version of +the shell you should ensure that the appropriate variable, either +@t{LANG} (to affect all aspects of the shell's operation) or +@t{LC_CTYPE} (to affect only the handling of character sets) is set to +an appropriate value. This is true even if you are using a +single-byte character set including extensions of ASCII such as +@t{ISO-8859-1} or @t{ISO-8859-15}. See the description of @t{LC_CTYPE} +in +@ref{Parameters}. + +@noindent + +@subsection Completion +@noindent + +@noindent +Completion is a feature present in many shells. It allows the user to +type only a part (usually the prefix) of a word and have the shell fill +in the rest. The completion system in zsh is programmable. For +example, the shell can be set to complete email addresses in +arguments to the mail command from your @t{~/.abook/addressbook}; +usernames, hostnames, and even remote paths in arguments to scp, and so +on. Anything that can be written in or glued together with zsh can be +the source of what the line editor offers as possible completions. + +@noindent +Zsh has two completion systems, an old, so called @t{compctl} completion +(named after the builtin command that serves as its complete and only +user interface), and a new one, referred to as @t{compsys}, +organized as library of builtin and user-defined functions. +The two systems differ in their interface for specifying the completion +behavior. The new system is more customizable and is supplied with +completions for many commonly used commands; it is therefore to be +preferred. + +@noindent +The completion system must be enabled explicitly when the shell starts. +For more information see +@ref{Completion System}. + +@noindent + +@subsection Extending the line editor +@noindent + +@noindent +Apart from completion, the line editor is highly extensible by means of +shell functions. Some useful functions are provided with the shell; they +provide facilities such as: + +@noindent +@table @asis +@item @t{insert-composed-char} +composing characters not found on the keyboard + +@item @t{match-words-by-style} +configuring what the line editor considers a word when moving or +deleting by word + +@item @t{history-beginning-search-backward-end}, etc. +alternative ways of searching the shell history + +@item @t{replace-string}, @t{replace-pattern} +functions for replacing strings or patterns globally in the command line + +@item @t{edit-command-line} +edit the command line with an external editor. + +@end table + +@noindent +See @ref{ZLE Functions} for descriptions of these. + +@noindent + +@section Options +@noindent + +@noindent +The shell has a large number of options for changing its behaviour. +These cover all aspects of the shell; browsing the full documentation is +the only good way to become acquainted with the many possibilities. See +@ref{Options}. + +@noindent + +@section Pattern Matching +@noindent + +@noindent +The shell has a rich set of patterns which are available for file matching +(described in the documentation as `filename generation' and also known for +historical reasons as `globbing') and for use when programming. These are +described in @ref{Filename Generation}. + +@noindent +Of particular interest are the following patterns that are not commonly +supported by other systems of pattern matching: + +@noindent +@table @asis +@item @t{**} +for matching over multiple directories + +@item @t{|} +for matching either of two alternatives + +@item @t{~}, @t{^} +the ability to exclude patterns from matching when the @t{EXTENDED_GLOB} +option is set + +@item @t{(}@var{...}@t{)} +glob qualifiers, included in parentheses at the end of the pattern, +which select files by type (such as directories) or attribute (such as +size). + +@end table + +@noindent + +@section General Comments on Syntax +@noindent + +@noindent +Although the syntax of zsh is in ways similar to the Korn shell, and +therefore more remotely to the original UNIX shell, the Bourne shell, +its default behaviour does not entirely correspond to those shells. +General shell syntax is introduced in @ref{Shell Grammar}. + +@noindent +One commonly encountered difference is that variables substituted onto the +command line are not split into words. See the description of the shell option +@t{SH_WORD_SPLIT} in +@ref{Parameter Expansion}. +In zsh, you can either explicitly request the splitting (e.g. @t{$@{=foo@}}) +or use an array when you want a variable to expand to more than one word. See +@ref{Array Parameters}. + +@noindent + +@section Programming +@noindent + +@noindent +The most convenient way of adding enhancements to the shell is typically +by writing a shell function and arranging for it to be autoloaded. +Functions are described in @ref{Functions}. Users changing from the C shell and its +relatives should notice that aliases are less used in zsh as they don't +perform argument substitution, only simple text replacement. + +@noindent +A few general functions, other than those for the line editor described +above, are provided with the shell and are described in +@ref{User Contributions}. Features include: + +@noindent +@table @asis +@item @t{promptinit} +a prompt theme system for changing prompts easily, see @ref{Prompt Themes} + +@item @t{zsh-mime-setup} +a MIME-handling system which dispatches commands according to the suffix of +a file as done by graphical file managers + +@item @t{zcalc} +a calculator + +@item @t{zargs} +a version of @t{xargs} that makes the @t{find} command redundant + +@item @t{zmv} +a command for renaming files by means of shell patterns. + +@end table +@c (avoiding a yodl bug) +@c Yodl file: Zsh/invoke.yo +@node Invocation, Files, Roadmap, Top + +@chapter Invocation +@noindent +@cindex invocation + +@section Invocation +@noindent +@cindex shell options +@cindex options, shell +@cindex shell flags +@cindex flags, shell +The following flags are interpreted by the shell when invoked to determine +where the shell will read commands from: + +@noindent +@table @asis +@item @t{-c} +Take the first argument as a command to execute, rather than reading commands +from a script or standard input. If any further arguments are given, the +first one is assigned to @t{$0}, rather than being used as a positional +parameter. + +@item @t{-i} +Force shell to be interactive. It is still possible to specify a +script to execute. + +@item @t{-s} +Force shell to read commands from the standard input. +If the @t{-s} flag is not present and an argument is given, +the first argument is taken to be the pathname of a script to +execute. + +@end table + +@noindent +If there are any remaining arguments after option processing, and neither +of the options @t{-c} or @t{-s} was supplied, the first argument is taken +as the file name of a script containing shell commands to be executed. If +the option @t{PATH_SCRIPT} is set, and the file name does not contain a +directory path (i.e. there is no `@t{/}' in the name), first the current +directory and then the command path given by the variable @t{PATH} are +searched for the script. If the option is not set or the file name +contains a `@t{/}' it is used directly. + +@noindent +After the first one or two arguments have been appropriated as described above, +the remaining arguments are assigned to the positional parameters. + +@noindent +For further options, which are common to invocation and the @t{set} +builtin, see +@ref{Options}. + +@noindent +The long option `@t{-}@t{-emulate}' followed (in a separate word) by an +emulation mode may be passed to the shell. +The emulation modes are those described for the @t{emulate} builtin, +see +@ref{Shell Builtin Commands}. +The `@t{-}@t{-emulate}' option must precede any other options (which might +otherwise be overridden), but following options are honoured, so +may be used to modify the requested emulation mode. Note that certain +extra steps are taken to ensure a smooth emulation when this option +is used compared with the @t{emulate} command within the shell: for +example, variables that conflict with POSIX usage such as @t{path} are +not defined within the shell. + +@noindent +Options may be specified by name using the @t{-o} option. @t{-o} acts like +a single-letter option, but takes a following string as the option name. +For example, + +@noindent +@example +zsh -x -o shwordsplit scr +@end example + +@noindent +runs the script @t{scr}, setting the @t{XTRACE} option by the corresponding +letter `@t{-x}' and the @t{SH_WORD_SPLIT} option by name. +Options may be turned @emph{off} by name by using @t{+o} instead of @t{-o}. +@t{-o} can be stacked up with preceding single-letter options, so for example +`@t{-xo shwordsplit}' or `@t{-xoshwordsplit}' is equivalent to +`@t{-x -o shwordsplit}'. + +@noindent +@cindex long option +Options may also be specified by name in GNU long option style, +`@t{-}@t{-}@var{option-name}'. When this is done, `@t{-}' characters in the +option name are permitted: they are translated into `@t{_}', and thus ignored. +So, for example, `@t{zsh -}@t{-sh-word-split}' invokes zsh with the +@t{SH_WORD_SPLIT} option turned on. Like other option syntaxes, options can +be turned off by replacing the initial `@t{-}' with a `@t{+}'; thus +`@t{+-sh-word-split}' is equivalent to `@t{-}@t{-no-sh-word-split}'. +Unlike other option syntaxes, GNU-style long options cannot be stacked with +any other options, so for example `@t{-x-shwordsplit}' is an error, +rather than being treated like `@t{-x -}@t{-shwordsplit}'. + +@noindent +@cindex --version +@cindex --help +The special GNU-style option `@t{-}@t{-version}' is handled; it sends to +standard output the shell's version information, then exits successfully. +`@t{-}@t{-help}' is also handled; it sends to standard output a list of +options that can be used when invoking the shell, then exits successfully. + +@noindent +Option processing may be finished, allowing following arguments that start with +`@t{-}' or `@t{+}' to be treated as normal arguments, in two ways. +Firstly, a lone `@t{-}' (or `@t{+}') as an argument by itself ends +option processing. Secondly, a special option `@t{-}@t{-}' (or +`@t{+-}'), which may be specified on its own (which is the standard +POSIX usage) or may be stacked with preceding options (so `@t{-x-}' is +equivalent to `@t{-x -}@t{-}'). Options are not permitted to be stacked +after `@t{-}@t{-}' (so `@t{-x-f}' is an error), but note the GNU-style +option form discussed above, where `@t{-}@t{-shwordsplit}' is permitted +and does not end option processing. + +@noindent +Except when the @cite{sh}/@cite{ksh} emulation single-letter options are in effect, +the option `@t{-b}' (or `@t{+b}') ends option processing. +`@t{-b}' is like `@t{-}@t{-}', except that further single-letter options +can be stacked after the `@t{-b}' and will take effect as normal. + +@noindent +@menu +* Compatibility:: +* Restricted Shell:: +@end menu + +@noindent +@c Yodl file: Zsh/compat.yo +@node Compatibility, Restricted Shell, , Invocation + +@section Compatibility +@noindent +@cindex compatibility +@cindex sh compatibility +@cindex ksh compatibility +Zsh tries to emulate @cite{sh} or @cite{ksh} when it is invoked as +@t{sh} or @t{ksh} respectively; more precisely, it looks at the first +letter of the name by which it was invoked, excluding any initial `@t{r}' +(assumed to stand for `restricted'), and if that is `@t{b}', `@t{s}' or `@t{k}' it +will emulate @cite{sh} or @cite{ksh}. Furthermore, if invoked as @t{su} (which +happens on certain systems when the shell is executed by the @t{su} +command), the shell will try to find an alternative name from the @t{SHELL} +environment variable and perform emulation based on that. + +@noindent +In @cite{sh} and @cite{ksh} compatibility modes the following +parameters are not special and not initialized by the shell: +@t{ARGC}, +@t{argv}, +@t{cdpath}, +@t{fignore}, +@t{fpath}, +@t{HISTCHARS}, +@t{mailpath}, +@t{MANPATH}, +@t{manpath}, +@t{path}, +@t{prompt}, +@t{PROMPT}, +@t{PROMPT2}, +@t{PROMPT3}, +@t{PROMPT4}, +@t{psvar}, +@t{status}, +@t{watch}. + +@noindent +@vindex ENV, use of +The usual zsh startup/shutdown scripts are not executed. Login shells +source @t{/etc/profile} followed by @t{$HOME/.profile}. If the +@t{ENV} environment variable is set on invocation, @t{$ENV} is sourced +after the profile scripts. The value of @t{ENV} is subjected to +parameter expansion, command substitution, and arithmetic expansion +before being interpreted as a pathname. Note that the @t{PRIVILEGED} +option also affects the execution of startup files. + +@noindent +The following options are set if the shell is invoked as @t{sh} or +@t{ksh}: +@t{NO_BAD_PATTERN}, +@t{NO_BANG_HIST}, +@t{NO_BG_NICE}, +@t{NO_EQUALS}, +@t{NO_FUNCTION_ARGZERO}, +@t{GLOB_SUBST}, +@t{NO_GLOBAL_EXPORT}, +@t{NO_HUP}, +@t{INTERACTIVE_COMMENTS}, +@t{KSH_ARRAYS}, +@t{NO_MULTIOS}, +@t{NO_NOMATCH}, +@t{NO_NOTIFY}, +@t{POSIX_BUILTINS}, +@t{NO_PROMPT_PERCENT}, +@t{RM_STAR_SILENT}, +@t{SH_FILE_EXPANSION}, +@t{SH_GLOB}, +@t{SH_OPTION_LETTERS}, +@t{SH_WORD_SPLIT}. +Additionally the @t{BSD_ECHO} and @t{IGNORE_BRACES} +options are set if zsh is invoked as @t{sh}. +Also, the +@t{KSH_OPTION_PRINT}, +@t{LOCAL_OPTIONS}, +@t{PROMPT_BANG}, +@t{PROMPT_SUBST} +and +@t{SINGLE_LINE_ZLE} +options are set if zsh is invoked as @t{ksh}. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/restricted.yo +@node Restricted Shell, , Compatibility, Invocation + +@section Restricted Shell +@noindent +@cindex restricted shell +@pindex RESTRICTED +When the basename of the command used to invoke zsh starts with the letter +`@t{r}' or the `@t{-r}' command line option is supplied at invocation, the +shell becomes restricted. Emulation mode is determined after stripping the +letter `@t{r}' from the invocation name. The following are disabled in +restricted mode: + +@noindent +@itemize @bullet + +@item +changing directories with the @t{cd} builtin +@item +changing or unsetting the @t{EGID}, @t{EUID}, @t{GID}, +@t{HISTFILE}, @t{HISTSIZE}, @t{IFS}, @t{LD_AOUT_LIBRARY_PATH}, +@t{LD_AOUT_PRELOAD}, @t{LD_LIBRARY_PATH}, @t{LD_PRELOAD}, +@t{MODULE_PATH}, @t{module_path}, @t{PATH}, @t{path}, @t{SHELL}, +@t{UID} and @t{USERNAME} parameters +@item +specifying command names containing @t{/} +@item +specifying command pathnames using @t{hash} +@item +redirecting output to files +@item +using the @t{exec} builtin command to replace the shell with another +command +@item +using @t{jobs -Z} to overwrite the shell process' argument and +environment space +@item +using the @t{ARGV0} parameter to override @t{argv[0]} for external +commands +@item +turning off restricted mode with @t{set +r} or @t{unsetopt +RESTRICTED} +@end itemize + +@noindent +These restrictions are enforced after processing the startup files. The +startup files should set up @t{PATH} to point to a directory of commands +which can be safely invoked in the restricted environment. They may also +add further restrictions by disabling selected builtins. + +@noindent +Restricted mode can also be activated any time by setting the +@t{RESTRICTED} option. This immediately enables all the restrictions +described above even if the shell still has not processed all startup +files. + +@noindent +A shell @emph{Restricted Mode} is an outdated way to restrict what users may +do: modern systems have better, safer and more reliable ways to +confine user actions, such as @emph{chroot jails}, @emph{containers} and +@emph{zones}. + +@noindent +A restricted shell is very difficult to implement safely. The feature +may be removed in a future version of zsh. + +@noindent +It is important to realise that the restrictions only apply to the shell, +not to the commands it runs (except for some shell builtins). While a +restricted shell can only run the restricted list of commands accessible +via the predefined `@t{PATH}' variable, it does not prevent those +commands from running any other command. + +@noindent +As an example, if `@t{env}' is among the list of @emph{allowed} commands, +then it allows the user to run any command as `@t{env}' is not a shell +builtin command and can run arbitrary executables. + +@noindent +So when implementing a restricted shell framework it is important to be +fully aware of what actions each of the @emph{allowed} commands or features +(which may be regarded as @emph{modules}) can perform. + +@noindent +Many commands can have their behaviour affected by environment +variables. Except for the few listed above, zsh does not restrict +the setting of environment variables. + +@noindent +If a `@t{perl}', `@t{python}', `@t{bash}', or other general purpose +interpreted script it treated as a restricted +command, the user can work around the restriction by +setting specially crafted `@t{PERL5LIB}', `@t{PYTHONPATH}', +`@t{BASHENV}' (etc.) environment variables. On GNU systems, any +command can be made to run arbitrary code when performing character set +conversion (including zsh itself) by setting a `@t{GCONV_PATH}' +environment variable. Those are only a few examples. + +@noindent +Bear in mind that, contrary to some other shells, `@t{readonly}' is not a +security feature in zsh as it can be undone and so cannot be used to +mitigate the above. + +@noindent +A restricted shell only works if the allowed commands are few +and carefully written so as not to grant more access to users than +intended. It is also important to restrict what zsh module the user may +load as some of them, such as `@t{zsh/system}', `@t{zsh/mapfile}' and +`@t{zsh/files}', allow bypassing most of the restrictions. +@c (avoiding a yodl bug) +@c (avoiding a yodl bug) +@c Yodl file: Zsh/files.yo +@node Files, Shell Grammar, Invocation, Top + +@chapter Files +@noindent + +@section Startup/Shutdown Files +@noindent +@cindex files, startup +@cindex startup files +@cindex files, shutdown +@cindex shutdown files +@pindex RCS, use of +@pindex GLOBAL_RCS, use of +@pindex NO_RCS, use of +@pindex NO_GLOBAL_RCS, use of +@vindex ZDOTDIR, use of +@cindex zshenv +Commands are first read from @t{/etc/zshenv}; this cannot be overridden. +Subsequent behaviour is modified by the @t{RCS} and +@t{GLOBAL_RCS} options; the former affects all startup files, while the +second only affects global startup files (those shown here with an +path starting with a @t{/}). If one of the options +is unset at any point, any subsequent startup file(s) +of the corresponding +type will not be read. It is also possible for a file in @t{$ZDOTDIR} to +re-enable @t{GLOBAL_RCS}. Both @t{RCS} and @t{GLOBAL_RCS} are set by +default. + +@noindent +Commands are then read from @t{$ZDOTDIR/.zshenv}. +@pindex LOGIN, use of +@cindex zprofile +If the shell is a login shell, commands +are read from @t{/etc/zprofile} and then @t{$ZDOTDIR/.zprofile}. +@cindex zshrc +Then, if the shell is interactive, +commands are read from @t{/etc/zshrc} and then @t{$ZDOTDIR/.zshrc}. +@cindex zlogin +Finally, if the shell is a login shell, @t{/etc/zlogin} and +@t{$ZDOTDIR/.zlogin} are read. + +@noindent +@cindex zlogout +When a login shell exits, the files @t{$ZDOTDIR/.zlogout} and then +@t{/etc/zlogout} are read. This happens with either an explicit exit +via the @t{exit} or @t{logout} commands, or an implicit exit by reading +end-of-file from the terminal. However, if the shell terminates due +to @t{exec}'ing another process, the logout files are not read. +These are also affected by the @t{RCS} and @t{GLOBAL_RCS} options. +Note also that the @t{RCS} option affects the saving of history files, +i.e. if @t{RCS} is unset when the shell exits, no history file will be +saved. + +@noindent +@vindex HOME, use of +If @t{ZDOTDIR} is unset, @t{HOME} is used instead. +Files listed above as being in @t{/etc} may be in another +directory, depending on the installation. + +@noindent +As @t{/etc/zshenv} is run for all instances of zsh, it is important that +it be kept as small as possible. In particular, it is a good idea to +put code that does not need to be run for every single shell behind +a test of the form `@t{if [[ -o rcs ]]; then ...}' so that it will not +be executed when zsh is invoked with the `@t{-f}' option. +@c Yodl file: Zsh/filelist.yo + +@section Files +@noindent +@cindex files used +@table @asis +@item @t{$ZDOTDIR/.zshenv} +@item @t{$ZDOTDIR/.zprofile} +@item @t{$ZDOTDIR/.zshrc} +@item @t{$ZDOTDIR/.zlogin} +@item @t{$ZDOTDIR/.zlogout} +@item @t{$@{TMPPREFIX@}*} (default is /tmp/zsh*) +@item @t{/etc/zshenv} +@item @t{/etc/zprofile} +@item @t{/etc/zshrc} +@item @t{/etc/zlogin} +@item @t{/etc/zlogout} (installation-specific - @t{/etc} is the default) +@end table +@sp 1 +@c (avoiding a yodl bug) + +@noindent +Any of these files may be pre-compiled with the @t{zcompile} builtin +command (@ref{Shell Builtin Commands}). If a compiled file exists (named for the original file plus the +@t{.zwc} extension) and it is newer than the original file, the compiled +file will be used instead. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/grammar.yo +@node Shell Grammar, Redirection, Files, Top + +@chapter Shell Grammar +@noindent +@cindex shell grammar +@cindex grammar, shell +@menu +* Simple Commands & Pipelines:: +* Precommand Modifiers:: +* Complex Commands:: +* Alternate Forms For Complex Commands:: +* Reserved Words:: +* Errors:: +* Comments:: +* Aliasing:: +* Quoting:: +@end menu +@node Simple Commands & Pipelines, Precommand Modifiers, , Shell Grammar + +@section Simple Commands & Pipelines +@noindent +@cindex simple commands +@cindex commands, simple +A @emph{simple command} is a sequence of optional parameter +assignments followed by blank-separated words, +with optional redirections interspersed. For a description +of assignment, see the beginning of +@ref{Parameters}. + +@noindent +The first word is the command to be executed, and the remaining +words, if any, are arguments to the command. +If a command name is given, the parameter assignments modify +the environment of the command when it is executed. +The value of a simple command is its exit status, +or 128 plus the signal number if terminated by a signal. +For example, + +@noindent +@example +echo foo +@end example + +@noindent +is a simple command with arguments. + +@noindent +@cindex pipeline +A @emph{pipeline} is either a simple command, or a sequence of two or more +simple commands where each command is separated from the next by `@t{|}' +or `@t{|&}'. Where commands are separated by `@t{|}', the standard +output of the first command is connected to the +standard input of the next. `@t{|&}' is shorthand for `@t{2>&1 |}', which +connects both the standard output and the standard error of the +command to the standard input of the next. The value of a pipeline +is the value of the last command, unless the pipeline is preceded by +`@t{!}' in which case the value is the logical inverse of the value of the +last command. +For example, + +@noindent +@example +echo foo | sed 's/foo/bar/' +@end example + +@noindent +is a pipeline, where the output (`@t{foo}' plus a newline) of the first +command will be passed to the input of the second. + +@noindent +@findex coproc +@cindex coprocess +If a pipeline is preceded by `@t{coproc}', it is executed as a coprocess; +a two-way pipe is established between it and the parent shell. The +shell can read from or write to the coprocess by means of the `@t{>&p}' +and `@t{<&p}' redirection operators or with `@t{print -p}' and `@t{read -p}'. +A pipeline cannot be preceded by both `@t{coproc}' and `@t{!}'. +If job control is active, the coprocess can be treated in other than input +and output as an ordinary background job. + +@noindent +@cindex sublist +A @emph{sublist} is either a single pipeline, or a sequence of two or more +pipelines separated by `@t{&&}' or `@t{||}'. If two pipelines are separated +by `@t{&&}', the second pipeline is executed only if the first succeeds +(returns a zero status). If two pipelines are separated by `@t{||}', the +second is executed only if the first fails (returns a nonzero status). +Both operators have equal precedence and are left associative. +The value of the sublist is the value of the last pipeline executed. +For example, + +@noindent +@example +dmesg | grep panic && print yes +@end example + +@noindent +is a sublist consisting of two pipelines, the second just a simple command +which will be executed if and only if the @t{grep} command returns a zero +status. If it does not, the value of the sublist is that return status, else +it is the status returned by the @t{print} (almost certainly zero). + +@noindent +@cindex list +A @emph{list} is a sequence of zero or more sublists, in which each sublist +is terminated by `@t{;}', `@t{&}', `@t{&|}', `@t{&!}', or a newline. +This terminator +may optionally be omitted from the last sublist in the list when the +list appears as a complex command inside `@t{(}...@t{)}' +or `@t{@{}...@t{@}}'. When a +sublist is terminated by `@t{;}' or newline, the shell waits for it to +finish before executing the next sublist. If a sublist is terminated +by a `@t{&}', `@t{&|}', or `@t{&!}', +the shell executes the last pipeline in it in the background, and +does not wait for it to finish (note the difference from other shells +which execute the whole sublist in the background). +A backgrounded pipeline returns a status of zero. + +@noindent +More generally, a list can be seen as a set of any shell commands +whatsoever, including the complex commands below; this is implied wherever +the word `list' appears in later descriptions. For example, the commands +in a shell function form a special sort of list. +@node Precommand Modifiers, Complex Commands, Simple Commands & Pipelines, Shell Grammar + +@section Precommand Modifiers +@noindent +@cindex precommand modifiers +@cindex modifiers, precommand +A simple command may be preceded by a @emph{precommand modifier}, +which will alter how the command is interpreted. These modifiers are +shell builtin commands with the exception of @t{nocorrect} which is +a reserved word. + +@noindent +@table @asis +@findex - +@item @t{-} +The command is executed with a `@t{-}' prepended to its +@t{argv[0]} string. + +@findex builtin +@item @t{builtin} +The command word is taken to be the name of a builtin command, +rather than a shell function or external command. + +@findex command +@item @t{command} [ @t{-pvV} ] +The command word is taken to be the name of an external command, +rather than a shell function or builtin. If the @t{POSIX_BUILTINS} option +is set, builtins will also be executed but certain special properties +of them are suppressed. The @t{-p} flag causes a default path to be +searched instead of that in @t{$path}. With the @t{-v} flag, @t{command} +is similar to @t{whence} and with @t{-V}, it is equivalent to @t{whence +-v}. + +@findex exec +@item @t{exec} [ @t{-cl} ] [ @t{-a} @var{argv0} ] +The following command together with any arguments is run in place +of the current process, rather than as a sub-process. The shell does not +fork and is replaced. The shell does not invoke @t{TRAPEXIT}, nor does it +source @t{zlogout} files. +The options are provided for compatibility with other shells. + +@noindent +The @t{-c} option clears the environment. + +@noindent +The @t{-l} option is equivalent to the @t{-} precommand modifier, to +treat the replacement command as a login shell; the command is executed +with a @t{-} prepended to its @t{argv[0]} string. This flag has no effect +if used together with the @t{-a} option. + +@noindent +The @t{-a} option is used to specify explicitly the @t{argv[0]} string +(the name of the command as seen by the process itself) to be used by the +replacement command and is directly equivalent to setting a value +for the @t{ARGV0} environment variable. + +@findex nocorrect +@item @t{nocorrect} +Spelling correction is not done on any of the words. This must appear +before any other precommand modifier, as it is interpreted immediately, +before any parsing is done. It has no effect in non-interactive shells. + +@findex noglob +@item @t{noglob} +Filename generation (globbing) is not performed on any of +the words. + +@end table +@node Complex Commands, Alternate Forms For Complex Commands, Precommand Modifiers, Shell Grammar + +@section Complex Commands +@noindent +@cindex complex commands +@cindex commands, complex +A @emph{complex command} in zsh is one of the following: + +@noindent +@table @asis +@findex if +@cindex if construct +@item @t{if} @var{list} @t{then} @var{list} [ @t{elif} @var{list} @t{then} @var{list} ] ... [ @t{else} @var{list} ] @t{fi} +The @t{if} @var{list} is executed, and if it returns a zero exit status, +the @t{then} @var{list} is executed. +Otherwise, the @t{elif} @var{list} is executed and if its status is zero, +the @t{then} @var{list} is executed. +If each @t{elif} @var{list} returns nonzero status, the @t{else} @var{list} +is executed. + +@findex for +@cindex for loops +@cindex loops, for +@item @t{for} @var{name} ... [ @t{in} @var{word} ... ] @var{term} @t{do} @var{list} @t{done} +Expand the list of @var{word}s, and set the parameter +@var{name} to each of them in turn, executing @var{list} +each time. If the `@t{in} @var{word}' is omitted, +use the positional parameters instead of the @var{word}s. + +@noindent +The @var{term} consists of one or more newline or @t{;} +which terminate the @var{word}s, and are optional when the +`@t{in} @var{word}' is omitted. + +@noindent +More than one parameter @var{name} can appear before the list of +@var{word}s. If @var{N} @var{name}s are given, then on each execution of the +loop the next @var{N} @var{word}s are assigned to the corresponding +parameters. If there are more @var{name}s than remaining @var{word}s, the +remaining parameters are each set to the empty string. Execution of the +loop ends when there is no remaining @var{word} to assign to the first +@var{name}. It is only possible for @t{in} to appear as the first @var{name} +in the list, else it will be treated as marking the end of the list. + +@item @t{for ((} [@var{expr1}] @t{;} [@var{expr2}] @t{;} [@var{expr3}] @t{)) do} @var{list} @t{done} +The arithmetic expression @var{expr1} is evaluated first (see +@ref{Arithmetic Evaluation}). The arithmetic expression +@var{expr2} is repeatedly evaluated until it evaluates to zero and +when non-zero, @var{list} is executed and the arithmetic expression +@var{expr3} evaluated. If any expression is omitted, then it behaves +as if it evaluated to 1. + +@findex while +@cindex while loops +@cindex loops, while +@item @t{while} @var{list} @t{do} @var{list} @t{done} +Execute the @t{do} @var{list} as long as the @t{while} @var{list} +returns a zero exit status. + +@findex until +@cindex until loops +@cindex loops, until +@item @t{until} @var{list} @t{do} @var{list} @t{done} +Execute the @t{do} @var{list} as long as @t{until} @var{list} +returns a nonzero exit status. + +@findex repeat +@cindex repeat loops +@cindex loops, repeat +@item @t{repeat} @var{word} @t{do} @var{list} @t{done} +@var{word} is expanded and treated as an arithmetic expression, +which must evaluate to a number @var{n}. +@var{list} is then executed @var{n} times. + +@noindent +The @t{repeat} syntax is disabled by default when the +shell starts in a mode emulating another shell. It can be enabled +with the command `@t{enable -r repeat}' + +@findex case +@cindex case selection +@cindex selection, case +@item @t{case} @var{word} @t{in} [ [@t{(}] @var{pattern} [ @t{|} @var{pattern} ] ... @t{)} @var{list} (@t{;;}|@t{;&}|@t{;|}) ] ... @t{esac} +Execute the @var{list} associated with the first @var{pattern} +that matches @var{word}, if any. The form of the patterns +is the same as that used for filename generation. See +@ref{Filename Generation}. + +@noindent +Note further that, unless the @t{SH_GLOB} option is set, the whole +pattern with alternatives is treated by the shell as equivalent to a +group of patterns within parentheses, although white space may appear +about the parentheses and the vertical bar and will be stripped from the +pattern at those points. White space may appear elsewhere in the +pattern; this is not stripped. If the @t{SH_GLOB} option is set, so +that an opening parenthesis can be unambiguously treated as part of the +case syntax, the expression is parsed into separate words and these are +treated as strict alternatives (as in other shells). + +@noindent +If the @var{list} that is executed is terminated with @t{;&} rather than +@t{;;}, the following list is also executed. The rule for +the terminator of the following list @t{;;}, @t{;&} or @t{;|} is +applied unless the @t{esac} is reached. + +@noindent +If the @var{list} that is executed is terminated with @t{;|} the +shell continues to scan the @var{pattern}s looking for the next match, +executing the corresponding @var{list}, and applying the rule for +the corresponding terminator @t{;;}, @t{;&} or @t{;|}. +Note that @var{word} is not re-expanded; all applicable @var{pattern}s +are tested with the same @var{word}. + +@findex select +@cindex user selection +@cindex selection, user +@item @t{select} @var{name} [ @t{in} @var{word} ... @var{term} ] @t{do} @var{list} @t{done} +where @var{term} is one or more newline or @t{;} to terminate the @var{word}s. +@vindex REPLY, use of +Print the set of @var{word}s, each preceded by a number. +If the @t{in} @var{word} is omitted, use the positional parameters. +The @t{PROMPT3} prompt is printed and a line is read from the line editor +if the shell is interactive and that is active, or else standard input. +If this line consists of the +number of one of the listed @var{word}s, then the parameter @var{name} +is set to the @var{word} corresponding to this number. +If this line is empty, the selection list is printed again. +Otherwise, the value of the parameter @var{name} is set to null. +The contents of the line read from standard input is saved +in the parameter @t{REPLY}. @var{list} is executed +for each selection until a break or end-of-file is encountered. + +@cindex subshell +@item @t{(} @var{list} @t{)} +Execute @var{list} in a subshell. Traps set by the @t{trap} builtin +are reset to their default values while executing @var{list}. + +@item @t{@{} @var{list} @t{@}} +Execute @var{list}. + +@findex always +@cindex always blocks +@cindex try blocks +@item @t{@{} @var{try-list} @t{@} always @{} @var{always-list} @t{@}} +First execute @var{try-list}. Regardless of errors, or @t{break} or +@t{continue} commands encountered within @var{try-list}, +execute @var{always-list}. Execution then continues from the +result of the execution of @var{try-list}; in other words, any error, +or @t{break} or @t{continue} command is treated in the +normal way, as if @var{always-list} were not present. The two +chunks of code are referred to as the `try block' and the `always block'. + +@noindent +Optional newlines or semicolons may appear after the @t{always}; +note, however, that they may @emph{not} appear between the preceding +closing brace and the @t{always}. + +@noindent +An `error' in this context is a condition such as a syntax error which +causes the shell to abort execution of the current function, script, or +list. Syntax errors encountered while the shell is parsing the +code do not cause the @var{always-list} to be executed. For example, +an erroneously constructed @t{if} block in @var{try-list} would cause the +shell to abort during parsing, so that @var{always-list} would not be +executed, while an erroneous substitution such as @t{$@{*foo*@}} would +cause a run-time error, after which @var{always-list} would be executed. + +@noindent +An error condition can be tested and reset with the special integer +variable @t{TRY_BLOCK_ERROR}. Outside an @var{always-list} the value is +irrelevant, but it is initialised to @t{-1}. Inside @var{always-list}, the +value is 1 if an error occurred in the @var{try-list}, else 0. If +@t{TRY_BLOCK_ERROR} is set to 0 during the @var{always-list}, the error +condition caused by the @var{try-list} is reset, and shell execution +continues normally after the end of @var{always-list}. Altering the value +during the @var{try-list} is not useful (unless this forms part of an +enclosing @t{always} block). + +@noindent +Regardless of @t{TRY_BLOCK_ERROR}, after the end of @var{always-list} the +normal shell status @t{$?} is the value returned from @var{try-list}. +This will be non-zero if there was an error, even if @t{TRY_BLOCK_ERROR} +was set to zero. + +@noindent +The following executes the given code, ignoring any errors it causes. +This is an alternative to the usual convention of protecting code by +executing it in a subshell. + +@noindent +@example +@{ + # code which may cause an error + @} always @{ + # This code is executed regardless of the error. + (( TRY_BLOCK_ERROR = 0 )) +@} +# The error condition has been reset. +@end example + +@noindent +When a @t{try} block occurs outside of any function, +a @t{return} or a @t{exit} encountered in @var{try-list} does @emph{not} cause +the execution of @var{always-list}. Instead, the shell exits immediately +after any @t{EXIT} trap has been executed. +Otherwise, a @t{return} command encountered in @var{try-list} will cause the +execution of @var{always-list}, just like @t{break} and @t{continue}. + +@noindent + + +@findex function +@item @t{function} @var{word} ... [ @t{()} ] [ @var{term} ] @t{@{} @var{list} @t{@}} +@itemx @var{word} ... @t{()} [ @var{term} ] @t{@{} @var{list} @t{@}} +@itemx @var{word} ... @t{()} [ @var{term} ] @var{command} +where @var{term} is one or more newline or @t{;}. +Define a function which is referenced by any one of @var{word}. +Normally, only one @var{word} is provided; multiple @var{word}s +are usually only useful for setting traps. +The body of the function is the @var{list} between +the @t{@{} and @t{@}}. See @ref{Functions}. + +@noindent +If the option @t{SH_GLOB} is set for compatibility with other shells, then +whitespace may appear between the left and right parentheses when +there is a single @var{word}; otherwise, the parentheses will be treated as +forming a globbing pattern in that case. + +@noindent +In any of the forms above, a redirection may appear outside the +function body, for example + +@noindent +@example +func() @{ ... @} 2>&1 +@end example + +@noindent +The redirection is stored with the function and applied whenever the +function is executed. Any variables in the redirection are expanded +at the point the function is executed, but outside the function scope. + +@cindex timing +@findex time +@item @t{time} [ @var{pipeline} ] +The @var{pipeline} is executed, and timing statistics are +reported on the standard error in the form specified +by the @t{TIMEFMT} parameter. +If @var{pipeline} is omitted, print statistics about the +shell process and its children. + +@cindex conditional expression +@findex [[ +@item @t{[[} @var{exp} @t{]]} +Evaluates the conditional expression @var{exp} +and return a zero exit status if it is true. +See @ref{Conditional Expressions} +for a description of @var{exp}. + +@end table +@node Alternate Forms For Complex Commands, Reserved Words, Complex Commands, Shell Grammar + +@section Alternate Forms For Complex Commands +@noindent +@cindex alternate forms for complex commands +@cindex commands, alternate forms for complex +Many of zsh's complex commands have alternate forms. These are +non-standard and are likely not to be obvious even to seasoned shell +programmers; they should not be used anywhere that portability of shell +code is a concern. + +@noindent +The short versions below only work if @var{sublist} is of the form `@t{@{} +@var{list} @t{@}}' or if the @t{SHORT_LOOPS} option is set. For the @t{if}, +@t{while} and @t{until} commands, in both these cases the test part of the +loop must also be suitably delimited, such as by `@t{[[} @var{...} @t{]]}' or +`@t{((} @var{...} @t{))}', +else the end of the test will not be recognized. For the +@t{for}, @t{repeat}, @t{case} and @t{select} commands no such special form +for the arguments is necessary, but the other condition (the special form +of @var{sublist} or use of the @t{SHORT_LOOPS} option) still applies. + +@noindent +@table @asis +@item @t{if} @var{list} @t{@{} @var{list} @t{@}} [ @t{elif} @var{list} @t{@{} @var{list} @t{@}} ] ... [ @t{else @{} @var{list} @t{@}} ] +An alternate form of @t{if}. The rules mean that + +@noindent +@example +if [[ -o ignorebraces ]] @{ + print yes +@} +@end example + +@noindent +works, but + +@noindent +@example +if true @{ # Does not work! + print yes +@} +@end example + +@noindent +does @emph{not}, since the test is not suitably delimited. + +@item @t{if} @var{list} @var{sublist} +A short form of the alternate @t{if}. The same limitations on the form of +@var{list} apply as for the previous form. + +@item @t{for} @var{name} ... @t{(} @var{word} ... @t{)} @var{sublist} +A short form of @t{for}. + +@item @t{for} @var{name} ... [ @t{in} @var{word} ... ] @var{term} @var{sublist} +where @var{term} is at least one newline or @t{;}. +Another short form of @t{for}. + +@item @t{for ((} [@var{expr1}] @t{;} [@var{expr2}] @t{;} [@var{expr3}] @t{))} @var{sublist} +A short form of the arithmetic @t{for} command. + +@findex foreach +@item @t{foreach} @var{name} ... @t{(} @var{word} ... @t{)} @var{list} @t{end} +Another form of @t{for}. + +@item @t{while} @var{list} @t{@{} @var{list} @t{@}} +An alternative form of @t{while}. Note the limitations on the form of +@var{list} mentioned above. + +@item @t{until} @var{list} @t{@{} @var{list} @t{@}} +An alternative form of @t{until}. Note the limitations on the form of +@var{list} mentioned above. + +@item @t{repeat} @var{word} @var{sublist} +This is a short form of @t{repeat}. + +@item @t{case} @var{word} @t{@{} [ [@t{(}] @var{pattern} [ @t{|} @var{pattern} ] ... @t{)} @var{list} (@t{;;}|@t{;&}|@t{;|}) ] ... @t{@}} +An alternative form of @t{case}. + +@item @t{select} @var{name} [ @t{in} @var{word} ... @var{term} ] @var{sublist} +where @var{term} is at least one newline or @t{;}. +A short form of @t{select}. + +@item @t{function} @var{word} ... [ @t{()} ] [ @var{term} ] @var{sublist} +This is a short form of @t{function}. + +@end table +@node Reserved Words, Errors, Alternate Forms For Complex Commands, Shell Grammar + +@section Reserved Words +@noindent +@cindex reserved words +@findex disable, use of +The following words are recognized as reserved words when used as the first +word of a command unless quoted or disabled using @t{disable -r}: + +@noindent +@t{do done esac then elif else fi for case +if while function repeat time until +select coproc nocorrect foreach end ! [[ @{ @} +declare export float integer local readonly typeset} + +@noindent +Additionally, `@t{@}}' is recognized in any position if neither the +@t{IGNORE_BRACES} option nor the @t{IGNORE_CLOSE_BRACES} option is set. +@node Errors, Comments, Reserved Words, Shell Grammar + +@section Errors +@noindent +@cindex errors, handling of +Certain errors are treated as fatal by the shell: in an interactive +shell, they cause control to return to the command line, and in a +non-interactive shell they cause the shell to be aborted. In older +versions of zsh, a non-interactive shell running a script would not +abort completely, but would resume execution at the next command to be +read from the script, skipping the remainder of any functions or +shell constructs such as loops or conditions; this somewhat illogical +behaviour can be recovered by setting the option @t{CONTINUE_ON_ERROR}. + +@noindent +Fatal errors found in non-interactive shells include: + +@noindent +@itemize @bullet + +@item +Failure to parse shell options passed when invoking the shell +@item +Failure to change options with the @t{set} builtin +@item +Parse errors of all sorts, including failures to parse +mathematical expressions +@item +Failures to set or modify variable behaviour with @t{typeset}, +@t{local}, @t{declare}, @t{export}, @t{integer}, @t{float} +@item +Execution of incorrectly positioned loop control structures +(@t{continue}, @t{break}) +@item +Attempts to use regular expression with no regular expression +module available +@item +Disallowed operations when the @t{RESTRICTED} options is set +@item +Failure to create a pipe needed for a pipeline +@item +Failure to create a multio +@item +Failure to autoload a module needed for a declared shell feature +@item +Errors creating command or process substitutions +@item +Syntax errors in glob qualifiers +@item +File generation errors where not caught by the option @t{BAD_PATTERN} +@item +All bad patterns used for matching within case statements +@item +File generation failures where not caused by @t{NO_MATCH} or +similar options +@item +All file generation errors where the pattern was used to create a +multio +@item +Memory errors where detected by the shell +@item +Invalid subscripts to shell variables +@item +Attempts to assign read-only variables +@item +Logical errors with variables such as assignment to the wrong type +@item +Use of invalid variable names +@item +Errors in variable substitution syntax +@item +Failure to convert characters in @t{$'}...@t{'} expressions +@end itemize + +@noindent +If the @t{POSIX_BUILTINS} option is set, more errors associated with +shell builtin commands are treated as fatal, as specified by the POSIX +standard. + +@noindent +@node Comments, Aliasing, Errors, Shell Grammar + +@section Comments +@noindent +@cindex comments +@pindex INTERACTIVE_COMMENTS, use of +@vindex histchars, use of +In non-interactive shells, or in interactive shells with the +@t{INTERACTIVE_COMMENTS} option set, a word beginning +with the third character of the @t{histchars} parameter +(`@t{#}' by default) causes that word and all the following +characters up to a newline to be ignored. +@node Aliasing, Quoting, Comments, Shell Grammar + +@section Aliasing +@noindent +@cindex aliasing +Every eligible @emph{word} in the shell input is checked to see if there +is an alias defined for it. +If so, it is replaced by the text of the alias if it is in command +position (if it could be the first word of a simple command), +or if the alias is global. +If the replacement text ends with a space, the next word in the shell input +is always eligible for purposes of alias expansion. +@findex alias, use of +@cindex aliases, global +An alias is defined using the @t{alias} builtin; global aliases +may be defined using the @t{-g} option to that builtin. + +@noindent +A @emph{word} is defined as: + +@noindent +@itemize @bullet + +@item +Any plain string or glob pattern +@item +Any quoted string, using any quoting method (note that the quotes +must be part of the alias definition for this to be eligible) +@item +Any parameter reference or command substitution +@item +Any series of the foregoing, concatenated without whitespace or +other tokens between them +@item +Any reserved word (@t{case}, @t{do}, @t{else}, etc.) +@item +With global aliasing, any command separator, any redirection +operator, and `@t{(}' or `@t{)}' when not part of a glob pattern +@end itemize + +@noindent +Alias expansion is done on the shell input before any other expansion +except history expansion. Therefore, if an alias is defined for the +word @t{foo}, alias expansion may be avoided by quoting part of the +word, e.g. @t{\foo}. Any form of quoting works, although there is +nothing to prevent an alias being defined for the quoted form such as +@t{\foo} as well. + +@noindent +When @t{POSIX_ALIASES} is set, only plain unquoted strings are eligible +for aliasing. The @t{alias} builtin does not reject ineligible aliases, +but they are not expanded. + +@noindent +For use with completion, which would remove an initial backslash followed +by a character that isn't special, it may be more convenient to quote the +word by starting with a single quote, i.e. @t{'foo}; completion will +automatically add the trailing single quote. + +@noindent + +@subsection Alias difficulties +@noindent + +@noindent +Although aliases can be used in ways that bend normal shell syntax, not +every string of non-white-space characters can be used as an alias. + +@noindent +Any set of characters not listed as a word above is not a word, hence no +attempt is made to expand it as an alias, no matter how it is defined +(i.e. via the builtin or the special parameter @t{aliases} described in +@ref{The zsh/parameter Module}). +However, as noted in the case of @t{POSIX_ALIASES} above, the shell does +not attempt to deduce whether the string corresponds to a word at the +time the alias is created. + +@noindent +For example, an expression containing an @t{=} at the start of +a command line is an assignment and cannot be expanded as an alias; +a lone @t{=} is not an assignment but can only be set as an alias +using the parameter, as otherwise the @t{=} is taken part of the +syntax of the builtin command. + +@noindent +It is not presently possible to alias the `@t{((}' token that +introduces arithmetic expressions, because until a full statement has been +parsed, it cannot be distinguished from two consecutive `@t{(}' +tokens introducing nested subshells. +Also, if a separator such as @t{&&} is aliased, +@t{\&&} turns into the two tokens @t{\&} and @t{&}, each of which may +have been aliased separately. Similarly for @t{\<<}, @t{\>|}, etc. + +@noindent +There is a commonly encountered problem with aliases +illustrated by the following code: + +@noindent +@example +alias echobar='echo bar'; echobar +@end example + +@noindent +This prints a message that the command @t{echobar} could not be found. +This happens because aliases are expanded when the code is read in; +the entire line is read in one go, so that when @t{echobar} is executed it +is too late to expand the newly defined alias. This is often +a problem in shell scripts, functions, and code executed with `@t{source}' +or `@t{.}'. Consequently, use of functions rather than aliases is +recommended in non-interactive code. + +@noindent +Note also the unhelpful interaction of aliases and function definitions: + +@noindent +@example +alias func='noglob func' +func() @{ + echo Do something with $* +@} +@end example + +@noindent +Because aliases are expanded in function definitions, this causes the +following command to be executed: + +@noindent +@example +noglob func() @{ + echo Do something with $* +@} +@end example + +@noindent +which defines @t{noglob} as well as @t{func} as functions with the +body given. To avoid this, either quote the name @t{func} or use the +alternative function definition form `@t{function func}'. Ensuring the +alias is defined after the function works but is problematic if the +code fragment might be re-executed. + +@noindent +@node Quoting, , Aliasing, Shell Grammar + +@section Quoting +@noindent +@cindex quoting +A character may be @emph{quoted} (that is, made +to stand for itself) by preceding it with a `@t{\}'. +`@t{\}' followed by a newline is ignored. + +@noindent +A string enclosed between `@t{$'}' and `@t{'}' is +processed the same way as the string arguments of the +@t{print} builtin, and the resulting string is considered to be +entirely quoted. A literal `@t{'}' character can be included in the +string by using the `@t{\'}' escape. + +@noindent +@pindex RC_QUOTES, use of +All characters enclosed between a pair of single quotes (@t{@value{dsq}}) that +is not preceded by a `@t{$}' are quoted. A single quote cannot appear +within single quotes unless the option @t{RC_QUOTES} is set, in which case +a pair of single quotes are turned into a single quote. For example, + +@noindent +@example +print @value{dsq}@value{dsq} +@end example + +@noindent +outputs nothing apart from a newline if @t{RC_QUOTES} is not set, but one +single quote if it is set. + +@noindent +Inside double quotes (@t{""}), parameter and +command substitution occur, and `@t{\}' quotes the characters +`@t{\}', `@t{`}', `@t{"}', `@t{$}', and the first character +of @t{$histchars} (default `@t{!}'). +@c (avoiding a yodl bug) +@c Yodl file: Zsh/redirect.yo +@node Redirection, Command Execution, Shell Grammar, Top + +@chapter Redirection +@noindent +@cindex redirection +@cindex file descriptors +@cindex descriptors, file +If a command is followed by @t{&} +and job control is not active, +then the default standard input +for the command is the empty file @t{/dev/null}. +Otherwise, the environment for the execution of a command contains the +file descriptors of the invoking shell as modified by +input/output specifications. + +@noindent +The following may appear anywhere in a simple command +or may precede or follow a complex command. +Expansion occurs before @var{word} or @var{digit} +is used except as noted below. +If the result of substitution on @var{word} +produces more than one filename, +redirection occurs for each +separate filename in turn. + +@noindent +@table @asis +@item @t{<} @var{word} +Open file @var{word} for reading as standard input. +It is an error to open a file in this fashion if it does not exist. + +@item @t{<>} @var{word} +Open file @var{word} for reading and writing as standard input. +If the file does not exist then it is created. + +@item @t{>} @var{word} +Open file @var{word} for writing as standard output. +If the file does not exist then it is created. +If the file exists, and the @t{CLOBBER} option is unset, +this causes an error; +otherwise, it is truncated to zero length. + +@item @t{>|} @var{word} +@itemx @t{>!} @var{word} +Same as @t{>}, except that the file is truncated to zero length +if it exists, regardless of @t{CLOBBER}. + +@item @t{>>} @var{word} +Open file @var{word} for writing in append mode as standard output. +If the file does not exist, and the @t{CLOBBER} and @t{APPEND_CREATE} +options are both unset, this causes an error; +otherwise, the file is created. + +@item @t{>>|} @var{word} +@itemx @t{>>!} @var{word} +Same as @t{>>}, except that the file is created if it does not +exist, regardless of @t{CLOBBER} and @t{APPEND_CREATE}. + +@item @t{<<}[@t{-}] @var{word} +The shell input is read up to a line that is the same as +@var{word}, or to an end-of-file. +No parameter expansion, command substitution or +filename generation is performed on @var{word}. +The resulting document, called a +@emph{here-document}, becomes the standard input. + +@noindent +If any character of @var{word} is quoted with +single or double quotes or a `@t{\}', +no interpretation is placed upon the characters of the document. +Otherwise, parameter and command substitution +occurs, `@t{\}' followed by a newline is removed, +and `@t{\}' must be used to quote the characters +`@t{\}', `@t{$}', `@t{`}' and the first character of @var{word}. + +@noindent +Note that @var{word} itself does not undergo shell expansion. Backquotes +in @var{word} do not have their usual effect; instead they behave +similarly to double quotes, except that the backquotes themselves are +passed through unchanged. (This information is given for completeness +and it is not recommended that backquotes be used.) Quotes in the form +@t{$'}@var{...}@t{'} have their standard effect of expanding backslashed +references to special characters. + +@noindent +If @t{<<-} is used, then all leading +tabs are stripped from @var{word} and from the document. + +@item @t{<<<} @var{word} +Perform shell expansion on @var{word} and pass the result +to standard input. This is known as a @emph{here-string}. +Compare the use of @var{word} in here-documents above, where @var{word} +does not undergo shell expansion. + +@item @t{<&} @var{number} +@itemx @t{>&} @var{number} +The standard input/output is duplicated from file descriptor +@var{number} (see man page dup2(2)). + +@item @t{<& -} +@itemx @t{>& -} +Close the standard input/output. + +@item @t{<& p} +@itemx @t{>& p} +The input/output from/to the coprocess is moved to the standard input/output. + +@item @t{>&} @var{word} +@itemx @t{&>} @var{word} +(Except where `@t{>&} @var{word}' matches one of the above syntaxes; +`@t{&>}' can always be used to avoid this ambiguity.) +Redirects both standard output and standard error (file descriptor 2) +in the manner of `@t{>} @var{word}'. +Note that this does @emph{not} have the same effect as `@t{>} @var{word} @t{2>&1}' +in the presence of multios (see the section below). + +@item @t{>&|} @var{word} +@itemx @t{>&!} @var{word} +@itemx @t{&>|} @var{word} +@itemx @t{&>!} @var{word} +Redirects both standard output and standard error (file descriptor 2) +in the manner of `@t{>|} @var{word}'. + +@item @t{>>&} @var{word} +@itemx @t{&>>} @var{word} +Redirects both standard output and standard error (file descriptor 2) +in the manner of `@t{>>} @var{word}'. + +@item @t{>>&|} @var{word} +@itemx @t{>>&!} @var{word} +@itemx @t{&>>|} @var{word} +@itemx @t{&>>!} @var{word} +Redirects both standard output and standard error (file descriptor 2) +in the manner of `@t{>>|} @var{word}'. + +@end table + +@noindent +If one of the above is preceded by a digit, then the file +descriptor referred to is that specified by the digit +instead of the default 0 or 1. +The order in which redirections are specified is significant. +The shell evaluates each redirection in terms of the +(@emph{file descriptor}, @emph{file}) +association at the time of evaluation. +For example: + +@noindent +@quotation +... @t{1>}@var{fname} @t{2>&1} +@end quotation + +@noindent +first associates file descriptor 1 with file @var{fname}. +It then associates file descriptor 2 with the file associated with file +descriptor 1 (that is, @var{fname}). +If the order of redirections were reversed, +file descriptor 2 would be associated +with the terminal (assuming file descriptor 1 had been) +and then file descriptor 1 would be associated with file @var{fname}. + +@noindent +The `@t{|&}' command separator described in +@ref{Simple Commands & Pipelines} +is a shorthand for `@t{2>&1 |}'. + +@noindent +The various forms of process substitution, `@t{<(}@var{list}@t{)}', +and `@t{=(}@var{list}@t{)}' for input and +`@t{>(}@var{list}@t{)}' for output, are often used together with +redirection. For example, if @var{word} in an output redirection is of the +form `@t{>(}@var{list}@t{)}' then the output is piped to the +command represented by @var{list}. See +@ref{Process Substitution}. + +@section Opening file descriptors using parameters +@noindent +@cindex file descriptors, use with parameters +@cindex parameters, for using file descriptors + +@noindent +When the shell is parsing arguments to a command, and the shell option +@t{IGNORE_BRACES} is not set, a different form of redirection is allowed: +instead of a digit before the operator there is a valid shell identifier +enclosed in braces. The shell will open a new file descriptor that +is guaranteed to be at least 10 and set the parameter named by the +identifier to the file descriptor opened. No whitespace is allowed +between the closing brace and the redirection character. For example: + +@noindent +@quotation +... @t{@{myfd@}>&1} +@end quotation + +@noindent +This opens a new file descriptor that is a duplicate of file descriptor +1 and sets the parameter @t{myfd} to the number of the file descriptor, +which will be at least 10. The new file descriptor can be written to using +the syntax @t{>&$myfd}. The file descriptor remains open in subshells +and forked external executables. + +@noindent +The syntax @t{@{}@var{varid}@t{@}>&-}, for example @t{@{myfd@}>&-}, may be used +to close a file descriptor opened in this fashion. Note that the +parameter given by @var{varid} must previously be set to a file descriptor +in this case. + +@noindent +It is an error to open or close a file descriptor in this fashion when the +parameter is readonly. However, it is not an error to read or write a file +descriptor using @t{<&$}@var{param} or @t{>&$}@var{param} if @var{param} is +readonly. + +@noindent +If the option @t{CLOBBER} is unset, it is an error to open a file +descriptor using a parameter that is already set to an open file descriptor +previously allocated by this mechanism. Unsetting the parameter before +using it for allocating a file descriptor avoids the error. + +@noindent +Note that this mechanism merely allocates or closes a file descriptor; it +does not perform any redirections from or to it. It is usually convenient +to allocate a file descriptor prior to use as an argument to @t{exec}. +The syntax does not in any case work when used around complex commands +such as parenthesised subshells or loops, where the opening brace is +interpreted as part of a command list to be executed in the current shell. + +@noindent +The following shows a typical sequence of allocation, use, and closing of a +file descriptor: + +@noindent +@example +integer myfd +exec @{myfd@}>~/logs/mylogfile.txt +print This is a log message. >&$myfd +exec @{myfd@}>&- +@end example + +@noindent +Note that the expansion of the variable in the expression @t{>&$myfd} +occurs at the point the redirection is opened. This is after the expansion +of command arguments and after any redirections to the left on the command +line have been processed. + +@section Multios +@noindent +@cindex multios +@pindex MULTIOS, use of +If the user tries to open a file descriptor for writing more than once, +the shell opens the file descriptor as a pipe to a process that copies +its input to all the specified outputs, similar to @cite{tee}, +provided the @t{MULTIOS} option is set, as it is by default. Thus: + +@noindent +@example +date >foo >bar +@end example + +@noindent +writes the date to two files, named `@t{foo}' and `@t{bar}'. +Note that a pipe is an implicit redirection; thus + +@noindent +@example +date >foo | cat +@end example + +@noindent +writes the date to the file `@t{foo}', and also pipes it to cat. + +@noindent +Note that the shell opens all the files to be used in the multio process +immediately, not at the point they are about to be written. + +@noindent +Note also that redirections are always expanded in order. This happens +regardless of the setting of the @t{MULTIOS} option, but with the option +in effect there are additional consequences. For example, +the meaning of the expression @t{>&1} will change after a previous +redirection: + +@noindent +@example +date >&1 >output +@end example + +@noindent +In the case above, the @t{>&1} refers to the standard output at the +start of the line; the result is similar to the @t{tee} command. +However, consider: + +@noindent +@example +date >output >&1 +@end example + +@noindent +As redirections are evaluated in order, when the @t{>&1} is encountered +the standard output is set to the file @t{output} and another copy of +the output is therefore sent to that file. This is unlikely to be what +is intended. + +@noindent +If the @t{MULTIOS} +option is set, the word after a redirection operator is also subjected +to filename generation (globbing). Thus + +@noindent +@example +: > * +@end example + +@noindent +will truncate all files in the current directory, +assuming there's at least one. (Without the @t{MULTIOS} +option, it would create an empty file called `@t{*}'.) +Similarly, you can do + +@noindent +@example +echo exit 0 >> *.sh +@end example + +@noindent +If the user tries to open a file descriptor for reading more than once, +the shell opens the file descriptor as a pipe to a process that copies +all the specified inputs to its output in the order specified, provided +the @t{MULTIOS} option is set. It should be noted that each file is +opened immediately, not at the point where it is about to be read: +this behaviour differs from @t{cat}, so if strictly standard behaviour +is needed, @t{cat} should be used instead. + +@noindent +Thus + +@noindent +@example +sort <foo <fubar +@end example + +@noindent +or even + +@noindent +@example +sort <f@{oo,ubar@} +@end example + +@noindent +is equivalent to `@t{cat foo fubar | sort}'. + +@noindent +Expansion of the redirection argument occurs at the point the redirection +is opened, at the point described above for the expansion of the variable +in @t{>&$myfd}. + +@noindent +Note that a pipe is an implicit redirection; thus + +@noindent +@example +cat bar | sort <foo +@end example + +@noindent +is equivalent to `@t{cat bar foo | sort}' (note the order of the inputs). + +@noindent +If the @t{MULTIOS} option is @emph{un}set, +each redirection replaces the previous redirection for that file descriptor. +However, all files redirected to are actually opened, so + +@noindent +@example +echo Hello > bar > baz +@end example + +@noindent +when @t{MULTIOS} is unset will truncate `@t{bar}', and write `@t{Hello}' +into `@t{baz}'. + +@noindent +There is a problem when an output multio is attached to an external +program. A simple example shows this: + +@noindent +@example +cat file >file1 >file2 +cat file1 file2 +@end example + +@noindent +Here, it is possible that the second `@t{cat}' will not display the full +contents of @t{file1} and @t{file2} (i.e. the original contents of +@t{file} repeated twice). + +@noindent +The reason for this is that the multios are spawned after the @t{cat} +process is forked from the parent shell, so the parent shell does not +wait for the multios to finish writing data. This means the command as +shown can exit before @t{file1} and @t{file2} are completely written. +As a workaround, it is possible to run the @t{cat} process as part of a +job in the current shell: + +@noindent +@example +@{ cat file @} >file >file2 +@end example + +@noindent +Here, the @t{@{}@var{...}@t{@}} job will pause to wait for both files to be +written. + +@noindent + +@section Redirections with no command +@noindent +When a simple command consists of one or more redirection operators +and zero or more parameter assignments, but no command name, zsh can +behave in several ways. + +@noindent +@vindex NULLCMD, use of +@pindex CSH_NULLCMD, use of +If the parameter @t{NULLCMD} is not set or the option @t{CSH_NULLCMD} is +set, an error is caused. This is the @cite{csh} behavior and @t{CSH_NULLCMD} +is set by default when emulating @cite{csh}. + +@noindent +@pindex SH_NULLCMD, use of +If the option @t{SH_NULLCMD} is set, the builtin `@t{:}' is inserted as a +command with the given redirections. This is the default when emulating +@cite{sh} or @cite{ksh}. + +@noindent +@vindex READNULLCMD, use of +Otherwise, if the parameter @t{NULLCMD} is set, its value will be used as a +command with the given redirections. If both @t{NULLCMD} and +@t{READNULLCMD} are set, then the value of the latter will be used instead +of that of the former when the redirection is an input. The default for +@t{NULLCMD} is `@t{cat}' and for @t{READNULLCMD} is `@t{more}'. Thus + +@noindent +@example +< file +@end example + +@noindent +shows the contents of @t{file} on standard output, with paging if that is a +terminal. @t{NULLCMD} and @t{READNULLCMD} may refer to shell functions. + +@noindent +@c (avoiding a yodl bug) +@c Yodl file: Zsh/exec.yo +@node Command Execution, Functions, Redirection, Top + +@chapter Command Execution +@noindent +@cindex command execution +@cindex execution, of commands +@cindex command not found, handling of +@findex command_not_found_handler +If a command name contains no slashes, the shell attempts to locate +it. If there exists a shell function by that name, the function +is invoked as described in @ref{Functions}. If there exists +a shell builtin by that name, the builtin is invoked. + +@noindent +@vindex path, use of +Otherwise, the shell searches each element of @t{$path} for a +directory containing an executable file by that name. If the +search is unsuccessful, the shell prints an error message and returns +a nonzero exit status. + +@noindent +If execution fails because the file is not in executable format, +and the file is not a directory, it is assumed to be a shell +script. @t{/bin/sh} is spawned to execute it. If the program +is a file beginning with `@t{#!}', the remainder of the first line +specifies an interpreter for the program. The shell will +execute the specified interpreter on operating systems that do +not handle this executable format in the kernel. + +@noindent +If no external command is found but a function @t{command_not_found_handler} +exists the shell executes this function with all +command line arguments. The return status of the function becomes the +status of the command. If the function wishes to mimic the +behaviour of the shell when the command is not found, it should +print the message `@t{command not found:} @var{cmd}' to standard error +and return status 127. Note that the handler is executed in a +subshell forked to execute an external command, hence changes to +directories, shell parameters, etc. have no effect on the main shell. + +@noindent +@c (avoiding a yodl bug) +@c Yodl file: Zsh/func.yo +@node Functions, Jobs & Signals, Command Execution, Top + +@chapter Functions +@noindent +@cindex functions +@findex function, use of +Shell functions are defined with the @t{function} reserved word or the +special syntax `@var{funcname} @t{()}'. +Shell functions are read in and stored internally. +Alias names are resolved when the function is read. +Functions are executed like commands with the arguments +passed as positional parameters. +(See @ref{Command Execution}.) + +@noindent +Functions execute in the same process as the caller and +share all files +and present working directory with the +caller. A trap on @t{EXIT} set inside a function +is executed after the function completes in the environment +of the caller. + +@noindent +@findex return, use of +The @t{return} builtin is used to return from function calls. + +@noindent +@findex functions, use of +Function identifiers can be listed with the @t{functions} builtin. +@findex unfunction, use of +Functions can be undefined with the @t{unfunction} builtin. + +@section Autoloading Functions +@noindent +@cindex autoloading functions +@cindex functions, autoloading + +@noindent +@findex autoload, use of +@vindex fpath, use of +A function can be marked as @emph{undefined} using the @t{autoload} builtin +(or `@t{functions -u}' or `@t{typeset -fu}'). Such a function has no +body. When the function is first executed, the shell searches for its +definition using the elements of the @t{fpath} variable. Thus to define +functions for autoloading, a typical sequence is: + +@noindent +@example +fpath=(~/myfuncs $fpath) +autoload myfunc1 myfunc2 ... +@end example + +@noindent +The usual alias expansion during reading will be suppressed if the +@t{autoload} builtin or its equivalent is given the option @t{-U}. This is +recommended for the use of functions supplied with the zsh distribution. +@findex zcompile, use of +Note that for functions precompiled with the @t{zcompile} builtin command +the flag @t{-U} must be provided when the @t{.zwc} file is created, as the +corresponding information is compiled into the latter. + +@noindent +For each @var{element} in @t{fpath}, the shell looks for three possible +files, the newest of which is used to load the definition for the function: + +@noindent +@table @asis +@item @var{element}@t{.zwc} +A file created with the @t{zcompile} builtin command, which is expected to +contain the definitions for all functions in the directory named +@var{element}. The file is treated in the same manner as a directory +containing files for functions and is searched for the definition of the +function. If the definition is not found, the search for a definition +proceeds with the other two possibilities described below. + +@noindent +If @var{element} already includes a @t{.zwc} extension (i.e. the extension +was explicitly given by the user), @var{element} is searched for the +definition of the function without comparing its age to that of other +files; in fact, there does not need to be any directory named @var{element} +without the suffix. Thus including an element such as +`@t{/usr/local/funcs.zwc}' in @t{fpath} will speed up the search for +functions, with the disadvantage that functions included must be explicitly +recompiled by hand before the shell notices any changes. + +@item @var{element}@t{/}@var{function}@t{.zwc} +A file created with @t{zcompile}, which is expected to contain the +definition for @var{function}. It may include other function definitions +as well, but those are neither loaded nor executed; a file found in this +way is searched @emph{only} for the definition of @var{function}. + +@item @var{element}@t{/}@var{function} +A file of zsh command text, taken to be the definition for @var{function}. + +@end table + +@noindent +In summary, the order of searching is, first, in the @emph{parents of} +directories in @t{fpath} for the newer of either a compiled directory or +a directory in @t{fpath}; second, if more than one of these contains a +definition for the function that is sought, the leftmost in the @t{fpath} +is chosen; and third, within a directory, the newer of either a compiled +function or an ordinary function definition is used. + +@noindent +@pindex KSH_AUTOLOAD, use of +If the @t{KSH_AUTOLOAD} option is set, or the file contains only a +simple definition of the function, the file's contents will be executed. +This will normally define the function in question, but may also perform +initialization, which is executed in the context of the function execution, +and may therefore define local parameters. It is an error if the function +is not defined by loading the file. + +@noindent +Otherwise, the function body (with no surrounding `@var{funcname}@t{() +@{}@var{...}@t{@}}') is taken to be the complete contents of the file. This +form allows the file to be used directly as an executable shell script. If +processing of the file results in the function being re-defined, the +function itself is not re-executed. To force the shell to perform +initialization and then call the function defined, the file should contain +initialization code (which will be executed then discarded) in addition to +a complete function definition (which will be retained for subsequent calls +to the function), and a call to the shell function, including any +arguments, at the end. + +@noindent +For example, suppose the autoload file @t{func} contains + +@noindent +@example +func() @{ print This is func; @} +print func is initialized +@end example + +@noindent +then `@t{func; func}' with @t{KSH_AUTOLOAD} set will produce both messages +on the first call, but only the message `@t{This is func}' on the second +and subsequent calls. Without @t{KSH_AUTOLOAD} set, it will produce +the initialization message on the first call, and the other message on the +second and subsequent calls. + +@noindent +It is also possible to create a function that is not marked as autoloaded, +but which loads its own definition by searching @t{fpath}, by using +`@t{autoload -X}' within a shell function. For example, the following are +equivalent: + +@noindent +@example +myfunc() @{ + autoload -X +@} +myfunc args... +@end example + +@noindent +and + +@noindent +@example +unfunction myfunc # if myfunc was defined +autoload myfunc +myfunc args... +@end example + +@noindent +In fact, the @t{functions} command outputs `@t{builtin autoload -X}' as +the body of an autoloaded function. This is done so that + +@noindent +@example +eval "$(functions)" +@end example + +@noindent +produces a reasonable result. A true autoloaded function can be +identified by the presence of the comment `@t{# undefined}' in the body, +because all comments are discarded from defined functions. + +@noindent +To load the definition of an autoloaded function @t{myfunc} without +executing @t{myfunc}, use: + +@noindent +@example +autoload +X myfunc +@end example + +@noindent + +@section Anonymous Functions +@noindent +@cindex anonymous functions +@cindex functions, anonymous + +@noindent +If no name is given for a function, it is `anonymous' and is handled +specially. Either form of function definition may be used: a `@t{()}' with +no preceding name, or a `@t{function}' with an immediately following open +brace. The function is executed immediately at the point of definition and +is not stored for future use. The function name is set to `@t{(anon)}'. + +@noindent +Arguments to the function may be specified as words following the +closing brace defining the function, hence if there are none no +arguments (other than @t{$0}) are set. This is a difference from the +way other functions are parsed: normal function definitions may be +followed by certain keywords such as `@t{else}' or `@t{fi}', which will +be treated as arguments to anonymous functions, so that a newline or +semicolon is needed to force keyword interpretation. + +@noindent +Note also that the argument list of any enclosing script or function is +hidden (as would be the case for any other function called at this +point). + +@noindent +Redirections may be applied to the anonymous function in the same manner as +to a current-shell structure enclosed in braces. The main use of anonymous +functions is to provide a scope for local variables. This is particularly +convenient in start-up files as these do not provide their own local +variable scope. + +@noindent +For example, + +@noindent +@example +variable=outside +function @{ + local variable=inside + print "I am $variable with arguments $*" +@} this and that +print "I am $variable" +@end example + +@noindent +outputs the following: + +@noindent +@example +I am inside with arguments this and that +I am outside +@end example + +@noindent +Note that function definitions with arguments that expand to nothing, +for example `@t{name=; function $name @{ }@var{...}@t{ @}}', are not +treated as anonymous functions. Instead, they are treated as normal +function definitions where the definition is silently discarded. + +@noindent + +@section Special Functions +@noindent +Certain functions, if defined, have special meaning to the shell. + +@noindent + +@subsection Hook Functions +@noindent +@findex functions, hook +@findex hook functions + +@noindent +For the functions below, it is possible to define an array that has the +same name as the function with `@t{_functions}' appended. Any element in +such an array is taken as the name of a function to execute; it is executed +in the same context and with the same arguments as the basic function. For +example, if @t{$chpwd_functions} is an array containing the values +`@t{mychpwd}', `@t{chpwd_save_dirstack}', then the shell attempts to +execute the functions `@t{chpwd}', `@t{mychpwd}' and +`@t{chpwd_save_dirstack}', in that order. Any function that does not exist +is silently ignored. A function found by this mechanism is referred to +elsewhere as a `hook function'. An error in any function causes subsequent +functions not to be run. Note further that an error in a @t{precmd} hook +causes an immediately following @t{periodic} function not to run (though +it may run at the next opportunity). + +@noindent +@table @asis +@findex chpwd +@vindex chpwd_functions +@item @t{chpwd} +Executed whenever the current working directory is changed. + +@findex periodic +@vindex periodic_functions +@item @t{periodic} +@vindex PERIOD +If the parameter @t{PERIOD} +is set, this function is executed every @t{$PERIOD} +seconds, just before a prompt. Note that if multiple functions +are defined using the array @t{periodic_functions} only one +period is applied to the complete set of functions, and the +scheduled time is not reset if the list of functions is altered. +Hence the set of functions is always called together. + +@findex precmd +@vindex precmd_functions +@item @t{precmd} +Executed before each prompt. Note that precommand functions are not +re-executed simply because the command line is redrawn, as happens, for +example, when a notification about an exiting job is displayed. + +@findex preexec +@vindex preexec_functions +@item @t{preexec} +Executed just after a command has been read and is about to be +executed. If the history mechanism is active (regardless of whether the +line was discarded from the history buffer), the string that the user +typed is passed as the first argument, otherwise it is an empty string. +The actual command that will be executed (including expanded aliases) is +passed in two different forms: the second argument is a single-line, +size-limited version of the command (with things like function bodies +elided); the third argument contains the full text that is being +executed. + +@findex zshaddhistory +@vindex zshaddhistory_functions +@item @t{zshaddhistory} +@cindex history, hook when line is saved +Executed when a history line has been read interactively, but +before it is executed. The sole argument is the complete history +line (so that any terminating newline will still be present). + +@noindent +If any of the hook functions returns status 1 (or any non-zero value +other than 2, though this is not guaranteed for future versions of the +shell) the history line will not be saved, although it lingers in the +history until the next line is executed, allowing you to reuse or edit +it immediately. + +@noindent +If any of the hook functions returns status 2 the history line +will be saved on the internal history list, but not written to +the history file. In case of a conflict, the first non-zero status +value is taken. + +@noindent +A hook function may call `@t{fc -p} @var{...}' to switch the history +context so that the history is saved in a different file from the +that in the global @t{HISTFILE} parameter. This is handled specially: +the history context is automatically restored after the processing +of the history line is finished. + +@noindent +The following example function works with one of the options +@t{INC_APPEND_HISTORY} or @t{SHARE_HISTORY} set, in order that the line +is written out immediately after the history entry is added. It first +adds the history line to the normal history with the newline stripped, +which is usually the correct behaviour. Then it switches the history +context so that the line will be written to a history file in the +current directory. + +@noindent +@example +zshaddhistory() @{ + print -sr -- $@{1%%$'\n'@} + fc -p .zsh_local_history +@} +@end example + +@findex zshexit +@vindex zshexit_functions +@item @t{zshexit} +Executed at the point where the main shell is about to exit normally. +This is not called by exiting subshells, nor when the @t{exec} +precommand modifier is used before an external command. Also, unlike +@t{TRAPEXIT}, it is not called when functions exit. + +@end table + +@noindent + +@subsection Trap Functions +@noindent + +@noindent +The functions below are treated specially but do not have corresponding +hook arrays. + +@noindent +@table @asis +@item @t{TRAP}@var{NAL} +@cindex signals, trapping +@cindex trapping signals +If defined and non-null, +this function will be executed whenever the shell +catches a signal @t{SIG}@var{NAL}, where @var{NAL} is a signal +name as specified for the @t{kill} builtin. +The signal number will be passed as the first parameter to the function. + +@noindent +If a function of this form is defined and null, +the shell and processes spawned by it will ignore @t{SIG}@var{NAL}. + +@noindent +The return status from the function is handled specially. If it is +zero, the signal is assumed to have been handled, and execution continues +normally. Otherwise, the shell will behave as interrupted except that +the return status of the trap is retained. + +@noindent +Programs terminated by uncaught signals typically return the status 128 +plus the signal number. Hence the following causes the handler for +@t{SIGINT} to print a message, then mimic the usual effect of the signal. + +@noindent +@example +TRAPINT() @{ + print "Caught SIGINT, aborting." + return $(( 128 + $1 )) +@} +@end example + +@noindent +The functions @t{TRAPZERR}, @t{TRAPDEBUG} and @t{TRAPEXIT} are never +executed inside other traps. + +@findex TRAPDEBUG +@item @t{TRAPDEBUG} +If the option @t{DEBUG_BEFORE_CMD} is set (as it is by default), executed +before each command; otherwise executed after each command. See +the description of the @t{trap} builtin in +@ref{Shell Builtin Commands} for details of additional features provided +in debug traps. + +@findex TRAPEXIT +@item @t{TRAPEXIT} +Executed when the shell exits, +or when the current function exits if defined inside a function. +The value of @t{$?} at the start of execution is the exit status of the +shell or the return status of the function exiting. + +@findex TRAPZERR +@findex TRAPERR +@item @t{TRAPZERR} +Executed whenever a command has a non-zero exit status. However, the +function is not executed if the command occurred in a sublist followed by +`@t{&&}' or `@t{||}'; only the final command in a sublist of this type +causes the trap to be executed. The function @t{TRAPERR} acts the same as +@t{TRAPZERR} on systems where there is no @t{SIGERR} (this is the usual +case). + +@end table + +@noindent +@findex trap, use of +The functions beginning `@t{TRAP}' may alternatively be defined with the +@t{trap} builtin: this may be preferable for some uses. Setting a trap +with one form removes any trap of the other form for the same signal; +removing a trap in either form removes all traps for the same signal. +The forms + +@noindent +@example +TRAPNAL() @{ + # code +@} +@end example + +@noindent +('function traps') and + +@noindent +@example +trap ' + # code +' NAL +@end example + +@noindent +('list traps') are equivalent in most ways, the exceptions being the +following: + +@noindent +@itemize @bullet + +@item +Function traps have all the properties of normal functions, +appearing in the list of functions and being called with their own +function context rather than the context where the trap was triggered. +@item +The return status from function traps is special, whereas a return +from a list trap causes the surrounding context to return with the given +status. +@item +Function traps are not reset within subshells, in accordance with +zsh behaviour; list traps are reset, in accordance with POSIX +behaviour. +@end itemize +@c (avoiding a yodl bug) +@c Yodl file: Zsh/jobs.yo +@node Jobs & Signals, Arithmetic Evaluation, Functions, Top + +@chapter Jobs & Signals +@noindent + +@section Jobs +@noindent +@cindex jobs +@pindex MONITOR, use of +If the @t{MONITOR} option is set, +an interactive shell associates a @emph{job} with each pipeline. +It keeps a table of current jobs, printed by the @t{jobs} +command, and assigns them small integer numbers. +When a job is started asynchronously with `@t{&}', +the shell prints a line to standard error which looks like: + +@noindent +@example +[1] 1234 +@end example + +@noindent +indicating that the job which was started asynchronously was job number +1 and had one (top-level) process, whose process ID was 1234. + +@noindent +If a job is started with `@t{&|}' or `@t{&!}', +then that job is immediately disowned. After startup, it +does not have a place in the job table, and is not subject +to the job control features described here. + +@noindent +If you are running a job and wish to do something else you may hit the key +^Z (control-Z) which sends a @t{TSTP} signal to the current job: this key +may be redefined by the @t{susp} option of the external @t{stty} command. +@cindex jobs, suspending +@cindex suspending jobs +The shell will then normally indicate that the job has been `suspended', +and print another prompt. You can then manipulate the state of this job, +@findex bg, use of +putting it in the background with the @t{bg} command, or run some other +commands and then eventually bring the job back into the foreground with +@findex fg, use of +the foreground command @t{fg}. A ^Z takes effect immediately and +is like an interrupt in that pending output and unread input are discarded +when it is typed. + +@noindent +A job being run in the background will suspend if it tries to read +from the terminal. + +@noindent +Note that if the job running in the foreground is a shell function, +then suspending it will have the effect of causing the shell to fork. +This is necessary to separate the function's state from that of the +parent shell performing the job control, so that the latter can return +to the command line prompt. As a result, even if @t{fg} is +used to continue the job the function will no longer be part of the +parent shell, and any variables set by the function will not be visible +in the parent shell. Thus the behaviour is different from the case +where the function was never suspended. Zsh is different from many +other shells in this regard. + +@noindent +One additional side effect is that use of @t{disown} with a job +created by suspending shell code in this fashion is delayed: the +job can only be disowned once any process started from the parent +shell has terminated. At that point, the disowned job disappears +silently from the job list. + +@noindent +The same behaviour is found when the shell is executing code as the +right hand side of a pipeline or any complex shell construct such as +@t{if}, @t{for}, etc., in order that the entire block of code +can be managed as a single job. +@cindex background jobs, I/O +@cindex jobs, background, I/O +Background jobs are normally allowed to produce output, +but this can be disabled by giving the command `@t{stty tostop}'. +If you set this +tty option, then background jobs will suspend when they try to produce +output like they do when they try to read input. + +@noindent +When a command is suspended and continued later with the @t{fg} or +@t{wait} builtins, zsh restores tty modes that were in effect when it was +suspended. This (intentionally) does not apply if the command is +continued via `@t{kill -CONT}', nor when it is continued with @t{bg}. + +@noindent +@cindex jobs, referring to +@cindex referring to jobs +There are several ways to refer to jobs in the shell. +A job can be referred to by the process ID of any process of the job +or by one of the following: + +@noindent +@table @asis +@item @t{%}@var{number} +The job with the given number. +@item @t{%}@var{string} +The last job whose command line begins with @var{string}. +@item @t{%?}@var{string} +The last job whose command line contains @var{string}. +@item @t{%%} +Current job. +@item @t{%+} +Equivalent to `@t{%%}'. +@item @t{%-} +Previous job. +@end table + +@noindent +The shell learns immediately whenever a process changes state. +@pindex NOTIFY, use of +It normally informs you whenever a job becomes blocked so that +no further progress is possible. If the @t{NOTIFY} option is not set, +it waits until just before it prints a prompt before it informs you. +All such notifications are sent directly to the terminal, not to +the standard output or standard error. + +@noindent +When the monitor mode is on, each background job that completes +triggers any trap set for @t{CHLD}. + +@noindent +When you try to leave the shell while jobs are running or suspended, you will +be warned that `You have suspended (running) jobs'. +You may use the @t{jobs} command to see what they are. +If you do this or immediately try to +exit again, the shell will not warn you a second time; the suspended +jobs will be terminated, and the running jobs will be sent +a @t{SIGHUP} signal, if the @t{HUP} option is set. +@pindex HUP, use of + +@noindent +@cindex jobs, disowning +@cindex disowning jobs +@findex disown, use of +To avoid having the shell terminate the running jobs, either +use the @cite{nohup} command (see man page nohup(1)) +or the @t{disown} builtin. + +@section Signals +@noindent +The @t{INT} and @t{QUIT} signals for an invoked +command are ignored if the command is followed by +`@t{&}' and the @t{MONITOR} option is not active. +The shell itself always ignores the @t{QUIT} signal. +Otherwise, signals have the values +inherited by the shell from its parent +(but see the @t{TRAP}@var{NAL} special functions in @ref{Functions}). + +@noindent +@cindex exiting shell, and asynchronous jobs +@cindex asynchronous jobs, and exiting shell +@cindex jobs, asynchronous, and exiting shell +Certain jobs are run asynchronously by the shell other than those +explicitly put into the background; even in cases where the shell +would usually wait for such jobs, an explicit @t{exit} command +or exit due to the option @t{ERR_EXIT} will cause the shell to +exit without waiting. Examples of such asynchronous jobs are +process substitution, see +@ref{Process Substitution}, and the handler processes for +multios, see +the section Multios in @ref{Redirection}. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/arith.yo +@node Arithmetic Evaluation, Conditional Expressions, Jobs & Signals, Top + +@chapter Arithmetic Evaluation +@noindent +@cindex arithmetic evaluation +@cindex evaluation, arithmetic +@findex let, use of +The shell can perform integer and floating point arithmetic, either using +the builtin @t{let}, or via a substitution of the form +@t{$((}@var{...}@t{))}. For +integers, the shell is usually compiled to use 8-byte precision where this +is available, otherwise precision is 4 bytes. This can be tested, for +example, by giving the command `@t{print - $(( 12345678901 ))}'; if the +number appears unchanged, the precision is at least 8 bytes. Floating +point arithmetic always uses the `double' type with whatever corresponding +precision is provided by the compiler and the library. + +@noindent +The @t{let} builtin command takes arithmetic expressions as arguments; each +is evaluated separately. Since many of the arithmetic operators, as well +as spaces, require quoting, an alternative form is provided: for any +command which begins with a `@t{((}', all the characters until a +matching `@t{))}' are treated as a quoted expression and +arithmetic expansion performed as for an argument of @t{let}. More +precisely, `@t{((}@var{...}@t{))}' is equivalent to +`@t{let "}@var{...}@t{"}'. The return status is 0 if the arithmetic value +of the expression is non-zero, 1 if it is zero, and 2 if an error occurred. + +@noindent +For example, the following statement + +@noindent +@example +(( val = 2 + 1 )) +@end example + +@noindent +is equivalent to + +@noindent +@example +let "val = 2 + 1" +@end example + +@noindent +both assigning the value 3 to the shell variable @t{val} and returning a +zero status. + +@noindent +@cindex arithmetic base +@cindex bases, in arithmetic +Integers can be in bases other than 10. +A leading `@t{0x}' or `@t{0X}' denotes hexadecimal and a leading +`@t{0b}' or `@t{0B}' binary. +Integers may also be of the form `@var{base}@t{#}@var{n}', +where @var{base} is a decimal number between two and thirty-six +representing the arithmetic base and @var{n} +is a number in that base (for example, `@t{16#ff}' is 255 in hexadecimal). +The @var{base}@t{#} may also be omitted, in which case +base 10 is used. For backwards compatibility the form +`@t{[}@var{base}@t{]}@var{n}' is also accepted. + +@noindent +An integer expression or a base given in the form +`@var{base}@t{#}@var{n}' may contain underscores (`@t{_}') after the +leading digit for visual guidance; these are ignored in computation. +Examples are @t{1_000_000} or @t{0xffff_ffff} which are equivalent to +@t{1000000} and @t{0xffffffff} respectively. + +@noindent +It is also possible to specify a base to be used for output in the form +`@t{[#}@var{base}@t{]}', for example `@t{[#16]}'. This is used when +outputting arithmetical substitutions or when assigning to scalar +parameters, but an explicitly defined integer or floating point parameter +will not be affected. If an integer variable is implicitly defined by an +arithmetic expression, any base specified in this way will be set as the +variable's output arithmetic base as if the option `@t{-i} @var{base}' to +the @t{typeset} builtin had been used. The expression has no precedence +and if it occurs more than once in a mathematical expression, the last +encountered is used. For clarity it is recommended that it appear at the +beginning of an expression. As an example: + +@noindent +@example +typeset -i 16 y +print $(( [#8] x = 32, y = 32 )) +print $x $y +@end example + +@noindent +outputs first `@t{8#40}', the rightmost value in the given output base, and +then `@t{8#40 16#20}', because @t{y} has been explicitly declared to +have output base 16, while @t{x} (assuming it does not already exist) is +implicitly typed by the arithmetic evaluation, where it acquires the output +base 8. + +@noindent +The @var{base} may be replaced or followed by an underscore, which may +itself be followed by a positive integer (if it is missing the value 3 +is used). This indicates that underscores should be inserted into the +output string, grouping the number for visual clarity. The following +integer specifies the number of digits to group together. For example: + +@noindent +@example +setopt cbases +print $(( [#16_4] 65536 ** 2 )) +@end example + +@noindent +outputs `@t{0x1_0000_0000}'. + +@noindent +The feature can be used with floating +point numbers, in which case the base must be omitted; grouping +is away from the decimal point. For example, + +@noindent +@example +zmodload zsh/mathfunc +print $(( [#_] sqrt(1e7) )) +@end example + +@noindent +outputs `@t{3_162.277_660_168_379_5}' (the number of decimal places +shown may vary). + +@noindent +@pindex C_BASES, use of +@pindex OCTAL_ZEROES, use of +If the @t{C_BASES} option is set, hexadecimal numbers are output in the standard C +format, for example `@t{0xFF}' instead of the usual `@t{16#FF}'. If the +option @t{OCTAL_ZEROES} is also set (it is not by default), octal numbers +will be treated similarly and hence appear as `@t{077}' instead of +`@t{8#77}'. This option has no effect on the output of bases other than +hexadecimal and octal, and these formats are always understood on input. + +@noindent +When an output base is specified using the `@t{[#}@var{base}@t{]}' syntax, +an appropriate base prefix will be output if necessary, so that the value +output is valid syntax for input. If the @t{#} is doubled, for example +`@t{[##16]}', then no base prefix is output. + +@noindent +Floating point constants are recognized by the presence of a decimal point +or an exponent. The decimal point may be the first character of the +constant, but the exponent character @t{e} or @t{E} may not, as it will be +taken for a parameter name. All numeric parts (before and after the +decimal point and in the exponent) may contain underscores after the +leading digit for visual guidance; these are ignored in computation. + +@noindent +@cindex arithmetic operators +@cindex operators, arithmetic +An arithmetic expression uses nearly the same syntax and +associativity of expressions as in C. + +@noindent +In the native mode of operation, the following operators are supported +(listed in decreasing order of precedence): + +@noindent +@table @asis +@item @t{+ - ! ~ ++ --} +unary plus/minus, logical NOT, complement, @{pre,post@}@{in,de@}crement +@item @t{<< >>} +bitwise shift left, right +@item @t{&} +bitwise AND +@item @t{^} +bitwise XOR +@item @t{|} +bitwise OR +@item @t{**} +exponentiation +@item @t{* / %} +multiplication, division, modulus (remainder) +@item @t{+ -} +addition, subtraction +@item @t{< > <= >=} +comparison +@item @t{== !=} +equality and inequality +@item @t{&&} +logical AND +@item @t{|| ^^} +logical OR, XOR +@item @t{? :} +ternary operator +@item @t{= += -= *= /= %= &= ^= |= <<= >>= &&= ||= ^^= **=} +assignment +@item @t{,} +comma operator +@end table + +@noindent +The operators `@t{&&}', `@t{||}', `@t{&&=}', and `@t{||=}' are +short-circuiting, and only one of the latter two expressions in a ternary +operator is evaluated. Note the precedence of the bitwise AND, OR, +and XOR operators. + +@noindent +With the option @t{C_PRECEDENCES} the precedences (but no other +properties) of the operators are altered to be the same as those in +most other languages that support the relevant operators: + +@noindent +@table @asis +@item @t{+ - ! ~ ++ --} +unary plus/minus, logical NOT, complement, @{pre,post@}@{in,de@}crement +@item @t{**} +exponentiation +@item @t{* / %} +multiplication, division, modulus (remainder) +@item @t{+ -} +addition, subtraction +@item @t{<< >>} +bitwise shift left, right +@item @t{< > <= >=} +comparison +@item @t{== !=} +equality and inequality +@item @t{&} +bitwise AND +@item @t{^} +bitwise XOR +@item @t{|} +bitwise OR +@item @t{&&} +logical AND +@item @t{^^} +logical XOR +@item @t{||} +logical OR +@item @t{? :} +ternary operator +@item @t{= += -= *= /= %= &= ^= |= <<= >>= &&= ||= ^^= **=} +assignment +@item @t{,} +comma operator +@end table + +@noindent +Note the precedence of exponentiation in both cases is below +that of unary operators, hence `@t{-3**2}' evaluates as `@t{9}', not +`@t{-9}'. Use parentheses where necessary: `@t{-(3**2)}'. This is +for compatibility with other shells. + +@noindent +@cindex mathematical functions, use of +@cindex functions, math, use of +Mathematical functions can be called with the syntax +`@var{func}@t{(}@var{args}@t{)}', where the function decides +if the @var{args} is used as a string or a comma-separated list of +arithmetic expressions. The shell currently defines no mathematical +functions by default, but the module @t{zsh/mathfunc} may be loaded with +the @t{zmodload} builtin to provide standard floating point mathematical +functions. + +@noindent +An expression of the form `@t{##}@var{x}' where @var{x} is any character +sequence such as `@t{a}', `@t{^A}', or `@t{\M-\C-x}' gives the value of +this character and an expression of the form `@t{#}@var{name}' gives the +value of the first character of the contents of the parameter @var{name}. +Character values are according to the character set used in the current +locale; for multibyte character handling the option @t{MULTIBYTE} must be +set. Note that this form is different from `@t{$#}@var{name}', a standard +parameter substitution which gives the length of the parameter @var{name}. +`@t{#\}' is accepted instead of `@t{##}', but its use is deprecated. + +@noindent +Named parameters and subscripted arrays can be referenced by name within an +arithmetic expression without using the parameter expansion syntax. For +example, + +@noindent +@example +((val2 = val1 * 2)) +@end example + +@noindent +assigns twice the value of @t{$val1} to the parameter named @t{val2}. + +@noindent +An internal integer representation of a named parameter +can be specified with the @t{integer} builtin. +@cindex parameters, integer +@cindex integer parameters +@findex integer, use of +Arithmetic evaluation is performed on the value of each +assignment to a named parameter declared integer +in this manner. Assigning a floating point number to an integer results in +rounding towards zero. + +@noindent +@cindex parameters, floating point +@cindex floating point parameters +@findex float, use of +Likewise, floating point numbers can be declared with the @t{float} +builtin; there are two types, differing only in their output format, as +described for the @t{typeset} builtin. The output format can be bypassed +by using arithmetic substitution instead of the parameter substitution, +i.e. `@t{$@{}@var{float}@t{@}}' uses the defined format, but +`@t{$((}@var{float}@t{))}' uses a generic floating point +format. + +@noindent +Promotion of integer to floating point values is performed where +necessary. In addition, if any operator which requires an integer +(`@t{&}', `@t{|}', `@t{^}', `@t{<<}', `@t{>>}' and their equivalents with +assignment) is given a floating point argument, it will be silently rounded +towards zero except for `@t{~}' which rounds down. + +@noindent +Users should beware that, in common with many other programming +languages but not software designed for calculation, the evaluation of +an expression in zsh is taken a term at a time and promotion of integers +to floating point does not occur in terms only containing integers. A +typical result of this is that a division such as @t{6/8} is truncated, +in this being rounded towards 0. The @t{FORCE_FLOAT} shell option can +be used in scripts or functions where floating point evaluation is +required throughout. + +@noindent +Scalar variables can hold integer or floating point values at different +times; there is no memory of the numeric type in this case. + +@noindent +If a variable is first assigned in a numeric context without previously +being declared, it will be implicitly typed as @t{integer} or @t{float} and +retain that type either until the type is explicitly changed or until the +end of the scope. This can have unforeseen consequences. For example, in +the loop + +@noindent +@example +for (( f = 0; f < 1; f += 0.1 )); do +# use $f +done +@end example + +@noindent +if @t{f} has not already been declared, the first assignment will cause it +to be created as an integer, and consequently the operation `@t{f += 0.1}' +will always cause the result to be truncated to zero, so that the loop will +fail. A simple fix would be to turn the initialization into `@t{f = 0.0}'. +It is therefore best to declare numeric variables with explicit types. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/cond.yo +@node Conditional Expressions, Prompt Expansion, Arithmetic Evaluation, Top + +@chapter Conditional Expressions +@noindent +@cindex conditional expressions +@cindex expressions, conditional +A @emph{conditional expression} is used with the @t{[[} +compound command to test attributes of files and to compare strings. +Each expression can be constructed from one or more +of the following unary or binary expressions: + +@noindent +@table @asis +@item @t{-a} @var{file} +true if @var{file} exists. + +@item @t{-b} @var{file} +true if @var{file} exists and is a block special file. + +@item @t{-c} @var{file} +true if @var{file} exists and is a character special file. + +@item @t{-d} @var{file} +true if @var{file} exists and is a directory. + +@item @t{-e} @var{file} +true if @var{file} exists. + +@item @t{-f} @var{file} +true if @var{file} exists and is a regular file. + +@item @t{-g} @var{file} +true if @var{file} exists and has its setgid bit set. + +@item @t{-h} @var{file} +true if @var{file} exists and is a symbolic link. + +@item @t{-k} @var{file} +true if @var{file} exists and has its sticky bit set. + +@item @t{-n} @var{string} +true if length of @var{string} is non-zero. + +@item @t{-o} @var{option} +true if option named @var{option} is on. @var{option} +may be a single character, in which case it is a single letter option name. +(See @ref{Specifying Options}.) + +@noindent +When no option named @var{option} exists, and the @t{POSIX_BUILTINS} option +hasn't been set, return 3 with a warning. If that option is set, return 1 +with no warning. + +@item @t{-p} @var{file} +true if @var{file} exists and is a FIFO special file (named pipe). + +@item @t{-r} @var{file} +true if @var{file} exists and is readable by current process. + +@item @t{-s} @var{file} +true if @var{file} exists and has size greater than zero. + +@item @t{-t} @var{fd} +true if file descriptor number @var{fd} +is open and associated with a terminal device. +(note: @var{fd} is not optional) + +@item @t{-u} @var{file} +true if @var{file} exists and has its setuid bit set. + +@item @t{-v} @var{varname} +true if shell variable @var{varname} is set. + +@item @t{-w} @var{file} +true if @var{file} exists and is writable by current process. + +@item @t{-x} @var{file} +true if @var{file} exists and is executable by current process. +If @var{file} exists and is a directory, then the current process +has permission to search in the directory. + +@item @t{-z} @var{string} +true if length of @var{string} is zero. + +@item @t{-L} @var{file} +true if @var{file} exists and is a symbolic link. + +@item @t{-O} @var{file} +true if @var{file} exists and is owned by the effective user ID of this process. + +@item @t{-G} @var{file} +true if @var{file} exists and its group matches +the effective group ID of this process. + +@item @t{-S} @var{file} +true if @var{file} exists and is a socket. + +@item @t{-N} @var{file} +true if @var{file} exists and its access time is +not newer than its modification time. + +@item @var{file1} @t{-nt} @var{file2} +true if @var{file1} exists and is newer than @var{file2}. + +@item @var{file1} @t{-ot} @var{file2} +true if @var{file1} exists and is older than @var{file2}. + +@item @var{file1} @t{-ef} @var{file2} +true if @var{file1} and @var{file2} exist and refer to the same file. + +@item @var{string} @t{=} @var{pattern} +@itemx @var{string} @t{==} @var{pattern} +true if @var{string} matches @var{pattern}. +The two forms are exactly equivalent. The `@t{=}' form is +the traditional shell syntax (and hence the only one generally used +with the @t{test} and @t{[} builtins); the `@t{==}' form provides +compatibility with other sorts of computer language. + +@item @var{string} @t{!=} @var{pattern} +true if @var{string} does not match @var{pattern}. + +@item @var{string} @t{=~} @var{regexp} +true if @var{string} matches the regular expression +@var{regexp}. If the option @t{RE_MATCH_PCRE} is set +@var{regexp} is tested as a PCRE regular expression using +the @t{zsh/pcre} module, else it is tested as a POSIX +extended regular expression using the @t{zsh/regex} module. +Upon successful match, some variables will be updated; no variables +are changed if the matching fails. + +@noindent +If the option @t{BASH_REMATCH} is not set the scalar parameter +@t{MATCH} is set to the substring that matched the pattern and +the integer parameters @t{MBEGIN} and @t{MEND} to the index of the start +and end, respectively, of the match in @var{string}, such that if +@var{string} is contained in variable @t{var} the expression +`@t{$@{var[$MBEGIN,$MEND]@}}' is identical to `@t{$MATCH}'. The setting +of the option @t{KSH_ARRAYS} is respected. Likewise, the array +@t{match} is set to the substrings that matched parenthesised +subexpressions and the arrays @t{mbegin} and @t{mend} to the indices of +the start and end positions, respectively, of the substrings within +@var{string}. The arrays are not set if there were no parenthesised +subexpressions. For example, if the string `@t{a short string}' is matched +against the regular expression `@t{s(...)t}', then (assuming the +option @t{KSH_ARRAYS} is not set) @t{MATCH}, @t{MBEGIN} +and @t{MEND} are `@t{short}', @t{3} and @t{7}, respectively, while @t{match}, +@t{mbegin} and @t{mend} are single entry arrays containing +the strings `@t{hor}', `@t{4}' and `@t{6}', respectively. + +@noindent +If the option @t{BASH_REMATCH} is set the array +@t{BASH_REMATCH} is set to the substring that matched the pattern +followed by the substrings that matched parenthesised +subexpressions within the pattern. + +@item @var{string1} @t{<} @var{string2} +true if @var{string1} comes before @var{string2} +based on ASCII value of their characters. + +@item @var{string1} @t{>} @var{string2} +true if @var{string1} comes after @var{string2} +based on ASCII value of their characters. + +@item @var{exp1} @t{-eq} @var{exp2} +true if @var{exp1} is numerically equal to @var{exp2}. +Note that for purely numeric comparisons use of the +@t{((}@var{...}@t{))} builtin described in +@ref{Arithmetic Evaluation} is more convenient than +conditional expressions. + +@item @var{exp1} @t{-ne} @var{exp2} +true if @var{exp1} is numerically not equal to @var{exp2}. + +@item @var{exp1} @t{-lt} @var{exp2} +true if @var{exp1} is numerically less than @var{exp2}. + +@item @var{exp1} @t{-gt} @var{exp2} +true if @var{exp1} is numerically greater than @var{exp2}. + +@item @var{exp1} @t{-le} @var{exp2} +true if @var{exp1} is numerically less than or equal to @var{exp2}. + +@item @var{exp1} @t{-ge} @var{exp2} +true if @var{exp1} is numerically greater than or equal to @var{exp2}. + +@item @t{(} @var{exp} @t{)} +true if @var{exp} is true. + +@item @t{!} @var{exp} +true if @var{exp} is false. + +@item @var{exp1} @t{&&} @var{exp2} +true if @var{exp1} and @var{exp2} are both true. + +@item @var{exp1} @t{||} @var{exp2} +true if either @var{exp1} or @var{exp2} is true. + +@end table + +@noindent +For compatibility, if there is a single argument that is not +syntactically significant, typically a variable, the condition is +treated as a test for whether the expression expands as a string of +non-zero length. In other words, @t{[[ $var ]]} is the same as @t{[[ -n +$var ]]}. It is recommended that the second, explicit, form be used +where possible. + +@noindent +Normal shell expansion is performed on the @var{file}, @var{string} and +@var{pattern} arguments, but the result of each expansion is constrained to +be a single word, similar to the effect of double quotes. + +@noindent +Filename generation is not performed on any form of argument to +conditions. However, it can be forced in any case where normal shell +expansion is valid and when the option @t{EXTENDED_GLOB} is in effect by +using an explicit glob qualifier of the form @t{(#q)} at the +end of the string. A normal glob qualifier expression may appear +between the `@t{q}' and the closing parenthesis; if none appears the +expression has no effect beyond causing filename generation. The +results of filename generation are joined together to form a single +word, as with the results of other forms of expansion. + +@noindent +This special use of filename generation is only available with the +@t{[[} syntax. If the condition occurs within the @t{[} or @t{test} +builtin commands then globbing occurs instead as part of normal command +line expansion before the condition is evaluated. In this case it may +generate multiple words which are likely to confuse the syntax of the +test command. + +@noindent +For example, + +@noindent +@example +[[ -n file*(#qN) ]] +@end example + +@noindent +produces status zero if and only if there is at least one file in the +current directory beginning with the string `@t{file}'. The globbing +qualifier @t{N} ensures that the expression is empty if there is +no matching file. + +@noindent +Pattern metacharacters are active for the @var{pattern} arguments; +the patterns are the same as those used for filename generation, see +@ref{Filename Generation}, but there is no special behaviour +of `@t{/}' nor initial dots, and no glob qualifiers are allowed. + +@noindent +In each of the above expressions, if +@var{file} is of the form `@t{/dev/fd/}@var{n}', +where @var{n} is an integer, +then the test applied to the open file whose +descriptor number is @var{n}, +even if the underlying system does not support +the @t{/dev/fd} directory. + +@noindent +In the forms which do numeric comparison, the expressions @var{exp} +undergo arithmetic expansion as if they were enclosed in +@t{$((}@var{...}@t{))}. + +@noindent +For example, the following: + +@noindent +@example +[[ ( -f foo || -f bar ) && $report = y* ]] && print File exists. +@end example + +@noindent +tests if either file @t{foo} or file @t{bar} exists, and if so, if the +value of the parameter @t{report} begins with `@t{y}'; if the complete +condition is true, the message `@t{File exists.}' is printed. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/prompt.yo +@node Prompt Expansion, Expansion, Conditional Expressions, Top + +@chapter Prompt Expansion +@noindent + +@section Expansion of Prompt Sequences +@noindent +@cindex prompt expansion +@cindex expansion, prompt +Prompt sequences undergo a special form of expansion. This type of expansion +is also available using the @t{-P} option to the @t{print} builtin. + +@noindent +@pindex PROMPT_SUBST, use of +If the @t{PROMPT_SUBST} option is set, the prompt string is first subjected to +@emph{parameter expansion}, +@emph{command substitution} and +@emph{arithmetic expansion}. +See +@ref{Expansion}. + +@noindent +Certain escape sequences may be recognised in the prompt string. + +@noindent +@pindex PROMPT_BANG, use of +If the @t{PROMPT_BANG} option is set, a `@t{!}' in the prompt is replaced +by the current history event number. A literal `@t{!}' may then be +represented as `@t{!!}'. + +@noindent +@pindex PROMPT_PERCENT, use of +If the @t{PROMPT_PERCENT} option is set, certain escape sequences that +start with `@t{%}' are expanded. +Many escapes are followed by a single character, although some of these +take an optional integer argument that +should appear between the `@t{%}' and the next character of the +sequence. More complicated escape sequences are available to provide +conditional expansion. + +@noindent + +@section Simple Prompt Escapes +@noindent + +@noindent + +@subsection Special characters +@noindent +@table @asis +@item @t{%%} +A `@t{%}'. + +@item @t{%)} +A `@t{)}'. + +@end table + +@noindent + +@subsection Login information +@noindent +@table @asis +@item @t{%l} +The line (tty) the user is logged in on, without `@t{/dev/}' prefix. +If the name starts with `@t{/dev/tty}', that prefix is stripped. + +@item @t{%M} +The full machine hostname. + +@item @t{%m} +The hostname up to the first `@t{.}'. +An integer may follow the `@t{%}' to specify +how many components of the hostname are desired. With a negative integer, +trailing components of the hostname are shown. + +@item @t{%n} +@t{$USERNAME}. + +@item @t{%y} +The line (tty) the user is logged in on, without `@t{/dev/}' prefix. +This does not treat `@t{/dev/tty}' names specially. + +@end table + +@noindent + +@subsection Shell state +@noindent +@table @asis +@item @t{%#} +A `@t{#}' if the shell is running with privileges, a `@t{%}' if not. +Equivalent to `@t{%(!.#.%%)}'. +The definition of `privileged', for these purposes, is that either the +effective user ID is zero, or, if POSIX.1e capabilities are supported, that +at least one capability is raised in either the Effective or Inheritable +capability vectors. + +@item @t{%?} +The return status of the last command executed just before the prompt. + +@item @t{%_} +The status of the parser, i.e. the shell constructs (like `@t{if}' and +`@t{for}') that have been started on the command line. If given an integer +number that many strings will be printed; zero or negative or no integer means +print as many as there are. This is most useful in prompts @t{PS2} for +continuation lines and @t{PS4} for debugging with the @t{XTRACE} option; in +the latter case it will also work non-interactively. + +@item @t{%^} +The status of the parser in reverse. This is the same as `@t{%_}' other than +the order of strings. It is often used in @t{RPS2}. + +@item @t{%d} +@itemx @t{%/} +Current working directory. If an integer follows the `@t{%}', +it specifies a number of trailing components of the current working +directory to show; zero means the whole path. A negative integer +specifies leading components, i.e. @t{%-1d} specifies the first component. + +@item @t{%~} +As @t{%d} and @t{%/}, but if the current working directory starts with +@t{$HOME}, that part is replaced by a `@t{~}'. Furthermore, if it has a named +directory as its prefix, that part is replaced by a `@t{~}' followed by +the name of the directory, but only if the result is shorter than +the full path; +@ref{Filename Expansion}. + +@item @t{%e} +Evaluation depth of the current sourced file, shell function, or @t{eval}. +This is incremented or decremented every time the value of @t{%N} is +set or reverted to a previous value, respectively. This is most useful +for debugging as part of @t{$PS4}. + +@item @t{%h} +@itemx @t{%!} +Current history event number. + +@item @t{%i} +The line number currently being executed in the script, sourced file, or +shell function given by @t{%N}. This is most useful for debugging as part +of @t{$PS4}. + +@item @t{%I} +The line number currently being executed in the file @t{%x}. This is +similar to @t{%i}, but the line number is always a line number in the +file where the code was defined, even if the code is a shell function. + +@item @t{%j} +The number of jobs. + +@item @t{%L} +The current value of @t{$SHLVL}. + +@item @t{%N} +The name of the script, sourced file, or shell function that zsh is +currently executing, whichever was started most recently. If there is +none, this is equivalent to the parameter @t{$0}. An integer may follow +the `@t{%}' to specify a number of trailing path components to show; zero +means the full path. A negative integer specifies leading components. + +@item @t{%x} +The name of the file containing the source code currently being +executed. This behaves as @t{%N} except that function and eval command +names are not shown, instead the file where they were defined. + +@item @t{%c} +@itemx @t{%.} +@itemx @t{%C} +Trailing component of the current working directory. +An integer may follow the `@t{%}' to get more than one component. +Unless `@t{%C}' is used, tilde contraction is performed first. These are +deprecated as @t{%c} and @t{%C} are equivalent to @t{%1~} and @t{%1/}, +respectively, while explicit positive integers have the same effect as for +the latter two sequences. + +@end table + +@noindent + +@subsection Date and time +@noindent +@table @asis +@item @t{%D} +The date in @var{yy}@t{-}@var{mm}@t{-}@var{dd} format. + +@item @t{%T} +Current time of day, in 24-hour format. + +@item @t{%t} +@itemx @t{%@@} +Current time of day, in 12-hour, am/pm format. + +@item @t{%*} +Current time of day in 24-hour format, with seconds. + +@item @t{%w} +The date in @var{day}@t{-}@var{dd} format. + +@item @t{%W} +The date in @var{mm}@t{/}@var{dd}@t{/}@var{yy} format. + +@item @t{%D@{}@var{string}@t{@}} +@var{string} is formatted using the @t{strftime} function. +See man page strftime(3) for more details. Various zsh +extensions provide numbers with no leading zero or space +if the number is a single digit: + +@noindent +@table @asis +@item @t{%f} +a day of the month +@item @t{%K} +the hour of the day on the 24-hour clock +@item @t{%L} +the hour of the day on the 12-hour clock +@end table + +@noindent +In addition, if the system supports the POSIX @t{gettimeofday} system +call, @t{%.} provides decimal fractions of a second since the epoch with +leading zeroes. By default three decimal places are provided, but a +number of digits up to 9 may be given following the @t{%}; hence @t{%6.} +outputs microseconds, and @t{%9.} outputs nanoseconds. (The latter +requires a nanosecond-precision @t{clock_gettime}; systems lacking this +will return a value multiplied by the appropriate power of 10.) A typical +example of this is the format `@t{%D@{%H:%M:%S.%.@}}'. + +@noindent +The GNU extension @t{%N} is handled as a synonym for @t{%9.}. + +@noindent +Additionally, the GNU extension that a `@t{-}' between the @t{%} and the +format character causes a leading zero or space to be stripped +is handled directly by the shell for the format characters @t{d}, @t{f}, +@t{H}, @t{k}, @t{l}, @t{m}, @t{M}, @t{S} and @t{y}; any other format +characters are provided to the system's strftime(3) +with any leading `@t{-}' present, so the handling is system dependent. +Further GNU (or other) extensions are also passed to strftime(3) +and may work if the system supports them. + +@end table + +@noindent + +@subsection Visual effects +@noindent +@table @asis +@item @t{%B} (@t{%b}) +Start (stop) boldface mode. + +@item @t{%E} +Clear to end of line. + +@item @t{%U} (@t{%u}) +Start (stop) underline mode. + +@item @t{%S} (@t{%s}) +Start (stop) standout mode. + +@item @t{%F} (@t{%f}) +Start (stop) using a different foreground colour, if supported +by the terminal. The colour may be specified two ways: either +as a numeric argument, as normal, or by a sequence in braces +following the @t{%F}, for example @t{%F@{red@}}. In the latter case +the values allowed are as described for the @t{fg} @t{zle_highlight} +attribute; +@ref{Character Highlighting}. This means that numeric +colours are allowed in the second format also. + +@item @t{%K} (@t{%k}) +Start (stop) using a different bacKground colour. The syntax is +identical to that for @t{%F} and @t{%f}. + +@item @t{%@{}...@t{%@}} +Include a string as a literal escape sequence. +The string within the braces should not change the cursor +position. Brace pairs can nest. + +@noindent +A positive numeric argument between the @t{%} and the @t{@{} is treated as +described for @t{%G} below. + +@item @t{%G} +Within a @t{%@{}...@t{%@}} sequence, include a `glitch': that is, assume +that a single character width will be output. This is useful when +outputting characters that otherwise cannot be correctly handled by the +shell, such as the alternate character set on some terminals. +The characters in question can be included within a @t{%@{}...@t{%@}} +sequence together with the appropriate number of @t{%G} sequences to +indicate the correct width. An integer between the `@t{%}' and `@t{G}' +indicates a character width other than one. Hence @t{%@{}@var{seq}@t{%2G%@}} +outputs @var{seq} and assumes it takes up the width of two standard +characters. + +@noindent +Multiple uses of @t{%G} accumulate in the obvious fashion; the position +of the @t{%G} is unimportant. Negative integers are not handled. + +@noindent +Note that when prompt truncation is in use it is advisable to divide up +output into single characters within each @t{%@{}...@t{%@}} group so that +the correct truncation point can be found. + +@end table + +@noindent + +@section Conditional Substrings in Prompts +@noindent +@table @asis +@item @t{%v} +@vindex psvar, use of +The value of the first element of the @t{psvar} array parameter. Following +the `@t{%}' with an integer gives that element of the array. Negative +integers count from the end of the array. + +@item @t{%(}@var{x}@t{.}@var{true-text}@t{.}@var{false-text}@t{)} +Specifies a ternary expression. The character following the @var{x} is +arbitrary; the same character is used to separate the text for the +`true' result from that for the `false' result. +This separator may not appear in the @var{true-text}, except as part of a +%-escape +sequence. A `@t{)}' may appear in the @var{false-text} as `@t{%)}'. +@var{true-text} +and @var{false-text} may both contain arbitrarily-nested escape +sequences, including further ternary expressions. + +@noindent +The left parenthesis may be preceded or followed by a positive integer @var{n}, +which defaults to zero. A negative integer will be multiplied by -1, except +as noted below for `@t{l}'. +The test character @var{x} may be any of the following: + +@noindent +@table @asis +@item @t{!} +True if the shell is running with privileges. +@item @t{#} +True if the effective uid of the current process is @var{n}. +@item @t{?} +True if the exit status of the last command was @var{n}. +@item @t{_} +True if at least @var{n} shell constructs were started. +@item @t{C} +@itemx @t{/} +True if the current absolute path has at least @var{n} elements +relative to the root directory, hence @t{/} is counted as 0 elements. +@item @t{c} +@itemx @t{.} +@itemx @t{~} +True if the current path, with prefix replacement, has at +least @var{n} elements relative to the root directory, hence @t{/} is +counted as 0 elements. +@item @t{D} +True if the month is equal to @var{n} (January = 0). +@item @t{d} +True if the day of the month is equal to @var{n}. +@item @t{e} +True if the evaluation depth is at least @var{n}. +@item @t{g} +True if the effective gid of the current process is @var{n}. +@item @t{j} +True if the number of jobs is at least @var{n}. +@item @t{L} +True if the @t{SHLVL} parameter is at least @var{n}. +@item @t{l} +True if at least @var{n} characters have already been +printed on the current line. When @var{n} is negative, true if at least +@t{abs}@t{(}@var{n}@t{)} characters remain before the opposite +margin (thus the left margin for @t{RPROMPT}). +@item @t{S} +True if the @t{SECONDS} parameter is at least @var{n}. +@item @t{T} +True if the time in hours is equal to @var{n}. +@item @t{t} +True if the time in minutes is equal to @var{n}. +@item @t{v} +True if the array @t{psvar} has at least @var{n} elements. +@item @t{V} +True if element @var{n} of the array @t{psvar} is set and +non-empty. +@item @t{w} +True if the day of the week is equal to @var{n} (Sunday = 0). +@end table + +@item @t{%<}@var{string}@t{<} +@itemx @t{%>}@var{string}@t{>} +@itemx @t{%[}@var{xstring}@t{]} +Specifies truncation behaviour for the remainder of the prompt string. +The third, deprecated, form is equivalent to `@t{%}@var{xstringx}', +i.e. @var{x} may be `@t{<}' or `@t{>}'. +The @var{string} will be displayed in +place of the truncated portion of any string; note this does not +undergo prompt expansion. + +@noindent +The numeric argument, which in the third form may appear immediately +after the `@t{[}', specifies the maximum permitted length of +the various strings that can be displayed in the prompt. +In the first two forms, this numeric argument may be negative, in which +case the truncation length is determined by subtracting the absolute +value of the numeric argument from the number of character positions +remaining on the current prompt line. If this results in a zero or +negative length, a length of 1 is used. In other words, a negative +argument arranges that after truncation at least @var{n} characters +remain before the right margin (left margin for @t{RPROMPT}). + +@noindent +The forms with `@t{<}' truncate at the left of the string, +and the forms with `@t{>}' truncate at the right of the string. +For example, if the current directory is `@t{/home/pike}', +the prompt `@t{%8<..<%/}' will expand to `@t{..e/pike}'. +In this string, the terminating character (`@t{<}', `@t{>}' or `@t{]}'), +or in fact any character, may be quoted by a preceding `@t{\}'; note +when using @t{print -P}, however, that this must be doubled as the +string is also subject to standard @t{print} processing, in addition +to any backslashes removed by a double quoted string: the worst case +is therefore `@t{print -P "%<\\\\<<..."}'. + +@noindent +If the @var{string} is longer than the specified truncation length, +it will appear in full, completely replacing the truncated string. + +@noindent +The part of the prompt string to be truncated runs to the end of the +string, or to the end of the next enclosing group of the `@t{%(}' +construct, or to the next truncation encountered at the same grouping +level (i.e. truncations inside a `@t{%(}' are separate), which +ever comes first. In particular, a truncation with argument zero +(e.g., `@t{%<<}') marks the end of the range of the string to be +truncated while turning off truncation from there on. For example, the +prompt `@t{%10<...<%~%<<%# }' will print a truncated representation of the +current directory, followed by a `@t{%}' or `@t{#}', followed by a +space. Without the `@t{%<<}', those two characters would be included +in the string to be truncated. Note that `@t{%-0<<}' is not equivalent +to `@t{%<<}' but specifies that the prompt is truncated at the right margin. + +@noindent +Truncation applies only within each individual line of the prompt, as +delimited by embedded newlines (if any). If the total length of any line +of the prompt after truncation is greater than the terminal width, or if +the part to be truncated contains embedded newlines, truncation behavior +is undefined and may change in a future version of the shell. Use +`@t{%-}@var{n}@t{(l.}@var{true-text}@t{.}@var{false-text}@t{)}' to remove parts +of the prompt when the available space is less than @var{n}. + +@end table +@c (avoiding a yodl bug) +@c Yodl file: Zsh/expn.yo +@node Expansion, Parameters, Prompt Expansion, Top + +@chapter Expansion +@noindent + +@cindex expansion +The following types of expansions are performed in the indicated order in +five steps: + +@noindent +@table @asis +@item @emph{History Expansion} +This is performed only in interactive shells. + +@item @emph{Alias Expansion} +Aliases are expanded immediately before the command line is parsed as +explained +in @ref{Aliasing}. + +@item @emph{Process Substitution} +@itemx @emph{Parameter Expansion} +@itemx @emph{Command Substitution} +@itemx @emph{Arithmetic Expansion} +@itemx @emph{Brace Expansion} +These five are performed in left-to-right fashion. On each argument, +any of the five steps that are needed are performed one after the other. +Hence, for example, all the parts of parameter expansion are completed +before command substitution is started. After these expansions, all +unquoted occurrences of the characters `@t{\}',`@t{'}' and `@t{"}' are +removed. + +@item @emph{Filename Expansion} +If the @t{SH_FILE_EXPANSION} option is set, the order of expansion is +modified for compatibility with @cite{sh} and @cite{ksh}. In that case +@emph{filename expansion} is performed immediately after @emph{alias expansion}, +preceding the set of five expansions mentioned above. + +@cindex globbing +@item @emph{Filename Generation} +This expansion, commonly referred to as @cite{globbing}, is always done last. + +@end table + +@noindent +The following sections explain the types of expansion in detail. + +@noindent +@menu +* History Expansion:: +* Process Substitution:: +* Parameter Expansion:: +* Command Substitution:: +* Arithmetic Expansion:: +* Brace Expansion:: +* Filename Expansion:: +* Filename Generation:: +@end menu +@node History Expansion, Process Substitution, , Expansion + +@section History Expansion +@noindent +@cindex history +@cindex history expansion +@cindex expansion, history +History expansion allows you to use words from previous command +lines in the command line you are typing. This simplifies spelling +corrections and the repetition of complicated commands or arguments. + +@noindent +@vindex HISTSIZE, use of +Immediately before execution, each command is saved in the history list, +the size of which is controlled by the @t{HISTSIZE} parameter. The one +most recent command is always retained in any case. Each saved command in +the history list is called a history @emph{event} and is assigned a number, +beginning with 1 (one) when the shell starts up. The history number that +you may see in your prompt (see +@ref{Prompt Expansion}) is the number that is to be assigned to the @emph{next} command. + +@noindent +@menu +* Overview:: +* Event Designators:: +* Word Designators:: +* Modifiers:: +@end menu +@node Overview, Event Designators, , History Expansion + +@subsection Overview +@noindent +@vindex histchars, use of +A history expansion begins with the first character of the @t{histchars} +parameter, which is `@t{!}' by default, and may occur anywhere on the +command line, including inside double quotes (but not inside single quotes +@t{'...'} or C-style quotes @t{$'...'} nor when escaped with a backslash). + +@noindent +The first character is followed by an optional event designator +(@ref{Event Designators}) and then an optional word +designator (@ref{Word Designators}); if neither of these designators is +present, no history expansion occurs. + +@noindent +Input lines containing history expansions are echoed after being expanded, +but before any other expansions take place and before the command is +executed. It is this expanded form that is recorded as the history event +for later references. + +@noindent +History expansions do not nest. + +@noindent +By default, a history reference with no event designator refers to the +same event as any preceding history reference on that command line; if it +is the only history reference in a command, it refers to the previous +command. +@pindex CSH_JUNKIE_HISTORY, use of +However, if the option @t{CSH_JUNKIE_HISTORY} is set, then every history +reference with no event specification @emph{always} refers to the previous +command. + +@noindent +For example, `@t{!}' is the event designator for the previous command, so +`@t{!!:1}' always refers to the first word of the previous command, and +`@t{!!$}' always refers to the last word of the previous command. With +@t{CSH_JUNKIE_HISTORY} set, then `@t{!:1}' and `@t{!$}' function in the +same manner as `@t{!!:1}' and `@t{!!$}', respectively. Conversely, if +@t{CSH_JUNKIE_HISTORY} is unset, then `@t{!:1}' and `@t{!$}' refer to the +first and last words, respectively, of the same event referenced by the +nearest other history reference preceding them on the current command +line, or to the previous command if there is no preceding reference. + +@noindent +The character sequence `@t{^}@var{foo}@t{^}@var{bar}' (where `@t{^}' is +actually the second character of the @t{histchars} parameter) +repeats the last command, replacing the string @var{foo} with @var{bar}. +More precisely, the sequence `@t{^}@var{foo}@t{^}@var{bar}@t{^}' is +synonymous with `@t{!!:s}@t{^}@var{foo}@t{^}@var{bar}@t{^}', hence other +modifiers (see @ref{Modifiers}) may follow the final `@t{^}'. +In particular, `@t{^}@var{foo}@t{^}@var{bar}@t{^:G}' performs a global +substitution. + +@noindent +If the shell encounters the character sequence `@t{!"}' +in the input, the history mechanism is temporarily disabled until +the current list (see +@ref{Shell Grammar}) is fully parsed. The `@t{!"}' is removed from the input, and any +subsequent `@t{!}' characters have no special significance. + +@noindent +@findex fc, use of +A less convenient but more comprehensible form of command history support +is provided by the @t{fc} builtin. +@node Event Designators, Word Designators, Overview, History Expansion + +@subsection Event Designators +@noindent +@cindex history event designators +@cindex event designators, history +An event designator is a reference to a command-line entry in the history +list. In the list below, remember that the initial @t{`!'} in each item +may be changed to another character by setting the @t{histchars} +parameter. + +@noindent +@table @asis +@item @t{!} +Start a history expansion, except when followed by a blank, newline, +`@t{=}' or `@t{(}'. If followed immediately by a word designator +(@ref{Word Designators}), this forms a history reference +with no event designator (@ref{Overview}). + +@item @t{!!} +Refer to the previous command. +By itself, this expansion +repeats the previous command. + +@item @t{!}@var{n} +Refer to command-line @var{n}. + +@item @t{!-}@var{n} +Refer to the current command-line minus @var{n}. + +@item @t{!}@var{str} +Refer to the most recent command starting with @var{str}. + +@item @t{!?}@var{str}[@t{?}] +Refer to the most recent command containing @var{str}. The trailing +`@t{?}' is necessary if this reference is to be followed by a modifier or +followed by any text that is not to be considered part of @var{str}. + +@item @t{!#} +Refer to the current command line typed in so far. The line is +treated as if it were complete up to and including the word before the +one with the `@t{!#}' reference. + +@item @t{!@{}...@t{@}} +Insulate a history reference from adjacent characters (if necessary). + +@end table +@node Word Designators, Modifiers, Event Designators, History Expansion + +@subsection Word Designators +@noindent +@cindex history word designators +@cindex word designators, history +A word designator indicates which word or words of a given command line are +to be included in a history reference. A `@t{:}' usually +separates the event specification from the word designator. +It may be omitted only if the word designator begins with a +`@t{^}', `@t{$}', `@t{*}', `@t{-}' or `@t{%}'. +Word designators include: + +@noindent +@table @asis +@item @t{0} +The first input word (command). +@item @var{n} +The @var{n}th argument. +@item @t{^} +The first argument. That is, @t{1}. +@item @t{$} +The last argument. +@item @t{%} +The word matched by (the most recent) @t{?}@var{str} search. +@item @var{x}@t{-}@var{y} +A range of words; @var{x} defaults to @t{0}. +@item @t{*} +All the arguments, or a null value if there are none. +@item @var{x}@t{*} +Abbreviates `@var{x}@t{-$}'. +@item @var{x}@t{-} +Like `@var{x}@t{*}' but omitting word @t{$}. +@end table + +@noindent +Note that a `@t{%}' word designator works only when used in one of +`@t{!%}', `@t{!:%}' or `@t{!?}@var{str}@t{?:%}', and only when used after a +@t{!?} expansion (possibly in an earlier command). Anything else results +in an error, although the error may not be the most obvious one. +@node Modifiers, , Word Designators, History Expansion + +@subsection Modifiers +@noindent +@cindex modifiers +@cindex colon modifiers +@cindex history modifiers +@cindex globbing modifiers +@cindex parameter modifiers +After the optional word designator, you can add +a sequence of one or more of the following modifiers, +each preceded by a `@t{:}'. These modifiers also work on the result +of @emph{filename generation} and @emph{parameter expansion}, except where +noted. + +@noindent +@table @asis +@item @t{a} +Turn a file name into an absolute path: prepends the current directory, +if necessary; remove `@t{.}' path segments; and remove `@t{..}' path segments +and the segments that immediately precede them. + +@noindent +This transformation is agnostic about what is in the filesystem, i.e. is +on the logical, not the physical directory. It takes place in the same +manner as when changing directories when neither of the options +@t{CHASE_DOTS} or @t{CHASE_LINKS} is set. For example, +`@t{/before/here/../after}' is always transformed to +`@t{/before/after}', regardless of whether `@t{/before/here}' exists or what +kind of object (dir, file, symlink, etc.) it is. + +@item @t{A} +Turn a file name into an absolute path as the `@t{a}' modifier does, and +@emph{then} pass the result through the @t{realpath(3)} library +function to resolve symbolic links. + +@noindent +Note: on systems that do not have a @t{realpath(3)} library +function, symbolic links are not resolved, so on those systems `@t{a}' and +`@t{A}' are equivalent. + +@noindent +Note: @t{foo:A} and @t{realpath(foo)} are different on some inputs. +For @t{realpath(foo)} semantics, see the `@t{P}` modifier. + +@item @t{c} +Resolve a command name into an absolute path by searching the command +path given by the @t{PATH} variable. This does not work for commands +containing directory parts. Note also that this does not usually work as +a glob qualifier unless a file of the same name is found in the +current directory. + +@item @t{e} +Remove all but the part of the filename extension following the `@t{.}'; +see the definition of the filename extension in the description of the +@t{r} modifier below. Note that according to that definition the result +will be empty if the string ends with a `@t{.}'. + +@item @t{h} [ @var{digits} ] +Remove a trailing pathname component, shortening the path by one +directory level: this is the `head' of the pathname. This works like +`@t{dirname}'. If the @t{h} is followed immediately (with no spaces or +other separator) by any number of decimal digits, and the value of the +resulting number is non-zero, that number of leading components is +preserved instead of the final component being removed. In an +absolute path the leading `@t{/}' is the first component, so, +for example, if @t{var=/my/path/to/something}, then @t{$@{var:h3@}} +substitutes @t{/my/path}. Consecutive `/'s are treated the same as +a single `/'. In parameter substitution, digits may only be +used if the expression is in braces, so for example the short form +substitution @t{$var:h2} is treated as @t{$@{var:h@}2}, not as +@t{$@{var:h2@}}. No restriction applies to the use of digits in history +substitution or globbing qualifiers. If more components are requested +than are present, the entire path is substituted (so this does not +trigger a `failed modifier' error in history expansion). + +@item @t{l} +Convert the words to all lowercase. + +@item @t{p} +Print the new command but do not execute it. Only works with history +expansion. + +@item @t{P} +Turn a file name into an absolute path, like @t{realpath(3)}. +The resulting path will be absolute, have neither `@t{.}' nor `@t{..}' components, +and refer to the same directory entry as the input filename. + +@noindent +Unlike @t{realpath(3)}, non-existent trailing components are +permitted and preserved. + +@item @t{q} +Quote the substituted words, escaping further substitutions. Works +with history expansion and parameter expansion, though for parameters +it is only useful if the resulting text is to be re-evaluated such as +by @t{eval}. + +@item @t{Q} +Remove one level of quotes from the substituted words. + +@item @t{r} +Remove a filename extension leaving the root name. Strings with no +filename extension are not altered. A filename +extension is a `@t{.}' followed by any number of characters (including +zero) that are neither `@t{.}' nor `@t{/}' and that continue to the end +of the string. For example, the extension of +`@t{foo.orig.c}' is `@t{.c}', and `@t{dir.c/foo}' has no extension. + +@item @t{s/}@var{l}@t{/}@var{r}[@t{/}] +Substitute @var{r} for @var{l} as described below. +The substitution is done only for the +first string that matches @var{l}. For arrays and for filename +generation, this applies to each word of the expanded text. See +below for further notes on substitutions. + +@noindent +The forms `@t{gs/}@var{l}@t{/}@var{r}' and `@t{s/}@var{l}@t{/}@var{r}@t{/:G}' +perform global substitution, i.e. substitute every occurrence of @var{r} +for @var{l}. Note that the @t{g} or @t{:G} must appear in exactly the +position shown. + +@noindent +See further notes on this form of substitution below. + +@item @t{&} +Repeat the previous @t{s} substitution. Like @t{s}, may be preceded +immediately by a @t{g}. In parameter expansion the @t{&} must appear +inside braces, and in filename generation it must be quoted with a +backslash. + +@item @t{t} [ @var{digits} ] +Remove all leading pathname components, leaving the final component (tail). +This works like `@t{basename}'. Any trailing slashes are first removed. +Decimal digits are handled as described above for (h), but in this +case that number of trailing components is preserved instead of +the default 1; 0 is treated the same as 1. + +@item @t{u} +Convert the words to all uppercase. + +@item @t{x} +Like @t{q}, but break into words at whitespace. Does not work with +parameter expansion. + +@end table + +@noindent +The @t{s/}@var{l}@t{/}@var{r}@t{/} substitution works as follows. By +default the left-hand side of substitutions are not patterns, but +character strings. Any character can be used as the delimiter in place +of `@t{/}'. A backslash quotes the delimiter character. The character +`@t{&}', in the right-hand-side @var{r}, is replaced by the text from the +left-hand-side @var{l}. The `@t{&}' can be quoted with a backslash. A +null @var{l} uses the previous string either from the previous @var{l} or +from the contextual scan string @var{s} from `@t{!?}@var{s}'. You can +omit the rightmost delimiter if a newline immediately follows @var{r}; +the rightmost `@t{?}' in a context scan can similarly be omitted. Note +the same record of the last @var{l} and @var{r} is maintained across all +forms of expansion. + +@noindent +Note that if a `@t{&}' is used within glob qualifiers an extra backslash +is needed as a @t{&} is a special character in this case. + +@noindent +Also note that the order of expansions affects the interpretation of +@var{l} and @var{r}. When used in a history expansion, which occurs before +any other expansions, @var{l} and @var{r} are treated as literal strings +(except as explained for @t{HIST_SUBST_PATTERN} below). When used in +parameter expansion, the replacement of @var{r} into the parameter's value +is done first, and then any additional process, parameter, command, +arithmetic, or brace references are applied, which may evaluate those +substitutions and expansions more than once if @var{l} appears more than +once in the starting value. When used in a glob qualifier, any +substitutions or expansions are performed once at the time the qualifier +is parsed, even before the `@t{:s}' expression itself is divided into +@var{l} and @var{r} sides. + +@noindent +If the option @t{HIST_SUBST_PATTERN} is set, @var{l} is treated as +a pattern of the usual form described in +@ref{Filename Generation}. This can be used in +all the places where modifiers are available; note, however, that +in globbing qualifiers parameter substitution has already taken place, +so parameters in the replacement string should be quoted to ensure +they are replaced at the correct time. +Note also that complicated patterns used in globbing qualifiers may +need the extended glob qualifier notation +@t{(#q:s/}@var{...}@t{/}@var{...}@t{/)} in order for the +shell to recognize the expression as a glob qualifier. Further, +note that bad patterns in the substitution are not subject to +the @t{NO_BAD_PATTERN} option so will cause an error. + +@noindent +When @t{HIST_SUBST_PATTERN} is set, @var{l} may start with a @t{#} +to indicate that the pattern must match at the start of the string +to be substituted, and a @t{%} may appear at the start or after an @t{#} +to indicate that the pattern must match at the end of the string +to be substituted. The @t{%} or @t{#} may be quoted with two +backslashes. + +@noindent +For example, the following piece of filename generation code +with the @t{EXTENDED_GLOB} option: + +@noindent +@example +print -r -- *.c(#q:s/#%(#b)s(*).c/'S$@{match[1]@}.C'/) +@end example + +@noindent +takes the expansion of @t{*.c} and applies the glob qualifiers in the +@t{(#q}@var{...}@t{)} expression, which consists of a substitution +modifier anchored to the start and end of each word (@t{#%}). This +turns on backreferences (@t{(#b)}), so that the parenthesised +subexpression is available in the replacement string as @t{$@{match[1]@}}. +The replacement string is quoted so that the parameter is not substituted +before the start of filename generation. + +@noindent +The following @t{f}, @t{F}, @t{w} and @t{W} modifiers work only with +parameter expansion and filename generation. They are listed here to +provide a single point of reference for all modifiers. + +@noindent +@table @asis +@item @t{f} +Repeats the immediately (without a colon) following modifier until the +resulting word doesn't change any more. + +@item @t{F:}@var{expr}@t{:} +Like @t{f}, but repeats only @var{n} times if the expression +@var{expr} evaluates to @var{n}. Any character can be used instead of +the `@t{:}'; if `@t{(}', `@t{[}', or `@t{@{}' +is used as the opening delimiter, +the closing delimiter should be '@t{)}', `@t{]}', or `@t{@}}', +respectively. + +@item @t{w} +Makes the immediately following modifier work on each word in the +string. + +@item @t{W:}@var{sep}@t{:} +Like @t{w} but words are considered to be the parts of the string +that are separated by @var{sep}. Any character can be used instead of +the `@t{:}'; opening parentheses are handled specially, see above. + +@end table +@node Process Substitution, Parameter Expansion, History Expansion, Expansion + +@section Process Substitution +@noindent +@cindex process substitution +@cindex substitution, process +Each part of a command argument that takes the form +`@t{<(}@var{list}@t{)}', +`@t{>(}@var{list}@t{)}' or +`@t{=(}@var{list}@t{)}' +is subject to process substitution. The expression may be preceded +or followed by other strings except that, to prevent clashes with +commonly occurring strings and patterns, the last +form must occur at the start of a command argument, and the forms +are only expanded when first parsing command or assignment arguments. +Process substitutions may be used following redirection operators; in this +case, the substitution must appear with no trailing string. + +@noindent +Note that `@t{<<(}@var{list}@t{)}' is not a special syntax; it +is equivalent to `@t{< <(}@var{list}@t{)}', redirecting +standard input from the result of process substitution. Hence all +the following documentation applies. The second form (with the space) +is recommended for clarity. + +@noindent +In the case of the @t{<} or @t{>} forms, the shell runs the commands in +@var{list} as a subprocess of the job executing the shell command line. +If the system supports the @t{/dev/fd} +mechanism, the command argument is the name of the device file +corresponding to a file descriptor; otherwise, if the system supports named +pipes (FIFOs), the command argument will be a named pipe. If the form with +@t{>} is selected then writing on this special file will provide input for +@var{list}. If @t{<} is used, then the file passed as an argument will +be connected to the output of the @var{list} process. For example, + +@noindent +@example +@t{paste <(cut -f1} @var{file1}@t{) <(cut -f3} @var{file2}@t{) | +tee >(}@var{process1}@t{) >(}@var{process2}@t{) >/dev/null} +@end example + +@noindent +cuts fields 1 and 3 from the files @var{file1} and @var{file2} respectively, +pastes the results together, and sends it to the processes +@var{process1} and @var{process2}. + +@noindent +If @t{=(}@var{...}@t{)} is used instead of +@t{<(}@var{...}@t{)}, +then the file passed as an argument will be the name +of a temporary file containing the output of the @var{list} +process. This may be used instead of the @t{<} +form for a program that expects to lseek (see man page lseek(2)) +on the input file. + +@noindent +There is an optimisation for substitutions of the form +@t{=(<<<}@var{arg}@t{)}, where @var{arg} is a single-word argument +to the here-string redirection @t{<<<}. This form produces a file name +containing the value of @var{arg} after any substitutions have been +performed. This is handled entirely within the current shell. This is +effectively the reverse of the special form @t{$(<}@var{arg}@t{)} +which treats @var{arg} as a file name and replaces it with the file's +contents. + +@noindent +The @t{=} form is useful as both the @t{/dev/fd} and the named pipe +implementation of @t{<(}@var{...}@t{)} have drawbacks. In +the former case, some programmes may automatically close the file +descriptor in question before examining the file on the command line, +particularly if this is necessary for security reasons such as when the +programme is running setuid. In the second case, if the +programme does not actually open the file, the subshell attempting to read +from or write to the pipe will (in a typical implementation, different +operating systems may have different behaviour) block for ever and have to +be killed explicitly. In both cases, the shell actually supplies the +information using a pipe, so that programmes that expect to lseek +(see man page lseek(2)) on the file will not work. + +@noindent +Also note that the previous example can be more compactly and +efficiently written (provided the @t{MULTIOS} option is set) as: + +@noindent +@example +@t{paste <(cut -f1} @var{file1}@t{) <(cut -f3} @var{file2}@t{)} @t{> >(}@var{process1}@t{) > >(}@var{process2}@t{)} +@end example + +@noindent +The shell uses pipes instead of FIFOs to implement the latter +two process substitutions in the above example. + +@noindent +There is an additional problem with @t{>(}@var{process}@t{)}; when +this is attached to an external command, the parent shell does not wait +for @var{process} to finish and hence an immediately following command +cannot rely on the results being complete. The problem and solution are +the same as described in the section @emph{MULTIOS} in +@ref{Redirection}. Hence in a simplified +version of the example above: + +@noindent +@example +@t{paste <(cut -f1} @var{file1}@t{) <(cut -f3} @var{file2}@t{)} @t{> >(}@var{process}@t{)} +@end example + +@noindent +(note that no @t{MULTIOS} are involved), @var{process} will be run +asynchronously as far as the parent shell is concerned. The workaround is: + +@noindent +@example +@t{@{ paste <(cut -f1} @var{file1}@t{) <(cut -f3} @var{file2}@t{) @}} @t{> >(}@var{process}@t{)} +@end example + +@noindent +The extra processes here are +spawned from the parent shell which will wait for their completion. + +@noindent +Another problem arises any time a job with a substitution that requires +a temporary file is disowned by the shell, including the case where +`@t{&!}' or `@t{&|}' appears at the end of a command containing a +substitution. In that case the temporary file will not be cleaned up as +the shell no longer has any memory of the job. A workaround is to use +a subshell, for example, + +@noindent +@example +(mycmd =(myoutput)) &! +@end example + +@noindent +as the forked subshell will wait for the command to finish then remove +the temporary file. + +@noindent +A general workaround to ensure a process substitution endures for +an appropriate length of time is to pass it as a parameter to +an anonymous shell function (a piece of shell code that is run +immediately with function scope). For example, this code: + +@noindent +@example +() @{ + print File $1: + cat $1 +@} =(print This be the verse) +@end example + +@noindent +outputs something resembling the following + +@noindent +@example +File /tmp/zsh6nU0kS: +This be the verse +@end example + +@noindent +The temporary file created by the process substitution will be deleted +when the function exits. + +@noindent +@node Parameter Expansion, Command Substitution, Process Substitution, Expansion + +@section Parameter Expansion +@noindent +@cindex parameter expansion +@cindex expansion, parameter +The character `@t{$}' is used to introduce parameter expansions. +See +@ref{Parameters} +for a description of parameters, including arrays, associative arrays, +and subscript notation to access individual array elements. + +@noindent +Note in particular the fact that words of unquoted parameters are not +automatically split on whitespace unless the option @t{SH_WORD_SPLIT} is +set; see references to this option below for more details. This is an +important difference from other shells. However, as in other shells, +null words are elided from unquoted parameters' expansions. + +@noindent +With default options, after the assignments: + +@noindent +@example +array=("first word" "" "third word") +scalar="only word" +@end example + +@noindent +then @t{$array} substitutes two words, `@t{first word}' and `@t{third +word}', and @t{$scalar} substitutes a single word `@t{only word}'. Note +that second element of @t{array} was elided. Scalar parameters can +be elided too if their value is null (empty). To avoid elision, use quoting as +follows: @t{"$scalar"} for scalars and @t{"$@{array[@@]@}"} or @t{"$@{(@@)array@}"} +for arrays. (The last two forms are equivalent.) + +@noindent +Parameter expansions can involve @emph{flags}, as in `@t{$@{(@@kv)aliases@}}', +and other operators, such as `@t{$@{PREFIX:-"/usr/local"@}}'. Parameter +expansions can also be nested. These topics will be introduced below. +The full rules are complicated and are noted at the end. + +@noindent +In the expansions discussed below that require a pattern, the form of +the pattern is the same as that used for filename generation; +see @ref{Filename Generation}. Note that these patterns, along with +the replacement text of any substitutions, are themselves subject to +parameter expansion, command substitution, and arithmetic expansion. +In addition to the following operations, the colon modifiers described in +@ref{Modifiers} in @ref{History Expansion} can be +applied: for example, @t{$@{i:s/foo/bar/@}} performs string +substitution on the expansion of parameter @t{$i}. + +@noindent +In the following descriptions, `@var{word}' refers to a single word +substituted on the command line, not necessarily a space delimited word. + +@noindent +@table @asis +@item @t{$@{}@var{name}@t{@}} +The value, if any, of the parameter @var{name} is substituted. +The braces are required if the expansion is to be followed by +a letter, digit, or underscore that is not to be interpreted +as part of @var{name}. In addition, more complicated forms of substitution +usually require the braces to be present; exceptions, which only apply if +the option @t{KSH_ARRAYS} is not set, are a single subscript or any colon +modifiers appearing after the name, or any of the characters `@t{^}', +`@t{=}', `@t{~}', `@t{#}' or `@t{+}' appearing before the name, all of +which work with or without braces. + +@noindent +If @var{name} is an array parameter, and the @t{KSH_ARRAYS} option is not +set, then the value of each +element of @var{name} is substituted, one element per word. Otherwise, the +expansion results in one word only; with @t{KSH_ARRAYS}, this is the first +element of an array. No field splitting is done on the result unless the +@t{SH_WORD_SPLIT} option is set. +See also the flags @t{=} and @t{s:}@var{string}@t{:}. + +@item @t{$@{+}@var{name}@t{@}} +If @var{name} is the name of a set parameter `@t{1}' is substituted, +otherwise `@t{0}' is substituted. + +@item @t{$@{}@var{name}@t{-}@var{word}@t{@}} +@itemx @t{$@{}@var{name}@t{:-}@var{word}@t{@}} +If @var{name} is set, or in the second form is non-null, then substitute +its value; otherwise substitute @var{word}. In the second form @var{name} +may be omitted, in which case @var{word} is always substituted. + +@item @t{$@{}@var{name}@t{+}@var{word}@t{@}} +@itemx @t{$@{}@var{name}@t{:+}@var{word}@t{@}} +If @var{name} is set, or in the second form is non-null, then substitute +@var{word}; otherwise substitute nothing. + +@item @t{$@{}@var{name}@t{=}@var{word}@t{@}} +@itemx @t{$@{}@var{name}@t{:=}@var{word}@t{@}} +@itemx @t{$@{}@var{name}@t{::=}@var{word}@t{@}} +In the first form, if @var{name} is unset then set it to @var{word}; in the +second form, if @var{name} is unset or null then set it to @var{word}; and +in the third form, unconditionally set @var{name} to @var{word}. In all +forms, the value of the parameter is then substituted. + +@item @t{$@{}@var{name}@t{?}@var{word}@t{@}} +@itemx @t{$@{}@var{name}@t{:?}@var{word}@t{@}} +In the first form, if @var{name} is set, or in the second form if @var{name} +is both set and non-null, then substitute its value; otherwise, print +@var{word} and exit from the shell. Interactive shells instead return to +the prompt. If @var{word} is omitted, then a standard message is printed. + +@end table + +@noindent +In any of the above expressions that test a variable and substitute an +alternate @var{word}, note that you can use standard shell quoting in the +@var{word} value to selectively override the splitting done by the +@t{SH_WORD_SPLIT} option and the @t{=} flag, but not splitting by the +@t{s:}@var{string}@t{:} flag. + +@noindent +In the following expressions, when @var{name} is an array and +the substitution is not quoted, or if the `@t{(@@)}' flag or the +@var{name}@t{[@@]} syntax is used, matching and replacement is +performed on each array element separately. + +@noindent +@table @asis +@item @t{$@{}@var{name}@t{#}@var{pattern}@t{@}} +@itemx @t{$@{}@var{name}@t{##}@var{pattern}@t{@}} +If the @var{pattern} matches the beginning of the value of +@var{name}, then substitute the value of @var{name} with +the matched portion deleted; otherwise, just +substitute the value of @var{name}. In the first +form, the smallest matching pattern is preferred; +in the second form, the largest matching pattern is +preferred. + +@item @t{$@{}@var{name}@t{%}@var{pattern}@t{@}} +@itemx @t{$@{}@var{name}@t{%%}@var{pattern}@t{@}} +If the @var{pattern} matches the end of the value of +@var{name}, then substitute the value of @var{name} with +the matched portion deleted; otherwise, just +substitute the value of @var{name}. In the first +form, the smallest matching pattern is preferred; +in the second form, the largest matching pattern is +preferred. + +@item @t{$@{}@var{name}@t{:#}@var{pattern}@t{@}} +If the @var{pattern} matches the value of @var{name}, then substitute +the empty string; otherwise, just substitute the value of @var{name}. +If @var{name} is an array +the matching array elements are removed (use the `@t{(M)}' flag to +remove the non-matched elements). + +@item @t{$@{}@var{name}@t{:|}@var{arrayname}@t{@}} +If @var{arrayname} is the name (N.B., not contents) of an array +variable, then any elements contained in @var{arrayname} are removed +from the substitution of @var{name}. If the substitution is scalar, +either because @var{name} is a scalar variable or the expression is +quoted, the elements of @var{arrayname} are instead tested against the +entire expression. + +@item @t{$@{}@var{name}@t{:*}@var{arrayname}@t{@}} +Similar to the preceding substitution, but in the opposite sense, +so that entries present in both the original substitution and as +elements of @var{arrayname} are retained and others removed. + +@item @t{$@{}@var{name}@t{:^}@var{arrayname}@t{@}} +@itemx @t{$@{}@var{name}@t{:^^}@var{arrayname}@t{@}} +Zips two arrays, such that the output array is twice as long as the +shortest (longest for `@t{:^^}') of @t{name} and @t{arrayname}, with +the elements alternatingly being picked from them. For `@t{:^}', if one +of the input arrays is longer, the output will stop when the end of the +shorter array is reached. Thus, + +@noindent +@example +a=(1 2 3 4); b=(a b); print $@{a:^b@} +@end example + +@noindent +will output `@t{1 a 2 b}'. For `@t{:^^}', then the input is repeated +until all of the longer array has been used up and the above will output +`@t{1 a 2 b 3 a 4 b}'. + +@noindent +Either or both inputs may be a scalar, they will be treated as an array +of length 1 with the scalar as the only element. If either array is empty, +the other array is output with no extra elements inserted. + +@noindent +Currently the following code will output `@t{a b}' and `@t{1}' as two separate +elements, which can be unexpected. The second print provides a workaround which +should continue to work if this is changed. + +@noindent +@example +a=(a b); b=(1 2); print -l "$@{a:^b@}"; print -l "$@{$@{a:^b@}@}" +@end example + +@item @t{$@{}@var{name}@t{:}@var{offset}@t{@}} +@itemx @t{$@{}@var{name}@t{:}@var{offset}@t{:}@var{length}@t{@}} +This syntax gives effects similar to parameter subscripting +in the form @t{$}@var{name}@t{[}@var{start}@t{,}@var{end}@t{]}, but is +compatible with other shells; note that both @var{offset} and @var{length} +are interpreted differently from the components of a subscript. + +@noindent +If @var{offset} is non-negative, then if the variable @var{name} is a +scalar substitute the contents starting @var{offset} characters from the +first character of the string, and if @var{name} is an array substitute +elements starting @var{offset} elements from the first element. If +@var{length} is given, substitute that many characters or elements, +otherwise the entire rest of the scalar or array. + +@noindent +A positive @var{offset} is always treated as the offset of a character or +element in @var{name} from the first character or element of the array +(this is different from native zsh subscript notation). Hence 0 +refers to the first character or element regardless of the setting of +the option @t{KSH_ARRAYS}. + +@noindent +A negative offset counts backwards from the end of the scalar or array, +so that -1 corresponds to the last character or element, and so on. + +@noindent +When positive, @var{length} counts from the @var{offset} position +toward the end of the scalar or array. When negative, @var{length} +counts back from the end. If this results in a position smaller +than @var{offset}, a diagnostic is printed and nothing is substituted. + +@noindent +The option @t{MULTIBYTE} is obeyed, i.e. the offset and length +count multibyte characters where appropriate. + +@noindent +@var{offset} and @var{length} undergo the same set of shell substitutions +as for scalar assignment; in addition, they are then subject to arithmetic +evaluation. Hence, for example + +@noindent +@example +print $@{foo:3@} +print $@{foo: 1 + 2@} +print $@{foo:$(( 1 + 2))@} +print $@{foo:$(echo 1 + 2)@} +@end example + +@noindent +all have the same effect, extracting the string starting at the fourth +character of @t{$foo} if the substitution would otherwise return a scalar, +or the array starting at the fourth element if @t{$foo} would return an +array. Note that with the option @t{KSH_ARRAYS} @t{$foo} always returns +a scalar (regardless of the use of the offset syntax) and a form +such as @t{$@{foo[*]:3@}} is required to extract elements of an array named +@t{foo}. + +@noindent +If @var{offset} is negative, the @t{-} may not appear immediately +after the @t{:} as this indicates the +@t{$@{}@var{name}@t{:-}@var{word}@t{@}} form of substitution. Instead, a space +may be inserted before the @t{-}. Furthermore, neither @var{offset} nor +@var{length} may begin with an alphabetic character or @t{&} as these are +used to indicate history-style modifiers. To substitute a value from a +variable, the recommended approach is to precede it with a @t{$} as this +signifies the intention (parameter substitution can easily be rendered +unreadable); however, as arithmetic substitution is performed, the +expression @t{$@{var: offs@}} does work, retrieving the offset from +@t{$offs}. + +@noindent +For further compatibility with other shells there is a special case +for array offset 0. This usually accesses the +first element of the array. However, if the substitution refers to the +positional parameter array, e.g. @t{$@@} or @t{$*}, then offset 0 +instead refers to @t{$0}, offset 1 refers to @t{$1}, and so on. In +other words, the positional parameter array is effectively extended by +prepending @t{$0}. Hence @t{$@{*:0:1@}} substitutes @t{$0} and +@t{$@{*:1:1@}} substitutes @t{$1}. + +@item @t{$@{}@var{name}@t{/}@var{pattern}@t{/}@var{repl}@t{@}} +@itemx @t{$@{}@var{name}@t{//}@var{pattern}@t{/}@var{repl}@t{@}} +@itemx @t{$@{}@var{name}@t{:/}@var{pattern}@t{/}@var{repl}@t{@}} +Replace the longest possible match of @var{pattern} in the expansion of +parameter @var{name} by string @var{repl}. The first form +replaces just the first occurrence, the second form all occurrences, +and the third form replaces only if @var{pattern} matches the entire string. +Both @var{pattern} and @var{repl} are subject to double-quoted substitution, +so that expressions like @t{$@{name/$opat/$npat@}} will work, but obey the +usual rule that pattern characters in @t{$opat} are not treated specially +unless either the option @t{GLOB_SUBST} is set, or @t{$opat} is instead +substituted as @t{$@{~opat@}}. + +@noindent +The @var{pattern} may begin with a `@t{#}', in which case the +@var{pattern} must match at the start of the string, or `@t{%}', in +which case it must match at the end of the string, or `@t{#%}' in which +case the @var{pattern} must match the entire string. The @var{repl} may +be an empty string, in which case the final `@t{/}' may also be omitted. +To quote the final `@t{/}' in other cases it should be preceded by a +single backslash; this is not necessary if the +`@t{/}' occurs inside a substituted parameter. Note also that the `@t{#}', +`@t{%}' and `@t{#%} are not active if they occur inside a substituted +parameter, even at the start. + +@noindent +If, after quoting rules apply, @t{$@{}@var{name}@t{@}} expands to an array, +the replacements act on each element individually. Note also the +effect of the @t{I} and @t{S} parameter expansion flags below; however, +the flags @t{M}, @t{R}, @t{B}, @t{E} and @t{N} are not useful. + +@noindent +For example, + +@noindent +@example +foo="twinkle twinkle little star" sub="t*e" rep="spy" +print $@{foo//$@{~sub@}/$rep@} +print $@{(S)foo//$@{~sub@}/$rep@} +@end example + +@noindent +Here, the `@t{~}' ensures that the text of @t{$sub} is treated as a +pattern rather than a plain string. In the first case, the longest +match for @t{t*e} is substituted and the result is `@t{spy star}', +while in the second case, the shortest matches are taken and the +result is `@t{spy spy lispy star}'. + +@item @t{$@{#}@var{spec}@t{@}} +If @var{spec} is one of the above substitutions, substitute +the length in characters of the result instead of +the result itself. If @var{spec} is an array expression, +substitute the number of elements of the result. +This has the side-effect that joining is skipped even in quoted +forms, which may affect other sub-expressions in @var{spec}. +Note that `@t{^}', `@t{=}', and `@t{~}', below, must appear +to the left of `@t{#}' when these forms are combined. + +@noindent +If the option @t{POSIX_IDENTIFIERS} is not set, and @var{spec} is a +simple name, then the braces are optional; this is true even +for special parameters so e.g. @t{$#-} and @t{$#*} take the length +of the string @t{$-} and the array @t{$*} respectively. If +@t{POSIX_IDENTIFIERS} is set, then braces are required for +the @t{#} to be treated in this fashion. + +@item @t{$@{^}@var{spec}@t{@}} +@pindex RC_EXPAND_PARAM, toggle +@cindex array expansion style, rc +@cindex rc, array expansion style +Turn on the @t{RC_EXPAND_PARAM} option for the +evaluation of @var{spec}; if the `@t{^}' is doubled, turn it off. +When this option is set, array expansions of the form +@var{foo}@t{$@{}@var{xx}@t{@}}@var{bar}, +where the parameter @var{xx} +is set to @t{(}@var{a b c}@t{)}, are substituted with +`@var{fooabar foobbar foocbar}' instead of the default +`@var{fooa b cbar}'. Note that an empty array will therefore cause +all arguments to be removed. + +@noindent +Internally, each such expansion is converted into the +equivalent list for brace expansion. E.g., @t{$@{^var@}} becomes +@t{@{$var[1],$var[2],}...@t{@}}, and is processed as described in +@ref{Brace Expansion} below: note, however, the expansion +happens immediately, with any explicit brace expansion +happening later. If word splitting is also in effect the +@t{$var[}@var{N}@t{]} may themselves be split into different list +elements. + +@item @t{$@{=}@var{spec}@t{@}} +@pindex SH_WORD_SPLIT, toggle +@cindex field splitting, sh style, parameter +@cindex sh, field splitting style, parameter +Perform word splitting using the rules for @t{SH_WORD_SPLIT} during the +evaluation of @var{spec}, but regardless of whether the parameter appears in +double quotes; if the `@t{=}' is doubled, turn it off. +@vindex IFS, use of +This forces parameter expansions to be split into +separate words before substitution, using @t{IFS} as a delimiter. +This is done by default in most other shells. + +@noindent +Note that splitting is applied to @var{word} in the assignment forms +of @var{spec} @emph{before} the assignment to @var{name} is performed. +This affects the result of array assignments with the @t{A} flag. + +@item @t{$@{~}@var{spec}@t{@}} +@pindex GLOB_SUBST, toggle +Turn on the @t{GLOB_SUBST} option for the evaluation of +@var{spec}; if the `@t{~}' is doubled, turn it off. When this option is +set, the string resulting from the expansion will be interpreted as a +pattern anywhere that is possible, such as in filename expansion and +filename generation and pattern-matching contexts like the right +hand side of the `@t{=}' and `@t{!=}' operators in conditions. + +@noindent +In nested substitutions, note that the effect of the @t{~} applies to the +result of the current level of substitution. A surrounding pattern +operation on the result may cancel it. Hence, for example, if the +parameter @t{foo} is set to @t{*}, @t{$@{~foo//\*/*.c@}} is substituted by +the pattern @t{*.c}, which may be expanded by filename generation, but +@t{$@{$@{~foo@}//\*/*.c@}} substitutes to the string @t{*.c}, which will not +be further expanded. + +@end table + +@noindent +If a @t{$@{}...@t{@}} type parameter expression or a +@t{$(}...@t{)} type command substitution is used in place of +@var{name} above, it is expanded first and the result is used as if +it were the value of @var{name}. Thus it is +possible to perform nested operations: @t{$@{$@{foo#head@}%tail@}} +substitutes the value of @t{$foo} with both `@t{head}' and `@t{tail}' +deleted. The form with @t{$(}...@t{)} is often useful in +combination with the flags described next; see the examples below. +Each @var{name} or nested @t{$@{}...@t{@}} in a parameter expansion may +also be followed by a subscript expression as described in +@ref{Array Parameters}. + +@noindent +Note that double quotes may appear around nested expressions, in which +case only the part inside is treated as quoted; for example, +@t{$@{(f)"$(foo)"@}} quotes the result of @t{$(foo)}, but the flag `@t{(f)}' +(see below) is applied using the rules for unquoted expansions. Note +further that quotes are themselves nested in this context; for example, in +@t{"$@{(@@f)"$(foo)"@}"}, there are two sets of quotes, one surrounding the +whole expression, the other (redundant) surrounding the @t{$(foo)} as +before. + +@noindent + +@subsection Parameter Expansion Flags +@noindent +@cindex parameter expansion flags +@cindex flags, parameter expansion +@cindex substitution, parameter, flags +If the opening brace is directly followed by an opening parenthesis, +the string up to the matching closing parenthesis will be taken as a +list of flags. In cases where repeating a flag is meaningful, the +repetitions need not be consecutive; for example, `(@t{q%q%q})' +means the same thing as the more readable `(@t{%%qqq})'. The +following flags are supported: + +@noindent +@table @asis +@item @t{#} +Evaluate the resulting words as numeric expressions and output the +characters corresponding to the resulting integer. Note that this form is +entirely distinct from use of the @t{#} without parentheses. + +@noindent +If the @t{MULTIBYTE} option is set and the number is greater than 127 +(i.e. not an ASCII character) it is treated as a Unicode character. + +@item @t{%} +Expand all @t{%} escapes in the resulting words in the same way as in +prompts (see +@ref{Prompt Expansion}). If this flag is given twice, +full prompt expansion is done on the resulting words, depending on the +setting of the @t{PROMPT_PERCENT}, @t{PROMPT_SUBST} and @t{PROMPT_BANG} +options. + +@item @t{@@} +In double quotes, array elements are put into separate words. +E.g., `@t{"$@{(@@)foo@}"}' is equivalent to `@t{"$@{foo[@@]@}"}' and +`@t{"$@{(@@)foo[1,2]@}"}' is the same as `@t{"$foo[1]" "$foo[2]"}'. +This is distinct from @emph{field splitting} by the @t{f}, @t{s} +or @t{z} flags, which still applies within each array element. + +@item @t{A} +Convert the substitution into an array expression, even if it otherwise +would be scalar. This has lower precedence than subscripting, so one +level of nested expansion is required in order that subscripts apply +to array elements. Thus @t{$@{$@{(A}@t{)}@var{name}@t{@}[1]@}} +yields the full value of @var{name} when @var{name} is scalar. + +@noindent +This assigns an array parameter with `@t{$@{}...@t{=}...@t{@}}', +`@t{$@{}...@t{:=}...@t{@}}' or `@t{$@{}...@t{::=}...@t{@}}'. +If this flag is repeated (as in `@t{AA}'), assigns an associative +array parameter. Assignment is made before sorting or padding; +if field splitting is active, the @var{word} part is split before +assignment. The @var{name} part may be a subscripted range for +ordinary arrays; when assigning an associative array, the @var{word} +part @emph{must} be converted to an array, for example by using +`@t{$@{(AA)=}@var{name}@t{=}...@t{@}}' to activate field splitting. + +@noindent +Surrounding context such as additional nesting or use of the value +in a scalar assignment may cause the array to be joined back into +a single string again. + +@item @t{a} +Sort in array index order; when combined with `@t{O}' sort in reverse +array index order. Note that `@t{a}' is therefore equivalent to the +default but `@t{Oa}' is useful for obtaining an array's elements in reverse +order. + +@item @t{b} +Quote with backslashes only characters that are special to pattern +matching. This is useful when the contents of the variable are to be +tested using @t{GLOB_SUBST}, including the @t{$@{~}@var{...}@t{@}} switch. + +@noindent +Quoting using one of the @t{q} family of flags does not work +for this purpose since quotes are not stripped from non-pattern +characters by @t{GLOB_SUBST}. In other words, + +@noindent +@example +pattern=$@{(q)str@} +[[ $str = $@{~pattern@} ]] +@end example + +@noindent +works if @t{$str} is `@t{a*b}' but not if it is `@t{a b}', whereas + +@noindent +@example +pattern=$@{(b)str@} +[[ $str = $@{~pattern@} ]] +@end example + +@noindent +is always true for any possible value of @t{$str}. + +@item @t{c} +With @t{$@{#}@var{name}@t{@}}, count the total number of characters in an array, +as if the elements were concatenated with spaces between them. This is not +a true join of the array, so other expressions used with this flag may have +an effect on the elements of the array before it is counted. + +@item @t{C} +Capitalize the resulting words. `Words' in this case refers to sequences +of alphanumeric characters separated by non-alphanumerics, @emph{not} to words +that result from field splitting. + +@item @t{D} +Assume the string or array elements contain directories and attempt +to substitute the leading part of these by names. The remainder of +the path (the whole of it if the leading part was not substituted) +is then quoted so that the whole string can be used as a shell +argument. This is the reverse of `@t{~}' substitution: see +@ref{Filename Expansion}. + +@item @t{e} +Perform single word shell expansions, namely @emph{parameter expansion}, +@emph{command substitution} and @emph{arithmetic expansion}, on the +result. Such expansions can be nested but too deep recursion may have +unpredictable effects. + +@item @t{f} +Split the result of the expansion at newlines. This is a shorthand +for `@t{ps:\n:}'. + +@item @t{F} +Join the words of arrays together using newline as a separator. +This is a shorthand for `@t{pj:\n:}'. + +@item @t{g:}@var{opts}@t{:} +Process escape sequences like the echo builtin when no options are given +(@t{g::}). With the @t{o} option, octal escapes don't take a leading +zero. With the @t{c} option, sequences like `@t{^X}' are also processed. +With the @t{e} option, processes `@t{\M-t}' and similar sequences like the +print builtin. With both of the @t{o} and @t{e} options, behaves like the +print builtin except that in none of these modes is `@t{\c}' interpreted. + +@item @t{i} +Sort case-insensitively. May be combined with `@t{n}' or `@t{O}'. + +@item @t{k} +If @var{name} refers to an associative array, substitute the @emph{keys} +(element names) rather than the values of the elements. Used with +subscripts (including ordinary arrays), force indices or keys to be +substituted even if the subscript form refers to values. However, +this flag may not be combined with subscript ranges. With the +@t{KSH_ARRAYS} option a subscript `@t{[*]}' or `@t{[@@]}' is needed +to operate on the whole array, as usual. + +@item @t{L} +Convert all letters in the result to lower case. + +@item @t{n} +Sort decimal integers numerically; if the first differing +characters of two test strings are not digits, sorting +is lexical. Integers with more initial zeroes +are sorted before those with fewer or none. Hence the array `@t{foo1 foo02 +foo2 foo3 foo20 foo23}' is sorted into the order shown. +May be combined with `@t{i}' or `@t{O}'. + +@item @t{o} +Sort the resulting words in ascending order; if this appears on its +own the sorting is lexical and case-sensitive (unless the locale +renders it case-insensitive). Sorting in ascending order is the +default for other forms of sorting, so this is ignored if combined +with `@t{a}', `@t{i}' or `@t{n}'. + +@item @t{O} +Sort the resulting words in descending order; `@t{O}' without `@t{a}', +`@t{i}' or `@t{n}' sorts in reverse lexical order. May be combined +with `@t{a}', `@t{i}' or `@t{n}' to reverse the order of sorting. + +@item @t{P} +This forces the value of the parameter @var{name} to be interpreted as a +further parameter name, whose value will be used where appropriate. +Note that flags set with one of the @t{typeset} family of commands +(in particular case transformations) are not applied to the value of +@var{name} used in this fashion. + +@noindent +If used with a nested parameter or command substitution, the result of that +will be taken as a parameter name in the same way. For example, if you +have `@t{foo=bar}' and `@t{bar=baz}', the strings @t{$@{(P)foo@}}, +@t{$@{(P)$@{foo@}@}}, and @t{$@{(P)$(echo bar)@}} will be expanded to +`@t{baz}'. + +@noindent +Likewise, if the reference is itself nested, the expression with the +flag is treated as if it were directly replaced by the parameter name. +It is an error if this nested substitution produces an array with more +than one word. For example, if `@t{name=assoc}' where the parameter +@t{assoc} is an associative array, then +`@t{$@{$@{(P)name@}[elt]@}}' refers to the element of the associative +subscripted `@t{elt}'. + +@item @t{q} +Quote characters that are special to the shell in the resulting words with +backslashes; unprintable or invalid characters are quoted using the +@t{$'\}@var{NNN}@t{'} form, with separate quotes for each octet. + +@noindent +If this flag is given twice, the resulting words are quoted in single +quotes and if it is given three times, the words are quoted in double +quotes; in these forms no special handling of unprintable or invalid +characters is attempted. If the flag is given four times, the words are +quoted in single quotes preceded by a @t{$}. Note that in all three of +these forms quoting is done unconditionally, even if this does not change +the way the resulting string would be interpreted by the shell. + +@noindent +If a @t{q-} is given (only a single @t{q} may appear), a minimal +form of single quoting is used that only quotes the string if needed to +protect special characters. Typically this form gives the most readable +output. + +@noindent +If a @t{q+} is given, an extended form of minimal quoting is used that +causes unprintable characters to be rendered using @t{$'}@var{...}@t{'}. +This quoting is similar to that used by the output of values by the +@t{typeset} family of commands. + +@item @t{Q} +Remove one level of quotes from the resulting words. + +@item @t{t} +Use a string describing the type of the parameter where the value +of the parameter would usually appear. This string consists of keywords +separated by hyphens (`@t{-}'). The first keyword in the string describes +the main type, it can be one of `@t{scalar}', `@t{array}', `@t{integer}', +`@t{float}' or `@t{association}'. The other keywords describe the type in +more detail: + +@noindent +@table @asis +@item @t{local} +for local parameters + +@item @t{left} +for left justified parameters + +@item @t{right_blanks} +for right justified parameters with leading blanks + +@item @t{right_zeros} +for right justified parameters with leading zeros + +@item @t{lower} +for parameters whose value is converted to all lower case when it is +expanded + +@item @t{upper} +for parameters whose value is converted to all upper case when it is +expanded + +@item @t{readonly} +for readonly parameters + +@item @t{tag} +for tagged parameters + +@item @t{export} +for exported parameters + +@item @t{unique} +for arrays which keep only the first occurrence of duplicated values + +@item @t{hide} +for parameters with the `hide' flag + +@item @t{hideval} +for parameters with the `hideval' flag + +@item @t{special} +for special parameters defined by the shell + +@end table + +@item @t{u} +Expand only the first occurrence of each unique word. + +@item @t{U} +Convert all letters in the result to upper case. + +@item @t{v} +Used with @t{k}, substitute (as two consecutive words) both the key +and the value of each associative array element. Used with subscripts, +force values to be substituted even if the subscript form refers to +indices or keys. + +@item @t{V} +Make any special characters in the resulting words visible. + +@item @t{w} +With @t{$@{#}@var{name}@t{@}}, count words in arrays or strings; the @t{s} +flag may be used to set a word delimiter. + +@item @t{W} +Similar to @t{w} with the difference that empty words between +repeated delimiters are also counted. + +@item @t{X} +With this flag, parsing errors occurring with the @t{Q}, @t{e} and @t{#} +flags or the pattern matching forms such as +`@t{$@{}@var{name}@t{#}@var{pattern}@t{@}}' are reported. Without the flag, +errors are silently ignored. + +@item @t{z} +Split the result of the expansion into words using shell parsing to +find the words, i.e. taking into account any quoting in the value. +Comments are not treated specially but as ordinary strings, similar +to interactive shells with the @t{INTERACTIVE_COMMENTS} option unset +(however, see the @t{Z} flag below for related options) + +@noindent +Note that this is done very late, even later than the `@t{(s)}' flag. So to +access single words in the result use nested expansions as +in `@t{$@{$@{(z)foo@}[2]@}}'. Likewise, to remove the quotes in the +resulting words use `@t{$@{(Q)$@{(z)foo@}@}}'. + +@item @t{0} +Split the result of the expansion on null bytes. This is a shorthand +for `@t{ps:\0:}'. + +@end table + +@noindent +The following flags (except @t{p}) are followed by one or more arguments +as shown. Any character, or the matching pairs `@t{(}...@t{)}', +`@t{@{}...@t{@}}', `@t{[}...@t{]}', or `@t{<}...@t{>}', may be used in place +of a colon as delimiters, but note that when a flag takes more than one +argument, a matched pair of delimiters must surround each argument. + +@noindent +@table @asis +@item @t{p} +Recognize the same escape sequences as the @t{print} builtin +in string arguments to any of the flags described below that +follow this argument. + +@noindent +Alternatively, with this option string arguments may be in the form +@t{$}@var{var} in which case the value of the variable is substituted. +Note this form is strict; the string argument does not undergo general +parameter expansion. + +@noindent +For example, + +@noindent +@example +sep=: +val=a:b:c +print $@{(ps.$sep.)val@} +@end example + +@noindent +splits the variable on a @t{:}. + +@item @t{~} +Strings inserted into the expansion by any of the flags below are to +be treated as patterns. This applies to the string arguments of flags +that follow @t{~} within the same set of parentheses. Compare with @t{~} +outside parentheses, which forces the entire substituted string to +be treated as a pattern. Hence, for example, + +@noindent +@example +[[ "?" = $@{(~j.|.)array@} ]] +@end example + +@noindent +treats `@t{|}' as a pattern and succeeds if and only if @t{$array} +contains the string `@t{?}' as an element. The @t{~} may be +repeated to toggle the behaviour; its effect only lasts to the +end of the parenthesised group. + +@item @t{j:}@var{string}@t{:} +Join the words of arrays together using @var{string} as a separator. +@pindex SH_WORD_SPLIT, use of +Note that this occurs before field splitting by the @t{s:}@var{string}@t{:} +flag or the @t{SH_WORD_SPLIT} option. + +@item @t{l:}@var{expr}@t{::}@var{string1}@t{::}@var{string2}@t{:} +Pad the resulting words on the left. Each word will be truncated if +required and placed in a field @var{expr} characters wide. + +@noindent +The arguments @t{:}@var{string1}@t{:} and @t{:}@var{string2}@t{:} are +optional; neither, the first, or both may be given. Note that the same +pairs of delimiters must be used for each of the three arguments. The +space to the left will be filled with @var{string1} (concatenated as +often as needed) or spaces if @var{string1} is not given. If both +@var{string1} and @var{string2} are given, @var{string2} is inserted once +directly to the left of each word, truncated if necessary, before +@var{string1} is used to produce any remaining padding. + +@noindent +If either of @var{string1} or @var{string2} is present but empty, +i.e. there are two delimiters together at that point, the first +character of @t{$IFS} is used instead. + +@noindent +If the @t{MULTIBYTE} option is in effect, the flag @t{m} may also +be given, in which case widths will be used for the calculation of +padding; otherwise individual multibyte characters are treated as occupying +one unit of width. + +@noindent +If the @t{MULTIBYTE} option is not in effect, each byte in the string is +treated as occupying one unit of width. + +@noindent +Control characters are always assumed to be one unit wide; this allows the +mechanism to be used for generating repetitions of control characters. + +@item @t{m} +Only useful together with one of the flags @t{l} or @t{r} or with the +@t{#} length operator when the @t{MULTIBYTE} option +is in effect. Use the character width reported by the system in +calculating how much of the string it occupies or the overall +length of the string. Most printable characters have a width of one +unit, however certain Asian character sets and certain special effects +use wider characters; combining characters have zero width. +Non-printable characters are arbitrarily counted as zero width; how they +would actually be displayed will vary. + +@noindent +If the @t{m} is repeated, the character either counts zero (if it has +zero width), else one. For printable character strings this has the +effect of counting the number of glyphs (visibly separate characters), +except for the case where combining characters themselves have non-zero +width (true in certain alphabets). + +@item @t{r:}@var{expr}@t{::}@var{string1}@t{::}@var{string2}@t{:} +As @t{l}, but pad the words on the right and insert @var{string2} +immediately to the right of the string to be padded. + +@noindent +Left and right padding may be used together. In this case the strategy +is to apply left padding to the first half width of each of the resulting +words, and right padding to the second half. If the string to be +padded has odd width the extra padding is applied on the left. + +@item @t{s:}@var{string}@t{:} +Force field splitting at the +separator @var{string}. Note that a @var{string} of two or more +characters means that all of them must match in sequence; this differs from +the treatment of two or more characters in the @t{IFS} parameter. +See also the @t{=} flag and the @t{SH_WORD_SPLIT} option. An empty +string may also be given in which case every character will be a separate +element. + +@noindent +For historical reasons, the usual behaviour that empty array elements +are retained inside double quotes is disabled for arrays generated +by splitting; hence the following: + +@noindent +@example +line="one::three" +print -l "$@{(s.:.)line@}" +@end example + +@noindent +produces two lines of output for @t{one} and @t{three} and elides the +empty field. To override this behaviour, supply the `@t{(@@)}' flag as well, +i.e. @t{"$@{(@@s.:.)line@}"}. + +@item @t{Z:}@var{opts}@t{:} +As @t{z} but takes a combination of option letters between a following +pair of delimiter characters. With no options the effect is identical +to @t{z}. @t{(Z+c+)} +causes comments to be parsed as a string and retained; any field in the +resulting array beginning with an unquoted comment character is a +comment. @t{(Z+C+)} causes comments to be parsed +and removed. The rule for comments is standard: anything between a word +starting with the third character of @t{$HISTCHARS}, default @t{#}, up to +the next newline is a comment. @t{(Z+n+)} causes +unquoted newlines to be treated as ordinary whitespace, else they are +treated as if they are shell code delimiters and converted to +semicolons. Options are combined within the same set of delimiters, +e.g. @t{(Z+Cn+)}. + +@item @t{_:}@var{flags}@t{:} +The underscore (@t{_}) flag is reserved for future use. As of this +revision of zsh, there are no valid @var{flags}; anything following an +underscore, other than an empty pair of delimiters, is treated as an +error, and the flag itself has no effect. + +@end table + +@noindent +The following flags are meaningful with the @t{$@{}...@t{#}...@t{@}} or +@t{$@{}...@t{%}...@t{@}} forms. The @t{S} and @t{I} flags may also be +used with the @t{$@{}...@t{/}...@t{@}} forms. + +@noindent +@table @asis +@item @t{S} +With @t{#} or @t{##}, search for the match that starts closest to the start of +the string (a `substring match'). Of all matches at a particular position, +@t{#} selects the shortest and @t{##} the longest: + +@noindent +@example +% str="aXbXc" +% echo $@{(S)str#X*@} +abXc +% echo $@{(S)str##X*@} +a +% +@end example + +@noindent +With @t{%} or @t{%%}, search for the match that starts closest to the end of +the string: + +@noindent +@example +% str="aXbXc" +% echo $@{(S)str%X*@} +aXbc +% echo $@{(S)str%%X*@} +aXb +% +@end example + +@noindent +(Note that @t{%} and @t{%%} don't search for the match that ends closest to the +end of the string, as one might expect.) + +@noindent +With substitution via @t{$@{}...@t{/}...@t{@}} or +@t{$@{}...@t{//}...@t{@}}, specifies non-greedy matching, i.e. that the +shortest instead of the longest match should be replaced: + +@noindent +@example +% str="abab" +% echo $@{str/*b/_@} +_ +% echo $@{(S)str/*b/_@} +_ab +% +@end example + +@item @t{I:}@var{expr}@t{:} +Search the @var{expr}th match (where @var{expr} evaluates to a number). +This only applies when searching for substrings, either with the @t{S} +flag, or with @t{$@{}...@t{/}...@t{@}} (only the @var{expr}th match is +substituted) or @t{$@{}...@t{//}...@t{@}} (all matches from the +@var{expr}th on are substituted). The default is to take the first match. + +@noindent +The @var{expr}th match is counted such that there is either one or zero +matches from each starting position in the string, although for global +substitution matches overlapping previous replacements are ignored. With +the @t{$@{}...@t{%}...@t{@}} and @t{$@{}...@t{%%}...@t{@}} forms, the starting +position for the match moves backwards from the end as the index increases, +while with the other forms it moves forward from the start. + +@noindent +Hence with the string +@example +which switch is the right switch for Ipswich? +@end example +substitutions of the form +@t{$@{}(@t{SI:}@var{N}@t{:})@t{string#w*ch@}} as @var{N} increases +from 1 will match and remove `@t{which}', `@t{witch}', `@t{witch}' and +`@t{wich}'; the form using `@t{##}' will match and remove `@t{which switch +is the right switch for Ipswich}', `@t{witch is the right switch for +Ipswich}', `@t{witch for Ipswich}' and `@t{wich}'. The form using `@t{%}' +will remove the same matches as for `@t{#}', but in reverse order, and the +form using `@t{%%}' will remove the same matches as for `@t{##}' in reverse +order. + +@item @t{B} +Include the index of the beginning of the match in the result. + +@item @t{E} +Include the index one character past the end of the match in the result +(note this is inconsistent with other uses of parameter index). + +@item @t{M} +Include the matched portion in the result. + +@item @t{N} +Include the length of the match in the result. + +@item @t{R} +Include the unmatched portion in the result (the @emph{R}est). + +@end table + +@noindent + +@subsection Rules +@noindent + +@noindent +Here is a summary of the rules for substitution; this assumes that braces +are present around the substitution, i.e. @t{$@{}@var{...}@t{@}}. Some particular +examples are given below. Note that the Zsh Development Group accepts +@emph{no responsibility} for any brain damage which may occur during the +reading of the following rules. + +@noindent +@table @asis +@item @t{1.} @emph{Nested substitution} +If multiple nested @t{$@{}@var{...}@t{@}} forms are present, substitution is +performed from the inside outwards. At each level, the substitution takes +account of whether the current value is a scalar or an array, whether the +whole substitution is in double quotes, and what flags are supplied to the +current level of substitution, just as if the nested substitution were the +outermost. The flags are not propagated up to enclosing +substitutions; the nested substitution will return either a scalar or an +array as determined by the flags, possibly adjusted for quoting. All the +following steps take place where applicable at all levels of substitution. + +@noindent +Note that, unless the `@t{(P)}' flag is present, the flags and any +subscripts apply directly to the value of the nested substitution; for +example, the expansion @t{$@{$@{foo@}@}} behaves exactly the same as +@t{$@{foo@}}. When the `@t{(P)}' flag is present in a nested substitution, +the other substitution rules are applied to the value @emph{before} it is +interpreted as a name, so @t{$@{$@{(P)foo@}@}} may differ from @t{$@{(P)foo@}}. + +@noindent +At each nested level of substitution, the substituted words undergo all +forms of single-word substitution (i.e. not filename generation), including +command substitution, arithmetic expansion and filename expansion +(i.e. leading @t{~} and @t{=}). Thus, for example, @t{$@{$@{:-=cat@}:h@}} +expands to the directory where the @t{cat} program resides. (Explanation: +the internal substitution has no parameter but a default value @t{=cat}, +which is expanded by filename expansion to a full path; the outer +substitution then applies the modifier @t{:h} and takes the directory part +of the path.) + +@item @t{2.} @emph{Internal parameter flags} +Any parameter flags set by one of the @t{typeset} family of commands, in +particular the @t{-L}, @t{-R}, @t{-Z}, @t{-u} and @t{-l} options for +padding and capitalization, are applied directly to the parameter value. +Note these flags are options to the command, e.g. `@t{typeset -Z}'; they +are not the same as the flags used within parameter substitutions. + +@noindent +At the outermost level of substitution, the `@t{(P)}' flag (rule @t{4.}) +ignores these transformations and uses the unmodified value of the +parameter as the name to be replaced. This is usually the desired +behavior because padding may make the value syntactically illegal as a +parameter name, but if capitalization changes are desired, use the +@t{$@{$@{(P)foo@}@}} form (rule @t{25.}). + +@item @t{3.} @emph{Parameter subscripting} +If the value is a raw parameter reference with a subscript, such as +@t{$@{}@var{var}@t{[3]@}}, the effect of subscripting is applied directly to +the parameter. Subscripts are evaluated left to right; subsequent +subscripts apply to the scalar or array value yielded by the previous +subscript. Thus if @t{var} is an array, @t{$@{var[1][2]@}} is the second +character of the first word, but @t{$@{var[2,4][2]@}} is the entire third +word (the second word of the range of words two through four of the +original array). Any number of subscripts may appear. Flags such as +`@t{(k)}' and `@t{(v)}' which alter the result of subscripting are applied. + +@item @t{4.} @emph{Parameter name replacement} +At the outermost level of nesting only, the `@t{(P)}' flag is applied. This +treats the value so far as a parameter name (which may include a subscript +expression) and replaces that with the corresponding value. This +replacement occurs later if the `@t{(P)}' flag appears in a nested +substitution. + +@noindent +If the value so far names a parameter that has internal flags (rule @t{2.}), +those internal flags are applied to the new value after replacement. + +@item @t{5.} @emph{Double-quoted joining} +If the value after this process is an array, and the substitution +appears in double quotes, and neither an `@t{(@@)}' flag nor a `@t{#}' +length operator is present at the current level, then words of the +value are joined with the first character of the parameter @t{$IFS}, +by default a space, between each word (single word arrays are not +modified). If the `@t{(j)}' flag is present, that is used for joining +instead of @t{$IFS}. + +@item @t{6.} @emph{Nested subscripting} +Any remaining subscripts (i.e. of a nested substitution) are evaluated at +this point, based on whether the value is an array or a scalar. As with +@t{3.}, multiple subscripts can appear. Note that @t{$@{foo[2,4][2]@}} is +thus equivalent to @t{$@{$@{foo[2,4]@}[2]@}} and also to +@t{"$@{$@{(@@)foo[2,4]@}[2]@}"} (the nested substitution returns an array in +both cases), but not to @t{"$@{$@{foo[2,4]@}[2]@}"} (the nested substitution +returns a scalar because of the quotes). + +@item @t{7.} @emph{Modifiers} +Any modifiers, as specified by a trailing `@t{#}', `@t{%}', `@t{/}' +(possibly doubled) or by a set of modifiers of the form `@t{:...}' (see +@ref{Modifiers} in @ref{History Expansion}), are applied to the words +of the value at this level. + +@item @t{8.} @emph{Character evaluation} +Any `@t{(#)}' flag is applied, evaluating the result so far numerically +as a character. + +@item @t{9.} @emph{Length} +Any initial `@t{#}' modifier, i.e. in the form @t{$@{#}@var{var}@t{@}}, is +used to evaluate the length of the expression so far. + +@item @t{10.} @emph{Forced joining} +If the `@t{(j)}' flag is present, or no `@t{(j)}' flag is present but +the string is to be split as given by rule @t{11.}, and joining +did not take place at rule @t{5.}, any words in the value are joined +together using the given string or the first character of @t{$IFS} if none. +Note that the `@t{(F)}' flag implicitly supplies a string for joining in this +manner. + +@item @t{11.} @emph{Simple word splitting} +If one of the `@t{(s)}' or `@t{(f)}' flags are present, or the `@t{=}' +specifier was present (e.g. @t{$@{=}@var{var}@t{@}}), the word is split on +occurrences of the specified string, or (for @t{=} with neither of the two +flags present) any of the characters in @t{$IFS}. + +@noindent +If no `@t{(s)}', `@t{(f)}' or `@t{=}' was given, but the word is not +quoted and the option @t{SH_WORD_SPLIT} is set, the word is split on +occurrences of any of the characters in @t{$IFS}. Note this step, too, +takes place at all levels of a nested substitution. + +@item @t{12.} @emph{Case modification} +Any case modification from one of the flags `@t{(L)}', `@t{(U)}' or `@t{(C)}' +is applied. + +@item @t{13.} @emph{Escape sequence replacement} +First any replacements from the `@t{(g)}' flag are performed, then any +prompt-style formatting from the `@t{(%)}' family of flags is applied. + +@item @t{14.} @emph{Quote application} +Any quoting or unquoting using `@t{(q)}' and `@t{(Q)}' and related flags +is applied. + +@item @t{15.} @emph{Directory naming} +Any directory name substitution using `@t{(D)}' flag is applied. + +@item @t{16.} @emph{Visibility enhancement} +Any modifications to make characters visible using the `@t{(V)}' flag +are applied. + +@item @t{17.} @emph{Lexical word splitting} +If the '@t{(z)}' flag or one of the forms of the '@t{(Z)}' flag is +present, the word is split as if it were a shell command line, so that +quotation marks and other metacharacters are used to decide what +constitutes a word. Note this form of splitting is entirely distinct +from that described by rule @t{11.}: it does not use @t{$IFS}, and +does not cause forced joining. + +@item @t{18.} @emph{Uniqueness} +If the result is an array and the `@t{(u)}' flag was present, duplicate +elements are removed from the array. + +@item @t{19.} @emph{Ordering} +If the result is still an array and one of the `@t{(o)}' or `@t{(O)}' flags +was present, the array is reordered. + +@item @t{20.} @t{RC_EXPAND_PARAM} +At this point the decision is made whether any resulting array elements +are to be combined element by element with surrounding text, as given +by either the @t{RC_EXPAND_PARAM} option or the `@t{^}' flag. + +@item @t{21.} @emph{Re-evaluation} +Any `@t{(e)}' flag is applied to the value, forcing it to be re-examined +for new parameter substitutions, but also for command and arithmetic +substitutions. + +@item @t{22.} @emph{Padding} +Any padding of the value by the `@t{(l.}@var{fill}@t{.)}' or +`@t{(r.}@var{fill}@t{.)}' flags is applied. + +@item @t{23.} @emph{Semantic joining} +In contexts where expansion semantics requires a single word to +result, all words are rejoined with the first character of @t{IFS} +between. So in `@t{$@{(P}@t{)$@{(f}@t{)lines@}@}}' +the value of @t{$@{lines@}} is split at newlines, but then must be +joined again before the `@t{(P)}' flag can be applied. + +@noindent +If a single word is not required, this rule is skipped. + +@item @t{24.} @emph{Empty argument removal} +If the substitution does not appear in double quotes, any resulting +zero-length argument, whether from a scalar or an element of an array, +is elided from the list of arguments inserted into the command line. + +@noindent +Strictly speaking, the removal happens later as the same happens with +other forms of substitution; the point to note here is simply that +it occurs after any of the above parameter operations. + +@item @t{25.} @emph{Nested parameter name replacement} +If the `@t{(P)}' flag is present and rule @t{4.} has not applied, the +value so far is treated as a parameter name (which may include a subscript +expression) and replaced with the corresponding value, with internal flags +(rule @t{2.}) applied to the new value. + +@end table + +@noindent + +@subsection Examples +@noindent +The flag @t{f} is useful to split a double-quoted substitution line by +line. For example, @t{$@{(f)"$(<}@var{file}@t{)"@}} +substitutes the contents of @var{file} divided so that each line is +an element of the resulting array. Compare this with the effect of +@t{$}@t{(<}@var{file}@t{)} alone, which divides the file +up by words, or the same inside double quotes, which makes the entire +content of the file a single string. + +@noindent +The following illustrates the rules for nested parameter expansions. +Suppose that @t{$foo} contains the array @t{(bar baz}@t{)}: + +@noindent +@table @asis +@item @t{"$@{(@@)$@{foo@}[1]@}"} +This produces the result @t{b}. First, the inner substitution +@t{"$@{foo@}"}, which has no array (@t{@@}) flag, produces a single word +result @t{"bar baz"}. The outer substitution @t{"$@{(@@)...[1]@}"} detects +that this is a scalar, so that (despite the `@t{(@@)}' flag) the subscript +picks the first character. + +@item @t{"$@{$@{(@@)foo@}[1]@}"} +This produces the result `@t{bar}'. In this case, the inner substitution +@t{"$@{(@@)foo@}"} produces the array `@t{(bar baz}@t{)}'. The outer +substitution @t{"$@{...[1]@}"} detects that this is an array and picks the +first word. This is similar to the simple case @t{"$@{foo[1]@}"}. + +@end table + +@noindent +As an example of the rules for word splitting and joining, suppose @t{$foo} +contains the array `@t{(ax1 bx1}@t{)}'. Then + +@noindent +@table @asis +@item @t{$@{(s/x/)foo@}} +produces the words `@t{a}', `@t{1 b}' and `@t{1}'. + +@item @t{$@{(j/x/s/x/)foo@}} +produces `@t{a}', `@t{1}', `@t{b}' and `@t{1}'. + +@item @t{$@{(s/x/)foo%%1*@}} +produces `@t{a}' and `@t{ b}' (note the extra space). As substitution +occurs before either joining or splitting, the operation first generates +the modified array @t{(ax bx}@t{)}, which is joined to give +@t{"ax bx"}, and then split to give `@t{a}', `@t{ b}' and `'. The final +empty string will then be elided, as it is not in double quotes. + +@end table + +@noindent +@node Command Substitution, Arithmetic Expansion, Parameter Expansion, Expansion + +@section Command Substitution +@noindent +@cindex command substitution +@cindex substitution, command +A command enclosed in parentheses preceded by a dollar sign, like +`@t{$(}...@t{)}', or quoted with grave +accents, like `@t{`}...@t{`}', is replaced with its standard output, with +any trailing newlines deleted. +If the substitution is not enclosed in double quotes, the +output is broken into words using the @t{IFS} parameter. +@vindex IFS, use of + +@noindent +The substitution `@t{$(cat} @var{foo}@t{)}' may be replaced +by the faster `@t{$(<}@var{foo}@t{)}'. In this case @var{foo} +undergoes single word shell expansions (@emph{parameter expansion}, +@emph{command substitution} and @emph{arithmetic expansion}), but not +filename generation. + +@noindent +If the option @t{GLOB_SUBST} is set, the result of any unquoted command +substitution, including the special form just mentioned, is eligible for +filename generation. + +@noindent +@node Arithmetic Expansion, Brace Expansion, Command Substitution, Expansion + +@section Arithmetic Expansion +@noindent +@cindex arithmetic expansion +@cindex expansion, arithmetic +A string of the form `@t{$[}@var{exp}@t{]}' or +`@t{$((}@var{exp}@t{))}' is substituted +with the value of the arithmetic expression @var{exp}. @var{exp} is +subjected to @emph{parameter expansion}, @emph{command substitution} +and @emph{arithmetic expansion} before it is evaluated. +See @ref{Arithmetic Evaluation}. +@node Brace Expansion, Filename Expansion, Arithmetic Expansion, Expansion + +@section Brace Expansion +@noindent +@cindex brace expansion +@cindex expansion, brace +A string of the form +`@var{foo}@t{@{}@var{xx}@t{,}@var{yy}@t{,}@var{zz}@t{@}}@var{bar}' +is expanded to the individual words +`@var{fooxxbar}', `@var{fooyybar}' and `@var{foozzbar}'. +Left-to-right order is preserved. This construct +may be nested. Commas may be quoted in order to +include them literally in a word. + +@noindent +An expression of the form `@t{@{}@var{n1}@t{..}@var{n2}@t{@}}', +where @var{n1} and @var{n2} are integers, +is expanded to every number between +@var{n1} and @var{n2} inclusive. If either number begins with a +zero, all the resulting numbers will be padded with leading zeroes to +that minimum width, but for negative numbers the @t{-} character is also +included in the width. If the numbers are in decreasing order the +resulting sequence will also be in decreasing order. + +@noindent +An expression of the form `@t{@{}@var{n1}@t{..}@var{n2}@t{..}@var{n3}@t{@}}', +where @var{n1}, @var{n2}, and @var{n3} are integers, +is expanded as above, but only every @var{n3}th number starting from @var{n1} +is output. If @var{n3} is negative the numbers are output in reverse order, +this is slightly different from simply swapping @var{n1} and @var{n2} in the case +that the step @var{n3} doesn't evenly divide the range. Zero padding can be +specified in any of the three numbers, specifying it in the third can be useful +to pad for example `@t{@{-99..100..01@}}' which is not possible to specify by putting a +0 on either of the first two numbers (i.e. pad to two characters). + +@noindent +An expression of the form `@t{@{}@var{c1}@t{..}@var{c2}@t{@}}', where +@var{c1} and @var{c2} are single characters (which may be multibyte +characters), is expanded to every character in the range from @var{c1} to +@var{c2} in whatever character sequence is used internally. For +characters with code points below 128 this is US ASCII (this is the only +case most users will need). If any intervening character is not +printable, appropriate quotation is used to render it printable. +If the character sequence is reversed, the output is in reverse +order, e.g. `@t{@{d..a@}}' is substituted as `@t{d c b a}'. + +@noindent +If a brace expression matches none of the above forms, it is left +unchanged, unless the option @t{BRACE_CCL} (an abbreviation for `brace +character class') is set. +@pindex BRACE_CCL, use of +In that case, it is expanded to a list of the individual +characters between the braces sorted into the order of the characters +in the ASCII character set (multibyte characters are not currently +handled). The syntax is similar to a +@t{[}...@t{]} expression in filename generation: +`@t{-}' is treated specially to denote a range of characters, but `@t{^}' or +`@t{!}' as the first character is treated normally. For example, +`@t{@{abcdef0-9@}}' expands to 16 words @t{0 1 2 3 4 5 6 7 8 9 a b c d e f}. + +@noindent +Note that brace expansion is not part of filename generation (globbing); an +expression such as @t{*/@{foo,bar@}} is split into two separate words +@t{*/foo} and @t{*/bar} before filename generation takes place. In +particular, note that this is liable to produce a `no match' error if +@emph{either} of the two expressions does not match; this is to be contrasted +with @t{*/(foo|bar)}, which is treated as a single pattern but otherwise +has similar effects. + +@noindent +To combine brace expansion with array expansion, see the +@t{$@{^}@var{spec}@t{@}} form described +in @ref{Parameter Expansion} +above. + +@noindent +@node Filename Expansion, Filename Generation, Brace Expansion, Expansion + +@section Filename Expansion +@noindent +@cindex filename expansion +@cindex expansion, filename +Each word is checked to see if it begins with an unquoted `@t{~}'. +If it does, then the word up to a `@t{/}', +or the end of the word if there is no `@t{/}', +is checked to see if it can be substituted in one of the ways +described here. If so, then the `@t{~}' and the checked portion are +replaced with the appropriate substitute value. + +@noindent +A `@t{~}' by itself is replaced by the value of @t{$HOME}. +A `@t{~}' followed by a `@t{+}' or a `@t{-}' is replaced by current +or previous working directory, respectively. + +@noindent +A `@t{~}' followed by a number is replaced by the directory at that +position in the directory stack. +`@t{~0}' is equivalent to `@t{~+}', +and `@t{~1}' is the top of the stack. +`@t{~+}' followed by a number is replaced by the directory at that +position in the directory stack. +`@t{~+0}' is equivalent to `@t{~+}', +and `@t{~+1}' is the top of the stack. +`@t{~-}' followed by a number is replaced by the directory that +many positions from the bottom of the stack. +`@t{~-0}' is the bottom of the stack. +@pindex PUSHD_MINUS, use of +The @t{PUSHD_MINUS} +option exchanges the effects of `@t{~+}' and `@t{~-}' where they are +followed by a number. + +@noindent + +@subsection Dynamic named directories +@noindent +@cindex directories, named, dynamic +@cindex named directories, dynamic +@cindex dynamic named directories + +@noindent +If the function @t{zsh_directory_name} exists, or the shell variable +@t{zsh_directory_name_functions} exists and contains an array of +function names, then the functions are used to implement dynamic +directory naming. The functions are tried in order until one returns +status zero, so it is important that functions test whether they can +handle the case in question and return an appropriate status. + +@noindent +A `@t{~}' followed by a string @var{namstr} in unquoted square brackets is +treated specially as a dynamic directory name. Note that the first +unquoted closing square bracket always terminates @var{namstr}. The shell +function is passed two arguments: the string @t{n} (for name) and +@var{namstr}. It should either set the array @t{reply} to a single element +which is the directory corresponding to the name and return status zero +(executing an assignment as the last statement is usually sufficient), or +it should return status non-zero. In the former case the element of reply +is used as the directory; in the latter case the substitution is deemed to +have failed. If all functions fail and the option @t{NOMATCH} is set, +an error results. + +@noindent +The functions defined as above are also used to see if a directory can +be turned into a name, for example when printing the directory stack or +when expanding @t{%~} in prompts. In this case each function is passed two +arguments: the string @t{d} (for directory) and the candidate for dynamic +naming. The function should either return non-zero status, if the +directory cannot be named by the function, or it should set the array reply +to consist of two elements: the first is the dynamic name for the directory +(as would appear within `@t{~[}@var{...}@t{]}'), and the second is the +prefix length of the directory to be replaced. For example, if the trial +directory is @t{/home/myname/src/zsh} and the dynamic name for +@t{/home/myname/src} (which has 16 characters) is @t{s}, then the function +sets + +@noindent +@example +reply=(s 16) +@end example + +@noindent +The directory name so returned is compared with possible static names for +parts of the directory path, as described below; it is used if the prefix +length matched (16 in the example) is longer than that matched by any +static name. + +@noindent +It is not a requirement that a function implements both +@t{n} and @t{d} calls; for example, it might be appropriate for certain +dynamic forms of expansion not to be contracted to names. In that case +any call with the first argument @t{d} should cause a non-zero status to +be returned. + +@noindent +The completion system calls `@t{zsh_directory_name c}' followed by +equivalent calls to elements of the array +@t{zsh_directory_name_functions}, if it exists, in order to +complete dynamic names for directories. The code for this should be +as for any other completion function as described in +@ref{Completion System}. + +@noindent +As a working example, here is a function that expands any dynamic names +beginning with the string @t{p:} to directories below +@t{/home/pws/perforce}. In this simple case a static name for the +directory would be just as effective. + +@noindent +@example +zsh_directory_name() @{ + emulate -L zsh + setopt extendedglob + local -a match mbegin mend + if [[ $1 = d ]]; then + # turn the directory into a name + if [[ $2 = (#b)(/home/pws/perforce/)([^/]##)* ]]; then + typeset -ga reply + reply=(p:$match[2] $(( $@{#match[1]@} + $@{#match[2]@} )) ) + else + return 1 + fi + elif [[ $1 = n ]]; then + # turn the name into a directory + [[ $2 != (#b)p:(?*) ]] && return 1 + typeset -ga reply + reply=(/home/pws/perforce/$match[1]) + elif [[ $1 = c ]]; then + # complete names + local expl + local -a dirs + dirs=(/home/pws/perforce/*(/:t)) + dirs=(p:$@{^dirs@}) + _wanted dynamic-dirs expl 'dynamic directory' compadd -S\] -a dirs + return + else + return 1 + fi + return 0 +@} +@end example + +@noindent + +@subsection Static named directories +@noindent +@cindex directories, named, static +@cindex named directories, static +@cindex static named directories +A `@t{~}' followed by anything not already covered consisting +of any number of alphanumeric characters or underscore (`@t{_}'), +hyphen (`@t{-}'), or dot (`@t{.}') is looked up as a +named directory, and replaced by the value of that named directory if found. +Named directories are typically home directories for users on the system. +They may also be defined if the text after the `@t{~}' is the name +of a string shell parameter whose value begins with a `@t{/}'. +Note that trailing slashes will be removed from the path to the directory +(though the original parameter is not modified). + +@noindent +It is also possible to define directory names using the @t{-d} option to the +@t{hash} builtin. + +@noindent +When the shell prints a path (e.g. when expanding @t{%~} in prompts or when +printing the directory stack), the path is checked to see if it has a named +directory as its prefix. If so, then the prefix portion is replaced with a +`@t{~}' followed by the name of the directory. +The shorter of the two ways of referring to the directory is used, +i.e. either the directory name or the full path; the name is used +if they are the same length. +The parameters @t{$PWD} and @t{$OLDPWD} are never abbreviated in this fashion. + +@noindent + +@subsection `=' expansion +@noindent + +@noindent +If a word begins with an unquoted `@t{=}' +and the @t{EQUALS} option is set, +the remainder of the word is taken as the +name of a command. If a command +exists by that name, the word is replaced +by the full pathname of the command. + +@noindent + +@subsection Notes +@noindent + +@noindent +Filename expansion is performed on the right hand side of a parameter +assignment, including those appearing after commands of the +@t{typeset} family. In this case, the right hand side will be treated +as a colon-separated list in the manner of the @t{PATH} parameter, +so that a `@t{~}' or an `@t{=}' following a `@t{:}' is eligible for expansion. +All such behaviour can be +disabled by quoting the `@t{~}', the `@t{=}', or the whole expression (but not +simply the colon); the @t{EQUALS} option is also respected. + +@noindent +If the option @t{MAGIC_EQUAL_SUBST} is set, any unquoted shell +argument in the form `@var{identifier}@t{=}@var{expression}' becomes eligible +for file expansion as described in the previous paragraph. Quoting the +first `@t{=}' also inhibits this. + +@noindent +@node Filename Generation, , Filename Expansion, Expansion + +@section Filename Generation +@noindent +@cindex filename generation +If a word contains an unquoted instance of one of the characters +`@t{*}', `@t{(}', `@t{|}', `@t{<}', `@t{[}', or `@t{?}', it is regarded +as a pattern for filename generation, unless the @t{GLOB} option is unset. +@pindex GLOB, use of +If the @t{EXTENDED_GLOB} option is set, +@pindex EXTENDED_GLOB, use of +the `@t{^}' and `@t{#}' characters also denote a pattern; otherwise +they are not treated specially by the shell. + +@noindent +The word is replaced with a list of sorted filenames that match +the pattern. If no matching pattern is found, the shell gives +an error message, unless the @t{NULL_GLOB} option is set, +@pindex NULL_GLOB, use of +in which case the word is deleted; or unless the @t{NOMATCH} +option is unset, in which case the word is left unchanged. +@pindex NOMATCH, use of + +@noindent +In filename generation, +the character `@t{/}' must be matched explicitly; +also, a `@t{.}' must be matched +explicitly at the beginning of a pattern or after a `@t{/}', unless the +@t{GLOB_DOTS} option is set. +@pindex GLOB_DOTS, use of +No filename generation pattern +matches the files `@t{.}' or `@t{..}'. In other instances of pattern +matching, the `@t{/}' and `@t{.}' are not treated specially. + +@subsection Glob Operators +@noindent +@table @asis +@item @t{*} +Matches any string, including the null string. + +@item @t{?} +Matches any character. + +@item @t{[}...@t{]} +Matches any of the enclosed characters. Ranges of characters +can be specified by separating two characters by a `@t{-}'. +A `@t{-}' or `@t{]}' may be matched by including it as the +first character in the list. +@cindex character classes +There are also several named classes of characters, in the form +`@t{[:}@var{name}@t{:]}' with the following meanings. +The first set use the macros provided by +the operating system to test for the given character combinations, +including any modifications due to local language settings, see +man page ctype(3): + +@noindent +@table @asis +@item @t{[:alnum:]} +The character is alphanumeric + +@item @t{[:alpha:]} +The character is alphabetic + +@item @t{[:ascii:]} +The character is 7-bit, i.e. is a single-byte character without +the top bit set. + +@item @t{[:blank:]} +The character is a blank character + +@item @t{[:cntrl:]} +The character is a control character + +@item @t{[:digit:]} +The character is a decimal digit + +@item @t{[:graph:]} +The character is a printable character other than whitespace + +@item @t{[:lower:]} +The character is a lowercase letter + +@item @t{[:print:]} +The character is printable + +@item @t{[:punct:]} +The character is printable but neither alphanumeric nor whitespace + +@item @t{[:space:]} +The character is whitespace + +@item @t{[:upper:]} +The character is an uppercase letter + +@item @t{[:xdigit:]} +The character is a hexadecimal digit + +@end table + +@noindent +Another set of named classes is handled internally by the shell and +is not sensitive to the locale: + +@noindent +@table @asis +@item @t{[:IDENT:]} +The character is allowed to form part of a shell identifier, such +as a parameter name + +@item @t{[:IFS:]} +The character is used as an input field separator, i.e. is contained in the +@t{IFS} parameter + +@item @t{[:IFSSPACE:]} +The character is an IFS white space character; see the documentation +for @t{IFS} in +@ref{Parameters Used By The Shell}. + +@item @t{[:INCOMPLETE:]} +Matches a byte that starts an incomplete multibyte character. +Note that there may be a sequence of more than one bytes that +taken together form the prefix of a multibyte character. To +test for a potentially incomplete byte sequence, use the pattern +`@t{[[:INCOMPLETE:]]*}'. This will never match a sequence starting +with a valid multibyte character. + +@item @t{[:INVALID:]} +Matches a byte that does not start a valid multibyte character. +Note this may be a continuation byte of an incomplete multibyte +character as any part of a multibyte string consisting of invalid and +incomplete multibyte characters is treated as single bytes. + +@item @t{[:WORD:]} +The character is treated as part of a word; this test is sensitive +to the value of the @t{WORDCHARS} parameter + +@end table + +@noindent +Note that the square brackets are additional +to those enclosing the whole set of characters, so to test for a +single alphanumeric character you need `@t{[[:alnum:]]}'. Named +character sets can be used alongside other types, +e.g. `@t{[[:alpha:]0-9]}'. + +@item @t{[^}...@t{]} +@itemx @t{[!}...@t{]} +Like @t{[}...@t{]}, except that it matches any character which is +not in the given set. + +@item @t{<}[@var{x}]@t{-}[@var{y}]@t{>} +Matches any number in the range @var{x} to @var{y}, inclusive. +Either of the numbers may be omitted to make the range open-ended; +hence `@t{<->}' matches any number. To match individual digits, the +@t{[}...@t{]} form is more efficient. + +@noindent +Be careful when using other wildcards adjacent to patterns of this form; +for example, @t{<0-9>*} will actually match any number whatsoever at the +start of the string, since the `@t{<0-9>}' will match the first digit, and +the `@t{*}' will match any others. This is a trap for the unwary, but is +in fact an inevitable consequence of the rule that the longest possible +match always succeeds. Expressions such as `@t{<0-9>[^[:digit:]]*}' can be +used instead. + +@item @t{(}...@t{)} +Matches the enclosed pattern. This is used for grouping. +If the @t{KSH_GLOB} option is set, then a +`@t{@@}', `@t{*}', `@t{+}', `@t{?}' or `@t{!}' immediately preceding +the `@t{(}' is treated specially, as detailed below. The option +@t{SH_GLOB} prevents bare parentheses from being used in this way, though +the @t{KSH_GLOB} option is still available. + +@noindent +Note that grouping cannot extend over multiple directories: it is an error +to have a `@t{/}' within a group (this only applies for patterns used in +filename generation). There is one exception: a group of the form +@t{(}@var{pat}@t{/)#} appearing as a complete path segment can +match a sequence of directories. For example, @t{foo/(a*/)#bar} matches +@t{foo/bar}, @t{foo/any/bar}, @t{foo/any/anyother/bar}, and so on. + +@item @var{x}@t{|}@var{y} +Matches either @var{x} or @var{y}. +This operator has lower precedence than any other. +The `@t{|}' character +must be within parentheses, to avoid interpretation as a pipeline. +The alternatives are tried in order from left to right. + +@item @t{^}@var{x} +(Requires @t{EXTENDED_GLOB} to be set.) +Matches anything except the pattern @var{x}. +This has a higher precedence than `@t{/}', so `@t{^foo/bar}' +will search directories in `@t{.}' except `@t{./foo}' +for a file named `@t{bar}'. + +@item @var{x}@t{~}@var{y} +(Requires @t{EXTENDED_GLOB} to be set.) +Match anything that matches the pattern @var{x} but does not match @var{y}. +This has lower precedence than any operator except `@t{|}', so +`@t{*/*~foo/bar}' will search for all files in all directories in `@t{.}' +and then exclude `@t{foo/bar}' if there was such a match. +Multiple patterns can be excluded by +`@var{foo}@t{~}@var{bar}@t{~}@var{baz}'. +In the exclusion pattern (@var{y}), `@t{/}' and `@t{.}' are not treated +specially the way they usually are in globbing. + +@item @var{x}@t{#} +(Requires @t{EXTENDED_GLOB} to be set.) +Matches zero or more occurrences of the pattern @var{x}. +This operator has high precedence; `@t{12#}' is equivalent to `@t{1(2#)}', +rather than `@t{(12)#}'. It is an error for an unquoted `@t{#}' to follow +something which cannot be repeated; this includes an empty string, a +pattern already followed by `@t{##}', or parentheses when part of a +@t{KSH_GLOB} pattern (for example, `@t{!(}@var{foo}@t{)#}' is +invalid and must be replaced by +`@t{*(!(}@var{foo}@t{))}'). + +@item @var{x}@t{##} +(Requires @t{EXTENDED_GLOB} to be set.) +Matches one or more occurrences of the pattern @var{x}. +This operator has high precedence; `@t{12##}' is equivalent to `@t{1(2##)}', +rather than `@t{(12)##}'. No more than two active `@t{#}' characters may +appear together. (Note the potential clash with glob qualifiers in the +form `@t{1(2##)}' which should therefore be avoided.) + +@end table + +@subsection ksh-like Glob Operators +@noindent +@pindex KSH_GLOB, use of +If the @t{KSH_GLOB} option is set, the effects of parentheses can be +modified by a preceding `@t{@@}', `@t{*}', `@t{+}', `@t{?}' or `@t{!}'. +This character need not be unquoted to have special effects, +but the `@t{(}' must be. + +@noindent +@table @asis +@item @t{@@(}...@t{)} +Match the pattern in the parentheses. (Like `@t{(}...@t{)}'.) + +@item @t{*(}...@t{)} +Match any number of occurrences. (Like `@t{(}...@t{)#}', +except that recursive directory searching is not supported.) + +@item @t{+(}...@t{)} +Match at least one occurrence. (Like `@t{(}...@t{)##}', +except that recursive directory searching is not supported.) + +@item @t{?(}...@t{)} +Match zero or one occurrence. (Like `@t{(|}...@t{)}'.) + +@item @t{!(}...@t{)} +Match anything but the expression in parentheses. +(Like `@t{(^(}...@t{))}'.) + +@end table + +@subsection Precedence +@noindent +@cindex precedence of glob operators +The precedence of the operators given above is (highest) `@t{^}', `@t{/}', +`@t{~}', `@t{|}' (lowest); the +remaining operators are simply treated from left to right as part of a +string, with `@t{#}' and `@t{##}' applying to the shortest possible +preceding unit (i.e. a character, `@t{?}', `@t{[}...@t{]}', +`@t{<}...@t{>}', or a parenthesised expression). As mentioned +above, a `@t{/}' used as a directory separator may not appear inside +parentheses, while a `@t{|}' must do so; in patterns used in other contexts +than filename generation (for example, in @t{case} statements and tests +within `@t{[[}...@t{]]}'), a `@t{/}' is not special; and `@t{/}' is also +not special after a `@t{~}' appearing outside parentheses in a filename +pattern. + +@subsection Globbing Flags +@noindent +There are various flags which affect any text to their right up to the +end of the enclosing group or to the end of the pattern; they require +the @t{EXTENDED_GLOB} option. All take the form +@t{(#}@var{X}@t{)} where @var{X} may have one of the following +forms: + +@noindent +@table @asis +@item @t{i} +Case insensitive: upper or lower case characters in the pattern match +upper or lower case characters. + +@item @t{l} +Lower case characters in the pattern match upper or lower case +characters; upper case characters in the pattern still only match +upper case characters. + +@item @t{I} +Case sensitive: locally negates the effect of @t{i} or @t{l} from +that point on. + +@vindex match +@vindex mbegin +@vindex mend +@item @t{b} +Activate backreferences for parenthesised groups in the pattern; +this does not work in filename generation. When a pattern with a set of +active parentheses is matched, the strings matched by the groups are +stored in the array @t{$match}, the indices of the beginning of the matched +parentheses in the array @t{$mbegin}, and the indices of the end in the array +@t{$mend}, with the first element of each array corresponding to the first +parenthesised group, and so on. These arrays are not otherwise special to +the shell. The indices use the same convention as does parameter +substitution, so that elements of @t{$mend} and @t{$mbegin} may be used in +subscripts; the @t{KSH_ARRAYS} option is respected. Sets of globbing flags +are not considered parenthesised groups; only the first nine active +parentheses can be referenced. + +@noindent +For example, + +@noindent +@example +foo="a_string_with_a_message" +if [[ $foo = (a|an)_(#b)(*) ]]; then + print $@{foo[$mbegin[1],$mend[1]]@} +fi +@end example + +@noindent +prints `@t{string_with_a_message}'. +Note that the first set of parentheses is before the +@t{(#b)} and does not create a backreference. + +@noindent +Backreferences work with all forms of pattern matching other than filename +generation, but note that when performing matches on an entire array, such +as @t{$@{}@var{array}@t{#}@var{pattern}@t{@}}, or a global substitution, such +as @t{$@{}@var{param}@t{//}@var{pat}@t{/}@var{repl}@t{@}}, only the data for the +last match remains available. In the case of global replacements this may +still be useful. See the example for the @t{m} flag below. + +@noindent +The numbering of backreferences strictly follows the order of the opening +parentheses from left to right in the pattern string, although sets of +parentheses may be nested. There are special rules for parentheses followed +by `@t{#}' or `@t{##}'. Only the last match of the parenthesis is +remembered: for example, in `@t{[[ abab = (#b)([ab])# ]]}', only the final +`@t{b}' is stored in @t{match[1]}. Thus extra parentheses may be necessary +to match the complete segment: for example, use +`@t{X((ab|cd)#)Y}' to match +a whole string of either `@t{ab}' or `@t{cd}' between `@t{X}' and `@t{Y}', +using the value of @t{$match[1]} rather than @t{$match[2]}. + +@noindent +If the match fails none of the parameters is altered, so in some cases it +may be necessary to initialise them beforehand. If some of the +backreferences fail to match --- which happens if they are in an alternate +branch which fails to match, or if they are followed by @t{#} and matched +zero times --- then the matched string is set to the empty string, and the +start and end indices are set to -1. + +@noindent +Pattern matching with backreferences is slightly slower than without. + +@item @t{B} +Deactivate backreferences, negating the effect of the @t{b} flag from that +point on. + +@item @t{c}@var{N}@t{,}@var{M} +The flag @t{(#c}@var{N}@t{,}@var{M}@t{)} can be used anywhere +that the @t{#} or @t{##} operators can be used except in the expressions +`@t{(*/)#}' and `@t{(*/)##}' in filename generation, where `@t{/}' +has special meaning; it cannot be combined with other globbing flags and +a bad pattern error occurs if it is misplaced. It is equivalent to the +form @t{@{}@var{N}@t{,}@var{M}@t{@}} in regular expressions. The previous +character or group is required to match between @var{N} and @var{M} times, +inclusive. The form @t{(#c}@var{N}@t{)} requires exactly @t{N} +matches; @t{(#c,}@var{M}@t{)} is equivalent to specifying @var{N} +as 0; @t{(#c}@var{N}@t{,)} specifies that there is no maximum +limit on the number of matches. + +@vindex MATCH +@vindex MBEGIN +@vindex MEND +@item @t{m} +Set references to the match data for the entire string matched; this is +similar to backreferencing and does not work in filename generation. The +flag must be in effect at the end of the pattern, i.e. not local to a +group. The parameters @t{$MATCH}, @t{$MBEGIN} and @t{$MEND} will be set to +the string matched and to the indices of the beginning and end of the +string, respectively. This is most useful in parameter substitutions, as +otherwise the string matched is obvious. + +@noindent +For example, + +@noindent +@example +arr=(veldt jynx grimps waqf zho buck) +print $@{arr//(#m)[aeiou]/$@{(U)MATCH@}@} +@end example + +@noindent +forces all the matches (i.e. all vowels) into uppercase, printing +`@t{vEldt jynx grImps wAqf zhO bUck}'. + +@noindent +Unlike backreferences, there is no speed penalty for using match +references, other than the extra substitutions required for the +replacement strings in cases such as the example shown. + +@item @t{M} +Deactivate the @t{m} flag, hence no references to match data will be +created. + +@item @t{a}@var{num} +Approximate matching: @var{num} errors are allowed in the string matched by +the pattern. The rules for this are described in the next subsection. + +@item @t{s}, @t{e} +Unlike the other flags, these have only a local effect, and each must +appear on its own: `@t{(#s)}' and `@t{(#e)}' are the only valid forms. +The `@t{(#s)}' flag succeeds only at the start of the test string, and the +`@t{(#e)}' flag succeeds only at the end of the test string; they +correspond to `@t{^}' and `@t{$}' in standard regular expressions. They +are useful for matching path segments in patterns other than those in +filename generation (where path segments are in any case treated +separately). For example, `@t{*((#s)|/)test((#e)|/)*}' matches +a path segment `@t{test}' in any of the following strings: @t{test}, +@t{test/at/start}, @t{at/end/test}, @t{in/test/middle}. + +@noindent +Another use is in parameter substitution; for example +`@t{$@{array/(#s)A*Z(#e)@}}' will remove only elements of an +array which +match the complete pattern `@t{A*Z}'. There are other ways of performing +many operations of this type, however the combination of the substitution +operations `@t{/}' and `@t{//}' with the `@t{(#s)}' and `@t{(#e)}' flags +provides a single simple and memorable method. + +@noindent +Note that assertions of the form `@t{(^(#s))}' also work, i.e. match +anywhere except at the start of the string, although this actually means +`anything except a zero-length portion at the start of the string'; you +need to use `@t{(""~(#s))}' to match a zero-length portion of the string +not at the start. + +@item @t{q} +A `@t{q}' and everything up to the closing parenthesis of the globbing +flags are ignored by the pattern matching code. This is intended to +support the use of glob qualifiers, see below. The result is that +the pattern `@t{(#b)(*).c(#q.)}' can be used both for globbing +and for +matching against a string. In the former case, the `@t{(#q.)}' will be +treated as a glob qualifier and the `@t{(#b)}' will not be useful, while in +the latter case the `@t{(#b)}' is useful for backreferences and the +`@t{(#q.)}' will be ignored. Note that colon modifiers in the glob +qualifiers are also not applied in ordinary pattern matching. + +@item @t{u} +Respect the current locale in determining the presence of multibyte +characters in a pattern, provided the shell was compiled with +@t{MULTIBYTE_SUPPORT}. This overrides the @t{MULTIBYTE} +option; the default behaviour is taken from the option. Compare @t{U}. +(Mnemonic: typically multibyte characters are from Unicode in the UTF-8 +encoding, although any extension of ASCII supported by the system +library may be used.) + +@item @t{U} +All characters are considered to be a single byte long. The opposite +of @t{u}. This overrides the @t{MULTIBYTE} option. + +@end table + +@noindent +For example, the test string @t{fooxx} can be matched by the pattern +@t{(#i}@t{)FOOXX}, but not by @t{(#l}@t{)FOOXX}, +@t{(#i}@t{)FOO}@t{(#I}@t{)XX} or +@t{((#i}@t{)FOOX}@t{)X}. The string +@t{(#ia2}@t{)readme} specifies case-insensitive matching of +@t{readme} with up to two errors. + +@noindent +When using the ksh syntax for grouping both @t{KSH_GLOB} and +@t{EXTENDED_GLOB} must be set and the left parenthesis should be +preceded by @t{@@}. Note also that the flags do not affect letters +inside @t{[}...@t{]} groups, in other words @t{(#i}@t{)[a-z]} +still matches only lowercase letters. Finally, note that when +examining whole paths case-insensitively every directory must be +searched for all files which match, so that a pattern of the form +@t{(#i}@t{)/foo/bar/...} is potentially slow. + +@noindent + +@subsection Approximate Matching +@noindent +When matching approximately, the shell keeps a count of the errors found, +which cannot exceed the number specified in the +@t{(#a}@var{num}@t{)} flags. Four types of error are recognised: + +@noindent +@table @asis +@item 1. +Different characters, as in @t{fooxbar} and @t{fooybar}. + +@item 2. +Transposition of characters, as in @t{banana} and @t{abnana}. + +@item 3. +A character missing in the target string, as with the pattern @t{road} and +target string @t{rod}. + +@item 4. +An extra character appearing in the target string, as with @t{stove} +and @t{strove}. + +@end table + +@noindent +Thus, the pattern @t{(#a3}@t{)abcd} matches @t{dcba}, with the +errors occurring by using the first rule twice and the second once, +grouping the string as @t{[d][cb][a]} and @t{[a][bc][d]}. + +@noindent +Non-literal parts of the pattern must match exactly, including characters +in character ranges: hence @t{(#a1}@t{)???} matches strings of +length four, by applying rule 4 to an empty part of the pattern, but not +strings of length two, since all the @t{?} must match. Other characters +which must match exactly are initial dots in filenames (unless the +@t{GLOB_DOTS} option is set), and all slashes in filenames, so that +@t{a/bc} is two errors from @t{ab/c} (the slash cannot be transposed with +another character). Similarly, errors are counted separately for +non-contiguous strings in the pattern, so that @t{(ab|cd}@t{)ef} +is two errors from @t{aebf}. + +@noindent +When using exclusion via the @t{~} operator, approximate matching is +treated entirely separately for the excluded part and must be activated +separately. Thus, @t{(#a1}@t{)README~READ_ME} matches +@t{READ.ME} but not @t{READ_ME}, as the trailing @t{READ_ME} is matched +without approximation. However, +@t{(#a1}@t{)README~(#a1}@t{)READ_ME} +does not match any pattern of the form @t{READ}@var{?}@t{ME} as all +such forms are now excluded. + +@noindent +Apart from exclusions, there is only one overall error count; however, the +maximum errors allowed may be altered locally, and this can be delimited by +grouping. For example, +@t{(#a1}@t{)cat}@t{((#a0}@t{)dog}@t{)fox} +allows one error in total, which may not occur in the @t{dog} section, and +the pattern +@t{(#a1}@t{)cat}@t{(#a0}@t{)dog}@t{(#a1}@t{)fox} +is equivalent. Note that the point at which an error is first found is the +crucial one for establishing whether to use approximation; for example, +@t{(#a1)abc(#a0)xyz} will not match @t{abcdxyz}, because the +error occurs at the `@t{x}', where approximation is turned off. + +@noindent +Entire path segments may be matched approximately, so that +`@t{(#a1)/foo/d/is/available/at/the/bar}' allows one error in any path +segment. This is much less efficient than without the @t{(#a1)}, however, +since every directory in the path must be scanned for a possible +approximate match. It is best to place the @t{(#a1)} after any path +segments which are known to be correct. + +@noindent + +@subsection Recursive Globbing +@noindent +A pathname component of the form `@t{(}@var{foo}@t{/)#}' +matches a path consisting of zero or more directories +matching the pattern @var{foo}. + +@noindent +As a shorthand, `@t{**/}' is equivalent to `@t{(*/)#}'; note that this +therefore matches files in the current directory as well as +subdirectories. +Thus: + +@noindent +@example +ls -ld -- (*/)#bar +@end example + +@noindent +or + +@noindent +@example +ls -ld -- **/bar +@end example + +@noindent +does a recursive directory search for files named `@t{bar}' (potentially +including the file `@t{bar}' in the current directory). This form does not +follow symbolic links; the alternative form `@t{***/}' does, but is +otherwise identical. Neither of these can be combined with other forms of +globbing within the same path segment; in that case, the `@t{*}' +operators revert to their usual effect. + +@noindent +Even shorter forms are available when the option @t{GLOB_STAR_SHORT} is +set. In that case if no @t{/} immediately follows a @t{**} or @t{***} +they are treated as if both a @t{/} plus a further @t{*} are present. +Hence: + +@noindent +@example +setopt GLOBSTARSHORT +ls -ld -- **.c +@end example + +@noindent +is equivalent to + +@noindent +@example +ls -ld -- **/*.c +@end example + +@subsection Glob Qualifiers +@noindent +@cindex globbing, qualifiers +@cindex qualifiers, globbing +Patterns used for filename generation may end in a +list of qualifiers enclosed in parentheses. +The qualifiers specify which filenames that otherwise match the given pattern +will be inserted in the argument list. + +@noindent +@pindex BARE_GLOB_QUAL, use of +If the option @t{BARE_GLOB_QUAL} is set, then a trailing set of parentheses +containing no `@t{|}' or `@t{(}' characters (or `@t{~}' if it is special) +is taken as a set of +glob qualifiers. A glob subexpression that would normally be taken as glob +qualifiers, for example `@t{(^x)}', can be forced to be treated as part of +the glob pattern by doubling the parentheses, in this case producing +`@t{((^x))}'. + +@noindent +If the option @t{EXTENDED_GLOB} is set, a different syntax for glob +qualifiers is available, namely `@t{(#q}@var{x}@t{)}' +where @var{x} is any of the same +glob qualifiers used in the other format. The qualifiers must still appear +at the end of the pattern. However, with this syntax multiple glob +qualifiers may be chained together. They are treated as a logical AND of +the individual sets of flags. Also, as the syntax is unambiguous, the +expression will be treated as glob qualifiers just as long any parentheses +contained within it are balanced; appearance of `@t{|}', `@t{(}' or +`@t{~}' does not negate the effect. Note that qualifiers will be +recognised in this form even if a bare glob qualifier exists at the end of +the pattern, for example `@t{*(#q*)(.)}' will recognise executable regular +files if both options are set; however, mixed syntax should probably be +avoided for the sake of clarity. Note that within conditions using the +`@t{[[}' form the presence of a parenthesised expression +@t{(#q}@var{...}@t{)} at the end of a string indicates that globbing +should be performed; the expression may include glob qualifiers, but +it is also valid if it is simply @t{(#q)}. This does +not apply to the right hand side of pattern match operators as the +syntax already has special significance. + +@noindent +A qualifier may be any one of the following: + +@noindent +@table @asis +@item @t{/} +directories + +@item @t{F} +`full' (i.e. non-empty) directories. Note that the +opposite sense @t{(^F}@t{)} expands to empty directories +and all non-directories. Use @t{(/^F}@t{)} for +empty directories. + +@item @t{.} +plain files + +@item @t{@@} +symbolic links + +@item @t{=} +sockets + +@item @t{p} +named pipes (FIFOs) + +@item @t{*} +executable plain files (0100 or 0010 or 0001) + +@item @t{%} +device files (character or block special) + +@item @t{%b} +block special files + +@item @t{%c} +character special files + +@item @t{r} +owner-readable files (0400) + +@item @t{w} +owner-writable files (0200) + +@item @t{x} +owner-executable files (0100) + +@item @t{A} +group-readable files (0040) + +@item @t{I} +group-writable files (0020) + +@item @t{E} +group-executable files (0010) + +@item @t{R} +world-readable files (0004) + +@item @t{W} +world-writable files (0002) + +@item @t{X} +world-executable files (0001) + +@item @t{s} +setuid files (04000) + +@item @t{S} +setgid files (02000) + +@item @t{t} +files with the sticky bit (01000) + +@item @t{f}@var{spec} +files with access rights matching @var{spec}. This @var{spec} may be a +octal number optionally preceded by a `@t{=}', a `@t{+}', or a +`@t{-}'. If none of these characters is given, the behavior is the +same as for `@t{=}'. The octal number describes the mode bits to be +expected, if combined with a `@t{=}', the value given must match the +file-modes exactly, with a `@t{+}', at least the bits in the +given number must be set in the file-modes, and with a `@t{-}', the +bits in the number must not be set. Giving a `@t{?}' instead of a +octal digit anywhere in the number ensures that the corresponding bits +in the file-modes are not checked, this is only useful in combination +with `@t{=}'. + +@noindent +If the qualifier `@t{f}' is followed by any other character anything +up to the next matching character (`@t{[}', `@t{@{}', and `@t{<}' match +`@t{]}', `@t{@}}', and `@t{>}' respectively, any other character +matches itself) is taken as a list of comma-separated +@var{sub-spec}s. Each @var{sub-spec} may be either an octal number as +described above or a list of any of the characters `@t{u}', `@t{g}', +`@t{o}', and `@t{a}', followed by a `@t{=}', a `@t{+}', or a +`@t{-}', followed by a list of any of the characters `@t{r}', `@t{w}', +`@t{x}', `@t{s}', and `@t{t}', or an octal digit. The first list of +characters specify which access rights are to be checked. If a `@t{u}' +is given, those for the owner of the file are used, if a `@t{g}' is +given, those of the group are checked, a `@t{o}' means to test those +of other users, and the `@t{a}' says to test all three groups. The +`@t{=}', `@t{+}', and `@t{-}' again says how the modes are to be +checked and have the same meaning as described for the first form +above. The second list of characters finally says which access rights +are to be expected: `@t{r}' for read access, `@t{w}' for write access, +`@t{x}' for the right to execute the file (or to search a directory), +`@t{s}' for the setuid and setgid bits, and `@t{t}' for the sticky +bit. + +@noindent +Thus, `@t{*(f70?)}' gives the files for which the owner has read, +write, and execute permission, and for which other group members have +no rights, independent of the permissions for other users. The pattern +`@t{*(f-100)}' gives all files for which the owner does not have +execute permission, and `@t{*(f:gu+w,o-rx:)}' gives the files for which +the owner and the other members of the group have at least write +permission, and for which other users don't have read or execute +permission. + +@item @t{e}@var{string} +@itemx @t{+}@var{cmd} +The @var{string} will be executed as shell code. The filename will be +included in the list if and only if the code returns a zero status (usually +the status of the last command). + +@noindent +In the first form, the first character after the `@t{e}' +will be used as a separator and anything up to the next matching separator +will be taken as the @var{string}; `@t{[}', `@t{@{}', and `@t{<}' match +`@t{]}', `@t{@}}', and `@t{>}', respectively, while any other character +matches itself. Note that expansions must be quoted in the @var{string} +to prevent them from being expanded before globbing is done. +@var{string} is then executed as shell code. The string @t{globqual} +is appended to the array @t{zsh_eval_context} the duration of +execution. + +@noindent +@vindex REPLY, use of +@vindex reply, use of +During the execution of @var{string} the filename currently being tested is +available in the parameter @t{REPLY}; the parameter may be altered to +a string to be inserted into the list instead of the original +filename. In addition, the parameter @t{reply} may be set to an array or a +string, which overrides the value of @t{REPLY}. If set to an array, the +latter is inserted into the command line word by word. + +@noindent +For example, suppose a directory contains a single file `@t{lonely}'. Then +the expression `@t{*(e:'reply=($@{REPLY@}@{1,2@})':)}' will cause the words +`@t{lonely1}' and `@t{lonely2}' to be inserted into the command line. Note +the quoting of @var{string}. + +@noindent +The form @t{+}@var{cmd} has the same effect, but no delimiters appear +around @var{cmd}. Instead, @var{cmd} is taken as the longest sequence of +characters following the @t{+} that are alphanumeric or underscore. +Typically @var{cmd} will be the name of a shell function that contains the +appropriate test. For example, + +@noindent +@example +nt() @{ [[ $REPLY -nt $NTREF ]] @} +NTREF=reffile +ls -ld -- *(+nt) +@end example + +@noindent +lists all files in the directory that have been modified more recently than +@t{reffile}. + +@item @t{d}@var{dev} +files on the device @var{dev} + +@item @t{l}[@t{-}|@t{+}]@var{ct} +files having a link count less than @var{ct} (@t{-}), greater than +@var{ct} (@t{+}), or equal to @var{ct} + +@item @t{U} +files owned by the effective user ID + +@item @t{G} +files owned by the effective group ID + +@item @t{u}@var{id} +files owned by user ID @var{id} if that is a number. Otherwise, +@var{id} specifies a user name: the +character after the `@t{u}' will be taken as a separator and the string +between it and the next matching separator will be taken as a user name. +The starting separators `@t{[}', `@t{@{}', and `@t{<}' +match the final separators `@t{]}', `@t{@}}', and `@t{>}', respectively; +any other character matches itself. The selected files are those +owned by this user. For example, `@t{u:foo:}' or `@t{u[foo]}' selects +files owned by user `@t{foo}'. + +@item @t{g}@var{id} +like @t{u}@var{id} but with group IDs or names + +@item @t{a}[@t{Mwhms}][@t{-}|@t{+}]@var{n} +files accessed exactly @var{n} days ago. Files accessed within the last +@var{n} days are selected using a negative value for @var{n} (@t{-}@var{n}). +Files accessed more than @var{n} days ago are selected by a positive @var{n} +value (@t{+}@var{n}). Optional unit specifiers `@t{M}', `@t{w}', +`@t{h}', `@t{m}' or `@t{s}' (e.g. `@t{ah5}') cause the check to be +performed with months (of 30 days), weeks, hours, minutes or seconds +instead of days, respectively. An explicit `@t{d}' for days is also +allowed. + +@noindent +Any fractional part of the difference between the access time and the +current part in the appropriate units is ignored in the comparison. For +instance, `@t{echo *(ah-5)}' would echo files accessed within the last +five hours, while `@t{echo *(ah+5)}' would echo files accessed at least +six hours ago, as times strictly between five and six hours are treated +as five hours. + +@item @t{m}[@t{Mwhms}][@t{-}|@t{+}]@var{n} +like the file access qualifier, except that it uses the file modification +time. + +@item @t{c}[@t{Mwhms}][@t{-}|@t{+}]@var{n} +like the file access qualifier, except that it uses the file inode change +time. + +@item @t{L}[@t{+}|@t{-}]@var{n} +files less than @var{n} bytes (@t{-}), more than @var{n} bytes (@t{+}), or +exactly @var{n} bytes in length. + +@noindent +If this flag is directly followed by a @emph{size specifier} `@t{k}' (`@t{K}'), +`@t{m}' (`@t{M}'), or `@t{p}' (`@t{P}') (e.g. `@t{Lk-50}') the check is +performed with kilobytes, megabytes, or blocks (of 512 bytes) instead. +(On some systems additional specifiers are available for gigabytes, +`@t{g}' or `@t{G}', and terabytes, `@t{t}' or `@t{T}'.) If a size specifier +is used a file is regarded as "exactly" the size if the file size rounded up +to the next unit is equal to the test size. Hence `@t{*(Lm1)}' +matches files from 1 byte up to 1 Megabyte inclusive. Note also that +the set of files "less than" the test size only includes files that would +not match the equality test; hence `@t{*(Lm-1)}' only matches +files of zero size. + +@item @t{^} +negates all qualifiers following it + +@item @t{-} +toggles between making the qualifiers work on symbolic links (the +default) and the files they point to + +@item @t{M} +sets the @t{MARK_DIRS} option for the current pattern +@pindex MARK_DIRS, setting in pattern + +@item @t{T} +appends a trailing qualifier mark to the filenames, analogous to the +@t{LIST_TYPES} option, for the current pattern (overrides @t{M}) + +@item @t{N} +sets the @t{NULL_GLOB} option for the current pattern +@pindex NULL_GLOB, setting in pattern + +@item @t{D} +sets the @t{GLOB_DOTS} option for the current pattern +@pindex GLOB_DOTS, setting in pattern + +@item @t{n} +sets the @t{NUMERIC_GLOB_SORT} option for the current pattern +@pindex NUMERIC_GLOB_SORT, setting in pattern + +@item @t{Y}@var{n} +enables short-circuit mode: the pattern will expand to at most @var{n} +filenames. If more than @var{n} matches exist, only the first @var{n} +matches in directory traversal order will be considered. + +@noindent +Implies @t{oN} when no @t{o}@var{c} qualifier is used. + +@item @t{o}@var{c} +specifies how the names of the files should be sorted. If @var{c} is +@t{n} they are sorted by name; if it is @t{L} they +are sorted depending on the size (length) of the files; if @t{l} +they are sorted by the number of links; if @t{a}, @t{m}, or @t{c} +they are sorted by the time of the last access, modification, or +inode change respectively; if @t{d}, files in subdirectories appear before +those in the current directory at each level of the search --- this is best +combined with other criteria, for example `@t{odon}' to sort on names for +files within the same directory; if @t{N}, no sorting is performed. +Note that @t{a}, @t{m}, and @t{c} compare +the age against the current time, hence the first name in the list is the +youngest file. Also note that the modifiers @t{^} and @t{-} are used, +so `@t{*(^-oL)}' gives a list of all files sorted by file size in descending +order, following any symbolic links. Unless @t{oN} is used, multiple order +specifiers may occur to resolve ties. + +@noindent +The default sorting is @t{n} (by name) unless the @t{Y} glob qualifier is used, +in which case it is @t{N} (unsorted). + +@noindent +@t{oe} and @t{o+} are special cases; they are each followed by shell code, +delimited as for the @t{e} glob qualifier and the @t{+} glob qualifier +respectively (see above). The code is executed for each matched file with +the parameter @t{REPLY} set to the name of the file on entry and +@t{globsort} appended to @t{zsh_eval_context}. The code +should modify the parameter @t{REPLY} in some fashion. On return, the +value of the parameter is used instead of the file name as the string on +which to sort. Unlike other sort operators, @t{oe} and @t{o+} may be +repeated, but note that the maximum number of sort operators of any kind +that may appear in any glob expression is 12. + +@item @t{O}@var{c} +like `@t{o}', but sorts in descending order; i.e. `@t{*(^oc)}' is the +same as `@t{*(Oc)}' and `@t{*(^Oc)}' is the same as `@t{*(oc)}'; `@t{Od}' +puts files in the current directory before those in subdirectories at each +level of the search. + +@item @t{[}@var{beg}[@t{,}@var{end}]@t{]} +specifies which of the matched filenames should be included in the +returned list. The syntax is the same as for array +subscripts. @var{beg} and the optional @var{end} may be mathematical +expressions. As in parameter subscripting they may be negative to make +them count from the last match backward. E.g.: `@t{*(-OL[1,3])}' +gives a list of the names of the three largest files. + +@item @t{P}@var{string} +The @var{string} will be prepended to each glob match as a separate +word. @var{string} is delimited in the same way as arguments to the +@t{e} glob qualifier described above. The qualifier can be repeated; +the words are prepended separately so that the resulting command +line contains the words in the same order they were given in the +list of glob qualifiers. + +@noindent +A typical use for this is to prepend an option before all occurrences +of a file name; for example, the pattern `@t{*(P:-f:)}' produces the +command line arguments `@t{-f} @var{file1} @t{-f} @var{file2} ...' + +@noindent +If the modifier @t{^} is active, then @var{string} will be appended +instead of prepended. Prepending and appending is done independently +so both can be used on the same glob expression; for example by writing +`@t{*(P:foo:^P:bar:^P:baz:)}' which produces the command line arguments +`@t{foo} @t{baz} @var{file1} @t{bar} ...' + +@end table + +@noindent +More than one of these lists can be combined, separated by commas. The +whole list matches if at least one of the sublists matches (they are +`or'ed, the qualifiers in the sublists are `and'ed). Some qualifiers, +however, affect all matches generated, independent of the sublist in +which they are given. These are the qualifiers `@t{M}', `@t{T}', +`@t{N}', `@t{D}', `@t{n}', `@t{o}', `@t{O}' and the subscripts given +in brackets (`@t{[}@var{...}@t{]}'). + +@noindent +If a `@t{:}' appears in a qualifier list, the remainder of the expression in +parenthesis is interpreted as a modifier (see @ref{Modifiers} +in @ref{History Expansion}). Each modifier must be introduced by a +separate `@t{:}'. Note also that the result after modification does not +have to be an existing file. The name of any existing file can be followed +by a modifier of the form `@t{(:}@var{...}@t{)}' +even if no actual filename generation +is performed, although note that the presence of the parentheses +causes the entire expression to be subjected to any global pattern matching +options such as @t{NULL_GLOB}. Thus: + +@noindent +@example +ls -ld -- *(-/) +@end example + +@noindent +lists all directories and symbolic links that point to directories, +and + +@noindent +@example +ls -ld -- *(-@@) +@end example + +@noindent +lists all broken symbolic links, and + +@noindent +@example +ls -ld -- *(%W) +@end example + +@noindent +lists all world-writable device files in the current directory, and + +@noindent +@example +ls -ld -- *(W,X) +@end example + +@noindent +lists all files in the current directory that are +world-writable or world-executable, and + +@noindent +@example +print -rC1 /tmp/foo*(u0^@@:t) +@end example + +@noindent +outputs the basename of all root-owned files beginning with the string +`@t{foo}' in @t{/tmp}, ignoring symlinks, and + +@noindent +@example +ls -ld -- *.*~(lex|parse).[ch](^D^l1) +@end example + +@noindent +lists all files having a link count of one whose names contain a dot +(but not those starting with a dot, since @t{GLOB_DOTS} is explicitly +switched off) except for @t{lex.c}, @t{lex.h}, @t{parse.c} and @t{parse.h}. + +@noindent +@example +print -rC1 b*.pro(#q:s/pro/shmo/)(#q.:s/builtin/shmiltin/) +@end example + +@noindent +demonstrates how colon modifiers and other qualifiers may be chained +together. The ordinary qualifier `@t{.}' is applied first, then the colon +modifiers in order from left to right. So if @t{EXTENDED_GLOB} is set and +the base pattern matches the regular file @t{builtin.pro}, the shell will +print `@t{shmiltin.shmo}'. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/params.yo +@node Parameters, Options, Expansion, Top + +@chapter Parameters +@noindent +@cindex parameters +@cindex variables + +@section Description +@noindent +A parameter has a name, a value, and a number of attributes. +A name may be any sequence of alphanumeric +characters and underscores, or the single characters +`@t{*}', `@t{@@}', `@t{#}', `@t{?}', `@t{-}', `@t{$}', or `@t{!}'. +A parameter whose name begins with an alphanumeric or underscore is also +referred to as a @emph{variable}. + +@noindent +@cindex scalar +@cindex parameters, scalar +@cindex parameters, array +@cindex parameters, associative array +@cindex hash +The attributes of a parameter determine the @emph{type} of its value, often +referred to as the parameter type or variable type, and also control +other processing that may be applied to the value when it is referenced. +The value type may be a @emph{scalar} (a string, an integer, or a floating +point number), an array (indexed numerically), or an @emph{associative} +array (an unordered set of name-value pairs, indexed by name, also +referred to as a @emph{hash}). + +@noindent +@cindex export +@cindex environment +@cindex environment variables +@cindex variables, environment +Named scalar parameters may have the @emph{exported}, @t{-x}, attribute, to +copy them into the process environment, which is then passed from the +shell to any new processes that it starts. Exported parameters are called +@emph{environment variables}. The shell also @emph{imports} environment variables +at startup time and automatically marks the corresponding parameters as +exported. Some environment variables are not imported for reasons of +security or because they would interfere with the correct operation of +other shell features. + +@noindent +@cindex special parameters +@cindex parameters, special +Parameters may also be @emph{special}, that is, they have a predetermined +meaning to the shell. Special parameters cannot have their type changed +or their readonly attribute turned off, and if a special parameter is +unset, then later recreated, the special properties will be retained. + +@noindent +To declare the type of a parameter, or to assign a string or numeric value +to a scalar parameter, use the @t{typeset} builtin. +@findex typeset, use of + +@noindent +The value of a scalar parameter may also be assigned by writing: +@cindex assignment + +@quotation +@var{name}@t{=}@var{value} +@end quotation + +@noindent +In scalar assignment, @var{value} is expanded as a single string, in +which the elements of arrays are joined together; filename expansion is +not performed unless the option @t{GLOB_ASSIGN} is set. + +@noindent +When the integer attribute, @t{-i}, or a floating point attribute, @t{-E} +or @t{-F}, is set for @var{name}, the @var{value} is subject to arithmetic +evaluation. Furthermore, by replacing `@t{=}' with `@t{+=}', a parameter +can be incremented or appended to. See @ref{Array Parameters} and +@ref{Arithmetic Evaluation} +for additional forms of assignment. + +@noindent +Note that assignment may implicitly change the attributes of a parameter. +For example, assigning a number to a variable in arithmetic evaluation may +change its type to integer or float, and with @t{GLOB_ASSIGN} assigning a +pattern to a variable may change its type to an array. + +@noindent +To reference the value of a parameter, write `@t{$}@var{name}' or +`@t{$@{}@var{name}@t{@}}'. See +@ref{Parameter Expansion} +for complete details. That section also explains the effect +of the difference between scalar and array assignment on parameter +expansion. +@menu +* Array Parameters:: +* Positional Parameters:: +* Local Parameters:: +* Parameters Set By The Shell:: +* Parameters Used By The Shell:: +@end menu +@node Array Parameters, Positional Parameters, , Parameters + +@section Array Parameters +@noindent +To assign an array value, write one of: +@findex set, use of +@cindex array assignment + +@quotation +@t{set -A} @var{name} @var{value} ... +@end quotation +@quotation +@var{name}@t{=(}@var{value} ...@t{)} +@end quotation +@quotation +@var{name}@t{=(}@t{[}@var{key}@t{]=}@var{value} ...@t{)} +@end quotation + +@noindent +If no parameter @var{name} exists, an ordinary array parameter is created. +If the parameter @var{name} exists and is a scalar, it is replaced by a new +array. + +@noindent +In the third form, @var{key} is an expression that will be evaluated in +arithmetic context (in its simplest form, an integer) that gives the +index of the element to be assigned with @var{value}. In this form any +elements not explicitly mentioned that come before the largest index to +which a value is assigned are assigned an empty string. The indices +may be in any order. Note that this syntax is strict: @t{[} and @t{]=} must +not be quoted, and @var{key} may not consist of the unquoted string +@t{]=}, but is otherwise treated as a simple string. The enhanced forms +of subscript expression that may be used when directly subscripting a +variable name, described in the section Array Subscripts below, are not +available. + +@noindent +The syntaxes with and without the explicit key may be mixed. An implicit +@var{key} is deduced by incrementing the index from the previously +assigned element. Note that it is not treated as an error +if latter assignments in this form overwrite earlier assignments. + +@noindent +For example, assuming the option @t{KSH_ARRAYS} is not set, the following: + +@noindent +@example +array=(one [3]=three four) +@end example + +@noindent +causes the array variable @t{array} to contain four elements @t{one}, +an empty string, @t{three} and @t{four}, in that order. + +@noindent +In the forms where only @var{value} is specified, full command +line expansion is performed. + +@noindent +In the @t{[}@var{key}@t{]=}@var{value} form, +both @var{key} and @var{value} undergo all forms of expansion +allowed for single word shell expansions (this does not include filename +generation); these are as performed by the parameter expansion flag +@t{(e)} as described in +@ref{Parameter Expansion}. +Nested parentheses may surround @var{value} and are included as part of the +value, which is joined into a plain string; this differs from ksh which +allows the values themselves to be arrays. A future version of zsh may +support that. To cause the brackets to be interpreted as a character +class for filename generation, and therefore to treat the resulting list +of files as a set of values, quote the equal sign using any form of quoting. +Example: + +@quotation +@var{name}@t{=(}@t{[a-z]'='*)} +@end quotation + +@noindent +To append to an array without changing the existing values, use +one of the following: + +@quotation +@var{name}@t{+=(}@var{value} ...@t{)} +@end quotation +@quotation +@var{name}@t{+=(}@t{[}@var{key}@t{]=}@var{value} ...@t{)} +@end quotation + +@noindent +In the second form @var{key} may specify an existing index as well as an +index off the end of the old array; any existing value is overwritten by +@var{value}. Also, it is possible to use @t{[}@var{key}@t{]+=}@var{value} +to append to the existing value at that index. + +@noindent +Within the parentheses on the right hand side of either form of the +assignment, newlines and semicolons are treated the same as white space, +separating individual @var{value}s. Any consecutive sequence of such +characters has the same effect. + +@noindent +Ordinary array parameters may also be explicitly declared with: +@findex typeset, use of + +@quotation +@t{typeset -a} @var{name} +@end quotation + +@noindent +Associative arrays @emph{must} be declared before assignment, by using: + +@quotation +@t{typeset -A} @var{name} +@end quotation + +@noindent +When @var{name} refers to an associative array, the list in an assignment +is interpreted as alternating keys and values: + +@quotation +@t{set -A} @var{name} @var{key} @var{value} ... +@end quotation +@quotation +@var{name}@t{=(}@var{key} @var{value} ...@t{)} +@end quotation +@quotation +@var{name}@t{=(}@t{[}@var{key}@t{]=}@var{value} ...@t{)} +@end quotation + +@noindent +Note that only one of the two syntaxes above may be used in any +given assignment; the forms may not be mixed. This is unlike the case +of numerically indexed arrays. + +@noindent +Every @var{key} must have a @var{value} in this case. Note that this +assigns to the entire array, deleting any elements that do not appear in +the list. The append syntax may also be used with an associative array: + +@quotation +@var{name}@t{+=(}@var{key} @var{value} ...@t{)} +@end quotation +@quotation +@var{name}@t{+=(}@t{[}@var{key}@t{]=}@var{value} ...@t{)} +@end quotation + +@noindent +This adds a new key/value pair if the key is not already present, and +replaces the value for the existing key if it is. In the second +form it is also possible to use @t{[}@var{key}@t{]+=}@var{value} to +append to the existing value at that key. Expansion is performed +identically to the corresponding forms for normal arrays, as +described above. + +@noindent +To create an empty array (including associative arrays), use one of: + +@quotation +@t{set -A} @var{name} +@end quotation +@quotation +@var{name}@t{=()} +@end quotation + +@noindent + +@subsection Array Subscripts +@noindent +@cindex subscripts +Individual elements of an array may be selected using a subscript. A +subscript of the form `@t{[}@var{exp}@t{]}' selects the single element +@var{exp}, where @var{exp} is an arithmetic expression which will be subject +to arithmetic expansion as if it were surrounded by +`@t{$((}...@t{))}'. The elements are numbered +beginning with 1, unless the @t{KSH_ARRAYS} option is set in which case +they are numbered from zero. +@pindex KSH_ARRAYS, use of + +@noindent +Subscripts may be used inside braces used to delimit a parameter name, thus +`@t{$@{foo[2]@}}' is equivalent to `@t{$foo[2]}'. If the @t{KSH_ARRAYS} +option is set, the braced form is the only one that works, as bracketed +expressions otherwise are not treated as subscripts. + +@noindent +If the @t{KSH_ARRAYS} option is not set, then by default accesses to +an array element with a subscript that evaluates to zero return an +empty string, while an attempt to write such an element is treated as +an error. For backward compatibility the @t{KSH_ZERO_SUBSCRIPT} +option can be set to cause subscript values 0 and 1 to be equivalent; see +the description of the option in @ref{Description of Options}. + +@noindent +The same subscripting syntax is used for associative arrays, except that +no arithmetic expansion is applied to @var{exp}. However, the parsing +rules for arithmetic expressions still apply, which affects the way that +certain special characters must be protected from interpretation. See +@emph{Subscript Parsing} below for details. + +@noindent +A subscript of the form `@t{[*]}' or `@t{[@@]}' evaluates to all elements +of an array; there is no difference between the two except when they +appear within double quotes. +`@t{"$foo[*]"}' evaluates to `@t{"$foo[1] $foo[2] }...@t{"}', whereas +`@t{"$foo[@@]"}' evaluates to `@t{"$foo[1]" "$foo[2]" }...'. For +associative arrays, `@t{[*]}' or `@t{[@@]}' evaluate to all the values, +in no particular order. Note that this does not substitute +the keys; see the documentation for the `@t{k}' flag under +@ref{Parameter Expansion} +for complete details. +When an array parameter is referenced as `@t{$}@var{name}' (with no +subscript) it evaluates to `@t{$}@var{name}@t{[*]}', unless the @t{KSH_ARRAYS} +option is set in which case it evaluates to `@t{$@{}@var{name}@t{[0]@}}' (for +an associative array, this means the value of the key `@t{0}', which may +not exist even if there are values for other keys). + +@noindent +A subscript of the form `@t{[}@var{exp1}@t{,}@var{exp2}@t{]}' +selects all elements in the range @var{exp1} to @var{exp2}, +inclusive. (Associative arrays are unordered, and so do not support +ranges.) If one of the subscripts evaluates to a negative number, +say @t{-}@var{n}, then the @var{n}th element from the end +of the array is used. Thus `@t{$foo[-3]}' is the third element +from the end of the array @t{foo}, and +`@t{$foo[1,-1]}' is the same as `@t{$foo[*]}'. + +@noindent +Subscripting may also be performed on non-array values, in which +case the subscripts specify a substring to be extracted. +For example, if @t{FOO} is set to `@t{foobar}', then +`@t{echo $FOO[2,5]}' prints `@t{ooba}'. Note that +some forms of subscripting described below perform pattern matching, +and in that case the substring extends from the start of the match +of the first subscript to the end of the match of the second +subscript. For example, + +@noindent +@example +string="abcdefghijklm" +print $@{string[(r)d?,(r)h?]@} +@end example + +@noindent +prints `@t{defghi}'. This is an obvious generalisation of the +rule for single-character matches. For a single subscript, +only a single character is referenced (not the range of characters +covered by the match). + +@noindent +Note that in substring operations the second subscript is handled +differently by the @t{r} and @t{R} subscript flags: the former takes the +shortest match as the length and the latter the longest match. Hence +in the former case a @t{*} at the end is redundant while in +the latter case it matches the whole remainder of the string. This +does not affect the result of the single subscript case as here the +length of the match is irrelevant. + +@noindent + +@subsection Array Element Assignment +@noindent + +@noindent +A subscript may be used on the left side of an assignment like so: + +@quotation +@var{name}@t{[}@var{exp}@t{]=}@var{value} +@end quotation + +@noindent +In this form of assignment the element or range specified by @var{exp} +is replaced by the expression on the right side. An array (but not an +associative array) may be created by assignment to a range or element. +Arrays do not nest, so assigning a parenthesized list of values to an +element or range changes the number of elements in the array, shifting the +other elements to accommodate the new values. (This is not supported for +associative arrays.) + +@noindent +This syntax also works as an argument to the @t{typeset} command: + +@quotation +@t{typeset} @t{"}@var{name}@t{[}@var{exp}@t{]"=}@var{value} +@end quotation + +@noindent +The @var{value} may @emph{not} be a parenthesized list in this case; only +single-element assignments may be made with @t{typeset}. Note that quotes +are necessary in this case to prevent the brackets from being interpreted +as filename generation operators. The @t{noglob} precommand modifier +could be used instead. + +@noindent +To delete an element of an ordinary array, assign `@t{()}' to +that element. To delete an element of an associative array, use the +@t{unset} command: + +@quotation +@t{unset} @t{"}@var{name}@t{[}@var{exp}@t{]"} +@end quotation + +@noindent + +@subsection Subscript Flags +@noindent +@cindex subscript flags +If the opening bracket, or the comma in a range, in any subscript +expression is directly followed by an opening parenthesis, the string up +to the matching closing one is considered to be a list of flags, as in +`@var{name}@t{[(}@var{flags}@t{)}@var{exp}@t{]}'. + +@noindent +The flags @t{s}, @t{n} and @t{b} take an argument; the delimiter +is shown below as `@t{:}', but any character, or the matching pairs +`@t{(}...@t{)}', `@t{@{}...@t{@}}', `@t{[}...@t{]}', or +`@t{<}...@t{>}', may be used, but note that `@t{<}...@t{>}' can only be +used if the subscript is inside a double quoted expression or a +parameter substitution enclosed in braces as otherwise the expression is +interpreted as a redirection. + +@noindent +The flags currently understood are: + +@noindent +@table @asis +@item @t{w} +If the parameter subscripted is a scalar then this flag makes +subscripting work on words instead of characters. The default word +separator is whitespace. When combined with the @t{i} or @t{I} flag, +the effect is to produce the index of the first character of the +first/last word which matches the given pattern; note that a failed +match in this case always yields 0. + +@item @t{s:}@var{string}@t{:} +This gives the @var{string} that separates words (for use with the +@t{w} flag). The delimiter character @t{:} is arbitrary; see above. + +@item @t{p} +Recognize the same escape sequences as the @t{print} builtin in +the string argument of a subsequent `@t{s}' flag. + +@item @t{f} +If the parameter subscripted is a scalar then this flag makes +subscripting work on lines instead of characters, i.e. with elements +separated by newlines. This is a shorthand for `@t{pws:\n:}'. + +@item @t{r} +Reverse subscripting: if this flag is given, the @var{exp} is taken as a +pattern and the result is the first matching array element, substring or +word (if the parameter is an array, if it is a scalar, or if it is a +scalar and the `@t{w}' flag is given, respectively). The subscript used +is the number of the matching element, so that pairs of subscripts such as +`@t{$foo[(r)??,3]}' and `@t{$foo[(r)??,(r)f*]}' are +possible if the parameter is not an associative array. If the +parameter is an associative array, only the value part of each pair is +compared to the pattern, and the result is that value. + +@noindent +If a search through an ordinary array failed, the search sets the +subscript to one past the end of the array, and hence +@t{$@{array[(r)}@var{pattern}@t{]@}} will substitute the empty string. Thus the +success of a search can be tested by using the @t{(i)} flag, for +example (assuming the option @t{KSH_ARRAYS} is not in effect): + +@noindent +@example +[[ $@{array[(i)pattern]@} -le $@{#array@} ]] +@end example + +@noindent +If @t{KSH_ARRAYS} is in effect, the @t{-le} should be replaced by @t{-lt}. + +@item @t{R} +Like `@t{r}', but gives the last match. For associative arrays, gives +all possible matches. May be used for assigning to ordinary array +elements, but not for assigning to associative arrays. On failure, for +normal arrays this has the effect of returning the element corresponding to +subscript 0; this is empty unless one of the options @t{KSH_ARRAYS} or +@t{KSH_ZERO_SUBSCRIPT} is in effect. + +@noindent +Note that in subscripts with both `@t{r}' and `@t{R}' pattern characters +are active even if they were substituted for a parameter (regardless of the +setting of @t{GLOB_SUBST} which controls this feature in normal pattern +matching). The flag `@t{e}' can be added to inhibit pattern matching. As +this flag does not inhibit other forms of substitution, care is still +required; using a parameter to hold the key has the desired effect: + +@noindent +@example +key2='original key' +print $@{array[(Re)$key2]@} +@end example + +@item @t{i} +Like `@t{r}', but gives the index of the match instead; this may not be +combined with a second argument. On the left side of an assignment, +behaves like `@t{r}'. For associative arrays, the key part of each pair +is compared to the pattern, and the first matching key found is the +result. On failure substitutes the length of the array plus one, as +discussed under the description of `@t{r}', or the empty string for an +associative array. + +@item @t{I} +Like `@t{i}', but gives the index of the last match, or all possible +matching keys in an associative array. On failure substitutes 0, or +the empty string for an associative array. This flag is best when +testing for values or keys that do not exist. + +@item @t{k} +If used in a subscript on an associative array, this flag causes the keys +to be interpreted as patterns, and returns the value for the first key +found where @var{exp} is matched by the key. Note this could be any +such key as no ordering of associative arrays is defined. +This flag does not work on the left side of an assignment to an associative +array element. If used on another type of parameter, this behaves like `@t{r}'. + +@item @t{K} +On an associative array this is like `@t{k}' but returns all values where +@var{exp} is matched by the keys. On other types of parameters this has +the same effect as `@t{R}'. + +@item @t{n:}@var{expr}@t{:} +If combined with `@t{r}', `@t{R}', `@t{i}' or `@t{I}', makes them give +the @var{n}th or @var{n}th last match (if @var{expr} evaluates to +@var{n}). This flag is ignored when the array is associative. +The delimiter character @t{:} is arbitrary; see above. + +@item @t{b:}@var{expr}@t{:} +If combined with `@t{r}', `@t{R}', `@t{i}' or `@t{I}', makes them begin +at the @var{n}th or @var{n}th last element, word, or character (if @var{expr} +evaluates to @var{n}). This flag is ignored when the array is associative. +The delimiter character @t{:} is arbitrary; see above. + +@item @t{e} +This flag causes any pattern matching that would be performed on the +subscript to use plain string matching instead. Hence +`@t{$@{array[(re)*]@}}' matches only the array element whose value is @t{*}. +Note that other forms of substitution such as parameter substitution are +not inhibited. + +@noindent +This flag can also be used to force @t{*} or @t{@@} to be interpreted as +a single key rather than as a reference to all values. It may be used +for either purpose on the left side of an assignment. + +@end table + +@noindent +See @emph{Parameter Expansion Flags} (@ref{Parameter Expansion}) for additional ways to manipulate the results of array subscripting. + +@noindent + +@subsection Subscript Parsing +@noindent + +@noindent +This discussion applies mainly to associative array key strings and to +patterns used for reverse subscripting (the `@t{r}', `@t{R}', `@t{i}', +etc. flags), but it may also affect parameter substitutions that appear +as part of an arithmetic expression in an ordinary subscript. + +@noindent +To avoid subscript parsing limitations in assignments to associative array +elements, use the append syntax: + +@noindent +@example +aa+=('key with "*strange*" characters' 'value string') +@end example + +@noindent +The basic rule to remember when writing a subscript expression is that all +text between the opening `@t{[}' and the closing `@t{]}' is interpreted +@emph{as if} it were in double quotes (@ref{Quoting}). However, unlike double quotes which normally cannot nest, subscript +expressions may appear inside double-quoted strings or inside other +subscript expressions (or both!), so the rules have two important +differences. + +@noindent +The first difference is that brackets (`@t{[}' and `@t{]}') must appear as +balanced pairs in a subscript expression unless they are preceded by a +backslash (`@t{\}'). Therefore, within a subscript expression (and unlike +true double-quoting) the sequence `@t{\[}' becomes `@t{[}', and similarly +`@t{\]}' becomes `@t{]}'. This applies even in cases where a backslash is +not normally required; for example, the pattern `@t{[^[]}' (to match any +character other than an open bracket) should be written `@t{[^\[]}' in a +reverse-subscript pattern. However, note that `@t{\[^\[\]}' and even +`@t{\[^[]}' mean the @emph{same} thing, because backslashes are always +stripped when they appear before brackets! + +@noindent +The same rule applies to parentheses (`@t{(}' and `@t{)}') and +braces (`@t{@{}' and `@t{@}}'): they must appear either in balanced pairs or +preceded by a backslash, and backslashes that protect parentheses or +braces are removed during parsing. This is because parameter expansions +may be surrounded by balanced braces, and subscript flags are introduced by +balanced parentheses. + +@noindent +The second difference is that a double-quote (`@t{"}') may appear as part +of a subscript expression without being preceded by a backslash, and +therefore that the two characters `@t{\"}' remain as two characters in the +subscript (in true double-quoting, `@t{\"}' becomes `@t{"}'). However, +because of the standard shell quoting rules, any double-quotes that appear +must occur in balanced pairs unless preceded by a backslash. This makes +it more difficult to write a subscript expression that contains an odd +number of double-quote characters, but the reason for this difference is +so that when a subscript expression appears inside true double-quotes, one +can still write `@t{\"}' (rather than `@t{\\\"}') for `@t{"}'. + +@noindent +To use an odd number of double quotes as a key in an assignment, use the +@t{typeset} builtin and an enclosing pair of double quotes; to refer to +the value of that key, again use double quotes: + +@noindent +@example +typeset -A aa +typeset "aa[one\"two\"three\"quotes]"=QQQ +print "$aa[one\"two\"three\"quotes]" +@end example + +@noindent +It is important to note that the quoting rules do not change when a +parameter expansion with a subscript is nested inside another subscript +expression. That is, it is not necessary to use additional backslashes +within the inner subscript expression; they are removed only once, from +the innermost subscript outwards. Parameters are also expanded from the +innermost subscript first, as each expansion is encountered left to right +in the outer expression. + +@noindent +A further complication arises from a way in which subscript parsing is +@emph{not} different from double quote parsing. As in true double-quoting, +the sequences `@t{\*}', and `@t{\@@}' remain as two characters when they +appear in a subscript expression. To use a literal `@t{*}' or `@t{@@}' as +an associative array key, the `@t{e}' flag must be used: + +@noindent +@example +typeset -A aa +aa[(e)*]=star +print $aa[(e)*] +@end example + +@noindent +A last detail must be considered when reverse subscripting is performed. +Parameters appearing in the subscript expression are first expanded and +then the complete expression is interpreted as a pattern. This has two +effects: first, parameters behave as if @t{GLOB_SUBST} were on (and it +cannot be turned off); second, backslashes are interpreted twice, once +when parsing the array subscript and again when parsing the pattern. In a +reverse subscript, it's necessary to use @emph{four} backslashes to cause a +single backslash to match literally in the pattern. For complex patterns, +it is often easiest to assign the desired pattern to a parameter and then +refer to that parameter in the subscript, because then the backslashes, +brackets, parentheses, etc., are seen only when the complete expression is +converted to a pattern. To match the value of a parameter literally in a +reverse subscript, rather than as a pattern, +use `@t{$@{(q}@t{)}@var{name}@t{@}}' (@ref{Parameter Expansion}) to quote the expanded value. + +@noindent +Note that the `@t{k}' and `@t{K}' flags are reverse subscripting for an +ordinary array, but are @emph{not} reverse subscripting for an associative +array! (For an associative array, the keys in the array itself are +interpreted as patterns by those flags; the subscript is a plain string +in that case.) + +@noindent +One final note, not directly related to subscripting: the numeric names +of positional parameters (@ref{Positional Parameters}) are parsed specially, so for example `@t{$2foo}' is equivalent to +`@t{$@{2@}foo}'. Therefore, to use subscript syntax to extract a substring +from a positional parameter, the expansion must be surrounded by braces; +for example, `@t{$@{2[3,5]@}}' evaluates to the third through fifth +characters of the second positional parameter, but `@t{$2[3,5]}' is the +entire second parameter concatenated with the filename generation pattern +`@t{[3,5]}'. + +@noindent +@node Positional Parameters, Local Parameters, Array Parameters, Parameters + +@section Positional Parameters +@noindent +The positional parameters provide access to the command-line arguments +of a shell function, shell script, or the shell itself; see +@ref{Invocation}, and also @ref{Functions}. +The parameter @var{n}, where @var{n} is a number, +is the @var{n}th positional parameter. +The parameter `@t{$0}' is a special case, see +@ref{Parameters Set By The Shell}. + +@noindent +The parameters @t{*}, @t{@@} and @t{argv} are +arrays containing all the positional parameters; +thus `@t{$argv[}@var{n}@t{]}', etc., is equivalent to simply `@t{$}@var{n}'. +Note that the options @t{KSH_ARRAYS} or @t{KSH_ZERO_SUBSCRIPT} apply +to these arrays as well, so with either of those options set, +`@t{$@{argv[0]@}}' is equivalent to `@t{$1}' and so on. + +@noindent +Positional parameters may be changed after the shell or function starts by +using the @t{set} builtin, by assigning to the @t{argv} array, or by direct +assignment of the form `@var{n}@t{=}@var{value}' where @var{n} is the number of +the positional parameter to be changed. This also creates (with empty +values) any of the positions from 1 to @var{n} that do not already have +values. Note that, because the positional parameters form an array, an +array assignment of the form `@var{n}@t{=(}@var{value} ...@t{)}' is +allowed, and has the effect of shifting all the values at positions greater +than @var{n} by as many positions as necessary to accommodate the new values. + +@noindent +@node Local Parameters, Parameters Set By The Shell, Positional Parameters, Parameters + +@section Local Parameters +@noindent +Shell function executions delimit scopes for shell parameters. +(Parameters are dynamically scoped.) The @t{typeset} builtin, and its +alternative forms @t{declare}, @t{integer}, @t{local} and @t{readonly} +(but not @t{export}), can be used to declare a parameter as being local +to the innermost scope. + +@noindent +When a parameter is read or assigned to, the +innermost existing parameter of that name is used. (That is, the +local parameter hides any less-local parameter.) However, assigning +to a non-existent parameter, or declaring a new parameter with @t{export}, +causes it to be created in the @emph{outer}most scope. + +@noindent +Local parameters disappear when their scope ends. +@t{unset} can be used to delete a parameter while it is still in scope; +any outer parameter of the same name remains hidden. + +@noindent +Special parameters may also be made local; they retain their special +attributes unless either the existing or the newly-created parameter +has the @t{-h} (hide) attribute. This may have unexpected effects: +there is no default value, so if there is no assignment at the +point the variable is made local, it will be set to an empty value (or zero +in the case of integers). +The following: + +@noindent +@example +typeset PATH=/new/directory:$PATH +@end example + +@noindent +is valid for temporarily allowing the shell or programmes called from it to +find the programs in @t{/new/directory} inside a function. + +@noindent +Note that the restriction in older versions of zsh that local parameters +were never exported has been removed. + +@noindent +@node Parameters Set By The Shell, Parameters Used By The Shell, Local Parameters, Parameters + +@section Parameters Set By The Shell +@noindent +In the parameter lists that follow, the mark `<S>' indicates that the +parameter is special. `<Z>' indicates that the parameter does not exist +when the shell initializes in @t{sh} or @t{ksh} emulation mode. + +@noindent +The following parameters are automatically set by the shell: + +@noindent +@table @asis +@vindex ! +@item @t{!} <S> +The process ID of the last command started in the background with @t{&}, +put into the background with the @t{bg} builtin, or spawned with @t{coproc}. + +@vindex # +@item @t{#} <S> +The number of positional parameters in decimal. Note that some confusion +may occur with the syntax @t{$#}@var{param} which substitutes the length of +@var{param}. Use @t{$@{#@}} to resolve ambiguities. In particular, the +sequence `@t{$#-}@var{...}' in an arithmetic expression is interpreted as +the length of the parameter @t{-}, q.v. + +@vindex ARGC +@item @t{ARGC} <S> <Z> +Same as @t{#}. + +@vindex $ +@item @t{$} <S> +The process ID of this shell. Note that this indicates the original +shell started by invoking @t{zsh}; all processes forked from the shells +without executing a new program, such as subshells started by +@t{(}@var{...}@t{)}, substitute the same value. + +@vindex - +@item @t{-} <S> +Flags supplied to the shell on invocation or by the @t{set} +or @t{setopt} commands. + +@vindex * +@item @t{*} <S> +An array containing the positional parameters. + +@vindex argv +@item @t{argv} <S> <Z> +Same as @t{*}. Assigning to @t{argv} changes the local positional +parameters, but @t{argv} is @emph{not} itself a local parameter. +Deleting @t{argv} with @t{unset} in any function deletes it everywhere, +although only the innermost positional parameter array is deleted (so +@t{*} and @t{@@} in other scopes are not affected). + +@vindex @@ +@item @t{@@} <S> +Same as @t{argv[@@]}, even when @t{argv} is not set. + +@vindex ? +@item @t{?} <S> +The exit status returned by the last command. + +@vindex 0 +@item @t{0} <S> +The name used to invoke the current shell, or as set by the @t{-c} command +line option upon invocation. If the @t{FUNCTION_ARGZERO} option is set, +@t{$0} is set upon entry to a shell function to the name of the function, +and upon entry to a sourced script to the name of the script, and reset to +its previous value when the function or script returns. + +@vindex status +@item @t{status} <S> <Z> +Same as @t{?}. + +@vindex pipestatus +@item @t{pipestatus} <S> <Z> +An array containing the exit statuses returned by all commands in the +last pipeline. + +@vindex _ +@item @t{_} <S> +The last argument of the previous command. +Also, this parameter is set in the environment of every command +executed to the full pathname of the command. + +@vindex CPUTYPE +@item @t{CPUTYPE} +The machine type (microprocessor class or machine model), +as determined at run time. + +@vindex EGID +@item @t{EGID} <S> +The effective group ID of the shell process. If you have sufficient +privileges, you may change the effective group ID of the shell +process by assigning to this parameter. Also (assuming sufficient +privileges), you may start a single command with a different +effective group ID by `@t{(EGID=}@var{gid}@t{; command)}' + +@noindent +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally. + +@vindex EUID +@item @t{EUID} <S> +The effective user ID of the shell process. If you have sufficient +privileges, you may change the effective user ID of the shell process +by assigning to this parameter. Also (assuming sufficient privileges), +you may start a single command with a different +effective user ID by `@t{(EUID=}@var{uid}@t{; command)}' + +@noindent +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally. + +@vindex ERRNO +@item @t{ERRNO} <S> +The value of errno (see man page errno(3)) +as set by the most recently failed system call. +This value is system dependent and is intended for debugging +purposes. It is also useful with the @t{zsh/system} module which +allows the number to be turned into a name or message. + +@vindex FUNCNEST +@item @t{FUNCNEST} <S> +Integer. If greater than or equal to zero, the maximum nesting depth of +shell functions. When it is exceeded, an error is raised at the point +where a function is called. The default value is determined when +the shell is configured, but is typically 500. Increasing +the value increases the danger of a runaway function recursion +causing the shell to crash. Setting a negative value turns off +the check. + +@vindex GID +@item @t{GID} <S> +The real group ID of the shell process. If you have sufficient privileges, +you may change the group ID of the shell process by assigning to this +parameter. Also (assuming sufficient privileges), you may start a single +command under a different +group ID by `@t{(GID=}@var{gid}@t{; command)}' + +@noindent +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally. + +@vindex HISTCMD +@item @t{HISTCMD} +The current history event number in an interactive shell, in other +words the event number for the command that caused @t{$HISTCMD} +to be read. If the current history event modifies the history, +@t{HISTCMD} changes to the new maximum history event number. + +@vindex HOST +@item @t{HOST} +The current hostname. + +@vindex LINENO +@item @t{LINENO} <S> +The line number of the current line within the current script, sourced +file, or shell function being executed, whichever was started most +recently. Note that in the case of shell functions the line +number refers to the function as it appeared in the original definition, +not necessarily as displayed by the @t{functions} builtin. + +@vindex LOGNAME +@item @t{LOGNAME} +If the corresponding variable is not set in the environment of the +shell, it is initialized to the login name corresponding to the +current login session. This parameter is exported by default but +this can be disabled using the @t{typeset} builtin. The value +is set to the string returned by the man page getlogin(3) system call +if that is available. + +@vindex MACHTYPE +@item @t{MACHTYPE} +The machine type (microprocessor class or machine model), +as determined at compile time. + +@vindex OLDPWD +@item @t{OLDPWD} +The previous working directory. This is set when the shell initializes +and whenever the directory changes. + +@vindex OPTARG +@item @t{OPTARG} <S> +The value of the last option argument processed by the @t{getopts} +command. + +@vindex OPTIND +@item @t{OPTIND} <S> +The index of the last option argument processed by the @t{getopts} +command. + +@vindex OSTYPE +@item @t{OSTYPE} +The operating system, as determined at compile time. + +@vindex PPID +@item @t{PPID} <S> +The process ID of the parent of the shell. As for @t{$$}, the +value indicates the parent of the original shell and does not +change in subshells. + +@vindex PWD +@item @t{PWD} +The present working directory. This is set when the shell initializes +and whenever the directory changes. + +@vindex RANDOM +@item @t{RANDOM} <S> +A pseudo-random integer from 0 to 32767, newly generated each time +this parameter is referenced. The random number generator +can be seeded by assigning a numeric value to @t{RANDOM}. + +@noindent +The values of @t{RANDOM} form an intentionally-repeatable pseudo-random +sequence; subshells that reference @t{RANDOM} will result +in identical pseudo-random values unless the value of @t{RANDOM} is +referenced or seeded in the parent shell in between subshell invocations. + +@vindex SECONDS +@item @t{SECONDS} <S> +The number of seconds since shell invocation. If this parameter +is assigned a value, then the value returned upon reference +will be the value that was assigned plus the number of seconds +since the assignment. + +@noindent +Unlike other special parameters, the type of the @t{SECONDS} parameter can +be changed using the @t{typeset} command. Only integer and one of the +floating point types are allowed. For example, `@t{typeset -F SECONDS}' +causes the value to be reported as a floating point number. The +value is available to microsecond accuracy, although the shell may +show more or fewer digits depending on the use of @t{typeset}. See +the documentation for the builtin @t{typeset} in +@ref{Shell Builtin Commands} for more details. + +@vindex SHLVL +@item @t{SHLVL} <S> +Incremented by one each time a new shell is started. + +@vindex signals +@item @t{signals} +An array containing the names of the signals. Note that with +the standard zsh numbering of array indices, where the first element +has index 1, the signals are offset by 1 from the signal number +used by the operating system. For example, on typical Unix-like systems +@t{HUP} is signal number 1, but is referred to as @t{$signals[2]}. This +is because of @t{EXIT} at position 1 in the array, which is used +internally by zsh but is not known to the operating system. + +@vindex TRY_BLOCK_ERROR +@item @t{TRY_BLOCK_ERROR} <S> +In an @t{always} block, indicates whether the preceding list of code +caused an error. The value is 1 to indicate an error, 0 otherwise. +It may be reset, clearing the error condition. See +@ref{Complex Commands} + +@vindex TRY_BLOCK_INTERRUPT +@item @t{TRY_BLOCK_INTERRUPT} <S> +This variable works in a similar way to @t{TRY_BLOCK_ERROR}, but +represents the status of an interrupt from the signal SIGINT, which +typically comes from the keyboard when the user types @t{^C}. If set to +0, any such interrupt will be reset; otherwise, the interrupt is +propagated after the @t{always} block. + +@noindent +Note that it is possible that an interrupt arrives during the execution +of the @t{always} block; this interrupt is also propagated. + +@vindex TTY +@item @t{TTY} +The name of the tty associated with the shell, if any. + +@vindex TTYIDLE +@item @t{TTYIDLE} <S> +The idle time of the tty associated with the shell in seconds or -1 if there +is no such tty. + +@vindex UID +@item @t{UID} <S> +The real user ID of the shell process. If you have sufficient privileges, +you may change the user ID of the shell by assigning to this parameter. +Also (assuming sufficient privileges), you may start a single command +under a different +user ID by `@t{(UID=}@var{uid}@t{; command)}' + +@noindent +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally. + +@vindex USERNAME +@item @t{USERNAME} <S> +The username corresponding to the real user ID of the shell process. If you +have sufficient privileges, you may change the username (and also the +user ID and group ID) of the shell by assigning to this parameter. +Also (assuming sufficient privileges), you may start a single command +under a different username (and user ID and group ID) +by `@t{(USERNAME=}@var{username}@t{; command)}' + +@vindex VENDOR +@item @t{VENDOR} +The vendor, as determined at compile time. + +@vindex zsh_eval_context +@vindex ZSH_EVAL_CONTEXT +@item @t{zsh_eval_context} <S> <Z> (@t{ZSH_EVAL_CONTEXT} <S>) +An array (colon-separated list) indicating the context of shell +code that is being run. Each time a piece of shell code that +is stored within the shell is executed a string is temporarily appended to +the array to indicate the type of operation that is being performed. +Read in order the array gives an indication of the stack of +operations being performed with the most immediate context last. + +@noindent +Note that the variable does not give information on syntactic context such +as pipelines or subshells. Use @t{$ZSH_SUBSHELL} to detect subshells. + +@noindent +The context is one of the following: +@table @asis +@item @t{cmdarg} +Code specified by the @t{-c} option to the command line that invoked +the shell. + +@item @t{cmdsubst} +Command substitution using the @t{`}@var{...}@t{`} or +@t{$(}@var{...}@t{)} construct. + +@item @t{equalsubst} +File substitution using the @t{=(}@var{...}@t{)} construct. + +@item @t{eval} +Code executed by the @t{eval} builtin. + +@item @t{evalautofunc} +Code executed with the @t{KSH_AUTOLOAD} mechanism in order to define +an autoloaded function. + +@item @t{fc} +Code from the shell history executed by the @t{-e} option to the @t{fc} +builtin. + +@item @t{file} +Lines of code being read directly from a file, for example by +the @t{source} builtin. + +@item @t{filecode} +Lines of code being read from a @t{.zwc} file instead of directly +from the source file. + +@item @t{globqual} +Code executed by the @t{e} or @t{+} glob qualifier. + +@item @t{globsort} +Code executed to order files by the @t{o} glob qualifier. + +@item @t{insubst} +File substitution using the @t{<(}@var{...}@t{)} construct. + +@item @t{loadautofunc} +Code read directly from a file to define an autoloaded function. + +@item @t{outsubst} +File substitution using the @t{>(}@var{...}@t{)} construct. + +@item @t{sched} +Code executed by the @t{sched} builtin. + +@item @t{shfunc} +A shell function. + +@item @t{stty} +Code passed to @t{stty} by the @t{STTY} environment variable. +Normally this is passed directly to the system's @t{stty} command, +so this value is unlikely to be seen in practice. + +@item @t{style} +Code executed as part of a style retrieved by the @t{zstyle} builtin +from the @t{zsh/zutil} module. + +@item @t{toplevel} +The highest execution level of a script or interactive shell. + +@item @t{trap} +Code executed as a trap defined by the @t{trap} builtin. Traps +defined as functions have the context @t{shfunc}. As traps are +asynchronous they may have a different hierarchy from other +code. + +@item @t{zpty} +Code executed by the @t{zpty} builtin from the @t{zsh/zpty} module. + +@item @t{zregexparse-guard} +Code executed as a guard by the @t{zregexparse} command from the +@t{zsh/zutil} module. + +@item @t{zregexparse-action} +Code executed as an action by the @t{zregexparse} command from the +@t{zsh/zutil} module. + +@end table + +@vindex ZSH_ARGZERO +@item @t{ZSH_ARGZERO} +If zsh was invoked to run a script, this is the name of the script. +Otherwise, it is the name used to invoke the current shell. This is +the same as the value of @t{$0} when the @t{POSIX_ARGZERO} option is +set, but is always available. + +@vindex ZSH_EXECUTION_STRING +@item @t{ZSH_EXECUTION_STRING} +If the shell was started with the option @t{-c}, this contains +the argument passed to the option. Otherwise it is not set. + +@vindex ZSH_NAME +@item @t{ZSH_NAME} +Expands to the basename of the command used to invoke this instance +of zsh. + +@vindex ZSH_PATCHLEVEL +@item @t{ZSH_PATCHLEVEL} +The output of `@t{git describe --tags --long}' for the zsh repository +used to build the shell. This is most useful in order to keep +track of versions of the shell during development between releases; +hence most users should not use it and should instead rely on +@t{$ZSH_VERSION}. + +@item @t{zsh_scheduled_events} +See @ref{The zsh/sched Module}. + +@vindex ZSH_SCRIPT +@item @t{ZSH_SCRIPT} +If zsh was invoked to run a script, this is the name of the script, +otherwise it is unset. + +@vindex ZSH_SUBSHELL <S> +@item @t{ZSH_SUBSHELL} +Readonly integer. Initially zero, incremented each time the shell forks +to create a subshell for executing code. Hence `@t{(print $ZSH_SUBSHELL)}' +and `@t{print $(print $ZSH_SUBSHELL)}' output 1, while +`@t{( (print $ZSH_SUBSHELL) )}' outputs 2. + +@vindex ZSH_VERSION +@item @t{ZSH_VERSION} +The version number of the release of zsh. + +@end table +@node Parameters Used By The Shell, , Parameters Set By The Shell, Parameters + +@section Parameters Used By The Shell +@noindent +The following parameters are used by the shell. Again, `<S>' indicates +that the parameter is special and `<Z>' indicates that the parameter does +not exist when the shell initializes in @t{sh} or @t{ksh} emulation mode. + +@noindent +In cases where there are two parameters with an upper- and lowercase +form of the same name, such as @t{path} and @t{PATH}, the lowercase form +is an array and the uppercase form is a scalar with the elements of the +array joined together by colons. These are similar to tied parameters +created via `@t{typeset -T}'. The normal use for the colon-separated +form is for exporting to the environment, while the array form is easier +to manipulate within the shell. Note that unsetting either of the pair +will unset the other; they retain their special properties when +recreated, and recreating one of the pair will recreate the other. + +@noindent +@table @asis +@vindex ARGV0 +@item @t{ARGV0} +If exported, its value is used as the @t{argv[0]} of external commands. +Usually used in constructs like `@t{ARGV0=emacs nethack}'. + +@cindex editing over slow connection +@cindex slow connection, editing over +@vindex BAUD +@item @t{BAUD} +The rate in bits per second at which data reaches the terminal. +The line editor will use this value in order to compensate for a slow +terminal by delaying updates to the display until necessary. If the +parameter is unset or the value is zero the compensation mechanism is +turned off. The parameter is not set by default. + +@noindent +This parameter may be profitably set in some circumstances, e.g. +for slow modems dialing into a communications server, or on a slow wide +area network. It should be set to the baud +rate of the slowest part of the link for best performance. + +@vindex cdpath +@vindex CDPATH +@item @t{cdpath} <S> <Z> (@t{CDPATH} <S>) +An array (colon-separated list) +of directories specifying the search path for the @t{cd} command. + +@vindex COLUMNS +@item @t{COLUMNS} <S> +The number of columns for this terminal session. +Used for printing select lists and for the line editor. + +@vindex CORRECT_IGNORE +@item @t{CORRECT_IGNORE} +If set, is treated as a pattern during spelling correction. Any +potential correction that matches the pattern is ignored. For example, +if the value is `@t{_*}' then completion functions (which, by +convention, have names beginning with `@t{_}') will never be offered +as spelling corrections. The pattern does not apply to the correction +of file names, as applied by the @t{CORRECT_ALL} option (so with the +example just given files beginning with `@t{_}' in the current +directory would still be completed). + +@vindex CORRECT_IGNORE_FILE +@item @t{CORRECT_IGNORE_FILE} +If set, is treated as a pattern during spelling correction of file names. +Any file name that matches the pattern is never offered as a correction. +For example, if the value is `@t{.*}' then dot file names will never be +offered as spelling corrections. This is useful with the +@t{CORRECT_ALL} option. + +@vindex DIRSTACKSIZE +@item @t{DIRSTACKSIZE} +The maximum size of the directory stack, by default there is no limit. If the +stack gets larger than this, it will be truncated automatically. +This is useful with the @t{AUTO_PUSHD} option. +@pindex AUTO_PUSHD, use of + +@vindex ENV +@item @t{ENV} +If the @t{ENV} environment variable is set when zsh is invoked as @t{sh} +or @t{ksh}, @t{$ENV} is sourced after the profile scripts. The value of +@t{ENV} is subjected to parameter expansion, command substitution, and +arithmetic expansion before being interpreted as a pathname. Note that +@t{ENV} is @emph{not} used unless the shell is interactive and zsh is +emulating @cite{sh} or @cite{ksh}. + +@vindex FCEDIT +@item @t{FCEDIT} +The default editor for the @t{fc} builtin. If @t{FCEDIT} is not set, +the parameter @t{EDITOR} is used; if that is not set either, a builtin +default, usually @t{vi}, is used. + +@vindex fignore +@vindex FIGNORE +@item @t{fignore} <S> <Z> (@t{FIGNORE} <S>) +An array (colon separated list) +containing the suffixes of files to be ignored +during filename completion. However, if completion only generates files +with suffixes in this list, then these files are completed anyway. + +@vindex fpath +@vindex FPATH +@item @t{fpath} <S> <Z> (@t{FPATH} <S>) +An array (colon separated list) +of directories specifying the search path for +function definitions. This path is searched when a function +with the @t{-u} attribute is referenced. If an executable +file is found, then it is read and executed in the current environment. + +@vindex histchars +@item @t{histchars} <S> +Three characters used by the shell's history and lexical analysis +mechanism. The first character signals the start of a history +expansion (default `@t{!}'). The second character signals the +start of a quick history substitution (default `@t{^}'). The third +character is the comment character (default `@t{#}'). + +@noindent +The characters must be in the ASCII character set; any attempt to set +@t{histchars} to characters with a locale-dependent meaning will be +rejected with an error message. + +@vindex HISTCHARS +@item @t{HISTCHARS} <S> <Z> +Same as @t{histchars}. (Deprecated.) + +@vindex HISTFILE +@item @t{HISTFILE} +The file to save the history in when an interactive shell exits. +If unset, the history is not saved. + +@vindex HISTORY_IGNORE +@item @t{HISTORY_IGNORE} +If set, is treated as a pattern at the time history files are written. +Any potential history entry that matches the pattern is skipped. For +example, if the value is `@t{fc *}' then commands that invoke the +interactive history editor are never written to the history file. + +@noindent +Note that @t{HISTORY_IGNORE} defines a single pattern: to +specify alternatives use the +`@t{(}@var{first}@t{|}@var{second}@t{|}@var{...}@t{)}' syntax. + +@noindent +Compare the @t{HIST_NO_STORE} option or the @t{zshaddhistory} hook, +either of which would prevent such commands from being added to the +interactive history at all. If you wish to use @t{HISTORY_IGNORE} to +stop history being added in the first place, you can define the +following hook: + +@noindent +@example +zshaddhistory() @{ + emulate -L zsh + ## uncomment if HISTORY_IGNORE + ## should use EXTENDED_GLOB syntax + # setopt extendedglob + [[ $1 != $@{~HISTORY_IGNORE@} ]] +@} +@end example + +@vindex HISTSIZE +@item @t{HISTSIZE} <S> +The maximum number of events stored in the internal history list. +If you use the @t{HIST_EXPIRE_DUPS_FIRST} option, setting this value +larger than the @t{SAVEHIST} size will give you the difference as a +cushion for saving duplicated history events. + +@noindent +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally. + +@vindex HOME +@item @t{HOME} <S> +The default argument for the @t{cd} command. This is not set automatically +by the shell in @t{sh}, @t{ksh} or @t{csh} emulation, but it is typically +present in the environment anyway, and if it becomes set it has its usual +special behaviour. + +@vindex IFS +@item @t{IFS} <S> +Internal field separators (by default space, tab, newline and NUL), that +are used to separate words which result from +command or parameter expansion and words read by +the @t{read} builtin. Any characters from the set space, tab and +newline that appear in the IFS are called @emph{IFS white space}. +One or more IFS white space characters or one non-IFS white space +character together with any adjacent IFS white space character delimit +a field. If an IFS white space character appears twice consecutively +in the IFS, this character is treated as if it were not an IFS white +space character. + +@noindent +If the parameter is unset, the default is used. Note this has +a different effect from setting the parameter to an empty string. + +@vindex KEYBOARD_HACK +@item @t{KEYBOARD_HACK} +This variable defines a character to be removed from the end of the +command line before interpreting it (interactive shells only). It is +intended to fix the problem with keys placed annoyingly close to return +and replaces the @t{SUNKEYBOARDHACK} option which did this for +backquotes only. Should the chosen character be one of singlequote, +doublequote or backquote, there must also be an odd number of them +on the command line for the last one to be removed. + +@noindent +For backward compatibility, if the @t{SUNKEYBOARDHACK} option is +explicitly set, the value of @t{KEYBOARD_HACK} reverts to backquote. +If the option is explicitly unset, this variable is set to empty. + +@vindex KEYTIMEOUT +@item @t{KEYTIMEOUT} +The time the shell waits, in hundredths of seconds, for another key to +be pressed when reading bound multi-character sequences. + +@vindex LANG +@item @t{LANG} <S> +This variable determines the locale category for any category not +specifically selected via a variable starting with `@t{LC_}'. + +@vindex LC_ALL +@item @t{LC_ALL} <S> +This variable overrides the value of the `@t{LANG}' variable and the value +of any of the other variables starting with `@t{LC_}'. + +@vindex LC_COLLATE +@item @t{LC_COLLATE} <S> +This variable determines the locale category for character collation +information within ranges in glob brackets and for sorting. + +@vindex LC_CTYPE +@item @t{LC_CTYPE} <S> +This variable determines the locale category for character handling +functions. If the @t{MULTIBYTE} option is in effect this variable or +@t{LANG} should contain a value that reflects the character set in +use, even if it is a single-byte character set, unless only the +7-bit subset (ASCII) is used. For example, if the character set +is ISO-8859-1, a suitable value might be @t{en_US.iso88591} (certain +Linux distributions) or @t{en_US.ISO8859-1} (MacOS). + +@vindex LC_MESSAGES +@item @t{LC_MESSAGES} <S> +This variable determines the language in which messages should be +written. Note that zsh does not use message catalogs. + +@vindex LC_NUMERIC +@item @t{LC_NUMERIC} <S> +This variable affects the decimal point character and thousands +separator character for the formatted input/output functions +and string conversion functions. Note that zsh ignores this +setting when parsing floating point mathematical expressions. + +@vindex LC_TIME +@item @t{LC_TIME} <S> +This variable determines the locale category for date and time +formatting in prompt escape sequences. + +@vindex LINES +@item @t{LINES} <S> +The number of lines for this terminal session. +Used for printing select lists and for the line editor. + +@vindex LISTMAX +@item @t{LISTMAX} +In the line editor, the number of matches to list without asking +first. If the value is negative, the list will be shown if it spans at +most as many lines as given by the absolute value. +If set to zero, the shell asks only if the top of the listing would scroll +off the screen. + +@vindex LOGCHECK +@item @t{LOGCHECK} +The interval in seconds between checks for login/logout activity +using the @t{watch} parameter. + +@vindex MAIL +@item @t{MAIL} +If this parameter is set and @t{mailpath} is not set, +the shell looks for mail in the specified file. + +@vindex MAILCHECK +@item @t{MAILCHECK} +The interval in seconds between checks for new mail. + +@vindex mailpath +@vindex MAILPATH +@item @t{mailpath} <S> <Z> (@t{MAILPATH} <S>) +An array (colon-separated list) of filenames to check for +new mail. Each filename can be followed by a `@t{?}' and a +message that will be printed. The message will undergo +parameter expansion, command substitution and arithmetic +expansion with the variable @t{$_} defined as the name +of the file that has changed. The default message is +`@t{You have new mail}'. If an element is a directory +instead of a file the shell will recursively check every +file in every subdirectory of the element. + +@vindex manpath +@vindex MANPATH +@item @t{manpath} <S> <Z> (@t{MANPATH} <S> <Z>) +An array (colon-separated list) +whose value is not used by the shell. The @t{manpath} +array can be useful, however, since setting it also sets +@t{MANPATH}, and vice versa. + +@item @t{match} +@itemx @t{mbegin} +@itemx @t{mend} +Arrays set by the shell when the @t{b} globbing flag is used in pattern +matches. See the subsection @emph{Globbing flags} in +@ref{Filename Generation}. + +@item @t{MATCH} +@itemx @t{MBEGIN} +@itemx @t{MEND} +Set by the shell when the @t{m} globbing flag is used in pattern +matches. See the subsection @emph{Globbing flags} in +@ref{Filename Generation}. + +@vindex module_path +@vindex MODULE_PATH +@item @t{module_path} <S> <Z> (@t{MODULE_PATH} <S>) +An array (colon-separated list) +of directories that @t{zmodload} +searches for dynamically loadable modules. +This is initialized to a standard pathname, +usually `@t{/usr/local/lib/zsh/$ZSH_VERSION}'. +(The `@t{/usr/local/lib}' part varies from installation to installation.) +For security reasons, any value set in the environment when the shell +is started will be ignored. + +@noindent +These parameters only exist if the installation supports dynamic +module loading. + +@vindex NULLCMD +@cindex null command style +@cindex csh, null command style +@cindex ksh, null command style +@item @t{NULLCMD} <S> +The command name to assume if a redirection is specified +with no command. Defaults to @t{cat}. For @cite{sh}/@cite{ksh} +behavior, change this to @t{:}. For @cite{csh}-like +behavior, unset this parameter; the shell will print an +error message if null commands are entered. + +@vindex path +@vindex PATH +@item @t{path} <S> <Z> (@t{PATH} <S>) +An array (colon-separated list) +of directories to search for commands. +When this parameter is set, each directory is scanned +and all files found are put in a hash table. + +@vindex POSTEDIT +@item @t{POSTEDIT} <S> +This string is output whenever the line editor exits. +It usually contains termcap strings to reset the terminal. + +@vindex PROMPT +@item @t{PROMPT} <S> <Z> +@vindex PROMPT2 +@itemx @t{PROMPT2} <S> <Z> +@vindex PROMPT3 +@itemx @t{PROMPT3} <S> <Z> +@vindex PROMPT4 +@itemx @t{PROMPT4} <S> <Z> +Same as @t{PS1}, @t{PS2}, @t{PS3} and @t{PS4}, +respectively. + +@vindex prompt +@item @t{prompt} <S> <Z> +Same as @t{PS1}. + +@vindex PROMPT_EOL_MARK +@item @t{PROMPT_EOL_MARK} +When the @t{PROMPT_CR} and @t{PROMPT_SP} options are set, the +@t{PROMPT_EOL_MARK} parameter can be used to customize how the end of +partial lines are shown. This parameter undergoes prompt expansion, with +the @t{PROMPT_PERCENT} option set. If not set, the default behavior is +equivalent to the value `@t{%B%S%#%s%b}'. + +@vindex PS1 +@item @t{PS1} <S> +The primary prompt string, printed before a command is read. +It undergoes a special form of expansion +before being displayed; see +@ref{Prompt Expansion}. The default is `@t{%m%# }'. + +@vindex PS2 +@item @t{PS2} <S> +The secondary prompt, printed when the shell needs more information +to complete a command. +It is expanded in the same way as @t{PS1}. +The default is `@t{%_> }', which displays any shell constructs or quotation +marks which are currently being processed. + +@vindex PS3 +@item @t{PS3} <S> +Selection prompt used within a @t{select} loop. +It is expanded in the same way as @t{PS1}. +The default is `@t{?# }'. + +@vindex PS4 +@item @t{PS4} <S> +The execution trace prompt. Default is `@t{+%N:%i> }', which displays +the name of the current shell structure and the line number within it. +In sh or ksh emulation, the default is `@t{+ }'. + +@vindex psvar +@vindex PSVAR +@item @t{psvar} <S> <Z> (@t{PSVAR} <S>) +An array (colon-separated list) whose elements can be used in +@t{PROMPT} strings. Setting @t{psvar} also sets @t{PSVAR}, and +vice versa. + +@vindex READNULLCMD +@item @t{READNULLCMD} <S> +The command name to assume if a single input redirection +is specified with no command. Defaults to @t{more}. + +@vindex REPORTMEMORY +@item @t{REPORTMEMORY} +If nonnegative, commands whose maximum resident set size (roughly +speaking, main memory usage) in kilobytes is greater than this +value have timing statistics reported. The format used to output +statistics is the value of the @t{TIMEFMT} parameter, which is the same +as for the @t{REPORTTIME} variable and the @t{time} builtin; note that +by default this does not output memory usage. Appending +@t{" max RSS %M"} to the value of @t{TIMEFMT} causes it to output the +value that triggered the report. If @t{REPORTTIME} is also in use, +at most a single report is printed for both triggers. This feature +requires the @t{getrusage()} system call, commonly supported by +modern Unix-like systems. + +@vindex REPORTTIME +@item @t{REPORTTIME} +If nonnegative, commands whose combined user and system execution times +(measured in seconds) are greater than this value have timing +statistics printed for them. Output is suppressed for commands +executed within the line editor, including completion; commands +explicitly marked with the @t{time} keyword still cause the summary +to be printed in this case. + +@vindex REPLY +@item @t{REPLY} +This parameter is reserved by convention to pass string values between +shell scripts and shell builtins in situations where a function call or +redirection are impossible or undesirable. The @t{read} builtin and the +@t{select} complex command may set @t{REPLY}, and filename generation both +sets and examines its value when evaluating certain expressions. Some +modules also employ @t{REPLY} for similar purposes. + +@vindex reply +@item @t{reply} +As @t{REPLY}, but for array values rather than strings. + +@vindex RPROMPT +@item @t{RPROMPT} <S> +@vindex RPS1 +@itemx @t{RPS1} <S> +This prompt is displayed on the right-hand side of the screen +when the primary prompt is being displayed on the left. +This does not work if the @t{SINGLE_LINE_ZLE} option is set. +It is expanded in the same way as @t{PS1}. + +@vindex RPROMPT2 +@item @t{RPROMPT2} <S> +@vindex RPS2 +@itemx @t{RPS2} <S> +This prompt is displayed on the right-hand side of the screen +when the secondary prompt is being displayed on the left. +This does not work if the @t{SINGLE_LINE_ZLE} option is set. +It is expanded in the same way as @t{PS2}. + +@vindex SAVEHIST +@item @t{SAVEHIST} +The maximum number of history events to save in the history file. + +@noindent +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally. + +@vindex SPROMPT +@item @t{SPROMPT} <S> +The prompt used for spelling correction. The sequence +`@t{%R}' expands to the string which presumably needs spelling +correction, and `@t{%r}' expands to the proposed correction. +All other prompt escapes are also allowed. + +@noindent +The actions available at the prompt are @t{[nyae]}: +@table @asis +@item @t{n} (`no') (default) +Discard the correction and run the command. +@item @t{y} (`yes') +Make the correction and run the command. +@item @t{a} (`abort') +Discard the entire command line without running it. +@item @t{e} (`edit') +Resume editing the command line. +@end table + +@vindex STTY +@item @t{STTY} +If this parameter is set in a command's environment, the shell runs the +@t{stty} command with the value of this parameter as arguments in order to +set up the terminal before executing the command. The modes apply only to the +command, and are reset when it finishes or is suspended. If the command is +suspended and continued later with the @t{fg} or @t{wait} builtins it will +see the modes specified by @t{STTY}, as if it were not suspended. This +(intentionally) does not apply if the command is continued via `@t{kill +-CONT}'. @t{STTY} is ignored if the command is run in the background, or +if it is in the environment of the shell but not explicitly assigned to in +the input line. This avoids running stty at every external command by +accidentally exporting it. Also note that @t{STTY} should not be used for +window size specifications; these will not be local to the command. + +@vindex TERM +@item @t{TERM} <S> +The type of terminal in use. This is used when looking up termcap +sequences. An assignment to @t{TERM} causes zsh to re-initialize the +terminal, even if the value does not change (e.g., `@t{TERM=$TERM}'). It +is necessary to make such an assignment upon any change to the terminal +definition database or terminal type in order for the new settings to +take effect. + +@vindex TERMINFO +@item @t{TERMINFO} <S> +A reference to your terminfo database, used by the `terminfo' library when the +system has it; see man page terminfo(5). +If set, this causes the shell to reinitialise the terminal, making the +workaround `@t{TERM=$TERM}' unnecessary. + +@vindex TERMINFO_DIRS +@item @t{TERMINFO_DIRS} <S> +A colon-seprarated list of terminfo databases, used by the `terminfo' library +when the system has it; see man page terminfo(5). This variable is only +used by certain terminal libraries, in particular ncurses; see +man page terminfo(5) to check support on your system. If set, this +causes the shell to reinitialise the terminal, making the workaround +`@t{TERM=$TERM}' unnecessary. Note that unlike other colon-separated +arrays this is not tied to a zsh array. + +@vindex TIMEFMT +@item @t{TIMEFMT} +The format of process time reports with the @t{time} keyword. +The default is `@t{%J %U user %S system %P cpu %*E total}'. +Recognizes the following escape sequences, although not all +may be available on all systems, and some that are available +may not be useful: + +@noindent +@table @asis +@item @t{%%} +A `@t{%}'. +@item @t{%U} +CPU seconds spent in user mode. +@item @t{%S} +CPU seconds spent in kernel mode. +@item @t{%E} +Elapsed time in seconds. +@item @t{%P} +The CPU percentage, computed as +100*(@t{%U}+@t{%S})/@t{%E}. +@item @t{%W} +Number of times the process was swapped. +@item @t{%X} +The average amount in (shared) text space used in kilobytes. +@item @t{%D} +The average amount in (unshared) data/stack space used in +kilobytes. +@item @t{%K} +The total space used (@t{%X}+@t{%D}) in kilobytes. +@item @t{%M} +The maximum memory the process had in use at any time in +kilobytes. +@item @t{%F} +The number of major page faults (page needed to be brought +from disk). +@item @t{%R} +The number of minor page faults. +@item @t{%I} +The number of input operations. +@item @t{%O} +The number of output operations. +@item @t{%r} +The number of socket messages received. +@item @t{%s} +The number of socket messages sent. +@item @t{%k} +The number of signals received. +@item @t{%w} +Number of voluntary context switches (waits). +@item @t{%c} +Number of involuntary context switches. +@item @t{%J} +The name of this job. +@end table + +@noindent +A star may be inserted between the percent sign and flags printing time +(e.g., `@t{%*E}'); this causes the time to be printed in +`@var{hh}@t{:}@var{mm}@t{:}@var{ss}@t{.}@var{ttt}' +format (hours and minutes are only printed if they are not zero). +Alternatively, `@t{m}' or `@t{u}' may be used (e.g., `@t{%mE}') to produce +time output in milliseconds or microseconds, respectively. + +@vindex TMOUT +@item @t{TMOUT} +If this parameter is nonzero, the shell will receive an @t{ALRM} +signal if a command is not entered within the specified number of +seconds after issuing a prompt. If there is a trap on @t{SIGALRM}, it +will be executed and a new alarm is scheduled using the value of the +@t{TMOUT} parameter after executing the trap. If no trap is set, and +the idle time of the terminal is not less than the value of the +@t{TMOUT} parameter, zsh terminates. Otherwise a new alarm is +scheduled to @t{TMOUT} seconds after the last keypress. + +@vindex TMPPREFIX +@item @t{TMPPREFIX} +A pathname prefix which the shell will use for all temporary files. +Note that this should include an initial part for the file name as +well as any directory names. The default is `@t{/tmp/zsh}'. + +@vindex TMPSUFFIX +@item @t{TMPSUFFIX} +A filename suffix which the shell will use for temporary files created +by process substitutions (e.g., `@t{=(@var{list})}'). +Note that the value should include a leading dot `@t{.}' if intended +to be interpreted as a file extension. The default is not to append +any suffix, thus this parameter should be assigned only when needed +and then unset again. + +@vindex watch +@vindex WATCH +@item @t{watch} <S> <Z> (@t{WATCH} <S>) +An array (colon-separated list) of login/logout events to report. + +@noindent +If it contains the single word `@t{all}', then all login/logout events +are reported. If it contains the single word `@t{notme}', then all +events are reported as with `@t{all}' except @t{$USERNAME}. + +@noindent +An entry in this list may consist of a username, +an `@t{@@}' followed by a remote hostname, +and a `@t{%}' followed by a line (tty). Any of these may +be a pattern (be sure to quote this during the assignment to +@t{watch} so that it does not immediately perform file generation); +the setting of the @t{EXTENDED_GLOB} option is respected. +Any or all of these components may be present in an entry; +if a login/logout event matches all of them, +it is reported. + +@noindent +For example, with the @t{EXTENDED_GLOB} option set, the following: + +@noindent +@example +watch=('^(pws|barts)') +@end example + +@noindent +causes reports for activity associated with any user other than @t{pws} +or @t{barts}. + +@vindex WATCHFMT +@item @t{WATCHFMT} +The format of login/logout reports if the @t{watch} parameter is set. +Default is `@t{%n has %a %l from %m}'. +Recognizes the following escape sequences: + +@noindent +@table @asis +@item @t{%n} +The name of the user that logged in/out. + +@item @t{%a} +The observed action, i.e. "logged on" or "logged off". + +@item @t{%l} +The line (tty) the user is logged in on. + +@item @t{%M} +The full hostname of the remote host. + +@item @t{%m} +The hostname up to the first `@t{.}'. If only the +IP address is available or the utmp field contains +the name of an X-windows display, the whole name is printed. + +@noindent +@emph{NOTE:} +The `@t{%m}' and `@t{%M}' escapes will work only if there is a host name +field in the utmp on your machine. Otherwise they are +treated as ordinary strings. + +@item @t{%S} (@t{%s}) +Start (stop) standout mode. + +@item @t{%U} (@t{%u}) +Start (stop) underline mode. + +@item @t{%B} (@t{%b}) +Start (stop) boldface mode. + +@item @t{%t} +@itemx @t{%@@} +The time, in 12-hour, am/pm format. + +@item @t{%T} +The time, in 24-hour format. + +@item @t{%w} +The date in `@var{day}@t{-}@var{dd}' format. + +@item @t{%W} +The date in `@var{mm}@t{/}@var{dd}@t{/}@var{yy}' format. + +@item @t{%D} +The date in `@var{yy}@t{-}@var{mm}@t{-}@var{dd}' format. + +@item @t{%D@{}@var{string}@t{@}} +The date formatted as @var{string} using the @t{strftime} function, with +zsh extensions as described by +@ref{Prompt Expansion}. + +@item @t{%(}@var{x}@t{:}@var{true-text}@t{:}@var{false-text}@t{)} +Specifies a ternary expression. +The character following the @var{x} is +arbitrary; the same character is used to separate the text +for the "true" result from that for the "false" result. +Both the separator and the right parenthesis may be escaped +with a backslash. +Ternary expressions may be nested. + +@noindent +The test character @var{x} may be any one of `@t{l}', `@t{n}', `@t{m}' +or `@t{M}', which indicate a `true' result if the corresponding +escape sequence would return a non-empty value; or it may be `@t{a}', +which indicates a `true' result if the watched user has logged in, +or `false' if he has logged out. +Other characters evaluate to neither true nor false; the entire +expression is omitted in this case. + +@noindent +If the result is `true', then the @var{true-text} +is formatted according to the rules above and printed, +and the @var{false-text} is skipped. +If `false', the @var{true-text} is skipped and the @var{false-text} +is formatted and printed. +Either or both of the branches may be empty, but +both separators must be present in any case. + +@end table + +@vindex WORDCHARS +@item @t{WORDCHARS} <S> +A list of non-alphanumeric characters considered part of a word +by the line editor. + +@vindex ZBEEP +@item @t{ZBEEP} +If set, this gives a string of characters, which can use all the same codes +as the @t{bindkey} command as described in +@ref{The zsh/zle Module}, that will be output to the terminal +instead of beeping. This may have a visible instead of an audible effect; +for example, the string `@t{\e[?5h\e[?5l}' on a vt100 or xterm will have +the effect of flashing reverse video on and off (if you usually use reverse +video, you should use the string `@t{\e[?5l\e[?5h}' instead). This takes +precedence over the @t{NOBEEP} option. + +@vindex ZDOTDIR +@item @t{ZDOTDIR} +The directory to search for shell startup files (.zshrc, etc), +if not @t{$HOME}. + +@vindex zle_bracketed_paste +@cindex bracketed paste +@cindex enabling bracketed paste +@item @t{zle_bracketed_paste} +Many terminal emulators have a feature that allows applications to +identify when text is pasted into the terminal rather than being typed +normally. For ZLE, this means that special characters such as tabs +and newlines can be inserted instead of invoking editor commands. +Furthermore, pasted text forms a single undo event and if the region is +active, pasted text will replace the region. + +@noindent +This two-element array contains the terminal escape sequences for +enabling and disabling the feature. These escape sequences are used to +enable bracketed paste when ZLE is active and disable it at other times. +Unsetting the parameter has the effect of ensuring that bracketed paste +remains disabled. + +@vindex zle_highlight +@item @t{zle_highlight} +An array describing contexts in which ZLE should highlight the input text. +See @ref{Character Highlighting}. + +@vindex ZLE_LINE_ABORTED +@item @t{ZLE_LINE_ABORTED} +This parameter is set by the line editor when an error occurs. It +contains the line that was being edited at the point of the error. +`@t{print -zr -- $ZLE_LINE_ABORTED}' can be used to recover the line. +Only the most recent line of this kind is remembered. + +@vindex ZLE_REMOVE_SUFFIX_CHARS +@vindex ZLE_SPACE_SUFFIX_CHARS +@item @t{ZLE_REMOVE_SUFFIX_CHARS} +@itemx @t{ZLE_SPACE_SUFFIX_CHARS} +These parameters are used by the line editor. In certain circumstances +suffixes (typically space or slash) added by the completion system +will be removed automatically, either because the next editing command +was not an insertable character, or because the character was marked +as requiring the suffix to be removed. + +@noindent +These variables can contain the sets of characters that will cause the +suffix to be removed. If @t{ZLE_REMOVE_SUFFIX_CHARS} is set, those +characters will cause the suffix to be removed; if +@t{ZLE_SPACE_SUFFIX_CHARS} is set, those characters will cause the +suffix to be removed and replaced by a space. + +@noindent +If @t{ZLE_REMOVE_SUFFIX_CHARS} is not set, the default behaviour is +equivalent to: + +@noindent +@example +ZLE_REMOVE_SUFFIX_CHARS=$' \t\n;&|' +@end example + +@noindent +If @t{ZLE_REMOVE_SUFFIX_CHARS} is set but is empty, no characters have this +behaviour. @t{ZLE_SPACE_SUFFIX_CHARS} takes precedence, so that the +following: + +@noindent +@example +ZLE_SPACE_SUFFIX_CHARS=$'&|' +@end example + +@noindent +causes the characters `@t{&}' and `@t{|}' to remove the suffix but to +replace it with a space. + +@noindent +To illustrate the difference, suppose that the option @t{AUTO_REMOVE_SLASH} +is in effect and the directory @t{DIR} has just been completed, with an +appended @t{/}, following which the user types `@t{&}'. The default result +is `@t{DIR&}'. With @t{ZLE_REMOVE_SUFFIX_CHARS} set but without including +`@t{&}' the result is `@t{DIR/&}'. With @t{ZLE_SPACE_SUFFIX_CHARS} set to +include `@t{&}' the result is `@t{DIR &}'. + +@noindent +Note that certain completions may provide their own suffix removal +or replacement behaviour which overrides the values described here. +See the completion system documentation in +@ref{Completion System}. + +@vindex ZLE_RPROMPT_INDENT +@item @t{ZLE_RPROMPT_INDENT} <S> +If set, used to give the indentation between the right hand side of +the right prompt in the line editor as given by @t{RPS1} or @t{RPROMPT} +and the right hand side of the screen. If not set, the value 1 is used. + +@noindent +Typically this will be used to set the value to 0 so that the prompt +appears flush with the right hand side of the screen. This is not the +default as many terminals do not handle this correctly, in particular +when the prompt appears at the extreme bottom right of the screen. +Recent virtual terminals are more likely to handle this case correctly. +Some experimentation is necessary. + +@end table +@c (avoiding a yodl bug) +@c Yodl file: Zsh/options.yo +@node Options, Shell Builtin Commands, Parameters, Top + +@chapter Options +@noindent +@cindex options +@menu +* Specifying Options:: +* Description of Options:: +* Option Aliases:: +* Single Letter Options:: +@end menu +@node Specifying Options, Description of Options, , Options + +@section Specifying Options +@noindent +@cindex options, specifying +Options are primarily referred to by name. +These names are case insensitive and underscores are ignored. +For example, `@t{allexport}' is equivalent to `@t{A__lleXP_ort}'. + +@noindent +The sense of an option name may be inverted by preceding it with +`@t{no}', so `@t{setopt No_Beep}' is equivalent to `@t{unsetopt beep}'. +This inversion can only be done once, so `@t{nonobeep}' is @emph{not} +a synonym for `@t{beep}'. Similarly, `@t{tify}' is not a synonym for +`@t{nonotify}' (the inversion of `@t{notify}'). + +@noindent +Some options also have one or more single letter names. +There are two sets of single letter options: one used by default, +and another used to emulate @cite{sh}/@cite{ksh} (used when the +@t{SH_OPTION_LETTERS} option is set). +The single letter options can be used on the shell command line, +or with the @t{set}, @t{setopt} and @t{unsetopt} +builtins, as normal Unix options preceded by `@t{-}'. + +@noindent +The sense of the single letter options may be inverted by using +`@t{+}' instead of `@t{-}'. +Some of the single letter option names refer to an option being off, +in which case the inversion of that name refers to the option being on. +For example, `@t{+n}' is the short name of `@t{exec}', and +`@t{-n}' is the short name of its inversion, `@t{noexec}'. + +@noindent +In strings of single letter options supplied to the shell at startup, +trailing whitespace will be ignored; for example the string `@t{-f }' +will be treated just as `@t{-f}', but the string `@t{-f i}' is an error. +This is because many systems which implement the `@t{#!}' mechanism for +calling scripts do not strip trailing whitespace. + +@noindent +@node Description of Options, Option Aliases, Specifying Options, Options + +@section Description of Options +@noindent +@cindex options, description +In the following list, options set by default in all emulations are marked +<D>; those set by default only in csh, ksh, sh, or zsh emulations are marked +<C>, <K>, <S>, <Z> as appropriate. When listing options (by `@t{setopt}', +`@t{unsetopt}', `@t{set -o}' or `@t{set +o}'), those turned on by default +appear in the list prefixed with `@t{no}'. Hence (unless +@t{KSH_OPTION_PRINT} is set), `@t{setopt}' shows all options whose settings +are changed from the default. + +@noindent + +@subsection Changing Directories +@noindent +@table @asis +@pindex AUTO_CD +@pindex NO_AUTO_CD +@pindex AUTOCD +@pindex NOAUTOCD +@cindex cd, automatic +@item @t{AUTO_CD} (@t{-J}) +If a command is issued that can't be executed as a normal command, +and the command is the name of a directory, perform the @t{cd} +command to that directory. +This option is only applicable if the option @t{SHIN_STDIN} is set, +i.e. if commands are being read from standard input. The option +is designed for interactive use; it is recommended that @t{cd} +be used explicitly in scripts to avoid ambiguity. + +@pindex AUTO_PUSHD +@pindex NO_AUTO_PUSHD +@pindex AUTOPUSHD +@pindex NOAUTOPUSHD +@cindex cd, behaving like pushd +@cindex pushd, making cd behave like +@item @t{AUTO_PUSHD} (@t{-N}) +Make @t{cd} push the old directory onto the directory stack. + +@pindex CDABLE_VARS +@pindex NO_CDABLE_VARS +@pindex CDABLEVARS +@pindex NOCDABLEVARS +@cindex cd, to parameter +@item @t{CDABLE_VARS} (@t{-T}) +If the argument to a @t{cd} command (or an implied @t{cd} with the +@t{AUTO_CD} option set) is not a directory, and does not begin with a +slash, try to expand the expression as if it were preceded by a `@t{~}' (see +@ref{Filename Expansion}). + +@pindex CD_SILENT +@pindex NO_CD_SILENT +@pindex CDSILENT +@pindex NOCDSILENT +@cindex cd, silencing +@cindex autocd, silencing +@item @t{CD_SILENT} +Never print the working directory after a @t{cd} (whether explicit or +implied with the @t{AUTO_CD} option set). @t{cd} normally prints the +working directory when the argument given to it was @t{-}, a stack entry, or +the name of a directory found under @t{CDPATH}. Note that this is distinct +from @t{pushd}'s stack-printing behaviour, which is controlled by +@t{PUSHD_SILENT}. This option overrides the printing-related effects of +@t{POSIX_CD}. + +@pindex CHASE_DOTS +@pindex NO_CHASE_DOTS +@pindex CHASEDOTS +@pindex NOCHASEDOTS +@cindex cd, with .. in argument +@item @t{CHASE_DOTS} +When changing to a directory containing a path segment `@t{..}' which would +otherwise be treated as canceling the previous segment in the path (in +other words, `@t{foo/..}' would be removed from the path, or if `@t{..}' is +the first part of the path, the last part of the current working directory +would be removed), instead resolve the path to the physical directory. +This option is overridden by @t{CHASE_LINKS}. + +@noindent +For example, suppose @t{/foo/bar} is a link to the directory @t{/alt/rod}. +Without this option set, `@t{cd /foo/bar/..}' changes to @t{/foo}; with it +set, it changes to @t{/alt}. The same applies if the current directory +is @t{/foo/bar} and `@t{cd ..}' is used. Note that all other symbolic +links in the path will also be resolved. + +@pindex CHASE_LINKS +@pindex NO_CHASE_LINKS +@pindex CHASELINKS +@pindex NOCHASELINKS +@cindex links, symbolic +@cindex symbolic links +@item @t{CHASE_LINKS} (@t{-w}) +Resolve symbolic links to their true values when changing directory. +This also has the effect of @t{CHASE_DOTS}, i.e. a `@t{..}' path segment +will be treated as referring to the physical parent, even if the preceding +path segment is a symbolic link. + +@pindex POSIX_CD +@pindex POSIXCD +@pindex NO_POSIX_CD +@pindex NOPOSIXCD +@cindex CDPATH, order of checking +@item @t{POSIX_CD} <K> <S> +Modifies the behaviour of @t{cd}, @t{chdir} and @t{pushd} commands +to make them more compatible with the POSIX standard. The behaviour with +the option unset is described in the documentation for the @t{cd} +builtin in +@ref{Shell Builtin Commands}. +If the option is set, the shell does not test for directories beneath +the local directory (`@t{.}') until after all directories in @t{cdpath} +have been tested, and the @t{cd} and @t{chdir} commands do not recognise +arguments of the form `@{@t{+}|@t{-}@}@var{n}' as directory stack entries. + +@noindent +Also, if the option is set, the conditions under which the shell +prints the new directory after changing to it are modified. It is +no longer restricted to interactive shells (although printing of +the directory stack with @t{pushd} is still limited to interactive +shells); and any use of a component of @t{CDPATH}, including a `@t{.}' but +excluding an empty component that is otherwise treated as `@t{.}', causes +the directory to be printed. + +@pindex PUSHD_IGNORE_DUPS +@pindex NO_PUSHD_IGNORE_DUPS +@pindex PUSHDIGNOREDUPS +@pindex NOPUSHDIGNOREDUPS +@cindex directory stack, ignoring duplicates +@item @t{PUSHD_IGNORE_DUPS} +Don't push multiple copies of the same directory onto the directory stack. + +@pindex PUSHD_MINUS +@pindex NO_PUSHD_MINUS +@pindex PUSHDMINUS +@pindex NOPUSHDMINUS +@cindex directory stack, controlling syntax +@item @t{PUSHD_MINUS} +Exchanges the meanings of `@t{+}' and `@t{-}' +when used with a number to specify a directory in the stack. + +@pindex PUSHD_SILENT +@pindex NO_PUSHD_SILENT +@pindex PUSHDSILENT +@pindex NOPUSHDSILENT +@cindex directory stack, silencing +@item @t{PUSHD_SILENT} (@t{-E}) +Do not print the directory stack after @t{pushd} or @t{popd}. + +@pindex PUSHD_TO_HOME +@pindex NO_PUSHD_TO_HOME +@pindex PUSHDTOHOME +@pindex NOPUSHDTOHOME +@cindex pushd, to home +@item @t{PUSHD_TO_HOME} (@t{-D}) +Have @t{pushd} with no arguments act like `@t{pushd $HOME}'. + +@end table + +@noindent + +@subsection Completion +@noindent +@table @asis +@pindex ALWAYS_LAST_PROMPT +@pindex NO_ALWAYS_LAST_PROMPT +@pindex ALWAYSLASTPROMPT +@pindex NOALWAYSLASTPROMPT +@item @t{ALWAYS_LAST_PROMPT} <D> +If unset, key functions that list completions try to return to the last +prompt if given a numeric argument. If set these functions try to +return to the last prompt if given @emph{no} numeric argument. + +@pindex ALWAYS_TO_END +@pindex NO_ALWAYS_TO_END +@pindex ALWAYSTOEND +@pindex NOALWAYSTOEND +@item @t{ALWAYS_TO_END} +If a completion is performed with the cursor within a word, and a +full completion is inserted, the cursor is moved to the end of the +word. That is, the cursor is moved to the end of the word if either +a single match is inserted or menu completion is performed. + +@pindex AUTO_LIST +@pindex NO_AUTO_LIST +@pindex AUTOLIST +@pindex NOAUTOLIST +@cindex completion, listing choices +@item @t{AUTO_LIST} (@t{-9}) <D> +Automatically list choices on an ambiguous completion. + +@pindex AUTO_MENU +@pindex NO_AUTO_MENU +@pindex AUTOMENU +@pindex NOAUTOMENU +@cindex completion, menu +@item @t{AUTO_MENU} <D> +Automatically use menu completion after the second consecutive request for +completion, for example by pressing the tab key repeatedly. This option +is overridden by @t{MENU_COMPLETE}. + +@pindex AUTO_NAME_DIRS +@pindex NO_AUTO_NAME_DIRS +@pindex AUTONAMEDIRS +@pindex NOAUTONAMEDIRS +@cindex directories, named +@item @t{AUTO_NAME_DIRS} +Any parameter that is set to the absolute name of a directory +immediately becomes a name for that directory, that will be used +by the `@t{%~}' +and related prompt sequences, and will be available when completion +is performed on a word starting with `@t{~}'. +(Otherwise, the parameter must be used in the form `@t{~}@var{param}' first.) + +@pindex AUTO_PARAM_KEYS +@pindex NO_AUTO_PARAM_KEYS +@pindex AUTOPARAMKEYS +@pindex NOAUTOPARAMKEYS +@item @t{AUTO_PARAM_KEYS} <D> +If a parameter name was completed and a following character +(normally a space) automatically +inserted, and the next character typed is one +of those that have to come directly after the name (like `@t{@}}', `@t{:}', +etc.), the automatically added character is deleted, so that the character +typed comes immediately after the parameter name. +Completion in a brace expansion is affected similarly: the added character +is a `@t{,}', which will be removed if `@t{@}}' is typed next. + +@pindex AUTO_PARAM_SLASH +@pindex NO_AUTO_PARAM_SLASH +@pindex AUTOPARAMSLASH +@pindex NOAUTOPARAMSLASH +@item @t{AUTO_PARAM_SLASH} <D> +If a parameter is completed whose content is the name of a directory, +then add a trailing slash instead of a space. + +@pindex AUTO_REMOVE_SLASH +@pindex NO_AUTO_REMOVE_SLASH +@pindex AUTOREMOVESLASH +@pindex NOAUTOREMOVESLASH +@cindex slash, removing trailing +@item @t{AUTO_REMOVE_SLASH} <D> +When the last character resulting from a completion is a slash and the next +character typed is a word delimiter, a slash, or a character that ends +a command (such as a semicolon or an ampersand), remove the slash. + +@pindex BASH_AUTO_LIST +@pindex NO_BASH_AUTO_LIST +@pindex BASHAUTOLIST +@pindex NOBASHAUTOLIST +@cindex completion, listing choices, bash style +@item @t{BASH_AUTO_LIST} +On an ambiguous completion, automatically list choices when the +completion function is called twice in succession. This takes +precedence over @t{AUTO_LIST}. The setting of @t{LIST_AMBIGUOUS} is +respected. If @t{AUTO_MENU} is set, the menu behaviour will then start +with the third press. Note that this will not work with +@t{MENU_COMPLETE}, since repeated completion calls immediately cycle +through the list in that case. + +@pindex COMPLETE_ALIASES +@pindex NO_COMPLETE_ALIASES +@pindex COMPLETEALIASES +@pindex NOCOMPLETEALIASES +@cindex aliases, completion of +@item @t{COMPLETE_ALIASES} +Prevents aliases on the command line from being internally substituted +before completion is attempted. The effect is to make the alias a +distinct command for completion purposes. + +@pindex COMPLETE_IN_WORD +@pindex NO_COMPLETE_IN_WORD +@pindex COMPLETEINWORD +@pindex NOCOMPLETEINWORD +@item @t{COMPLETE_IN_WORD} +If unset, the cursor is set to the end of the word if completion is +started. Otherwise it stays there and completion is done from both ends. + +@pindex GLOB_COMPLETE +@pindex NO_GLOB_COMPLETE +@pindex GLOBCOMPLETE +@pindex NOGLOBCOMPLETE +@item @t{GLOB_COMPLETE} +When the current word has a glob pattern, do not insert all the words +resulting from the expansion but generate matches as for completion and +cycle through them like @t{MENU_COMPLETE}. The matches are generated as if +a `@t{*}' was added to the end of the word, or inserted at the cursor when +@t{COMPLETE_IN_WORD} is set. This actually uses pattern matching, not +globbing, so it works not only for files but for any completion, such as +options, user names, etc. + +@noindent +Note that when the pattern matcher is used, matching control (for example, +case-insensitive or anchored matching) cannot be used. This limitation +only applies when the current word contains a pattern; simply turning +on the @t{GLOB_COMPLETE} option does not have this effect. + +@pindex HASH_LIST_ALL +@pindex NO_HASH_LIST_ALL +@pindex HASHLISTALL +@pindex NOHASHLISTALL +@item @t{HASH_LIST_ALL} <D> +Whenever a command completion or spelling correction is attempted, make +sure the entire command path is hashed first. This makes the first +completion slower but avoids false reports of spelling errors. + +@pindex LIST_AMBIGUOUS +@pindex NO_LIST_AMBIGUOUS +@pindex LISTAMBIGUOUS +@pindex NOLISTAMBIGUOUS +@cindex ambiguous completion +@cindex completion, ambiguous +@item @t{LIST_AMBIGUOUS} <D> +This option works when @t{AUTO_LIST} or @t{BASH_AUTO_LIST} is also +set. If there is an unambiguous prefix to insert on the command line, +that is done without a completion list being displayed; in other +words, auto-listing behaviour only takes place when nothing would be +inserted. In the case of @t{BASH_AUTO_LIST}, this means that the list +will be delayed to the third call of the function. + +@pindex LIST_BEEP +@pindex NO_LIST_BEEP +@pindex LISTBEEP +@pindex NOLISTBEEP +@cindex beep, ambiguous completion +@cindex completion, beep on ambiguous +@item @t{LIST_BEEP} <D> +Beep on an ambiguous completion. More accurately, this forces the +completion widgets to return status 1 on an ambiguous completion, which +causes the shell to beep if the option @t{BEEP} is also set; this may +be modified if completion is called from a user-defined widget. + +@pindex LIST_PACKED +@pindex NO_LIST_PACKED +@pindex LISTPACKED +@pindex NOLISTPACKED +@cindex completion, listing +@item @t{LIST_PACKED} +Try to make the completion list smaller (occupying less lines) by +printing the matches in columns with different widths. + +@pindex LIST_ROWS_FIRST +@pindex NO_LIST_ROWS_FIRST +@pindex LISTROWSFIRST +@pindex NOLISTROWSFIRST +@cindex completion, listing order +@item @t{LIST_ROWS_FIRST} +Lay out the matches in completion lists sorted horizontally, that is, +the second match is to the right of the first one, not under it as +usual. + +@pindex LIST_TYPES +@pindex NO_LIST_TYPES +@pindex LISTTYPES +@pindex NOLISTTYPES +@cindex marking file types +@cindex files, marking type of +@item @t{LIST_TYPES} (@t{-X}) <D> +When listing files that are possible completions, show the +type of each file with a trailing identifying mark. + +@pindex MENU_COMPLETE +@pindex NO_MENU_COMPLETE +@pindex MENUCOMPLETE +@pindex NOMENUCOMPLETE +@cindex completion, menu +@item @t{MENU_COMPLETE} (@t{-Y}) +On an ambiguous completion, instead of listing possibilities or beeping, +insert the first match immediately. Then when completion is requested +again, remove the first match and insert the second match, etc. +When there are no more matches, go back to the first one again. +@t{reverse-menu-complete} may be used to loop through the list +in the other direction. This option overrides @t{AUTO_MENU}. + +@pindex REC_EXACT +@pindex NO_REC_EXACT +@pindex RECEXACT +@pindex NORECEXACT +@cindex completion, exact matches +@item @t{REC_EXACT} (@t{-S}) +If the string on the command line exactly matches one of the possible +completions, it is accepted, even if there is another completion (i.e. that +string with something else added) that also matches. + +@end table + +@noindent + +@subsection Expansion and Globbing +@noindent +@table @asis +@pindex BAD_PATTERN +@pindex NO_BAD_PATTERN +@pindex BADPATTERN +@pindex NOBADPATTERN +@cindex globbing, bad pattern +@cindex filename generation, bad pattern +@item @t{BAD_PATTERN} (@t{+2}) <C> <Z> +If a pattern for filename generation is badly formed, print an error message. +(If this option is unset, the pattern will be left unchanged.) + +@pindex BARE_GLOB_QUAL +@pindex NO_BARE_GLOB_QUAL +@pindex BAREGLOBQUAL +@pindex NOBAREGLOBQUAL +@cindex globbing qualifiers, enable +@cindex enable globbing qualifiers +@item @t{BARE_GLOB_QUAL} <Z> +In a glob pattern, treat a trailing set of parentheses as a qualifier +list, if it contains no `@t{|}', `@t{(}' or (if special) `@t{~}' +characters. See @ref{Filename Generation}. + +@pindex BRACE_CCL +@pindex NO_BRACE_CCL +@pindex BRACECCL +@pindex NOBRACECCL +@cindex brace expansion, extending +@cindex expansion, brace, extending +@item @t{BRACE_CCL} +Expand expressions in braces which would not otherwise undergo brace +expansion to a lexically ordered list of all the characters. See +@ref{Brace Expansion}. + +@pindex CASE_GLOB +@pindex NO_CASE_GLOB +@pindex CASEGLOB +@pindex NOCASEGLOB +@cindex case-insensitive globbing, option +@item @t{CASE_GLOB} <D> +Make globbing (filename generation) sensitive to case. Note that other +uses of patterns are always sensitive to case. If the option is unset, +the presence of any character which is special to filename generation +will cause case-insensitive matching. For example, @t{cvs(/)} +can match the directory @t{CVS} owing to the presence of the globbing flag +(unless the option @t{BARE_GLOB_QUAL} is unset). + +@pindex CASE_MATCH +@pindex NO_CASE_MATCH +@pindex CASEMATCH +@pindex NOCASEMATCH +@cindex case-insensitive regular expression matches, option +@cindex regular expressions, case-insensitive matching, option +@item @t{CASE_MATCH} <D> +Make regular expressions using the @t{zsh/regex} module (including +matches with @t{=~}) sensitive to case. + +@pindex CSH_NULL_GLOB +@pindex NO_CSH_NULL_GLOB +@pindex CSHNULLGLOB +@pindex NOCSHNULLGLOB +@cindex csh, null globbing style +@cindex null globbing style, csh +@cindex globbing, null, style, csh +@item @t{CSH_NULL_GLOB} <C> +If a pattern for filename generation has no matches, +delete the pattern from the argument list; +do not report an error unless all the patterns +in a command have no matches. +Overrides @t{NOMATCH}. + +@pindex EQUALS +@pindex NO_EQUALS +@pindex NOEQUALS +@cindex filename expansion, = +@item @t{EQUALS} <Z> +Perform @t{=} filename expansion. +(See @ref{Filename Expansion}.) + +@pindex EXTENDED_GLOB +@pindex NO_EXTENDED_GLOB +@pindex EXTENDEDGLOB +@pindex NOEXTENDEDGLOB +@cindex globbing, extended +@item @t{EXTENDED_GLOB} +Treat the `@t{#}', `@t{~}' and `@t{^}' characters as part of patterns +for filename generation, etc. (An initial unquoted `@t{~}' +always produces named directory expansion.) + +@pindex FORCE_FLOAT +@pindex NO_FORCE_FLOAT +@pindex FORCEFLOAT +@pindex NOFORCEFLOAT +@cindex floating point, forcing use of +@cindex forcing use of floating point +@item @t{FORCE_FLOAT} +Constants in arithmetic evaluation will be treated as +floating point even without the use of a decimal point; the +values of integer variables will be converted to floating point when +used in arithmetic expressions. Integers in any base will be converted. + +@pindex GLOB +@pindex NO_GLOB +@pindex NOGLOB +@cindex globbing, enabling +@cindex enabling globbing +@item @t{GLOB} (@t{+F}, ksh: @t{+f}) <D> +Perform filename generation (globbing). +(See @ref{Filename Generation}.) + +@pindex GLOB_ASSIGN +@pindex NO_GLOB_ASSIGN +@pindex GLOBASSIGN +@pindex NOGLOBASSIGN +@item @t{GLOB_ASSIGN} <C> +If this option is set, filename generation (globbing) is +performed on the right hand side of scalar parameter assignments of +the form `@var{name}@t{=}@var{pattern} (e.g. `@t{foo=*}'). +If the result has more than one word the parameter will become an array +with those words as arguments. This option is provided for backwards +compatibility only: globbing is always performed on the right hand side +of array assignments of the form `@var{name}@t{=(}@var{value}@t{)}' +(e.g. `@t{foo=(*)}') and this form is recommended for clarity; +with this option set, it is not possible to predict whether the result +will be an array or a scalar. + +@pindex GLOB_DOTS +@pindex NO_GLOB_DOTS +@pindex GLOBDOTS +@pindex NOGLOBDOTS +@cindex globbing, of . files +@item @t{GLOB_DOTS} (@t{-4}) +Do not require a leading `@t{.}' in a filename to be matched explicitly. + +@pindex GLOB_STAR_SHORT +@pindex NO_GLOB_STAR_SHORT +@pindex GLOBSTARSHORT +@pindex NOGLOBSTARSHORT +@cindex globbing, short forms +@cindex globbing, ** special +@item @t{GLOB_STAR_SHORT} +When this option is set and the default zsh-style globbing is in +effect, the pattern `@t{**/*}' can be abbreviated to `@t{**}' and the +pattern `@t{***/*}' can be abbreviated to @t{***}. Hence `@t{**.c}' +finds a file ending in @t{.c} in any subdirectory, and `@t{***.c}' does +the same while also following symbolic links. A @t{/} immediately +after the `@t{**}' or `@t{***}' forces the pattern to be treated as the +unabbreviated form. + +@pindex GLOB_SUBST +@pindex NO_GLOB_SUBST +@pindex GLOBSUBST +@pindex NOGLOBSUBST +@item @t{GLOB_SUBST} <C> <K> <S> +Treat any characters resulting from parameter expansion as being +eligible for filename expansion and filename generation, and any +characters resulting from command substitution as being eligible for +filename generation. Braces (and commas in between) do not become eligible +for expansion. + +@pindex HIST_SUBST_PATTERN +@pindex NO_HIST_SUBST_PATTERN +@pindex HISTSUBSTPATTERN +@pindex NOHISTSUBSTPATTERN +@item @t{HIST_SUBST_PATTERN} +Substitutions using the @t{:s} and @t{:&} history modifiers are performed +with pattern matching instead of string matching. This occurs wherever +history modifiers are valid, including glob qualifiers and parameters. +See +@ref{Modifiers}. + +@pindex IGNORE_BRACES +@pindex NO_IGNORE_BRACES +@pindex IGNOREBRACES +@pindex NOIGNOREBRACES +@cindex disabling brace expansion +@cindex brace expansion, disabling +@cindex expansion, brace, disabling +@item @t{IGNORE_BRACES} (@t{-I}) <S> +Do not perform brace expansion. For historical reasons this +also includes the effect of the @t{IGNORE_CLOSE_BRACES} option. + +@pindex IGNORE_CLOSE_BRACES +@pindex NO_IGNORE_CLOSE_BRACES +@pindex IGNORECLOSEBRACES +@pindex NOIGNORECLOSEBRACES +@item @t{IGNORE_CLOSE_BRACES} +When neither this option nor @t{IGNORE_BRACES} is set, a sole +close brace character `@t{@}}' is syntactically significant at any +point on a command line. This has the effect that no semicolon +or newline is necessary before the brace terminating a function +or current shell construct. When either option is set, a closing brace +is syntactically significant only in command position. Unlike +@t{IGNORE_BRACES}, this option does not disable brace expansion. + +@noindent +For example, with both options unset a function may be defined +in the following fashion: + +@noindent +@example +args() @{ echo $# @} +@end example + +@noindent +while if either option is set, this does not work and something +equivalent to the following is required: + +@noindent +@example +args() @{ echo $#; @} +@end example + +@noindent + +@pindex KSH_GLOB +@pindex NO_KSH_GLOB +@pindex KSHGLOB +@pindex NOKSHGLOB +@item @t{KSH_GLOB} <K> +In pattern matching, the interpretation of parentheses is affected by +a preceding `@t{@@}', `@t{*}', `@t{+}', `@t{?}' or `@t{!}'. +See @ref{Filename Generation}. + +@pindex MAGIC_EQUAL_SUBST +@pindex NO_MAGIC_EQUAL_SUBST +@pindex MAGICEQUALSUBST +@pindex NOMAGICEQUALSUBST +@item @t{MAGIC_EQUAL_SUBST} +All unquoted arguments of the form `@var{anything}@t{=}@var{expression}' +appearing after the command name have filename expansion (that is, +where @var{expression} has a leading `@t{~}' or `@t{=}') performed on +@var{expression} as if it were a parameter assignment. The argument is +not otherwise treated specially; it is passed to the command as a single +argument, and not used as an actual parameter assignment. For example, in +@t{echo foo=~/bar:~/rod}, both occurrences of @t{~} would be replaced. +Note that this happens anyway with @t{typeset} and similar statements. + +@noindent +This option respects the setting of the @t{KSH_TYPESET} option. In other +words, if both options are in effect, arguments looking like +assignments will not undergo word splitting. + +@pindex MARK_DIRS +@pindex NO_MARK_DIRS +@pindex MARKDIRS +@pindex NOMARKDIRS +@cindex directories, marking +@cindex marking directories +@item @t{MARK_DIRS} (@t{-8}, ksh: @t{-X}) +Append a trailing `@t{/}' to all directory +names resulting from filename generation (globbing). + +@pindex MULTIBYTE +@pindex NO_MULTIBYTE +@pindex NOMULTIBYTE +@cindex characters, multibyte, in expansion and globbing +@cindex multibyte characters, in expansion and globbing +@item @t{MULTIBYTE} <D> +Respect multibyte characters when found in strings. +When this option is set, strings are examined using the +system library to determine how many bytes form a character, depending +on the current locale. This affects the way characters are counted in +pattern matching, parameter values and various delimiters. + +@noindent +The option is on by default if the shell was compiled with +@t{MULTIBYTE_SUPPORT}; otherwise it is off by default and has no effect +if turned on. + +@noindent +If the option is off a single byte is always treated as a single +character. This setting is designed purely for examining strings +known to contain raw bytes or other values that may not be characters +in the current locale. It is not necessary to unset the option merely +because the character set for the current locale does not contain multibyte +characters. + +@noindent +The option does not affect the shell's editor, which always uses the +locale to determine multibyte characters. This is because +the character set displayed by the terminal emulator is independent of +shell settings. + +@pindex NOMATCH +@pindex NO_NOMATCH +@pindex NONOMATCH +@cindex globbing, no matches +@item @t{NOMATCH} (@t{+3}) <C> <Z> +If a pattern for filename generation has no matches, +print an error, instead of +leaving it unchanged in the argument list. +This also applies to file expansion +of an initial `@t{~}' or `@t{=}'. + +@pindex NULL_GLOB +@pindex NO_NULL_GLOB +@pindex NULLGLOB +@pindex NONULLGLOB +@cindex globbing, no matches +@item @t{NULL_GLOB} (@t{-G}) +If a pattern for filename generation has no matches, +delete the pattern from the argument list instead +of reporting an error. Overrides @t{NOMATCH}. + +@pindex NUMERIC_GLOB_SORT +@pindex NO_NUMERIC_GLOB_SORT +@pindex NUMERICGLOBSORT +@pindex NONUMERICGLOBSORT +@cindex globbing, sorting numerically +@item @t{NUMERIC_GLOB_SORT} +If numeric filenames are matched by a filename generation pattern, +sort the filenames numerically rather than lexicographically. + +@pindex RC_EXPAND_PARAM +@pindex NO_RC_EXPAND_PARAM +@pindex RCEXPANDPARAM +@pindex NORCEXPANDPARAM +@cindex rc, parameter expansion style +@cindex parameter expansion style, rc +@item @t{RC_EXPAND_PARAM} (@t{-P}) +Array expansions of the form +`@var{foo}@t{$@{}@var{xx}@t{@}}@var{bar}', where the parameter +@var{xx} is set to @t{(}@var{a b c}@t{)}, are substituted with +`@var{fooabar foobbar foocbar}' instead of the default +`@var{fooa b cbar}'. Note that an empty array will therefore cause +all arguments to be removed. + +@pindex REMATCH_PCRE +@pindex NO_REMATCH_PCRE +@pindex REMATCHPCRE +@pindex NOREMATCHPCRE +@cindex regexp, PCRE +@cindex PCRE, regexp +@item @t{REMATCH_PCRE} +If set, regular expression matching with the @t{=~} operator will use +Perl-Compatible Regular Expressions from the PCRE library. +(The @t{zsh/pcre} module must be available.) +If not set, regular expressions will use the extended regexp syntax +provided by the system libraries. + +@pindex SH_GLOB +@pindex NO_SH_GLOB +@pindex SHGLOB +@pindex NOSHGLOB +@cindex sh, globbing style +@cindex globbing style, sh +@item @t{SH_GLOB} <K> <S> +Disables the special meaning of `@t{(}', `@t{|}', `@t{)}' +and '@t{<}' for globbing the result of parameter and command substitutions, +and in some other places where +the shell accepts patterns. If @t{SH_GLOB} is set but @t{KSH_GLOB} is +not, the shell allows the interpretation of +subshell expressions enclosed in parentheses in some cases where there +is no space before the opening parenthesis, e.g. @t{!(true)} +is interpreted as if there were a space after the @t{!}. This option is +set by default if zsh is invoked as @t{sh} or @t{ksh}. + +@pindex UNSET +@pindex NO_UNSET +@pindex NOUNSET +@cindex parameters, substituting unset +@cindex unset parameters, substituting +@item @t{UNSET} (@t{+u}, ksh: @t{+u}) <K> <S> <Z> +Treat unset parameters as if they were empty when substituting, and as if +they were zero when reading their values in arithmetic expansion and +arithmetic commands. +Otherwise they are treated as an error. + +@pindex WARN_CREATE_GLOBAL +@pindex NO_WARN_CREATE_GLOBAL +@pindex WARNCREATEGLOBAL +@pindex NOWARNCREATEGLOBAL +@cindex parameters, warning when created globally +@item @t{WARN_CREATE_GLOBAL} +Print a warning message when a global parameter is created in a function +by an assignment or in math context. +This often indicates that a parameter has not been +declared local when it should have been. Parameters explicitly declared +global from within a function using @t{typeset -g} do not cause a warning. +Note that there is no warning when a local parameter is assigned to in +a nested function, which may also indicate an error. + +@pindex WARN_NESTED_VAR +@pindex NO_WARN_NESTED_VAR +@pindex WARNNESTEDVAR +@pindex NO_WARNNESTEDVAR +@cindex parameters, warning when setting in enclosing scope +@item @t{WARN_NESTED_VAR} +Print a warning message when an existing parameter from an +enclosing function scope, or global, is set in a function +by an assignment or in math context. Assignment to shell +special parameters does not cause a warning. This is the companion +to @t{WARN_CREATE_GLOBAL} as in this case the warning is only +printed when a parameter is @emph{not} created. Where possible, +use of @t{typeset -g} to set the parameter suppresses the error, +but note that this needs to be used every time the parameter is set. +To restrict the effect of this option to a single function scope, +use `@t{functions -W}'. + +@noindent +For example, the following code produces a warning for the assignment +inside the function @t{nested} as that overrides the value within +@t{toplevel} + +@noindent +@example +toplevel() @{ + local foo="in fn" + nested +@} +nested() @{ + foo="in nested" +@} +setopt warn_nested_var +toplevel +@end example + +@end table + +@noindent + +@subsection History +@noindent +@table @asis +@pindex APPEND_HISTORY +@pindex NO_APPEND_HISTORY +@pindex APPENDHISTORY +@pindex NOAPPENDHISTORY +@cindex history, appending to a file +@item @t{APPEND_HISTORY} <D> +If this is set, zsh sessions will append their history list to +the history file, rather than replace it. Thus, multiple parallel +zsh sessions will all have the new entries from their history lists +added to the history file, in the order that they exit. +The file will still be periodically re-written to trim it when the +number of lines grows 20% beyond the value specified by +@t{$SAVEHIST} (see also the @t{HIST_SAVE_BY_COPY} option). + +@pindex BANG_HIST +@pindex NO_BANG_HIST +@pindex BANGHIST +@pindex NOBANGHIST +@cindex history, enable substitution +@cindex enable history substitution +@item @t{BANG_HIST} (@t{+K}) <C> <Z> +Perform textual history expansion, @cite{csh}-style, +treating the character `@t{!}' specially. + +@pindex EXTENDED_HISTORY +@pindex NO_EXTENDED_HISTORY +@pindex EXTENDEDHISTORY +@pindex NOEXTENDEDHISTORY +@cindex history, timestamping +@item @t{EXTENDED_HISTORY} <C> +Save each command's beginning timestamp (in seconds since the epoch) +and the duration (in seconds) to the history file. The format of +this prefixed data is: + +@noindent +`@t{: }@var{<beginning time>}@t{:}@var{<elapsed seconds>}@t{;}@var{<command>}'. + +@pindex HIST_ALLOW_CLOBBER +@pindex NO_HIST_ALLOW_CLOBBER +@pindex HISTALLOWCLOBBER +@pindex NOHISTALLOWCLOBBER +@item @t{HIST_ALLOW_CLOBBER} +Add `@t{|}' to output redirections in the history. This allows history +references to clobber files even when @t{CLOBBER} is unset. + +@pindex HIST_BEEP +@pindex NO_HIST_BEEP +@pindex HISTBEEP +@pindex NOHISTBEEP +@cindex history beeping +@cindex beep, history +@item @t{HIST_BEEP} <D> +Beep in ZLE when a widget attempts to access a history entry which +isn't there. + +@pindex HIST_EXPIRE_DUPS_FIRST +@pindex NO_HIST_EXPIRE_DUPS_FIRST +@pindex HISTEXPIREDUPSFIRST +@pindex NOHISTEXPIREDUPSFIRST +@cindex history, expiring duplicates +@item @t{HIST_EXPIRE_DUPS_FIRST} +If the internal history needs to be trimmed to add the current command line, +setting this option will cause the oldest history event that has a duplicate +to be lost before losing a unique event from the list. +You should be sure to set the value of @t{HISTSIZE} to a larger number +than @t{SAVEHIST} in order to give you some room for the duplicated +events, otherwise this option will behave just like +@t{HIST_IGNORE_ALL_DUPS} once the history fills up with unique events. + +@pindex HIST_FCNTL_LOCK +@pindex NO_HIST_FCNTL_LOCK +@pindex HISTFCNTLLOCK +@pindex NOHISTFCNTLLOCK +@item @t{HIST_FCNTL_LOCK} +When writing out the history file, by default zsh uses ad-hoc file locking +to avoid known problems with locking on some operating systems. With this +option locking is done by means of the system's @t{fcntl} call, where +this method is available. On recent operating systems this may +provide better performance, in particular avoiding history corruption when +files are stored on NFS. + +@pindex HIST_FIND_NO_DUPS +@pindex NO_HIST_FIND_NO_DUPS +@pindex HISTFINDNODUPS +@pindex NOHISTFINDNODUPS +@cindex history, ignoring duplicates in search +@item @t{HIST_FIND_NO_DUPS} +When searching for history entries in the line editor, do not display +duplicates of a line previously found, even if the duplicates are not +contiguous. + +@pindex HIST_IGNORE_ALL_DUPS +@pindex NO_HIST_IGNORE_ALL_DUPS +@pindex HISTIGNOREALLDUPS +@pindex NOHISTIGNOREALLDUPS +@cindex history, ignoring all duplicates +@item @t{HIST_IGNORE_ALL_DUPS} +If a new command line being added to the history list duplicates an +older one, the older command is removed from the list (even if it is +not the previous event). + +@pindex HIST_IGNORE_DUPS +@pindex NO_HIST_IGNORE_DUPS +@pindex HISTIGNOREDUPS +@pindex NOHISTIGNOREDUPS +@cindex history, ignoring duplicates +@item @t{HIST_IGNORE_DUPS} (@t{-h}) +Do not enter command lines into the history list +if they are duplicates of the previous event. + +@pindex HIST_IGNORE_SPACE +@pindex NO_HIST_IGNORE_SPACE +@pindex HISTIGNORESPACE +@pindex NOHISTIGNORESPACE +@cindex history, ignoring spaces +@item @t{HIST_IGNORE_SPACE} (@t{-g}) +Remove command lines from the history list when the first character on +the line is a space, or when one of the expanded aliases contains a +leading space. Only normal aliases (not global or suffix aliases) +have this behaviour. +Note that the command lingers in the internal history until the next +command is entered before it vanishes, allowing you to briefly reuse +or edit the line. If you want to make it vanish right away without +entering another command, type a space and press return. + +@pindex HIST_LEX_WORDS +@pindex NO_HIST_LEX_WORDS +@pindex HISTLEXWORDS +@pindex NOHISTLEXWORDS +@item @t{HIST_LEX_WORDS} +By default, shell history that is read in from files is split into +words on all white space. This means that arguments with quoted +whitespace are not correctly handled, with the consequence that +references to words in history lines that have been read from a file +may be inaccurate. When this option is set, words read in from a +history file are divided up in a similar fashion to normal shell +command line handling. Although this produces more accurately delimited +words, if the size of the history file is large this can be slow. Trial +and error is necessary to decide. + +@pindex HIST_NO_FUNCTIONS +@pindex NO_HIST_NO_FUNCTIONS +@pindex HISTNOFUNCTIONS +@pindex NOHISTNOFUNCTIONS +@item @t{HIST_NO_FUNCTIONS} +Remove function definitions from the history list. +Note that the function lingers in the internal history until the next +command is entered before it vanishes, allowing you to briefly reuse +or edit the definition. + +@pindex HIST_NO_STORE +@pindex NO_HIST_NO_STORE +@pindex HISTNOSTORE +@pindex NOHISTNOSTORE +@item @t{HIST_NO_STORE} +Remove the @t{history} (@t{fc -l}) command from the history list +when invoked. +Note that the command lingers in the internal history until the next +command is entered before it vanishes, allowing you to briefly reuse +or edit the line. + +@pindex HIST_REDUCE_BLANKS +@pindex NO_HIST_REDUCE_BLANKS +@pindex HISTREDUCEBLANKS +@pindex NOHISTREDUCEBLANKS +@item @t{HIST_REDUCE_BLANKS} +Remove superfluous blanks from each command line +being added to the history list. + +@pindex HIST_SAVE_BY_COPY +@pindex NO_HIST_SAVE_BY_COPY +@pindex HISTSAVEBYCOPY +@pindex NOHISTSAVEBYCOPY +@item @t{HIST_SAVE_BY_COPY} <D> +When the history file is re-written, we normally write out a copy of +the file named @t{$HISTFILE.new} and then rename it over the old one. +However, if this option is unset, we instead truncate the old +history file and write out the new version in-place. If one of the +history-appending options is enabled, this option only has an effect +when the enlarged history file needs to be re-written to trim it +down to size. Disable this only if you have special needs, as doing +so makes it possible to lose history entries if zsh gets interrupted +during the save. + +@noindent +When writing out a copy of the history file, zsh preserves the old +file's permissions and group information, but will refuse to write +out a new file if it would change the history file's owner. + +@pindex HIST_SAVE_NO_DUPS +@pindex NO_HIST_SAVE_NO_DUPS +@pindex HISTSAVENODUPS +@pindex NOHISTSAVENODUPS +@item @t{HIST_SAVE_NO_DUPS} +When writing out the history file, older commands that duplicate +newer ones are omitted. + +@pindex HIST_VERIFY +@pindex NO_HIST_VERIFY +@pindex HISTVERIFY +@pindex NOHISTVERIFY +@cindex history, verifying substitution +@item @t{HIST_VERIFY} +Whenever the user enters a line with history expansion, +don't execute the line directly; instead, perform +history expansion and reload the line into the editing buffer. + +@pindex INC_APPEND_HISTORY +@pindex NO_INC_APPEND_HISTORY +@pindex INCAPPENDHISTORY +@pindex NOINCAPPENDHISTORY +@cindex history, incremental appending to a file +@item @t{INC_APPEND_HISTORY} +This option works like @t{APPEND_HISTORY} except that new history lines +are added to the @t{$HISTFILE} incrementally (as soon as they are +entered), rather than waiting until the shell exits. +The file will still be periodically re-written to trim it when the +number of lines grows 20% beyond the value specified by +@t{$SAVEHIST} (see also the @t{HIST_SAVE_BY_COPY} option). + +@pindex INC_APPEND_HISTORY_TIME +@pindex NO_INC_APPEND_HISTORY_TIME +@pindex INCAPPENDHISTORYTIME +@pindex NOINCAPPENDHISTORYTIME +@cindex history, incremental appending to a file with time +@item @t{INC_APPEND_HISTORY_TIME} +This option is a variant of @t{INC_APPEND_HISTORY} in which, where +possible, the history entry is written out to the file after the +command is finished, so that the time taken by the command is recorded +correctly in the history file in @t{EXTENDED_HISTORY} format. This +means that the history entry will not be available immediately from +other instances of the shell that are using the same history file. + +@noindent +This option is only useful if @t{INC_APPEND_HISTORY} and +@t{SHARE_HISTORY} are turned off. The three options should be +considered mutually exclusive. + +@pindex SHARE_HISTORY +@pindex NO_SHARE_HISTORY +@pindex SHAREHISTORY +@pindex NOSHAREHISTORY +@cindex share history +@cindex history, sharing +@item @t{SHARE_HISTORY} <K> + +@noindent +This option both imports new commands from the history file, and also +causes your typed commands to be appended to the history file (the +latter is like specifying @t{INC_APPEND_HISTORY}, which should be turned +off if this option is in effect). The history lines are also output +with timestamps ala @t{EXTENDED_HISTORY} (which makes it easier to find +the spot where we left off reading the file after it gets re-written). + +@noindent +By default, history movement commands visit the imported lines as +well as the local lines, but you can toggle this on and off with the +set-local-history zle binding. It is also possible to create a zle +widget that will make some commands ignore imported commands, and +some include them. + +@noindent +If you find that you want more control over when commands +get imported, you may wish to turn @t{SHARE_HISTORY} off, +@t{INC_APPEND_HISTORY} or @t{INC_APPEND_HISTORY_TIME} (see above) on, +and then manually import commands whenever you need them using `@t{fc +-RI}'. + +@end table + +@noindent + +@subsection Initialisation +@noindent +@table @asis +@pindex ALL_EXPORT +@pindex NO_ALL_EXPORT +@pindex ALLEXPORT +@pindex NOALLEXPORT +@cindex export, automatic +@item @t{ALL_EXPORT} (@t{-a}, ksh: @t{-a}) +All parameters subsequently defined are automatically exported. + +@pindex GLOBAL_EXPORT +@pindex NO_GLOBAL_EXPORT +@pindex GLOBALEXPORT +@pindex NOGLOBALEXPORT +@cindex environment, and local parameters +@item @t{GLOBAL_EXPORT} <Z> +If this option is set, passing the @t{-x} flag to the builtins @t{declare}, +@t{float}, @t{integer}, @t{readonly} and @t{typeset} (but not @t{local}) +will also set the @t{-g} flag; hence parameters exported to +the environment will not be made local to the enclosing function, unless +they were already or the flag @t{+g} is given explicitly. If the option is +unset, exported parameters will be made local in just the same way as any +other parameter. + +@noindent +This option is set by default for backward compatibility; it is not +recommended that its behaviour be relied upon. Note that the builtin +@t{export} always sets both the @t{-x} and @t{-g} flags, and hence its +effect extends beyond the scope of the enclosing function; this is the +most portable way to achieve this behaviour. + +@cindex exporting, and local parameters +@pindex GLOBAL_RCS +@pindex NO_GLOBAL_RCS +@pindex GLOBALRCS +@pindex NOGLOBALRCS +@cindex startup files, global, inhibiting +@cindex files, global startup, inhibiting +@item @t{GLOBAL_RCS} (@t{-d}) <D> +If this option is unset, the startup files @t{/etc/zprofile}, +@t{/etc/zshrc}, @t{/etc/zlogin} and @t{/etc/zlogout} will not be run. It +can be disabled and re-enabled at any time, including inside local startup +files (@t{.zshrc}, etc.). + +@pindex RCS +@pindex NO_RCS +@pindex NORCS +@cindex startup files, sourcing +@item @t{RCS} (@t{+f}) <D> +After @t{/etc/zshenv} is sourced on startup, source the +@t{.zshenv}, @t{/etc/zprofile}, @t{.zprofile}, +@t{/etc/zshrc}, @t{.zshrc}, @t{/etc/zlogin}, @t{.zlogin}, and @t{.zlogout} +files, as described in @ref{Files}. +If this option is unset, the @t{/etc/zshenv} file is still sourced, but any +of the others will not be; it can be set at any time to prevent the +remaining startup files after the currently executing one from +being sourced. + +@end table + +@noindent + +@subsection Input/Output +@noindent +@table @asis +@pindex ALIASES +@pindex NO_ALIASES +@pindex NOALIASES +@cindex aliases, expansion +@item @t{ALIASES} <D> +Expand aliases. + +@pindex CLOBBER +@pindex NO_CLOBBER +@pindex NOCLOBBER +@cindex clobbering, of files +@cindex file clobbering, allowing +@item @t{CLOBBER} (@t{+C}, ksh: @t{+C}) <D> +Allows `@t{>}' redirection to truncate existing files. +Otherwise `@t{>!}' or `@t{>|}' must be used to truncate a file. + +@noindent +If the option is not set, and the option @t{APPEND_CREATE} is also +not set, `@t{>>!}' or `@t{>>|}' must be used to create a file. +If either option is set, `@t{>>}' may be used. + +@pindex CORRECT +@pindex NO_CORRECT +@pindex NOCORRECT +@cindex correction, spelling +@cindex spelling correction +@item @t{CORRECT} (@t{-0}) +Try to correct the spelling of commands. +Note that, when the @t{HASH_LIST_ALL} option is not set or when some +directories in the path are not readable, this may falsely report spelling +errors the first time some commands are used. + +@noindent +The shell variable @t{CORRECT_IGNORE} may be set to a pattern to +match words that will never be offered as corrections. + +@pindex CORRECT_ALL +@pindex NO_CORRECT_ALL +@pindex CORRECTALL +@pindex NOCORRECTALL +@item @t{CORRECT_ALL} (@t{-O}) +Try to correct the spelling of all arguments in a line. + +@noindent +The shell variable @t{CORRECT_IGNORE_FILE} may be set to a pattern to +match file names that will never be offered as corrections. + +@pindex DVORAK +@pindex NO_DVORAK +@pindex NODVORAK +@item @t{DVORAK} +Use the Dvorak keyboard instead of the standard qwerty keyboard as a basis +for examining spelling mistakes for the @t{CORRECT} and @t{CORRECT_ALL} +options and the @t{spell-word} editor command. + +@pindex FLOW_CONTROL +@pindex NO_FLOW_CONTROL +@pindex FLOWCONTROL +@pindex NOFLOWCONTROL +@cindex flow control +@item @t{FLOW_CONTROL} <D> +If this option is unset, +output flow control via start/stop characters (usually assigned to +^S/^Q) is disabled in the shell's editor. + +@pindex IGNORE_EOF +@pindex NO_IGNORE_EOF +@pindex IGNOREEOF +@pindex NOIGNOREEOF +@cindex EOF, ignoring +@item @t{IGNORE_EOF} (@t{-7}) +Do not exit on end-of-file. Require the use +of @t{exit} or @t{logout} instead. +However, ten consecutive EOFs will cause the shell to exit anyway, +to avoid the shell hanging if its tty goes away. + +@noindent +Also, if this option is set and the Zsh Line Editor is used, widgets +implemented by shell functions can be bound to EOF (normally +Control-D) without printing the normal warning message. This works +only for normal widgets, not for completion widgets. + +@pindex INTERACTIVE_COMMENTS +@pindex NO_INTERACTIVE_COMMENTS +@pindex INTERACTIVECOMMENTS +@pindex NOINTERACTIVECOMMENTS +@cindex comments, in interactive shells +@item @t{INTERACTIVE_COMMENTS} (@t{-k}) <K> <S> +Allow comments even in interactive shells. + +@pindex HASH_CMDS +@pindex NO_HASH_CMDS +@pindex HASHCMDS +@pindex NOHASHCMDS +@cindex hashing, of commands +@cindex command hashing +@item @t{HASH_CMDS} <D> +Note the location of each command the first time it is executed. +Subsequent invocations of the same command will use the +saved location, avoiding a path search. +If this option is unset, no path hashing is done at all. +However, when @t{CORRECT} is set, commands whose names do not appear in +the functions or aliases hash tables are hashed in order to avoid +reporting them as spelling errors. + +@pindex HASH_DIRS +@pindex NO_HASH_DIRS +@pindex HASHDIRS +@pindex NOHASHDIRS +@cindex hashing, of directories +@cindex directories, hashing +@item @t{HASH_DIRS} <D> +Whenever a command name is hashed, hash the directory containing it, +as well as all directories that occur earlier in the path. +Has no effect if neither @t{HASH_CMDS} nor @t{CORRECT} is set. + +@pindex HASH_EXECUTABLES_ONLY +@pindex NO_HASH_EXECUTABLES_ONLY +@pindex HASHEXECUTABLESONLY +@pindex NOHASHEXECUTABLESONLY +@cindex hashing, of executables +@cindex executables, hashing +@item @t{HASH_EXECUTABLES_ONLY} +When hashing commands because of @t{HASH_CMDS}, check that the +file to be hashed is actually an executable. This option +is unset by default as if the path contains a large number of commands, +or consists of many remote files, the additional tests can take +a long time. Trial and error is needed to show if this option is +beneficial. + +@pindex MAIL_WARNING +@pindex NO_MAIL_WARNING +@pindex MAILWARNING +@pindex NOMAILWARNING +@cindex mail, warning of reading +@item @t{MAIL_WARNING} (@t{-U}) +Print a warning message if a mail file has been +accessed since the shell last checked. + +@pindex PATH_DIRS +@pindex NO_PATH_DIRS +@pindex PATHDIRS +@pindex NOPATHDIRS +@cindex path search, extended +@item @t{PATH_DIRS} (@t{-Q}) +Perform a path search even on command names with slashes in them. +Thus if `@t{/usr/local/bin}' is in the user's path, and he or she types +`@t{X11/xinit}', the command `@t{/usr/local/bin/X11/xinit}' will be executed +(assuming it exists). +Commands explicitly beginning with `@t{/}', `@t{./}' or `@t{../}' +are not subject to the path search. +This also applies to the `@t{.}' and @t{source} builtins. + +@noindent +Note that subdirectories of the current directory are always searched for +executables specified in this form. This takes place before any search +indicated by this option, and regardless of whether `@t{.}' or the current +directory appear in the command search path. + +@pindex PATH_SCRIPT +@pindex NO_PATH_SCRIPT +@pindex PATHSCRIPT +@pindex NOPATHSCRIPT +@cindex path search, for script argument to shell +@item @t{PATH_SCRIPT} <K> <S> +If this option is not set, a script passed as the first non-option argument +to the shell must contain the name of the file to open. If this +option is set, and the script does not specify a directory path, +the script is looked for first in the current directory, then in the +command path. See +@ref{Invocation}. + +@pindex PRINT_EIGHT_BIT +@pindex NO_PRINT_EIGHT_BIT +@pindex PRINTEIGHTBIT +@pindex NOPRINTEIGHTBIT +@cindex eight bit characters, printing +@item @t{PRINT_EIGHT_BIT} +Print eight bit characters literally in completion lists, etc. +This option is not necessary if your system correctly returns the +printability of eight bit characters (see man page ctype(3)). + +@pindex PRINT_EXIT_VALUE +@pindex NO_PRINT_EXIT_VALUE +@pindex PRINTEXITVALUE +@pindex NOPRINTEXITVALUE +@cindex exit status, printing +@item @t{PRINT_EXIT_VALUE} (@t{-1}) +Print the exit value of programs with non-zero exit status. +This is only available at the command line in interactive shells. + +@pindex RC_QUOTES +@pindex NO_RC_QUOTES +@pindex RCQUOTES +@pindex NORCQUOTES +@cindex rc, quoting style +@cindex quoting style, rc +@item @t{RC_QUOTES} +Allow the character sequence `@t{@value{dsq}}' to signify a single quote +within singly quoted strings. Note this does not apply in quoted strings +using the format @t{$'}@var{...}@t{'}, where a backslashed single quote can +be used. + +@pindex RM_STAR_SILENT +@pindex NO_RM_STAR_SILENT +@pindex RMSTARSILENT +@pindex NORMSTARSILENT +@cindex rm *, querying before +@cindex querying before rm * +@item @t{RM_STAR_SILENT} (@t{-H}) <K> <S> +Do not query the user before executing `@t{rm *}' or `@t{rm path/*}'. + +@pindex RM_STAR_WAIT +@pindex NO_RM_STAR_WAIT +@pindex RMSTARWAIT +@pindex NORMSTARWAIT +@cindex rm *, waiting before +@cindex waiting before rm * +@item @t{RM_STAR_WAIT} +If querying the user before executing `@t{rm *}' or `@t{rm path/*}', +first wait ten seconds and ignore anything typed in that time. +This avoids the problem of reflexively answering `yes' to the query +when one didn't really mean it. The wait and query can always be +avoided by expanding the `@t{*}' in ZLE (with tab). + +@pindex SHORT_LOOPS +@pindex NO_SHORT_LOOPS +@pindex SHORTLOOPS +@pindex NOSHORTLOOPS +@item @t{SHORT_LOOPS} <C> <Z> +Allow the short forms of @t{for}, @t{repeat}, @t{select}, +@t{if}, and @t{function} constructs. + +@pindex SUN_KEYBOARD_HACK +@pindex NO_SUN_KEYBOARD_HACK +@pindex SUNKEYBOARDHACK +@pindex NOSUNKEYBOARDHACK +@cindex sun keyboard, annoying +@cindex annoying keyboard, sun +@item @t{SUN_KEYBOARD_HACK} (@t{-L}) +If a line ends with a backquote, and there are an odd number +of backquotes on the line, ignore the trailing backquote. +This is useful on some keyboards where the return key is +too small, and the backquote key lies annoyingly close to it. +As an alternative the variable @t{KEYBOARD_HACK} lets you choose the +character to be removed. + +@end table + +@noindent + +@subsection Job Control +@noindent +@table @asis +@pindex AUTO_CONTINUE +@pindex NO_AUTO_CONTINUE +@pindex AUTOCONTINUE +@pindex NOAUTOCONTINUE +@cindex jobs, continuing automatically +@cindex continuing jobs automatically +@item @t{AUTO_CONTINUE} +With this option set, stopped jobs that are removed from the job table +with the @t{disown} builtin command are automatically sent a @t{CONT} +signal to make them running. + +@pindex AUTO_RESUME +@pindex NO_AUTO_RESUME +@pindex AUTORESUME +@pindex NOAUTORESUME +@cindex jobs, resuming automatically +@cindex resuming jobs automatically +@item @t{AUTO_RESUME} (@t{-W}) +Treat single word simple commands without redirection +as candidates for resumption of an existing job. + +@pindex BG_NICE +@pindex NO_BG_NICE +@pindex BGNICE +@pindex NOBGNICE +@cindex jobs, background priority +@cindex background jobs, priority of +@cindex priority of background jobs +@item @t{BG_NICE} (@t{-6}) <C> <Z> +Run all background jobs at a lower priority. This option +is set by default. + +@pindex CHECK_JOBS +@pindex NO_CHECK_JOBS +@pindex CHECKJOBS +@pindex NOCHECKJOBS +@cindex exiting, checking jobs when +@cindex logging out, checking jobs when +@item @t{CHECK_JOBS} <Z> +Report the status of background and suspended jobs before exiting a shell +with job control; a second attempt to exit the shell will succeed. +@t{NO_CHECK_JOBS} is best used only in combination with @t{NO_HUP}, else +such jobs will be killed automatically. + +@noindent +The check is omitted if the commands run from the previous command line +included a `@t{jobs}' command, since it is assumed the user is aware that +there are background or suspended jobs. A `@t{jobs}' command run from one +of the hook functions defined in +the section Special Functions in @ref{Functions} +is not counted for this purpose. + +@pindex CHECK_RUNNING_JOBS +@pindex NO_CHECK_RUNNING_JOBS +@pindex CHECKRUNNINGJOBS +@pindex NOCHECKRUNNINGJOBS +@cindex exiting, checking running jobs when +@cindex logging out, checking running jobs when +@item @t{CHECK_RUNNING_JOBS} <Z> +Check for both running and suspended jobs when @t{CHECK_JOBS} is enabled. +When this option is disabled, zsh checks only for suspended jobs, which +matches the default behavior of bash. + +@noindent +This option has no effect unless @t{CHECK_JOBS} is set. + +@pindex HUP +@pindex NO_HUP +@pindex NOHUP +@cindex jobs, HUP +@item @t{HUP} <Z> +Send the @t{HUP} signal to running jobs when the +shell exits. + +@pindex LONG_LIST_JOBS +@pindex NO_LONG_LIST_JOBS +@pindex LONGLISTJOBS +@pindex NOLONGLISTJOBS +@cindex jobs, list format +@item @t{LONG_LIST_JOBS} (@t{-R}) +Print job notifications in the long format by default. + +@pindex MONITOR +@pindex NO_MONITOR +@pindex NOMONITOR +@cindex job control, allowing +@item @t{MONITOR} (@t{-m}, ksh: @t{-m}) +Allow job control. Set by default in interactive shells. + +@pindex NOTIFY +@pindex NO_NOTIFY +@pindex NONOTIFY +@cindex background jobs, notification +@cindex notification of background jobs +@item @t{NOTIFY} (@t{-5}, ksh: @t{-b}) <Z> +Report the status of background jobs immediately, rather than +waiting until just before printing a prompt. + +@pindex POSIX_JOBS +@pindex POSIXJOBS +@pindex NO_POSIX_JOBS +@pindex NOPOSIXJOBS +@cindex bg, output in POSIX format +@cindex fg, output in POSIX format +@cindex job control, in subshell +@cindex jobs, output in subshell +@item @t{POSIX_JOBS} <K> <S> +This option makes job control more compliant with the POSIX standard. + +@noindent +When the option is not set, the @t{MONITOR} option is unset on entry to +subshells, so that job control is no longer active. When the option is +set, the @t{MONITOR} option and job control remain active in the +subshell, but note that the subshell has no access to jobs in the parent +shell. + +@noindent +When the option is not set, jobs put in the background or foreground +with @t{bg} or @t{fg} are displayed with the same information that would +be reported by @t{jobs}. When the option is set, only the text is +printed. The output from @t{jobs} itself is not affected by the option. + +@noindent +When the option is not set, job information from the parent +shell is saved for output within a subshell (for example, within a +pipeline). When the option is set, the output of @t{jobs} is empty +until a job is started within the subshell. + +@noindent +In previous versions of the shell, it was necessary to enable +@t{POSIX_JOBS} in order for the builtin command @t{wait} to return the +status of background jobs that had already exited. This is no longer +the case. + +@end table + +@noindent + +@subsection Prompting +@noindent +@table @asis +@pindex PROMPT_BANG +@pindex NO_PROMPT_BANG +@pindex PROMPTBANG +@pindex NOPROMPTBANG +@cindex prompt, ! expansion +@item @t{PROMPT_BANG} <K> +If set, `@t{!}' is treated specially in prompt expansion. +See +@ref{Prompt Expansion}. + +@pindex PROMPT_CR +@pindex NO_PROMPT_CR +@pindex PROMPTCR +@pindex NOPROMPTCR +@cindex prompt, with CR +@item @t{PROMPT_CR} (@t{+V}) <D> +Print a carriage return just before printing +a prompt in the line editor. This is on by default as multi-line editing +is only possible if the editor knows where the start of the line appears. + +@pindex PROMPT_SP +@pindex NO_PROMPT_SP +@pindex PROMPTSP +@pindex NOPROMPTSP +@cindex prompt, save partial lines +@item @t{PROMPT_SP} <D> +Attempt to preserve a partial line (i.e. a line that did not end with a +newline) that would otherwise be covered up by the command prompt due to +the @t{PROMPT_CR} option. This works by outputting some cursor-control +characters, including a series of spaces, that should make the terminal +wrap to the next line when a partial line is present (note that this is +only successful if your terminal has automatic margins, which is typical). + +@noindent +When a partial line is preserved, by default you will see an inverse+bold +character at the end of the partial line: a `@t{%}' for a normal user or +a `@t{#}' for root. If set, the shell parameter @t{PROMPT_EOL_MARK} can be +used to customize how the end of partial lines are shown. + +@noindent +NOTE: if the @t{PROMPT_CR} option is not set, enabling this option will +have no effect. This option is on by default. + +@pindex PROMPT_PERCENT +@pindex NO_PROMPT_PERCENT +@pindex PROMPTPERCENT +@pindex NOPROMPTPERCENT +@cindex prompt, % expansion +@item @t{PROMPT_PERCENT} <C> <Z> +If set, `@t{%}' is treated specially in prompt expansion. +See +@ref{Prompt Expansion}. + +@pindex PROMPT_SUBST +@pindex NO_PROMPT_SUBST +@pindex PROMPTSUBST +@pindex NOPROMPTSUBST +@cindex prompt, parameter expansion +@item @t{PROMPT_SUBST} <K> <S> +If set, @emph{parameter expansion}, @emph{command substitution} and +@emph{arithmetic expansion} are performed in prompts. Substitutions +within prompts do not affect the command status. + +@pindex TRANSIENT_RPROMPT +@pindex NO_TRANSIENT_RPROMPT +@pindex TRANSIENTRPROMPT +@pindex NOTRANSIENTRPROMPT +@item @t{TRANSIENT_RPROMPT} +Remove any right prompt from display when accepting a command +line. This may be useful with terminals with other cut/paste methods. + +@end table + +@noindent + +@subsection Scripts and Functions +@noindent +@table @asis +@pindex ALIAS_FUNC_DEF +@pindex NO_ALIAS_FUNC_DEF +@pindex ALIASFUNCDEF +@pindex NOALIASFUNCDEF +@cindex functions, defining with expanded aliases +@cindex aliases, expanding in function definition +@item @t{ALIAS_FUNC_DEF} <S> +By default, zsh does not allow the definition of functions using +the `@var{name} @t{()}' syntax if @var{name} was expanded as an +alias: this causes an error. This is usually the desired behaviour, as +otherwise the combination of an alias and a function based on the same +definition can easily cause problems. + +@noindent +When this option is set, aliases can be used for defining functions. + +@noindent +For example, consider the following definitions as they might +occur in a startup file. + +@noindent +@example +alias foo=bar +foo() @{ + print This probably does not do what you expect. +@} +@end example + +@noindent +Here, @t{foo} is expanded as an alias to @t{bar} before the +@t{()} is encountered, so the function defined would be named +@t{bar}. By default this is instead an error in native mode. Note that +quoting any part of the function name, or using the keyword +@t{function}, avoids the problem, so is recommended when the function +name can also be an alias. + +@pindex C_BASES +@pindex NO_C_BASES +@pindex CBASES +@pindex NOCBASES +@cindex bases, output in C format +@cindex hexadecimal, output in C format +@cindex octal, output in C format +@item @t{C_BASES} +Output hexadecimal numbers in the standard C format, for example `@t{0xFF}' +instead of the usual `@t{16#FF}'. If the option @t{OCTAL_ZEROES} is also +set (it is not by default), octal numbers will be treated similarly and +hence appear as `@t{077}' instead of `@t{8#77}'. This option has no effect +on the choice of the output base, nor on the output of bases other than +hexadecimal and octal. Note that these formats will be understood on input +irrespective of the setting of @t{C_BASES}. + +@pindex C_PRECEDENCES +@pindex NO_C_PRECEDENCES +@pindex CPRECEDENCES +@pindex NOCPRECEDENCES +@cindex precedence, operator +@cindex operator precedence +@item @t{C_PRECEDENCES} +This alters the precedence of arithmetic operators to be more +like C and other programming languages; +@ref{Arithmetic Evaluation} +has an explicit list. + +@pindex DEBUG_BEFORE_CMD +@pindex NO_DEBUG_BEFORE_CMD +@pindex DEBUGBEFORECMD +@pindex NODEBUGBEFORECMD +@cindex traps, DEBUG, before or after command +@cindex DEBUG trap, before or after command +@item @t{DEBUG_BEFORE_CMD} <D> +Run the @t{DEBUG} trap before each command; otherwise it is run after +each command. Setting this option mimics the behaviour of ksh 93; with +the option unset the behaviour is that of ksh 88. + +@pindex ERR_EXIT +@pindex NO_ERR_EXIT +@pindex ERREXIT +@pindex NOERREXIT +@cindex exit status, trapping +@item @t{ERR_EXIT} (@t{-e}, ksh: @t{-e}) +If a command has a non-zero exit status, execute the @t{ZERR} +trap, if set, and exit. This is disabled while running initialization +scripts. + +@noindent +The behaviour is also disabled inside @t{DEBUG} traps. In this +case the option is handled specially: it is unset on entry to +the trap. If the option @t{DEBUG_BEFORE_CMD} is set, +as it is by default, and the option @t{ERR_EXIT} is found to have been set +on exit, then the command for which the @t{DEBUG} trap is being executed is +skipped. The option is restored after the trap exits. + +@noindent +Non-zero status in a command list containing @t{&&} or @t{||} is ignored +for commands not at the end of the list. Hence + +@noindent +@example +false && true +@end example + +@noindent +does not trigger exit. + +@noindent +Exiting due to @t{ERR_EXIT} has certain interactions with asynchronous +jobs noted in +@ref{Jobs & Signals}. + +@pindex ERR_RETURN +@pindex NO_ERR_RETURN +@pindex ERRRETURN +@pindex NOERRRETURN +@cindex function return, on error +@cindex return from function, on error +@item @t{ERR_RETURN} +If a command has a non-zero exit status, return immediately from the +enclosing function. The logic is similar to that for @t{ERR_EXIT}, +except that an implicit @t{return} statement is executed instead of an +@t{exit}. This will trigger an exit at the outermost level of a +non-interactive script. + +@noindent +Normally this option inherits the behaviour of @t{ERR_EXIT} that +code followed by `@t{&&}' `@t{||}' does not trigger a return. Hence +in the following: + +@noindent +@example +summit || true +@end example + +@noindent +no return is forced as the combined effect always has a zero return +status. + +@noindent +Note. however, that if @t{summit} in the above example is itself a +function, code inside it is considered separately: it may force a return +from @t{summit} (assuming the option remains set within @t{summit}), but +not from the enclosing context. This behaviour is different from +@t{ERR_EXIT} which is unaffected by function scope. + +@pindex EVAL_LINENO +@pindex NO_EVAL_LINENO +@pindex EVALLINENO +@pindex NOEVALLINENO +@cindex line number, in evaluated expression +@item @t{EVAL_LINENO} <Z> +If set, line numbers of expressions evaluated using the builtin @t{eval} +are tracked separately of the enclosing environment. This applies both +to the parameter @t{LINENO} and the line number output by the prompt +escape @t{%i}. If the option is set, the prompt escape @t{%N} will output +the string `@t{(eval)}' instead of the script or function name as an +indication. (The two prompt escapes are typically used in the parameter +@t{PS4} to be output when the option @t{XTRACE} is set.) If +@t{EVAL_LINENO} is unset, the line number of the surrounding script or +function is retained during the evaluation. + +@pindex EXEC +@pindex NO_EXEC +@pindex NOEXEC +@cindex command execution, enabling +@item @t{EXEC} (@t{+n}, ksh: @t{+n}) <D> +Do execute commands. Without this option, commands are +read and checked for syntax errors, but not executed. +This option cannot be turned off in an interactive shell, +except when `@t{-n}' is supplied to the shell at startup. + +@pindex FUNCTION_ARGZERO +@pindex NO_FUNCTION_ARGZERO +@pindex FUNCTIONARGZERO +@pindex NOFUNCTIONARGZERO +@cindex $0, setting +@item @t{FUNCTION_ARGZERO} <C> <Z> +When executing a shell function or sourcing a script, set @t{$0} +temporarily to the name of the function/script. Note that toggling +@t{FUNCTION_ARGZERO} from on to off (or off to on) does not change the +current value of @t{$0}. Only the state upon entry to the function or +script has an effect. Compare @t{POSIX_ARGZERO}. + +@pindex LOCAL_LOOPS +@pindex NO_LOCAL_LOOPS +@pindex LOCALLOOPS +@pindex NOLOCALLOOPS +@cindex break, inside function +@cindex continue, inside function +@cindex function, scope of break and continue +@item @t{LOCAL_LOOPS} +When this option is not set, the effect of @t{break} and @t{continue} +commands may propagate outside function scope, affecting loops in +calling functions. When the option is set in a calling function, a +@t{break} or a @t{continue} that is not caught within a called function +(regardless of the setting of the option within that function) +produces a warning and the effect is cancelled. + +@pindex LOCAL_OPTIONS +@pindex NO_LOCAL_OPTIONS +@pindex LOCALOPTIONS +@pindex NOLOCALOPTIONS +@item @t{LOCAL_OPTIONS} <K> +If this option is set at the point of return from a shell function, +most options (including this one) which were in force upon entry to +the function are restored; options that are not restored are +@t{PRIVILEGED} and @t{RESTRICTED}. Otherwise, only this option, +and the @t{LOCAL_LOOPS}, @t{XTRACE} and @t{PRINT_EXIT_VALUE} options are +restored. Hence if this is explicitly unset by a shell function the +other options in force at the point of return will remain so. +A shell function can also guarantee itself a known shell configuration +with a formulation like `@t{emulate -L zsh}'; the @t{-L} activates +@t{LOCAL_OPTIONS}. + +@pindex LOCAL_PATTERNS +@pindex NO_LOCAL_PATTERNS +@pindex LOCALPATTERNS +@pindex NOLOCALPATTERNS +@item @t{LOCAL_PATTERNS} +If this option is set at the point of return from a shell function, +the state of pattern disables, as set with the builtin command +`@t{disable -p}', is restored to what it was when the function was +entered. The behaviour of this option is similar to the effect +of @t{LOCAL_OPTIONS} on options; hence `@t{emulate -L sh}' (or +indeed any other emulation with the @t{-L} option) activates +@t{LOCAL_PATTERNS}. + +@pindex LOCAL_TRAPS +@pindex NO_LOCAL_TRAPS +@pindex LOCALTRAPS +@pindex NOLOCALTRAPS +@item @t{LOCAL_TRAPS} <K> +If this option is set when a signal trap is set inside a function, then the +previous status of the trap for that signal will be restored when the +function exits. Note that this option must be set @emph{prior} to altering the +trap behaviour in a function; unlike @t{LOCAL_OPTIONS}, the value on exit +from the function is irrelevant. However, it does not need to be set +before any global trap for that to be correctly restored by a function. +For example, + +@noindent +@example +unsetopt localtraps +trap - INT +fn() @{ setopt localtraps; trap @value{dsq} INT; sleep 3; @} +@end example + +@noindent +will restore normal handling of @t{SIGINT} after the function exits. + +@pindex MULTI_FUNC_DEF +@pindex NO_MULTI_FUNC_DEF +@pindex MULTIFUNCDEF +@pindex NOMULTIFUNCDEF +@item @t{MULTI_FUNC_DEF} <Z> +Allow definitions of multiple functions at once in the form `@t{fn1 +fn2}@var{...}@t{()}'; if the option is not set, this causes +a parse error. Definition of multiple functions with the @t{function} +keyword is always allowed. Multiple function definitions are not often +used and can cause obscure errors. + +@pindex MULTIOS +@pindex NO_MULTIOS +@pindex NOMULTIOS +@item @t{MULTIOS} <Z> +Perform implicit @cite{tee}s or @cite{cat}s when multiple +redirections are attempted (see @ref{Redirection}). + +@pindex OCTAL_ZEROES +@pindex NO_OCTAL_ZEROES +@pindex OCTALZEROES +@pindex NOOCTALZEROES +@cindex octal, arithmetic expressions +@item @t{OCTAL_ZEROES} <S> +Interpret any integer constant beginning with a 0 as octal, per IEEE Std +1003.2-1992 (ISO 9945-2:1993). This is not enabled by default as it +causes problems with parsing of, for example, date and time strings with +leading zeroes. + +@noindent +Sequences of digits indicating a numeric base such as the `@t{08}' +component in `@t{08#77}' are always interpreted as decimal, regardless +of leading zeroes. + +@pindex PIPE_FAIL +@pindex NO_PIPE_FAIL +@pindex PIPEFAIL +@pindex NOPIPEFAIL +@cindex exit status from pipeline +@cindex status, on exit from pipeline +@cindex pipeline, exit status from +@item @t{PIPE_FAIL} +By default, when a pipeline exits the exit status recorded by the shell +and returned by the shell variable @t{$?} reflects that of the +rightmost element of a pipeline. If this option is set, the exit status +instead reflects the status of the rightmost element of the pipeline +that was non-zero, or zero if all elements exited with zero status. + +@pindex SOURCE_TRACE +@pindex NO_SOURCE_TRACE +@pindex SOURCETRACE +@pindex NOSOURCETRACE +@item @t{SOURCE_TRACE} +If set, zsh will print an informational message announcing the name of +each file it loads. The format of the output is similar to that +for the @t{XTRACE} option, with the message @t{<sourcetrace>}. +A file may be loaded by the shell itself when it +starts up and shuts down (@t{Startup/Shutdown Files}) or by the use of +the `@t{source}' and `@t{dot}' builtin commands. + +@pindex TYPESET_SILENT +@pindex NO_TYPESET_SILENT +@pindex TYPESETSILENT +@pindex NOTYPESETSILENT +@item @t{TYPESET_SILENT} +If this is unset, executing any of the `@t{typeset}' family of +commands with no options and a list of parameters that have no values +to be assigned but already exist will display the value of the parameter. +If the option is set, they will only be shown when parameters are selected +with the `@t{-m}' option. The option `@t{-p}' is available whether or not +the option is set. + +@pindex VERBOSE +@pindex NO_VERBOSE +@pindex NOVERBOSE +@cindex tracing, of input lines +@cindex input, tracing +@item @t{VERBOSE} (@t{-v}, ksh: @t{-v}) +Print shell input lines as they are read. + +@pindex XTRACE +@pindex NO_XTRACE +@pindex NOXTRACE +@cindex tracing, of commands +@cindex commands, tracing +@item @t{XTRACE} (@t{-x}, ksh: @t{-x}) +Print commands and their arguments as they are executed. The +output is preceded by the value of @t{$PS4}, formatted as described +in +@ref{Prompt Expansion}. + +@end table + +@noindent + +@subsection Shell Emulation +@noindent +@table @asis +@pindex APPEND_CREATE +@pindex NO_APPEND_CREATE +@pindex APPENDCREATE +@pindex NOAPPENDCREATE +@cindex clobbering, POSIX compatibility +@cindex file clobbering, POSIX compatibility +@cindex no clobber, POSIX compatible +@item @t{APPEND_CREATE} <K> <S> +This option only applies when @t{NO_CLOBBER} (-@t{C}) is in effect. + +@noindent +If this option is not set, the shell will report an error when a +append redirection (@t{>>}) is used on a file that does not already +exists (the traditional zsh behaviour of @t{NO_CLOBBER}). If the option +is set, no error is reported (POSIX behaviour). + +@pindex BASH_REMATCH +@pindex NO_BASH_REMATCH +@pindex BASHREMATCH +@pindex NOBASHREMATCH +@cindex bash, BASH_REMATCH variable +@cindex regexp, bash BASH_REMATCH variable +@item @t{BASH_REMATCH} +When set, matches performed with the @t{=~} operator will set the +@t{BASH_REMATCH} array variable, instead of the default @t{MATCH} and +@t{match} variables. The first element of the @t{BASH_REMATCH} array +will contain the entire matched text and subsequent elements will contain +extracted substrings. This option makes more sense when @t{KSH_ARRAYS} is +also set, so that the entire matched portion is stored at index 0 and the +first substring is at index 1. Without this option, the @t{MATCH} variable +contains the entire matched text and the @t{match} array variable contains +substrings. + +@pindex BSD_ECHO +@pindex NO_BSD_ECHO +@pindex BSDECHO +@pindex NOBSDECHO +@cindex echo, BSD compatible +@item @t{BSD_ECHO} <S> +Make the @t{echo} builtin compatible with the BSD man page echo(1) command. +This disables backslashed escape sequences in echo strings unless the +@t{-e} option is specified. + +@pindex CONTINUE_ON_ERROR +@pindex NO_CONTINUE_ON_ERROR +@pindex CONTINUEONERROR +@pindex NOCONTINUEONERROR +@cindex error, option to continue script on +@item @t{CONTINUE_ON_ERROR} +If a fatal error is encountered (see +@ref{Errors}), and the code is running +in a script, the shell will resume execution at the next statement +in the script at the top level, in other words outside all functions +or shell constructs such as loops and conditions. This mimics the +behaviour of interactive shells, where the shell returns to the +line editor to read a new command; it was the normal behaviour in versions +of zsh before 5.0.1. + +@pindex CSH_JUNKIE_HISTORY +@pindex NO_CSH_JUNKIE_HISTORY +@pindex CSHJUNKIEHISTORY +@pindex NOCSHJUNKIEHISTORY +@cindex csh, history style +@cindex history style, csh +@item @t{CSH_JUNKIE_HISTORY} <C> +A history reference without an event specifier will always refer to the +previous command. Without this option, such a history reference refers +to the same event as the previous history reference on the current +command line, defaulting to the previous command. + +@pindex CSH_JUNKIE_LOOPS +@pindex NO_CSH_JUNKIE_LOOPS +@pindex CSHJUNKIELOOPS +@pindex NOCSHJUNKIELOOPS +@cindex csh, loop style +@cindex loop style, csh +@item @t{CSH_JUNKIE_LOOPS} <C> +Allow loop bodies to take the form `@var{list}@t{; end}' instead of +`@t{do }@var{list}@t{; done}'. + +@pindex CSH_JUNKIE_QUOTES +@pindex NO_CSH_JUNKIE_QUOTES +@pindex CSHJUNKIEQUOTES +@pindex NOCSHJUNKIEQUOTES +@cindex csh, quoting style +@cindex quoting style, csh +@item @t{CSH_JUNKIE_QUOTES} <C> +Changes the rules for single- and double-quoted text to match that of +@cite{csh}. These require that embedded newlines be preceded by a backslash; +unescaped newlines will cause an error message. +In double-quoted strings, it is made impossible to escape `@t{$}', `@t{`}' +or `@t{"}' (and `@t{\}' itself no longer needs escaping). +Command substitutions are only expanded once, and cannot be nested. + +@pindex CSH_NULLCMD +@pindex NO_CSH_NULLCMD +@pindex CSHNULLCMD +@pindex NOCSHNULLCMD +@vindex NULLCMD, ignoring +@vindex READNULLCMD, ignoring +@cindex redirections with no command, csh +@cindex csh, redirections with no command +@item @t{CSH_NULLCMD} <C> +Do not use the values of @t{NULLCMD} and @t{READNULLCMD} +when running redirections with no command. This make +such redirections fail (see @ref{Redirection}). + +@pindex KSH_ARRAYS +@pindex NO_KSH_ARRAYS +@pindex KSHARRAYS +@pindex NOKSHARRAYS +@cindex arrays, ksh style +@cindex array style, ksh +@cindex ksh, array style +@item @t{KSH_ARRAYS} <K> <S> +Emulate @cite{ksh} array handling as closely as possible. If this option +is set, array elements are numbered from zero, an array parameter +without subscript refers to the first element instead of the whole array, +and braces are required to delimit a subscript (`@t{$@{path[2]@}}' rather +than just `@t{$path[2]}') or to apply modifiers to any parameter +(`@t{$@{PWD:h@}}' rather than `@t{$PWD:h}'). + +@pindex KSH_AUTOLOAD +@pindex NO_KSH_AUTOLOAD +@pindex KSHAUTOLOAD +@pindex NOKSHAUTOLOAD +@item @t{KSH_AUTOLOAD} <K> <S> +Emulate @cite{ksh} function autoloading. This means that when a function is +autoloaded, the corresponding file is merely executed, and must define +the function itself. (By default, the function is defined to the contents +of the file. However, the most common @cite{ksh}-style case - of the file +containing only a simple definition of the function - is always handled +in the @cite{ksh}-compatible manner.) + +@pindex KSH_OPTION_PRINT +@pindex NO_KSH_OPTION_PRINT +@pindex KSHOPTIONPRINT +@pindex NOKSHOPTIONPRINT +@cindex option printing, ksh style +@cindex option printing style, ksh +@cindex ksh, option printing style +@item @t{KSH_OPTION_PRINT} <K> +Alters the way options settings are printed: instead of separate lists of +set and unset options, all options are shown, marked `on' if +they are in the non-default state, `off' otherwise. + +@pindex KSH_TYPESET +@pindex NO_KSH_TYPESET +@pindex KSHTYPESET +@pindex NOKSHTYPESET +@cindex argument splitting, in typeset etc. +@cindex ksh, argument splitting in typeset +@item @t{KSH_TYPESET} +This option is now obsolete: a better appropximation to the behaviour of +other shells is obtained with the reserved word interface to +@t{declare}, @t{export}, @t{float}, @t{integer}, @t{local}, @t{readonly} +and @t{typeset}. Note that the option is only applied when the reserved +word interface is @emph{not} in use. + +@noindent +Alters the way arguments to the @t{typeset} family of commands, including +@t{declare}, @t{export}, @t{float}, @t{integer}, @t{local} and +@t{readonly}, are processed. Without this option, zsh will perform normal +word splitting after command and parameter expansion in arguments of an +assignment; with it, word splitting does not take place in those cases. + +@pindex KSH_ZERO_SUBSCRIPT +@pindex NO_KSH_ZERO_SUBSCRIPT +@pindex KSHZEROSUBSCRIPT +@pindex NOKSHZEROSUBSCRIPT +@cindex arrays, behaviour of index zero +@item @t{KSH_ZERO_SUBSCRIPT} +Treat use of a subscript of value zero in array or string expressions as a +reference to the first element, i.e. the element that usually has the +subscript 1. Ignored if @t{KSH_ARRAYS} is also set. + +@noindent +If neither this option nor @t{KSH_ARRAYS} is set, accesses to an element of +an array or string with subscript zero return an empty element or string, +while attempts to set element zero of an array or string are treated as an +error. However, attempts to set an otherwise valid subscript range that +includes zero will succeed. For example, if @t{KSH_ZERO_SUBSCRIPT} is not +set, + +@noindent +@example +array[0]=(element) +@end example + +@noindent +is an error, while + +@noindent +@example +array[0,1]=(element) +@end example + +@noindent +is not and will replace the first element of the array. + +@noindent +This option is for compatibility with older versions of the shell and +is not recommended in new code. + +@pindex POSIX_ALIASES +@pindex NO_POSIX_ALIASES +@pindex POSIXALIASES +@pindex NOPOSIXALIASES +@item @t{POSIX_ALIASES} <K> <S> +When this option is set, reserved words are not candidates for +alias expansion: it is still possible to declare any of them as an alias, +but the alias will never be expanded. Reserved words are described in +@ref{Reserved Words}. + +@noindent +Alias expansion takes place while text is being read; hence when this +option is set it does not take effect until the end of any function or +other piece of shell code parsed as one unit. Note this may +cause differences from other shells even when the option is in +effect. For example, when running a command with `@t{zsh -c}', +or even `@t{zsh -o posixaliases -c}', the entire command argument is parsed +as one unit, so aliases defined within the argument are not available even +in later lines. If in doubt, avoid use of aliases in non-interactive +code. + +@pindex POSIX_ARGZERO +@pindex NO_POSIX_ARGZERO +@pindex POSIXARGZERO +@pindex NOPOSIXARGZERO +@cindex $0, using +@item @t{POSIX_ARGZERO} +This option may be used to temporarily disable @t{FUNCTION_ARGZERO} and +thereby restore the value of @t{$0} to the name used to invoke the shell +(or as set by the @t{-c} command line option). For compatibility with +previous versions of the shell, emulations use @t{NO_FUNCTION_ARGZERO} +instead of @t{POSIX_ARGZERO}, which may result in unexpected scoping of +@t{$0} if the emulation mode is changed inside a function or script. +To avoid this, explicitly enable @t{POSIX_ARGZERO} in the @t{emulate} +command: + +@noindent +@example +emulate sh -o POSIX_ARGZERO +@end example + +@noindent +Note that @t{NO_POSIX_ARGZERO} has no effect unless @t{FUNCTION_ARGZERO} +was already enabled upon entry to the function or script. + +@pindex POSIX_BUILTINS +@pindex NO_POSIX_BUILTINS +@pindex POSIXBUILTINS +@pindex NOPOSIXBUILTINS +@item @t{POSIX_BUILTINS} <K> <S> +When this option is set the @t{command} builtin can be used to execute +shell builtin commands. Parameter assignments specified before shell +functions and special builtins are kept after the command completes unless +the special builtin is prefixed with the @t{command} builtin. Special +builtins are +@t{.}, +@t{:}, +@t{break}, +@t{continue}, +@t{declare}, +@t{eval}, +@t{exit}, +@t{export}, +@t{integer}, +@t{local}, +@t{readonly}, +@t{return}, +@t{set}, +@t{shift}, +@t{source}, +@t{times}, +@t{trap} and +@t{unset}. + +@noindent +In addition, various error conditions associated with the above builtins +or @t{exec} cause a non-interactive shell to exit and an interactive +shell to return to its top-level processing. + +@noindent +Furthermore, functions and shell builtins are not executed after +an @t{exec} prefix; the command to be executed must be an external +command found in the path. + +@noindent +Furthermore, the @t{getopts} builtin behaves in a POSIX-compatible +fashion in that the associated variable @t{OPTIND} is not made +local to functions. + +@noindent +Moreover, the warning and special exit code from +@t{[[ -o }@var{non_existent_option}@t{ ]]} are suppressed. + +@pindex POSIX_IDENTIFIERS +@pindex NO_POSIX_IDENTIFIERS +@pindex POSIXIDENTIFIERS +@pindex NOPOSIXIDENTIFIERS +@cindex identifiers, non-portable characters in +@cindex parameter names, non-portable characters in +@item @t{POSIX_IDENTIFIERS} <K> <S> +When this option is set, only the ASCII characters @t{a} to @t{z}, @t{A} to +@t{Z}, @t{0} to @t{9} and @t{_} may be used in identifiers (names +of shell parameters and modules). + +@noindent +In addition, setting this option limits the effect of parameter +substitution with no braces, so that the expression @t{$#} is treated as +the parameter @t{$#} even if followed by a valid parameter name. +When it is unset, zsh allows expressions of the form @t{$#}@var{name} +to refer to the length of @t{$}@var{name}, even for special variables, +for example in expressions such as @t{$#-} and @t{$#*}. + +@noindent +Another difference is that with the option set assignment to an +unset variable in arithmetic context causes the variable to be created +as a scalar rather than a numeric type. So after `@t{unset t; (( t = 3 +))}'. without @t{POSIX_IDENTIFIERS} set @t{t} has integer type, while with +it set it has scalar type. + +@noindent +When the option is unset and multibyte character support is enabled (i.e. it +is compiled in and the option @t{MULTIBYTE} is set), then additionally any +alphanumeric characters in the local character set may be used in +identifiers. Note that scripts and functions written with this feature are +not portable, and also that both options must be set before the script +or function is parsed; setting them during execution is not sufficient +as the syntax @var{variable}@t{=}@var{value} has already been parsed as +a command rather than an assignment. + +@noindent +If multibyte character support is not compiled into the shell this option is +ignored; all octets with the top bit set may be used in identifiers. +This is non-standard but is the traditional zsh behaviour. + +@pindex POSIX_STRINGS +@pindex NO_POSIX_STRINGS +@pindex POSIXSTRINGS +@pindex NOPOSIXSTRINGS +@cindex discarding embedded nulls in $'...' +@cindex embedded nulls, in $'...' +@cindex nulls, embedded in $'...' +@item @t{POSIX_STRINGS} <K> <S> +This option affects processing of quoted strings. Currently it only +affects the behaviour of null characters, i.e. character 0 in the +portable character set corresponding to US ASCII. + +@noindent +When this option is not set, null characters embedded within strings +of the form @t{$'}@var{...}@t{'} are treated as ordinary characters. The +entire string is maintained within the shell and output to files where +necessary, although owing to restrictions of the library interface +the string is truncated at the null character in file names, environment +variables, or in arguments to external programs. + +@noindent +When this option is set, the @t{$'}@var{...}@t{'} expression is truncated at +the null character. Note that remaining parts of the same string +beyond the termination of the quotes are not truncated. + +@noindent +For example, the command line argument @t{a$'b\0c'd} is treated with +the option off as the characters @t{a}, @t{b}, null, @t{c}, @t{d}, +and with the option on as the characters @t{a}, @t{b}, @t{d}. + +@pindex POSIX_TRAPS +@pindex NO_POSIX_TRAPS +@pindex POSIXTRAPS +@pindex NOPOSIXTRAPS +@cindex traps, on function exit +@cindex traps, POSIX compatibility +@item @t{POSIX_TRAPS} <K> <S> +When this option is set, the usual zsh behaviour of executing +traps for @t{EXIT} on exit from shell functions is suppressed. +In that case, manipulating @t{EXIT} traps always alters the global +trap for exiting the shell; the @t{LOCAL_TRAPS} option is +ignored for the @t{EXIT} trap. Furthermore, a @t{return} statement +executed in a trap with no argument passes back from the function the +value from the surrounding context, not from code executed within the +trap. + +@pindex SH_FILE_EXPANSION +@pindex NO_SH_FILE_EXPANSION +@pindex SHFILEEXPANSION +@pindex NOSHFILEEXPANSION +@cindex sh, expansion style +@cindex expansion style, sh +@item @t{SH_FILE_EXPANSION} <K> <S> +Perform filename expansion (e.g., @t{~} expansion) @emph{before} +parameter expansion, command substitution, arithmetic expansion +and brace expansion. +If this option is unset, it is performed @emph{after} +brace expansion, so things like `@t{~$USERNAME}' and +`@t{~@{pfalstad,rc@}}' will work. + +@pindex SH_NULLCMD +@pindex NO_SH_NULLCMD +@pindex SHNULLCMD +@pindex NOSHNULLCMD +@vindex NULLCMD, ignoring +@vindex READNULLCMD, ignoring +@cindex sh, redirections with no command +@cindex ksh, redirections with no command +@cindex redirections with no command, sh +@cindex redirections with no command, ksh +@item @t{SH_NULLCMD} <K> <S> +Do not use the values of @t{NULLCMD} and @t{READNULLCMD} +when doing redirections, use `@t{:}' instead (see @ref{Redirection}). + +@pindex SH_OPTION_LETTERS +@pindex NO_SH_OPTION_LETTERS +@pindex SHOPTIONLETTERS +@pindex NOSHOPTIONLETTERS +@cindex sh, single letter options style +@cindex ksh, single letter options style +@cindex single letter options, ksh style +@cindex options, single letter, ksh style +@item @t{SH_OPTION_LETTERS} <K> <S> +If this option is set the shell tries to interpret single letter options +(which are used with @t{set} and @t{setopt}) like @cite{ksh} does. +This also affects the value of the @t{-} special parameter. + +@pindex SH_WORD_SPLIT +@pindex NO_SH_WORD_SPLIT +@pindex SHWORDSPLIT +@pindex NOSHWORDSPLIT +@cindex field splitting, sh style +@cindex sh, field splitting style +@item @t{SH_WORD_SPLIT} (@t{-y}) <K> <S> +Causes field splitting to be performed on unquoted parameter expansions. +Note that this option has nothing to do with word splitting. +(See +@ref{Parameter Expansion}.) + +@pindex TRAPS_ASYNC +@pindex NO_TRAPS_ASYNC +@pindex TRAPSASYNC +@pindex NOTRAPSASYNC +@cindex traps, asynchronous +@item @t{TRAPS_ASYNC} +While waiting for a program to exit, handle signals and run traps +immediately. Otherwise the trap is run after a child process has exited. +Note this does not affect the point at which traps are run for any case +other than when the shell is waiting for a child process. + +@end table + +@noindent + +@subsection Shell State +@noindent +@table @asis +@pindex INTERACTIVE +@pindex NO_INTERACTIVE +@pindex NOINTERACTIVE +@item @t{INTERACTIVE} (@t{-i}, ksh: @t{-i}) +This is an interactive shell. This option is set upon initialisation if +the standard input is a tty and commands are being read from standard input. +(See the discussion of @t{SHIN_STDIN}.) +This heuristic may be overridden by specifying a state for this option +on the command line. +The value of this option can only be changed via flags supplied at +invocation of the shell. +It cannot be changed once zsh is running. + +@pindex LOGIN +@pindex NO_LOGIN +@pindex NOLOGIN +@item @t{LOGIN} (@t{-l}, ksh: @t{-l}) +This is a login shell. +If this option is not explicitly set, the shell becomes a login shell if +the first character of the @t{argv[0]} passed to the shell is a `@t{-}'. + +@pindex PRIVILEGED +@pindex NO_PRIVILEGED +@pindex NOPRIVILEGED +@cindex privileged mode +@cindex mode, privileged +@item @t{PRIVILEGED} (@t{-p}, ksh: @t{-p}) +Turn on privileged mode. Typically this is used when script is to be run +with elevated privileges. This should be done as follows directly with +the @t{-p} option to zsh so that it takes effect during startup. + +@noindent +@example +#!/bin/zsh -p +@end example + +@noindent +The option is enabled automatically on startup if the effective user +(group) ID is not equal to the real user (group) ID. In this case, +turning the option off causes the effective user and group IDs to be set +to the real user and group IDs. Be aware that if that fails the shell may +be running with different IDs than was intended so a script should check +for failure and act accordingly, for example: + +@noindent +@example +unsetopt privileged || exit +@end example + +@noindent +The @t{PRIVILEGED} option disables sourcing user startup files. +If zsh is invoked as `@t{sh}' or `@t{ksh}' with this option set, +@t{/etc/suid_profile} is sourced (after @t{/etc/profile} on interactive +shells). Sourcing @t{~/.profile} is disabled and the contents of the +@t{ENV} variable is ignored. This option cannot be changed using the +@t{-m} option of @t{setopt} and @t{unsetopt}, and changing it inside a +function always changes it globally regardless of the @t{LOCAL_OPTIONS} +option. + +@pindex RESTRICTED +@pindex NO_RESTRICTED +@pindex NORESTRICTED +@cindex restricted shell +@item @t{RESTRICTED} (@t{-r}) +Enables restricted mode. This option cannot be changed using +@t{unsetopt}, and setting it inside a function always changes it +globally regardless of the @t{LOCAL_OPTIONS} option. See +@ref{Restricted Shell}. + +@pindex SHIN_STDIN +@pindex NO_SHIN_STDIN +@pindex SHINSTDIN +@pindex NOSHINSTDIN +@item @t{SHIN_STDIN} (@t{-s}, ksh: @t{-s}) +Commands are being read from the standard input. +Commands are read from standard input if no command is specified with +@t{-c} and no file of commands is specified. If @t{SHIN_STDIN} +is set explicitly on the command line, +any argument that would otherwise have been +taken as a file to run will instead be treated as a normal positional +parameter. +Note that setting or unsetting this option on the command line does not +necessarily affect the state the option will have while the shell is +running - that is purely an indicator of whether or not commands are +@emph{actually} being read from standard input. +The value of this option can only be changed via flags supplied at +invocation of the shell. +It cannot be changed once zsh is running. + +@pindex SINGLE_COMMAND +@pindex NO_SINGLE_COMMAND +@pindex SINGLECOMMAND +@pindex NOSINGLECOMMAND +@cindex single command +@pindex INTERACTIVE, use of +@item @t{SINGLE_COMMAND} (@t{-t}, ksh: @t{-t}) +If the shell is reading from standard input, it exits after a single command +has been executed. This also makes the shell non-interactive, unless the +@t{INTERACTIVE} option is explicitly set on the command line. +The value of this option can only be changed via flags supplied at +invocation of the shell. +It cannot be changed once zsh is running. + +@end table + +@noindent + +@subsection Zle +@noindent +@table @asis +@pindex BEEP +@pindex NO_BEEP +@pindex NOBEEP +@cindex beep, enabling +@cindex enabling the beep +@item @t{BEEP} (@t{+B}) <D> +Beep on error in ZLE. + +@pindex COMBINING_CHARS +@pindex NO_COMBINING_CHARS +@pindex COMBININGCHARS +@pindex NOCOMBININGCHARS +@cindex characters, (Unicode) combining +@cindex combining characters (Unicode) +@cindex Unicode combining characters +@item @t{COMBINING_CHARS} +Assume that the terminal displays combining characters correctly. +Specifically, if a base alphanumeric character is followed by one or more +zero-width punctuation characters, assume that the zero-width characters +will be displayed as modifications to the base character within the +same width. Not all terminals handle this. If this option is not +set, zero-width characters are displayed separately with special +mark-up. + +@noindent +If this option is set, the pattern test @t{[[:WORD:]]} matches a +zero-width punctuation character on the assumption that it will be +used as part of a word in combination with a word character. +Otherwise the base shell does not handle combining characters specially. + +@pindex EMACS +@pindex NO_EMACS +@pindex NOEMACS +@item @t{EMACS} +If ZLE is loaded, turning on this option has the equivalent effect +of `@t{bindkey -e}'. In addition, the VI option is unset. +Turning it off has no effect. The option setting is +not guaranteed to reflect the current keymap. This option is +provided for compatibility; @t{bindkey} is the recommended interface. + +@pindex OVERSTRIKE +@pindex NO_OVERSTRIKE +@pindex NOOVERSTRIKE +@cindex editor, overstrike mode +@cindex overstrike mode, of editor +@item @t{OVERSTRIKE} +Start up the line editor in overstrike mode. + +@pindex SINGLE_LINE_ZLE +@pindex NO_SINGLE_LINE_ZLE +@pindex SINGLELINEZLE +@pindex NOSINGLELINEZLE +@cindex editor, single line mode +@item @t{SINGLE_LINE_ZLE} (@t{-M}) <K> +Use single-line command line editing instead of multi-line. + +@noindent +Note that although this is on by default in ksh emulation it only +provides superficial compatibility with the ksh line editor and +reduces the effectiveness of the zsh line editor. As it has no +effect on shell syntax, many users may wish to disable this option +when using ksh emulation interactively. + +@pindex VI +@pindex NO_VI +@pindex NOVI +@item @t{VI} +If ZLE is loaded, turning on this option has the equivalent effect +of `@t{bindkey -v}'. In addition, the EMACS option is unset. +Turning it off has no effect. The option setting is +not guaranteed to reflect the current keymap. This option is +provided for compatibility; @t{bindkey} is the recommended interface. + +@pindex ZLE +@pindex NO_ZLE +@pindex NOZLE +@cindex editor, enabling +@cindex enabling the editor +@item @t{ZLE} (@t{-Z}) +Use the zsh line editor. Set by default in interactive shells connected to +a terminal. + +@end table + +@noindent +@node Option Aliases, Single Letter Options, Description of Options, Options + +@section Option Aliases +@noindent +@cindex options, aliases +Some options have alternative names. These aliases are never used for +output, but can be used just like normal option names when specifying +options to the shell. + +@noindent +@table @asis +@pindex BRACE_EXPAND +@pindex NO_BRACE_EXPAND +@pindex BRACEEXPAND +@pindex NOBRACEEXPAND +@item @t{BRACE_EXPAND} +@emph{NO_}@t{IGNORE_BRACES} +(ksh and bash compatibility) + +@pindex DOT_GLOB +@pindex NO_DOT_GLOB +@pindex DOTGLOB +@pindex NODOTGLOB +@item @t{DOT_GLOB} +@t{GLOB_DOTS} +(bash compatibility) + +@pindex HASH_ALL +@pindex NO_HASH_ALL +@pindex HASHALL +@pindex NOHASHALL +@item @t{HASH_ALL} +@t{HASH_CMDS} +(bash compatibility) + +@pindex HIST_APPEND +@pindex NO_HIST_APPEND +@pindex HISTAPPEND +@pindex NOHISTAPPEND +@item @t{HIST_APPEND} +@t{APPEND_HISTORY} +(bash compatibility) + +@pindex HIST_EXPAND +@pindex NO_HIST_EXPAND +@pindex HISTEXPAND +@pindex NOHISTEXPAND +@item @t{HIST_EXPAND} +@t{BANG_HIST} +(bash compatibility) + +@pindex LOG +@pindex NO_LOG +@pindex NOLOG +@item @t{LOG} +@emph{NO_}@t{HIST_NO_FUNCTIONS} +(ksh compatibility) + +@pindex MAIL_WARN +@pindex NO_MAIL_WARN +@pindex MAILWARN +@pindex NOMAILWARN +@item @t{MAIL_WARN} +@t{MAIL_WARNING} +(bash compatibility) + +@pindex ONE_CMD +@pindex NO_ONE_CMD +@pindex ONECMD +@pindex NOONECMD +@item @t{ONE_CMD} +@t{SINGLE_COMMAND} +(bash compatibility) + +@pindex PHYSICAL +@pindex NO_PHYSICAL +@pindex NOPHYSICAL +@item @t{PHYSICAL} +@t{CHASE_LINKS} +(ksh and bash compatibility) + +@pindex PROMPT_VARS +@pindex NO_PROMPT_VARS +@pindex PROMPTVARS +@pindex NOPROMPTVARS +@item @t{PROMPT_VARS} +@t{PROMPT_SUBST} +(bash compatibility) + +@pindex STDIN +@pindex NO_STDIN +@pindex NOSTDIN +@item @t{STDIN} +@t{SHIN_STDIN} +(ksh compatibility) + +@pindex TRACK_ALL +@pindex NO_TRACK_ALL +@pindex TRACKALL +@pindex NOTRACKALL +@item @t{TRACK_ALL} +@t{HASH_CMDS} +(ksh compatibility) + +@end table +@node Single Letter Options, , Option Aliases, Options + +@section Single Letter Options +@noindent +@cindex options, single letter +@cindex single letter options + +@subsection Default set +@noindent +@table @asis +@item @t{-0} +CORRECT +@item @t{-1} +PRINT_EXIT_VALUE +@item @t{-2} +@emph{NO_}BAD_PATTERN +@item @t{-3} +@emph{NO_}NOMATCH +@item @t{-4} +GLOB_DOTS +@item @t{-5} +NOTIFY +@item @t{-6} +BG_NICE +@item @t{-7} +IGNORE_EOF +@item @t{-8} +MARK_DIRS +@item @t{-9} +AUTO_LIST +@item @t{-B} +@emph{NO_}BEEP +@item @t{-C} +@emph{NO_}CLOBBER +@item @t{-D} +PUSHD_TO_HOME +@item @t{-E} +PUSHD_SILENT +@item @t{-F} +@emph{NO_}GLOB +@item @t{-G} +NULL_GLOB +@item @t{-H} +RM_STAR_SILENT +@item @t{-I} +IGNORE_BRACES +@item @t{-J} +AUTO_CD +@item @t{-K} +@emph{NO_}BANG_HIST +@item @t{-L} +SUN_KEYBOARD_HACK +@item @t{-M} +SINGLE_LINE_ZLE +@item @t{-N} +AUTO_PUSHD +@item @t{-O} +CORRECT_ALL +@item @t{-P} +RC_EXPAND_PARAM +@item @t{-Q} +PATH_DIRS +@item @t{-R} +LONG_LIST_JOBS +@item @t{-S} +REC_EXACT +@item @t{-T} +CDABLE_VARS +@item @t{-U} +MAIL_WARNING +@item @t{-V} +@emph{NO_}PROMPT_CR +@item @t{-W} +AUTO_RESUME +@item @t{-X} +LIST_TYPES +@item @t{-Y} +MENU_COMPLETE +@item @t{-Z} +ZLE +@item @t{-a} +ALL_EXPORT +@item @t{-e} +ERR_EXIT +@item @t{-f} +@emph{NO_}RCS +@item @t{-g} +HIST_IGNORE_SPACE +@item @t{-h} +HIST_IGNORE_DUPS +@item @t{-i} +INTERACTIVE +@item @t{-k} +INTERACTIVE_COMMENTS +@item @t{-l} +LOGIN +@item @t{-m} +MONITOR +@item @t{-n} +@emph{NO_}EXEC +@item @t{-p} +PRIVILEGED +@item @t{-r} +RESTRICTED +@item @t{-s} +SHIN_STDIN +@item @t{-t} +SINGLE_COMMAND +@item @t{-u} +@emph{NO_}UNSET +@item @t{-v} +VERBOSE +@item @t{-w} +CHASE_LINKS +@item @t{-x} +XTRACE +@item @t{-y} +SH_WORD_SPLIT +@end table + +@subsection sh/ksh emulation set +@noindent +@table @asis +@item @t{-C} +@emph{NO_}CLOBBER +@item @t{-T} +TRAPS_ASYNC +@item @t{-X} +MARK_DIRS +@item @t{-a} +ALL_EXPORT +@item @t{-b} +NOTIFY +@item @t{-e} +ERR_EXIT +@item @t{-f} +@emph{NO_}GLOB +@item @t{-i} +INTERACTIVE +@item @t{-l} +LOGIN +@item @t{-m} +MONITOR +@item @t{-n} +@emph{NO_}EXEC +@item @t{-p} +PRIVILEGED +@item @t{-r} +RESTRICTED +@item @t{-s} +SHIN_STDIN +@item @t{-t} +SINGLE_COMMAND +@item @t{-u} +@emph{NO_}UNSET +@item @t{-v} +VERBOSE +@item @t{-x} +XTRACE +@end table + +@subsection Also note +@noindent +@table @asis +@item @t{-A} +Used by @t{set} for setting arrays +@item @t{-b} +Used on the command line to specify end of option processing +@item @t{-c} +Used on the command line to specify a single command +@item @t{-m} +Used by @t{setopt} for pattern-matching option setting +@item @t{-o} +Used in all places to allow use of long option names +@item @t{-s} +Used by @t{set} to sort positional parameters +@end table +@c (avoiding a yodl bug) +@c Yodl file: Zsh/builtins.yo +@node Shell Builtin Commands, Zsh Line Editor, Options, Top + +@chapter Shell Builtin Commands +@noindent + +@cindex builtin commands +@cindex commands, builtin +Some shell builtin commands take options as described in individual +entries; these are often referred to in the list below as `@t{flags}' to +avoid confusion with shell options, which may also have an effect on the +behaviour of builtin commands. In this introductory section, +`@t{option}' always has the meaning of an option to a command that should +be familiar to most command line users. + +@noindent +Typically, options are single letters preceded by a hyphen (@t{-}). +Options that take an argument accept it either immediately following the +option letter or after white space, for example `@t{print -C3 @{1..9@}}' or +`@t{print -C 3 @{1..9@}}' are equivalent. Arguments to options are not the +same as arguments to the command; the documentation indicates which is +which. Options that do not take an argument may be combined in a single +word, for example `@t{print -rca -- *}' and `@t{print -r -c -a -- *}' are +equivalent. + +@noindent +Some shell builtin commands also take options that begin with `@t{+}' +instead of `@t{-}'. The list below makes clear which commands these +are. + +@noindent +Options (together with their individual arguments, if any) must appear +in a group before any non-option arguments; once the first non-option +argument has been found, option processing is terminated. + +@noindent +All builtin commands other than `@t{echo}' and precommand modifiers, +even those that have no options, can be given the argument `@t{-}@t{-}' +to terminate option processing. This indicates that the following words +are non-option arguments, but is otherwise ignored. This is useful in +cases where arguments to the command may begin with `@t{-}'. For +historical reasons, most builtin commands (including `@t{echo}') also +recognize a single `@t{-}' in a separate word for this purpose; note +that this is less standard and use of `@t{-}@t{-}' is recommended. + +@noindent +@table @asis +@item @t{-} @var{simple command} +See @ref{Precommand Modifiers}. + +@findex . +@item @t{.} @var{file} [ @var{arg} ... ] +Read commands from @var{file} and execute them in the current shell +environment. + +@noindent +If @var{file} does not contain a slash, or if @t{PATH_DIRS} is set, +the shell looks in the components of @t{$path} to find the directory +containing @var{file}. Files in the current directory are not read +unless `@t{.}' appears somewhere in @t{$path}. If a file named +`@var{file}@t{.zwc}' is found, is newer than @var{file}, and is the +compiled form (created with the @t{zcompile} builtin) of @var{file}, +then commands are read from that file instead of @var{file}. + +@noindent +If any arguments @var{arg} are given, +they become the positional parameters; the old positional +parameters are restored when the @var{file} is done executing. +However, if no arguments are given, +the positional parameters remain those of the calling context, +and no restoring is done. + +@noindent +If @var{file} was not found the return status is 127; if @var{file} was found +but contained a syntax error the return status is 126; else the return +status is the exit status of the last command executed. + +@findex : +@cindex expanding parameters +@cindex parameters, expanding +@cindex doing nothing +@item @t{:} [ @var{arg} ... ] +This command does nothing, although normal argument expansions is performed +which may have effects on shell parameters. A zero exit status is returned. + +@findex alias +@cindex aliases, defining +@cindex aliases, listing +@item @t{alias} [ @{@t{+}|@t{-}@}@t{gmrsL} ] [ @var{name}[@t{=}@var{value}] ... ] +For each @var{name} with a corresponding @var{value}, define an alias +with that value. A trailing space in @var{value} causes the next word +to be checked for alias expansion. If the @t{-g} flag is present, +define a global alias; global aliases are expanded even if they do not +occur in command position. + +@noindent +If the @t{-s} flag is present, define a suffix alias: if the command +word on a command line is in the form `@var{text}@t{.}@var{name}', where +@var{text} is any non-empty string, it is replaced by the text +`@var{value} @var{text}@t{.}@var{name}'. Note that @var{name} is treated as +a literal string, not a pattern. A trailing space in @var{value} is not +special in this case. For example, + +@noindent +@example +alias -s ps='gv --' +@end example + +@noindent +will cause the command `@t{*.ps}' to be expanded to `@t{gv -- *.ps}'. As +alias expansion is carried out earlier than globbing, the `@t{*.ps}' will +then be expanded. Suffix aliases constitute a different name space from +other aliases (so in the above example it is still possible +to create an alias for the command @t{ps}) and the two sets are never +listed together. + +@noindent +For each @var{name} with no @var{value}, +print the value of @var{name}, if any. With no arguments, print all +currently defined aliases other than suffix aliases. If the @t{-m} flag +is given the arguments are taken as patterns (they should be quoted to +preserve them from being interpreted as glob patterns), and the aliases +matching these patterns are printed. When printing aliases and one of +the @t{-g}, @t{-r} or @t{-s} flags is present, restrict the printing to +global, regular or suffix aliases, respectively; a regular alias is one +which is neither a global nor a suffix alias. Using `@t{+}' +instead of `@t{-}', or ending the option list with a single +`@t{+}', prevents the values of the aliases from being printed. + +@noindent +If the @t{-L} flag is present, then print each +alias in a manner suitable for putting in a startup script. The exit +status is nonzero if a @var{name} (with no @var{value}) is given for +which no alias has been defined. + +@noindent +For more on aliases, include common problems, see +@ref{Aliasing}. + +@findex autoload +@cindex functions, autoloading +@cindex autoloading functions +@item @t{autoload} [ @{@t{+}|@t{-}@}@t{RTUXdkmrtWz} ] [ @t{-w} ] [ @var{name} ... ] +@vindex fpath, searching +See the section `Autoloading Functions' in @ref{Functions} for full details. The @t{fpath} parameter +will be searched to find the function definition when the function is +first referenced. + +@noindent +If @var{name} consists of an absolute path, the function is defined to +load from the file given (searching as usual for dump files in the given +location). The name of the function is the basename (non-directory +part) of the file. It is normally an error if the function is not found +in the given location; however, if the option @t{-d} is given, searching +for the function defaults to @t{$fpath}. If a function is loaded by +absolute path, any functions loaded from it that are marked for +@t{autoload} without an absolute path have the load path of the parent +function temporarily prepended to @t{$fpath}. + +@noindent +If the option @t{-r} or @t{-R} is given, the function is searched for +immediately and the location is recorded internally for use when the +function is executed; a relative path is expanded using the value of +@t{$PWD}. This protects against a change to @t{$fpath} after the call +to @t{autoload}. With @t{-r}, if the function is not found, it is +silently left unresolved until execution; with @t{-R}, an error message +is printed and command processing aborted immediately the search fails, +i.e. at the @t{autoload} command rather than at function execution.. + +@noindent +The flag @t{-X} may be used only inside a shell function. It causes the +calling function to be marked for autoloading and then immediately +loaded and executed, with the current array of positional parameters as +arguments. This replaces the previous definition of the function. If +no function definition is found, an error is printed and the function +remains undefined and marked for autoloading. If an argument is given, +it is used as a directory (i.e. it does not include the name of the +function) in which the function is to be found; this may be combined +with the @t{-d} option to allow the function search to default to @t{$fpath} +if it is not in the given location. + +@noindent +The flag @t{+X} attempts to load each @var{name} as an autoloaded function, +but does @emph{not} execute it. The exit status is zero (success) if the +function was not previously defined @emph{and} a definition for it was found. +This does @emph{not} replace any existing definition of the function. The +exit status is nonzero (failure) if the function was already defined or +when no definition was found. In the latter case the function remains +undefined and marked for autoloading. If ksh-style autoloading is +enabled, the function created will contain the contents of the file +plus a call to the function itself appended to it, thus giving normal +ksh autoloading behaviour on the first call to the function. +If the @t{-m} flag is also given each @var{name} is treated as a +pattern and all functions already marked for autoload that match the +pattern are loaded. + +@noindent +With the @t{-t} flag, turn on execution tracing; with @t{-T}, turn on +execution tracing only for the current function, turning it off on entry +to any called functions that do not also have tracing enabled. + +@noindent +With the @t{-U} flag, alias expansion is suppressed when the function is +loaded. + +@noindent +With the @t{-w} flag, the @var{name}s are taken as names of files compiled +with the @t{zcompile} builtin, and all functions defined in them are +marked for autoloading. + +@noindent +The flags @t{-z} and @t{-k} mark the function to be autoloaded using the +zsh or ksh style, as if the option @t{KSH_AUTOLOAD} were unset or were +set, respectively. The flags override the setting of the option at the +time the function is loaded. + +@noindent +Note that the @t{autoload} command makes no attempt to ensure the +shell options set during the loading or execution of the file have +any particular value. For this, the @t{emulate} command can be used: + +@noindent +@example +emulate zsh -c 'autoload -Uz @var{func}' +@end example + +@noindent +arranges that when @var{func} is loaded the shell is in native @t{zsh} +emulation, and this emulation is also applied when @var{func} is run. + +@noindent +Some of the functions of @t{autoload} are also provided by @t{functions +-u} or @t{functions -U}, but @t{autoload} is a more comprehensive +interface. + +@findex bg +@cindex jobs, backgrounding +@item @t{bg} [ @var{job} ... ] +@itemx @var{job} ... @t{&} +Put each specified @var{job} in the background, +or the current job if none is specified. + +@item @t{bindkey} +See @ref{Zle Builtins}. + +@findex break +@cindex exiting loops +@cindex loops, exiting +@item @t{break} [ @var{n} ] +Exit from an enclosing @t{for}, @t{while}, +@t{until}, @t{select} or @t{repeat} loop. If an arithmetic expression @var{n} +is specified, then break @var{n} levels instead of just one. + +@findex builtin +@item @t{builtin} @var{name} [ @var{args} ... ] +Executes the builtin @var{name}, with the given @var{args}. + +@findex bye +@item @t{bye} +Same as @t{exit}. + +@item @t{cap} +See @ref{The zsh/cap Module}. + +@findex cd +@cindex directories, changing +@item @t{cd} [ @t{-qsLP} ] [ @var{arg} ] +@itemx @t{cd} [ @t{-qsLP} ] @var{old} @var{new} +@itemx @t{cd} [ @t{-qsLP} ] @{@t{+}|@t{-}@}@var{n} +Change the current directory. In the first form, change the +current directory to @var{arg}, or to the value of @t{$HOME} if +@var{arg} is not specified. If @var{arg} is `@t{-}', change to the +previous directory. + +@noindent +Otherwise, if @var{arg} begins with a slash, attempt to change to the +directory given by @var{arg}. + +@noindent +If @var{arg} does not begin with a slash, the behaviour depends on whether +the current directory `@t{.}' occurs in the list of directories contained +in the shell parameter @t{cdpath}. If it does not, first attempt to change +to the directory @var{arg} under the current directory, and if that fails +but @t{cdpath} is set and contains at least one element attempt to change +to the directory @var{arg} under each component of @t{cdpath} in turn until +successful. If `@t{.}' occurs in @t{cdpath}, then @t{cdpath} is searched +strictly in order so that `@t{.}' is only tried at the appropriate point. + +@noindent +The order of testing @t{cdpath} is modified if the option @t{POSIX_CD} +is set, as described in the documentation for the option. + +@noindent +If no directory is found, the option @t{CDABLE_VARS} is set, and a +parameter named @var{arg} exists whose value begins with a slash, treat its +value as the directory. In that case, the parameter is added to the named +directory hash table. + +@noindent +The second form of @t{cd} substitutes the string @var{new} +for the string @var{old} in the name of the current directory, +and tries to change to this new directory. + +@noindent +The third form of @t{cd} extracts an entry from the directory +stack, and changes to that directory. An argument of the form +`@t{+}@var{n}' identifies a stack entry by counting from the left +of the list shown by the @t{dirs} command, starting with zero. +An argument of the form `@t{-}@var{n}' counts from the right. +If the @t{PUSHD_MINUS} option is set, the meanings of `@t{+}' +and `@t{-}' in this context are swapped. +If the @t{POSIX_CD} option is set, this form of @t{cd} is not recognised +and will be interpreted as the first form. + +@noindent +If the @t{-q} (quiet) option is specified, the hook function @t{chpwd} +and the functions in the array @t{chpwd_functions} are not called. +This is useful for calls to @t{cd} that do not change the environment +seen by an interactive user. + +@noindent +If the @t{-s} option is specified, @t{cd} refuses to change the current +directory if the given pathname contains symlinks. If the @t{-P} option +is given or the @t{CHASE_LINKS} option is set, symbolic links are resolved +to their true values. If the @t{-L} option is given symbolic links are +retained in the directory (and not resolved) regardless of the state of +the @t{CHASE_LINKS} option. + +@findex chdir +@item @t{chdir} +Same as @t{cd}. + +@item @t{clone} +See @ref{The zsh/clone Module}. + +@findex command +@item @t{command} [ @t{-pvV} ] @var{simple command} +The simple command argument is taken as an external command instead of +a function or builtin and is executed. If the @t{POSIX_BUILTINS} option +is set, builtins will also be executed but certain special properties +of them are suppressed. The @t{-p} flag causes a default path to be +searched instead of that in @t{$path}. With the @t{-v} flag, @t{command} +is similar to @t{whence} and with @t{-V}, it is equivalent to @t{whence +-v}. + +@noindent +See also @ref{Precommand Modifiers}. + +@item @t{comparguments} +See @ref{The zsh/computil Module}. + +@item @t{compcall} +See @ref{The zsh/compctl Module}. + +@item @t{compctl} +See @ref{The zsh/compctl Module}. + +@item @t{compdescribe} +See @ref{The zsh/computil Module}. + +@item @t{compfiles} +See @ref{The zsh/computil Module}. + +@item @t{compgroups} +See @ref{The zsh/computil Module}. + +@item @t{compquote} +See @ref{The zsh/computil Module}. + +@item @t{comptags} +See @ref{The zsh/computil Module}. + +@item @t{comptry} +See @ref{The zsh/computil Module}. + +@item @t{compvalues} +See @ref{The zsh/computil Module}. + +@findex continue +@cindex loops, continuing +@cindex continuing loops +@item @t{continue} [ @var{n} ] +Resume the next iteration of the enclosing +@t{for}, @t{while}, @t{until}, @t{select} or +@t{repeat} loop. If an arithmetic expression @var{n} is specified, break out of +@var{n}-1 loops and resume at the @var{n}th enclosing loop. + +@findex declare +@item @t{declare} +Same as @t{typeset}. + +@findex dirs +@cindex directory stack, printing +@item @t{dirs} [ @t{-c} ] [ @var{arg} ... ] +@itemx @t{dirs} [ @t{-lpv} ] +With no arguments, print the contents of the directory stack. +Directories are added to this stack with the @t{pushd} command, +and removed with the @t{cd} or @t{popd} commands. +If arguments are specified, load them onto the directory stack, +replacing anything that was there, and push the current directory +onto the stack. + +@noindent +@table @asis +@item @t{-c} +clear the directory stack. + +@item @t{-l} +print directory names in full instead of using of using @t{~} expressions (@ref{Filename Expansion}). + +@item @t{-p} +print directory entries one per line. + +@item @t{-v} +number the directories in the stack when printing. + +@end table + +@noindent + +@findex disable +@cindex disabling commands +@cindex commands, disabling +@item @t{disable} [ @t{-afmprs} ] @var{name} ... +Temporarily disable the @var{name}d hash table elements or patterns. The default +is to disable builtin commands. This allows you to use an external +command with the same name as a builtin command. The @t{-a} option +causes @t{disable} to act on regular or global aliases. The @t{-s} +option causes @t{disable} to act on suffix aliases. The @t{-f} option causes +@t{disable} to act on shell functions. The @t{-r} options causes +@t{disable} to act on reserved words. Without arguments all disabled +hash table elements from the corresponding hash table are printed. +With the @t{-m} flag the arguments are taken as patterns (which should be +quoted to prevent them from undergoing filename expansion), and all hash +table elements from the corresponding hash table matching these patterns +are disabled. Disabled objects can be enabled with the @t{enable} +command. + +@noindent +With the option @t{-p}, @var{name} ... refer to elements of the +shell's pattern syntax as described in @ref{Filename Generation}. +Certain elements can be disabled separately, as given below. + +@noindent +Note that patterns +not allowed by the current settings for the options @t{EXTENDED_GLOB}, +@t{KSH_GLOB} and @t{SH_GLOB} are never enabled, regardless of the +setting here. For example, if @t{EXTENDED_GLOB} is not active, +the pattern @t{^} is ineffective even if `@t{disable -p "^"}' has +not been issued. The list below indicates any option settings +that restrict the use of the pattern. It should be noted that +setting @t{SH_GLOB} has a wider effect than merely disabling patterns +as certain expressions, in particular those involving parentheses, +are parsed differently. + +@noindent +The following patterns may be disabled; all +the strings need quoting on the command line to prevent them from +being interpreted immediately as patterns and the patterns are +shown below in single quotes as a reminder. + +@noindent +@table @asis +@item @t{'?'} +The pattern character @t{?} wherever it occurs, including when preceding +a parenthesis with @t{KSH_GLOB}. + +@item @t{'*'} +The pattern character @t{*} wherever it occurs, including recursive +globbing and when preceding a parenthesis with @t{KSH_GLOB}. + +@item @t{'['} +Character classes. + +@item @t{'<'} (@t{NO_SH_GLOB}) +Numeric ranges. + +@item @t{'|'} (@t{NO_SH_GLOB}) +Alternation in grouped patterns, case statements, or KSH_GLOB +parenthesised expressions. + +@item @t{'('} (@t{NO_SH_GLOB}) +Grouping using single parentheses. Disabling this does not disable the +use of parentheses for @t{KSH_GLOB} where they are introduced by a +special character, nor for glob qualifiers (use `@t{setopt +NO_BARE_GLOB_QUAL}' to disable glob qualifiers that use parentheses +only). + +@item @t{'~'} (@t{EXTENDED_GLOB}) +Exclusion in the form @var{A}@t{~}@var{B}. + +@item @t{'^'} (@t{EXTENDED_GLOB}) +Exclusion in the form @var{A}@t{^}@var{B}. + +@item @t{'#'} (@t{EXTENDED_GLOB}) +The pattern character @t{#} wherever it occurs, both for +repetition of a previous pattern and for indicating globbing flags. + +@item @t{'?('} (@t{KSH_GLOB}) +The grouping form @t{?(}@var{...}@t{)}. Note this is also +disabled if @t{'?'} is disabled. + +@item @t{'*('} (@t{KSH_GLOB}) +The grouping form @t{*(}@var{...}@t{)}. Note this is also +disabled if @t{'*'} is disabled. + +@item @t{'+('} (@t{KSH_GLOB}) +The grouping form @t{+(}@var{...}@t{)}. + +@item @t{'!('} (@t{KSH_GLOB}) +The grouping form @t{!(}@var{...}@t{)}. + +@item @t{'@@('} (@t{KSH_GLOB}) +The grouping form @t{@@(}@var{...}@t{)}. + +@end table + +@findex disown +@cindex jobs, disowning +@item @t{disown} [ @var{job} ... ] +@itemx @var{job} ... @t{&|} +@itemx @var{job} ... @t{&!} +Remove the specified @var{job}s from the job table; the shell will +no longer report their status, and will not complain if you +try to exit an interactive shell with them running or stopped. +If no @var{job} is specified, disown the current job. + +@noindent +If the @var{job}s are currently stopped and the @t{AUTO_CONTINUE} option +is not set, a warning is printed containing information about how to +make them running after they have been disowned. If one of the latter +two forms is used, the @var{job}s will automatically be made running, +independent of the setting of the @t{AUTO_CONTINUE} option. + +@findex echo +@item @t{echo} [ @t{-neE} ] [ @var{arg} ... ] +Write each @var{arg} on the standard output, with a space separating +each one. +If the @t{-n} flag is not present, print a newline at the end. +@t{echo} recognizes the following escape sequences: + +@noindent +@table @asis +@item @t{\a} +bell character +@item @t{\b} +backspace +@item @t{\c} +suppress subsequent characters and final newline +@item @t{\e} +escape +@item @t{\f} +form feed +@item @t{\n} +linefeed (newline) +@item @t{\r} +carriage return +@item @t{\t} +horizontal tab +@item @t{\v} +vertical tab +@item @t{\\} +backslash +@item @t{\0}@var{NNN} +character code in octal +@item @t{\x}@var{NN} +character code in hexadecimal +@item @t{\u}@var{NNNN} +unicode character code in hexadecimal +@item @t{\U}@var{NNNNNNNN} +unicode character code in hexadecimal +@end table + +@noindent +@pindex BSD_ECHO, use of +The @t{-E} flag, or the @t{BSD_ECHO} option, can be used to disable +these escape sequences. In the latter case, @t{-e} flag can be used to +enable them. + +@noindent +Note that for standards compliance a double dash does not terminate +option processing; instead, it is printed directly. However, a +single dash does terminate option processing, so the first dash, +possibly following options, is not printed, but everything following it +is printed as an argument. The single dash behaviour is different +from other shells. For a more portable way of printing text, see +@t{printf}, and for a more controllable way of printing text within zsh, +see @t{print}. + +@item @t{echotc} +See @ref{The zsh/termcap Module}. + +@item @t{echoti} +See @ref{The zsh/terminfo Module}. + +@findex emulate +@cindex compatibility, sh +@cindex compatibility, ksh +@cindex compatibility, csh +@cindex sh, compatibility +@cindex ksh, compatibility +@cindex csh, compatibility +@item @t{emulate} [ @t{-lLR} ] [ @{@t{zsh}|@t{sh}|@t{ksh}|@t{csh}@} [ @var{flags} ... ] ] +Without any argument print current emulation mode. + +@noindent +With single argument set up zsh options to emulate the specified shell +as much as possible. +@cite{csh} will never be fully emulated. +If the argument is not one of the shells listed above, @t{zsh} +will be used as a default; more precisely, the tests performed on the +argument are the same as those used to determine the emulation at startup +based on the shell name, see +@ref{Compatibility} +. In addition to setting shell options, the command also restores +the pristine state of pattern enables, as if all patterns had been +enabled using @t{enable -p}. + +@noindent +If the @t{emulate} command occurs inside a function that has been +marked for execution tracing with @t{functions -t} then the @t{xtrace} +option will be turned on regardless of emulation mode or other options. +Note that code executed inside the function by the @t{.}, @t{source}, or +@t{eval} commands is not considered to be running directly from the +function, hence does not provoke this behaviour. + +@noindent +If the @t{-R} switch is given, all settable options +are reset to their default value corresponding to the specified emulation +mode, except for certain options describing the interactive +environment; otherwise, only those options likely to cause portability +problems in scripts and functions are altered. If the @t{-L} switch is given, +the options @t{LOCAL_OPTIONS}, @t{LOCAL_PATTERNS} and @t{LOCAL_TRAPS} +will be set as +well, causing the effects of the @t{emulate} command and any @t{setopt}, +@t{disable -p} or @t{enable -p}, and @t{trap} commands to be local to +the immediately surrounding shell +function, if any; normally these options are turned off in all emulation +modes except @t{ksh}. The @t{-L} switch is mutually exclusive with the +use of @t{-c} in @var{flags}. + +@noindent +If there is a single argument and the @t{-l} switch is given, the +options that would be set or unset (the latter indicated with the prefix +`@t{no}') are listed. @t{-l} can be combined with @t{-L} or @t{-R} and +the list will be modified in the appropriate way. Note the list does +not depend on the current setting of options, i.e. it includes all +options that may in principle change, not just those that would actually +change. + +@noindent +The @var{flags} may be any of the invocation-time flags described in +@ref{Invocation}, +except that `@t{-o EMACS}' and `@t{-o VI}' may not be used. Flags such +as `@t{+r}'/`@t{+o RESTRICTED}' may be prohibited in some circumstances. + +@noindent +If @t{-c} @var{arg} appears in @var{flags}, @var{arg} is evaluated while the +requested emulation is temporarily in effect. In this case the emulation +mode and all options are restored to their previous values before +@t{emulate} returns. The @t{-R} switch may precede the name of the shell +to emulate; note this has a meaning distinct from including @t{-R} in +@var{flags}. + +@noindent +Use of @t{-c} enables `sticky' emulation mode for functions defined +within the evaluated expression: the emulation mode is associated +thereafter with the function so that whenever the function is executed +the emulation (respecting the @t{-R} switch, if present) and all +options are set (and pattern disables cleared) +before entry to the function, and the state is restored after exit. +If the function is called when the sticky emulation is already in +effect, either within an `@t{emulate} @var{shell} @t{-c}' expression or +within another function with the same sticky emulation, entry and exit +from the function do not cause options to be altered (except due to +standard processing such as the @t{LOCAL_OPTIONS} option). This also +applies to functions marked for autoload within the sticky emulation; +the appropriate set of options will be applied at the point the +function is loaded as well as when it is run. + +@noindent +For example: + +@noindent +@example +emulate sh -c 'fni() @{ setopt cshnullglob; @} +fno() @{ fni; @}' +fno +@end example + +@noindent +The two functions @t{fni} and @t{fno} are defined with sticky @t{sh} +emulation. @t{fno} is then executed, causing options associated +with emulations to be set to their values in @t{sh}. @t{fno} then +calls @t{fni}; because @t{fni} is also marked for sticky @t{sh} +emulation, no option changes take place on entry to or exit from it. +Hence the option @t{cshnullglob}, turned off by @t{sh} emulation, will +be turned on within @t{fni} and remain on return to @t{fno}. On exit +from @t{fno}, the emulation mode and all options will be restored to the +state they were in before entry to the temporary emulation. + +@noindent +The documentation above is typically sufficient for the intended +purpose of executing code designed for other shells in a suitable +environment. More detailed rules follow. +@table @asis +@item 1. +The sticky emulation environment provided by `@t{emulate} +@var{shell} @t{-c}' is identical to that provided by entry to +a function marked for sticky emulation as a consequence of being +defined in such an environment. Hence, for example, the sticky +emulation is inherited by subfunctions defined within functions +with sticky emulation. +@item 2. +No change of options takes place on entry to or exit from +functions that are not marked for sticky emulation, other than those +that would normally take place, even if those functions are called +within sticky emulation. +@item 3. +No special handling is provided for functions marked for +@t{autoload} nor for functions present in wordcode created by +the @t{zcompile} command. +@item 4. +The presence or absence of the @t{-R} switch to @t{emulate} +corresponds to different sticky emulation modes, so for example +`@t{emulate sh -c}', `@t{emulate -R sh -c}' and `@t{emulate csh -c}' +are treated as three distinct sticky emulations. +@item 5. +Difference in shell options supplied in addition to the +basic emulation also mean the sticky emulations are different, so for +example `@t{emulate zsh -c}' and `@t{emulate zsh -o cbases -c}' are +treated as distinct sticky emulations. +@end table + +@findex enable +@cindex enabling commands +@cindex commands, enabling +@item @t{enable} [ @t{-afmprs} ] @var{name} ... +Enable the @var{name}d hash table elements, presumably disabled +earlier with @t{disable}. The default is to enable builtin commands. +The @t{-a} option causes @t{enable} to act on regular or global aliases. +The @t{-s} option causes @t{enable} to act on suffix aliases. +The @t{-f} option causes @t{enable} to act on shell functions. The @t{-r} +option causes @t{enable} to act on reserved words. Without arguments +all enabled hash table elements from the corresponding hash table are +printed. With the @t{-m} flag the arguments are taken as patterns +(should be quoted) and all hash table elements from the corresponding +hash table matching these patterns are enabled. Enabled objects can be +disabled with the @t{disable} builtin command. + +@noindent +@t{enable -p} reenables patterns disabled with @t{disable -p}. Note +that it does not override globbing options; for example, `@t{enable -p +"~"}' does not cause the pattern character @t{~} to be active unless +the @t{EXTENDED_GLOB} option is also set. To enable all possible +patterns (so that they may be individually disabled with @t{disable -p}), +use `@t{setopt EXTENDED_GLOB KSH_GLOB NO_SH_GLOB}'. + +@findex eval +@cindex evaluating arguments as commands +@item @t{eval} [ @var{arg} ... ] +Read the arguments as input to the shell and execute the resulting +command(s) in the current shell process. The return status is +the same as if the commands had been executed directly by the shell; +if there are no @var{args} or they contain no commands (i.e. are +an empty string or whitespace) the return status is zero. + +@item @t{exec} [ @t{-cl} ] [ @t{-a} @var{argv0} ] [ @var{command} [ @var{arg} ... ] ] +Replace the current shell with @var{command} rather than forking. +If @var{command} is a shell builtin command or a shell function, +the shell executes it, and exits when the command is complete. + +@noindent +With @t{-c} clear the environment; with @t{-l} prepend @t{-} to the +@t{argv[0]} string of the command executed (to simulate a login shell); +with @t{-a} @var{argv0} set the @t{argv[0]} string of the command +executed. +See @ref{Precommand Modifiers}. + +@noindent +If the option @t{POSIX_BUILTINS} is set, @var{command} is never +interpreted as a shell builtin command or shell function. This +means further precommand modifiers such as @t{builtin} and +@t{noglob} are also not interpreted within the shell. Hence +@var{command} is always found by searching the command path. + +@noindent +@cindex redirection, current shell's I/O +If @var{command} is omitted but any redirections are specified, +then the redirections will take effect in the current shell. + +@findex exit +@item @t{exit} [ @var{n} ] +Exit the shell with the exit status specified by an arithmetic +expression @var{n}; if none +is specified, use the exit status from the last command executed. +@pindex IGNORE_EOF, use of +An EOF condition will also cause the shell to exit, unless +the @t{IGNORE_EOF} option is set. + +@noindent +See notes at the end of +@ref{Jobs & Signals} for some possibly unexpected interactions +of the @t{exit} command with jobs. + +@findex export +@item @t{export} [ @var{name}[@t{=}@var{value}] ... ] +The specified @var{name}s are marked for automatic export +to the environment of subsequently executed commands. +Equivalent to @t{typeset -gx}. +If a parameter specified does not +already exist, it is created in the global scope. + +@findex false +@cindex doing nothing, unsuccessfully +@item @t{false} [ @var{arg} ... ] +Do nothing and return an exit status of 1. + +@findex fc +@cindex history, editing +@cindex editing history + +@item @t{fc} [ @t{-e} @var{ename} ] [ @t{-LI} ] [ @t{-m} @var{match} ] [ @var{old}@t{=}@var{new} ... ] [ @var{first} [ @var{last} ] ] +@itemx @t{fc -l }[ @t{-LI} ] [ @t{-nrdfEiD} ] [ @t{-t} @var{timefmt} ] [ @t{-m} @var{match} ] +@itemx @t{@ @ @ @ @ @ }[ @var{old}@t{=}@var{new} ... ] [ @var{first} [ @var{last} ] ] +@itemx @t{fc -p }[ @t{-a} ] [ @var{filename} [ @var{histsize} [ @var{savehistsize} ] ] ] +@itemx @t{fc} @t{-P} +@itemx @t{fc} @t{-ARWI} [ @var{filename} ] +The @t{fc} command controls the interactive history mechanism. Note +that reading and writing of history options is only performed if the +shell is interactive. Usually this is detected automatically, but +it can be forced by setting the @t{interactive} option when starting the +shell. + +@noindent +The first two forms of this command select a range of events from +@var{first} to @var{last} from the history list. The arguments @var{first} +and @var{last} may be specified as a number or as a string. A negative +number is used as an offset to the current history event number. A string +specifies the most recent event beginning with the given string. All +substitutions @var{old}@t{=}@var{new}, if any, are then performed on the +text of the events. + +@noindent +In addition to the number range, +@table @asis +@item @t{-I} +restricts to only internal events (not from @t{$HISTFILE}) +@item @t{-L} +restricts to only local events (not from other shells, see +@t{SHARE_HISTORY} in @ref{Description of Options} -- note that @t{$HISTFILE} is +considered local when read at startup) +@item @t{-m} +takes the first argument as a pattern (should be quoted) and +only the history events matching this pattern are considered +@end table + +@noindent +If @var{first} is not specified, it will be set to -1 (the most recent +event), or to -16 if the @t{-l} flag is given. +If @var{last} is not specified, it will be set to @var{first}, +or to -1 if the @t{-l} flag is given. +However, if the current event has added entries to the history with +`@t{print -s}' or `@t{fc -R}', then the default @var{last} for @t{-l} +includes all new history entries since the current event began. + +@noindent +When the @t{-l} flag is given, the resulting events are listed on +standard output. Otherwise the editor program specified by @t{-e} @var{ename} +is invoked on a file containing these history events. If @t{-e} is not given, the +value of the parameter @t{FCEDIT} is used; if that is not set the value of +the parameter @t{EDITOR} is used; if that is not set a builtin default, +usually `@t{vi}' is used. If @var{ename} is `@t{-}', no editor is invoked. +When editing is complete, the edited command is executed. + +@noindent +The flag @t{-r} reverses the order of the events and the +flag @t{-n} suppresses event numbers when listing. + +@noindent +Also when listing, +@table @asis +@item @t{-d} +prints timestamps for each event +@item @t{-f} +prints full time-date stamps in the US +`@var{MM}@t{/}@var{DD}@t{/}@var{YY} @var{hh}@t{:}@var{mm}' format +@item @t{-E} +prints full time-date stamps in the European +`@var{dd}@t{.}@var{mm}@t{.}@var{yyyy} @var{hh}@t{:}@var{mm}' format +@item @t{-i} +prints full time-date stamps in ISO8601 +`@var{yyyy}@t{-}@var{mm}@t{-}@var{dd} @var{hh}@t{:}@var{mm}' format +@item @t{-t} @var{fmt} +prints time and date stamps in the given format; +@var{fmt} is formatted with the strftime function with the zsh extensions +described for the @t{%D@{}@var{string}@t{@}} prompt format in +@ref{Prompt Expansion}. The resulting formatted string must be +no more than 256 characters or will not be printed + +@item @t{-D} +prints elapsed times; may be combined with one of the +options above +@end table + +@noindent +@cindex history, stack +@cindex stack, history +`@t{fc -p}' pushes the current history list onto a stack and switches to a +new history list. If the @t{-a} option is also specified, this history list +will be automatically popped when the current function scope is exited, which +is a much better solution than creating a trap function to call `@t{fc -P}' +manually. If no arguments are specified, the history list is left empty, +@t{$HISTFILE} is unset, and @t{$HISTSIZE} & @t{$SAVEHIST} are set to their +default values. If one argument is given, @t{$HISTFILE} is set to that +filename, @t{$HISTSIZE} & @t{$SAVEHIST} are left unchanged, and the history +file is read in (if it exists) to initialize the new list. If a second +argument is specified, @t{$HISTSIZE} & @t{$SAVEHIST} are instead set to the +single specified numeric value. Finally, if a third argument is specified, +@t{$SAVEHIST} is set to a separate value from @t{$HISTSIZE}. You are free to +change these environment values for the new history list however you desire +in order to manipulate the new history list. + +@noindent +`@t{fc -P}' pops the history list back to an older list saved by `@t{fc -p}'. +The current list is saved to its @t{$HISTFILE} before it is destroyed +(assuming that @t{$HISTFILE} and @t{$SAVEHIST} are set appropriately, of +course). The values of @t{$HISTFILE}, @t{$HISTSIZE}, and @t{$SAVEHIST} are +restored to the values they had when `@t{fc -p}' was called. Note that this +restoration can conflict with making these variables "local", so your best +bet is to avoid local declarations for these variables in functions that use +`@t{fc -p}'. The one other guaranteed-safe combination is declaring these +variables to be local at the top of your function and using the automatic +option (@t{-a}) with `@t{fc -p}'. Finally, note that it is legal to manually +pop a push marked for automatic popping if you need to do so before the +function exits. + +@noindent +@cindex history, file +@cindex file, history +`@t{fc -R}' reads the history from the given file, +`@t{fc -W}' writes the history out to the given file, +and `@t{fc -A}' appends the history out to the given file. +If no filename is specified, the @t{$HISTFILE} is assumed. +If the @t{-I} option is added to @t{-R}, only those events that are +not already contained within the internal history list are added. +If the @t{-I} option is added to @t{-A} or @t{-W}, only those +events that are new since last incremental append/write to +the history file are appended/written. +In any case, the created file will have no more than @t{$SAVEHIST} +entries. + +@findex fg +@cindex jobs, foregrounding +@cindex jobs, resuming +@item @t{fg} [ @var{job} ... ] +@itemx @var{job} ... +Bring each specified @var{job} in turn to the foreground. +If no @var{job} is specified, resume the current job. + +@findex float +@item @t{float} [ @{@t{+}|@t{-}@}@t{Hghlprtux} ] [ @{@t{+}|@t{-}@}@t{EFLRZ} [ @var{n} ] ] [ @var{name}[@t{=}@var{value}] ... ] +Equivalent to @t{typeset -E}, except that options irrelevant to floating +point numbers are not permitted. + +@findex functions +@item @t{functions} [ @{@t{+}|@t{-}@}@t{UkmtTuWz} ] [ @t{-x} @var{num} ] [ @var{name} ... ] +@itemx @t{functions -c} @var{oldfn} @var{newfn} +@itemx @t{functions -M} [@t{-s}] @var{mathfn} [ @var{min} [ @var{max} [ @var{shellfn} ] ] ] +@itemx @t{functions -M} [ @t{-m} @var{pattern} ... ] +@itemx @t{functions +M} [ @t{-m} ] @var{mathfn} ... +Equivalent to @t{typeset -f}, with the exception of the @t{-c}, @t{-x}, +@t{-M} and @t{-W} options. For @t{functions -u} and @t{functions -U}, +see @t{autoload}, which provides additional options. + +@noindent +The @t{-x} option indicates that any functions output will have +each leading tab for indentation, added by the shell to show syntactic +structure, expanded to the given number @var{num} of spaces. @var{num} +can also be 0 to suppress all indentation. + +@noindent +The @t{-W} option turns on the option @t{WARN_NESTED_VAR} for the named +function or functions only. The option is turned off at the start of +nested functions (apart from anonoymous functions) unless the called +function also has the @t{-W} attribute. + +@noindent +The @t{-c} option causes @var{oldfn} to be copied to @var{newfn}. The +copy is efficiently handled internally by reference counting. If +@var{oldfn} was marked for autoload it is first loaded and if this +fails the copy fails. Either function may subsequently be redefined +without affecting the other. A typical idiom is that @var{oldfn} is the +name of a library shell function which is then redefined to call +@t{newfn}, thereby installing a modified version of the function. + +@noindent +Use of the @t{-M} option may not be combined with any of the options +handled by @t{typeset -f}. + +@noindent +@t{functions -M} @var{mathfn} defines @var{mathfn} as the name of +a mathematical function recognised in all forms of arithmetical expressions; +see +@ref{Arithmetic Evaluation}. By default @var{mathfn} may take +any number of comma-separated arguments. If @var{min} is given, +it must have exactly @var{min} args; if @var{min} and @var{max} are +both given, it must have at least @var{min} and at most @var{max} +args. @var{max} may be -1 to indicate that there is no upper limit. + +@noindent +By default the function is implemented by a shell function of the same +name; if @var{shellfn} is specified it gives the name of the corresponding +shell function while @var{mathfn} remains the name used in arithmetical +expressions. The name of the function in @t{$0} is @var{mathfn} (not +@var{shellfn} as would usually be the case), provided the option +@t{FUNCTION_ARGZERO} is in effect. The positional parameters in the shell +function correspond to the arguments of the mathematical function call. +The result of the last arithmetical expression evaluated +inside the shell function (even if it is a form that normally only returns +a status) gives the result of the mathematical function. + +@noindent +If the additional option @t{-s} is given to @t{functions -M}, the +argument to the function is a single string: anything between the +opening and matching closing parenthesis is passed to the function as a +single argument, even if it includes commas or white space. The minimum +and maximum argument specifiers must therefore be 1 if given. An empty +argument list is passed as a zero-length string. + +@noindent +@t{functions -M} with no arguments lists all such user-defined functions in +the same form as a definition. With the additional option @t{-m} and +a list of arguments, all functions whose @var{mathfn} matches one of +the pattern arguments are listed. + +@noindent +@t{function +M} removes the list of mathematical functions; with the +additional option @t{-m} the arguments are treated as patterns and +all functions whose @var{mathfn} matches the pattern are removed. Note +that the shell function implementing the behaviour is not removed +(regardless of whether its name coincides with @var{mathfn}). + +@noindent +For example, the following prints the cube of 3: + +@noindent +@example +zmath_cube() @{ (( $1 * $1 * $1 )) @} +functions -M cube 1 1 zmath_cube +print $(( cube(3) )) +@end example + +@noindent +The following string function takes a single argument, including +the commas, so prints 11: + +@noindent +@example +stringfn() @{ (( $#1 )) @} +functions -Ms stringfn +print $(( stringfn(foo,bar,rod) )) +@end example + +@item @t{getcap} +See @ref{The zsh/cap Module}. + +@findex getln +@cindex line, reading +@cindex reading a line +@item @t{getln} [ @t{-AclneE} ] @var{name} ... +Read the top value from the buffer stack and put it in +the shell parameter @var{name}. Equivalent to +@t{read -zr}. + +@findex getopts +@cindex options, processing +@item @t{getopts} @var{optstring} @var{name} [ @var{arg} ... ] +Checks the @var{arg}s for legal options. If the @var{arg}s are omitted, +use the positional parameters. A valid option argument +begins with a `@t{+}' or a `@t{-}'. An argument not beginning with +a `@t{+}' or a `@t{-}', or the argument `@t{-}@t{-}', ends the options. +Note that a single `@t{-}' is not considered a valid option argument. +@var{optstring} contains the letters that @t{getopts} +recognizes. If a letter is followed by a `@t{:}', that option +requires an argument. The options can be +separated from the argument by blanks. + +@noindent +Each time it is invoked, @t{getopts} places the option letter it finds +in the shell parameter @var{name}, prepended with a `@t{+}' when +@var{arg} begins with a `@t{+}'. The index of the next @var{arg} +is stored in @t{OPTIND}. The option argument, if any, +is stored in @t{OPTARG}. +@vindex OPTIND, use of +@vindex OPTARG, use of + +@noindent +The first option to be examined may be changed by explicitly assigning +to @t{OPTIND}. @t{OPTIND} has an initial value of @t{1}, and is +normally set to @t{1} upon entry to a shell function and restored +upon exit (this is disabled by the @t{POSIX_BUILTINS} option). @t{OPTARG} +is not reset and retains its value from the most recent call to +@t{getopts}. If either of @t{OPTIND} or @t{OPTARG} is explicitly +unset, it remains unset, and the index or option argument is not +stored. The option itself is still stored in @var{name} in this case. + +@noindent +A leading `@t{:}' in @var{optstring} causes @t{getopts} to store the +letter of any invalid option in @t{OPTARG}, and to set @var{name} to +`@t{?}' for an unknown option and to `@t{:}' when a required argument is +missing. Otherwise, @t{getopts} sets @var{name} to `@t{?}' and prints +an error message when an option is invalid. The exit status is +nonzero when there are no more options. + +@findex hash +@item @t{hash} [ @t{-Ldfmrv} ] [ @var{name}[@t{=}@var{value}] ] ... +@t{hash} can be used to directly modify the contents of the command +hash table, and the named directory hash table. Normally one would +modify these tables by modifying one's @t{PATH} +(for the command hash table) or by creating appropriate shell parameters +(for the named directory hash table). +The choice of hash table to work on is determined by the @t{-d} option; +without the option the command hash table is used, and with the option the +named directory hash table is used. + +@noindent +A command @var{name} starting with a @t{/} is never hashed, whether by +explicit use of the @t{hash} command or otherwise. Such a command +is always found by direct look up in the file system. + +@noindent +Given no arguments, and neither the @t{-r} or @t{-f} options, +the selected hash table will be listed in full. + +@noindent +The @t{-r} option causes the selected hash table to be emptied. +It will be subsequently rebuilt in the normal fashion. +The @t{-f} option causes the selected hash table to be fully +rebuilt immediately. For the command hash table this hashes +all the absolute directories in the @t{PATH}, +and for the named directory hash table this adds all users' home directories. +These two options cannot be used with any arguments. + +@noindent +The @t{-m} option causes the arguments to be taken as patterns +(which should be quoted) and the elements of the hash table +matching those patterns are printed. This is the only way to display +a limited selection of hash table elements. + +@noindent +For each @var{name} with a corresponding @var{value}, put `@var{name}' in +the selected hash table, associating it with the pathname `@var{value}'. +In the command hash table, this means that +whenever `@var{name}' is used as a command argument, the shell will try +to execute the file given by `@var{value}'. +In the named directory hash table, this means +that `@var{value}' may be referred to as `@t{~}@var{name}'. + +@noindent +For each @var{name} with no +corresponding @var{value}, attempt to add @var{name} to the hash table, +checking what the appropriate @t{value} is in the normal manner for +that hash table. If an appropriate @t{value} can't be found, then +the hash table will be unchanged. + +@noindent +The @t{-v} option causes hash table entries to be listed as they are +added by explicit specification. If has no effect if used with @t{-f}. + +@noindent +If the @t{-L} flag is present, then each hash table entry is printed in +the form of a call to hash. + +@findex history +@item @t{history} +Same as @t{fc -l}. + +@findex integer +@item @t{integer} [ @{@t{+}|@t{-}@}@t{Hghlprtux} ] [ @{@t{+}|@t{-}@}@t{LRZi} [ @var{n} ] ] [ @var{name}[@t{=}@var{value}] ... ] +Equivalent to @t{typeset -i}, except that options irrelevant to +integers are not permitted. + +@findex jobs +@item @t{jobs} [ @t{-dlprs} ] [ @var{job} ... ] +@itemx @t{jobs -Z} @var{string} +Lists information about each given job, or all jobs +if @var{job} is omitted. The @t{-l} flag lists process +IDs, and the @t{-p} flag lists process groups. +If the @t{-r} flag is specified only running jobs will be listed +and if the @t{-s} flag is given only stopped jobs are shown. +If the @t{-d} flag is given, the directory from which the job was +started (which may not be the current directory of the job) will also +be shown. + +@noindent +The @t{-Z} option replaces the shell's argument and environment space with +the given string, truncated if necessary to fit. This will normally be +visible in @t{ps} (man page ps(1)) listings. This feature is typically +used by daemons, to indicate their state. + +@findex kill +@cindex killing jobs +@cindex jobs, killing +@item @t{kill} [ @t{-s} @var{signal_name} | @t{-n} @var{signal_number} | @t{-}@var{sig} ] @var{job} ... +@itemx @t{kill} @t{-l} [ @var{sig} ... ] +Sends either @t{SIGTERM} or the specified signal to the given +jobs or processes. +Signals are given by number or by names, with or without the `@t{SIG}' +prefix. +If the signal being sent is not `@t{KILL}' or `@t{CONT}', then the job +will be sent a `@t{CONT}' signal if it is stopped. +The argument @var{job} can be the process ID of a job +not in the job list. +In the second form, @t{kill -l}, if @var{sig} is not +specified the signal names are listed. Otherwise, for each +@var{sig} that is a name, the corresponding signal number is +listed. For each @var{sig} that is a signal number or a number +representing the exit status of a process which was terminated or +stopped by a signal the name of the signal is printed. + +@noindent +On some systems, alternative signal names are allowed for a few signals. +Typical examples are @t{SIGCHLD} and @t{SIGCLD} or @t{SIGPOLL} and +@t{SIGIO}, assuming they correspond to the same signal number. @t{kill +-l} will only list the preferred form, however @t{kill -l} @var{alt} will +show if the alternative form corresponds to a signal number. For example, +under Linux @t{kill -l IO} and @t{kill -l POLL} both output 29, hence +@t{kill -IO} and @t{kill -POLL} have the same effect. + +@noindent +Many systems will allow process IDs to be negative to kill a process +group or zero to kill the current process group. + +@findex let +@item @t{let} @var{arg} ... +Evaluate each @var{arg} as an arithmetic expression. +See +@ref{Arithmetic Evaluation} +for a description of arithmetic expressions. The exit status is 0 if the +value of the last expression is nonzero, 1 if it is zero, and 2 if +an error occurred. + +@findex limit +@cindex resource limits +@cindex limits, resource +@item @t{limit} [ @t{-hs} ] [ @var{resource} [ @var{limit} ] ] ... +Set or display resource limits. Unless the @t{-s} flag is given, +the limit applies only the children of the shell. If @t{-s} is +given without other arguments, the resource limits of the current +shell is set to the previously set resource limits of the children. + +@noindent +If @var{limit} is not specified, print the current limit placed +on @var{resource}, otherwise +set the limit to the specified value. If the @t{-h} flag +is given, use hard limits instead of soft limits. +If no @var{resource} is given, print all limits. + +@noindent +When looping over multiple resources, the shell will abort immediately if +it detects a badly formed argument. However, if it fails to set a limit +for some other reason it will continue trying to set the remaining limits. + +@noindent +@var{resource} can be one of: + +@noindent +@table @asis +@item @t{addressspace} +Maximum amount of address space used. +@item @t{aiomemorylocked} +Maximum amount of memory locked in RAM for AIO operations. +@item @t{aiooperations} +Maximum number of AIO operations. +@item @t{cachedthreads} +Maximum number of cached threads. +@item @t{coredumpsize} +Maximum size of a core dump. +@item @t{cputime} +Maximum CPU seconds per process. +@item @t{datasize} +Maximum data size (including stack) for each process. +@item @t{descriptors} +Maximum value for a file descriptor. +@item @t{filesize} +Largest single file allowed. +@item @t{kqueues} +Maximum number of kqueues allocated. +@item @t{maxproc} +Maximum number of processes. +@item @t{maxpthreads} +Maximum number of threads per process. +@item @t{memorylocked} +Maximum amount of memory locked in RAM. +@item @t{memoryuse} +Maximum resident set size. +@item @t{msgqueue} +Maximum number of bytes in POSIX message queues. +@item @t{posixlocks} +Maximum number of POSIX locks per user. +@item @t{pseudoterminals} +Maximum number of pseudo-terminals. +@item @t{resident} +Maximum resident set size. +@item @t{sigpending} +Maximum number of pending signals. +@item @t{sockbufsize} +Maximum size of all socket buffers. +@item @t{stacksize} +Maximum stack size for each process. +@item @t{swapsize} +Maximum amount of swap used. +@item @t{vmemorysize} +Maximum amount of virtual memory. +@end table + +@noindent +Which of these resource limits are available depends on the system. +@var{resource} can be abbreviated to any unambiguous prefix. It +can also be an integer, which corresponds to the integer defined +for the resource by the operating system. + +@noindent +If argument corresponds to a number which is out of the range of the +resources configured into the shell, the shell will try to read or write +the limit anyway, and will report an error if this fails. As the shell +does not store such resources internally, an attempt to set the limit will +fail unless the @t{-s} option is present. + +@noindent +@var{limit} is a number, with an optional scaling factor, as follows: + +@noindent +@table @asis +@item @var{n}@t{h} +hours +@item @var{n}@t{k} +kilobytes (default) +@item @var{n}@t{m} +megabytes or minutes +@item @var{n}@t{g} +gigabytes +@item [@var{mm}@t{:}]@var{ss} +minutes and seconds +@end table + +@noindent +The @t{limit} command is not made available by default when the +shell starts in a mode emulating another shell. It can be made available +with the command `@t{zmodload -F zsh/rlimits b:limit}'. + +@findex local +@item @t{local} [ @{@t{+}|@t{-}@}@t{AHUahlprtux} ] [ @{@t{+}|@t{-}@}@t{EFLRZi} [ @var{n} ] ] [ @var{name}[@t{=}@var{value}] ... ] +Same as @t{typeset}, except that the options @t{-g}, and +@t{-f} are not permitted. In this case the @t{-x} option does not force +the use of @t{-g}, i.e. exported variables will be local to functions. + +@findex log +@vindex watch, use of +@cindex watching users +@cindex users, watching +@item @t{log} +List all users currently logged in who are affected by +the current setting of the @t{watch} parameter. + +@findex logout +@item @t{logout} [ @var{n} ] +Same as @t{exit}, except that it only works in a login shell. + +@item @t{noglob} @var{simple command} +See @ref{Precommand Modifiers}. + +@findex popd +@item @t{popd} [ @t{-q} ] [ @{@t{+}|@t{-}@}@var{n} ] +Remove an entry from the directory stack, and perform a @t{cd} to +the new top directory. With no argument, the current top entry is +removed. An argument of the form `@t{+}@var{n}' identifies a stack +entry by counting from the left of the list shown by the @t{dirs} command, +starting with zero. An argument of the form @t{-}@var{n} counts from the right. +@pindex PUSHD_MINUS, use of +If the @t{PUSHD_MINUS} option is set, the meanings of `@t{+}' and +`@t{-}' in this context are swapped. + +@noindent +If the @t{-q} (quiet) option is specified, the hook function @t{chpwd} +and the functions in the array @t{$chpwd_functions} are not called, +and the new directory stack is not printed. This is useful for calls to +@t{popd} that do not change the environment seen by an interactive user. + +@findex print +@item @t{print }[ @t{-abcDilmnNoOpPrsSz} ] [ @t{-u} @var{n} ] [ @t{-f} @var{format} ] [ @t{-C} @var{cols} ] +@itemx @t{@ @ @ @ @ @ }[ @t{-v} @var{name} ] [ @t{-xX} @var{tabstop} ] [ @t{-R} [ @t{-en} ]] [ @var{arg} ... ] +With the `@t{-f}' option the arguments are printed as described by @t{printf}. +With no flags or with the flag `@t{-}', the arguments are printed on +the standard output as described by @t{echo}, with the following differences: +the escape sequence `@t{\M-}@var{x}' (or `@t{\M}@var{x}') metafies the character +@var{x} (sets the highest bit), +`@t{\C-}@var{x}' (or `@t{\C}@var{x}') produces a control character +(`@t{\C-@@}' and `@t{\C-?}' give the characters NULL and delete), +a character code in octal is represented by `@t{\}@var{NNN}' +(instead of `@t{\0}@var{NNN}'), +and `@t{\E}' is a synonym for `@t{\e}'. +Finally, if not in an escape +sequence, `@t{\}' escapes the following character and is not printed. + +@noindent +@table @asis +@item @t{-a} +Print arguments with the column incrementing first. Only useful with the +@t{-c} and @t{-C} options. + +@item @t{-b} +Recognize all the escape sequences defined for the @t{bindkey} command, +see +@ref{Zle Builtins}. + +@item @t{-c} +Print the arguments in columns. Unless @t{-a} is also given, arguments are +printed with the row incrementing first. + +@item @t{-C} @var{cols} +Print the arguments in @var{cols} columns. Unless @t{-a} is also given, +arguments are printed with the row incrementing first. + +@item @t{-D} +Treat the arguments as paths, replacing directory prefixes with @t{~} +expressions corresponding to directory names, as appropriate. + +@item @t{-i} +If given together with @t{-o} or @t{-O}, sorting is performed +case-independently. + +@item @t{-l} +Print the arguments separated by newlines instead of spaces. Note: if +the list of arguments is empty, @t{print -l} will still output one empty +line. To print a possibly-empty list of arguments one per line, use +@t{print -C1}, as in `@t{print -rC1 -- "$list[@@]"}'. + +@item @t{-m} +Take the first argument as a pattern (should be quoted), and remove +it from the argument list together with subsequent arguments that +do not match this pattern. + +@item @t{-n} +Do not add a newline to the output. + +@item @t{-N} +Print the arguments separated and terminated by nulls. Again, +@t{print -rNC1 -- "$list[@@]"} is a canonical way to print an +arbitrary list as null-delimited records. + +@item @t{-o} +Print the arguments sorted in ascending order. + +@item @t{-O} +Print the arguments sorted in descending order. + +@item @t{-p} +Print the arguments to the input of the coprocess. + +@item @t{-P} +Perform prompt expansion (see +@ref{Prompt Expansion}). +In combination with `@t{-f}', +prompt escape sequences are parsed only within interpolated arguments, +not within the format string. + +@item @t{-r} +Ignore the escape conventions of @t{echo}. + +@item @t{-R} +Emulate the BSD @t{echo} command, which does not process escape sequences +unless the @t{-e} flag is given. The @t{-n} flag suppresses the trailing +newline. Only the @t{-e} and @t{-n} flags are recognized after +@t{-R}; all other arguments and options are printed. + +@item @t{-s} +Place the results in the history list instead of on the standard output. +Each argument to the @t{print} command is treated as a single word in the +history, regardless of its content. + +@item @t{-S} +Place the results in the history list instead of on the standard output. +In this case only a single argument is allowed; it will be split into +words as if it were a full shell command line. The effect is +similar to reading the line from a history file with the +@t{HIST_LEX_WORDS} option active. + +@item @t{-u} @var{n} +Print the arguments to file descriptor @var{n}. + +@item @t{-v} @var{name} +Store the printed arguments as the value of the parameter @var{name}. + +@item @t{-x} @var{tab-stop} +Expand leading tabs on each line of output in the printed string +assuming a tab stop every @var{tab-stop} characters. This is appropriate +for formatting code that may be indented with tabs. Note that leading +tabs of any argument to print, not just the first, are expanded, even if +@t{print} is using spaces to separate arguments (the column count +is maintained across arguments but may be incorrect on output +owing to previous unexpanded tabs). + +@noindent +The start of the output of each print command is assumed to be aligned +with a tab stop. Widths of multibyte characters are handled if the +option @t{MULTIBYTE} is in effect. This option is ignored if other +formatting options are in effect, namely column alignment or +@t{printf} style, or if output is to a special location such as shell +history or the command line editor. + +@item @t{-X} @var{tab-stop} +This is similar to @t{-x}, except that all tabs in the printed string +are expanded. This is appropriate if tabs in the arguments are +being used to produce a table format. + +@item @t{-z} +Push the arguments onto the editing buffer stack, separated by spaces. + +@end table + +@noindent +If any of `@t{-m}', `@t{-o}' or `@t{-O}' are used in combination with +`@t{-f}' and there are no arguments (after the removal process in the +case of `@t{-m}') then nothing is printed. + +@findex printf +@item @t{printf} [ @t{-v} @var{name} ] @var{format} [ @var{arg} ... ] +Print the arguments according to the format specification. Formatting +rules are the same as used in C. The same escape sequences as for @t{echo} +are recognised in the format. All C conversion specifications ending in +one of @t{csdiouxXeEfgGn} are handled. In addition to this, `@t{%b}' can be +used instead of `@t{%s}' to cause escape sequences in the argument to be +recognised and `@t{%q}' can be used to quote the argument in such a way +that allows it to be reused as shell input. With the numeric format +specifiers, if the corresponding argument starts with a quote character, +the numeric value of the following character is used as the number to +print; otherwise the argument is evaluated as an arithmetic expression. See +@ref{Arithmetic Evaluation} +for a description of arithmetic +expressions. With `@t{%n}', the corresponding argument is taken as an +identifier which is created as an integer parameter. + +@noindent +Normally, conversion specifications are applied to each argument in order +but they can explicitly specify the @var{n}th argument is to be used by +replacing `@t{%}' by `@t{%}@var{n}@t{$}' and `@t{*}' by `@t{*}@var{n}@t{$}'. +It is recommended that you do not mix references of this explicit style +with the normal style and the handling of such mixed styles may be subject +to future change. + +@noindent +If arguments remain unused after formatting, the format string is reused +until all arguments have been consumed. With the @t{print} builtin, this +can be suppressed by using the @t{-r} option. If more arguments are +required by the format than have been specified, the behaviour is as if +zero or an empty string had been specified as the argument. + +@noindent +The @t{-v} option causes the output to be stored as the value of the +parameter @var{name}, instead of printed. If @var{name} is an array and +the format string is reused when consuming arguments then one +array element will be used for each use of the format string. + +@findex pushd +@pindex PUSHD_TO_HOME, use of +@pindex PUSHD_MINUS, use of +@pindex CDABLE_VARS, use of +@pindex PUSHD_SILENT, use of +@item @t{pushd} [ @t{-qsLP} ] [ @var{arg} ] +@itemx @t{pushd} [ @t{-qsLP} ] @var{old} @var{new} +@itemx @t{pushd} [ @t{-qsLP} ] @{@t{+}|@t{-}@}@var{n} +Change the current directory, and push the old current directory +onto the directory stack. In the first form, change the +current directory to @var{arg}. +If @var{arg} is not specified, change to the second directory +on the stack (that is, exchange the top two entries), or +change to @t{$HOME} if the @t{PUSHD_TO_HOME} +option is set or if there is only one entry on the stack. +Otherwise, @var{arg} is interpreted as it would be by @t{cd}. +The meaning of @var{old} and @var{new} in the second form is also +the same as for @t{cd}. + +@noindent +The third form of @t{pushd} changes directory by rotating the +directory list. An argument of the form `@t{+}@var{n}' identifies a stack +entry by counting from the left of the list shown by the @t{dirs} +command, starting with zero. An argument of the form `@t{-}@var{n}' counts +from the right. If the @t{PUSHD_MINUS} option is set, the meanings +of `@t{+}' and `@t{-}' in this context are swapped. + +@noindent +If the @t{-q} (quiet) option is specified, the hook function @t{chpwd} +and the functions in the array @t{$chpwd_functions} are not called, +and the new directory stack is not printed. This is useful for calls to +@t{pushd} that do not change the environment seen by an interactive user. + +@noindent +If the option @t{-q} is not specified and the shell option @t{PUSHD_SILENT} +is not set, the directory stack will be printed after a @t{pushd} is +performed. + +@noindent +The options @t{-s}, @t{-L} and @t{-P} have the same meanings as for the +@t{cd} builtin. + +@findex pushln +@item @t{pushln} [ @var{arg} ... ] +Equivalent to @t{print -nz}. + +@findex pwd +@pindex CHASE_LINKS, use of +@item @t{pwd} [ @t{-rLP} ] +Print the absolute pathname of the current working directory. +If the @t{-r} or the @t{-P} flag is specified, or the @t{CHASE_LINKS} +option is set and the @t{-L} flag is not given, the printed path will not +contain symbolic links. + +@findex r +@item @t{r} +Same as @t{fc -e -}. + +@findex read +@vindex IFS, use of + +@item @t{read }[ @t{-rszpqAclneE} ] [ @t{-t} [ @var{num} ] ] [ @t{-k} [ @var{num} ] ] [ @t{-d} @var{delim} ] +@itemx @t{@ @ @ @ @ }[ @t{-u} @var{n} ] [ @var{name}[@t{?}@var{prompt}] ] [ @var{name} ... ] +@vindex REPLY, use of +@vindex reply, use of +Read one line and break it into fields using the characters +in @t{$IFS} as separators, except as noted below. +The first field is assigned to the first @var{name}, the second field +to the second @var{name}, etc., with leftover +fields assigned to the last @var{name}. +If @var{name} is omitted then +@t{REPLY} is used for scalars and @t{reply} for arrays. + +@noindent +@table @asis +@item @t{-r} +Raw mode: a `@t{\}' at the end of a line does not signify line +continuation and backslashes in the line don't quote the following +character and are not removed. + +@item @t{-s} +Don't echo back characters if reading from the terminal. + +@item @t{-q} +Read only one character from the terminal and set @var{name} to +`@t{y}' if this character was `@t{y}' or `@t{Y}' and to `@t{n}' otherwise. +With this flag set the return status is zero only if the character was +`@t{y}' or `@t{Y}'. This option may be used with a timeout (see @t{-t}); if +the read times out, or encounters end of file, status 2 is returned. Input is +read from the terminal unless one of @t{-u} or @t{-p} is present. This option +may also be used within zle widgets. + +@item @t{-k} [ @var{num} ] +Read only one (or @var{num}) characters. All are assigned to the first +@var{name}, without word splitting. This flag is ignored when @t{-q} is +present. Input is read from the terminal unless one of @t{-u} or @t{-p} +is present. This option may also be used within zle widgets. + +@noindent +Note that despite the mnemonic `key' this option does read full +characters, which may consist of multiple bytes if the option +@t{MULTIBYTE} is set. + +@item @t{-z} +Read one entry from the editor buffer stack and assign it to the first +@var{name}, without word splitting. Text is pushed onto the stack with +`@t{print -z}' or with @t{push-line} from the line editor (see +@ref{Zsh Line Editor}). This flag is ignored when the @t{-k} or @t{-q} flags are present. + +@item @t{-e} +@itemx @t{-E} +The input read is printed (echoed) to the standard output. If the @t{-e} +flag is used, no input is assigned to the parameters. + +@item @t{-A} +The first @var{name} is taken as the name of an array and all words are +assigned to it. + +@item @t{-c} +@itemx @t{-l} +These flags are allowed only if called inside a +function used for completion (specified with the @t{-K} flag to +@t{compctl}). If the @t{-c} flag is given, the words of the +current command are read. If the @t{-l} flag is given, the whole +line is assigned as a scalar. If both flags are present, @t{-l} +is used and @t{-c} is ignored. + +@item @t{-n} +Together with @t{-c}, the number of the word the cursor is on is +read. With @t{-l}, the index of the character the cursor is on is +read. Note that the command name is word number 1, not word 0, +and that when the cursor is at the end of the line, its character +index is the length of the line plus one. + +@item @t{-u} @var{n} +Input is read from file descriptor @var{n}. + +@item @t{-p} +Input is read from the coprocess. + +@item @t{-d} @var{delim} +Input is terminated by the first character of @var{delim} instead of +by newline. + +@item @t{-t} [ @var{num} ] +Test if input is available before attempting to read. If @var{num} +is present, it must begin with a digit and will be evaluated +to give a number of seconds, which may be a floating point number; +in this case the read times out if input is not available within this +time. If @var{num} is not present, it is taken to be zero, so that +@t{read} returns immediately if no input is available. +If no input is available, return status 1 and do not set any variables. + +This option is not available when reading from the editor buffer with +@t{-z}, when called from within completion with @t{-c} or @t{-l}, with +@t{-q} which clears the input queue before reading, or within zle where +other mechanisms should be used to test for input. + +Note that read does not attempt to alter the input processing mode. The +default mode is canonical input, in which an entire line is read at a time, +so usually `@t{read -t}' will not read anything until an entire line has +been typed. However, when reading from the terminal with @t{-k} +input is processed one key at a time; in this case, only availability of +the first character is tested, so that e.g. `@t{read -t -k 2}' can still +block on the second character. Use two instances of `@t{read -t -k}' if +this is not what is wanted. + +@end table + +@noindent +If the first argument contains a `@t{?}', the remainder of this +word is used as a @var{prompt} on standard error when the shell +is interactive. + +@noindent +The value (exit status) of @t{read} is 1 when an end-of-file is +encountered, or when @t{-c} or @t{-l} is present and the command is +not called from a @t{compctl} function, or as described for @t{-q}. +Otherwise the value is 0. + +@noindent +The behavior of some combinations of the @t{-k}, @t{-p}, @t{-q}, @t{-u} +and @t{-z} flags is undefined. Presently @t{-q} cancels all the others, +@t{-p} cancels @t{-u}, @t{-k} cancels @t{-z}, and otherwise @t{-z} +cancels both @t{-p} and @t{-u}. + +@noindent +The @t{-c} or @t{-l} flags cancel any and all of @t{-kpquz}. + +@cindex parameters, marking readonly +@item @t{readonly} +Same as @t{typeset -r}. With the @t{POSIX_BUILTINS} option set, same +as @t{typeset -gr}. + +@findex rehash +@item @t{rehash} +Same as @t{hash -r}. + +@findex return +@cindex functions, returning from +@item @t{return} [ @var{n} ] +Causes a shell function or `@t{.}' script to return to +the invoking script with the return status specified by +an arithmetic expression @var{n}. If @var{n} +is omitted, the return status is that of the last command +executed. + +@noindent +If @t{return} was executed from a trap in a @t{TRAP}@var{NAL} function, +the effect is different for zero and non-zero return status. With zero +status (or after an implicit return at the end of the trap), the shell +will return to whatever it was previously processing; with a non-zero +status, the shell will behave as interrupted except that the return +status of the trap is retained. Note that the numeric value of the signal +which caused the trap is passed as the first argument, so the statement +`@t{return $((128+$1))}' will return the same status as if the signal +had not been trapped. + +@item @t{sched} +See @ref{The zsh/sched Module}. + +@findex set +@cindex parameters, listing +@cindex parameters, positional +@cindex parameters, setting array +@cindex array parameters, setting +@pindex KSH_ARRAYS, use of + +@item @t{set }[ @{@t{+}|@t{-}@}@var{options} | @{@t{+}|@t{-}@}@t{o} [ @var{option_name} ] ] ... [ @{@t{+}|@t{-}@}@t{A} [ @var{name} ] ] +@itemx @t{@ @ @ @ }[ @var{arg} ... ] +Set the options for the shell and/or set the positional parameters, or +declare and set an array. If the @t{-s} option is given, it causes the +specified arguments to be sorted before assigning them to the positional +parameters (or to the array @var{name} if @t{-A} is used). With @t{+s} +sort arguments in descending order. For the meaning of the other flags, see +@ref{Options}. Flags may be specified by name using the @t{-o} option. If no option +name is supplied with @t{-o}, the current option states are printed: see +the description of @t{setopt} below for more information on the format. +With @t{+o} they are printed in a form that can be used as input +to the shell. + +@noindent +If the @t{-A} flag is specified, @var{name} is set to an array containing +the given @var{arg}s; if no @var{name} is specified, all arrays are printed +together with their values. + +@noindent +If @t{+A} is used and @var{name} is an array, the +given arguments will replace the initial elements of that array; if no +@var{name} is specified, all arrays are printed without their values. + +@noindent +The behaviour of arguments after @t{-A} @var{name} or @t{+A} @var{name} +depends on whether the option @t{KSH_ARRAYS} is set. If it is not set, all +arguments following @var{name} are treated as values for the array, +regardless of their form. If the option is set, normal option processing +continues at that point; only regular arguments are treated as values for +the array. This means that + +@noindent +@example +set -A array -x -- foo +@end example + +@noindent +sets @t{array} to `@t{-x -}@t{- foo}' if @t{KSH_ARRAYS} is not set, but sets +the array to @t{foo} and turns on the option `@t{-x}' if it is set. + +@noindent +If the @t{-A} flag is not present, but there are arguments beyond the +options, the positional parameters are set. If the option list (if any) +is terminated by `@t{-}@t{-}', and there are no further arguments, the +positional parameters will be unset. + +@noindent +If no arguments and no `@t{-}@t{-}' are given, then the names and values of +all parameters are printed on the standard output. If the only argument is +`@t{+}', the names of all parameters are printed. + +@noindent +For historical reasons, `@t{set -}' is treated as `@t{set +xv}' +and `@t{set -} @var{args}' as `@t{set +xv --} @var{args}' when in +any other emulation mode than zsh's native mode. + +@item @t{setcap} +See @ref{The zsh/cap Module}. + +@findex setopt +@cindex options, setting +@item @t{setopt} [ @{@t{+}|@t{-}@}@var{options} | @{@t{+}|@t{-}@}@t{o} @var{option_name} ] [ @t{-m} ] [ @var{name} ... ] +Set the options for the shell. All options specified either +with flags or by name are set. + +@noindent +If no arguments are supplied, the names of all options currently set are +printed. The form is chosen so as to minimize the differences from the +default options for the current emulation (the default emulation being +native @t{zsh}, shown as @t{<Z>} in +@ref{Description of Options}). +Options that are on by default for the emulation are +shown with the prefix @t{no} only if they are off, while other options are +shown without the prefix @t{no} and only if they are on. In addition to +options changed from the default state by the user, any options activated +automatically by the shell (for example, @t{SHIN_STDIN} or @t{INTERACTIVE}) +will be shown in the list. The format is further modified by the option +@t{KSH_OPTION_PRINT}, however the rationale for choosing options with +or without the @t{no} prefix remains the same in this case. + +@noindent +If the @t{-m} flag is given the arguments are taken as patterns +(which should be quoted to protect them from filename expansion), and all +options with names matching these patterns are set. + +@noindent +Note that a bad option name does not cause execution of subsequent shell +code to be aborted; this is behaviour is different from that of `@t{set +-o}'. This is because @t{set} is regarded as a special builtin by the +POSIX standard, but @t{setopt} is not. + +@findex shift +@cindex parameters, positional +@item @t{shift} [ @t{-p} ] [ @var{n} ] [ @var{name} ... ] +The positional parameters @t{$@{}@var{n}+1@t{@}} ... are renamed +to @t{$1} ..., where @var{n} is an arithmetic expression that +defaults to 1. +If any @var{name}s are given then the arrays with these names are +shifted instead of the positional parameters. + +@noindent +If the option @t{-p} is given arguments are instead removed (popped) +from the end rather than the start of the array. + +@findex source +@item @t{source} @var{file} [ @var{arg} ... ] +Same as `@t{.}', except that the current directory is always searched and +is always searched first, before directories in @t{$path}. + +@item @t{stat} +See @ref{The zsh/stat Module}. + +@findex suspend +@cindex shell, suspending +@cindex suspending the shell +@item @t{suspend} [ @t{-f} ] +Suspend the execution of the shell (send it a @t{SIGTSTP}) +until it receives a @t{SIGCONT}. +Unless the @t{-f} option is given, this will refuse to suspend a login shell. + +@findex test +@item @t{test} [ @var{arg} ... ] +@itemx @t{[} [ @var{arg} ... ] @t{]} +Like the system version of @t{test}. Added for compatibility; +use conditional expressions instead (see @ref{Conditional Expressions}). +The main differences between the conditional expression syntax and the +@t{test} and @t{[} builtins are: these commands are not handled +syntactically, so for example an empty variable expansion may cause an +argument to be omitted; syntax errors cause status 2 to be returned instead +of a shell error; and arithmetic operators expect integer arguments rather +than arithmetic expressions. + +@noindent +The command attempts to implement POSIX and its extensions where these +are specified. Unfortunately there are intrinsic ambiguities in +the syntax; in particular there is no distinction between test operators +and strings that resemble them. The standard attempts to resolve these +for small numbers of arguments (up to four); for five or more arguments +compatibility cannot be relied on. Users are urged wherever possible to +use the `@t{[[}' test syntax which does not have these ambiguities. + +@findex times +@cindex shell, timing +@cindex timing the shell +@item @t{times} +Print the accumulated user and system times for the shell +and for processes run from the shell. + +@findex trap +@cindex signals, trapping +@cindex trapping signals +@item @t{trap} [ @var{arg} ] [ @var{sig} ... ] +@var{arg} is a series of commands (usually quoted to protect it from +immediate evaluation by the shell) to be read and executed when the shell +receives any of the signals specified by one or more @var{sig} args. +Each @var{sig} can be given as a number, +or as the name of a signal either with or without the string @t{SIG} +in front (e.g. 1, HUP, and SIGHUP are all the same signal). + +@noindent +If @var{arg} is `@t{-}', then the specified signals are reset to their +defaults, or, if no @var{sig} args are present, all traps are reset. + +@noindent +If @var{arg} is an empty string, then the specified signals +are ignored by the shell (and by the commands it invokes). + +@noindent +If @var{arg} is omitted but one or more @var{sig} args are provided (i.e. +the first argument is a valid signal number or name), the effect is the +same as if @var{arg} had been specified as `@t{-}'. + +@noindent +The @t{trap} command with no arguments prints a list of commands +associated with each signal. + +@noindent +If @var{sig} is @t{ZERR} then @var{arg} will be executed +after each command with a nonzero exit status. @t{ERR} is an alias +for @t{ZERR} on systems that have no @t{SIGERR} signal (this is the +usual case). + +@noindent +If @var{sig} is @t{DEBUG} then @var{arg} will be executed +before each command if the option @t{DEBUG_BEFORE_CMD} is set +(as it is by default), else after each command. Here, a `command' is +what is described as a `sublist' in the shell grammar, see +@ref{Simple Commands & Pipelines}. +If @t{DEBUG_BEFORE_CMD} is set various additional features are available. +First, it is possible to skip the next command by setting the option +@t{ERR_EXIT}; see the description of the @t{ERR_EXIT} option in +@ref{Description of Options}. Also, the shell parameter +@t{ZSH_DEBUG_CMD} is set to the string corresponding to the command +to be executed following the trap. Note that this string is reconstructed +from the internal format and may not be formatted the same way as the +original text. The parameter is unset after the trap is executed. + +@noindent +If @var{sig} is @t{0} or @t{EXIT} +and the @t{trap} statement is executed inside the body of a function, +then the command @var{arg} is executed after the function completes. +The value of @t{$?} at the start of execution is the exit status of the +shell or the return status of the function exiting. +If @var{sig} is @t{0} or @t{EXIT} +and the @t{trap} statement is not executed inside the body of a function, +then the command @var{arg} is executed when the shell terminates; the +trap runs before any @t{zshexit} hook functions. + +@noindent +@t{ZERR}, @t{DEBUG}, and @t{EXIT} traps are not executed inside other +traps. @t{ZERR} and @t{DEBUG} traps are kept within subshells, while +other traps are reset. + +@noindent +Note that traps defined with the @t{trap} builtin are slightly different +from those defined as `@t{TRAP}@var{NAL} () @{ ... @}', as the latter have +their own function environment (line numbers, local variables, etc.) while +the former use the environment of the command in which they were called. +For example, + +@noindent +@example +trap 'print $LINENO' DEBUG +@end example + +@noindent +will print the line number of a command executed after it has run, while + +@noindent +@example +TRAPDEBUG() @{ print $LINENO; @} +@end example + +@noindent +will always print the number zero. + +@noindent +Alternative signal names are allowed as described under @t{kill} above. +Defining a trap under either name causes any trap under an alternative +name to be removed. However, it is recommended that for consistency +users stick exclusively to one name or another. + +@findex true +@cindex doing nothing, successfully +@item @t{true} [ @var{arg} ... ] +Do nothing and return an exit status of 0. + +@findex ttyctl +@cindex tty, freezing +@item @t{ttyctl} [ @t{-fu} ] +The @t{-f} option freezes the tty (i.e. terminal or terminal emulator), and +@t{-u} unfreezes it. +When the tty is frozen, no changes made to the tty settings by +external programs will be honored by the shell, except for changes in the +size of the screen; the shell will +simply reset the settings to their previous values as soon as each +command exits or is suspended. Thus, @t{stty} and similar programs have +no effect when the tty is frozen. Freezing the tty does not cause +the current state to be remembered: instead, it causes future changes +to the state to be blocked. + +@noindent +Without options it reports whether the terminal is frozen or not. + +@noindent +Note that, regardless of whether the tty is frozen or not, the +shell needs to change the settings when the line editor starts, so +unfreezing the tty does not guarantee settings made on the +command line are preserved. Strings of commands run between +editing the command line will see a consistent tty state. +See also the shell variable @t{STTY} for a means of initialising +the tty before running external commands. + +@findex type +@item @t{type} [ @t{-wfpamsS} ] @var{name} ... +Equivalent to @t{whence -v}. + +@findex typeset +@cindex parameters, setting +@cindex parameters, declaring + +@item @t{typeset }[ @{@t{+}|@t{-}@}@t{AHUaghlmrtux} ] [ @{@t{+}|@t{-}@}@t{EFLRZip} [ @var{n} ] ] +@itemx @t{@ @ @ @ @ @ @ @ }[ @t{+} ] [ @var{name}[@t{=}@var{value}] ... ] +@itemx @t{typeset }@t{-T} [ @{@t{+}|@t{-}@}@t{Uglrux} ] [ @{@t{+}|@t{-}@}@t{LRZp} [ @var{n} ] ] +@itemx @t{@ @ @ @ @ @ @ @ }[ @t{+} | @var{SCALAR}[@t{=}@var{value}] @var{array}[@t{=(}@var{value} ...@t{)}] [ @var{sep} ] ] +@itemx @t{typeset} @t{-f} [ @{@t{+}|@t{-}@}@t{TUkmtuz} ] [ @t{+} ] [ @var{name} ... ] +Set or display attributes and values for shell parameters. + +@noindent +Except as noted below for control flags that change the behavior, +a parameter is created for each @var{name} that does not already refer +to one. When inside a function, a new parameter is created for every +@var{name} (even those that already exist), and is unset again when the +function completes. See +@ref{Local Parameters}. The same rules apply to special shell parameters, which +retain their special attributes when made local. + +@noindent +For each @var{name}@t{=}@var{value} assignment, the parameter +@var{name} is set to @var{value}. + +@noindent +If the shell option @t{TYPESET_SILENT} is not set, for each remaining +@var{name} that refers to a parameter that is already set, the name and +value of the parameter are printed in the form of an assignment. +Nothing is printed for newly-created parameters, or when any attribute +flags listed below are given along with the @var{name}. Using +`@t{+}' instead of minus to introduce an attribute turns it off. + +@noindent +If no @var{name} is present, the names and values of all parameters are +printed. In this case the attribute flags restrict the display to only +those parameters that have the specified attributes, and using `@t{+}' +rather than `@t{-}' to introduce the flag suppresses printing of the values +of parameters when there is no parameter name. + +@noindent +All forms of the command handle scalar assignment. Array assignment is +possible if any of the reserved words @t{declare}, @t{export}, @t{float}, +@t{integer}, @t{local}, @t{readonly} or @t{typeset} is matched when the +line is parsed (N.B. not when it is executed). In this case the arguments +are parsed as assignments, except that the `@t{+=}' syntax and the +@t{GLOB_ASSIGN} option are not supported, and scalar values after @t{=} +are @emph{not} split further into words, even if expanded (regardless of the +setting of the @t{KSH_TYPESET} option; this option is obsolete). + +@noindent +Examples of the differences between command and reserved word parsing: + +@noindent +@example +# Reserved word parsing +typeset svar=$(echo one word) avar=(several words) +@end example + +@noindent +The above creates a scalar parameter @t{svar} and an array +parameter @t{avar} as if the assignments had been + +@noindent +@example +svar="one word" +avar=(several words) +@end example + +@noindent +On the other hand: + +@noindent +@example +# Normal builtin interface +builtin typeset svar=$(echo two words) +@end example + +@noindent +The @t{builtin} keyword causes the above to use the standard builtin +interface to @t{typeset} in which argument parsing is performed in the same +way as for other commands. This example creates a scalar @t{svar} +containing the value @t{two} and another scalar parameter @t{words} with +no value. An array value in this case would either cause an error or be +treated as an obscure set of glob qualifiers. + +@noindent +Arbitrary arguments are allowed if they take the form of assignments +after command line expansion; however, these only perform scalar +assignment: + +@noindent +@example +var='svar=val' +typeset $var +@end example + +@noindent +The above sets the scalar parameter @t{svar} to the value @t{val}. +Parentheses around the value within @t{var} would not cause array +assignment as they will be treated as ordinary characters when @t{$var} +is substituted. Any non-trivial expansion in the name part of the +assignment causes the argument to be treated in this fashion: + +@noindent +@example +typeset @{var1,var2,var3@}=name +@end example + +@noindent +The above syntax is valid, and has the expected effect of setting the +three parameters to the same value, but the command line is parsed as +a set of three normal command line arguments to @t{typeset} after +expansion. Hence it is not possible to assign to multiple arrays by +this means. + +@noindent +Note that each interface to any of the commands my be disabled +separately. For example, `@t{disable -r typeset}' disables the reserved +word interface to @t{typeset}, exposing the builtin interface, while +`@t{disable typeset}' disables the builtin. Note that disabling the +reserved word interface for @t{typeset} may cause problems with the +output of `@t{typeset -p}', which assumes the reserved word interface is +available in order to restore array and associative array values. + +@noindent +Unlike parameter assignment statements, @t{typeset}'s exit status on an +assignment that involves a command substitution does not reflect the exit +status of the command substitution. Therefore, to test for an error in +a command substitution, separate the declaration of the parameter from its +initialization: + +@noindent +@example +# WRONG +typeset var1=$(exit 1) || echo "Trouble with var1" + +# RIGHT +typeset var1 && var1=$(exit 1) || echo "Trouble with var1" + +@end example + +@noindent +To initialize a parameter @var{param} to a command output and mark it readonly, +use @t{typeset -r }@var{param} or @t{readonly }@var{param} after the parameter +assignment statement. + +@noindent +If no attribute flags are given, and either no @var{name} arguments are +present or the flag @t{+m} is used, then each parameter name printed is +preceded by a list of the attributes of that parameter (@t{array}, +@t{association}, @t{exported}, @t{float}, @t{integer}, @t{readonly}, +or @t{undefined} for autoloaded parameters not yet loaded). If @t{+m} is +used with attribute flags, and all those flags are introduced with +@t{+}, the matching parameter names are printed but their values +are not. + +@noindent +The following control flags change the behavior of @t{typeset}: + +@noindent +@table @asis +@item @t{+} +If `@t{+}' appears by itself in a separate word as the last option, +then the names of all parameters (functions with @t{-f}) are printed, but +the values (function bodies) are not. No @var{name} arguments may appear, +and it is an error for any other options to follow `@t{+}'. The +effect of `@t{+}' is as if all attribute flags which precede it were +given with a `@t{+}' prefix. For example, `@t{typeset -U +}' is +equivalent to `@t{typeset +U}' and displays the names of all arrays having +the uniqueness attribute, whereas `@t{typeset -f -U +}' displays the +names of all autoloadable functions. If @t{+} is the only option, +then type information (array, readonly, etc.) is also printed for each +parameter, in the same manner as `@t{typeset +m "*"}'. + +@item @t{-g} +The @t{-g} (global) means that any resulting parameter will not be +restricted to local scope. Note that this does not necessarily mean that +the parameter will be global, as the flag will apply to any existing +parameter (even if unset) from an enclosing function. This flag does not +affect the parameter after creation, hence it has no effect when listing +existing parameters, nor does the flag @t{+g} have any effect except in +combination with @t{-m} (see below). + +@item @t{-m} +If the @t{-m} flag is given the @var{name} arguments are taken as patterns +(use quoting to prevent these from being interpreted as file patterns). +With no attribute flags, all parameters (or functions with the @t{-f} +flag) with matching names are printed (the shell option @t{TYPESET_SILENT} +is not used in this case). + +@noindent +If the @t{+g} flag is combined with @t{-m}, a new local parameter is +created for every matching parameter that is not already local. Otherwise +@t{-m} applies all other flags or assignments to the existing parameters. + +@noindent +Except when assignments are made with @var{name}@t{=}@var{value}, using +@t{+m} forces the matching parameters and their attributes to be printed, +even inside a function. Note that @t{-m} is ignored if no patterns are +given, so `@t{typeset -m}' displays attributes but `@t{typeset -a +m}' +does not. + +@item @t{-p} [ @var{n} ] +If the @t{-p} option is given, parameters and values are printed in the +form of a typeset command with an assignment, regardless of other flags +and options. Note that the @t{-H} flag on parameters is respected; no +value will be shown for these parameters. + +@noindent +@t{-p} may be followed by an optional integer argument. Currently +only the value @t{1} is supported. In this case arrays and associative +arrays are printed with newlines between indented elements for +readability. + +@item @t{-T} [ @var{scalar}[@t{=}@var{value}] @var{array}[@t{=(}@var{value} ...@t{)}] [ @var{sep} ] ] +This flag has a different meaning when used with @t{-f}; see below. +Otherwise the @t{-T} option requires zero, two, or three arguments to be +present. With no arguments, the list of parameters created in this +fashion is shown. With two or three arguments, the first two are the name +of a scalar and of an array parameter (in that order) that will be tied +together in the manner of @t{$PATH} and @t{$path}. The optional third +argument is a single-character separator which will be used to join the +elements of the array to form the scalar; if absent, a colon is used, as +with @t{$PATH}. Only the first character of the separator is significant; +any remaining characters are ignored. Multibyte characters are not +yet supported. + +@noindent +Only one of the scalar and array parameters may be assigned an initial +value (the restrictions on assignment forms described above also apply). + +@noindent +Both the scalar and the array may be manipulated as normal. If one is +unset, the other will automatically be unset too. There is no way of +untying the variables without unsetting them, nor of converting the type +of one of them with another @t{typeset} command; @t{+T} does not work, +assigning an array to @var{scalar} is an error, and assigning a scalar to +@var{array} sets it to be a single-element array. + +@noindent +Note that both `@t{typeset -xT ...}' and `@t{export -T ...}' work, but +only the scalar will be marked for export. Setting the value using the +scalar version causes a split on all separators (which cannot be quoted). +It is possible to apply @t{-T} to two previously tied variables but with a +different separator character, in which case the variables remain joined +as before but the separator is changed. + +@noindent +When an existing scalar is tied to a new array, the value of the scalar +is preserved but no attribute other than export will be preserved. + +@end table + +@noindent +Attribute flags that transform the final value (@t{-L}, @t{-R}, @t{-Z}, +@t{-l}, @t{-u}) are only applied to the expanded value at the point +of a parameter expansion expression using `@t{$}'. They are not applied +when a parameter is retrieved internally by the shell for any purpose. + +@noindent +The following attribute flags may be specified: + +@noindent +@table @asis +@item @t{-A} +The names refer to associative array parameters; see +@ref{Array Parameters}. + +@item @t{-L} [ @var{n} ] +Left justify and remove leading blanks from the value when the parameter +is expanded. +If @var{n} is nonzero, it defines the width of the field. +If @var{n} is zero, the width is determined by the width of the value of +the first assignment. In the case of numeric parameters, the length of the +complete value assigned to the parameter is used to determine the width, +not the value that would be output. + +@noindent +The width is the count of characters, which may be multibyte characters +if the @t{MULTIBYTE} option is in effect. Note that the screen +width of the character is not taken into account; if this is required, +use padding with parameter expansion flags +@t{$@{(ml}@var{...}@t{)}@var{...}@t{@}} as described in +`Parameter Expansion Flags' in +@ref{Parameter Expansion}. + +@noindent +When the parameter is expanded, it is filled on the right with +blanks or truncated if necessary to fit the field. +Note truncation can lead to unexpected results with numeric parameters. +Leading zeros are removed if the @t{-Z} flag is also set. + +@item @t{-R} [ @var{n} ] +Similar to @t{-L}, except that right justification is used; +when the parameter is expanded, the field is left filled with +blanks or truncated from the end. May not be combined with the @t{-Z} +flag. + +@item @t{-U} +For arrays (but not for associative arrays), keep only the first +occurrence of each duplicated value. This may also be set for tied +parameters (see @t{-T}) or colon-separated special parameters like +@t{PATH} or @t{FIGNORE}, etc. Note the flag takes effect on assignment, +and the type of the variable being assigned to is determinative; for +variables with shared values it is therefore recommended to set the flag +for all interfaces, e.g. `@t{typeset -U PATH path}'. + +@noindent +This flag has a different meaning when used with @t{-f}; see below. + +@item @t{-Z} [ @var{n} ] +Specially handled if set along with the @t{-L} flag. +Otherwise, similar to @t{-R}, except that leading zeros are used for +padding instead of blanks if the first non-blank character is a digit. +Numeric parameters are specially handled: they are always eligible +for padding with zeroes, and the zeroes are inserted at an appropriate +place in the output. + +@item @t{-a} +The names refer to array parameters. An array parameter may be +created this way, but it may be assigned to in the @t{typeset} +statement only if the reserved word form of @t{typeset} is enabled +(as it is by default). When displaying, both normal and associative +arrays are shown. + +@item @t{-f} +The names refer to functions rather than parameters. No assignments +can be made, and the only other valid flags are @t{-t}, @t{-T}, @t{-k}, +@t{-u}, @t{-U} and @t{-z}. The flag @t{-t} turns on execution tracing +for this function; the flag @t{-T} does the same, but turns off tracing +for any named (not anonymous) function called from the present one, +unless that function also +has the @t{-t} or @t{-T} flag. The @t{-u} and @t{-U} flags cause the +function to be marked for autoloading; @t{-U} also causes alias +expansion to be suppressed when the function is loaded. See the +description of the `@t{autoload}' builtin for details. + +@noindent +Note that the builtin @t{functions} provides the same basic capabilities +as @t{typeset -f} but gives access to a few extra options; @t{autoload} +gives further additional options for the case @t{typeset -fu} and +@t{typeset -fU}. + +@item @t{-h} +Hide: only useful for special parameters (those marked `<S>' in the table in +@ref{Parameters Set By The Shell}), and for local parameters with the same name as a special parameter, +though harmless for others. A special parameter with this attribute will +not retain its special effect when made local. Thus after `@t{typeset -h +PATH}', a function containing `@t{typeset PATH}' will create an ordinary +local parameter without the usual behaviour of @t{PATH}. Alternatively, +the local parameter may itself be given this attribute; hence inside a +function `@t{typeset -h PATH}' creates an ordinary local parameter and the +special @t{PATH} parameter is not altered in any way. It is also possible +to create a local parameter using `@t{typeset +h }@var{special}', where the +local copy of @var{special} will retain its special properties regardless of +having the @t{-h} attribute. Global special parameters loaded from shell +modules (currently those in @t{zsh/mapfile} and @t{zsh/parameter}) are +automatically given the @t{-h} attribute to avoid name clashes. + +@item @t{-H} +Hide value: specifies that @t{typeset} will not display the value of the +parameter when listing parameters; the display for such parameters is +always as if the `@t{+}' flag had been given. Use of the parameter is +in other respects normal, and the option does not apply if the parameter is +specified by name, or by pattern with the @t{-m} option. This is on by +default for the parameters in the @t{zsh/parameter} and @t{zsh/mapfile} +modules. Note, however, that unlike the @t{-h} flag this is also useful +for non-special parameters. + +@item @t{-i} [ @var{n} ] +Use an internal integer representation. If @var{n} is nonzero it +defines the output arithmetic base, otherwise it is determined by the +first assignment. Bases from 2 to 36 inclusive are allowed. + +@item @t{-E} [ @var{n} ] +Use an internal double-precision floating point representation. On output +the variable will be converted to scientific notation. If @var{n} is +nonzero it defines the number of significant figures to display; the +default is ten. + +@item @t{-F} [ @var{n} ] +Use an internal double-precision floating point representation. On output +the variable will be converted to fixed-point decimal notation. If @var{n} +is nonzero it defines the number of digits to display after the decimal +point; the default is ten. + +@item @t{-l} +Convert the result to lower case whenever the parameter is expanded. +The value is @emph{not} converted when assigned. + +@item @t{-r} +The given @var{name}s are marked readonly. Note that if @var{name} is a +special parameter, the readonly attribute can be turned on, but cannot then +be turned off. + +@noindent +If the @t{POSIX_BUILTINS} option is set, the readonly attribute is +more restrictive: unset variables can be marked readonly and cannot then +be set; furthermore, the readonly attribute cannot be removed from any +variable. + +@noindent +It is still possible to change other attributes of the variable though, +some of which like @t{-U} or @t{-Z} would affect the value. More generally, +the readonly attribute should not be relied on as a security mechanism. + +@noindent +Note that in zsh (like in pdksh but unlike most other shells) it is +still possible to create a local variable of the same name as this is +considered a different variable (though this variable, too, can be marked +readonly). Special variables that have been made readonly retain their value +and readonly attribute when made local. + +@item @t{-t} +Tags the named parameters. Tags have no special meaning to the shell. +This flag has a different meaning when used with @t{-f}; see above. + +@item @t{-u} +Convert the result to upper case whenever the parameter is expanded. +The value is @emph{not} converted when assigned. +This flag has a different meaning when used with @t{-f}; see above. + +@item @t{-x} +Mark for automatic export to the environment of subsequently +executed commands. If the option @t{GLOBAL_EXPORT} is set, this implies +the option @t{-g}, unless @t{+g} is also explicitly given; in other words +the parameter is not made local to the enclosing function. This is for +compatibility with previous versions of zsh. + +@end table + +@findex ulimit +@cindex resource limits +@cindex limits, resource +@item @t{ulimit} [ @t{-HSa} ] [ @{ @t{-bcdfiklmnpqrsTtvwx} | @t{-N} @var{resource} @} [ @var{limit} ] ... ] +Set or display resource limits of the shell and the processes started by +the shell. The value of @var{limit} can be a number in the unit specified +below or one of the values `@t{unlimited}', which removes the limit on the +resource, or `@t{hard}', which uses the current value of the hard limit on +the resource. + +@noindent +By default, only soft limits are manipulated. If the @t{-H} flag +is given use hard limits instead of soft limits. If the @t{-S} flag is given +together with the @t{-H} flag set both hard and soft limits. + +@noindent +If no options are used, the file size limit (@t{-f}) is assumed. + +@noindent +If @var{limit} is omitted the current value of the specified resources are +printed. When more than one resource value is printed, the limit name and +unit is printed before each value. + +@noindent +When looping over multiple resources, the shell will abort immediately if +it detects a badly formed argument. However, if it fails to set a limit +for some other reason it will continue trying to set the remaining limits. + +@noindent +Not all the following resources are supported on all systems. Running +@t{ulimit -a} will show which are supported. + +@noindent +@table @asis +@item @t{-a} +Lists all of the current resource limits. +@item @t{-b} +Socket buffer size in bytes (N.B. not kilobytes) +@item @t{-c} +512-byte blocks on the size of core dumps. +@item @t{-d} +Kilobytes on the size of the data segment. +@item @t{-f} +512-byte blocks on the size of files written. +@item @t{-i} +The number of pending signals. +@item @t{-k} +The number of kqueues allocated. +@item @t{-l} +Kilobytes on the size of locked-in memory. +@item @t{-m} +Kilobytes on the size of physical memory. +@item @t{-n} +open file descriptors. +@item @t{-p} +The number of pseudo-terminals. +@item @t{-q} +Bytes in POSIX message queues. +@item @t{-r} +Maximum real time priority. On some systems where this +is not available, such as NetBSD, this has the same effect as @t{-T} +for compatibility with @t{sh}. +@item @t{-s} +Kilobytes on the size of the stack. +@item @t{-T} +The number of simultaneous threads available to the user. +@item @t{-t} +CPU seconds to be used. +@item @t{-u} +The number of processes available to the user. +@item @t{-v} +Kilobytes on the size of virtual memory. On some systems this +refers to the limit called `address space'. +@item @t{-w} +Kilobytes on the size of swapped out memory. +@item @t{-x} +The number of locks on files. +@end table + +@noindent +A resource may also be specified by integer in the form `@t{-N} +@var{resource}', where @var{resource} corresponds to the integer defined for +the resource by the operating system. This may be used to set the limits +for resources known to the shell which do not correspond to option letters. +Such limits will be shown by number in the output of `@t{ulimit -a}'. + +@noindent +The number may alternatively be out of the range of limits compiled into +the shell. The shell will try to read or write the limit anyway, and +will report an error if this fails. + +@findex umask +@cindex umask +@item @t{umask} [ @t{-S} ] [ @var{mask} ] +The umask is set to @var{mask}. @var{mask} can be either +an octal number or a symbolic value as described in man page chmod(1). +If @var{mask} is omitted, the current value is printed. The @t{-S} +option causes the mask to be printed as a symbolic value. Otherwise, +the mask is printed as an octal number. Note that in +the symbolic form the permissions you specify are those which are to be +allowed (not denied) to the users specified. + +@cindex aliases, removing +@item @t{unalias} [ @t{-ams} ] @var{name} ... +Removes aliases. This command works the same as @t{unhash -a}, except that +the @t{-a} option removes all regular or global aliases, or with @t{-s} +all suffix aliases: in this case no @var{name} arguments may appear. The +options @t{-m} (remove by pattern) and @t{-s} without @t{-a} (remove +listed suffix aliases) behave as for @t{unhash -a}. Note that +the meaning of @t{-a} is different between @t{unalias} and @t{unhash}. + +@cindex functions, removing +@findex unfunction +@item @t{unfunction} +Same as @t{unhash -f}. + +@findex unhash +@item @t{unhash} [ @t{-adfms} ] @var{name} ... +Remove the element named @var{name} from an internal hash table. The +default is remove elements from the command hash table. The @t{-a} +option causes @t{unhash} to remove regular or global aliases; note +when removing a global aliases that the argument must be quoted to prevent +it from being expanded before being passed to the command. +The @t{-s} option causes @t{unhash} to remove suffix aliases. +The @t{-f} option causes +@t{unhash} to remove shell functions. The @t{-d} options causes +@t{unhash} to remove named directories. If the @t{-m} flag is given +the arguments are taken as patterns (should be quoted) and all elements +of the corresponding hash table with matching names will be removed. + +@findex unlimit +@cindex resource limits +@cindex limits, resource +@item @t{unlimit} [ @t{-hs} ] @var{resource} ... +The resource limit for each @var{resource} is set to the hard limit. +If the @t{-h} flag is given and the shell has appropriate privileges, +the hard resource limit for each @var{resource} is removed. +The resources of the shell process are only changed if the @t{-s} +flag is given. + +@noindent +The @t{unlimit} command is not made available by default when the +shell starts in a mode emulating another shell. It can be made available +with the command `@t{zmodload -F zsh/rlimits b:unlimit}'. + +@findex unset +@cindex parameters, unsetting +@item @t{unset} [ @t{-fmv} ] @var{name} ... +Each named parameter is unset. +Local parameters remain local even if unset; they appear unset within scope, +but the previous value will still reappear when the scope ends. + +@noindent +Individual elements of associative array parameters may be unset by using +subscript syntax on @var{name}, which should be quoted (or the entire command +prefixed with @t{noglob}) to protect the subscript from filename generation. + +@noindent +If the @t{-m} flag is specified the arguments are taken as patterns (should +be quoted) and all parameters with matching names are unset. Note that this +cannot be used when unsetting associative array elements, as the subscript +will be treated as part of the pattern. + +@noindent +The @t{-v} flag specifies that @var{name} refers to parameters. This is the +default behaviour. + +@noindent +@t{unset -f} is equivalent to @t{unfunction}. + +@findex unsetopt +@cindex options, unsetting +@item @t{unsetopt} [ @{@t{+}|@t{-}@}@var{options} | @{@t{+}|@t{-}@}@t{o} @var{option_name} ] [ @var{name} ... ] +Unset the options for the shell. All options specified either +with flags or by name are unset. If no arguments are supplied, +the names of all options currently unset are printed. +If the @t{-m} flag is given the arguments are taken as patterns +(which should be quoted to preserve them from being interpreted as glob +patterns), and all options with names matching these patterns are unset. + +@item @t{vared} +See @ref{Zle Builtins}. + +@findex wait +@cindex waiting for jobs +@cindex jobs, waiting for +@item @t{wait} [ @var{job} ... ] +Wait for the specified jobs or processes. If @var{job} is not given +then all currently active child processes are waited for. +Each @var{job} can be either a job specification or the process ID +of a job in the job table. +The exit status from this command is that of the job waited for. +If @var{job} represents an unknown job or process ID, a warning is printed +(unless the @t{POSIX_BUILTINS} option is set) and the exit status is 127. + +@noindent +It is possible to wait for recent processes (specified by process ID, +not by job) that were running in the background even if the process has +exited. Typically the process ID will be recorded by capturing the +value of the variable @t{$!} immediately after the process has been +started. There is a limit on the number of process IDs remembered by +the shell; this is given by the value of the system configuration +parameter @t{CHILD_MAX}. When this limit is reached, older process IDs +are discarded, least recently started processes first. + +@noindent +Note there is no protection against the process ID wrapping, i.e. if the +wait is not executed soon enough there is a chance the process waited +for is the wrong one. A conflict implies both process IDs have been +generated by the shell, as other processes are not recorded, and that +the user is potentially interested in both, so this problem is intrinsic +to process IDs. + +@findex whence +@item @t{whence} [ @t{-vcwfpamsS} ] [ @t{-x} @var{num} ] @var{name} ... +For each @var{name}, indicate how it would be interpreted if used as a +command name. + +@noindent +If @var{name} is not an alias, built-in command, external command, shell +function, hashed command, or a reserved word, the exit status shall be +non-zero, and --- if @t{-v}, @t{-c}, or @t{-w} was passed --- a message +will be written to standard output. (This is different from other shells that +write that message to standard error.) + +@noindent +@t{whence} is most useful when @var{name} is only the last path component +of a command, i.e. does not include a `@t{/}'; in particular, pattern +matching only succeeds if just the non-directory component of the command is +passed. + +@noindent +@table @asis +@item @t{-v} +Produce a more verbose report. + +@item @t{-c} +Print the results in a @cite{csh}-like format. +This takes precedence over @t{-v}. + +@item @t{-w} +For each @var{name}, print `@var{name}@t{:} @var{word}' where @var{word} +is one of @t{alias}, @t{builtin}, @t{command}, @t{function}, +@t{hashed}, @t{reserved} or @t{none}, according as @var{name} +corresponds to an alias, a built-in command, an external command, a +shell function, a command defined with the @t{hash} builtin, a +reserved word, or is not recognised. This takes precedence over +@t{-v} and @t{-c}. + +@item @t{-f} +Causes the contents of a shell function to be +displayed, which would otherwise not happen unless the @t{-c} +flag were used. + +@item @t{-p} +Do a path search for @var{name} +even if it is an alias, reserved word, shell function or builtin. + +@item @t{-a} +Do a search for all occurrences of @var{name} +throughout the command path. +Normally only the first occurrence is printed. + +@item @t{-m} +The arguments are taken as patterns (pattern characters should be +quoted), and the information is displayed for each command matching one +of these patterns. + +@item @t{-s} +If a pathname contains symlinks, print the symlink-free pathname as well. + +@item @t{-S} +As @t{-s}, but if the pathname had to be resolved by following +multiple symlinks, the intermediate steps are printed, too. The +symlink resolved at each step might be anywhere in the path. + +@item @t{-x} @var{num} +Expand tabs when outputting shell functions using the @t{-c} option. +This has the same effect as the @t{-x} option to the @t{functions} +builtin. + +@end table + +@findex where +@item @t{where} [ @t{-wpmsS} ] [ @t{-x} @var{num} ] @var{name} ... +Equivalent to @t{whence -ca}. + +@findex which +@item @t{which} [ @t{-wpamsS} ] [ @t{-x} @var{num} ] @var{name} ... +Equivalent to @t{whence -c}. + +@findex zcompile +@cindex .zwc files, creation +@cindex compilation +@item @t{zcompile} [ @t{-U} ] [ @t{-z} | @t{-k} ] [ @t{-R} | @t{-M} ] @var{file} [ @var{name} ... ] +@itemx @t{zcompile} @t{-ca} [ @t{-m} ] [ @t{-R} | @t{-M} ] @var{file} [ @var{name} ... ] +@itemx @t{zcompile -t} @var{file} [ @var{name} ... ] +This builtin command can be used to compile functions or scripts, +storing the compiled form in a file, and to examine files containing +the compiled form. This allows faster autoloading of functions and +sourcing of scripts by avoiding parsing of the text when the files +are read. + +@noindent +The first form (without the @t{-c}, @t{-a} or @t{-t} options) creates a +compiled file. If only the @var{file} argument is given, the +output file has the name `@var{file}@t{.zwc}' and will be placed in +the same directory as the @var{file}. The shell will load the compiled +file instead of the normal function file when the function +is autoloaded; see +@ref{Functions} +for a description of how autoloaded functions are searched. The +extension @t{.zwc} stands for `zsh word code'. + +@noindent +@vindex fpath, with zcompile +If there is at least one @var{name} argument, all the named files +are compiled into the output @var{file} given as the first argument. If +@var{file} does not end in @t{.zwc}, this extension is automatically +appended. Files containing multiple compiled functions are called `digest' +files, and are intended to be used as elements of the @t{FPATH}/@t{fpath} +special array. + +@noindent +The second form, with the @t{-c} or @t{-a} options, writes the compiled +definitions for all the named functions into @var{file}. For @t{-c}, the +names must be functions currently defined in the shell, not those marked +for autoloading. Undefined functions that are marked for autoloading +may be written by using the @t{-a} option, in which case the @t{fpath} +is searched and the contents of the definition files for those +functions, if found, are compiled into @var{file}. If both @t{-c} and +@t{-a} are given, names of both defined functions and functions marked +for autoloading may be given. In either case, the functions in files +written with the @t{-c} or @t{-a} option will be autoloaded as if the +@t{KSH_AUTOLOAD} option were unset. + +@noindent +The reason for handling loaded and not-yet-loaded functions with +different options is that some definition files for autoloading define +multiple functions, including the function with the same name as the +file, and, at the end, call that function. In such cases the output of +`@t{zcompile -c}' does not include the additional functions defined in +the file, and any other initialization code in the file is lost. Using +`@t{zcompile -a}' captures all this extra information. + +@noindent +If the @t{-m} option is combined with @t{-c} or @t{-a}, +the @var{name}s are used as patterns and all functions whose names +match one of these patterns will be written. If no @var{name} is given, +the definitions of all functions currently defined or marked as +autoloaded will be written. + +@noindent +Note the second form cannot be used for compiling functions that +include redirections as part of the definition rather than within +the body of the function; for example + +@noindent +@example +fn1() @{ @{ ... @} >~/logfile @} +@end example + +@noindent +can be compiled but + +@noindent +@example +fn1() @{ ... @} >~/logfile +@end example + +@noindent +cannot. It is possible to use the first form of @t{zcompile} to compile +autoloadable functions that include the full function definition instead +of just the body of the function. + +@noindent +The third form, with the @t{-t} option, examines an existing +compiled file. Without further arguments, the names of the original +files compiled into it are listed. The first line of output shows +the version of the shell which compiled the file and how the file +will be used (i.e. by reading it directly or by mapping it into memory). +With arguments, nothing is output and the return status is set to zero if +definitions for @emph{all} @var{name}s were found in the compiled +file, and non-zero if the definition for at least one @var{name} was not +found. + +@noindent +Other options: + +@noindent +@table @asis +@item @t{-U} +Aliases are not expanded when compiling the @var{name}d files. + +@item @t{-R} +When the compiled file is read, its contents are copied into the +shell's memory, rather than memory-mapped (see @t{-M}). This +happens automatically on systems that do not support memory mapping. + +@noindent +When compiling scripts instead of autoloadable functions, it is +often desirable to use this option; otherwise the whole file, including the +code to define functions which have already been defined, will +remain mapped, consequently wasting memory. + +@item @t{-M} +The compiled file is mapped into the shell's memory when read. This +is done in such a way that multiple instances of the shell running +on the same host will share this mapped file. If neither @t{-R} nor +@t{-M} is given, the @t{zcompile} builtin decides what to do based +on the size of the compiled file. + +@item @t{-k} +@itemx @t{-z} +These options are used when the compiled file contains functions which +are to be autoloaded. If @t{-z} is given, the +function will be autoloaded as if the @t{KSH_AUTOLOAD} option is +@emph{not} set, even if it is set at the time the compiled file is +read, while if the @t{-k} is given, the function will be loaded as if +@t{KSH_AUTOLOAD} @emph{is} set. These options also take precedence over +any @t{-k} or @t{-z} options specified to the @t{autoload} builtin. If +neither of these options is given, the function will be loaded as +determined by the setting of the @t{KSH_AUTOLOAD} option at the time +the compiled file is read. + +These options may also appear as many times as necessary between the listed +@var{name}s to specify the loading style of all following functions, up to +the next @t{-k} or @t{-z}. + +@end table + +@noindent +The created file always contains two versions of the compiled +format, one for big-endian machines and one for small-endian +machines. The upshot of this is that the compiled file is machine +independent and if it is read or mapped, only one half of the file +is actually used (and mapped). + + +@item @t{zformat} +See @ref{The zsh/zutil Module}. + +@item @t{zftp} +See @ref{The zsh/zftp Module}. + +@item @t{zle} +See @ref{Zle Builtins}. + +@findex zmodload +@cindex modules, loading +@cindex loading modules +@item @t{zmodload} [ @t{-dL} ] [ @t{-s} ] [ ... ] +@itemx @t{zmodload -F} [ @t{-alLme} @t{-P} @var{param} ] @var{module} [ [@t{+-}]@var{feature} ... ] +@itemx @t{zmodload -e} [ @t{-A} ] [ ... ] +@itemx @t{zmodload} [ @t{-a} [ @t{-bcpf} [ @t{-I} ] ] ] [ @t{-iL} ] ... +@itemx @t{zmodload} @t{-u} [ @t{-abcdpf} [ @t{-I} ] ] [ @t{-iL} ] ... +@itemx @t{zmodload} @t{-A} [ @t{-L} ] [ @var{modalias}[@t{=}@var{module}] ... ] +@itemx @t{zmodload} @t{-R} @var{modalias} ... +Performs operations relating to zsh's loadable modules. +Loading of modules while the shell is running (`dynamical loading') is not +available on all operating systems, or on all installations on a particular +operating system, although the @t{zmodload} command itself is always +available and can be used to manipulate modules built into versions of the +shell executable without dynamical loading. + +@noindent +Without arguments the names of all currently loaded binary modules are +printed. The @t{-L} option causes this list to be in the form of a +series of @t{zmodload} commands. Forms with arguments are: + +@noindent +@table @asis +@item @t{zmodload} [ @t{-is} ] @var{name} ... +@itemx @t{zmodload} @t{-u} [ @t{-i} ] @var{name} ... +In the simplest case, @t{zmodload} loads a binary module. The module must +be in a file with a name consisting of the specified @var{name} followed by +a standard suffix, usually `@t{.so}' (`@t{.sl}' on HPUX). +If the module to be loaded is already loaded the duplicate module is +ignored. If @t{zmodload} detects an inconsistency, such as an +invalid module name or circular dependency list, the current code block is +aborted. If it is available, the module is loaded if necessary, while if it +is not available, non-zero status is silently returned. The option +@t{-i} is accepted for compatibility but has no effect. + +@noindent +The @var{name}d module is searched for in the same way a command is, using +@t{$module_path} instead of @t{$path}. However, the path search is +performed even when the module name contains a `@t{/}', which it usually does. +There is no way to prevent the path search. + +@noindent +If the module supports features (see below), @t{zmodload} tries to +enable all features when loading a module. If the module was successfully +loaded but not all features could be enabled, @t{zmodload} returns status 2. + +@noindent +If the option @t{-s} is given, no error is printed if the module was not +available (though other errors indicating a problem with the module are +printed). The return status indicates if the module was loaded. This +is appropriate if the caller considers the module optional. + +@noindent +With @t{-u}, @t{zmodload} unloads modules. The same @var{name} +must be given that was given when the module was loaded, but it is not +necessary for the module to exist in the file system. +The @t{-i} option suppresses the error if the module is already +unloaded (or was never loaded). + +@noindent +Each module has a boot and a cleanup function. The module +will not be loaded if its boot function fails. Similarly a module +can only be unloaded if its cleanup function runs successfully. + +@item @t{zmodload -F} [ @t{-almLe} @t{-P} @var{param} ] @var{module} [ [@t{+-}]@var{feature} ... ] +@t{zmodload -F} allows more selective control over the features provided +by modules. With no options apart from @t{-F}, the module named +@var{module} is loaded, if it was not already loaded, and the list of +@var{feature}s is set to the required state. If no +@var{feature}s are specified, the module is loaded, if it was not already +loaded, but the state of features is unchanged. Each feature +may be preceded by a @t{+} to turn the feature on, or @t{-} to turn it +off; the @t{+} is assumed if neither character is present. +Any feature not explicitly mentioned is left in its current state; +if the module was not previously loaded this means any such features will +remain disabled. The return status is zero if all features were +set, 1 if the module failed to load, and 2 if some features could +not be set (for example, a parameter couldn't be added because there +was a different parameter of the same name) but the module was loaded. + +@noindent +The standard features are builtins, conditions, parameters and math +functions; these are indicated by the prefix `@t{b:}', `@t{c:}' +(`@t{C:}' for an infix condition), `@t{p:}' and `@t{f:}', respectively, +followed by the name that the corresponding feature would have in the +shell. For example, `@t{b:strftime}' indicates a builtin named +@t{strftime} and @t{p:EPOCHSECONDS} indicates a parameter named +@t{EPOCHSECONDS}. The module may provide other (`abstract') features of +its own as indicated by its documentation; these have no prefix. + +@noindent +With @t{-l} or @t{-L}, features provided by the module are listed. With +@t{-l} alone, a list of features together with their states is shown, one +feature per line. With @t{-L} alone, a @t{zmodload -F} command that would +cause enabled features of the module to be turned on is shown. With +@t{-lL}, a @t{zmodload -F} command that would cause all the features to be +set to their current state is shown. If one of these combinations is given +with the option @t{-P} @var{param} then the parameter @var{param} is set to an +array of features, either features together with their state or (if +@t{-L} alone is given) enabled features. + +@noindent +With the option @t{-L} the module name may be omitted; then a list +of all enabled features for all modules providing features is printed +in the form of @t{zmodload -F} commands. If @t{-l} is also given, +the state of both enabled and disabled features is output in that form. + +@noindent +A set of features may be provided together with @t{-l} or @t{-L} and a +module name; in that case only the state of those features is +considered. Each feature may be preceded by @t{+} or @t{-} but the +character has no effect. If no set of features is provided, all +features are considered. + +@noindent +With @t{-e}, the command first tests that the module is loaded; +if it is not, status 1 is returned. If the module is loaded, +the list of features given as an argument is examined. Any feature +given with no prefix is simply tested to see if the module provides it; +any feature given with a prefix @t{+} or @t{-} is tested to +see if is provided and in the given state. If the tests on all features +in the list succeed, status 0 is returned, else status 1. + +@noindent +With @t{-m}, each entry in the given list of features is taken +as a pattern to be matched against the list of features provided +by the module. An initial @t{+} or @t{-} must be given explicitly. +This may not be combined with the @t{-a} option as autoloads must +be specified explicitly. + +@noindent +With @t{-a}, the given list of features is marked for autoload from +the specified module, which may not yet be loaded. An optional @t{+} +may appear before the feature name. If the feature is prefixed with +@t{-}, any existing autoload is removed. The options @t{-l} and @t{-L} +may be used to list autoloads. Autoloading is specific to individual +features; when the module is loaded only the requested feature is +enabled. Autoload requests are preserved if the module is +subsequently unloaded until an explicit `@t{zmodload -Fa} @var{module} +@t{-}@var{feature}' is issued. It is not an error to request an autoload +for a feature of a module that is already loaded. + +@noindent +When the module is loaded each autoload is checked against the features +actually provided by the module; if the feature is not provided the +autoload request is deleted. A warning message is output; if the +module is being loaded to provide a different feature, and that autoload +is successful, there is no effect on the status of the current command. +If the module is already loaded at the time when @t{zmodload -Fa} is +run, an error message is printed and status 1 returned. + +@noindent +@t{zmodload -Fa} can be used with the @t{-l}, @t{-L}, @t{-e} and +@t{-P} options for listing and testing the existence of autoloadable +features. In this case @t{-l} is ignored if @t{-L} is specified. +@t{zmodload -FaL} with no module name lists autoloads for all modules. + +@noindent +Note that only standard features as described above can be autoloaded; +other features require the module to be loaded before enabling. + +@item @t{zmodload} @t{-d} [ @t{-L} ] [ @var{name} ] +@itemx @t{zmodload} @t{-d} @var{name} @var{dep} ... +@itemx @t{zmodload} @t{-ud} @var{name} [ @var{dep} ... ] +The @t{-d} option can be used to specify module dependencies. The modules +named in the second and subsequent arguments will be loaded before the +module named in the first argument. + +@noindent +With @t{-d} and one argument, all dependencies for that module are listed. +With @t{-d} and no arguments, all module dependencies are listed. This +listing is by default in a Makefile-like format. The @t{-L} option +changes this format to a list of @t{zmodload -d} commands. + +@noindent +If @t{-d} and @t{-u} are both used, dependencies are removed. If only one +argument is given, all dependencies for that module are removed. + +@item @t{zmodload} @t{-ab} [ @t{-L} ] +@itemx @t{zmodload} @t{-ab} [ @t{-i} ] @var{name} [ @var{builtin} ... ] +@itemx @t{zmodload} @t{-ub} [ @t{-i} ] @var{builtin} ... +The @t{-ab} option defines autoloaded builtins. It defines the specified +@var{builtin}s. When any of those builtins is called, the module specified +in the first argument is loaded and all its features are enabled (for +selective control of features use `@t{zmodload -F -a}' as described +above). If only the @var{name} is given, one builtin is defined, with +the same name as the module. @t{-i} suppresses the error if the builtin +is already defined or autoloaded, but not if another builtin of the +same name is already defined. + +@noindent +With @t{-ab} and no arguments, all autoloaded builtins are listed, with the +module name (if different) shown in parentheses after the builtin name. +The @t{-L} option changes this format to a list of @t{zmodload -a} +commands. + +@noindent +If @t{-b} is used together with the @t{-u} option, it removes builtins +previously defined with @t{-ab}. This is only possible if the builtin is +not yet loaded. @t{-i} suppresses the error if the builtin is already +removed (or never existed). + +@noindent +Autoload requests are retained if the module is subsequently unloaded +until an explicit `@t{zmodload -ub} @var{builtin}' is issued. + +@item @t{zmodload} @t{-ac} [ @t{-IL} ] +@itemx @t{zmodload} @t{-ac} [ @t{-iI} ] @var{name} [ @var{cond} ... ] +@itemx @t{zmodload} @t{-uc} [ @t{-iI} ] @var{cond} ... +The @t{-ac} option is used to define autoloaded condition codes. The +@var{cond} strings give the names of the conditions defined by the +module. The optional @t{-I} option is used to define infix condition +names. Without this option prefix condition names are defined. + +@noindent +If given no condition names, all defined names are listed (as a series of +@t{zmodload} commands if the @t{-L} option is given). + +@noindent +The @t{-uc} option removes definitions for autoloaded conditions. + +@item @t{zmodload} @t{-ap} [ @t{-L} ] +@itemx @t{zmodload} @t{-ap} [ @t{-i} ] @var{name} [ @var{parameter} ... ] +@itemx @t{zmodload} @t{-up} [ @t{-i} ] @var{parameter} ... +The @t{-p} option is like the @t{-b} and @t{-c} options, but makes +@t{zmodload} work on autoloaded parameters instead. + +@item @t{zmodload} @t{-af} [ @t{-L} ] +@itemx @t{zmodload} @t{-af} [ @t{-i} ] @var{name} [ @var{function} ... ] +@itemx @t{zmodload} @t{-uf} [ @t{-i} ] @var{function} ... +The @t{-f} option is like the @t{-b}, @t{-p}, and @t{-c} options, but +makes @t{zmodload} work on autoloaded math functions instead. + +@item @t{zmodload} @t{-a} [ @t{-L} ] +@itemx @t{zmodload} @t{-a} [ @t{-i} ] @var{name} [ @var{builtin} ... ] +@itemx @t{zmodload} @t{-ua} [ @t{-i} ] @var{builtin} ... +Equivalent to @t{-ab} and @t{-ub}. + +@item @t{zmodload -e} [ @t{-A} ] [ @var{string} ... ] +The @t{-e} option without arguments lists all loaded modules; if the @t{-A} +option is also given, module aliases corresponding to loaded modules are +also shown. If arguments are provided, nothing is printed; +the return status is set to zero if all @var{string}s given as arguments +are names of loaded modules and to one if at least on @var{string} is not +the name of a loaded module. This can be used to test for the +availability of things implemented by modules. In this case, any +aliases are automatically resolved and the @t{-A} flag is not used. + +@item @t{zmodload} @t{-A} [ @t{-L} ] [ @var{modalias}[@t{=}@var{module}] ... ] +For each argument, if both @var{modalias} and @var{module} are given, +define @var{modalias} to be an alias for the module @var{module}. +If the module @var{modalias} is ever subsequently requested, either via a +call to @t{zmodload} or implicitly, the shell will attempt to load +@var{module} instead. If @var{module} is not given, show the definition of +@var{modalias}. If no arguments are given, list all defined module aliases. +When listing, if the @t{-L} flag was also given, list the definition as a +@t{zmodload} command to recreate the alias. + +@noindent +The existence of aliases for modules is completely independent of whether +the name resolved is actually loaded as a module: while the alias exists, +loading and unloading the module under any alias has exactly the same +effect as using the resolved name, and does not affect the connection +between the alias and the resolved name which can be removed either by +@t{zmodload -R} or by redefining the alias. Chains of aliases (i.e. where +the first resolved name is itself an alias) are valid so long as these are +not circular. As the aliases take the same format as module names, they +may include path separators: in this case, there is no requirement for any +part of the path named to exist as the alias will be resolved first. For +example, `@t{any/old/alias}' is always a valid alias. + +@noindent +Dependencies added to aliased modules are actually added to the resolved +module; these remain if the alias is removed. It is valid to create an +alias whose name is one of the standard shell modules and which resolves to +a different module. However, if a module has dependencies, it +will not be possible to use the module name as an alias as the module will +already be marked as a loadable module in its own right. + +@noindent +Apart from the above, aliases can be used in the @t{zmodload} command +anywhere module names are required. However, aliases will not be +shown in lists of loaded modules with a bare `@t{zmodload}'. + +@item @t{zmodload} @t{-R} @var{modalias} ... +For each @var{modalias} argument that was previously defined as a module +alias via @t{zmodload -A}, delete the alias. If any was not defined, an +error is caused and the remainder of the line is ignored. + +@end table + +@noindent +Note that @t{zsh} makes no distinction between modules that were linked +into the shell and modules that are loaded dynamically. In both cases +this builtin command has to be used to make available the builtins and +other things defined by modules (unless the module is autoloaded on +these definitions). This is true even for systems that don't support +dynamic loading of modules. + +@item @t{zparseopts} +See @ref{The zsh/zutil Module}. + +@item @t{zprof} +See @ref{The zsh/zprof Module}. + +@item @t{zpty} +See @ref{The zsh/zpty Module}. + +@item @t{zregexparse} +See @ref{The zsh/zutil Module}. + +@item @t{zsocket} +See @ref{The zsh/net/socket Module}. + +@item @t{zstyle} +See @ref{The zsh/zutil Module}. + +@item @t{ztcp} +See @ref{The zsh/net/tcp Module}. + +@end table +@c (avoiding a yodl bug) +@c Yodl file: Zsh/zle.yo +@node Zsh Line Editor, Completion Widgets, Shell Builtin Commands, Top + +@chapter Zsh Line Editor +@noindent +@cindex line editor +@cindex editor, line +@cindex ZLE + +@section Description +@noindent +@pindex ZLE, use of +If the @t{ZLE} option is set (which it is by default in interactive shells) +and the shell input is attached to the terminal, the user +is able to edit command lines. + +@noindent +There are two display modes. The first, multiline mode, is the +default. It only works if the @t{TERM} parameter is set to a valid +terminal type that can move the cursor up. The second, single line +mode, is used if @t{TERM} is invalid or incapable of moving the +cursor up, or if the @t{SINGLE_LINE_ZLE} option is set. +@pindex SINGLE_LINE_ZLE, use of +@cindex ksh, editor mode +@cindex editor ksh style +This mode +is similar to @cite{ksh}, and uses no termcap sequences. If @t{TERM} is +"emacs", the @t{ZLE} option will be unset by default. + +@noindent +@vindex BAUD, use of +@vindex COLUMNS, use of +@vindex LINES, use of +The parameters @t{BAUD}, @t{COLUMNS}, and @t{LINES} are also used by the +line editor. See +@ref{Parameters Used By The Shell}. + +@noindent +@vindex zle_highlight, use of +The parameter @t{zle_highlight} is also used by the line editor; see +@ref{Character Highlighting}. Highlighting +of special characters and the region between the cursor and the +mark (as set with @t{set-mark-command} in Emacs mode, or by @t{visual-mode} +in Vi mode) is enabled +by default; consult this reference for more information. Irascible +conservatives will wish to know that all highlighting may be disabled by +the following setting: + +@noindent +@example +zle_highlight=(none) +@end example + +@noindent +In many places, references are made to the @t{numeric argument}. This can +by default be entered in emacs mode by holding the alt key and typing +a number, or pressing escape before each digit, and in vi command mode +by typing the number before entering a command. Generally the numeric +argument causes the next command entered to be repeated the specified +number of times, unless otherwise noted below; this is implemented +by the @t{digit-argument} widget. See also +@ref{Arguments} for some other ways the numeric argument can be modified. + +@noindent +@menu +* Keymaps:: +* Zle Builtins:: +* Zle Widgets:: +* Character Highlighting:: +@end menu + +@noindent +@node Keymaps, Zle Builtins, , Zsh Line Editor + +@section Keymaps +@noindent +@cindex keymaps +@cindex key bindings +@cindex bindings, key +A keymap in ZLE contains a set of bindings between key sequences +and ZLE commands. The empty key sequence cannot be bound. + +@noindent +There can be any number of keymaps at any time, and each keymap has one +or more names. If all of a keymap's names are deleted, it disappears. +@findex bindkey, use of +@t{bindkey} can be used to manipulate keymap names. + +@noindent +Initially, there are eight keymaps: + +@noindent +@table @asis +@item @t{emacs} +EMACS emulation +@item @t{viins} +vi emulation - insert mode +@item @t{vicmd} +vi emulation - command mode +@item @t{viopp} +vi emulation - operator pending +@item @t{visual} +vi emulation - selection active +@item @t{isearch} +incremental search mode +@item @t{command} +read a command name +@item @t{.safe} +fallback keymap +@end table + +@noindent +The `@t{.safe}' keymap is special. It can never be altered, and the name +can never be removed. However, it can be linked to other names, which can +be removed. In the future other special keymaps may be added; users should +avoid using names beginning with `@t{.}' for their own keymaps. + +@noindent +@vindex VISUAL +@vindex EDITOR +In addition to these names, either `@t{emacs}' or `@t{viins}' is +also linked to the name `@t{main}'. If one of the @t{VISUAL} or +@t{EDITOR} environment variables contain the string `@t{vi}' when the shell +starts up then it will be `@t{viins}', otherwise it will be `@t{emacs}'. +@t{bindkey}'s @t{-e} and @t{-v} +options provide a convenient way to override this default choice. + +@noindent +When the editor starts up, it will select the `@t{main}' keymap. +If that keymap doesn't exist, it will use `@t{.safe}' instead. + +@noindent +In the `@t{.safe}' keymap, each single key is bound to @t{self-insert}, +except for ^J (line feed) and ^M (return) which are bound to @t{accept-line}. +This is deliberately not pleasant to use; if you are using it, it +means you deleted the main keymap, and you should put it back. + +@subsection Reading Commands +@noindent +When ZLE is reading a command from the terminal, it may read a sequence +that is bound to some command and is also a prefix of a longer bound string. +In this case ZLE will wait a certain time to see if more characters +are typed, and if not (or they don't match any longer string) it will +execute the binding. This timeout is defined by the @t{KEYTIMEOUT} parameter; +its default is 0.4 sec. There is no timeout if the prefix string is not +itself bound to a command. + +@noindent +The key timeout is also applied when ZLE is reading the bytes from a +multibyte character string when it is in the appropriate mode. (This +requires that the shell was compiled with multibyte mode enabled; typically +also the locale has characters with the UTF-8 encoding, although any +multibyte encoding known to the operating system is supported.) If the +second or a subsequent byte is not read within the timeout period, the +shell acts as if @t{?} were typed and resets the input state. + +@noindent +As well as ZLE commands, key sequences can be bound to other strings, by using +`@t{bindkey -s}'. +When such a sequence is read, the replacement string is pushed back as input, +and the command reading process starts again using these fake keystrokes. +This input can itself invoke further replacement strings, but in order to +detect loops the process will be stopped if there are twenty such replacements +without a real command being read. + +@noindent +A key sequence typed by the user can be turned into a command name for use +in user-defined widgets with the @t{read-command} widget, described in +@ref{Miscellaneous} below. + +@subsection Local Keymaps +@noindent +@cindex local keymaps +While for normal editing a single keymap is used exclusively, in many +modes a local keymap allows for some keys to be customised. For example, +in an incremental search mode, a binding in the @t{isearch} keymap will +override a binding in the @t{main} keymap but all keys that are not +overridden can still be used. + +@noindent +If a key sequence is defined in a local keymap, it will hide a key +sequence in the global keymap that is a prefix of that sequence. An +example of this occurs with the binding of @t{iw} in @t{viopp} as this +hides the binding of @t{i} in @t{vicmd}. However, a longer sequence in +the global keymap that shares the same prefix can still apply so for +example the binding of @t{^Xa} in the global keymap will be unaffected +by the binding of @t{^Xb} in the local keymap. + +@noindent +@node Zle Builtins, Zle Widgets, Keymaps, Zsh Line Editor + +@section Zle Builtins +@noindent +@cindex zle, builtin commands +The ZLE module contains three related builtin commands. The @t{bindkey} +command manipulates keymaps and key bindings; the @t{vared} command invokes +ZLE on the value of a shell parameter; and the @t{zle} command manipulates +editing widgets and allows command line access to ZLE commands from within +shell functions. + +@noindent +@table @asis +@findex bindkey +@cindex keys, rebinding +@cindex rebinding keys +@cindex keys, binding +@cindex binding keys +@cindex keymaps +@item @t{bindkey} [ @var{options} ] @t{-l} [ @t{-L} ] [ @var{keymap} ... ] +@itemx @t{bindkey} [ @var{options} ] @t{-d} +@itemx @t{bindkey} [ @var{options} ] @t{-D} @var{keymap} ... +@itemx @t{bindkey} [ @var{options} ] @t{-A} @var{old-keymap new-keymap} +@itemx @t{bindkey} [ @var{options} ] @t{-N} @var{new-keymap} [ @var{old-keymap} ] +@itemx @t{bindkey} [ @var{options} ] @t{-m} +@itemx @t{bindkey} [ @var{options} ] @t{-r} @var{in-string} ... +@itemx @t{bindkey} [ @var{options} ] @t{-s} @var{in-string out-string} ... +@itemx @t{bindkey} [ @var{options} ] @var{in-string command} ... +@itemx @t{bindkey} [ @var{options} ] [ @var{in-string} ] +@t{bindkey}'s options can be divided into three categories: keymap +selection for the current command, operation selection, and others. The +keymap selection options are: + +@noindent +@table @asis +@item @t{-e} +Selects keymap `@t{emacs}' for any operations by the current command, +and also links `@t{emacs}' to `@t{main}' so that it is selected by +default the next time the editor starts. + +@item @t{-v} +Selects keymap `@t{viins}' for any operations by the current command, +and also links `@t{viins}' to `@t{main}' so that it is selected by default +the next time the editor starts. + +@item @t{-a} +Selects keymap `@t{vicmd}' for any operations by the current command. + +@item @t{-M} @var{keymap} +The @var{keymap} specifies a keymap name that is selected for any +operations by the current command. + +@end table + +@noindent +If a keymap selection is required and none of the options above are used, the +`@t{main}' keymap is used. Some operations do not permit a keymap to be +selected, namely: + +@noindent +@table @asis +@item @t{-l} +List all existing keymap names; if any arguments are given, list just +those keymaps. + +@noindent +If the @t{-L} option is also used, list in the form of @t{bindkey} +commands to create or link the keymaps. `@t{bindkey -lL +main}' shows which keymap is linked to `@t{main}', if any, and hence if +the standard emacs or vi emulation is in effect. This option does +not show the @t{.safe} keymap because it cannot be created in that +fashion; however, neither is `@t{bindkey -lL .safe}' reported as an +error, it simply outputs nothing. + +@item @t{-d} +Delete all existing keymaps and reset to the default state. + +@item @t{-D} @var{keymap} ... +Delete the named @var{keymap}s. + +@item @t{-A} @var{old-keymap new-keymap} +Make the @var{new-keymap} name an alias for @var{old-keymap}, so that +both names refer to the same keymap. The names have equal standing; +if either is deleted, the other remains. If there is already a keymap +with the @var{new-keymap} name, it is deleted. + +@item @t{-N} @var{new-keymap} [ @var{old-keymap} ] +Create a new keymap, named @var{new-keymap}. If a keymap already has that +name, it is deleted. If an @var{old-keymap} name is given, the new keymap +is initialized to be a duplicate of it, otherwise the new keymap will +be empty. + +@end table + +@noindent +To use a newly created keymap, it should be linked to @t{main}. Hence +the sequence of commands to create and use a new keymap `@t{mymap}' +initialized from the @t{emacs} keymap (which remains unchanged) is: + +@noindent +@example +bindkey -N mymap emacs +bindkey -A mymap main +@end example + +@noindent +Note that while `@t{bindkey -A} @var{newmap} @t{main}' will work when +@var{newmap} is @t{emacs} or @t{viins}, it will not work for @t{vicmd}, as +switching from vi insert to command mode becomes impossible. + +@noindent +The following operations act on the `@t{main}' keymap if no keymap +selection option was given: + +@noindent +@table @asis +@item @t{-m} +Add the built-in set of meta-key bindings to the selected keymap. +Only keys that are unbound or bound to @t{self-insert} are affected. + +@item @t{-r} @var{in-string} ... +Unbind the specified @var{in-string}s in the selected keymap. +This is exactly equivalent to binding the strings to @t{undefined-key}. + +@noindent +When @t{-R} is also used, interpret the @var{in-string}s as ranges. + +@noindent +When @t{-p} is also used, the @var{in-string}s specify prefixes. Any +binding that has the given @var{in-string} as a prefix, not including the +binding for the @var{in-string} itself, if any, will be removed. For +example, + +@noindent +@example +bindkey -rpM viins '^[' +@end example + +@noindent +will remove all bindings in the vi-insert keymap beginning with an escape +character (probably cursor keys), but leave the binding for the escape +character itself (probably @t{vi-cmd-mode}). This is incompatible with the +option @t{-R}. + +@item @t{-s} @var{in-string out-string} ... +Bind each @var{in-string} to each @var{out-string}. +When @var{in-string} is typed, @var{out-string} will be +pushed back and treated as input to the line editor. +When @t{-R} is also used, interpret the @var{in-string}s as ranges. + +@noindent +Note that both @var{in-string} and @var{out-string} are subject to the same +form of interpretation, as described below. + +@item @var{in-string command} ... +Bind each @var{in-string} to each @var{command}. +When @t{-R} is used, interpret the @var{in-string}s as ranges. + +@item [ @var{in-string} ] +List key bindings. If an @var{in-string} is specified, the binding of +that string in the selected keymap is displayed. Otherwise, all key +bindings in the selected keymap are displayed. (As a special case, +if the @t{-e} or @t{-v} option is used alone, the keymap is @emph{not} +displayed - the implicit linking of keymaps is the only thing that +happens.) + +@noindent +When the option @t{-p} is used, the @var{in-string} must be present. +The listing shows all bindings which have the given key sequence as a +prefix, not including any bindings for the key sequence itself. + +@noindent +When the @t{-L} option is used, the list is in the form of @t{bindkey} +commands to create the key bindings. + +@end table + +@noindent +When the @t{-R} option is used as noted above, a valid range consists of +two characters, with an optional `@t{-}' between them. All characters +between the two specified, inclusive, are bound as specified. + +@noindent +For either @var{in-string} or @var{out-string}, the following +escape sequences are recognised: + +@noindent +@table @asis +@item @t{\a} +bell character +@item @t{\b} +backspace +@item @t{\e}, @t{\E} +escape +@item @t{\f} +form feed +@item @t{\n} +linefeed (newline) +@item @t{\r} +carriage return +@item @t{\t} +horizontal tab +@item @t{\v} +vertical tab +@item @t{\}@var{NNN} +character code in octal +@item @t{\x}@var{NN} +character code in hexadecimal +@item @t{\u}@var{NNNN} +unicode character code in hexadecimal +@item @t{\U}@var{NNNNNNNN} +unicode character code in hexadecimal +@item @t{\M}[@t{-}]@var{X} +character with meta bit set +@item @t{\C}[@t{-}]@var{X} +control character +@item @t{^}@var{X} +control character +@end table + +@noindent +In all other cases, `@t{\}' escapes the following character. Delete is +written as `@t{^?}'. Note that `@t{\M^?}' and `@t{^\M?}' are not the same, +and that (unlike emacs), the bindings `@t{\M-}@var{X}' and `@t{\e}@var{X}' +are entirely distinct, although they are initialized to the same bindings +by `@t{bindkey -m}'. + +@findex vared +@cindex parameters, editing +@cindex editing parameters + +@item @t{vared }[ @t{-Aacghe} ] [ @t{-p} @var{prompt} ] [ @t{-r} @var{rprompt} ] +@itemx @t{@ @ @ @ @ @ }[ @t{-M} @var{main-keymap} ] [ @t{-m} @var{vicmd-keymap} ] +@itemx @t{@ @ @ @ @ @ }[ @t{-i} @var{init-widget} ] [ @t{-f} @var{finish-widget} ] +@itemx @t{@ @ @ @ @ @ }[ @t{-t} @var{tty} ] @var{name} +The value of the parameter @var{name} is loaded into the edit +buffer, and the line editor is invoked. When the editor exits, +@var{name} is set to the string value returned by the editor. +When the @t{-c} flag is given, the parameter is created if it doesn't +already exist. The @t{-a} flag may be given with @t{-c} to create +an array parameter, or the @t{-A} flag to create an associative array. +If the type of an existing parameter does not match the type to be +created, the parameter is unset and recreated. The @t{-g} flag may +be given to suppress warnings from the @t{WARN_CREATE_GLOBAL} +and @t{WARN_NESTED_VAR} options. + +@noindent +If an array or array slice is being edited, separator characters as defined +in @t{$IFS} will be shown quoted with a backslash, as will backslashes +themselves. Conversely, when the edited text is split into an array, a +backslash quotes an immediately following separator character or backslash; +no other special handling of backslashes, or any handling of quotes, is +performed. + +@noindent +Individual elements of existing array or associative array parameters +may be edited by using subscript syntax on @var{name}. New elements are +created automatically, even without @t{-c}. + +@noindent +If the @t{-p} flag is given, the following string will be taken as +the prompt to display at the left. If the @t{-r} flag is given, +the following string gives the prompt to display at the right. If the +@t{-h} flag is specified, the history can be accessed from ZLE. If the +@t{-e} flag is given, typing @t{^D} (Control-D) on an empty line +causes @t{vared} to exit immediately with a non-zero return value. + +@noindent +The @t{-M} option gives a keymap to link to the @t{main} keymap during +editing, and the @t{-m} option gives a keymap to link to the @t{vicmd} +keymap during editing. For vi-style editing, this allows a pair of keymaps +to override @t{viins} and @t{vicmd}. For emacs-style editing, only @t{-M} +is normally needed but the @t{-m} option may still be used. On exit, the +previous keymaps will be restored. + +@noindent +@t{Vared} calls the usual `@t{zle-line-init}' and `@t{zle-line-finish}' +hooks before and after it takes control. Using the @t{-i} and @t{-f} +options, it is possible to replace these with other custom widgets. + +@noindent +If `@t{-t} @var{tty}' is given, @var{tty} is the name of a terminal device +to be used instead of the default @t{/dev/tty}. If @var{tty} does not +refer to a terminal an error is reported. + +@findex zle +@cindex widgets, rebinding +@cindex rebinding widgets +@cindex widgets, binding +@cindex binding widgets +@cindex widgets, invoking +@cindex invoking widgets +@cindex widgets, calling +@cindex calling widgets +@cindex widgets, defining +@cindex defining widgets +@item @t{zle} +@itemx @t{zle} @t{-l} [ @t{-L} | @t{-a} ] [ @var{string} ... ] +@itemx @t{zle} @t{-D} @var{widget} ... +@itemx @t{zle} @t{-A} @var{old-widget} @var{new-widget} +@itemx @t{zle} @t{-N} @var{widget} [ @var{function} ] +@itemx @t{zle} @t{-f} @var{flag} [ @var{flag}... ] +@itemx @t{zle} @t{-C} @var{widget} @var{completion-widget} @var{function} +@itemx @t{zle} @t{-R} [ @t{-c} ] [ @var{display-string} ] [ @var{string} ... ] +@itemx @t{zle} @t{-M} @var{string} +@itemx @t{zle} @t{-U} @var{string} +@itemx @t{zle} @t{-K} @var{keymap} +@itemx @t{zle} @t{-F} [ @t{-L} | @t{-w} ] [ @var{fd} [ @var{handler} ] ] +@itemx @t{zle} @t{-I} +@itemx @t{zle} @t{-T} [ @t{tc} @var{function} | @t{-r} @t{tc} | @t{-L} ] +@itemx @t{zle} @var{widget} [ @t{-n} @var{num} ] [ @t{-Nw} ] [ @t{-K} @var{keymap} ] @var{args} ... +The @t{zle} builtin performs a number of different actions concerning +ZLE. + +@noindent +With no options and no arguments, only the return status will be +set. It is zero if ZLE is currently active and widgets could be +invoked using this builtin command and non-zero otherwise. +Note that even if non-zero status is returned, zle may still be active as +part of the completion system; this does not allow direct calls to ZLE +widgets. + +@noindent +Otherwise, which operation it performs depends on its options: + +@noindent +@table @asis +@item @t{-l} [ @t{-L} | @t{-a} ] [ @var{string} ] +List all existing user-defined widgets. If the @t{-L} +option is used, list in the form of @t{zle} +commands to create the widgets. + +@noindent +When combined with the @t{-a} option, all widget names are listed, +including the builtin ones. In this case the @t{-L} option is ignored. + +@noindent +If at least one @var{string} is given, and @t{-a} is present or @t{-L} is +not used, nothing will be printed. The return status will be zero if +all @var{string}s are names of existing widgets and non-zero if at least one +@var{string} is not a name of a defined widget. If @t{-a} is also +present, all widget names are used for the comparison including builtin +widgets, else only user-defined widgets are used. + +@noindent +If at least one @var{string} is present and the @t{-L} option is used, +user-defined widgets matching any @var{string} are listed in the form of +@t{zle} commands to create the widgets. + +@item @t{-D} @var{widget} ... +Delete the named @var{widget}s. + +@item @t{-A} @var{old-widget} @var{new-widget} +Make the @var{new-widget} name an alias for @var{old-widget}, so that +both names refer to the same widget. The names have equal standing; +if either is deleted, the other remains. If there is already a widget +with the @var{new-widget} name, it is deleted. + +@item @t{-N} @var{widget} [ @var{function} ] +Create a user-defined widget. If there is already a widget with the +specified name, it is overwritten. When the new +widget is invoked from within the editor, the specified shell @var{function} +is called. If no function name is specified, it defaults to +the same name as the widget. For further information, see +@ref{Zle Widgets}. + +@item @t{-f} @var{flag} [ @var{flag}... ] +Set various flags on the running widget. Possible values for @var{flag} are: + +@noindent +@t{yank} for indicating that the widget has yanked text into the buffer. +If the widget is wrapping an existing internal widget, no further +action is necessary, but if it has inserted the text manually, then it +should also take care to set @t{YANK_START} and @t{YANK_END} correctly. +@t{yankbefore} does the same but is used when the yanked text appears +after the cursor. + +@noindent +@t{kill} for indicating that text has been killed into the cutbuffer. +When repeatedly invoking a kill widget, text is appended to the cutbuffer +instead of replacing it, but when wrapping such widgets, it is necessary +to call `@t{zle -f kill}' to retain this effect. + +@noindent +@t{vichange} for indicating that the widget represents a vi change that +can be repeated as a whole with `@t{vi-repeat-change}'. The flag should be set +early in the function before inspecting the value of @t{NUMERIC} or invoking +other widgets. This has no effect for a widget invoked from insert mode. If +insert mode is active when the widget finishes, the change extends until next +returning to command mode. + +@cindex completion widgets, creating +@item @t{-C} @var{widget} @var{completion-widget} @var{function} +Create a user-defined completion widget named @var{widget}. The +completion widget will behave like the built-in completion-widget +whose name is given as @var{completion-widget}. To generate the +completions, the shell function @var{function} will be called. +For further information, see +@ref{Completion Widgets}. + +@item @t{-R} [ @t{-c} ] [ @var{display-string} ] [ @var{string} ... ] +Redisplay the command line; this is to be called from within a user-defined +widget to allow changes to become visible. If a @var{display-string} is +given and not empty, this is shown in the status line (immediately +below the line being edited). + +@noindent +If the optional @var{string}s are given they are listed below the +prompt in the same way as completion lists are printed. If no +@var{string}s are given but the @t{-c} option is used such a list is +cleared. + +@noindent +Note that this option is only useful for widgets that do not exit +immediately after using it because the strings displayed will be erased +immediately after return from the widget. + +@noindent +This command can safely be called outside user defined widgets; if zle is +active, the display will be refreshed, while if zle is not active, the +command has no effect. In this case there will usually be no other +arguments. + +@noindent +The status is zero if zle was active, else one. + +@item @t{-M} @var{string} +As with the @t{-R} option, the @var{string} will be displayed below the +command line; unlike the @t{-R} option, the string will not be put into +the status line but will instead be printed normally below the +prompt. This means that the @var{string} will still be displayed after +the widget returns (until it is overwritten by subsequent commands). + +@item @t{-U} @var{string} +This pushes the characters in the @var{string} onto the input stack of +ZLE. After the widget currently executed finishes ZLE will behave as +if the characters in the @var{string} were typed by the user. + +@noindent +As ZLE uses a stack, if this option is used repeatedly +the last string pushed onto the stack will be processed first. However, +the characters in each @var{string} will be processed in the order in which +they appear in the string. + +@item @t{-K} @var{keymap} +Selects the keymap named @var{keymap}. An error message will be displayed if +there is no such keymap. + +@noindent +This keymap selection affects the interpretation of following keystrokes +within this invocation of ZLE. Any following invocation (e.g., the next +command line) will start as usual with the `@t{main}' keymap selected. + +@item @t{-F} [ @t{-L} | @t{-w} ] [ @var{fd} [ @var{handler} ] ] +Only available if your system supports one of the `poll' or `select' system +calls; most modern systems do. + +@noindent +Installs @var{handler} (the name of a shell function) to handle input from +file descriptor @var{fd}. Installing a handler for an @var{fd} which is +already handled causes the existing handler to be replaced. Any number of +handlers for any number of readable file descriptors may be installed. +Note that zle makes no attempt to check whether this @var{fd} is actually +readable when installing the handler. The user must make their own +arrangements for handling the file descriptor when zle is not active. + +@noindent +When zle is attempting to read data, it will examine both the terminal and +the list of handled @var{fd}'s. If data becomes available on a handled +@var{fd}, zle calls @var{handler} with the fd which is ready for reading +as the first argument. Under normal circumstances this is the only +argument, but if an error was detected, a second argument provides +details: `@t{hup}' for a disconnect, `@t{nval}' for a closed or otherwise +invalid descriptor, or `@t{err}' for any other condition. Systems that +support only the `select' system call always use `@t{err}'. + +@noindent +If the option @t{-w} is also given, the @var{handler} is instead a line +editor widget, typically a shell function made into a widget using +`@t{zle -N}'. In that case @var{handler} can use all the facilities of zle +to update the current editing line. Note, however, that as handling @var{fd} +takes place at a low level changes to the display will not automatically +appear; the widget should call `@t{zle -R}' to force redisplay. As of this +writing, widget handlers only support a single argument and thus are never +passed a string for error state, so widgets must be prepared to test the +descriptor themselves. + +@noindent +If either type of handler produces output to the terminal, it should call +`@t{zle -I}' before doing so (see below). Handlers should not attempt to +read from the terminal. + +@noindent +If no @var{handler} is given, but an @var{fd} is present, any handler for +that @var{fd} is removed. If there is none, an error message is printed +and status 1 is returned. + +@noindent +If no arguments are given, or the @t{-L} option is supplied, a list of +handlers is printed in a form which can be stored for later execution. + +@noindent +An @var{fd} (but not a @var{handler}) may optionally be given with the @t{-L} +option; in this case, the function will list the handler if any, else +silently return status 1. + +@noindent +Note that this feature should be used with care. Activity on one of the +@var{fd}'s which is not properly handled can cause the terminal to become +unusable. Removing an @var{fd} handler from within a signal trap may cause +unpredictable behavior. + +@noindent +Here is a simple example of using this feature. A connection to a remote +TCP port is created using the ztcp command; see +@ref{The zsh/net/tcp Module}. Then a handler is installed +which simply prints out any data which arrives on this connection. Note +that `select' will indicate that the file descriptor needs handling +if the remote side has closed the connection; we handle that by testing +for a failed read. + +@noindent +@example +if ztcp pwspc 2811; then + tcpfd=$REPLY + handler() @{ + zle -I + local line + if ! read -r line <&$1; then + # select marks this fd if we reach EOF, + # so handle this specially. + print "[Read on fd $1 failed, removing.]" >&2 + zle -F $1 + return 1 + fi + print -r - $line + @} + zle -F $tcpfd handler +fi +@end example + +@item @t{-I} +Unusually, this option is most useful outside ordinary widget functions, +though it may be used within if normal output to the terminal is required. +It invalidates the current zle display in preparation for output; typically +this will be from a trap function. It has no effect if zle is not +active. When a trap exits, the shell checks to see if the display needs +restoring, hence the following will print output in such a way as not to +disturb the line being edited: + +@noindent +@example +TRAPUSR1() @{ + # Invalidate zle display + [[ -o zle ]] && zle -I + # Show output + print Hello +@} +@end example + +@noindent +In general, the trap function may need to test whether zle is active before +using this method (as shown in the example), since the @t{zsh/zle} module +may not even be loaded; if it is not, the command can be skipped. + +@noindent +It is possible to call `@t{zle -I}' several times before control is +returned to the editor; the display will only be invalidated the first time +to minimise disruption. + +@noindent +Note that there are normally better ways of manipulating the display from +within zle widgets; see, for example, `@t{zle -R}' above. + +@noindent +The returned status is zero if zle was invalidated, even though +this may have been by a previous call to `@t{zle -I}' or by a system +notification. To test if a zle widget may be called at this point, execute +@t{zle} with no arguments and examine the return status. + +@item @t{-T} +This is used to add, list or remove internal transformations on the +processing performed by the line editor. It is typically used only for +debugging or testing and is therefore of little interest to the general +user. + +@noindent +`@t{zle -T} @var{transformation} @var{func}' specifies that the +given @var{transformation} (see below) is effected by shell function +@var{func}. + +@noindent +`@t{zle -Tr} @var{transformation}' removes the given @var{transformation} +if it was present (it is not an error if none was). + +@noindent +`@t{zle -TL}' can be used to list all transformations currently in +operation. + +@noindent +Currently the only transformation is @t{tc}. This is used instead +of outputting termcap codes to the terminal. When the transformation is +in operation the shell function is passed the termcap code that would be +output as its first argument; if the operation required a numeric +argument, that is passed as a second argument. The function should set +the shell variable @t{REPLY} to the transformed termcap code. Typically +this is used to produce some simply formatted version of the code and +optional argument for debugging or testing. Note that this +transformation is not applied to other non-printing characters such as +carriage returns and newlines. + +@item @var{widget} [ @t{-n} @var{num} ] [ @t{-Nw} ] [ @t{-K} @var{keymap} ] @var{args} ... +Invoke the specified @var{widget}. This can only be done when ZLE is +active; normally this will be within a user-defined widget. + +@noindent +With the options @t{-n} and @t{-N}, the current numeric argument will be +saved and then restored after the call to @var{widget}; `@t{-n} @var{num}' +sets the numeric argument temporarily to @var{num}, while `@t{-N}' sets it +to the default, i.e. as if there were none. + +@noindent +With the option @t{-K}, @var{keymap} will be used as the current keymap +during the execution of the widget. The previous keymap will be +restored when the widget exits. + +@noindent +Normally, calling a widget in this way does not set the special +parameter @t{WIDGET} and related parameters, so that the environment +appears as if the top-level widget called by the user were still +active. With the option @t{-w}, @t{WIDGET} and related parameters are set +to reflect the widget being executed by the @t{zle} call. + +@noindent +Any further arguments will be passed to the widget; note that as +standard argument handling is performed, any general argument list +should be preceded by @t{-}@t{-}. If it is a shell +function, these are passed down as positional parameters; for builtin +widgets it is up to the widget in question what it does with them. +Currently arguments are only handled by the incremental-search commands, +the @t{history-search-forward} and @t{-backward} and the corresponding +functions prefixed by @t{vi-}, and by @t{universal-argument}. No error is +flagged if the command does not use the arguments, or only uses some of +them. + +@noindent +The return status reflects the success or failure of the operation carried +out by the widget, or if it is a user-defined widget the return status of +the shell function. + +@noindent +A non-zero return status causes the shell to beep when the widget exits, +unless the @t{BEEP} options was unset or the widget was called via the +@t{zle} command. Thus if a user defined widget requires an immediate beep, +it should call the @t{beep} widget directly. + +@end table + +@end table + +@noindent +@node Zle Widgets, Character Highlighting, Zle Builtins, Zsh Line Editor + +@section Widgets +@noindent +@cindex widgets +All actions in the editor are performed by `widgets'. A widget's job is +simply to perform some small action. The ZLE commands that key sequences +in keymaps are bound to are in fact widgets. Widgets can be user-defined +or built in. + +@noindent +The standard widgets built into ZLE are listed in Standard Widgets below. +Other built-in widgets can be defined by other modules (see +@ref{Zsh Modules}). Each built-in widget has two names: its normal canonical name, and the +same name preceded by a `@t{.}'. The `@t{.}' name is special: it can't be +rebound to a different widget. This makes the widget available even when +its usual name has been redefined. + +@noindent +User-defined widgets are defined using `@t{zle -N}', and implemented +as shell functions. When the widget is executed, the corresponding +shell function is executed, and can perform editing (or other) actions. +It is recommended that user-defined widgets should not have names +starting with `@t{.}'. + +@section User-Defined Widgets +@noindent +@cindex widgets, user-defined +User-defined widgets, being implemented as shell functions, +can execute any normal shell command. They can also run other widgets +(whether built-in or user-defined) using the @t{zle} builtin command. The +standard input of the function is redirected from /dev/null to prevent +external commands from unintentionally blocking ZLE by reading from the +terminal, but @t{read -k} or @t{read -q} can be used to read characters. +Finally, they can examine and edit the ZLE buffer being edited by reading +and setting the special parameters described below. + +@noindent +@cindex parameters, editor +@cindex parameters, zle +These special parameters are always available in widget functions, but +are not in any way special outside ZLE. If they have some normal value +outside ZLE, that value is temporarily inaccessible, but will return +when the widget function exits. These special parameters in fact have +local scope, like parameters created in a function using @t{local}. + +@noindent +Inside completion widgets and traps called while ZLE is active, these +parameters are available read-only. + +@noindent +Note that the parameters appear as local to any ZLE widget in +which they appear. Hence if it is desired to override them this needs +to be done within a nested function: + +@noindent +@example +widget-function() @{ + # $WIDGET here refers to the special variable + # that is local inside widget-function + () @{ + # This anonymous nested function allows WIDGET + # to be used as a local variable. The -h + # removes the special status of the variable. + local -h WIDGET + @} +@} +@end example + +@noindent +@table @asis +@vindex BUFFER +@item @t{BUFFER} (scalar) +The entire contents of the edit buffer. If it is written to, the +cursor remains at the same offset, unless that would put it outside the +buffer. + +@vindex BUFFERLINES +@item @t{BUFFERLINES} (integer) +The number of screen lines needed for the edit buffer currently +displayed on screen (i.e. without any changes to the preceding +parameters done after the last redisplay); read-only. + +@vindex CONTEXT +@item @t{CONTEXT} (scalar) +The context in which zle was called to read a line; read-only. One of +the values: + +@noindent +@table @asis +@item @t{start} +The start of a command line (at prompt @t{PS1}). + +@item @t{cont} +A continuation to a command line (at prompt @t{PS2}). + +@item @t{select} +In a @t{select} loop (at prompt @t{PS3}). + +@item @t{vared} +Editing a variable in @t{vared}. + +@end table + +@vindex CURSOR +@item @t{CURSOR} (integer) +The offset of the cursor, within the edit buffer. This is in the range +0 to @t{$#BUFFER}, and is by definition equal to @t{$#LBUFFER}. +Attempts to move the cursor outside the buffer will result in the +cursor being moved to the appropriate end of the buffer. + +@vindex CUTBUFFER +@item @t{CUTBUFFER} (scalar) +The last item cut using one of the `@t{kill-}' commands; the string +which the next yank would insert in the line. Later entries in +the kill ring are in the array @t{killring}. Note that the +command `@t{zle copy-region-as-kill} @var{string}' can be used to +set the text of the cut buffer from a shell function and cycle the kill +ring in the same way as interactively killing text. + +@vindex HISTNO +@item @t{HISTNO} (integer) +The current history number. Setting this has the same effect as +moving up or down in the history to the corresponding history line. +An attempt to set it is ignored if the line is not stored in the +history. Note this is not the same as the parameter @t{HISTCMD}, +which always gives the number of the history line being added to the main +shell's history. @t{HISTNO} refers to the line being retrieved within +zle. + +@vindex ISEARCHMATCH_ACTIVE +@vindex ISEARCHMATCH_START +@vindex ISEARCHMATCH_END +@item @t{ISEARCHMATCH_ACTIVE} (integer) +@itemx @t{ISEARCHMATCH_START} (integer) +@itemx @t{ISEARCHMATCH_END} (integer) +@t{ISEARCHMATCH_ACTIVE} indicates whether a part of the @t{BUFFER} is +currently matched by an incremental search pattern. @t{ISEARCHMATCH_START} +and @t{ISEARCHMATCH_END} give the location of the matched part and are +in the same units as @t{CURSOR}. They are only valid for reading +when @t{ISEARCHMATCH_ACTIVE} is non-zero. + +@noindent +All parameters are read-only. + +@vindex KEYMAP +@item @t{KEYMAP} (scalar) +The name of the currently selected keymap; read-only. + +@vindex KEYS +@item @t{KEYS} (scalar) +The keys typed to invoke this widget, as a literal string; read-only. + +@vindex KEYS_QUEUED_COUNT +@item @t{KEYS_QUEUED_COUNT} (integer) +The number of bytes pushed back to the input queue and therefore +available for reading immediately before any I/O is done; read-only. +See also @t{PENDING}; the two values are distinct. + +@vindex killring +@item @t{killring} (array) +The array of previously killed items, with the most recently killed first. +This gives the items that would be retrieved by a @t{yank-pop} in the +same order. Note, however, that the most recently killed item is in +@t{$CUTBUFFER}; @t{$killring} shows the array of previous entries. + +@noindent +The default size for the kill ring is eight, however the length may be +changed by normal array operations. Any empty string in the kill ring is +ignored by the @t{yank-pop} command, hence the size of the array +effectively sets the maximum length of the kill ring, while the number of +non-zero strings gives the current length, both as seen by the user at the +command line. + +@vindex LASTABORTEDSEARCH +@item @t{LASTABORTEDSEARCH} (scalar) +The last search string used by an interactive search that was +aborted by the user (status 3 returned by the search widget). + +@vindex LASTSEARCH +@item @t{LASTSEARCH} (scalar) +The last search string used by an interactive search; read-only. +This is set even if the search failed (status 0, 1 or 2 returned +by the search widget), but not if it was aborted by the user. + +@vindex LASTWIDGET +@item @t{LASTWIDGET} (scalar) +The name of the last widget that was executed; read-only. + +@vindex LBUFFER +@item @t{LBUFFER} (scalar) +The part of the buffer that lies to the left of the cursor position. +If it is assigned to, only that part of the buffer is replaced, and the +cursor remains between the new @t{$LBUFFER} and the old @t{$RBUFFER}. + +@vindex MARK +@item @t{MARK} (integer) +Like @t{CURSOR}, but for the mark. With vi-mode operators that wait for +a movement command to select a region of text, setting @t{MARK} allows +the selection to extend in both directions from the initial cursor +position. + +@vindex NUMERIC +@item @t{NUMERIC} (integer) +The numeric argument. If no numeric argument was given, this parameter +is unset. When this is set inside a widget function, builtin widgets +called with the @t{zle} builtin command will use the value +assigned. If it is unset inside a widget function, builtin widgets +called behave as if no numeric argument was given. + +@vindex PENDING +@item @t{PENDING} (integer) +The number of bytes pending for input, i.e. the number of bytes which have +already been typed and can immediately be read. On systems where the shell +is not able to get this information, this parameter will always have a +value of zero. Read-only. See also @t{KEYS_QUEUED_COUNT}; the two +values are distinct. + +@vindex PREBUFFER +@item @t{PREBUFFER} (scalar) +In a multi-line input at the secondary prompt, this read-only parameter +contains the contents of the lines before the one the cursor is +currently in. + +@vindex PREDISPLAY +@item @t{PREDISPLAY} (scalar) +Text to be displayed before the start of the editable text buffer. This +does not have to be a complete line; to display a complete line, a newline +must be appended explicitly. The text is reset on each new invocation +(but not recursive invocation) of zle. + +@vindex POSTDISPLAY +@item @t{POSTDISPLAY} (scalar) +Text to be displayed after the end of the editable text buffer. This +does not have to be a complete line; to display a complete line, a newline +must be prepended explicitly. The text is reset on each new invocation +(but not recursive invocation) of zle. + +@vindex RBUFFER +@item @t{RBUFFER} (scalar) +The part of the buffer that lies to the right of the cursor position. +If it is assigned to, only that part of the buffer is replaced, and the +cursor remains between the old @t{$LBUFFER} and the new @t{$RBUFFER}. + +@vindex REGION_ACTIVE +@item @t{REGION_ACTIVE} (integer) +Indicates if the region is currently active. It can be assigned 0 or 1 +to deactivate and activate the region respectively. A value of 2 +activates the region in line-wise mode with the highlighted text +extending for whole lines only; see +@ref{Character Highlighting}. + +@vindex region_highlight +@item @t{region_highlight} (array) +Each element of this array may be set to a string that describes +highlighting for an arbitrary region of the command line that will +take effect the next time the command line is redisplayed. Highlighting +of the non-editable parts of the command line in @t{PREDISPLAY} +and @t{POSTDISPLAY} are possible, but note that the @t{P} flag +is needed for character indexing to include @t{PREDISPLAY}. + +@noindent +Each string consists of the following parts: + +@noindent +@itemize @bullet + +@item +Optionally, a `@t{P}' to signify that the start and end offset that +follow include any string set by the @t{PREDISPLAY} special parameter; +this is needed if the predisplay string itself is to be highlighted. +Whitespace may follow the `@t{P}'. +@item +A start offset in the same units as @t{CURSOR}, terminated by +whitespace. +@item +An end offset in the same units as @t{CURSOR}, terminated by +whitespace. +@item +A highlight specification in the same format as +used for contexts in the parameter @t{zle_highlight}, see +@ref{Character Highlighting}; +for example, @t{standout} or @t{fg=red,bold}. +@end itemize + +@noindent +For example, + +@noindent +@example +region_highlight=("P0 20 bold") +@end example + +@noindent +specifies that the first twenty characters of the text including +any predisplay string should be highlighted in bold. + +@noindent +Note that the effect of @t{region_highlight} is not saved and disappears +as soon as the line is accepted. + +@noindent +The final highlighting on the command line depends on both @t{region_highlight} +and @t{zle_highlight}; see +@ref{Character Highlighting} for details. + +@vindex registers +@item @t{registers} (associative array) +The contents of each of the vi register buffers. These are +typically set using @t{vi-set-buffer} followed by a delete, change or +yank command. + +@vindex SUFFIX_ACTIVE +@vindex SUFFIX_START +@vindex SUFFIX_END +@item @t{SUFFIX_ACTIVE} (integer) +@itemx @t{SUFFIX_START} (integer) +@itemx @t{SUFFIX_END} (integer) +@t{SUFFIX_ACTIVE} indicates whether an auto-removable completion suffix +is currently active. @t{SUFFIX_START} and @t{SUFFIX_END} give the +location of the suffix and are in the same units as @t{CURSOR}. They are +only valid for reading when @t{SUFFIX_ACTIVE} is non-zero. + +@noindent +All parameters are read-only. + +@vindex UNDO_CHANGE_NO +@item @t{UNDO_CHANGE_NO} (integer) +A number representing the state of the undo history. The only use +of this is passing as an argument to the @t{undo} widget in order to +undo back to the recorded point. Read-only. + +@vindex UNDO_LIMIT_NO +@item @t{UNDO_LIMIT_NO} (integer) +A number corresponding to an existing change in the undo history; +compare @t{UNDO_CHANGE_NO}. If this is set to a value greater +than zero, the @t{undo} command will not allow the line to +be undone beyond the given change number. It is still possible +to use `@t{zle undo} @var{change}' in a widget to undo beyond +that point; in that case, it will not be possible to undo at +all until @t{UNDO_LIMIT_NO} is reduced. Set to 0 to disable the limit. + +@noindent +A typical use of this variable in a widget function is as follows (note +the additional function scope is required): + +@noindent +@example +() @{ + local UNDO_LIMIT_NO=$UNDO_CHANGE_NO + # Perform some form of recursive edit. +@} +@end example + +@vindex WIDGET +@item @t{WIDGET} (scalar) +The name of the widget currently being executed; read-only. + +@vindex WIDGETFUNC +@item @t{WIDGETFUNC} (scalar) +The name of the shell function that implements a widget defined with +either @t{zle -N} or @t{zle -C}. In the former case, this is the second +argument to the @t{zle -N} command that defined the widget, or +the first argument if there was no second argument. In the latter case +this is the third argument to the @t{zle -C} command that defined the +widget. Read-only. + +@vindex WIDGETSTYLE +@item @t{WIDGETSTYLE} (scalar) +Describes the implementation behind the completion widget currently being +executed; the second argument that followed @t{zle -C} when the widget was +defined. This is the name of a builtin completion widget. For widgets +defined with @t{zle -N} this is set to the empty string. Read-only. + +@vindex YANK_ACTIVE +@vindex YANK_START +@vindex YANK_END +@item @t{YANK_ACTIVE} (integer) +@itemx @t{YANK_START} (integer) +@itemx @t{YANK_END} (integer) +@t{YANK_ACTIVE} indicates whether text has just been yanked (pasted) +into the buffer. @t{YANK_START} and @t{YANK_END} give the location of +the pasted text and are in the same units as @t{CURSOR}. They are only +valid for reading when @t{YANK_ACTIVE} is non-zero. They can also be +assigned by widgets that insert text in a yank-like fashion, for example +wrappers of @t{bracketed-paste}. See also @t{zle -f}. + +@noindent +@t{YANK_ACTIVE} is read-only. + +@vindex ZLE_RECURSIVE +@item @t{ZLE_RECURSIVE} (integer) +Usually zero, but incremented inside any instance of +@t{recursive-edit}. Hence indicates the current recursion level. + +@noindent +@t{ZLE_RECURSIVE} is read-only. + +@vindex ZLE_STATE +@item @t{ZLE_STATE} (scalar) +Contains a set of space-separated words that describe the current @t{zle} +state. + +@noindent +Currently, the states shown are the insert mode as set by the +@t{overwrite-mode} or @t{vi-replace} widgets and whether history commands +will visit imported entries as controlled by the set-local-history widget. +The string contains `@t{insert}' if characters to be inserted on the +command line move existing characters to the right or `@t{overwrite}' +if characters to be inserted overwrite existing characters. It contains +`@t{localhistory}' if only local history commands will be visited or +`@t{globalhistory}' if imported history commands will also be visited. + +@noindent +The substrings are sorted in alphabetical order so that if you want to +test for two specific substrings in a future-proof way, you can do match +by doing: + +@noindent +@example +if [[ $ZLE_STATE == *globalhistory*insert* ]]; then ...; fi +@end example + +@end table + +@noindent + +@subsection Special Widgets +@noindent + +@noindent +There are a few user-defined widgets which are special to the shell. +If they do not exist, no special action is taken. The environment +provided is identical to that for any other editing widget. + +@noindent +@table @asis +@tindex zle-isearch-exit +@item @t{zle-isearch-exit} +Executed at the end of incremental search at the point where the isearch +prompt is removed from the display. See @t{zle-isearch-update} for +an example. + +@tindex zle-isearch-update +@item @t{zle-isearch-update} +Executed within incremental search when the display is about to be +redrawn. Additional output below the incremental search prompt can be +generated by using `@t{zle -M}' within the widget. For example, + +@noindent +@example +zle-isearch-update() @{ zle -M "Line $HISTNO"; @} +zle -N zle-isearch-update +@end example + +@noindent +Note the line output by `@t{zle -M}' is not deleted on exit from +incremental search. This can be done from a @t{zle-isearch-exit} +widget: + +@noindent +@example +zle-isearch-exit() @{ zle -M ""; @} +zle -N zle-isearch-exit +@end example + +@tindex zle-line-pre-redraw +@item @t{zle-line-pre-redraw} +Executed whenever the input line is about to be redrawn, providing an +opportunity to update the region_highlight array. + +@tindex zle-line-init +@item @t{zle-line-init} +Executed every time the line editor is started to read a new line +of input. The following example puts the line editor into vi command +mode when it starts up. + +@noindent +@example +zle-line-init() @{ zle -K vicmd; @} +zle -N zle-line-init +@end example + +@noindent +(The command inside the function sets the keymap directly; it is +equivalent to @t{zle vi-cmd-mode}.) + +@tindex zle-line-finish +@item @t{zle-line-finish} +This is similar to @t{zle-line-init} but is executed every time the +line editor has finished reading a line of input. + +@tindex zle-history-line-set +@item @t{zle-history-line-set} +Executed when the history line changes. + +@tindex zle-keymap-select +@item @t{zle-keymap-select} +Executed every time the keymap changes, i.e. the special parameter +@t{KEYMAP} is set to a different value, while the line editor is active. +Initialising the keymap when the line editor starts does not cause the +widget to be called. + +@noindent +The value @t{$KEYMAP} within the function reflects the new keymap. The +old keymap is passed as the sole argument. + +@noindent +This can be used for detecting switches between the vi command +(@t{vicmd}) and insert (usually @t{main}) keymaps. + +@end table + +@noindent + +@section Standard Widgets +@noindent +@cindex widgets, standard +The following is a list of all the standard widgets, +and their default bindings in emacs mode, +vi command mode and vi insert mode +(the `@t{emacs}', `@t{vicmd}' and `@t{viins}' keymaps, respectively). + +@noindent +Note that cursor keys are bound to movement keys in all three keymaps; +the shell assumes that the cursor keys send the key sequences reported +by the terminal-handling library (termcap or terminfo). The key sequences +shown in the list are those based on the VT100, common on many modern +terminals, but in fact these are not necessarily bound. In the case of the +@t{viins} keymap, the initial escape character of the sequences serves also +to return to the @t{vicmd} keymap: whether this happens is determined by +the @t{KEYTIMEOUT} parameter, see @ref{Parameters}. +@menu +* Movement:: +* History Control:: +* Modifying Text:: +* Arguments:: +* Completion:: +* Miscellaneous:: +* Text Objects:: +@end menu +@node Movement, History Control, , Zle Widgets + +@subsection Movement +@noindent +@table @asis +@tindex vi-backward-blank-word +@item @t{vi-backward-blank-word} (unbound) (@t{B}) (unbound) +Move backward one word, where a word is defined as a series of +non-blank characters. + +@tindex vi-backward-blank-word-end +@item @t{vi-backward-blank-word-end} (unbound) (@t{gE}) (unbound) +Move to the end of the previous word, where a word is defined as a +series of non-blank characters. + +@tindex backward-char +@item @t{backward-char} (@t{^B ESC-[D}) (unbound) (unbound) +Move backward one character. + +@tindex vi-backward-char +@item @t{vi-backward-char} (unbound) (@t{^H h ^?}) (@t{ESC-[D}) +Move backward one character, without changing lines. + +@tindex backward-word +@item @t{backward-word} (@t{ESC-B ESC-b}) (unbound) (unbound) +Move to the beginning of the previous word. + +@tindex emacs-backward-word +@item @t{emacs-backward-word} +Move to the beginning of the previous word. + +@tindex vi-backward-word +@item @t{vi-backward-word} (unbound) (@t{b}) (unbound) +Move to the beginning of the previous word, vi-style. + +@tindex vi-backward-word-end +@item @t{vi-backward-word-end} (unbound) (@t{ge}) (unbound) +Move to the end of the previous word, vi-style. + +@tindex beginning-of-line +@item @t{beginning-of-line} (@t{^A}) (unbound) (unbound) +Move to the beginning of the line. If already at the beginning +of the line, move to the beginning of the previous line, if any. + +@tindex vi-beginning-of-line +@item @t{vi-beginning-of-line} +Move to the beginning of the line, without changing lines. + +@tindex down-line +@item @t{down-line} (unbound) (unbound) (unbound) +Move down a line in the buffer. + +@tindex end-of-line +@item @t{end-of-line} (@t{^E}) (unbound) (unbound) +Move to the end of the line. If already at the end +of the line, move to the end of the next line, if any. + +@tindex vi-end-of-line +@item @t{vi-end-of-line} (unbound) (@t{$}) (unbound) +Move to the end of the line. +If an argument is given to this command, the cursor will be moved to +the end of the line (argument - 1) lines down. + +@tindex vi-forward-blank-word +@item @t{vi-forward-blank-word} (unbound) (@t{W}) (unbound) +Move forward one word, where a word is defined as a series of +non-blank characters. + +@tindex vi-forward-blank-word-end +@item @t{vi-forward-blank-word-end} (unbound) (@t{E}) (unbound) +Move to the end of the current word, or, if at the end of the current word, +to the end of the next word, +where a word is defined as a series of non-blank characters. + +@tindex forward-char +@item @t{forward-char} (@t{^F ESC-[C}) (unbound) (unbound) +Move forward one character. + +@tindex vi-forward-char +@item @t{vi-forward-char} (unbound) (@t{space l}) (@t{ESC-[C}) +Move forward one character. + +@tindex vi-find-next-char +@item @t{vi-find-next-char} (@t{^X^F}) (@t{f}) (unbound) +Read a character from the keyboard, and move to +the next occurrence of it in the line. + +@tindex vi-find-next-char-skip +@item @t{vi-find-next-char-skip} (unbound) (@t{t}) (unbound) +Read a character from the keyboard, and move to +the position just before the next occurrence of it in the line. + +@tindex vi-find-prev-char +@item @t{vi-find-prev-char} (unbound) (@t{F}) (unbound) +Read a character from the keyboard, and move to +the previous occurrence of it in the line. + +@tindex vi-find-prev-char-skip +@item @t{vi-find-prev-char-skip} (unbound) (@t{T}) (unbound) +Read a character from the keyboard, and move to +the position just after the previous occurrence of it in the line. + +@tindex vi-first-non-blank +@item @t{vi-first-non-blank} (unbound) (@t{^}) (unbound) +Move to the first non-blank character in the line. + +@tindex vi-forward-word +@item @t{vi-forward-word} (unbound) (@t{w}) (unbound) +Move forward one word, vi-style. + +@tindex forward-word +@item @t{forward-word} (@t{ESC-F ESC-f}) (unbound) (unbound) +Move to the beginning of the next word. +The editor's idea of a word is specified with the @t{WORDCHARS} +parameter. + +@tindex emacs-forward-word +@item @t{emacs-forward-word} +Move to the end of the next word. + +@tindex vi-forward-word-end +@item @t{vi-forward-word-end} (unbound) (@t{e}) (unbound) +Move to the end of the next word. + +@tindex vi-goto-column +@item @t{vi-goto-column} (@t{ESC-|}) (@t{|}) (unbound) +Move to the column specified by the numeric argument. + +@tindex vi-goto-mark +@item @t{vi-goto-mark} (unbound) (@t{`}) (unbound) +Move to the specified mark. + +@tindex vi-goto-mark-line +@item @t{vi-goto-mark-line} (unbound) (@t{'}) (unbound) +Move to beginning of the line containing the specified mark. + +@tindex vi-repeat-find +@item @t{vi-repeat-find} (unbound) (@t{;}) (unbound) +Repeat the last @t{vi-find} command. + +@tindex vi-rev-repeat-find +@item @t{vi-rev-repeat-find} (unbound) (@t{,}) (unbound) +Repeat the last @t{vi-find} command in the opposite direction. + +@tindex up-line +@item @t{up-line} (unbound) (unbound) (unbound) +Move up a line in the buffer. + +@end table +@node History Control, Modifying Text, Movement, Zle Widgets + +@subsection History Control +@noindent +@table @asis +@tindex beginning-of-buffer-or-history +@item @t{beginning-of-buffer-or-history} (@t{ESC-<}) (@t{gg}) (unbound) +Move to the beginning of the buffer, or if already there, +move to the first event in the history list. + +@tindex beginning-of-line-hist +@item @t{beginning-of-line-hist} +Move to the beginning of the line. If already at the +beginning of the buffer, move to the previous history line. + +@tindex beginning-of-history +@item @t{beginning-of-history} +Move to the first event in the history list. + +@tindex down-line-or-history +@item @t{down-line-or-history} (@t{^N ESC-[B}) (@t{j}) (@t{ESC-[B}) +Move down a line in the buffer, or if already at the bottom line, +move to the next event in the history list. + +@tindex vi-down-line-or-history +@item @t{vi-down-line-or-history} (unbound) (@t{+}) (unbound) +Move down a line in the buffer, or if already at the bottom line, +move to the next event in the history list. +Then move to the first non-blank character on the line. + +@tindex down-line-or-search +@item @t{down-line-or-search} +Move down a line in the buffer, or if already at the bottom line, +search forward in the history for a line beginning with the first +word in the buffer. + +@noindent +If called from a function by the @t{zle} command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer. + +@tindex down-history +@item @t{down-history} (unbound) (@t{^N}) (unbound) +Move to the next event in the history list. + +@tindex history-beginning-search-backward +@item @t{history-beginning-search-backward} +Search backward in the history for a line beginning with the current +line up to the cursor. +This leaves the cursor in its original position. + +@tindex end-of-buffer-or-history +@item @t{end-of-buffer-or-history} (@t{ESC->}) (unbound) (unbound) +Move to the end of the buffer, or if already there, +move to the last event in the history list. + +@tindex end-of-line-hist +@item @t{end-of-line-hist} +Move to the end of the line. If already at the end of +the buffer, move to the next history line. + +@tindex end-of-history +@item @t{end-of-history} +Move to the last event in the history list. + +@tindex vi-fetch-history +@item @t{vi-fetch-history} (unbound) (@t{G}) (unbound) +Fetch the history line specified by the numeric argument. +This defaults to the current history line +(i.e. the one that isn't history yet). + +@tindex history-incremental-search-backward +@item @t{history-incremental-search-backward} (@t{^R ^Xr}) (unbound) (unbound) +Search backward incrementally for a specified string. The search is +case-insensitive if the search string does not have uppercase letters and no +numeric argument was given. The string may begin with `@t{^}' to anchor the +search to the beginning of the line. When called from a user-defined +function returns the following statuses: 0, if the search succeeded; +1, if the search failed; 2, if the search term was a bad pattern; +3, if the search was aborted by the @t{send-break} command. + +@noindent +A restricted set of editing functions +is available in the mini-buffer. Keys are looked up in the special +@t{isearch} keymap, and if not found there in the main keymap (note +that by default the @t{isearch} keymap is empty). +An interrupt signal, as defined by the stty +setting, will stop the search and go back to the original line. An undefined +key will have the same effect. Note that the following always +perform the same task within incremental searches and cannot be +replaced by user defined widgets, nor can the set of functions +be extended. The supported functions are: + +@noindent +@table @asis +@item @t{accept-and-hold} +@itemx @t{accept-and-infer-next-history} +@itemx @t{accept-line} +@itemx @t{accept-line-and-down-history} +Perform the usual function after exiting incremental search. +The command line displayed is executed. + +@item @t{backward-delete-char} +@itemx @t{vi-backward-delete-char} +Back up one place in the search history. If the search has been +repeated this does not immediately erase a character in the +minibuffer. + +@item @t{accept-search} +Exit incremental search, retaining the command line but performing no +further action. Note that this function is not bound by default +and has no effect outside incremental search. + +@item @t{backward-delete-word} +@itemx @t{backward-kill-word} +@itemx @t{vi-backward-kill-word} +Back up one character in the minibuffer; if multiple searches +have been performed since the character was inserted the search +history is rewound to the point just before the character was +entered. Hence this has the effect of repeating +@t{backward-delete-char}. + +@item @t{clear-screen} +Clear the screen, remaining in incremental search mode. + +@item @t{history-incremental-search-backward} +Find the next occurrence of the contents of the mini-buffer. If the +mini-buffer is empty, the most recent previously used search string is +reinstated. + +@item @t{history-incremental-search-forward} +Invert the sense of the search. + +@item @t{magic-space} +Inserts a non-magical space. + +@item @t{quoted-insert} +@itemx @t{vi-quoted-insert} +Quote the character to insert into the minibuffer. + +@item @t{redisplay} +Redisplay the command line, remaining in incremental search mode. + +@item @t{vi-cmd-mode} +Select the `@t{vicmd}' keymap; +the `@t{main}' keymap (insert mode) will be selected initially. + +@noindent +In addition, the modifications that were made while in vi insert mode are +merged to form a single undo event. + +@item @t{vi-repeat-search} +@itemx @t{vi-rev-repeat-search} +Repeat the search. The direction of the search is indicated in the +mini-buffer. + +@end table + +@noindent +Any character that is not bound to one of the above functions, or +@t{self-insert} or @t{self-insert-unmeta}, will cause the mode to be +exited. The character is then looked up and executed in the keymap in +effect at that point. + +@noindent +When called from a widget function by the @t{zle} command, the incremental +search commands can take a string argument. This will be treated as a +string of keys, as for arguments to the @t{bindkey} command, and used as +initial input for the command. Any characters in the string which are +unused by the incremental search will be silently ignored. For example, + +@noindent +@example +zle history-incremental-search-backward forceps +@end example + +@noindent +will search backwards for @t{forceps}, leaving the minibuffer containing +the string `@t{forceps}'. + +@tindex history-incremental-search-forward +@item @t{history-incremental-search-forward} (@t{^S ^Xs}) (unbound) (unbound) +Search forward incrementally for a specified string. The search is +case-insensitive if the search string does not have uppercase letters and no +numeric argument was given. The string may begin with `@t{^}' to anchor the +search to the beginning of the line. The functions available in the +mini-buffer are the same as for @t{history-incremental-search-backward}. + +@tindex history-incremental-pattern-search-backward +@tindex history-incremental-pattern-search-forward +@item @t{history-incremental-pattern-search-backward} +@itemx @t{history-incremental-pattern-search-forward} +These widgets behave similarly to the corresponding widgets with +no @t{-pattern}, but the search string typed by the user is treated +as a pattern, respecting the current settings of the various options +affecting pattern matching. See +@ref{Filename Generation} for a description of patterns. +If no numeric argument was given lowercase letters in the search +string may match uppercase letters in the history. The string may begin +with `@t{^}' to anchor the search to the beginning of the line. + +@noindent +The prompt changes to indicate an invalid pattern; this may simply +indicate the pattern is not yet complete. + +@noindent +Note that only non-overlapping matches are reported, so an expression +with wildcards may return fewer matches on a line than are visible +by inspection. + +@tindex history-search-backward +@item @t{history-search-backward} (@t{ESC-P ESC-p}) (unbound) (unbound) +Search backward in the history for a line beginning with the first +word in the buffer. + +@noindent +If called from a function by the @t{zle} command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer. + +@tindex vi-history-search-backward +@item @t{vi-history-search-backward} (unbound) (@t{/}) (unbound) +Search backward in the history for a specified string. +The string may begin with `@t{^}' to anchor the search to the +beginning of the line. + +@noindent +A restricted set of editing functions is available in +the mini-buffer. An interrupt signal, as defined by the stty setting, will +stop the search. +The functions available in the mini-buffer are: +@t{accept-line}, +@t{backward-delete-char}, +@t{vi-backward-delete-char}, +@t{backward-kill-word}, +@t{vi-backward-kill-word}, +@t{clear-screen}, +@t{redisplay}, +@t{quoted-insert} +and +@t{vi-quoted-insert}. + +@noindent +@t{vi-cmd-mode} is treated the same as accept-line, and +@t{magic-space} is treated as a space. +Any other character that is not bound to self-insert or +self-insert-unmeta will beep and be ignored. If the function is called from vi +command mode, the bindings of the current insert mode will be used. + +@noindent +If called from a function by the @t{zle} command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer. + +@tindex history-search-forward +@item @t{history-search-forward} (@t{ESC-N ESC-n}) (unbound) (unbound) +Search forward in the history for a line beginning with the first +word in the buffer. + +@noindent +If called from a function by the @t{zle} command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer. + +@tindex vi-history-search-forward +@item @t{vi-history-search-forward} (unbound) (@t{?}) (unbound) +Search forward in the history for a specified string. +The string may begin with `@t{^}' to anchor the search to the +beginning of the line. The functions available in the mini-buffer are the same +as for @t{vi-history-search-backward}. Argument handling is also the same +as for that command. + +@tindex infer-next-history +@item @t{infer-next-history} (@t{^X^N}) (unbound) (unbound) +Search in the history list for a line matching the current one and +fetch the event following it. + +@tindex insert-last-word +@item @t{insert-last-word} (@t{ESC-_ ESC-.}) (unbound) (unbound) +Insert the last word from the previous history event at the +cursor position. If a positive numeric argument is given, +insert that word from the end of the previous history event. +If the argument is zero or negative insert that word from the +left (zero inserts the previous command word). Repeating this command +replaces the word just inserted with the last word from the +history event prior to the one just used; numeric arguments can be used in +the same way to pick a word from that event. + +@noindent +When called from a shell function invoked from a user-defined widget, the +command can take one to three arguments. The first argument specifies a +history offset which applies to successive calls to this widget: if it is -1, +the default behaviour is used, while if it is 1, successive calls will move +forwards through the history. The value 0 can be used to indicate that the +history line examined by the previous execution of the command will be +reexamined. Note that negative numbers should be preceded by a +`@t{-}@t{-}' argument to avoid confusing them with options. + +@noindent +If two arguments are given, the second specifies the word on the command +line in normal array index notation (as a more natural alternative to the +numeric argument). Hence 1 is the first word, and -1 (the default) is the +last word. + +@noindent +If a third argument is given, its value is ignored, but it is used to +signify that the history offset is relative to the current history line, +rather than the one remembered after the previous invocations of +@t{insert-last-word}. + +@noindent +For example, the default behaviour of the command corresponds to + +@noindent +@example +zle insert-last-word -- -1 -1 +@end example + +@noindent +while the command + +@noindent +@example +zle insert-last-word -- -1 1 - +@end example + +@noindent +always copies the first word of the line in the history immediately before +the line being edited. This has the side effect that later invocations of +the widget will be relative to that line. + +@tindex vi-repeat-search +@item @t{vi-repeat-search} (unbound) (@t{n}) (unbound) +Repeat the last vi history search. + +@tindex vi-rev-repeat-search +@item @t{vi-rev-repeat-search} (unbound) (@t{N}) (unbound) +Repeat the last vi history search, but in reverse. + +@tindex up-line-or-history +@item @t{up-line-or-history} (@t{^P ESC-[A}) (@t{k}) (@t{ESC-[A}) +Move up a line in the buffer, or if already at the top line, +move to the previous event in the history list. + +@tindex vi-up-line-or-history +@item @t{vi-up-line-or-history} (unbound) (@t{-}) (unbound) +Move up a line in the buffer, or if already at the top line, +move to the previous event in the history list. +Then move to the first non-blank character on the line. + +@tindex up-line-or-search +@item @t{up-line-or-search} +Move up a line in the buffer, or if already at the top line, +search backward in the history for a line beginning with the +first word in the buffer. + +@noindent +If called from a function by the @t{zle} command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer. + +@tindex up-history +@item @t{up-history} (unbound) (@t{^P}) (unbound) +Move to the previous event in the history list. + +@tindex history-beginning-search-forward +@item @t{history-beginning-search-forward} +Search forward in the history for a line beginning with the current +line up to the cursor. +This leaves the cursor in its original position. + +@tindex set-local-history +@item @t{set-local-history} +By default, history movement commands visit the imported lines as well as +the local lines. This widget lets you toggle this on and off, or set it with +the numeric argument. Zero for both local and imported lines and nonzero for +only local lines. + +@end table +@node Modifying Text, Arguments, History Control, Zle Widgets + +@subsection Modifying Text +@noindent +@table @asis +@tindex vi-add-eol +@item @t{vi-add-eol} (unbound) (@t{A}) (unbound) +Move to the end of the line and enter insert mode. + +@tindex vi-add-next +@item @t{vi-add-next} (unbound) (@t{a}) (unbound) +Enter insert mode after the current cursor position, without changing lines. + +@tindex backward-delete-char +@item @t{backward-delete-char} (@t{^H ^?}) (unbound) (unbound) +Delete the character behind the cursor. + +@tindex vi-backward-delete-char +@item @t{vi-backward-delete-char} (unbound) (@t{X}) (@t{^H}) +Delete the character behind the cursor, without changing lines. +If in insert mode, this won't delete past the point where insert mode was +last entered. + +@tindex backward-delete-word +@item @t{backward-delete-word} +Delete the word behind the cursor. + +@tindex backward-kill-line +@item @t{backward-kill-line} +Kill from the beginning of the line to the cursor position. + +@tindex backward-kill-word +@item @t{backward-kill-word} (@t{^W ESC-^H ESC-^?}) (unbound) (unbound) +Kill the word behind the cursor. + +@tindex vi-backward-kill-word +@item @t{vi-backward-kill-word} (unbound) (unbound) (@t{^W}) +Kill the word behind the cursor, without going past the point where insert +mode was last entered. + +@tindex capitalize-word +@item @t{capitalize-word} (@t{ESC-C ESC-c}) (unbound) (unbound) +Capitalize the current word and move past it. + +@tindex vi-change +@item @t{vi-change} (unbound) (@t{c}) (unbound) +Read a movement command from the keyboard, and kill +from the cursor position to the endpoint of the movement. +Then enter insert mode. +If the command is @t{vi-change}, change the current line. + +@noindent +For compatibility with vi, if the command is @t{vi-forward-word} +or @t{vi-forward-blank-word}, the whitespace after the word is not +included. If you prefer the more consistent behaviour with the +whitespace included use the following key binding: + +@noindent +@example +bindkey -a -s cw dwi +@end example + +@tindex vi-change-eol +@item @t{vi-change-eol} (unbound) (@t{C}) (unbound) +Kill to the end of the line and enter insert mode. + +@tindex vi-change-whole-line +@item @t{vi-change-whole-line} (unbound) (@t{S}) (unbound) +Kill the current line and enter insert mode. + +@tindex copy-region-as-kill +@item @t{copy-region-as-kill} (@t{ESC-W ESC-w}) (unbound) (unbound) +Copy the area from the cursor to the mark to the kill buffer. + +@noindent +If called from a ZLE widget function in the form `@t{zle +copy-region-as-kill} @var{string}' then @var{string} will be taken as the +text to copy to the kill buffer. The cursor, the mark and the text on the +command line are not used in this case. + +@tindex copy-prev-word +@item @t{copy-prev-word} (@t{ESC-^_}) (unbound) (unbound) +Duplicate the word to the left of the cursor. + +@tindex copy-prev-shell-word +@item @t{copy-prev-shell-word} +Like @t{copy-prev-word}, but the word is found by using shell parsing, +whereas @t{copy-prev-word} looks for blanks. This makes a difference +when the word is quoted and contains spaces. + +@tindex vi-delete +@item @t{vi-delete} (unbound) (@t{d}) (unbound) +Read a movement command from the keyboard, and kill +from the cursor position to the endpoint of the movement. +If the command is @t{vi-delete}, kill the current line. + +@tindex delete-char +@item @t{delete-char} +Delete the character under the cursor. + +@tindex vi-delete-char +@item @t{vi-delete-char} (unbound) (@t{x}) (unbound) +Delete the character under the cursor, +without going past the end of the line. + +@tindex delete-word +@item @t{delete-word} +Delete the current word. + +@tindex down-case-word +@item @t{down-case-word} (@t{ESC-L ESC-l}) (unbound) (unbound) +Convert the current word to all lowercase and move past it. + +@tindex vi-down-case +@item @t{vi-down-case} (unbound) (@t{gu}) (unbound) +Read a movement command from the keyboard, and convert all characters +from the cursor position to the endpoint of the movement to lowercase. +If the movement command is @t{vi-down-case}, swap the case of all +characters on the current line. + +@tindex kill-word +@item @t{kill-word} (@t{ESC-D ESC-d}) (unbound) (unbound) +Kill the current word. + +@tindex gosmacs-transpose-chars +@item @t{gosmacs-transpose-chars} +Exchange the two characters behind the cursor. + +@tindex vi-indent +@item @t{vi-indent} (unbound) (@t{>}) (unbound) +Indent a number of lines. + +@tindex vi-insert +@item @t{vi-insert} (unbound) (@t{i}) (unbound) +Enter insert mode. + +@tindex vi-insert-bol +@item @t{vi-insert-bol} (unbound) (@t{I}) (unbound) +Move to the first non-blank character on the line and enter insert mode. + +@tindex vi-join +@item @t{vi-join} (@t{^X^J}) (@t{J}) (unbound) +Join the current line with the next one. + +@tindex kill-line +@item @t{kill-line} (@t{^K}) (unbound) (unbound) +Kill from the cursor to the end of the line. +If already on the end of the line, kill the newline character. + +@tindex vi-kill-line +@item @t{vi-kill-line} (unbound) (unbound) (@t{^U}) +Kill from the cursor back to wherever insert mode was last entered. + +@tindex vi-kill-eol +@item @t{vi-kill-eol} (unbound) (@t{D}) (unbound) +Kill from the cursor to the end of the line. + +@tindex kill-region +@item @t{kill-region} +Kill from the cursor to the mark. + +@tindex kill-buffer +@item @t{kill-buffer} (@t{^X^K}) (unbound) (unbound) +Kill the entire buffer. + +@tindex kill-whole-line +@item @t{kill-whole-line} (@t{^U}) (unbound) (unbound) +Kill the current line. + +@tindex vi-match-bracket +@item @t{vi-match-bracket} (@t{^X^B}) (@t{%}) (unbound) +Move to the bracket character (one of @t{@{@}}, @t{()} or @t{[]}) that +matches the one under the cursor. +If the cursor is not on a bracket character, move forward without going +past the end of the line to find one, and then go to the matching bracket. + +@tindex vi-open-line-above +@item @t{vi-open-line-above} (unbound) (@t{O}) (unbound) +Open a line above the cursor and enter insert mode. + +@tindex vi-open-line-below +@item @t{vi-open-line-below} (unbound) (@t{o}) (unbound) +Open a line below the cursor and enter insert mode. + +@tindex vi-oper-swap-case +@item @t{vi-oper-swap-case} (unbound) (@t{g~}) (unbound) +Read a movement command from the keyboard, and swap +the case of all characters +from the cursor position to the endpoint of the movement. +If the movement command is @t{vi-oper-swap-case}, +swap the case of all characters on the current line. + +@tindex overwrite-mode +@item @t{overwrite-mode} (@t{^X^O}) (unbound) (unbound) +Toggle between overwrite mode and insert mode. + +@tindex vi-put-before +@item @t{vi-put-before} (unbound) (@t{P}) (unbound) +Insert the contents of the kill buffer before the cursor. +If the kill buffer contains a sequence of lines (as opposed to characters), +paste it above the current line. + +@tindex vi-put-after +@item @t{vi-put-after} (unbound) (@t{p}) (unbound) +Insert the contents of the kill buffer after the cursor. +If the kill buffer contains a sequence of lines (as opposed to characters), +paste it below the current line. + +@tindex put-replace-selection +@item @t{put-replace-selection} (unbound) (unbound) (unbound) +Replace the contents of the current region or selection with the +contents of the kill buffer. If the kill buffer contains a sequence of +lines (as opposed to characters), the current line will be split by the +pasted lines. + +@tindex quoted-insert +@item @t{quoted-insert} (@t{^V}) (unbound) (unbound) +Insert the next character typed into the buffer literally. +An interrupt character will not be inserted. + +@tindex vi-quoted-insert +@item @t{vi-quoted-insert} (unbound) (unbound) (@t{^Q ^V}) +Display a `@t{^}' at the cursor position, and +insert the next character typed into the buffer literally. +An interrupt character will not be inserted. + +@tindex quote-line +@item @t{quote-line} (@t{ESC-'}) (unbound) (unbound) +Quote the current line; that is, put a `@t{'}' character at the +beginning and the end, and convert all `@t{'}' characters +to `@t{'\@value{dsq}}'. + +@tindex quote-region +@item @t{quote-region} (@t{ESC-"}) (unbound) (unbound) +Quote the region from the cursor to the mark. + +@tindex vi-replace +@item @t{vi-replace} (unbound) (@t{R}) (unbound) +Enter overwrite mode. + +@tindex vi-repeat-change +@item @t{vi-repeat-change} (unbound) (@t{.}) (unbound) +Repeat the last vi mode text modification. +If a count was used with the modification, it is remembered. +If a count is given to this command, it overrides the remembered count, +and is remembered for future uses of this command. +The cut buffer specification is similarly remembered. + +@tindex vi-replace-chars +@item @t{vi-replace-chars} (unbound) (@t{r}) (unbound) +Replace the character under the cursor with a character +read from the keyboard. + +@tindex self-insert +@item @t{self-insert} (printable characters) (unbound) (printable characters and some control characters) +Insert a character into the buffer at the cursor position. + +@tindex self-insert-unmeta +@item @t{self-insert-unmeta} (@t{ESC-^I ESC-^J ESC-^M}) (unbound) (unbound) +Insert a character into the buffer after stripping the meta bit +and converting ^M to ^J. + +@tindex vi-substitute +@item @t{vi-substitute} (unbound) (@t{s}) (unbound) +Substitute the next character(s). + +@tindex vi-swap-case +@item @t{vi-swap-case} (unbound) (@t{~}) (unbound) +Swap the case of the character under the cursor and move past it. + +@tindex transpose-chars +@item @t{transpose-chars} (@t{^T}) (unbound) (unbound) +Exchange the two characters to the left of the +cursor if at end of line, else exchange the +character under the cursor with the character +to the left. + +@tindex transpose-words +@item @t{transpose-words} (@t{ESC-T ESC-t}) (unbound) (unbound) +Exchange the current word with the one before it. + +@noindent +With a positive numeric argument @emph{N}, the word around the cursor, or +following it if the cursor is between words, is transposed with the +preceding @emph{N} words. The cursor is put at the end of the resulting +group of words. + +@noindent +With a negative numeric argument @emph{-N}, the effect is the same as using +a positive argument @emph{N} except that the original cursor position is +retained, regardless of how the words are rearranged. + +@tindex vi-unindent +@item @t{vi-unindent} (unbound) (@t{<}) (unbound) +Unindent a number of lines. + +@tindex vi-up-case +@item @t{vi-up-case} (unbound) (@t{gU}) (unbound) +Read a movement command from the keyboard, and convert all characters +from the cursor position to the endpoint of the movement to lowercase. +If the movement command is @t{vi-up-case}, swap the case of all +characters on the current line. + +@tindex up-case-word +@item @t{up-case-word} (@t{ESC-U ESC-u}) (unbound) (unbound) +Convert the current word to all caps and move past it. + +@tindex yank +@item @t{yank} (@t{^Y}) (unbound) (unbound) +Insert the contents of the kill buffer at the cursor position. + +@tindex yank-pop +@item @t{yank-pop} (@t{ESC-y}) (unbound) (unbound) +Remove the text just yanked, rotate the kill-ring (the history of +previously killed text) and yank the new top. Only works following +@t{yank}, @t{vi-put-before}, @t{vi-put-after} or @t{yank-pop}. + +@tindex vi-yank +@item @t{vi-yank} (unbound) (@t{y}) (unbound) +Read a movement command from the keyboard, and copy the region +from the cursor position to the endpoint of the movement +into the kill buffer. +If the command is @t{vi-yank}, copy the current line. + +@tindex vi-yank-whole-line +@item @t{vi-yank-whole-line} (unbound) (@t{Y}) (unbound) +Copy the current line into the kill buffer. + +@tindex vi-yank-eol +@item @t{vi-yank-eol} +Copy the region from the cursor position to the end of the line +into the kill buffer. +Arguably, this is what Y should do in vi, but it isn't what it actually does. + +@end table +@node Arguments, Completion, Modifying Text, Zle Widgets + +@subsection Arguments +@noindent +@table @asis +@tindex digit-argument +@item @t{digit-argument} (@t{ESC-0}..@t{ESC-9}) (@t{1}-@t{9}) (unbound) +Start a new numeric argument, or add to the current one. +See also @t{vi-digit-or-beginning-of-line}. This only works if bound to a +key sequence ending in a decimal digit. + +@noindent +Inside a widget function, a call to this function treats the last key of +the key sequence which called the widget as the digit. + +@tindex neg-argument +@item @t{neg-argument} (@t{ESC-}@t{-}) (unbound) (unbound) +Changes the sign of the following argument. + +@tindex universal-argument +@item @t{universal-argument} +Multiply the argument of the next command by 4. Alternatively, if +this command is followed by an integer (positive or negative), use +that as the argument for the next command. Thus digits cannot be +repeated using this command. For example, if this command occurs +twice, followed immediately by @t{forward-char}, move forward sixteen +spaces; if instead it is followed by @t{-2}, then @t{forward-char}, +move backward two spaces. + +@noindent +Inside a widget function, if passed an argument, i.e. `@t{zle +universal-argument} @var{num}', the numeric argument will be set to +@var{num}; this is equivalent to `@t{NUMERIC=}@var{num}'. + +@tindex argument-base +@item @t{argument-base} +Use the existing numeric argument as a numeric base, which must be in the +range 2 to 36 inclusive. Subsequent use of @t{digit-argument} and +@t{universal-argument} will input a new numeric argument in the given base. +The usual hexadecimal convention is used: the letter @t{a} or @t{A} +corresponds to 10, and so on. Arguments in bases requiring digits from 10 +upwards are more conveniently input with @t{universal-argument}, since +@t{ESC-a} etc. are not usually bound to @t{digit-argument}. + +@noindent +The function can be used with a command argument inside a user-defined +widget. The following code sets the base to 16 and lets the user input a +hexadecimal argument until a key out of the digit range is typed: + +@noindent +@example +zle argument-base 16 +zle universal-argument +@end example + +@end table +@node Completion, Miscellaneous, Arguments, Zle Widgets + +@subsection Completion +@noindent +@table @asis +@tindex accept-and-menu-complete +@item @t{accept-and-menu-complete} +In a menu completion, insert the current completion into the buffer, +and advance to the next possible completion. + +@tindex complete-word +@item @t{complete-word} +Attempt completion on the current word. + +@tindex delete-char-or-list +@item @t{delete-char-or-list} (@t{^D}) (unbound) (unbound) +Delete the character under the cursor. If the cursor +is at the end of the line, list possible completions for the +current word. + +@tindex expand-cmd-path +@item @t{expand-cmd-path} +Expand the current command to its full pathname. + +@tindex expand-or-complete +@item @t{expand-or-complete} (@t{TAB}) (unbound) (@t{TAB}) +Attempt shell expansion on the current word. +If that fails, +attempt completion. + +@tindex expand-or-complete-prefix +@item @t{expand-or-complete-prefix} +Attempt shell expansion on the current word up to cursor. + +@tindex expand-history +@item @t{expand-history} (@t{ESC-space ESC-!}) (unbound) (unbound) +Perform history expansion on the edit buffer. + +@tindex expand-word +@item @t{expand-word} (@t{^X*}) (unbound) (unbound) +Attempt shell expansion on the current word. + +@tindex list-choices +@item @t{list-choices} (@t{ESC-^D}) (@t{^D =}) (@t{^D}) +List possible completions for the current word. + +@tindex list-expand +@item @t{list-expand} (@t{^Xg ^XG}) (@t{^G}) (@t{^G}) +List the expansion of the current word. + +@tindex magic-space +@item @t{magic-space} +Perform history expansion and insert a space into the +buffer. This is intended to be bound to space. + +@tindex menu-complete +@pindex MENU_COMPLETE, use of +@item @t{menu-complete} +Like @t{complete-word}, except that menu completion is used. +See the @t{MENU_COMPLETE} option. + +@tindex menu-expand-or-complete +@item @t{menu-expand-or-complete} +Like @t{expand-or-complete}, except that menu completion is used. + +@tindex reverse-menu-complete +@item @t{reverse-menu-complete} +Perform menu completion, like @t{menu-complete}, except that if +a menu completion is already in progress, move to the @emph{previous} +completion rather than the next. + +@tindex end-of-list +@item @t{end-of-list} +When a previous completion displayed a list below the prompt, this +widget can be used to move the prompt below the list. + +@end table +@node Miscellaneous, Text Objects, Completion, Zle Widgets + +@subsection Miscellaneous +@noindent +@table @asis +@tindex accept-and-hold +@item @t{accept-and-hold} (@t{ESC-A ESC-a}) (unbound) (unbound) +Push the contents of the buffer on the buffer stack +and execute it. + +@tindex accept-and-infer-next-history +@item @t{accept-and-infer-next-history} +Execute the contents of the buffer. +Then search the history list for a line matching the current one +and push the event following onto the buffer stack. + +@tindex accept-line +@item @t{accept-line} (@t{^J ^M}) (@t{^J ^M}) (@t{^J ^M}) +Finish editing the buffer. Normally this causes the buffer to be +executed as a shell command. + +@tindex accept-line-and-down-history +@item @t{accept-line-and-down-history} (@t{^O}) (unbound) (unbound) +Execute the current line, and push the next history +event on the buffer stack. + +@tindex auto-suffix-remove +@item @t{auto-suffix-remove} +If the previous action added a suffix (space, slash, etc.) to the word on +the command line, remove it. Otherwise do nothing. Removing the suffix +ends any active menu completion or menu selection. + +@noindent +This widget is intended to be called from user-defined widgets to enforce +a desired suffix-removal behavior. + +@tindex auto-suffix-retain +@item @t{auto-suffix-retain} +If the previous action added a suffix (space, slash, etc.) to the word on +the command line, force it to be preserved. Otherwise do nothing. +Retaining the suffix ends any active menu completion or menu selection. + +@noindent +This widget is intended to be called from user-defined widgets to enforce +a desired suffix-preservation behavior. + +@tindex beep +@item @t{beep} +Beep, unless the @t{BEEP} option is unset. + +@tindex bracketed-paste +@item @t{bracketed-paste} +This widget is invoked when text is pasted to the terminal emulator. It +is not intended to be bound to actual keys but instead to the special +sequence generated by the terminal emulator when text is pasted. + +@noindent +When invoked interactively, the pasted text is inserted to the buffer +and placed in the cutbuffer. +If a numeric argument is given, shell quoting will be applied to the +pasted text before it is inserted. + +@noindent +When a named buffer is specified with @t{vi-set-buffer} (@t{"x}), +the pasted text is stored in that named buffer but not inserted. + +@noindent +When called from a widget function as `@t{bracketed-paste} @var{name}`, the +pasted text is assigned to the variable @var{name} and no other processing is +done. + +@noindent +See also the @t{zle_bracketed_paste} parameter. + +@tindex vi-cmd-mode +@item @t{vi-cmd-mode} (@t{^X^V}) (unbound) (@t{^[}) +Enter command mode; that is, select the `@t{vicmd}' keymap. +Yes, this is bound by default in emacs mode. + +@tindex vi-caps-lock-panic +@item @t{vi-caps-lock-panic} +Hang until any lowercase key is pressed. +This is for vi users without the mental capacity to keep +track of their caps lock key (like the author). + +@tindex clear-screen +@item @t{clear-screen} (@t{^L ESC-^L}) (@t{^L}) (@t{^L}) +Clear the screen and redraw the prompt. + +@tindex deactivate-region +@item @t{deactivate-region} +Make the current region inactive. This disables vim-style visual +selection mode if it is active. + +@tindex describe-key-briefly +@item @t{describe-key-briefly} +Reads a key sequence, then prints the function bound to that sequence. + +@tindex exchange-point-and-mark +@item @t{exchange-point-and-mark} (@t{^X^X}) (unbound) (unbound) +Exchange the cursor position (point) with the position of the mark. +Unless a negative numeric argument is given, the region between +point and mark is activated so that it can be highlighted. +If a zero numeric argument is given, the region is activated but +point and mark are not swapped. + +@tindex execute-named-cmd +@item @t{execute-named-cmd} (@t{ESC-x}) (@t{:}) (unbound) +Read the name of an editor command and execute it. Aliasing this +widget with `@t{zle -A}' or replacing it with `@t{zle -N}' has no +effect when interpreting key bindings, but `@t{zle execute-named-cmd}' +will invoke such an alias or replacement. + +@noindent +A restricted set of editing functions is available in the +mini-buffer. Keys are looked up in the special +@t{command} keymap, and if not found there in the main keymap. +An interrupt signal, as defined by the stty setting, will +abort the function. Note that the following always +perform the same task within the @t{executed-named-cmd} environment and +cannot be replaced by user defined widgets, nor can the set of functions +be extended. The allowed functions are: +@t{backward-delete-char}, +@t{vi-backward-delete-char}, +@t{clear-screen}, +@t{redisplay}, +@t{quoted-insert}, +@t{vi-quoted-insert}, +@t{backward-kill-word}, +@t{vi-backward-kill-word}, +@t{kill-whole-line}, +@t{vi-kill-line}, +@t{backward-kill-line}, +@t{list-choices}, +@t{delete-char-or-list}, +@t{complete-word}, +@t{accept-line}, +@t{expand-or-complete} and +@t{expand-or-complete-prefix}. + +@noindent +@t{kill-region} kills the last word, +and vi-cmd-mode is treated the same as accept-line. +The space and tab characters, if not bound to one of +these functions, will complete the name and then list the +possibilities if the @t{AUTO_LIST} option is set. +Any other character that is not bound to @t{self-insert} or +@t{self-insert-unmeta} will beep and be ignored. +The bindings of the current insert mode will be used. + +@noindent +Currently this command may not be redefined or called by name. + +@tindex execute-last-named-cmd +@item @t{execute-last-named-cmd} (@t{ESC-z}) (unbound) (unbound) +Redo the last function executed with @t{execute-named-cmd}. + +@noindent +Like @t{execute-named-cmd}, this command may not be redefined, +but it may be called by name. + +@tindex get-line +@item @t{get-line} (@t{ESC-G ESC-g}) (unbound) (unbound) +Pop the top line off the buffer stack and insert it at the +cursor position. + +@tindex pound-insert +@item @t{pound-insert} (unbound) (@t{#}) (unbound) +If there is no # character at the beginning of the buffer, +add one to the beginning of each line. +If there is one, remove a # from each line that has one. +In either case, accept the current line. +The @t{INTERACTIVE_COMMENTS} option must be set +for this to have any usefulness. + +@tindex vi-pound-insert +@item @t{vi-pound-insert} +If there is no # character at the beginning of the current line, +add one. If there is one, remove it. +The @t{INTERACTIVE_COMMENTS} option must be set +for this to have any usefulness. + +@tindex push-input +@item @t{push-input} +Push the entire current multiline construct onto the buffer stack and +return to the top-level (@t{PS1}) prompt. +If the current parser construct is only a single line, this is exactly +like @t{push-line}. +Next time the editor starts up or is popped with @t{get-line}, the +construct will be popped off the top of the buffer stack and loaded +into the editing buffer. + +@tindex push-line +@item @t{push-line} (@t{^Q ESC-Q ESC-q}) (unbound) (unbound) +Push the current buffer onto the buffer stack and clear +the buffer. +Next time the editor starts up, the buffer will be popped +off the top of the buffer stack and loaded into the editing +buffer. + +@tindex push-line-or-edit +@item @t{push-line-or-edit} +At the top-level (@t{PS1}) prompt, equivalent to @t{push-line}. +At a secondary (@t{PS2}) prompt, move the entire current multiline +construct into the editor buffer. +The latter is equivalent to @t{push-input} followed by @t{get-line}. + +@tindex read-command +@item @t{read-command} +Only useful from a user-defined widget. A keystroke is read just as in +normal operation, but instead of the command being executed the name +of the command that would be executed is stored in the shell parameter +@t{REPLY}. This can be used as the argument of a future @t{zle} +command. If the key sequence is not bound, status 1 is returned; +typically, however, @t{REPLY} is set to @t{undefined-key} to indicate +a useless key sequence. + +@tindex recursive-edit +@item @t{recursive-edit} +Only useful from a user-defined widget. At this point in the function, +the editor regains control until one of the standard widgets which would +normally cause zle to exit (typically an @t{accept-line} caused by +hitting the return key) is executed. Instead, control returns to the +user-defined widget. The status returned is non-zero if the return was +caused by an error, but the function still continues executing and hence +may tidy up. This makes it safe for the user-defined widget to alter +the command line or key bindings temporarily. + +@noindent +The following widget, @t{caps-lock}, serves as an example. + +@noindent +@example +self-insert-ucase() @{ + LBUFFER+=$@{(U)KEYS[-1]@} +@} + +integer stat + +zle -N self-insert self-insert-ucase +zle -A caps-lock save-caps-lock +zle -A accept-line caps-lock + +zle recursive-edit +stat=$? + +zle -A .self-insert self-insert +zle -A save-caps-lock caps-lock +zle -D save-caps-lock + +(( stat )) && zle send-break + +return $stat +@end example + +@noindent +This causes typed letters to be inserted capitalised until either +@t{accept-line} (i.e. typically the return key) is typed or the +@t{caps-lock} widget is invoked again; the later is handled by saving +the old definition of @t{caps-lock} as @t{save-caps-lock} and then +rebinding it to invoke @t{accept-line}. Note that an error from the +recursive edit is detected as a non-zero return status and propagated by +using the @t{send-break} widget. + +@tindex redisplay +@item @t{redisplay} (unbound) (@t{^R}) (@t{^R}) +Redisplays the edit buffer. + +@tindex reset-prompt +@item @t{reset-prompt} (unbound) (unbound) (unbound) +Force the prompts on both the left and right of the screen to be +re-expanded, then redisplay the edit buffer. This +reflects changes both to the prompt variables themselves and changes +in the expansion of the values (for example, changes in time or +directory, or changes to the value of variables referred to by the +prompt). + +@noindent +Otherwise, the prompt is only expanded each time zle starts, and +when the display has been interrupted by output from another part of the +shell (such as a job notification) which causes the command line to be +reprinted. + +@noindent +@t{reset-prompt} doesn't alter the special parameter @t{LASTWIDGET}. + +@noindent + +@tindex send-break +@item @t{send-break} (@t{^G ESC-^G}) (unbound) (unbound) +Abort the current editor function, e.g. @t{execute-named-command}, or the +editor itself, e.g. if you are in @t{vared}. Otherwise abort the parsing of +the current line; in this case the aborted line is available in the shell +variable @t{ZLE_LINE_ABORTED}. If the editor is aborted from within +@t{vared}, the variable @t{ZLE_VARED_ABORTED} is set. + +@tindex run-help +@item @t{run-help} (@t{ESC-H ESC-h}) (unbound) (unbound) +Push the buffer onto the buffer stack, and execute the +command `@t{run-help} @var{cmd}', where @var{cmd} is the current +command. @t{run-help} is normally aliased to @t{man}. + +@tindex vi-set-buffer +@item @t{vi-set-buffer} (unbound) (@t{"}) (unbound) +Specify a buffer to be used in the following command. +There are 37 buffers that can be specified: +the 26 `named' buffers @t{"a} to @t{"z}, the `yank' buffer @t{"0}, +the nine `queued' buffers @t{"1} to @t{"9} and the `black hole' buffer +@t{"_}. The named buffers can also be specified as @t{"A} to @t{"Z}. + +@noindent +When a buffer is specified for a cut, change or yank command, the text +concerned replaces the previous contents of the specified buffer. If +a named buffer is specified using a capital, the newly cut text is +appended to the buffer instead of overwriting it. When using the @t{"_} +buffer, nothing happens. This can be useful for deleting text without +affecting any buffers. + +@noindent +If no buffer is specified for a cut or change command, @t{"1} is used, and +the contents of @t{"1} to @t{"8} are each shifted along one buffer; +the contents of @t{"9} is lost. If no buffer is specified for a yank +command, @t{"0} is used. Finally, a paste command without a specified +buffer will paste the text from the most recent command regardless of any +buffer that might have been used with that command. + +@noindent +When called from a widget function by the @t{zle} command, the buffer +can optionally be specified with an argument. For example, + +@noindent +@example +zle vi-set-buffer A +@end example + +@tindex vi-set-mark +@item @t{vi-set-mark} (unbound) (@t{m}) (unbound) +Set the specified mark at the cursor position. + +@tindex set-mark-command +@item @t{set-mark-command} (@t{^@@}) (unbound) (unbound) +Set the mark at the cursor position. If called with a negative +numeric argument, do not set the mark but deactivate the region so that +it is no longer highlighted (it is still usable for other purposes). +Otherwise the region is marked as active. + +@tindex spell-word +@item @t{spell-word} (@t{ESC-$ ESC-S ESC-s}) (unbound) (unbound) +Attempt spelling correction on the current word. + +@tindex split-undo +@item @t{split-undo} +Breaks the undo sequence at the current change. This is useful in vi mode as +changes made in insert mode are coalesced on entering command mode. Similarly, +@t{undo} will normally revert as one all the changes made by a user-defined +widget. + +@tindex undefined-key +@item @t{undefined-key} +This command is executed when a key sequence that is not bound to any +command is typed. By default it beeps. + +@tindex undo +@item @t{undo} (@t{^_ ^Xu ^X^U}) (@t{u}) (unbound) +Incrementally undo the last text modification. When called from a +user-defined widget, takes an optional argument indicating a previous state +of the undo history as returned by the @t{UNDO_CHANGE_NO} variable; +modifications are undone until that state is reached, subject to +any limit imposed by the @t{UNDO_LIMIT_NO} variable. + +@noindent +Note that when invoked from vi command mode, the full prior change made in +insert mode is reverted, the changes having been merged when command mode was +selected. + +@tindex redo +@item @t{redo} (unbound) (@t{^R}) (unbound) +Incrementally redo undone text modifications. + +@tindex vi-undo-change +@item @t{vi-undo-change} (unbound) (unbound) (unbound) +Undo the last text modification. +If repeated, redo the modification. + +@tindex visual-mode +@item @t{visual-mode} (unbound) (@t{v}) (unbound) +Toggle vim-style visual selection mode. If line-wise visual mode is +currently enabled then it is changed to being character-wise. If used +following an operator, it forces the subsequent movement command to be +treated as a character-wise movement. + +@tindex visual-line-mode +@item @t{visual-line-mode} (unbound) (@t{V}) (unbound) +Toggle vim-style line-wise visual selection mode. If character-wise +visual mode is currently enabled then it is changed to being line-wise. If used +following an operator, it forces the subsequent movement command to be +treated as a line-wise movement. + +@tindex what-cursor-position +@item @t{what-cursor-position} (@t{^X=}) (@t{ga}) (unbound) +Print the character under the cursor, its code as an octal, decimal and +hexadecimal number, the current cursor position within the buffer and the +column of the cursor in the current line. + +@tindex where-is +@item @t{where-is} +Read the name of an editor command and print the listing of key +sequences that invoke the specified command. +A restricted set of editing functions is available in the +mini-buffer. Keys are looked up in the special +@t{command} keymap, and if not found there in the main keymap. + +@tindex which-command +@item @t{which-command} (@t{ESC-?}) (unbound) (unbound) +Push the buffer onto the buffer stack, and execute the +command `@t{which-command} @var{cmd}'. where @var{cmd} is the current +command. @t{which-command} is normally aliased to @t{whence}. + +@tindex vi-digit-or-beginning-of-line +@item @t{vi-digit-or-beginning-of-line} (unbound) (@t{0}) (unbound) +If the last command executed was a digit as part of an argument, +continue the argument. Otherwise, execute vi-beginning-of-line. + +@end table +@node Text Objects, , Miscellaneous, Zle Widgets + +@subsection Text Objects +@noindent +@cindex text objects +Text objects are commands that can be used to select a block of text +according to some criteria. They are a feature of the vim text editor +and so are primarily intended for use with vi operators or from visual +selection mode. However, they can also be used from vi-insert or emacs +mode. Key bindings listed below apply to the @t{viopp} and @t{visual} +keymaps. + +@noindent +@table @asis +@tindex select-a-blank-word +@item @t{select-a-blank-word} (@t{aW}) +Select a word including adjacent blanks, where a word is defined as a +series of non-blank characters. With a numeric argument, multiple words +will be selected. + +@tindex select-a-shell-word +@item @t{select-a-shell-word} (@t{aa}) +Select the current command argument applying the normal rules for +quoting. + +@tindex select-a-word +@item @t{select-a-word} (@t{aw}) +Select a word including adjacent blanks, using the normal vi-style word +definition. With a numeric argument, multiple words will be selected. + +@tindex select-in-blank-word +@item @t{select-in-blank-word} (@t{iW}) +Select a word, where a word is defined as a series of non-blank +characters. With a numeric argument, multiple words will be selected. + +@tindex select-in-shell-word +@item @t{select-in-shell-word} (@t{ia}) +Select the current command argument applying the normal rules for +quoting. If the argument begins and ends with matching quote characters, +these are not included in the selection. + +@tindex select-in-word +@item @t{select-in-word} (@t{iw}) +Select a word, using the normal vi-style word definition. With a numeric +argument, multiple words will be selected. + +@end table + +@noindent +@node Character Highlighting, , Zle Widgets, Zsh Line Editor + +@section Character Highlighting +@noindent + +@noindent +@vindex zle_highlight, setting +The line editor has the ability to highlight characters or regions +of the line that have a particular significance. This is controlled +by the array parameter @t{zle_highlight}, if it has been set by the user. + +@noindent +If the parameter contains the single entry @t{none} all highlighting +is turned off. Note the parameter is still expected to be an array. + +@noindent +Otherwise each entry of the array should consist of a word indicating a +context for highlighting, then a colon, then a comma-separated list of +the types of highlighting to apply in that context. + +@noindent +The contexts available for highlighting are the following: + +@noindent +@table @asis +@cindex region, highlighting +@cindex highlighting, region +@item @t{default} +Any text within the command line not affected by any other highlighting. +Text outside the editable area of the command line is not affected. + +@item @t{isearch} +When one of the incremental history search widgets is active, the +area of the command line matched by the search string or pattern. + +@item @t{region} +The currently selected text. In emacs terminology, this is referred to as +the region and is bounded by the cursor (point) and the mark. The region +is only highlighted if it is active, which is the case after the mark +is modified with @t{set-mark-command} or @t{exchange-point-and-mark}. +Note that whether or not the region is active has no effect on its +use within emacs style widgets, it simply determines whether it is +highlighted. In vi mode, the region corresponds to selected text in +visual mode. + +@cindex special characters, highlighting +@cindex highlighting, special characters +@item @t{special} +Individual characters that have no direct printable +representation but are shown in a special manner by the line editor. +These characters are described below. + +@cindex completion removable suffix, highlighting +@cindex suffix, highlighting removable, in completion +@cindex removable suffix, highlighting in completion +@item @t{suffix} +This context is used in completion for characters that are +marked as suffixes that will be removed if the completion ends +at that point, the most obvious example being a slash (@t{/}) after +a directory name. Note that suffix removal is configurable; the +circumstances under which the suffix will be removed may differ +for different completions. + +@item @t{paste} +Following a command to paste text, the characters that were inserted. + +@end table + +@noindent +When @t{region_highlight} is set, the contexts that describe a region --- +@t{isearch}, @t{region}, @t{suffix}, and @t{paste} --- +are applied first, then @t{region_highlight} is applied, then the remaining +@t{zle_highlight} contexts are applied. If a particular character is +affected by multiple specifications, the last specification wins. + +@noindent +@t{zle_highlight} may contain additional fields for controlling how +terminal sequences to change colours are output. Each of the following is +followed by a colon and a string in the same form as for key bindings. +This will not be necessary for the vast majority of terminals as the +defaults shown in parentheses are widely used. + +@noindent +@table @asis +@cindex escape sequences, terminal, for highlighting +@cindex terminal escape sequences for highlighting +@item @t{fg_start_code} (@t{\e[3}) +The start of the escape sequence for the foreground colour. +This is followed by one to three ASCII digits representing the colour. +Only used for palette colors, i.e. not 24-bit colors specified via a +color triplet. + +@item @t{fg_default_code} (@t{9}) +The number to use instead of the colour to reset the default foreground +colour. + +@item @t{fg_end_code} (@t{m}) +The end of the escape sequence for the foreground colour. + +@item @t{bg_start_code} (@t{\e[4}) +The start of the escape sequence for the background colour. +See @t{fg_start_code} above. + +@item @t{bg_default_code} (@t{9}) +The number to use instead of the colour to reset the default +background colour. + +@item @t{bg_end_code} (@t{m}) +The end of the escape sequence for the background colour. + +@end table + +@noindent +The available types of highlighting are the following. Note that +not all types of highlighting are available on all terminals: + +@noindent +@table @asis +@item @t{none} +No highlighting is applied to the given context. It is not useful for +this to appear with other types of highlighting; it is used to override +a default. + +@item @t{fg=}@var{colour} +The foreground colour should be set to @var{colour}, a decimal integer, +the name of one of the eight most widely-supported colours or as a +`@t{#}' followed by an RGB triplet in hexadecimal format. + +@noindent +Not all terminals support this and, of those that do, not all provide +facilities to test the support, hence the user should decide based on the +terminal type. Most terminals support the colours @t{black}, @t{red}, +@t{green}, @t{yellow}, @t{blue}, @t{magenta}, @t{cyan} and @t{white}, +which can be set by name. In addition. @t{default} may be used to +set the terminal's default foreground colour. Abbreviations are allowed; +@t{b} or @t{bl} selects black. Some terminals may generate additional +colours if the @t{bold} attribute is also present. + +@noindent +On recent terminals and on systems with an up-to-date terminal database the +number of colours supported may be tested by the command `@t{echotc +Co}'; if this succeeds, it indicates a limit on the number of colours which +will be enforced by the line editor. The number of colours is in any case +limited to 256 (i.e. the range 0 to 255). + +@noindent +Some modern terminal emulators have support for 24-bit true colour (16 +million colours). In this case, the hex triplet format can be used. This +consists of a `@t{#}' followed by either a three or six digit hexadecimal +number describing the red, green and blue components of the colour. Hex +triplets can also be used with 88 and 256 colour terminals via the +@t{zsh/nearcolor} module (see @ref{The zsh/nearcolor Module}). + +@noindent +Colour is also known as color. + +@item @t{bg=}@var{colour} +The background colour should be set to @var{colour}. +This works similarly to the foreground colour, except the background is +not usually affected by the bold attribute. + +@item @t{bold} +The characters in the given context are shown in a bold font. +Not all terminals distinguish bold fonts. + +@item @t{standout} +The characters in the given context are shown in the terminal's standout +mode. The actual effect is specific to the terminal; on many terminals it +is inverse video. On some such terminals, where the cursor does not blink +it appears with standout mode negated, making it less than clear where +the cursor actually is. On such terminals one of the other effects +may be preferable for highlighting the region and matched search string. + +@item @t{underline} +The characters in the given context are shown underlined. Some +terminals show the foreground in a different colour instead; in this +case whitespace will not be highlighted. + +@end table + +@noindent +The characters described above as `special' are as follows. The +formatting described here is used irrespective of whether the characters +are highlighted: + +@noindent +@table @asis +@item ASCII control characters +Control characters in the ASCII range are shown as +`@t{^}' followed by the base character. + +@item Unprintable multibyte characters +This item applies to control characters not in the ASCII range, +plus other characters as follows. If the @t{MULTIBYTE} option is in +effect, multibyte characters not in the ASCII character set that are +reported as having zero width are treated as combining characters when the +option @t{COMBINING_CHARS} is on. If the option is off, or if a character +appears where a combining character is not valid, the character +is treated as unprintable. + +@noindent +Unprintable multibyte characters are shown as a hexadecimal number between +angle brackets. The number is the code point of the character in the wide +character set; this may or may not be Unicode, depending on the operating +system. + +@item Invalid multibyte characters +If the @t{MULTIBYTE} option is in effect, any sequence of one or more +bytes that does not form a valid character in the current character +set is treated as a series of bytes each shown as a special character. +This case can be distinguished from other unprintable characters +as the bytes are represented as two hexadecimal digits between angle +brackets, as distinct from the four or eight digits that are used for +unprintable characters that are nonetheless valid in the current +character set. + +@noindent +Not all systems support this: for it to work, the system's representation of +wide characters must be code values from the Universal Character Set, +as defined by IS0 10646 (also known as Unicode). + +@item Wrapped double-width characters +When a double-width character appears in the final column of a line, it +is instead shown on the next line. The empty space left in the original +position is highlighted as a special character. + +@end table + +@noindent +If @t{zle_highlight} is not set or no value applies to a particular +context, the defaults applied are equivalent to + +@noindent +@example +zle_highlight=(region:standout special:standout +suffix:bold isearch:underline paste:standout) +@end example + +@noindent +i.e. both the region and special characters are shown in standout mode. + +@noindent +Within widgets, arbitrary regions may be highlighted by setting the +special array parameter @t{region_highlight}; see +@ref{Zle Widgets}. + +@noindent +@c (avoiding a yodl bug) +@c Yodl file: Zsh/compwid.yo +@node Completion Widgets, Completion System, Zsh Line Editor, Top + +@chapter Completion Widgets +@noindent +@cindex completion, widgets +@cindex completion, programmable +@cindex completion, controlling + +@section Description +@noindent +The shell's programmable completion mechanism can be manipulated in two +ways; here the low-level features supporting the newer, function-based +mechanism are defined. A complete set of shell functions based on these +features is described in +the next chapter, @ref{Completion System}, +and users with no interest in adding to that system (or, potentially, +writing their own --- see dictionary entry for `hubris') should skip +the current section. The older system based on the @t{compctl} builtin +command is described in +@ref{Completion Using compctl}. + +@noindent +Completion widgets are defined by the @t{-C} option to the @t{zle} +builtin command provided by the @t{zsh/zle} module (see +@ref{The zsh/zle Module}). For example, + +@noindent +@example +zle -C complete expand-or-complete completer +@end example + +@noindent +defines a widget named `@t{complete}'. The second argument is the name +of any of the builtin widgets that handle completions: +@t{complete-word}, @t{expand-or-complete}, +@t{expand-or-complete-prefix}, @t{menu-complete}, +@t{menu-expand-or-complete}, @t{reverse-menu-complete}, +@t{list-choices}, or @t{delete-char-or-list}. Note that this will still +work even if the widget in question has been re-bound. + +@noindent +When this newly defined widget is bound to a key +using the @t{bindkey} builtin command defined in the @t{zsh/zle} module +(@ref{Zsh Line Editor}), typing that key will call the shell function `@t{completer}'. This +function is responsible for generating the possible matches using the +builtins described below. As with other ZLE widgets, the function is +called with its standard input closed. + +@noindent +Once the function returns, the completion code takes over control again +and treats the matches in the same manner as the specified builtin +widget, in this case @t{expand-or-complete}. + +@noindent +@menu +* Completion Special Parameters:: +* Completion Builtin Commands:: +* Completion Condition Codes:: +* Completion Matching Control:: +* Completion Widget Example:: +@end menu + +@noindent +@node Completion Special Parameters, Completion Builtin Commands, , Completion Widgets + +@section Completion Special Parameters +@noindent + +@noindent +The parameters @t{ZLE_REMOVE_SUFFIX_CHARS} and @t{ZLE_SPACE_SUFFIX_CHARS} +are used by the completion mechanism, but are not special. See +@ref{Parameters Used By The Shell}. + +@noindent +Inside completion widgets, and any functions called from them, some +parameters have special meaning; outside these functions they are not +special to the shell in any way. These parameters are used to pass +information between the completion code and the completion widget. Some of +the builtin commands and the condition codes use or change the current +values of these parameters. Any existing values will be hidden during +execution of completion widgets; except for @t{compstate}, the parameters +are reset on each function exit (including nested function calls from +within the completion widget) to the values they had when the function was +entered. + +@noindent +@table @asis +@vindex CURRENT +@item @t{CURRENT} +This is the number of the current word, i.e. the word the cursor is +currently on in the @t{words} array. Note that this value is only +correct if the @t{ksharrays} option is not set. + +@vindex IPREFIX +@item @t{IPREFIX} +Initially this will be set to the empty string. This parameter functions +like @t{PREFIX}; it contains a string which precedes the one in @t{PREFIX} +and is not considered part of the list of matches. Typically, a string is +transferred from the beginning of @t{PREFIX} to the end of @t{IPREFIX}, for +example: + +@noindent +@example +IPREFIX=$@{PREFIX%%\=*@}= +PREFIX=$@{PREFIX#*=@} +@end example + +@noindent +causes the part of the prefix up to and including the first equal sign not +to be treated as part of a matched string. This can be done automatically +by the @t{compset} builtin, see below. + +@vindex ISUFFIX +@item @t{ISUFFIX} +As @t{IPREFIX}, but for a suffix that should not be considered part +of the matches; note that the @t{ISUFFIX} string follows the @t{SUFFIX} +string. + +@vindex PREFIX +@item @t{PREFIX} +Initially this will be set to the part of the current word from the +beginning of the word up to the position of the cursor; it may be altered +to give a common prefix for all matches. + +@vindex QIPREFIX +@item @t{QIPREFIX} +This parameter is read-only and contains the quoted string up to the +word being completed. E.g. when completing `@t{"foo}', this parameter +contains the double quote. If the @t{-q} option of @t{compset} is used +(see below), and the original string was `@t{"foo bar}' with the +cursor on the `@t{bar}', this parameter contains `@t{"foo }'. + +@vindex QISUFFIX +@item @t{QISUFFIX} +Like @t{QIPREFIX}, but containing the suffix. + +@vindex SUFFIX +@item @t{SUFFIX} +Initially this will be set to the part of the current word from the +cursor position to the end; it may be altered to give a common suffix for +all matches. It is most useful when the option @t{COMPLETE_IN_WORD} is +set, as otherwise the whole word on the command line is treated as a +prefix. + +@vindex compstate +@cindex completion widgets, examining and setting state in +@item @t{compstate} +This is an associative array with various keys and values that the +completion code uses to exchange information with the completion widget. +The keys are: + +@noindent +@table @asis +@vindex all_quotes, compstate +@item @t{all_quotes} +The @t{-q} option of the @t{compset} builtin command (see below) +allows a quoted string to be broken into separate words; if the cursor is +on one of those words, that word will be completed, possibly invoking +`@t{compset -q}' recursively. With this key it is possible to test the +types of quoted strings which are currently broken into parts in this +fashion. Its value contains one character for each quoting level. The +characters are a single quote or a double quote for strings quoted with +these characters, a dollars sign for strings quoted with +@t{$'}@var{...}@t{'} and a backslash for strings not starting with a +quote character. The first character in the value always corresponds to the +innermost quoting level. + +@vindex context, compstate +@item @t{context} +This will be set by the completion code to the overall context +in which completion is attempted. Possible values are: + +@noindent +@table @asis +@item @t{array_value} +when completing inside the value of an array parameter assignment; in +this case the @t{words} array contains the words inside the parentheses. + +@item @t{brace_parameter} +when completing the name of a parameter in a parameter expansion beginning +with @t{$@{}. This context will also be set when completing parameter +flags following @t{$@{(}; the full command line argument is presented +and the handler must test the value to be completed to ascertain that +this is the case. + +@item @t{assign_parameter} +when completing the name of a parameter in a parameter assignment. + +@item @t{command} +when completing for a normal command (either in command position or for +an argument of the command). + +@item @t{condition} +when completing inside a `@t{[[}...@t{]]}' conditional expression; in +this case the @t{words} array contains only the words inside the +conditional expression. + +@item @t{math} +when completing in a mathematical environment such as a +`@t{((}...@t{))}' construct. + +@item @t{parameter} +when completing the name of a parameter in a parameter expansion beginning +with @t{$} but not @t{$@{}. + +@item @t{redirect} +when completing after a redirection operator. + +@item @t{subscript} +when completing inside a parameter subscript. + +@item @t{value} +when completing the value of a parameter assignment. + +@end table + +@vindex exact, compstate +@item @t{exact} +Controls the behaviour when the @t{REC_EXACT} option is set. It will be +set to @t{accept} if an exact match would be accepted, and will be unset +otherwise. + +@noindent +If it was set when at least one match equal to the string on the line +was generated, the match is accepted. + +@vindex exact_string, compstate +@item @t{exact_string} +The string of an exact match if one was found, otherwise unset. + +@vindex ignored, compstate +@item @t{ignored} +The number of words that were ignored because they matched one of the +patterns given with the @t{-F} option to the @t{compadd} builtin +command. + +@vindex insert, compstate +@item @t{insert} +This controls the manner in which a match is inserted into the command +line. On entry to the widget function, if it is unset the command line is +not to be changed; if set to @t{unambiguous}, any prefix common to all +matches is to be inserted; if set to @t{automenu-unambiguous}, the +common prefix is to be inserted and the next invocation of the +completion code may start menu completion (due to the @t{AUTO_MENU} +option being set); if set to @t{menu} or @t{automenu} menu completion +will be started for the matches currently generated (in the +latter case this will happen because the @t{AUTO_MENU} is set). The +value may also contain the string `@t{tab}' when the completion code +would normally not really do completion, but only insert the TAB +character. + +@noindent +On exit it may be set to any of the values above (where setting it to +the empty string is the same as unsetting it), or to a number, in which +case the match whose number is given will be inserted into the command line. +Negative numbers count backward from the last match (with `@t{-1}' +selecting the last match) and out-of-range values are wrapped +around, so that a value of zero selects the last match and a value +one more than the maximum selects the first. Unless the value of this +key ends in a space, the match is inserted as in a menu completion, +i.e. without automatically appending a space. + +@noindent +Both @t{menu} and @t{automenu} may also specify the number of the +match to insert, given after a colon. For example, `@t{menu:2}' says +to start menu completion, beginning with the second match. + +@noindent +Note that a value containing the substring `@t{tab}' makes the +matches generated be ignored and only the TAB be inserted. + +@noindent +Finally, it may also be set to @t{all}, which makes all matches +generated be inserted into the line. + +@vindex insert_positions, compstate +@item @t{insert_positions} +When the completion system inserts an unambiguous string into the +line, there may be multiple places where characters are missing or +where the character inserted differs from at least one match. The +value of this key contains a colon separated list of all these +positions, as indexes into the command line. + +@vindex last_prompt, compstate +@item @t{last_prompt} +If this is set to a non-empty string for every match added, the +completion code will move the cursor back to the previous prompt after +the list of completions has been displayed. Initially this is set or +unset according to the @t{ALWAYS_LAST_PROMPT} option. + +@vindex list, compstate +@item @t{list} +This controls whether or how the list of matches will be displayed. If it +is unset or empty they will never be listed; if its value begins with +@t{list}, they will always be listed; if it begins with @t{autolist} +or @t{ambiguous}, they will be listed when the @t{AUTO_LIST} or +@t{LIST_AMBIGUOUS} options respectively would normally cause them to +be. + +@noindent +If the substring @t{force} appears in the value, this makes the +list be shown even if there is only one match. Normally, the list +would be shown only if there are at least two matches. + +@noindent +The value contains the substring @t{packed} if the @t{LIST_PACKED} +option is set. If this substring is given for all matches added to a +group, this group will show the @t{LIST_PACKED} behavior. The same is +done for the @t{LIST_ROWS_FIRST} option with the substring @t{rows}. + +@noindent +Finally, if the value contains the string @t{explanations}, only the +explanation strings, if any, will be listed and if it contains +@t{messages}, only the messages (added with the @t{-x} option of +@t{compadd}) will be listed. If it contains both @t{explanations} and +@t{messages} both kinds of explanation strings will be listed. It +will be set appropriately on entry to a completion widget and may be +changed there. + +@vindex list_lines, compstate +@item @t{list_lines} +This gives the number of lines that are needed to display the full +list of completions. Note that to calculate the total number of lines +to display you need to add the number of lines needed for the command +line to this value, this is available as the value of the @t{BUFFERLINES} +special parameter. + +@vindex list_max, compstate +@item @t{list_max} +Initially this is set to the value of the @t{LISTMAX} parameter. +It may be set to any other value; when the widget exits this value +will be used in the same way as the value of @t{LISTMAX}. + +@vindex nmatches, compstate +@item @t{nmatches} +The number of matches generated and accepted by the completion code so +far. + +@vindex old_insert, compstate +@item @t{old_insert} +On entry to the widget this will be set to the number of the match of +an old list of completions that is currently inserted into the command +line. If no match has been inserted, this is unset. + +@noindent +As with @t{old_list}, the value of this key will only be used if it is the +string @t{keep}. If it was set to this value by the widget and there was an +old match inserted into the command line, this match will be kept and if +the value of the @t{insert} key specifies that another match should be +inserted, this will be inserted after the old one. + +@vindex old_list, compstate +@item @t{old_list} +This is set to @t{yes} if there is still a valid list of completions +from a previous completion at the time the widget is invoked. This will +usually be the case if and only if the previous editing operation was a +completion widget or one of the builtin completion functions. If there is a +valid list and it is also currently shown on the screen, the value of this +key is @t{shown}. + +@noindent +After the widget has exited the value of this key is only used if it +was set to @t{keep}. In this case the completion code will continue +to use this old list. If the widget generated new matches, they will +not be used. + +@vindex parameter, compstate +@item @t{parameter} +The name of the parameter when completing in a subscript or in the +value of a parameter assignment. + +@vindex pattern_insert, compstate +@item @t{pattern_insert} +Normally this is set to @t{menu}, which specifies that menu completion will +be used whenever a set of matches was generated using pattern matching. If +it is set to any other non-empty string by the user and menu completion is +not selected by other option settings, the code will instead insert any +common prefix for the generated matches as with normal completion. + +@vindex pattern_match, compstate +@item @t{pattern_match} +Locally controls the behaviour given by the @t{GLOB_COMPLETE} option. +Initially it is set to `@t{*}' if and only if the option is set. +The completion widget may set it to this value, to an empty string +(which has the same effect as unsetting it), or to any +other non-empty string. If it is non-empty, unquoted metacharacters on the +command line will be treated as patterns; if it is `@t{*}', then +additionally a wildcard `@t{*}' is assumed at the cursor position; if +it is empty or unset, metacharacters will be treated literally. + +@noindent +Note that the matcher specifications given to the @t{compadd} builtin +command are not used if this is set to a non-empty string. + +@vindex quote, compstate +@item @t{quote} +When completing inside quotes, this contains the quotation character +(i.e. either a single quote, a double quote, or a backtick). Otherwise it +is unset. + +@vindex quoting, compstate +@item @t{quoting} +When completing inside single quotes, this is set to the string +@t{single}; inside double quotes, the string +@t{double}; inside backticks, the string @t{backtick}. +Otherwise it is unset. + +@vindex redirect, compstate +@item @t{redirect} +The redirection operator when completing in a redirection position, +i.e. one of @t{<}, @t{>}, etc. + +@vindex restore, compstate +@item @t{restore} +This is set to @t{auto} before a function is entered, which forces the +special parameters mentioned above (@t{words}, @t{CURRENT}, @t{PREFIX}, +@t{IPREFIX}, @t{SUFFIX}, and @t{ISUFFIX}) to be restored to their +previous values when the function exits. If a function unsets it or +sets it to any other string, they will not be restored. + +@vindex to_end, compstate +@item @t{to_end} +Specifies the occasions on which the cursor is moved to the end of a string +when a match is inserted. On entry to a widget function, it may be +@t{single} if this will happen when a single unambiguous match was inserted +or @t{match} if it will happen any time a match is inserted (for example, +by menu completion; this is likely to be the effect of the @t{ALWAYS_TO_END} +option). + +@noindent +On exit, it may be set to @t{single} as above. It may also be set to +@t{always}, or to the empty string or unset; in those cases the cursor will +be moved to the end of the string always or never respectively. Any +other string is treated as @t{match}. + +@vindex unambiguous, compstate +@item @t{unambiguous} +This key is read-only and will always be set to the common (unambiguous) +prefix the completion code has generated for all matches added so far. + +@vindex unambiguous_cursor, compstate +@item @t{unambiguous_cursor} +This gives the position the cursor would be placed at if the +common prefix in the @t{unambiguous} key were inserted, relative to +the value of that key. The cursor would be placed before the character +whose index is given by this key. + +@vindex unambiguous_positions, compstate +@item @t{unambiguous_positions} +This contains all positions where characters in the unambiguous string +are missing or where the character inserted differs from at least one +of the matches. The positions are given as indexes into the string +given by the value of the @t{unambiguous} key. + +@vindex vared, compstate +@item @t{vared} +If completion is called while editing a line using the @t{vared} +builtin, the value of this key is set to the name of the parameter +given as an argument to @t{vared}. This key is only set while a @t{vared} +command is active. + +@end table + +@vindex words +@item @t{words} +This array contains the words present on the command line currently being +edited. + +@end table + +@noindent +@node Completion Builtin Commands, Completion Condition Codes, Completion Special Parameters, Completion Widgets + +@section Completion Builtin Commands +@noindent +@table @asis +@findex compadd +@cindex completion widgets, adding specified matches + +@item @t{compadd }[ @t{-akqQfenUl12C} ] [ @t{-F} @var{array} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-P} @var{prefix} ] [ @t{-S} @var{suffix} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-p} @var{hidden-prefix} ] [ @t{-s} @var{hidden-suffix} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-i} @var{ignored-prefix} ] [ @t{-I} @var{ignored-suffix} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-W} @var{file-prefix} ] [ @t{-d} @var{array} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-J} @var{group-name} ] [ @t{-X} @var{explanation} ] [ @t{-x} @var{message} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-V} @var{group-name} ] [ @t{-o} [ @var{order} ] ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-r} @var{remove-chars} ] [ @t{-R} @var{remove-func} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-D} @var{array} ] [ @t{-O} @var{array} ] [ @t{-A} @var{array} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-E} @var{number} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-M} @var{match-spec} ] [ @t{-}@t{-} ] [ @var{words} ... ] + +@noindent +This builtin command can be used to add matches directly and control +all the information the completion code stores with each possible +match. The return status is zero if at least one match was added and +non-zero if no matches were added. + +@noindent +The completion code breaks the string to complete into seven fields in +the order: + +@noindent +@quotation +@var{<ipre><apre><hpre><word><hsuf><asuf><isuf>} +@end quotation + +@noindent +The first field +is an ignored prefix taken from the command line, the contents of the +@t{IPREFIX} parameter plus the string given with the @t{-i} +option. With the @t{-U} option, only the string from the @t{-i} +option is used. The field @var{<apre>} is an optional prefix string +given with the @t{-P} option. The @var{<hpre>} field is a string +that is considered part of the match but that should not be shown when +listing completions, given with the @t{-p} option; for example, +functions that do filename generation might specify +a common path prefix this way. @var{<word>} is the part of the match that +should appear in the list of completions, i.e. one of the @var{words} given +at the end of the @t{compadd} command line. The suffixes @var{<hsuf>}, +@var{<asuf>} and @var{<isuf>} correspond to the prefixes @var{<hpre>}, +@var{<apre>} and @var{<ipre>} and are given by the options @t{-s}, @t{-S} and +@t{-I}, respectively. + +@noindent +The supported flags are: + +@noindent +@table @asis +@item @t{-P} @var{prefix} +This gives a string to be inserted before the given @var{words}. The +string given is not considered as part of the match and any shell +metacharacters in it will not be quoted when the string is inserted. + +@item @t{-S} @var{suffix} +Like @t{-P}, but gives a string to be inserted after the match. + +@item @t{-p} @var{hidden-prefix} +This gives a string that should be inserted into the command line before the +match but that should not appear in the list of matches. Unless the +@t{-U} option is given, this string must be matched as part of the string +on the command line. + +@item @t{-s} @var{hidden-suffix} +Like `@t{-p}', but gives a string to insert after the match. + +@item @t{-i} @var{ignored-prefix} +This gives a string to insert into the command line just before any +string given with the `@t{-P}' option. Without `@t{-P}' the string is +inserted before the string given with `@t{-p}' or directly before the +match. + +@item @t{-I} @var{ignored-suffix} +Like @t{-i}, but gives an ignored suffix. + +@item @t{-a} +With this flag the @var{words} are taken as names of arrays and the +possible matches are their values. If only some elements of the +arrays are needed, the @var{words} may also contain subscripts, as in +`@t{foo[2,-1]}'. + +@item @t{-k} +With this flag the @var{words} are taken as names of associative arrays +and the possible matches are their keys. As for @t{-a}, the +@var{words} may also contain subscripts, as in `@t{foo[(R)*bar*]}'. + +@item @t{-d} @var{array} +This adds per-match display strings. The @var{array} should contain one +element per @var{word} given. The completion code will then display the +first element instead of the first @var{word}, and so on. The +@var{array} may be given as the name of an array parameter or directly +as a space-separated list of words in parentheses. + +@noindent +If there are fewer display strings than @var{words}, the leftover +@var{words} will be displayed unchanged and if there are more display +strings than @var{words}, the leftover display strings will be silently +ignored. + +@item @t{-l} +This option only has an effect if used together with the @t{-d} +option. If it is given, the display strings are listed one per line, +not arrayed in columns. + +@item @t{-o} [ @var{order} ] +This controls the order in which matches are sorted. @var{order} is a +comma-separated list comprising the following possible values. These values +can be abbreviated to their initial two or three characters. Note that the +order forms part of the group name space so matches with different orderings +will not be in the same group. + +@noindent +@table @asis +@item @t{match} +If given, the order of the output is determined by the match strings; +otherwise it is determined by the display strings (i.e. the strings given +by the @t{-d} option). This is the default if `@t{-o}' is specified but +the @var{order} argument is omitted. + +@item @t{nosort} +This specifies that the matches are pre-sorted and their order should be +preserved. This value only makes sense alone and cannot be combined with any +others. + +@item @t{numeric} +If the matches include numbers, sort them numerically rather than +lexicographically. + +@item @t{reverse} +Arrange the matches backwards by reversing the sort ordering. + +@end table + +@item @t{-J} @var{group-name} +Gives the name of the group of matches the words should be stored in. + +@item @t{-V} @var{group-name} +Like @t{-J} but naming an unsorted group. This option is identical to +the combination of @t{-J} and @t{-o nosort}. + +@item @t{-1} +If given together with the @t{-V} option, makes +only consecutive duplicates in the group be removed. If combined with +the @t{-J} option, this has no visible effect. Note that groups +with and without this flag are in different name spaces. + +@item @t{-2} +If given together with the @t{-J} or @t{-V} option, makes all +duplicates be kept. Again, groups with and without this flag are in +different name spaces. + +@item @t{-X} @var{explanation} +The @var{explanation} string will be printed with the list of matches, +above the group currently selected. + +@noindent +Within the @var{explanation}, the following sequences may be used to +specify output attributes +(see @ref{Prompt Expansion}): +`@t{%B}', `@t{%S}', `@t{%U}', `@t{%F}', `@t{%K}' and their lower case +counterparts, as well as `@t{%@{}...@t{%@}}'. `@t{%F}', `@t{%K}' and +`@t{%@{}...@t{%@}}' take arguments in the same form as prompt +expansion. (Note that the sequence `@t{%G}' is not available; an +argument to `@t{%@{}' should be used instead.) The sequence `@t{%%}' +produces a literal `@t{%}'. + +@noindent +These sequences are most often employed by users when customising the +@t{format} style +(see +@ref{Completion System}), +but they must also be taken into account when writing completion +functions, as passing descriptions with unescaped `@t{%}' characters +to utility functions such as @t{_arguments} and @t{_message} may +produce unexpected results. If arbitrary text is to be passed in a +description, it can be escaped using e.g. @t{$@{my_str//\%/%%@}}. + +@item @t{-x} @var{message} +Like @t{-X}, but the @var{message} will be printed even if there are no +matches in the group. + +@item @t{-q} +The suffix given with @t{-S} will be automatically removed if +the next character typed is a blank or does not insert anything, or if +the suffix consists of only one character and the next character typed +is the same character. + +@item @t{-r} @var{remove-chars} +This is a more versatile form of the @t{-q} option. +The suffix given with @t{-S} or the slash automatically added after +completing directories will be automatically removed if +the next character typed inserts one of the characters given in the +@var{remove-chars}. This string is parsed as a characters class and +understands the backslash sequences used by the @t{print} command. For +example, `@t{-r "a-z\t"}' removes the suffix if the next character typed +inserts a lower case character or a TAB, and `@t{-r "^0-9"}' removes the +suffix if the next character typed inserts anything but a digit. One extra +backslash sequence is understood in this string: `@t{\-}' stands for +all characters that insert nothing. Thus `@t{-S "=" -q}' is the same +as `@t{-S "=" -r "= \t\n\-"}'. + +@noindent +This option may also be used without the @t{-S} option; then any +automatically added space will be removed when one of the characters in the +list is typed. + +@item @t{-R} @var{remove-func} +This is another form of the @t{-r} option. When a suffix +has been inserted and the completion accepted, the function +@var{remove-func} will be called after the next character typed. It is +passed the length of the suffix as an argument and can use the special +parameters available in ordinary (non-completion) zle widgets (see +@ref{Zsh Line Editor}) to analyse and modify the command line. + +@item @t{-f} +If this flag is given, all of the matches built from @var{words} are +marked as being the names of files. They are not required to be actual +filenames, but if they are, and the option @t{LIST_TYPES} is set, the +characters describing the types of the files in the completion lists will +be shown. This also forces a slash to be added when the name of a +directory is completed. + +@item @t{-e} +This flag can be used to tell the completion code that the matches +added are parameter names for a parameter expansion. This will make +the @t{AUTO_PARAM_SLASH} and @t{AUTO_PARAM_KEYS} options be used for +the matches. + +@item @t{-W} @var{file-prefix} +This string is a pathname that will be +prepended to each of the matches formed by the given @var{words} together +with any prefix specified by the @t{-p} option to form a complete filename +for testing. Hence it is only useful if combined with the @t{-f} flag, as +the tests will not otherwise be performed. + +@item @t{-F} @var{array} +Specifies an array containing patterns. Words matching one of these +patterns are ignored, i.e. not considered to be possible matches. + +@noindent +The @var{array} may be the name of an array parameter or a list of +literal patterns enclosed in parentheses and quoted, as in `@t{-F "(*?.o +*?.h)"}'. If the name of an array is given, the elements of the array are +taken as the patterns. + +@item @t{-Q} +This flag instructs the completion +code not to quote any metacharacters in the words when inserting them +into the command line. + +@item @t{-M} @var{match-spec} +This gives local match specifications as described below in +@ref{Completion Matching Control}. This option may be given more than once. +In this case all @var{match-spec}s given are concatenated with spaces +between them to form the specification string to use. +Note that they will only be used if the @t{-U} option is not given. + +@item @t{-n} +Specifies that the words added are to be used as possible +matches, but are not to appear in the completion listing. + +@item @t{-U} +If this flag is given, all words given will be accepted and no matching +will be done by the completion code. Normally this is used in +functions that do the matching themselves. + +@item @t{-O} @var{array} +If this option is given, the @var{words} are @emph{not} added to the set of +possible completions. Instead, matching is done as usual and all of the +@var{words} given as arguments that match the string on the command line +will be stored in the array parameter whose name is given as @var{array}. + +@item @t{-A} @var{array} +As the @t{-O} option, except that instead of those of the @var{words} which +match being stored in @var{array}, the strings generated internally by the +completion code are stored. For example, +with a matching specification of `@t{-M "L:|no="}', the string `@t{nof}' +on the command line and the string `@t{foo}' as one of the @var{words}, this +option stores the string `@t{nofoo}' in the array, whereas the @t{-O} +option stores the `@t{foo}' originally given. + +@item @t{-D} @var{array} +As with @t{-O}, the @var{words} are not added to the set of possible +completions. Instead, the completion code tests whether each @var{word} +in turn matches what is on the line. If the @var{n}th @var{word} does not +match, the @var{n}th element of the @var{array} is removed. Elements +for which the corresponding @var{word} is matched are retained. + +@item @t{-C} +This option adds a special match which expands to all other matches +when inserted into the line, even those that are added after this +option is used. Together with the @t{-d} option it is possible to +specify a string that should be displayed in the list for this special +match. If no string is given, it will be shown as a string containing +the strings that would be inserted for the other matches, truncated to +the width of the screen. + +@item @t{-E} @var{number} +This option adds @var{number} empty matches after the @var{words} have +been added. An empty match takes up space in completion listings but +will never be inserted in the line and can't be selected with menu +completion or menu selection. This makes empty matches only useful to +format completion lists and to make explanatory string be shown in +completion lists (since empty matches can be given display strings +with the @t{-d} option). And because all but one empty string would +otherwise be removed, this option implies the @t{-V} and @t{-2} +options (even if an explicit @t{-J} option is given). This can be +important to note as it affects the name space into which matches are +added. + +@item @t{-} +@itemx @t{-}@t{-} +This flag ends the list of flags and options. All arguments after it +will be taken as the words to use as matches even if they begin with +hyphens. + +@end table + +@noindent +Except for the @t{-M} flag, if any of these flags is given more than +once, the first one (and its argument) will be used. + +@findex compset +@cindex completion widgets, modifying special parameters +@item @t{compset -p} @var{number} +@itemx @t{compset -P} [ @var{number} ] @var{pattern} +@itemx @t{compset -s} @var{number} +@itemx @t{compset -S} [ @var{number} ] @var{pattern} +@itemx @t{compset -n} @var{begin} [ @var{end} ] +@itemx @t{compset -N} @var{beg-pat} [ @var{end-pat} ] +@itemx @t{compset -q} +This command simplifies modification of the special parameters, +while its return status allows tests on them to be carried out. + +@noindent +The options are: + +@noindent +@table @asis +@item @t{-p} @var{number} +If the value of the @t{PREFIX} parameter is at least @var{number} +characters long, the first @var{number} characters are removed from it and +appended to the contents of the @t{IPREFIX} parameter. + +@item @t{-P} [ @var{number} ] @var{pattern} +If the value of the @t{PREFIX} parameter begins with anything that +matches the @var{pattern}, the matched portion is removed from +@t{PREFIX} and appended to @t{IPREFIX}. + +@noindent +Without the optional @var{number}, the longest match is taken, but +if @var{number} is given, anything up to the @var{number}th match is +moved. If the @var{number} is negative, the @var{number}th longest +match is moved. For example, if @t{PREFIX} contains the string +`@t{a=b=c}', then @t{compset -P '*\='} will move the string `@t{a=b=}' +into the @t{IPREFIX} parameter, but @t{compset -P 1 '*\='} will move only +the string `@t{a=}'. + +@item @t{-s} @var{number} +As @t{-p}, but transfer the last @var{number} characters from the +value of @t{SUFFIX} to the front of the value of @t{ISUFFIX}. + +@item @t{-S} [ @var{number} ] @var{pattern} +As @t{-P}, but match the last portion of @t{SUFFIX} and transfer the +matched portion to the front of the value of @t{ISUFFIX}. + +@item @t{-n} @var{begin} [ @var{end} ] +If the current word position as specified by the parameter @t{CURRENT} +is greater than or equal to @var{begin}, anything up to the +@var{begin}th word is removed from the @t{words} array and the value +of the parameter @t{CURRENT} is decremented by @var{begin}. + +@noindent +If the optional @var{end} is given, the modification is done only if +the current word position is also less than or equal to @var{end}. In +this case, the words from position @var{end} onwards are also removed from +the @t{words} array. + +@noindent +Both @var{begin} and @var{end} may be negative to count backwards +from the last element of the @t{words} array. + +@item @t{-N} @var{beg-pat} [ @var{end-pat} ] +If one of the elements of the @t{words} array before the one at the +index given by the value of the parameter @t{CURRENT} matches the +pattern @var{beg-pat}, all elements up to and including the matching one are +removed from the @t{words} array and the value of @t{CURRENT} is changed to +point to the same word in the changed array. + +@noindent +If the optional pattern @var{end-pat} is also given, and there is an +element in the @t{words} array matching this pattern, the parameters +are modified only if the index of this word is higher than the one +given by the @t{CURRENT} parameter (so that the matching word has +to be after the cursor). In this case, the words starting with the one +matching @t{end-pat} are also removed from the @t{words} +array. If @t{words} contains no word matching @var{end-pat}, the +testing and modification is performed as if it were not given. + +@item @t{-q} +The word +currently being completed is split on spaces into separate words, +respecting the usual shell quoting conventions. The +resulting words are stored in the @t{words} array, and @t{CURRENT}, +@t{PREFIX}, @t{SUFFIX}, @t{QIPREFIX}, and @t{QISUFFIX} are modified to +reflect the word part that is completed. + +@end table + +@noindent +In all the above cases the return status is zero if the test succeeded +and the parameters were modified and non-zero otherwise. This allows +one to use this builtin in tests such as: + +@noindent +@example +if compset -P '*\='; then ... +@end example + +@noindent +This forces anything up to and including the last equal sign to be +ignored by the completion code. + +@item @t{compcall} [ @t{-TD} ] +This allows the use of completions defined with the @t{compctl} builtin +from within completion widgets. The list of matches will be generated as +if one of the non-widget completion functions (@t{complete-word}, etc.) +had been called, except that only @t{compctl}s given for specific commands +are used. To force the code to try completions defined with the @t{-T} +option of @t{compctl} and/or the default completion (whether defined by +@t{compctl -D} or the builtin default) in the appropriate places, the +@t{-T} and/or @t{-D} flags can be passed to @t{compcall}. + +@noindent +The return status can be used to test if a matching @t{compctl} +definition was found. It is non-zero if a @t{compctl} was found and +zero otherwise. + +@noindent +Note that this builtin is defined by the @t{zsh/compctl} module. + +@end table + +@noindent +@node Completion Condition Codes, Completion Matching Control, Completion Builtin Commands, Completion Widgets + +@section Completion Condition Codes +@noindent +@cindex completion widgets, condition codes + +@noindent +The following additional condition codes for use within the @t{[[} @var{...} @t{]]} +construct are available in completion widgets. These work on the special +parameters. All of these tests can also be performed by the @t{compset} +builtin, but in the case of the condition codes the contents of the special +parameters are not modified. + +@noindent +@table @asis +@item @t{-prefix} [ @var{number} ] @var{pattern} +true if the test for the @t{-P} option of @t{compset} would succeed. + +@item @t{-suffix} [ @var{number} ] @var{pattern} +true if the test for the @t{-S} option of @t{compset} would succeed. + +@item @t{-after} @var{beg-pat} +true if the test of the @t{-N} option with only the @var{beg-pat} given +would succeed. + +@item @t{-between} @var{beg-pat end-pat} +true if the test for the @t{-N} option with both patterns would succeed. + +@end table + +@noindent +@node Completion Matching Control, Completion Widget Example, Completion Condition Codes, Completion Widgets + +@section Completion Matching Control +@noindent + +@noindent +It is possible by use of the +@t{-M} option of the @t{compadd} builtin command to specify how the +characters in the string to be completed (referred to here as the +command line) map onto the characters in the list of matches produced by +the completion code (referred to here as the trial completions). Note +that this is not used if the command line contains a glob pattern and +the @t{GLOB_COMPLETE} option is set or the @t{pattern_match} of the +@t{compstate} special association is set to a non-empty string. + +@noindent +The @var{match-spec} given as the argument to the @t{-M} option (see +@ref{Completion Builtin Commands}) consists of one or more matching descriptions separated by +whitespace. Each description consists of a letter followed by a colon +and then the patterns describing which character sequences on the line match +which character sequences in the trial completion. Any sequence of +characters not handled in this fashion must match exactly, as usual. + +@noindent +The forms of @var{match-spec} understood are as follows. In each case, the +form with an upper case initial character retains the string already +typed on the command line as the final result of completion, while with +a lower case initial character the string on the command line is changed +into the corresponding part of the trial completion. + +@noindent +@table @asis +@item @t{m:}@var{lpat}@t{=}@var{tpat} +@itemx @t{M:}@var{lpat}@t{=}@var{tpat} +Here, @var{lpat} is a pattern that matches on the command line, +corresponding to @var{tpat} which matches in the trial completion. + +@item @t{l:}@var{lanchor}@t{|}@var{lpat}@t{=}@var{tpat} +@itemx @t{L:}@var{lanchor}@t{|}@var{lpat}@t{=}@var{tpat} +@itemx @t{l:}@var{lanchor}@t{||}@var{ranchor}@t{=}@var{tpat} +@itemx @t{L:}@var{lanchor}@t{||}@var{ranchor}@t{=}@var{tpat} +@itemx @t{b:}@var{lpat}@t{=}@var{tpat} +@itemx @t{B:}@var{lpat}@t{=}@var{tpat} +These letters are for patterns that are anchored by another pattern on +the left side. Matching for @var{lpat} and @var{tpat} is as for @t{m} and +@t{M}, but the pattern @var{lpat} matched on the command line must be +preceded by the pattern @var{lanchor}. The @var{lanchor} can be blank to +anchor the match to the start of the command line string; otherwise the +anchor can occur anywhere, but must match in both the command line and +trial completion strings. + +@noindent +If no @var{lpat} is given but a @var{ranchor} is, this matches the gap +between substrings matched by @var{lanchor} and @var{ranchor}. Unlike +@var{lanchor}, the @var{ranchor} only needs to match the trial +completion string. + +@noindent +The @t{b} and @t{B} forms are similar to @t{l} and @t{L} with an empty +anchor, but need to match only the beginning of the word on the command line +or trial completion, respectively. + +@item @t{r:}@var{lpat}@t{|}@var{ranchor}@t{=}@var{tpat} +@itemx @t{R:}@var{lpat}@t{|}@var{ranchor}@t{=}@var{tpat} +@itemx @t{r:}@var{lanchor}@t{||}@var{ranchor}@t{=}@var{tpat} +@itemx @t{R:}@var{lanchor}@t{||}@var{ranchor}@t{=}@var{tpat} +@itemx @t{e:}@var{lpat}@t{=}@var{tpat} +@itemx @t{E:}@var{lpat}@t{=}@var{tpat} +As @t{l}, @t{L}, @t{b} and @t{B}, with the difference that the command +line and trial completion patterns are anchored on the right side. +Here an empty @var{ranchor} and the @t{e} and @t{E} forms force the +match to the end of the command line or trial completion string. + +@item @t{x:} +This form is used to mark the end of matching specifications: +subsequent specifications are ignored. In a single standalone list +of specifications this has no use but where matching specifications +are accumulated, such as from nested function calls, it can allow one +function to override another. + +@end table + +@noindent +Each @var{lpat}, @var{tpat} or @var{anchor} is either an empty string or +consists of a sequence of literal characters (which may be quoted with a +backslash), question marks, character classes, and correspondence +classes; ordinary shell patterns are not used. Literal characters match +only themselves, question marks match any character, and character +classes are formed as for globbing and match any character in the given +set. + +@noindent +Correspondence classes are defined like character classes, but with two +differences: they are delimited by a pair of braces, and negated classes +are not allowed, so the characters @t{!} and @t{^} have no special +meaning directly after the opening brace. They indicate that a range of +characters on the line match a range of characters in the trial +completion, but (unlike ordinary character classes) paired according to +the corresponding position in the sequence. For example, to make any +ASCII lower case letter on the line match the corresponding upper case +letter in the trial completion, you can use `@t{m:@{a-z@}=@{A-Z@}}' +(however, see below for the recommended form for this). More +than one pair of classes can occur, in which case the first class before +the @t{=} corresponds to the first after it, and so on. If one side has +more such classes than the other side, the superfluous classes behave +like normal character classes. In anchor patterns correspondence classes +also behave like normal character classes. + +@noindent +The standard `@t{[:}@var{name}@t{:]}' forms described for standard shell +patterns (see +@ref{Filename Generation}) +may appear in correspondence classes as well as normal character +classes. The only special behaviour in correspondence classes is if +the form on the left and the form on the right are each one of +@t{[:upper:]}, @t{[:lower:]}. In these cases the +character in the word and the character on the line must be the same up +to a difference in case. Hence to make any lower case character on the +line match the corresponding upper case character in the trial +completion you can use `@t{m:@{[:lower:]@}=@{[:upper:]@}}'. Although the +matching system does not yet handle multibyte characters, this is likely +to be a future extension, at which point this syntax will handle +arbitrary alphabets; hence this form, rather than the use of explicit +ranges, is the recommended form. In other cases +`@t{[:}@var{name}@t{:]}' forms are allowed. If the two forms on the left +and right are the same, the characters must match exactly. In remaining +cases, the corresponding tests are applied to both characters, but they +are not otherwise constrained; any matching character in one set goes +with any matching character in the other set: this is equivalent to the +behaviour of ordinary character classes. + +@noindent +The pattern @var{tpat} may also be one or two stars, `@t{*}' or +`@t{**}'. This means that the pattern on the command line can match +any number of characters in the trial completion. In this case the +pattern must be anchored (on either side); in the case of a single +star, the @var{anchor} then determines how much of the trial completion +is to be included --- only the characters up to the next appearance of +the anchor will be matched. With two stars, substrings matched by the +anchor can be matched, too. + +@noindent +Examples: + +@noindent +The keys of the @t{options} association defined by the @t{parameter} +module are the option names in all-lower-case form, without +underscores, and without the optional @t{no} at the beginning even +though the builtins @t{setopt} and @t{unsetopt} understand option names +with upper case letters, underscores, and the optional @t{no}. The +following alters the matching rules so that the prefix @t{no} and any +underscore are ignored when trying to match the trial completions +generated and upper case letters on the line match the corresponding +lower case letters in the words: + +@noindent +@example +compadd -M 'L:|[nN][oO]= M:_= M:@{[:upper:]@}=@{[:lower:]@}' - \ + $@{(k)options@} +@end example + +@noindent +The first part says that the pattern `@t{[nN][oO]}' at the beginning +(the empty anchor before the pipe symbol) of the string on the +line matches the empty string in the list of words generated by +completion, so it will be ignored if present. The second part does the +same for an underscore anywhere in the command line string, and the +third part uses correspondence classes so that any +upper case letter on the line matches the corresponding lower case +letter in the word. The use of the upper case forms of the +specification characters (@t{L} and @t{M}) guarantees that what has +already been typed on the command line (in particular the prefix +@t{no}) will not be deleted. + +@noindent +Note that the use of @t{L} in the first part means that it matches +only when at the beginning of both the command line string and the +trial completion. I.e., the string `@t{_NO_f}' would not be +completed to `@t{_NO_foo}', nor would `@t{NONO_f}' be completed to +`@t{NONO_foo}' because of the leading underscore or the second +`@t{NO}' on the line which makes the pattern fail even though they are +otherwise ignored. To fix this, one would use `@t{B:[nN][oO]=}' +instead of the first part. As described above, this matches at the +beginning of the trial completion, independent of other characters or +substrings at the beginning of the command line word which are ignored +by the same or other @var{match-spec}s. + +@noindent +The second example makes completion case insensitive. This is just +the same as in the option example, except here we wish to retain the +characters in the list of completions: + +@noindent +@example +compadd -M 'm:@{[:lower:]@}=@{[:upper:]@}' ... +@end example + +@noindent +This makes lower case letters match their upper case counterparts. +To make upper case letters match the lower case forms as well: + +@noindent +@example +compadd -M 'm:@{[:lower:][:upper:]@}=@{[:upper:][:lower:]@}' ... +@end example + +@noindent +A nice example for the use of @t{*} patterns is partial word +completion. Sometimes you would like to make strings like `@t{c.s.u}' +complete to strings like `@t{comp.source.unix}', i.e. the word on the +command line consists of multiple parts, separated by a dot in this +example, where each part should be completed separately --- note, +however, that the case where each part of the word, i.e. `@t{comp}', +`@t{source}' and `@t{unix}' in this example, is to be completed from +separate sets of matches +is a different problem to be solved by the implementation of the +completion widget. The example can be handled by: + +@noindent +@example +compadd -M 'r:|.=* r:|=*' \ + - comp.sources.unix comp.sources.misc ... +@end example + +@noindent +The first specification says that @var{lpat} is the empty string, while +@var{anchor} is a dot; @var{tpat} is @t{*}, so this can match anything +except for the `@t{.}' from the anchor in +the trial completion word. So in `@t{c.s.u}', the matcher sees `@t{c}', +followed by the empty string, followed by the anchor `@t{.}', and +likewise for the second dot, and replaces the empty strings before the +anchors, giving `@t{c}[@t{omp}]@t{.s}[@t{ources}]@t{.u}[@t{nix}]', where +the last part of the completion is just as normal. + +@noindent +With the pattern shown above, the string `@t{c.u}' could not be +completed to `@t{comp.sources.unix}' because the single star means +that no dot (matched by the anchor) can be skipped. By using two stars +as in `@t{r:|.=**}', however, `@t{c.u}' could be completed to +`@t{comp.sources.unix}'. This also shows that in some cases, +especially if the anchor is a real pattern, like a character class, +the form with two stars may result in more matches than one would like. + +@noindent +The second specification is needed to make this work when the cursor is +in the middle of the string on the command line and the option +@t{COMPLETE_IN_WORD} is set. In this case the completion code would +normally try to match trial completions that end with the string as +typed so far, i.e. it will only insert new characters at the cursor +position rather than at the end. However in our example we would like +the code to recognise matches which contain extra characters after the +string on the line (the `@t{nix}' in the example). Hence we say that the +empty string at the end of the string on the line matches any characters +at the end of the trial completion. + +@noindent +More generally, the specification + +@noindent +@example +compadd -M 'r:|[.,_-]=* r:|=*' ... +@end example + +@noindent +allows one to complete words with abbreviations before any of the +characters in the square brackets. For example, to +complete @t{veryverylongfile.c} rather than @t{veryverylongheader.h} +with the above in effect, you can just type @t{very.c} before attempting +completion. + +@noindent +The specifications with both a left and a right anchor are useful to +complete partial words whose parts are not separated by some +special character. For example, in some places strings have to be +completed that are formed `@t{LikeThis}' (i.e. the separate parts are +determined by a leading upper case letter) or maybe one has to +complete strings with trailing numbers. Here one could use the simple +form with only one anchor as in: + +@noindent +@example +compadd -M 'r:|[[:upper:]0-9]=* r:|=*' LikeTHIS FooHoo 5foo123 5bar234 +@end example + +@noindent +But with this, the string `@t{H}' would neither complete to `@t{FooHoo}' +nor to `@t{LikeTHIS}' because in each case there is an upper case +letter before the `@t{H}' and that is matched by the anchor. Likewise, +a `@t{2}' would not be completed. In both cases this could be changed +by using `@t{r:|[[:upper:]0-9]=**}', but then `@t{H}' completes to both +`@t{LikeTHIS}' and `@t{FooHoo}' and a `@t{2}' matches the other +strings because characters can be inserted before every upper case +letter and digit. To avoid this one would use: + +@noindent +@example +compadd -M 'r:[^[:upper:]0-9]||[[:upper:]0-9]=** r:|=*' \ + LikeTHIS FooHoo foo123 bar234 +@end example + +@noindent +By using these two anchors, a `@t{H}' matches only upper case `@t{H}'s that +are immediately preceded by something matching the left anchor +`@t{[^[:upper:]0-9]}'. The effect is, of course, that `@t{H}' matches only +the string `@t{FooHoo}', a `@t{2}' matches only `@t{bar234}' and so on. + +@noindent +When using the completion system (see +@ref{Completion System}), users can define match specifications that are to be used for +specific contexts by using the @t{matcher} and @t{matcher-list} +styles. The values for the latter will be used everywhere. + +@noindent +@node Completion Widget Example, , Completion Matching Control, Completion Widgets + +@section Completion Widget Example +@noindent +@cindex completion widgets, example + +@noindent +The first step is to define the widget: + +@noindent +@example +zle -C complete complete-word complete-files +@end example + +@noindent +Then the widget can be bound to a key using the @t{bindkey} builtin +command: + +@noindent +@example +bindkey '^X\t' complete +@end example + +@noindent +After that the shell function @t{complete-files} will be invoked +after typing control-X and TAB. The function should then generate the +matches, e.g.: + +@noindent +@example +complete-files () @{ compadd - * @} +@end example + +@noindent +This function will complete files in the current directory matching the +current word. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/compsys.yo +@node Completion System, Completion Using compctl, Completion Widgets, Top + +@chapter Completion System +@noindent +@cindex completion system +@cindex completion, programmable +@cindex completion, controlling + +@section Description +@noindent + +@noindent +This describes the shell code for the `new' completion system, referred +to as @t{compsys}. It is written in shell functions based on the +features described in +the previous chapter, @ref{Completion Widgets}. + +@noindent +The features are contextual, sensitive to the point at which completion is +started. Many completions are already provided. +For this reason, a user can perform a great many tasks without +knowing any details beyond how to initialize the system, which is +described +in @ref{Initialization}. + +@noindent +The context that decides what completion is to be performed may be +@itemize @bullet + +@item +an argument or option position: these describe the position on the +command line at which completion is requested. For example `first argument +to rmdir, the word being completed names a directory'; + +@item +a special context, denoting an element in the shell's syntax. For example +`a word in command position' or `an array subscript'. + +@end itemize + +@noindent +A full context specification contains other elements, as we shall describe. + +@noindent +Besides commands names and contexts, the system employs two more +concepts, @emph{styles} and @emph{tags}. These provide ways for the user +to configure the system's behaviour. + +@noindent +Tags play a dual role. They serve as a classification system for +the matches, typically indicating a class of object that the user +may need to distinguish. For example, when completing arguments of the +@t{ls} command the user may prefer to try @t{files} before @t{directories}, +so both of these are tags. They also appear as the rightmost +element in a context specification. + +@noindent +Styles modify various operations of the completion system, such as +output formatting, but also what kinds of completers are used (and in +what order), or which tags are examined. Styles may accept arguments +and are manipulated using the @t{zstyle} command described in +@ref{The zsh/zutil Module}. + +@noindent +In summary, tags describe @emph{what} the completion objects are, and style +@t{how} they are to be completed. At various points of execution, the +completion system checks what styles and/or tags are defined for the +current context, and uses that to modify its behavior. The full +description of context handling, which determines how tags and other +elements of the context influence the behaviour of styles, is described +in @ref{Completion System Configuration}. + +@noindent +When a completion is requested, a dispatcher function is called; +see the description of @t{_main_complete} in the list of control functions +below. This dispatcher decides which function should +be called to produce the completions, and calls it. The result is +passed to one or more @emph{completers}, functions that implement +individual completion strategies: simple completion, error correction, +completion with error correction, menu selection, etc. + +@noindent +More generally, the shell functions contained in the completion system are +of two types: +@itemize @bullet + +@item +those beginning `@t{comp}' are to be called directly; there are only +a few of these; + +@item +those beginning `@t{_}' are called by the +completion code. The shell functions of this set, which implement +completion behaviour and may be bound to keystrokes, are referred to +as `widgets'. These proliferate as new completions are required. + +@end itemize + +@noindent +@menu +* Initialization:: +* Completion System Configuration:: +* Control Functions:: +* Bindable Commands:: +* Completion Functions:: +* Completion Directories:: +* Completion System Variables:: +@end menu + +@noindent +@node Initialization, Completion System Configuration, , Completion System + +@section Initialization +@noindent +@findex compinstall +@cindex completion system, installing + +@noindent +If the system was installed completely, it should be enough to +call the shell function @t{compinit} from your initialization file; see the +next section. However, the function @t{compinstall} can be run by a user +to configure various aspects of the completion system. + +@noindent +Usually, @t{compinstall} will insert code into @t{.zshrc}, although if +that is not writable it will save it in another file and tell you that +file's location. Note that it is up to you to make sure that the lines +added to @t{.zshrc} are actually run; you may, for example, need to move +them to an earlier place in the file if @t{.zshrc} usually returns early. +So long as you keep them all together (including the comment lines at the +start and finish), you can rerun @t{compinstall} and it will correctly +locate and modify these lines. Note, however, that any code you add to +this section by hand is likely to be lost if you rerun @t{compinstall}, +although lines using the command `@t{zstyle}' should be gracefully handled. + +@noindent +The new code will take effect next time you start the shell, or run +@t{.zshrc} by hand; there is also an option to make them take effect +immediately. However, if @t{compinstall} has removed definitions, you will +need to restart the shell to see the changes. + +@noindent +To run @t{compinstall} you will need to make sure it is in a directory +mentioned in your @t{fpath} parameter, which should already be the case if +zsh was properly configured as long as your startup files do not remove the +appropriate directories from @t{fpath}. Then it must be autoloaded +(`@t{autoload -U compinstall}' is recommended). You can abort the +installation any time you are being prompted for information, and your +@t{.zshrc} will not be altered at all; changes only take place right at the +end, where you are specifically asked for confirmation. + +@noindent + +@subsection Use of compinit +@noindent +@findex compinit +@cindex completion system, initializing + +@noindent +This section describes the use of @t{compinit} to initialize completion for +the current session when called directly; if you have run +@t{compinstall} it will be called automatically from your @t{.zshrc}. + +@noindent +To initialize the system, the function @t{compinit} should be in a +directory mentioned in the @t{fpath} parameter, and should be autoloaded +(`@t{autoload -U compinit}' is recommended), and then run simply as +`@t{compinit}'. This will define a +few utility functions, arrange for all the necessary shell functions to be +autoloaded, and will then re-define all widgets that do completion to use the +new system. If you use the @t{menu-select} widget, which is part of the +@t{zsh/complist} module, you should make sure that that module is loaded +before the call to @t{compinit} so that that widget is also +re-defined. If completion styles (see below) are set up to perform +expansion as well as completion by default, and the TAB key is bound to +@t{expand-or-complete}, @t{compinit} will rebind it to @t{complete-word}; +this is necessary to use the correct form of expansion. + +@noindent +Should you need to use the original completion commands, you can still +bind keys to the old widgets by putting a `@t{.}' in front of the +widget name, e.g. `@t{.expand-or-complete}'. + +@noindent +To speed up the running of @t{compinit}, it can be made to produce a dumped +configuration that will be read in on future invocations; this is the +default, but can be turned off by calling @t{compinit} with the +option @t{-D}. The dumped file is @t{.zcompdump} in the same +directory as the startup files (i.e. @t{$ZDOTDIR} or @t{$HOME}); +alternatively, an explicit file name can be given by `@t{compinit -d} +@var{dumpfile}'. The next invocation of @t{compinit} will read the dumped +file instead of performing a full initialization. + +@noindent +If the number of completion files changes, @t{compinit} will recognise this +and produce a new dump file. However, if the name of a function or the +arguments in the first line of a @t{#compdef} function (as described below) +change, it is easiest to delete the dump file by hand so that +@t{compinit} will re-create it the next time it is run. The check +performed to see if there are new functions can be omitted by giving +the option @t{-C}. In this case the dump file will only be created if +there isn't one already. + +@noindent +The dumping is actually done by another function, @t{compdump}, but you +will only need to run this yourself if you change the configuration +(e.g. using @t{compdef}) and then want to dump the new one. The name of +the old dumped file will be remembered for this purpose. + +@noindent +If the parameter @t{_compdir} is set, @t{compinit} uses it as a directory +where completion functions can be found; this is only necessary if they are +not already in the function search path. + +@noindent +For security reasons @t{compinit} also checks if the completion system +would use files not owned by root or by the current user, or files in +directories that are world- or group-writable or that are not owned by +root or by the current user. If such files or directories are found, +@t{compinit} will ask if the completion system should really be used. To +avoid these tests and make all files found be used without asking, use the +option @t{-u}, and to make @t{compinit} silently ignore all insecure files +and directories use the option @t{-i}. This security check is skipped +entirely when the @t{-C} option is given. + +@noindent +@findex compaudit +The security check can be retried at any time by running the function +@t{compaudit}. This is the same check used by @t{compinit}, but when it +is executed directly any changes to @t{fpath} are made local to the +function so they do not persist. The directories to be checked may be +passed as arguments; if none are given, @t{compaudit} uses @t{fpath} and +@t{_compdir} to find completion system directories, adding missing ones +to @t{fpath} as necessary. To force a check of exactly the directories +currently named in @t{fpath}, set @t{_compdir} to an empty string before +calling @t{compaudit} or @t{compinit}. + +@noindent +@findex bashcompinit +The function @t{bashcompinit} provides compatibility with bash's programmable +completion system. When run it will define the functions, @t{compgen} and +@t{complete} which correspond to the bash builtins with the same names. +It will then be possible to use completion specifications and functions +written for bash. + +@noindent + +@subsection Autoloaded files +@noindent +@cindex completion system, autoloaded functions + +@noindent +The convention for autoloaded functions used in completion is that they +start with an underscore; as already mentioned, the @t{fpath/FPATH} +parameter must contain the directory in which they are stored. If @t{zsh} +was properly installed on your system, then @t{fpath/FPATH} automatically +contains the required directories for the standard functions. + +@noindent +For incomplete installations, if @t{compinit} does not find enough files +beginning with an underscore (fewer than twenty) in the search path, it +will try to find more by adding the directory @t{_compdir} to the search +path. If that directory has a subdirectory named @t{Base}, all +subdirectories will be added to the path. Furthermore, if the subdirectory +@t{Base} has a subdirectory named @t{Core}, @t{compinit} will add all +subdirectories of the subdirectories to the path: this allows +the functions to be in the same format as in the @t{zsh} source +distribution. + +@noindent +@cindex compdef, use of by compinit +When @t{compinit} is run, it searches all such files accessible via +@t{fpath/FPATH} and reads the first line of each of them. This line should +contain one of the tags described below. Files whose first line does not +start with one of these tags are not considered to be part of the +completion system and will not be treated specially. + +@noindent +The tags are: + +@noindent +@table @asis +@item @t{#compdef} @var{name} ... [ @t{-}@{@t{p}|@t{P}@} @var{pattern} ... [ @t{-N} @var{name} ... ] ] +The file will be made autoloadable and the function defined +in it will be called when completing @var{name}s, each of which is +either the name of a command whose arguments are to be completed or one of +a number of special contexts in the form @t{-}@var{context}@t{-} described +below. + +@noindent +Each @var{name} may also be of the form `@var{cmd}@t{=}@var{service}'. +When completing the command @var{cmd}, the function typically behaves as +if the command (or special context) @var{service} was being completed +instead. This provides a way of altering the behaviour of functions +that can perform many different completions. It is implemented +by setting the parameter @t{$service} when calling the function; +the function may choose to interpret this how it wishes, and simpler +functions will probably ignore it. + +@noindent +If the @t{#compdef} line contains one of the options @t{-p} or @t{-P}, +the words following are taken to be patterns. The function will be +called when completion is attempted for a command or context that matches +one of the patterns. The options @t{-p} and @t{-P} are used to specify +patterns to be tried before or after other completions respectively. +Hence @t{-P} may be used to specify default actions. + +@noindent +The option @t{-N} is used after a list following @t{-p} or @t{-P}; it +specifies that remaining words no longer define patterns. It is +possible to toggle between the three options as many times as necessary. + +@item @t{#compdef -k} @var{style key-sequence} ... +This option creates a widget behaving like the +builtin widget @var{style} and binds it to the given @var{key-sequence}s, +if any. The @var{style} must be one of the builtin widgets that perform +completion, namely @t{complete-word}, @t{delete-char-or-list}, +@t{expand-or-complete}, @t{expand-or-complete-prefix}, @t{list-choices}, +@t{menu-complete}, @t{menu-expand-or-complete}, or +@t{reverse-menu-complete}. If the @t{zsh/complist} module is loaded (see +@ref{The zsh/complist Module}) the widget @t{menu-select} is also available. + +@noindent +When one of the @var{key-sequence}s is typed, the function in the file will +be invoked to generate the matches. Note that a key will not be re-bound +if it already was (that is, was bound to something other than +@t{undefined-key}). The widget created has the same name as the file and +can be bound to any other keys using @t{bindkey} as usual. + +@item @t{#compdef -K} @var{widget-name} @var{style} @var{key-sequence} [ @var{name} @var{style} @var{seq} ... ] +This is similar to @t{-k} except that only one @var{key-sequence} +argument may be given for each @var{widget-name} @var{style} pair. +However, the entire set of three arguments may be repeated with a +different set of arguments. Note in particular that the +@var{widget-name} must be distinct in each set. If it does not begin with +`@t{_}' this will be added. The @var{widget-name} should not clash with +the name of any existing widget: names based on the name of the function +are most useful. For example, + +@noindent +@example +#compdef -K _foo_complete complete-word "^X^C" \ + _foo_list list-choices "^X^D" +@end example + +@noindent +(all on one line) defines a widget @t{_foo_complete} for completion, bound +to `@t{^X^C}', and a widget @t{_foo_list} for listing, bound to `@t{^X^D}'. + +@item @t{#autoload} [ @var{options} ] +Functions with the @t{#autoload} tag are marked for autoloading but +are not otherwise treated specially. Typically they are to be called +from within one of the completion functions. Any @var{options} supplied +will be passed to the @t{autoload} builtin; a typical use is @t{+X} to +force the function to be loaded immediately. Note that the @t{-U} and +@t{-z} flags are always added implicitly. + +@end table + +@noindent +The @t{#} is part of the tag name and no white space is allowed after it. +The @t{#compdef} tags use the @t{compdef} function described below; the +main difference is that the name of the function is supplied implicitly. + +@noindent +The special contexts for which completion functions can be defined are: + +@noindent +@table @asis +@kindex -array-value-, completion context +@item @t{-array-value-} +The right hand side of an array-assignment +(`@var{name}@t{=(}@var{...}@t{)}') + +@kindex -brace-parameter-, completion context +@item @t{-brace-parameter-} +The name of a parameter expansion within braces (`@t{$@{}@var{...}@t{@}}') + +@kindex -assign-parameter-, completion context +@item @t{-assign-parameter-} +The name of a parameter in an assignment, i.e. on the left hand side of +an `@t{=}' + +@kindex -command-, completion context +@item @t{-command-} +A word in command position + +@kindex -condition-, completion context +@item @t{-condition-} +A word inside a condition (`@t{[[}@var{...}@t{]]}') + +@kindex -default-, completion context +@item @t{-default-} +Any word for which no other completion is defined + +@kindex -equal-, completion context +@item @t{-equal-} +A word beginning with an equals sign + +@kindex -first-, completion context +@item @t{-first-} +This is tried before any other completion function. The function called +may set the @t{_compskip} parameter to one of various values: +@t{all}: no further completion is attempted; a string +containing the substring @t{patterns}: no pattern completion functions +will be called; a string containing @t{default}: the +function for the `@t{-default-}' context will not be called, but +functions defined for commands will be. + +@kindex -math-, completion context +@item @t{-math-} +Inside mathematical contexts, such as +`@t{((}@var{...}@t{))}' + +@kindex -parameter-, completion context +@item @t{-parameter-} +The name of a parameter expansion (`@t{$}@var{...}') + +@kindex -redirect-, completion context +@item @t{-redirect-} +The word after a redirection operator. + +@kindex -subscript-, completion context +@item @t{-subscript-} +The contents of a parameter subscript. + +@kindex -tilde-, completion context +@item @t{-tilde-} +After an initial tilde (`@t{~}'), but before the first slash +in the word. + +@kindex -value-, completion context +@item @t{-value-} +On the right hand side of an assignment. + +@end table + +@noindent +Default implementations are supplied for each of these +contexts. In most cases the context @t{-}@var{context}@t{-} is +implemented by a corresponding function @t{_}@var{context}, for example +the context `@t{-tilde-}' and the function `@t{_tilde}'). + +@noindent +The contexts @t{-redirect-} and @t{-value-} allow extra context-specific +information. (Internally, this is handled by the functions for each +context calling the function @t{_dispatch}.) The extra +information is added separated by commas. + +@noindent +For the @t{-redirect-} context, the extra information is in the form +`@t{-redirect-,}@var{op}@t{,}@var{command}', where @var{op} is the +redirection operator and @var{command} is the name of the command on +the line. If there is no command on the line yet, the @var{command} +field will be empty. + +@noindent +For the @t{-value-} context, the form is +`@t{-value-,}@var{name}@t{,}@var{command}', where @var{name} is the name of +the parameter on the left hand side of the assignment. +In the case of elements of an associative array, for +example `@t{assoc=(key <TAB>}', @var{name} is expanded to +`@var{name}@t{-}@var{key}'. In certain special contexts, such as +completing after `@t{make CFLAGS=}', the @var{command} part gives the +name of the command, here @t{make}; otherwise it is empty. + +@noindent +It is not necessary to define fully specific completions as the +functions provided will try to generate completions by progressively +replacing the elements with `@t{-default-}'. For example, when +completing after `@t{foo=<TAB>}', @t{_value} will try the names +`@t{-value-,foo,}' (note the empty @var{command} part), +`@t{-value-,foo,-default-}' and`@t{-value-,-default-,-default-}', in +that order, until it finds a function to handle the context. + +@noindent +As an example: + +@noindent +@example +compdef '_files -g "*.log"' '-redirect-,2>,-default-' +@end example + +@noindent +completes files matching `@t{*.log}' after `@t{2> <TAB>}' for any +command with no more specific handler defined. + +@noindent +Also: + +@noindent +@example +compdef _foo -value-,-default-,-default- +@end example + +@noindent +specifies that @t{_foo} provides completions for the values of +parameters for which no special function has been defined. This is +usually handled by the function @t{_value} itself. + +@noindent +The same lookup rules are used when looking up styles (as described +below); for example + +@noindent +@example +zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log' +@end example + +@noindent +is another way to make completion after `@t{2> <TAB>}' complete files +matching `@t{*.log}'. + +@noindent + +@subsection Functions +@noindent + +@noindent +The following function is defined by @t{compinit} and may be called +directly. + +@noindent +@findex compdef +@cindex completion system, adding definitions +@table @asis + +@item @t{compdef} [ @t{-ane} ] @var{function name} ... [ @t{-}@{@t{p}|@t{P}@} @var{pattern} ... [ @t{-N} @var{name} ...]] +@itemx @t{compdef -d} @var{name} ... +@itemx @t{compdef -k} [ @t{-an} ] @var{function style key-sequence} [ @var{key-sequence} ... ] +@itemx @t{compdef -K} [ @t{-an} ] @var{function name style key-seq} [ @var{name style seq} ... ] +The first form defines the @var{function} to call for completion in the +given contexts as described for the @t{#compdef} tag above. + +@noindent +Alternatively, all the arguments may have the form +`@var{cmd}@t{=}@var{service}'. Here @var{service} should already have been +defined by `@var{cmd1}@t{=}@var{service}' lines in @t{#compdef} files, as +described above. The argument for @var{cmd} will be completed in the +same way as @var{service}. + +@noindent +The @var{function} argument may alternatively be a string containing +almost any shell code. If the string contains an equal sign, the above +will take precedence. The option @t{-e} may be used to specify the first +argument is to be evaluated as shell code even if it contains an equal +sign. The string will be executed using the @t{eval} builtin command to +generate completions. This provides a way of avoiding having to define +a new completion function. For example, to complete files ending in +`@t{.h}' as arguments to the command @t{foo}: + +@noindent +@example +compdef '_files -g "*.h"' foo +@end example + +@noindent +The option @t{-n} prevents any completions already defined for the +command or context from being overwritten. + +@noindent +The option @t{-d} deletes any completion defined for the command or +contexts listed. + +@noindent +The @var{name}s may also contain @t{-p}, @t{-P} and @t{-N} options as +described for the @t{#compdef} tag. The effect on the argument list is +identical, switching between definitions of patterns tried initially, +patterns tried finally, and normal commands and contexts. + +@noindent +The parameter @t{$_compskip} may be set by any function defined for a +pattern context. If it is set to a value containing the substring +`@t{patterns}' none of the pattern-functions will be called; if it is +set to a value containing the substring `@t{all}', no other function +will be called. Setting @t{$_compskip} in this manner is of particular +utility when using the @t{-p} option, as otherwise the dispatcher will +move on to additional functions (likely the default one) after calling +the pattern-context one, which can mangle the display of completion +possibilities if not handled properly. + +@noindent +The form with @t{-k} defines a widget with the same name as the @var{function} +that will be called for each of the @var{key-sequence}s; this is like the +@t{#compdef -k} tag. The function should generate the completions needed +and will otherwise behave like the builtin widget whose name is given as +the @var{style} argument. The widgets usable for this are: +@t{complete-word}, @t{delete-char-or-list}, @t{expand-or-complete}, +@t{expand-or-complete-prefix}, @t{list-choices}, @t{menu-complete}, +@t{menu-expand-or-complete}, and @t{reverse-menu-complete}, as well as +@t{menu-select} if the @t{zsh/complist} module is loaded. The option @t{-n} +prevents the key being bound if it is already to bound to something other +than @t{undefined-key}. + +@noindent +The form with @t{-K} is similar and defines multiple widgets based on the +same @var{function}, each of which requires the set of three arguments +@var{name}, @var{style} and @var{key-seq}uence, where the latter two are as +for @t{-k} and the first must be a unique widget name beginning with an +underscore. + +@noindent +Wherever applicable, the @t{-a} option makes the @var{function} +autoloadable, equivalent to @t{autoload -U }@var{function}. + +@end table + +@noindent +The function @t{compdef} can be used to associate existing completion +functions with new commands. For example, + +@noindent +@example +compdef _pids foo +@end example + +@noindent +uses the function @t{_pids} to complete process IDs for the command @t{foo}. + +@noindent +Note also the @t{_gnu_generic} function described below, which can be +used to complete options for commands that understand the +`@t{-}@t{-help}' option. + +@noindent +@node Completion System Configuration, Control Functions, Initialization, Completion System + +@section Completion System Configuration +@noindent +@cindex completion system, configuration + +@noindent +This section gives a short overview of how the completion system works, +and then more detail on how users can configure how and when matches are +generated. + +@noindent + +@subsection Overview +@noindent + +@noindent +When completion is attempted somewhere on the command line the +completion system begins building the context. The context represents +everything that the shell knows about the meaning of the command line +and the significance of the cursor position. This takes account of a +number of things including the command word (such as `@t{grep}' or +`@t{zsh}') and options to which the current word may be an argument +(such as the `@t{-o}' option to @t{zsh} which takes a shell option as an +argument). + +@noindent +The context starts out very generic ("we are beginning a completion") +and becomes more specific as more is learned ("the current word is in a +position that is usually a command name" or "the current word might be a +variable name" and so on). Therefore the context will vary during the +same call to the completion system. + +@noindent +This context information is condensed into a string consisting of multiple +fields separated by colons, referred to simply as `the context' in the +remainder of the documentation. Note that a user of the completion system +rarely needs to compose a context string, unless for example a new +function is being written to perform completion for a new command. What a +user may need to do is compose a @emph{style} pattern, which is matched +against a context when needed to look up context-sensitive options that +configure the completion system. + +@noindent +The next few paragraphs explain how a context is composed within the +completion function suite. Following that is discussion of how @emph{styles} +are defined. Styles determine such things as how the matches are +generated, similarly to shell options but with much more control. They +are defined with the @t{zstyle} builtin command (@ref{The zsh/zutil Module}). + +@noindent +The context string always consists of a fixed set of fields, separated +by colons and with a leading colon before the first. Fields which are +not yet known are left empty, but the surrounding colons appear anyway. +The fields are always in the order +@t{:completion:}@var{function}@t{:}@var{completer}@t{:}@var{command}@t{:}@var{argument}@t{:}@var{tag}. These have the following meaning: + +@noindent +@itemize @bullet + +@item +The literal string @t{completion}, saying that this style is used by +the completion system. This distinguishes the context from those used +by, for example, zle widgets and ZFTP functions. + +@item +The @var{function}, if completion is called from a named widget rather +than through the normal completion system. Typically this is blank, but +it is set by special widgets such as @t{predict-on} and the various +functions in the @t{Widget} directory of the distribution to the name of +that function, often in an abbreviated form. + +@item +The @var{completer} currently active, the name of the function without the +leading underscore and with other underscores converted to hyphens. A +`completer' is in overall control of how completion is to be performed; +`@t{complete}' is the simplest, but other completers exist to perform +related tasks such as correction, or to modify the behaviour of a later +completer. See +@ref{Control Functions} +for more information. + +@item +The @var{command} or a special @t{-}@var{context}@t{-}, just at it appears +following the @t{#compdef} tag or the @t{compdef} function. Completion +functions for commands that have sub-commands usually modify this field +to contain the name of the command followed by a minus sign and the +sub-command. For example, the completion function for the @t{cvs} +command sets this field to @t{cvs-add} when completing arguments to +the @t{add} subcommand. + +@item +The @var{argument}; this indicates which command line or option argument +we are completing. For command arguments this generally takes the form +@t{argument-}@var{n}, where @var{n} is the number of the argument, +and for arguments to options the form @t{option-}@var{opt}@t{-}@var{n} +where @var{n} is the number of the argument to option @var{opt}. However, +this is only the case if the command line is parsed with standard +UNIX-style options and arguments, so many completions do not set this. + +@item +The @var{tag}. As described previously, tags are used to discriminate between +the types of matches a completion function can generate in a certain context. +Any completion function may use any tag name it likes, but a list of the +more common ones is given below. + +@end itemize + +@noindent +The context is gradually put together as the functions are executed, starting +with the main entry point, which adds @t{:completion:} and the @var{function} +element if necessary. The completer then adds the @var{completer} element. +The contextual completion adds the @var{command} and @var{argument} options. +Finally, the @var{tag} is added when the types of completion are known. +For example, the context name + +@noindent +@example +@t{:completion::complete:dvips:option-o-1:files} +@end example + +@noindent +says that normal completion was attempted as the first argument to the +option @t{-o} of the command @t{dvips}: + +@noindent +@example +@t{dvips -o ...} +@end example + +@noindent +and the completion function will generate filenames. + +@noindent +Usually completion will be tried for all possible tags in an order given +by the completion function. However, this can be altered by using the +@t{tag-order} style. Completion is then restricted to the list of given +tags in the given order. + +@noindent +The @t{_complete_help} bindable command shows all the contexts and tags +available for completion at a particular point. This provides an easy +way of finding information for @t{tag-order} and other styles. It is +described in +@ref{Bindable Commands}. + +@noindent +When looking up styles the completion system uses full context names, +including the tag. Looking up the value of a style therefore consists of +two things: the context, which is matched to the most specific (best +fitting) style pattern, and the name of the style itself, which must be +matched exactly. The following examples demonstrate that style patterns +may be loosely defined for styles that apply broadly, or as tightly +defined as desired for styles that apply in narrower circumstances. + +@noindent +For example, many completion functions can generate matches in a +simple and a verbose form and use the @t{verbose} style to decide +which form should be used. To make all such functions use the verbose form, +put + +@noindent +@example +zstyle ':completion:*' verbose yes +@end example + +@noindent +in a startup file (probably @t{.zshrc}). +This gives the @t{verbose} style the value @t{yes} in every +context inside the completion system, unless that context has a more +specific definition. It is best to avoid giving the context as `@t{*}' +in case the style has some meaning outside the completion system. + +@noindent +Many such general purpose styles can be configured simply by using the +@t{compinstall} function. + +@noindent +A more specific example of the use of the @t{verbose} style is by the +completion for the @t{kill} builtin. If the style is set, the builtin +lists full job texts and process command lines; otherwise it shows the +bare job numbers and PIDs. To turn the style off for this use only: + +@noindent +@example +zstyle ':completion:*:*:kill:*:*' verbose no +@end example + +@noindent +For even more control, the style can use one of the tags `@t{jobs}' or +`@t{processes}'. To turn off verbose display only for jobs: + +@noindent +@example +zstyle ':completion:*:*:kill:*:jobs' verbose no +@end example + +@noindent +The @t{-e} option to @t{zstyle} even allows completion function code to +appear as the argument to a style; this requires some understanding of +the internals of completion functions (see +@ref{Completion Widgets})). For example, + +@noindent +@example +@t{zstyle -e ':completion:*' hosts 'reply=($myhosts)'} +@end example + +@noindent +This forces the value of the @t{hosts} style to be read from the +variable @t{myhosts} each time a host name is needed; this is useful +if the value of @t{myhosts} can change dynamically. +For another useful example, see the example in the description of the +@t{file-list} style below. This form can be +slow and should be avoided for commonly examined styles such +as @t{menu} and @t{list-rows-first}. + +@noindent +Note that the order in which styles are @emph{defined} does not matter; the +style mechanism uses the most specific possible match for a particular +style to determine the set of values. More precisely, strings are +preferred over patterns (for example, `@t{:completion::complete:::foo}' is +more specific than `@t{:completion::complete:::*'}), and longer patterns are +preferred over shorter patterns. + +@noindent +A good rule of thumb is that any completion style pattern that needs to +include more than one wildcard (@t{*}) and that does not end in a tag +name, should include all six colons (@t{:}), possibly surrounding +additional wildcards. + +@noindent +Style names like those of tags are arbitrary and depend on the completion +function. However, the following two sections list some of the most +common tags and styles. + +@noindent + +@subsection Standard Tags +@noindent +@cindex completion system, tags + +@noindent +Some of the following are only used when looking up particular styles +and do not refer to a type of match. + +@noindent +@table @asis +@kindex accounts, completion tag +@item @t{accounts} +used to look up the @t{users-hosts} style + +@kindex all-expansions, completion tag +@item @t{all-expansions} +used by the @t{_expand} completer when adding the single string containing +all possible expansions + +@kindex all-files, completion tag +@item @t{all-files} +for the names of all files (as distinct from a particular subset, see the +@t{globbed-files} tag). + +@kindex arguments, completion tag +@item @t{arguments} +for arguments to a command + +@kindex arrays, completion tag +@item @t{arrays} +for names of array parameters + +@kindex association-keys, completion tag +@item @t{association-keys} +for keys of associative arrays; used when completing inside a +subscript to a parameter of this type + +@kindex bookmarks, completion tag +@item @t{bookmarks} +when completing bookmarks (e.g. for URLs and the @t{zftp} function suite) + +@kindex builtins, completion tag +@item @t{builtins} +for names of builtin commands + +@kindex characters, completion tag +@item @t{characters} +for single characters in arguments of commands such as @t{stty}. Also used +when completing character classes after an opening bracket + +@kindex colormapids, completion tag +@item @t{colormapids} +for X colormap ids + +@kindex colors, completion tag +@item @t{colors} +for color names + +@kindex commands, completion tag +@item @t{commands} +for names of external commands. Also used by complex commands such as +@t{cvs} when completing names subcommands. + +@kindex contexts, completion tag +@item @t{contexts} +for contexts in arguments to the @t{zstyle} builtin command + +@kindex corrections, completion tag +@item @t{corrections} +used by the @t{_approximate} and @t{_correct} completers for possible +corrections + +@kindex cursors, completion tag +@item @t{cursors} +for cursor names used by X programs + +@kindex default, completion tag +@item @t{default} +used in some contexts to provide a way of supplying a default when more +specific tags are also valid. Note that this tag is +used when only the @var{function} field of the context name is set + +@kindex descriptions, completion tag +@item @t{descriptions} +used when looking up the value of the @t{format} style to generate +descriptions for types of matches + +@kindex devices, completion tag +@item @t{devices} +for names of device special files + +@kindex directories, completion tag +@item @t{directories} +for names of directories --- @t{local-directories} is used instead +when completing arguments of @t{cd} and related builtin commands when +the @t{cdpath} array is set + +@kindex directory-stack, completion tag +@item @t{directory-stack} +for entries in the directory stack + +@kindex displays, completion tag +@item @t{displays} +for X display names + +@kindex domains, completion tag +@item @t{domains} +for network domains + +@kindex email-*, completion tag +@item @t{email-}@var{plugin} +for email addresses from the `@t{_email-}@var{plugin}' backend of @t{_email_addresses} + +@kindex expansions, completion tag +@item @t{expansions} +used by the @t{_expand} completer for individual words (as opposed to +the complete set of expansions) resulting from the expansion of a word +on the command line + +@kindex extensions, completion tag +@item @t{extensions} +for X server extensions + +@kindex file-descriptors, completion tag +@item @t{file-descriptors} +for numbers of open file descriptors + +@kindex files, completion tag +@item @t{files} +the generic file-matching tag used by functions completing filenames + +@kindex fonts, completion tag +@item @t{fonts} +for X font names + +@kindex fstypes, completion tag +@item @t{fstypes} +for file system types (e.g. for the @t{mount} command) + +@kindex functions, completion tag +@item @t{functions} +names of functions --- normally shell functions, although certain +commands may understand other kinds of function + +@kindex globbed-files, completion tag +@item @t{globbed-files} +for filenames when the name has been generated by pattern matching + +@kindex groups, completion tag +@item @t{groups} +for names of user groups + +@kindex history-words, completion tag +@item @t{history-words} +for words from the history + +@kindex hosts, completion tag +@item @t{hosts} +for hostnames + +@kindex indexes, completion tag +@item @t{indexes} +for array indexes + +@kindex jobs, completion tag +@item @t{jobs} +for jobs (as listed by the `@t{jobs}' builtin) + +@kindex interfaces, completion tag +@item @t{interfaces} +for network interfaces + +@kindex keymaps, completion tag +@item @t{keymaps} +for names of zsh keymaps + +@kindex keysyms, completion tag +@item @t{keysyms} +for names of X keysyms + +@kindex libraries, completion tag +@item @t{libraries} +for names of system libraries + +@kindex limits, completion tag +@item @t{limits} +for system limits + +@kindex local-directories, completion tag +@item @t{local-directories} +for names of directories that are subdirectories of the current working +directory when completing arguments of @t{cd} and related builtin +commands (compare @t{path-directories}) --- when the @t{cdpath} +array is unset, @t{directories} is used instead + +@kindex manuals, completion tag +@item @t{manuals} +for names of manual pages + +@kindex mailboxes, completion tag +@item @t{mailboxes} +for e-mail folders + +@kindex maps, completion tag +@item @t{maps} +for map names (e.g. NIS maps) + +@kindex messages, completion tag +@item @t{messages} +used to look up the @t{format} style for messages + +@kindex modifiers, completion tag +@item @t{modifiers} +for names of X modifiers + +@kindex modules, completion tag +@item @t{modules} +for modules (e.g. @t{zsh} modules) + +@kindex my-accounts, completion tag +@item @t{my-accounts} +used to look up the @t{users-hosts} style + +@kindex named-directories, completion tag +@item @t{named-directories} +for named directories (you wouldn't have guessed that, would you?) + +@kindex names, completion tag +@item @t{names} +for all kinds of names + +@kindex newsgroups, completion tag +@item @t{newsgroups} +for USENET groups + +@kindex nicknames, completion tag +@item @t{nicknames} +for nicknames of NIS maps + +@kindex options, completion tag +@item @t{options} +for command options + +@kindex original, completion tag +@item @t{original} +used by the @t{_approximate}, @t{_correct} and @t{_expand} completers when +offering the original string as a match + +@kindex other-accounts, completion tag +@item @t{other-accounts} +used to look up the @t{users-hosts} style + +@kindex other-files, completion tag +@item @t{other-files} +for the names of any non-directory files. This is used instead +of @t{all-files} when the @t{list-dirs-first} style is in effect. + +@kindex packages, completion tag +@item @t{packages} +for packages (e.g. @t{rpm} or installed @t{Debian} packages) + +@kindex parameters, completion tag +@item @t{parameters} +for names of parameters + +@kindex path-directories, completion tag +@item @t{path-directories} +for names of directories found by searching the @t{cdpath} array when +completing arguments of @t{cd} and related builtin commands (compare +@t{local-directories}) + +@kindex paths, completion tag +@item @t{paths} +used to look up the values of the @t{expand}, @t{ambiguous} and +@t{special-dirs} styles + +@kindex pods, completion tag +@item @t{pods} +for perl pods (documentation files) + +@kindex ports, completion tag +@item @t{ports} +for communication ports + +@kindex prefixes, completion tag +@item @t{prefixes} +for prefixes (like those of a URL) + +@kindex printers, completion tag +@item @t{printers} +for print queue names + +@kindex processes, completion tag +@item @t{processes} +for process identifiers + +@kindex processes-names, completion tag +@item @t{processes-names} +used to look up the @t{command} style when generating the names of +processes for @t{killall} + +@kindex sequences, completion tag +@item @t{sequences} +for sequences (e.g. @t{mh} sequences) + +@kindex sessions, completion tag +@item @t{sessions} +for sessions in the @t{zftp} function suite + +@kindex signals, completion tag +@item @t{signals} +for signal names + +@kindex strings, completion tag +@item @t{strings} +for strings (e.g. the replacement strings for the @t{cd} builtin +command) + +@kindex styles, completion tag +@item @t{styles} +for styles used by the zstyle builtin command + +@kindex suffixes, completion tag +@item @t{suffixes} +for filename extensions + +@kindex tags, completion tag +@item @t{tags} +for tags (e.g. @t{rpm} tags) + +@kindex targets, completion tag +@item @t{targets} +for makefile targets + +@kindex time-zones, completion tag +@item @t{time-zones} +for time zones (e.g. when setting the @t{TZ} parameter) + +@kindex types, completion tag +@item @t{types} +for types of whatever (e.g. address types for the @t{xhost} command) + +@kindex urls, completion tag +@item @t{urls} +used to look up the @t{urls} and @t{local} styles when completing URLs + +@kindex users, completion tag +@item @t{users} +for usernames + +@kindex values, completion tag +@item @t{values} +for one of a set of values in certain lists + +@kindex variant, completion tag +@item @t{variant} +used by @t{_pick_variant} to look up the command to run when determining +what program is installed for a particular command name. + +@kindex visuals, completion tag +@item @t{visuals} +for X visuals + +@kindex warnings, completion tag +@item @t{warnings} +used to look up the @t{format} style for warnings + +@kindex widgets, completion tag +@item @t{widgets} +for zsh widget names + +@kindex windows, completion tag +@item @t{windows} +for IDs of X windows + +@kindex zsh-options, completion tag +@item @t{zsh-options} +for shell options + +@end table + +@noindent + +@subsection Standard Styles +@noindent +@cindex completion system, styles + +@noindent +Note that the values of several of these styles represent boolean +values. Any of the strings `@t{true}', `@t{on}', +`@t{yes}', and `@t{1}' can be used for the value `true' and +any of the strings `@t{false}', `@t{off}', `@t{no}', and `@t{0}' for +the value `false'. The behavior for any other value is undefined +except where explicitly mentioned. The default value may +be either `true' or `false' if the style is not set. + +@noindent +Some of these styles are tested first for every possible tag +corresponding to a type of match, and if no style was found, for the +@t{default} tag. The most notable styles of this type are @t{menu}, +@t{list-colors} and styles controlling completion listing such as +@t{list-packed} and @t{last-prompt}. When tested for the @t{default} +tag, only the @var{function} field of the context will be set so that +a style using the @t{default} tag will normally be defined along the lines of: + +@noindent +@example +zstyle ':completion:*:default' menu ... +@end example + +@noindent +@table @asis +@kindex accept-exact, completion style +@item @t{accept-exact} +This is tested for the @t{default} tag in addition to the tags valid for +the current context. If it is set to `true' and any of the trial +matches is the same as the string on the command line, this match will +immediately be accepted (even if it would otherwise be considered +ambiguous). + +@noindent +When completing pathnames (where the tag used is `@t{paths}') +this style accepts any number of patterns as the value in addition to +the boolean values. Pathnames matching one of these +patterns will be accepted immediately even if the command line contains +some more partially typed pathname components and these match no file +under the directory accepted. + +@noindent +This style is also used by the @t{_expand} completer to decide if +words beginning with a tilde or parameter expansion should be +expanded. For example, if there are parameters +@t{foo} and @t{foobar}, the string `@t{$foo}' will only be expanded if +@t{accept-exact} is set to `true'; otherwise the completion system will +be allowed to complete @t{$foo} to @t{$foobar}. If the style is set to +`@t{continue}', @t{_expand} will add the expansion as a match and the completion +system will also be allowed to continue. + +@kindex accept-exact-dirs, completion style +@item @t{accept-exact-dirs} +This is used by filename completion. Unlike @t{accept-exact} it is +a boolean. By default, filename completion examines all components +of a path to see if there are completions of that component, even if +the component matches an existing directory. For example, when +completion after @t{/usr/bin/}, the function examines possible +completions to @t{/usr}. + +@noindent +When this style is `true', any prefix of a path that matches an existing +directory is accepted without any attempt to complete it further. +Hence, in the given example, the path @t{/usr/bin/} is accepted +immediately and completion tried in that directory. + +@noindent +This style is also useful when completing after directories that +magically appear when referenced, such as ZFS @t{.zfs} directories +or NetApp @t{.snapshot} directories. When the style is set the +shell does not check for the existence of the directory within the +parent directory. + +@noindent +If you wish to inhibit this behaviour entirely, set the @t{path-completion} +style (see below) to `false'. + +@kindex add-space, completion style +@item @t{add-space} +This style is used by the @t{_expand} completer. If it is `true' (the +default), a space will be inserted after all words resulting from the +expansion, or a slash in the case of directory names. If the value +is `@t{file}', the completer will only add a space +to names of existing files. Either a boolean `true' or the value +`@t{file}' may be combined with `@t{subst}', in which case the completer +will not add a space to words generated from the expansion of a +substitution of the form `@t{$(}@var{...}@t{)}' or `@t{$@{}@var{...}@t{@}}'. + +@noindent +The @t{_prefix} completer uses this style as a simple boolean value +to decide if a space should be inserted before the suffix. + +@kindex ambiguous, completion style +@item @t{ambiguous} +This applies when completing non-final components of filename paths, in +other words those with a trailing slash. If it is set, the cursor is +left after the first ambiguous component, even if menu completion is in +use. The style is always tested with the @t{paths} tag. + +@kindex assign-list, completion style +@item @t{assign-list} +When completing after an equals sign that is being treated as an +assignment, the completion system normally completes only one filename. +In some cases the value may be a list of filenames separated by colons, +as with @t{PATH} and similar parameters. This style can be set to a +list of patterns matching the names of such parameters. + +@noindent +The default is to complete lists when the word on the line already +contains a colon. + +@kindex auto-description, completion style +@item @t{auto-description} +If set, this style's value will be used as the description for options that +are not described by the completion functions, but that have exactly +one argument. The sequence `@t{%d}' in the value will be replaced by +the description for this argument. Depending on personal preferences, +it may be useful to set this style to something like `@t{specify: %d}'. +Note that this may not work for some commands. + +@kindex avoid-completer, completion style +@item @t{avoid-completer} +This is used by the @t{_all_matches} completer to decide if the string +consisting of all matches should be added to the list currently being +generated. Its value is a list of names of completers. If any of +these is the name of the completer that generated the matches in this +completion, the string will not be added. + +@noindent +The default value for this style is `@t{_expand _old_list _correct +_approximate}', i.e. it contains the completers for which a string +with all matches will almost never be wanted. + +@kindex cache-path, completion style +@item @t{cache-path} +This style defines the path where any cache files containing dumped +completion data are stored. It defaults to `@t{$ZDOTDIR/.zcompcache}', or +`@t{$HOME/.zcompcache}' if @t{$ZDOTDIR} is not defined. The completion +cache will not be used unless the @t{use-cache} style is set. + +@kindex cache-policy, completion style +@item @t{cache-policy} +This style defines the function that will be used to determine whether +a cache needs rebuilding. See the section on the @t{_cache_invalid} +function below. + +@kindex call-command, completion style +@item @t{call-command} +This style is used in the function for commands such as @t{make} and +@t{ant} where calling the command directly to generate matches suffers +problems such as being slow or, as in the case of @t{make} can +potentially cause actions in the makefile to be executed. If it is set +to `true' the command is called to generate matches. The default value +of this style is `false'. + +@kindex command, completion style +@item @t{command} +In many places, completion functions need to call external commands to +generate the list of completions. This style can be used to override the +command that is called in some such cases. The elements of the value are +joined with spaces to form a command line to execute. The value can also +start with a hyphen, in which case the usual command will be added to the +end; this is most useful for putting `@t{builtin}' or `@t{command}' in +front to make sure the appropriate version of a command is called, for +example to avoid calling a shell function with the same name as an external +command. + +@noindent +As an example, the completion function for process IDs uses this +style with the @t{processes} tag to generate the IDs to complete and +the list of processes to display (if the @t{verbose} style is `true'). +The list produced by the command should look like the output of the +@t{ps} command. The first line is not displayed, but is searched for +the string `@t{PID}' (or `@t{pid}') to find the position of the +process IDs in the following lines. If the line does not contain +`@t{PID}', the first numbers in each of the other lines are taken as the +process IDs to complete. + +@noindent +Note that the completion function generally has to call the specified +command for each attempt to generate the completion list. Hence +care should be taken to specify only commands that take a short +time to run, and in particular to avoid any that may never terminate. + +@kindex command-path, completion style +@item @t{command-path} +This is a list of directories to search for commands to complete. The +default for this style is the value of the special parameter @t{path}. + +@kindex commands, completion style +@item @t{commands} +This is used by the function completing sub-commands for the system +initialisation scripts (residing in @t{/etc/init.d} or somewhere not +too far away from that). Its values give the default commands to +complete for those commands for which the completion function isn't +able to find them out automatically. The default for this style are +the two strings `@t{start}' and `@t{stop}'. + +@kindex complete, completion style +@item @t{complete} +This is used by the @t{_expand_alias} function when invoked as a +bindable command. If set to `true' and the word on the command +line is not the name of an alias, matching alias names will be +completed. + +@kindex complete-options, completion style +@item @t{complete-options} +This is used by the completer for @t{cd}, @t{chdir} and @t{pushd}. +For these commands a @t{-} is used to introduce a directory stack entry +and completion of these is far more common than completing options. +Hence unless the value of this style is `true' options will not be +completed, even after an initial @t{-}. If it is `true', options will +be completed after an initial @t{-} unless there is a preceding +@t{-}@t{-} on the command line. + +@kindex completer, completion style +@item @t{completer} +The strings given as the value of this style provide the names of the +completer functions to use. The available completer functions are +described in +@ref{Control Functions}. + +@noindent +Each string may be either the name of a completer function or a string +of the form `@var{function}@t{:}@var{name}'. In the first case the +@var{completer} field of the context will contain the name of the +completer without the leading underscore and with all other +underscores replaced by hyphens. In the second case the +@var{function} is the name of the completer to call, but the context +will contain the user-defined @var{name} in the @var{completer} field of +the context. If the @var{name} starts with a hyphen, the string for the +context will be build from the name of the completer function as in +the first case with the @var{name} appended to it. For example: + +@noindent +@example +zstyle ':completion:*' completer _complete _complete:-foo +@end example + +@noindent +Here, completion will call the @t{_complete} completer twice, once +using `@t{complete}' and once using `@t{complete-foo}' in the +@var{completer} field of the context. Normally, using the same +completer more than once only makes sense when used with the +`@var{functions}@t{:}@var{name}' form, because otherwise the context +name will be the same in all calls to the completer; possible +exceptions to this rule are the @t{_ignored} and @t{_prefix} +completers. + +@noindent +The default value for this style is `@t{_complete _ignored}': +only completion will be done, first using the @t{ignored-patterns} style +and the @t{$fignore} array and then without ignoring matches. + +@kindex condition, completion style +@item @t{condition} +This style is used by the @t{_list} completer function to decide if +insertion of matches should be delayed unconditionally. The default is +`true'. + +@kindex delimiters, completion style +@item @t{delimiters} +This style is used when adding a delimiter for use with history +modifiers or glob qualifiers that have delimited arguments. It is +an array of preferred delimiters to add. Non-special characters are +preferred as the completion system may otherwise become confused. +The default list is @t{:}, @t{+}, @t{/}, @t{-}, @t{%}. The list +may be empty to force a delimiter to be typed. + +@kindex disabled, completion style +@item @t{disabled} +If this is set to `true', the @t{_expand_alias} completer and bindable +command will try to expand disabled aliases, too. The default is +`false'. + +@kindex domains, completion style +@item @t{domains} +A list of names of network domains for completion. +If this is not set, domain names will be taken from +the file @t{/etc/resolv.conf}. + +@kindex environ, completion style +@item @t{environ} +The environ style is used when completing for `@t{sudo}'. It is set to an +array of `@var{VAR}@t{=}@var{value}' assignments to be exported into the +local environment before the completion for the target command is invoked. +@example +zstyle ':completion:*:sudo::' environ \ + PATH="/sbin:/usr/sbin:$PATH" HOME="/root" +@end example + +@kindex expand, completion style +@item @t{expand} +This style is used when completing strings consisting of multiple +parts, such as path names. + +@noindent +If one of its values is the string `@t{prefix}', the partially typed +word from the line will be expanded as far as possible even if trailing +parts cannot be completed. + +@noindent +If one of its values is the string `@t{suffix}', matching names for +components after the first ambiguous one will also be added. This means +that the resulting string is the longest unambiguous string possible. +However, menu completion can be used to cycle through all matches. + +@kindex fake, completion style +@item @t{fake} +This style may be set for any completion context. It +specifies additional strings that will always be completed in that +context. The form of each string is `@var{value}@t{:}@var{description}'; +the colon and description may be omitted, but any literal colons in +@var{value} must be quoted with a backslash. Any @var{description} +provided is shown alongside the value in completion listings. + +@noindent +It is important to use a sufficiently restrictive context when specifying +fake strings. Note that the styles @t{fake-files} and @t{fake-parameters} +provide additional features when completing files or parameters. + +@kindex fake-always, completion style +@item @t{fake-always} +This works identically to the @t{fake} style except that +the @t{ignored-patterns} style is not applied to it. This makes it +possible to override a set of matches completely by setting the +ignored patterns to `@t{*}'. + +@noindent +The following shows a way of supplementing any tag with arbitrary data, but +having it behave for display purposes like a separate tag. In this example +we use the features of the @t{tag-order} style to divide the +@t{named-directories} tag into two when performing completion with +the standard completer @t{complete} for arguments of @t{cd}. The tag +@t{named-directories-normal} behaves as normal, but the tag +@t{named-directories-mine} contains a fixed set of directories. +This has the effect of adding the match group `@t{extra directories}' with +the given completions. + +@noindent +@example +zstyle ':completion::complete:cd:*' tag-order \ + 'named-directories:-mine:extra\ directories + named-directories:-normal:named\ directories *' +zstyle ':completion::complete:cd:*:named-directories-mine' \ + fake-always mydir1 mydir2 +zstyle ':completion::complete:cd:*:named-directories-mine' \ + ignored-patterns '*' +@end example + +@kindex fake-files, completion style +@item @t{fake-files} +This style is used when completing files and looked up +without a tag. Its values are of the form +`@var{dir}@t{:}@var{names...}'. This will add the @var{names} (strings +separated by spaces) as +possible matches when completing in the directory @var{dir}, even if no +such files really exist. The dir may be a pattern; pattern characters +or colons in @var{dir} should be quoted with a backslash to be treated +literally. + +@noindent +This can be useful on systems that support special file systems whose +top-level pathnames can not be listed or generated with glob patterns +(but see @t{accept-exact-dirs} for a more general way of dealing +with this problem). It can also be used for directories for which one +does not have read permission. + +@noindent +The pattern form can be used to add a certain `magic' entry +to all directories on a particular file system. + +@kindex fake-parameters, completion style +@item @t{fake-parameters} +This is used by the completion function for parameter names. +Its values are names of parameters that might not yet be +set but should be completed nonetheless. Each name may also be +followed by a colon and a string specifying the type of the parameter +(like `@t{scalar}', `@t{array}' or `@t{integer}'). If the type is +given, the name will only be completed if parameters of that type are +required in the particular context. Names for which no type is +specified will always be completed. + +@kindex file-list, completion style +@item @t{file-list} +This style controls whether files completed using the standard builtin +mechanism are to be listed with a long list similar to @t{ls -l}. +Note that this feature uses the shell module +@t{zsh/stat} for file information; this loads the builtin @t{stat} +which will replace any external @t{stat} executable. To avoid +this the following code can be included in an initialization file: + +@noindent +@example +zmodload -i zsh/stat +disable stat +@end example + +@noindent +The style may either be set to a `true' value (or `@t{all}'), or +one of the values `@t{insert}' or `@t{list}', indicating that files +are to be listed in long format in all circumstances, or when +attempting to insert a file name, or when listing file names +without attempting to insert one. + +@noindent +More generally, the value may be an array of any of the above values, +optionally followed by @t{=}@var{num}. If @var{num} is present it +gives the maximum number of matches for which long listing style +will be used. For example, + +@noindent +@example +zstyle ':completion:*' file-list list=20 insert=10 +@end example + +@noindent +specifies that long format will be used when listing up to 20 files +or inserting a file with up to 10 matches (assuming a listing +is to be shown at all, for example on an ambiguous completion), else short +format will be used. + +@noindent +@example +zstyle -e ':completion:*' file-list \ + '(( $@{+NUMERIC@} )) && reply=(true)' +@end example + +@noindent +specifies that long format will be used any time a numeric argument is +supplied, else short format. + +@kindex file-patterns, completion style +@item @t{file-patterns} +This is used by the standard function for completing filenames, +@t{_files}. If the style is unset up to three tags are offered, +`@t{globbed-files}',`@t{directories}' and `@t{all-files}', depending on +the types of files expected by the caller of @t{_files}. The first two +(`@t{globbed-files}' and `@t{directories}') are normally offered +together to make it easier to complete files in sub-directories. + +@noindent +The @t{file-patterns} style provides alternatives to the default tags, +which are not used. Its value consists of elements of the form +`@var{pattern}@t{:}@var{tag}'; each string may contain any number of +such specifications separated by spaces. + +@noindent +The @var{pattern} is a pattern that is to be used to generate filenames. +Any occurrence of the sequence `@t{%p}' is replaced by any +pattern(s) +passed by the function calling @t{_files}. Colons in the pattern must +be preceded by a backslash to make them distinguishable from the colon +before the @var{tag}. If more than one pattern is needed, the patterns +can be given inside braces, separated by commas. + +@noindent +The @var{tag}s of all strings in the value will be offered by @t{_files} +and used when looking up other styles. Any @var{tag}s in the same +word will be offered at the same time and before later words. +If no `@t{:}@var{tag}' is given the `@t{files}' tag will be used. + +@noindent +The @var{tag} may also be followed by an optional second colon and a +description, which will be used for the `@t{%d}' in the value of +the @t{format} style (if that is set) instead of the default +description supplied by the completion function. If the description +given here contains itself a `@t{%d}', that is replaced with the +description supplied by the completion function. + +@noindent +For example, to make the @t{rm} command first complete only names of +object files and then the names of all files if there is no matching +object file: + +@noindent +@example +zstyle ':completion:*:*:rm:*:*' file-patterns \ + '*.o:object-files' '%p:all-files' +@end example + +@noindent +To alter the default behaviour of file completion --- offer files +matching a pattern and directories on the first attempt, then all files +--- to offer only matching files on the first attempt, then directories, +and finally all files: + +@noindent +@example +zstyle ':completion:*' file-patterns \ + '%p:globbed-files' '*(-/):directories' '*:all-files' +@end example + +@noindent +This works even where there is no special pattern: @t{_files} matches +all files using the pattern `@t{*}' at the first step and stops when it +sees this pattern. Note also it will never try a pattern more than once +for a single completion attempt. + +@noindent +During the execution of completion functions, the @t{EXTENDED_GLOB} +option is in effect, so the characters `@t{#}', `@t{~}' and `@t{^}' have +special meanings in the patterns. + +@kindex file-sort, completion style +@item @t{file-sort} +The standard filename completion function uses this style without a tag +to determine in which order the names should be listed; menu completion +will cycle through them in the same order. The possible +values are: `@t{size}' to sort by the size of the file; +`@t{links}' to sort by the number of links to the file; +`@t{modification}' (or `@t{time}' or `@t{date}') to sort by the last +modification time; `@t{access}' to sort by the last access time; and +`@t{inode}' (or `@t{change}') to sort by the last inode change +time. If the style is set to any other value, or is unset, files will be +sorted alphabetically by name. If the value contains the string +`@t{reverse}', sorting is done in the opposite order. If the value +contains the string `@t{follow}', timestamps are associated with the +targets of symbolic links; the default is to use the timestamps +of the links themselves. + +@kindex file-split-chars, completion style +@item @t{file-split-chars} +A set of characters that will cause @emph{all} file completions for +the given context to be split at the point where any of the characters +occurs. A typical use is to set the style to @t{:}; then everything +up to and including the last @t{:} in the string so far is ignored when +completing files. As this is quite heavy-handed, it is usually +preferable to update completion functions for contexts where this +behaviour is useful. + +@kindex filter, completion style +@item @t{filter} +The @t{ldap} plugin of email address completion (see @t{_email_addresses}) uses +this style to specify +the attributes to match against when filtering entries. So for example, if +the style is set to `@t{sn}', matching is done against surnames. Standard +LDAP filtering is used so normal completion matching is bypassed. If this +style is not set, the LDAP plugin is skipped. You may also need to set the +@t{command} style to specify how to connect to your LDAP server. + +@kindex force-list, completion style +@item @t{force-list} +This forces a list of completions to be shown at any point where listing is +done, even in cases where the list would usually be suppressed. +For example, normally the list is only shown if +there are at least two different matches. By setting this style to +`@t{always}', the list will always be shown, even if there is only a +single match that will immediately be accepted. The style may also +be set to a number. In this case the list will be shown if there are +at least that many matches, even if they would all insert the same +string. + +@noindent +This style is tested for the default tag as well as for each tag valid +for the current completion. Hence the listing can be forced only for +certain types of match. + +@kindex format, completion style +@item @t{format} +If this is set for the @t{descriptions} tag, its value is used as a +string to display above matches in completion lists. The sequence +`@t{%d}' in this string will be replaced with a short description of +what these matches are. This string may also contain the output +attribute sequences understood by @t{compadd -X} +(see +@ref{Completion Widgets}). + +@noindent +The style is tested with each tag valid for the current completion +before it is tested for the @t{descriptions} tag. Hence different format +strings can be defined for different types of match. + +@noindent +Note also that some completer functions define additional +`@t{%}'-sequences. These are described for the completer functions that +make use of them. + +@noindent +Some completion functions display messages that may be customised by +setting this style for the @t{messages} tag. Here, the `@t{%d}' is +replaced with a message given by the completion function. + +@noindent +Finally, the format string is looked up with the @t{warnings} tag, +for use when no matches could be generated at all. In this case the +`@t{%d}' is replaced with the descriptions for the matches that were +expected separated by spaces. The sequence `@t{%D}' is replaced with +the same descriptions separated by newlines. + +@noindent +It is possible to use printf-style field width specifiers with `@t{%d}' +and similar escape sequences. This is handled by the @t{zformat} +builtin command from the @t{zsh/zutil} module, see +@ref{The zsh/zutil Module}. + +@kindex glob, completion style +@item @t{glob} +This is used by the @t{_expand} completer. If +it is set to `true' (the default), globbing will be attempted on the +words resulting from a previous substitution (see the @t{substitute} +style) or else the original string from the line. + +@kindex global, completion style +@item @t{global} +If this is set to `true' (the default), the @t{_expand_alias} +completer and bindable command will try to expand global aliases. + +@kindex group-name, completion style +@item @t{group-name} +The completion system can group different types of matches, which appear +in separate lists. This style can be used to give the names of groups +for particular tags. For example, in command position the completion +system generates names of builtin and external commands, names of +aliases, shell functions and parameters and reserved words as possible +completions. To have the external commands and shell functions listed +separately: + +@noindent +@example +zstyle ':completion:*:*:-command-:*:commands' \ + group-name commands +zstyle ':completion:*:*:-command-:*:functions' \ + group-name functions +@end example + +@noindent +As a consequence, any match with the same tag will be displayed in the +same group. + +@noindent +If the name given is the empty string the name of the tag for +the matches will be used as the name of the group. So, to have all +different types of matches displayed separately, one can just set: + +@noindent +@example +zstyle ':completion:*' group-name @value{dsq} +@end example + +@noindent +All matches for which no group name is defined will be put in a group +named @t{-default-}. + +@kindex group-order, completion style +@item @t{group-order} +This style is additional to the @t{group-name} style to specify the +order for display of the groups defined by that style (compare @t{tag-order}, +which determines which completions appear at all). The groups named +are shown in the given order; any other groups +are shown in the order defined by the completion function. + +@noindent +For example, to have names of builtin commands, shell functions and +external commands appear in that order when completing in command +position: + +@noindent +@example +zstyle ':completion:*:*:-command-:*:*' group-order \ + builtins functions commands +@end example + +@kindex groups, completion style +@item @t{groups} +A list of names of UNIX groups. If this is not set, +group names are taken from the YP database or the file `@t{/etc/group}'. + +@kindex hidden, completion style +@item @t{hidden} +If this is set to `true', matches for the given context +will not be listed, although +any description for the matches set with the @t{format} style will be +shown. If it is set to `@t{all}', not even the description will be +displayed. + +@noindent +Note that the matches will still be completed; they are just not shown +in the list. To avoid having matches considered as possible +completions at all, the @t{tag-order} style can be modified as described +below. + +@kindex hosts, completion style +@item @t{hosts} +A list of names of hosts that should be completed. If this is not set, +hostnames are taken from the file `@t{/etc/hosts}'. + +@kindex hosts-ports, completion style +@item @t{hosts-ports} +This style is used by commands that need or accept hostnames and +network ports. The strings in the value should be of the form +`@var{host}@t{:}@var{port}'. Valid ports are determined by the presence +of hostnames; multiple ports for the same host may appear. + +@kindex ignore-line, completion style +@item @t{ignore-line} +This is tested for each tag valid for the current completion. If +it is set to `true', none of the words that are already on the line +will be considered as possible completions. If it is set to +`@t{current}', the word the cursor is on will not be considered as a +possible completion. The value `@t{current-shown}' is similar but only +applies if the list of completions is currently shown on the screen. +Finally, if the style is set to `@t{other}', all words on the line except +for the current one will be excluded from the possible completions. + +@noindent +The values `@t{current}' and `@t{current-shown}' are a bit like the +opposite of the @t{accept-exact} style: only strings with +missing characters will be completed. + +@noindent +Note that you almost certainly don't want to set this to `true' or +`@t{other}' for a general +context such as `@t{:completion:*}'. This is because it would disallow +completion of, for example, options multiple times even if the command +in question accepts the option more than once. + +@kindex ignore-parents, completion style +@item @t{ignore-parents} +The style is tested without a tag by the function completing pathnames +in order to determine whether to ignore +the names of directories already mentioned in the current word, or the +name of the current working directory. The value must include one or both +of the following strings: + +@noindent +@table @asis +@item @t{parent} +The name of any directory whose path is already contained in the word on +the line is ignored. For example, when completing after @t{foo/../}, the +directory @t{foo} will not be considered a valid completion. + +@item @t{pwd} +The name of the current working directory will not be completed; hence, +for example, completion after @t{../} will not use the name of the current +directory. + +@end table + +@noindent +In addition, the value may include one or both of: + +@noindent +@table @asis +@item @t{..} +Ignore the specified directories only when the word on the line contains +the substring `@t{../}'. + +@item @t{directory} +Ignore the specified directories only when names of directories are +completed, not when completing names of files. + +@end table + +@noindent +Excluded values act in a similar fashion to values of the +@t{ignored-patterns} style, so they can be restored to consideration by +the @t{_ignored} completer. + +@kindex extra-verbose, completion style +@item @t{extra-verbose} +If set, the completion listing is more verbose at the cost of +a probable decrease in completion speed. Completion performance +will suffer if this style is set to `true'. + +@kindex ignored-patterns, completion style +@item @t{ignored-patterns} +A list of patterns; any trial completion matching one of the patterns +will be excluded from consideration. The +@t{_ignored} completer can appear in the list of completers to +restore the ignored matches. This is a more configurable +version of the shell parameter @t{$fignore}. + +@noindent +Note that the +@t{EXTENDED_GLOB} option is set during the execution of completion +functions, so the characters `@t{#}', `@t{~}' and `@t{^}' have special +meanings in the patterns. + +@kindex insert, completion style +@item @t{insert} +This style is used by the @t{_all_matches} completer to decide whether to +insert the list of all matches unconditionally instead of adding the +list as another match. + +@kindex insert-ids, completion style +@item @t{insert-ids} +When completing process IDs, for example as arguments to the @t{kill} and +@t{wait} builtins the name of a +command may be converted to the appropriate process ID. A problem +arises when the process name typed is not unique. By default (or if this +style is set explicitly to `@t{menu}') the name will be converted +immediately to a set of possible IDs, and menu completion will be started +to cycle through them. + +@noindent +If the value of the style is `@t{single}', +the shell will wait until the user has typed enough to make the command +unique before converting the name to an ID; attempts at completion will +be unsuccessful until that point. If the value is any other +string, menu completion will be started when the string typed by the +user is longer than the common prefix to the corresponding IDs. + +@kindex insert-tab, completion style +@item @t{insert-tab} +If this is set to `true', the completion system will +insert a TAB character (assuming that was used to start completion) instead +of performing completion when there is no non-blank character to the left +of the cursor. If it is set to `false', completion will be done even there. + +@noindent +The value may also contain the substrings `@t{pending}' or +`@t{pending=}@var{val}'. In this case, the typed character will be +inserted instead of starting completion when there is unprocessed input +pending. If a @var{val} is given, completion will not be done if there +are at least that many characters of unprocessed input. This is often +useful when pasting characters into a terminal. Note +however, that it relies on the @t{$PENDING} special parameter from the +@t{zsh/zle} module being set properly which is not guaranteed on all +platforms. + +@noindent +The default value of this style is `true' except for completion within +@t{vared} builtin command where it is `false'. + +@kindex insert-unambiguous, completion style +@item @t{insert-unambiguous} +This is used by the @t{_match} and @t{_approximate} completers. +These completers are often used with menu completion since the word typed +may bear little resemblance to the final completion. +However, if this style is `true', the completer will start menu +completion only if it could find no unambiguous initial string at +least as long as the original string typed by the user. + +@noindent +In the case of the @t{_approximate} completer, the completer +field in the context will already have been set to one of +@t{correct-}@var{num} or @t{approximate-}@var{num}, where @var{num} is the +number of errors that were accepted. + +@noindent +In the case of the @t{_match} completer, the style may also be set to +the string `@t{pattern}'. Then the pattern on the line is left +unchanged if it does not match unambiguously. + +@kindex gain-privileges, completion style +@item @t{gain-privileges} +If set to @t{true}, this style enables the use of commands like @t{sudo} +or @t{doas} to gain extra privileges when retrieving information for +completion. This is only done when a command such as @t{sudo} appears on +the command-line. To force the use of, e.g. @t{sudo} or to override any +prefix that might be added due to @t{gain-privileges}, the @t{command} +style can be used with a value that begins with a hyphen. + +@kindex keep-prefix, completion style +@item @t{keep-prefix} +This style is used by the @t{_expand} completer. If it is `true', the +completer will try to keep a prefix containing a tilde or parameter +expansion. Hence, for example, the string `@t{~/f*}' would be expanded to +`@t{~/foo}' instead of `@t{/home/user/foo}'. If the style is set to +`@t{changed}' (the default), the prefix will only be left unchanged if +there were other changes between the expanded words and the original +word from the command line. Any other value forces the prefix to be +expanded unconditionally. + +@noindent +The behaviour of @t{_expand} when this style is `true' is to cause @t{_expand} +to give up when a single expansion with the restored prefix is the same +as the original; hence any remaining completers may be called. + +@kindex last-prompt, completion style +@item @t{last-prompt} +This is a more flexible form of the @t{ALWAYS_LAST_PROMPT} option. +If it is `true', the completion system will try to return the cursor to +the previous command line after displaying a completion list. It is +tested for all tags valid for the current completion, then the +@t{default} tag. The cursor will be moved back to the +previous line if this style is `true' for all types of match. Note +that unlike the @t{ALWAYS_LAST_PROMPT} option this is independent of the +numeric argument. + +@kindex known-hosts-files +@item @t{known-hosts-files} +This style should contain a list of files to search for host names and +(if the @t{use-ip} style is set) IP addresses in a format compatible with +ssh @t{known_hosts} files. If it is not set, the files +@t{/etc/ssh/ssh_known_hosts} and @t{~/.ssh/known_hosts} are used. + +@kindex list, completion style +@item @t{list} +This style is used by the @t{_history_complete_word} bindable command. +If it is set to `true' it has no effect. If it is set to `false' +matches will not be listed. This overrides the setting of the options +controlling listing behaviour, in particular @t{AUTO_LIST}. The context +always starts with `@t{:completion:history-words}'. + +@kindex list-colors, completion style +@item @t{list-colors} +If the @t{zsh/complist} module is loaded, this style can be used to set +color specifications. This mechanism replaces the use of the +@t{ZLS_COLORS} and @t{ZLS_COLOURS} parameters described in +@ref{The zsh/complist Module}, but the syntax is the same. + +@noindent +If this style is set for the @t{default} tag, the strings in the value +are taken as specifications that are to be used everywhere. If it is +set for other tags, the specifications are used only for matches of +the type described by the tag. For this to work best, the @t{group-name} +style must be set to an empty string. + +@noindent +In addition to setting styles for specific tags, it is also possible to +use group names specified explicitly by the @t{group-name} tag together +with the `@t{(group)}' syntax allowed by the @t{ZLS_COLORS} and +@t{ZLS_COLOURS} parameters and simply using the @t{default} tag. + +@noindent +It is possible to use any color specifications already set up for the GNU +version of the @t{ls} command: + +@noindent +@example +zstyle ':completion:*:default' list-colors \ + $@{(s.:.)LS_COLORS@} +@end example + +@noindent +The default colors are the same as for the GNU @t{ls} command and can be +obtained by setting the style to an empty string (i.e. @t{@value{dsq}}). + +@kindex list-dirs-first, completion style +@item @t{list-dirs-first} +This is used by file completion. If set, directories to be completed +are listed separately from and before completion for other files, +regardless of tag ordering. In addition, the tag @t{other-files} +is used in place of @t{all-files} for the remaining files, to indicate +that no directories are presented with that tag. + +@kindex list-grouped, completion style +@item @t{list-grouped} +If this style is `true' (the default), the completion system will try to +make certain completion listings more compact by grouping matches. +For example, options for commands that have the same description (shown +when the @t{verbose} style is set to `true') will appear as a single +entry. However, menu selection can be used to cycle through all the +matches. + +@kindex list-packed, completion style +@item @t{list-packed} +This is tested for each tag valid in the current context as well as the +@t{default} tag. If it is set to `true', the corresponding matches +appear in listings as if the @t{LIST_PACKED} option were set. If it is +set to `false', they are listed normally. + +@kindex list-prompt, completion style +@item @t{list-prompt} +If this style is set for the @t{default} tag, +completion lists that don't fit on the screen can be scrolled (see +@ref{The zsh/complist Module}). The value, if not the empty string, will be displayed after every +screenful and the shell will prompt for a key press; if the style is +set to the empty string, +a default prompt will be used. + +@noindent +The value may contain the escape sequences: +`@t{%l}' or `@t{%L}', which will be replaced by the number of the last line +displayed and the total number of lines; `@t{%m}' or `@t{%M}', +the number of the last match shown and the total number of +matches; and `@t{%p}' and `@t{%P}', `@t{Top}' +when at the beginning of the list, `@t{Bottom}' when at the end and the +position shown as a percentage of the total length otherwise. In each +case the form with the uppercase letter will be replaced by a string of fixed +width, padded to the right with spaces, while the lowercase form will +be replaced by a variable width string. As in other prompt strings, the +escape sequences `@t{%S}', `@t{%s}', `@t{%B}', `@t{%b}', `@t{%U}', +`@t{%u}' for entering and leaving the display modes +standout, bold and underline, and `@t{%F}', `@t{%f}', `@t{%K}', `@t{%k}' for +changing the foreground background colour, are also available, as is the form +`@t{%@{}...@t{%@}}' for enclosing escape sequences which display with zero +(or, with a numeric argument, some other) width. + +@noindent +After deleting this prompt the variable @t{LISTPROMPT} should be unset for +the removal to take effect. + +@kindex list-rows-first, completion style +@item @t{list-rows-first} +This style is tested in the same way as the @t{list-packed} style and +determines whether matches are to be listed in a rows-first fashion as +if the @t{LIST_ROWS_FIRST} option were set. + +@kindex list-suffixes, completion style +@item @t{list-suffixes} +This style is used by the function that completes filenames. If it is +`true', and completion is attempted on a string containing multiple partially +typed pathname components, all ambiguous components will be shown. +Otherwise, completion stops at the first ambiguous component. + +@kindex list-separator, completion style +@item @t{list-separator} +The value of this style is used in completion listing to separate the +string to complete from a description when possible (e.g. when +completing options). It defaults to `@t{-}@t{-}' (two hyphens). + +@kindex local, completion style +@item @t{local} +This is for use with functions that complete URLs for which the +corresponding files are available directly from the file system. +Its value should consist of three strings: a +hostname, the path to the default web pages for the server, and the +directory name used by a user placing web pages within their home +area. + +@noindent +For example: + +@noindent +@example +zstyle ':completion:*' local toast \ + /var/http/public/toast public_html +@end example + +@noindent +Completion after `@t{http://toast/stuff/}' will look for files in the +directory @t{/var/http/public/toast/stuff}, while completion after +`@t{http://toast/~yousir/}' will look for files in the directory +@t{~yousir/public_html}. + +@kindex mail-directory, completion style +@item @t{mail-directory} +If set, zsh will assume that mailbox files can be found in +the directory specified. It defaults to `@t{~/Mail}'. + +@kindex match-original, completion style +@item @t{match-original} +This is used by the @t{_match} completer. If it is set to +@t{only}, @t{_match} will try to generate matches without inserting a +`@t{*}' at the cursor position. If set to any other non-empty value, +it will first try to generate matches without inserting the `@t{*}' +and if that yields no matches, it will try again with the `@t{*}' +inserted. If it is unset or set to the empty string, matching will +only be performed with the `@t{*}' inserted. + +@kindex matcher, completion style +@item @t{matcher} +This style is tested separately for each tag valid in the current +context. Its value is placed before any match specifications given by the +@t{matcher-list} style so can override them via the use of an @t{x:} +specification. The value should be in the form described in +@ref{Completion Matching Control}. For examples of this, see the description of the @t{tag-order} style. + +@noindent +For notes comparing the use of this and the @t{matcher-list} style, see +under the description of the @t{tag-order} style. + +@kindex matcher-list, completion style +@item @t{matcher-list} +This style can be set to a list of match specifications that are to +be applied everywhere. Match specifications are described in +@ref{Completion Matching Control}. +The completion system will try them one after another for each completer +selected. For example, to try first simple completion and, if that +generates no matches, case-insensitive completion: + +@noindent +@example +zstyle ':completion:*' matcher-list @value{dsq} 'm:@{a-zA-Z@}=@{A-Za-z@}' +@end example + +@noindent +By default each specification replaces the previous one; however, if a +specification is prefixed with @t{+}, it is added to the existing list. +Hence it is possible to create increasingly general specifications +without repetition: + +@noindent +@example +zstyle ':completion:*' matcher-list \ + @value{dsq} '+m:@{a-z@}=@{A-Z@}' '+m:@{A-Z@}=@{a-z@}' +@end example + +@noindent +It is possible to create match specifications valid for particular +completers by using the third field of the context. This applies only +to completers that override the global matcher-list, which as of this +writing includes only @t{_prefix} and @t{_ignored}. For example, to +use the completers @t{_complete} and @t{_prefix} but allow +case-insensitive completion only with @t{_complete}: + +@noindent +@example +zstyle ':completion:*' completer _complete _prefix +zstyle ':completion:*:complete:*:*:*' matcher-list \ + @value{dsq} 'm:@{a-zA-Z@}=@{A-Za-z@}' +@end example + +@noindent +User-defined names, as explained for the @t{completer} style, are +available. This makes it possible to try the same completer more than +once with different match specifications each time. For example, to try +normal completion without a match specification, then normal completion +with case-insensitive matching, then correction, and finally +partial-word completion: + +@noindent +@example +zstyle ':completion:*' completer \ + _complete _correct _complete:foo +zstyle ':completion:*:complete:*:*:*' matcher-list \ + @value{dsq} 'm:@{a-zA-Z@}=@{A-Za-z@}' +zstyle ':completion:*:foo:*:*:*' matcher-list \ + 'm:@{a-zA-Z@}=@{A-Za-z@} r:|[-_./]=* r:|=*' +@end example + +@noindent +If the style is unset in any context no match specification is applied. +Note also that some completers such as @t{_correct} and @t{_approximate} +do not use the match specifications at all, though these completers will +only ever be called once even if the @t{matcher-list} contains more than +one element. + +@noindent +Where multiple specifications are useful, note that the @emph{entire} +completion is done for each element of @t{matcher-list}, which can +quickly reduce the shell's performance. As a rough rule of thumb, +one to three strings will give acceptable performance. On the other +hand, putting multiple space-separated values into the same string does +not have an appreciable impact on performance. + +@noindent +If there is no current matcher or it is empty, and the option +@t{NO_CASE_GLOB} is in effect, the matching for files is performed +case-insensitively in any case. However, any matcher must +explicitly specify case-insensitive matching if that is required. + +@noindent +For notes comparing the use of this and the @t{matcher} style, see +under the description of the @t{tag-order} style. + +@kindex max-errors, completion style +@item @t{max-errors} +This is used by the @t{_approximate} and @t{_correct} completer functions +to determine the maximum number of errors to allow. The completer will try +to generate completions by first allowing one error, then two errors, and +so on, until either a match or matches were found or the maximum number of +errors given by this style has been reached. + +@noindent +If the value for this style contains the string `@t{numeric}', the +completer function will take any numeric argument as the +maximum number of errors allowed. For example, with + +@noindent +@example +zstyle ':completion:*:approximate:::' max-errors 2 numeric +@end example + +@noindent +two errors are allowed if no numeric argument is given, but with +a numeric argument of six (as in `@t{ESC-6 TAB}'), up to six +errors are accepted. Hence with a value of `@t{0 numeric}', no correcting +completion will be attempted unless a numeric argument is given. + +@noindent +If the value contains the string `@t{not-numeric}', the completer +will @emph{not} try to generate corrected +completions when given a numeric argument, so in this case the number given +should be greater than zero. For example, `@t{2 not-numeric}' specifies that +correcting completion with two errors will usually be performed, but if a +numeric argument is given, correcting completion will not be +performed. + +@noindent +The default value for this style is `@t{2 numeric}'. + +@kindex max-matches-width, completion style +@item @t{max-matches-width} +This style is used to determine the trade off between the width of the +display used for matches and the width used for their descriptions when +the @t{verbose} style is in effect. The value gives the number of +display columns to reserve for the matches. The default is half the +width of the screen. + +@noindent +This has the most impact when several matches have the +same description and so will be grouped together. Increasing the style +will allow more matches to be grouped together; decreasing it will allow +more of the description to be visible. + +@kindex menu, completion style +@item @t{menu} +If this is `true' in the context of any of the tags defined +for the current completion menu completion will be used. The value for +a specific tag will take precedence over that for the `@t{default}' tag. + +@noindent +If none of the values found in this way is `true' but at least +one is set to `@t{auto}', the shell behaves as if the @t{AUTO_MENU} +option is set. + +@noindent +If one of the values is explicitly set to `false', menu +completion will be explicitly turned off, overriding the +@t{MENU_COMPLETE} option and other settings. + +@noindent +In the form `@t{yes=}@var{num}', where `@t{yes}' may be any of the +`true' values (`@t{yes}', `@t{true}', `@t{on}' and `@t{1}'), +menu completion will be turned on if there are at least @var{num} matches. +In the form `@t{yes=long}', menu completion will be turned on +if the list does not fit on the screen. This does not activate menu +completion if the widget normally only lists completions, but menu +completion can be activated in that case with the value `@t{yes=long-list}' +(Typically, the value `@t{select=long-list}' described later is more +useful as it provides control over scrolling.) + +@noindent +Similarly, with any of the `false' values (as in `@t{no=10}'), menu +completion will @emph{not} be used if there are @var{num} or more matches. + +@noindent +The value of this widget also controls menu selection, as implemented by +the @t{zsh/complist} module. The following values may appear either +alongside or instead of the values above. + +@noindent +If the value contains the string `@t{select}', menu selection +will be started unconditionally. + +@noindent +In the form `@t{select=}@var{num}', menu selection will only be started if +there are at least @var{num} matches. If the values for more than one +tag provide a number, the smallest number is taken. + +@noindent +Menu selection can be turned off explicitly by defining a value +containing the string`@t{no-select}'. + +@noindent +It is also possible to start menu selection only if the list of +matches does not fit on the screen by using the value +`@t{select=long}'. To start menu selection even if the current widget +only performs listing, use the value `@t{select=long-list}'. + +@noindent +To turn on menu completion or menu selection when there are a certain +number of matches @emph{or} the list of matches does not fit on the +screen, both of `@t{yes=}' and `@t{select=}' may be given twice, once +with a number and once with `@t{long}' or `@t{long-list}'. + +@noindent +Finally, it is possible to activate two special modes of menu selection. +The word `@t{interactive}' in the value causes interactive mode +to be entered immediately when menu selection is started; see +@ref{The zsh/complist Module} +for a description of interactive mode. Including the string +`@t{search}' does the same for incremental search mode. To select backward +incremental search, include the string `@t{search-backward}'. + +@kindex muttrc, completion style +@item @t{muttrc} +If set, gives the location of the mutt configuration file. It defaults +to `@t{~/.muttrc}'. + +@kindex numbers, completion style +@item @t{numbers} +This is used with the @t{jobs} tag. If it is `true', the shell will +complete job numbers instead of the shortest unambiguous prefix +of the job command text. If the value is a number, job numbers will +only be used if that many words from the job descriptions are required to +resolve ambiguities. For example, if the value is `@t{1}', strings will +only be used if all jobs differ in the first word on their command lines. + +@kindex old-list, completion style +@item @t{old-list} +This is used by the @t{_oldlist} completer. If it is set to `@t{always}', +then standard widgets which perform listing will retain the current list of +matches, however they were generated; this can be turned off explicitly +with the value `@t{never}', giving the behaviour without the @t{_oldlist} +completer. If the style is unset, or any other value, then the existing +list of completions is displayed if it is not already; otherwise, the +standard completion list is generated; this is the default behaviour of +@t{_oldlist}. However, if there is an old list and this style contains +the name of the completer function that generated the list, then the +old list will be used even if it was generated by a widget which does +not do listing. + +@noindent +For example, suppose you type @t{^Xc} to use the @t{_correct_word} +widget, which generates a list of corrections for the word under the +cursor. Usually, typing @t{^D} would generate a standard list of +completions for the word on the command line, and show that. With +@t{_oldlist}, it will instead show the list of corrections already +generated. + +@noindent +As another example consider the @t{_match} completer: with the +@t{insert-unambiguous} style set to `true' it inserts only a common prefix +string, if there is any. However, this may remove parts of the original +pattern, so that further completion could produce more matches than on the +first attempt. By using the @t{_oldlist} completer and setting this style +to @t{_match}, the list of matches generated on the first attempt will be +used again. + +@kindex old-matches, completion style +@item @t{old-matches} +This is used by the @t{_all_matches} completer to decide if an old +list of matches should be used if one exists. This is selected by one of +the `true' values or by the string `@t{only}'. If +the value is `@t{only}', @t{_all_matches} will only use an old list +and won't have any effect on the list of matches currently being +generated. + +@noindent +If this style is set it is generally unwise to call the @t{_all_matches} +completer unconditionally. One possible use is for either this style or +the @t{completer} style to be defined with the @t{-e} option to +@t{zstyle} to make the style conditional. + +@kindex old-menu, completion style +@item @t{old-menu} +This is used by the @t{_oldlist} completer. It controls how menu +completion behaves when a completion has already been inserted and the +user types a standard completion key such as @t{TAB}. The default +behaviour of @t{_oldlist} is that menu completion always continues +with the existing list of completions. If this style is set to +`false', however, a new completion is started if the old list was +generated by a different completion command; this is the behaviour without +the @t{_oldlist} completer. + +@noindent +For example, suppose you type @t{^Xc} to generate a list of corrections, +and menu completion is started in one of the usual ways. Usually, or with +this style set to `false', typing @t{TAB} at this point would start +trying to complete the line as it now appears. With @t{_oldlist}, it +instead continues to cycle through the list of corrections. + +@kindex original, completion style +@item @t{original} +This is used by the @t{_approximate} and @t{_correct} +completers to decide if the original string should be added as +a possible completion. Normally, this is done only if there are +at least two possible corrections, but if this style is set to `true', it +is always added. Note that the style will be examined with the +completer field in the context name set to @t{correct-}@var{num} or +@t{approximate-}@var{num}, where @var{num} is the number of errors that +were accepted. + +@kindex packageset, completion style +@item @t{packageset} +This style is used when completing arguments of the Debian `@t{dpkg}' +program. It contains an override for the default package set +for a given context. For example, + +@noindent +@example +zstyle ':completion:*:complete:dpkg:option--status-1:*' \ + packageset avail +@end example + +@noindent +causes available packages, rather than only installed packages, +to be completed for `@t{dpkg -}@t{-status}'. + +@kindex path, completion style +@item @t{path} +The function that completes color names uses this style with the +@t{colors} tag. The value should be the pathname of a file +containing color names in the format of an X11 @t{rgb.txt} file. If +the style is not set but this file is found in one of various standard +locations it will be used as the default. + +@kindex path-completion, completion style +@item @t{path-completion} +This is used by filename completion. By default, filename completion +examines all components of a path to see if there are completions of +that component. For example, @t{/u/b/z} can be completed to +@t{/usr/bin/zsh}. Explicitly setting this style to `false' inhibits this +behaviour for path components up to the @t{/} before the cursor; this +overrides the setting of @t{accept-exact-dirs}. + +@noindent +Even with the style set to `false', it is still possible to complete +multiple paths by setting the option @t{COMPLETE_IN_WORD} and moving the +cursor back to the first component in the path to be completed. For +example, @t{/u/b/z} can be completed to @t{/usr/bin/zsh} if the cursor is +after the @t{/u}. + +@kindex pine-directory, completion style +@item @t{pine-directory} +If set, specifies the directory containing PINE mailbox files. There +is no default, since recursively searching this directory is inconvenient +for anyone who doesn't use PINE. + +@kindex ports, completion style +@item @t{ports} +A list of Internet service names (network ports) to complete. If this is +not set, service names are taken from the file `@t{/etc/services}'. + +@kindex prefix-hidden, completion style +@item @t{prefix-hidden} +This is used for certain completions which share a common prefix, for +example command options beginning with dashes. If it is `true', the +prefix will not be shown in the list of matches. + +@noindent +The default value for this style is `false'. + +@kindex prefix-needed, completion style +@item @t{prefix-needed} +This style is also relevant for matches with a common prefix. If it is +set to `true' this common prefix must be typed by the user to generate +the matches. + +@noindent +The style is applicable to the @t{options}, @t{signals}, @t{jobs}, +@t{functions}, and @t{parameters} completion tags. + +@noindent +For command options, this means that the initial `@t{-}', `@t{+}', or +`@t{-}@t{-}' must be typed explicitly before option names will be +completed. + +@noindent +For signals, an initial `@t{-}' is required before signal names will +be completed. + +@noindent +For jobs, an initial `@t{%}' is required before job names will be +completed. + +@noindent +For function and parameter names, an initial `@t{_}' or `@t{.}' is +required before function or parameter names starting with those +characters will be completed. + +@noindent +The default value for this style is `false' for @t{function} and +@t{parameter} completions, and `true' otherwise. + +@kindex preserve-prefix, completion style +@item @t{preserve-prefix} +This style is used when completing path names. Its value should be a +pattern matching an initial prefix of the word to complete that should +be left unchanged under all circumstances. For example, on some Unices +an initial `@t{//}' (double slash) has a special meaning; setting +this style to the string `@t{//}' will preserve it. As another example, +setting this style to `@t{?:/}' under Cygwin would allow completion +after `@t{a:/...}' and so on. + +@kindex range, completion style +@item @t{range} +This is used by the @t{_history} completer and the +@t{_history_complete_word} bindable command to decide which words +should be completed. + +@noindent +If it is a single number, only the last @var{N} words from the history +will be completed. + +@noindent +If it is a range of the form `@var{max}@t{:}@var{slice}', +the last @var{slice} words will be completed; then if that +yields no matches, the @var{slice} words before those will be tried and +so on. This process stops either when at least one match has been +found, or @var{max} words have been tried. + +@noindent +The default is to complete all words from the history at once. + +@kindex recursive-files, completion style +@item @t{recursive-files} +If this style is set, its value is an array of patterns to be +tested against `@t{$PWD/}': note the trailing slash, which allows +directories in the pattern to be delimited unambiguously by including +slashes on both sides. If an ordinary file completion fails +and the word on the command line does not yet have a directory part to its +name, the style is retrieved using the same tag as for the completion +just attempted, then the elements tested against @t{$PWD/} in turn. +If one matches, then the shell reattempts completion by prepending the word +on the command line with each directory in the expansion of @t{**/*(/)} +in turn. Typically the elements of the style will be set to restrict +the number of directories beneath the current one to a manageable +number, for example `@t{*/.git/*}'. + +@noindent +For example, + +@noindent +@example +zstyle ':completion:*' recursive-files '*/zsh/*' +@end example + +@noindent +If the current directory is @t{/home/pws/zsh/Src}, then +@t{zle_tr}@emph{TAB} can be completed to @t{Zle/zle_tricky.c}. + +@kindex regular, completion style +@item @t{regular} +This style is used by the @t{_expand_alias} completer and bindable +command. If set to `true' (the default), regular aliases will be +expanded but only in command position. If it is set to `false', +regular aliases will never be expanded. If it is set to `@t{always}', +regular aliases will be expanded even if not in command position. + +@kindex rehash, completion style +@item @t{rehash} +If this is set when completing external commands, the internal +list (hash) of commands will be updated for each search by issuing +the @t{rehash} command. There is a speed penalty for this which +is only likely to be noticeable when directories in the path have +slow file access. + +@kindex remote-access, completion style +@item @t{remote-access} +If set to `false', certain commands will be prevented from making +Internet connections to retrieve remote information. This includes the +completion for the @t{CVS} command. + +@noindent +It is not always possible to know if connections are in fact to a remote +site, so some may be prevented unnecessarily. + +@kindex remove-all-dups, completion style +@item @t{remove-all-dups} +The @t{_history_complete_word} bindable command and the @t{_history} +completer use this to decide if all duplicate matches should be +removed, rather than just consecutive duplicates. + +@kindex select-prompt, completion style +@item @t{select-prompt} +If this is set for the @t{default} tag, its +value will be displayed during menu selection (see the @t{menu} style +above) when the completion list does not fit on the screen as a +whole. The same escapes as for the @t{list-prompt} style are +understood, except that the numbers refer to the match or line the mark is +on. A default prompt is used when the value is the empty string. + +@kindex select-scroll, completion style +@item @t{select-scroll} +This style is tested for the @t{default} tag and determines how a +completion list is scrolled during a menu selection (see the @t{menu} +style above) when the completion list does not fit on the screen as a +whole. If the value is `@t{0}' (zero), the list is scrolled by +half-screenfuls; if it is a positive integer, the list is scrolled by the +given number of lines; if it is a negative number, the list is scrolled by a +screenful minus the absolute value of the given number of lines. +The default is to scroll by single lines. + +@kindex separate-sections, completion style +@item @t{separate-sections} +This style is used with the @t{manuals} tag when completing names of +manual pages. If it is `true', entries for different sections are +added separately using tag names of the form `@t{manual.}@var{X}', +where @var{X} is the section number. When the @t{group-name} style is +also in effect, pages from different sections will appear separately. +This style is also used similarly with the @t{words} style when +completing words for the dict command. It allows words from different +dictionary databases to be added separately. +The default for this style is `false'. + +@kindex show-ambiguity, completion style +@item @t{show-ambiguity} +If the @t{zsh/complist} module is loaded, this style can be used to +highlight the first ambiguous character in completion lists. The +value is either a color indication such as those supported by the +@t{list-colors} style or, with a value of `true', a default of +underlining is selected. The highlighting is only applied if the +completion display strings correspond to the actual matches. + +@kindex show-completer, completion style +@item @t{show-completer} +Tested whenever a new completer is tried. If it is `true', the completion +system outputs a progress message in the listing area showing what +completer is being tried. The message will be overwritten by any output +when completions are found and is removed after completion is finished. + +@kindex single-ignored, completion style +@item @t{single-ignored} +This is used by the @t{_ignored} completer when there is only one match. +If its value is `@t{show}', the single match will be +displayed but not inserted. If the value is `@t{menu}', then the single +match and the original string are both added as matches and menu completion +is started, making it easy to select either of them. + +@kindex sort, completion style +@item @t{sort} +This allows the standard ordering of matches to be overridden. + +@noindent +If its value is `@t{true}' or `@t{false}', sorting is enabled or disabled. +Additionally the values associated with the `@t{-o}' option to @t{compadd} can +also be listed: @t{match}, @t{nosort}, @t{numeric}, @t{reverse}. If it is not +set for the context, the standard behaviour of the calling widget is used. + +@noindent +The style is tested first against the full context including the tag, and +if that fails to produce a value against the context without the tag. + +@noindent +In many cases where a calling widget explicitly selects a particular ordering +in lieu of the default, a value of `@t{true}' is not honoured. An example of +where this is not the case is for command history where the default of sorting +matches chronologically may be overridden by setting the style to `true'. + +@noindent +In the @t{_expand} completer, if it is set to +`true', the expansions generated will always be sorted. If it is set +to `@t{menu}', then the expansions are only sorted when they are offered +as single strings but not in the string containing all possible +expansions. + +@kindex special-dirs, completion style +@item @t{special-dirs} +Normally, the completion code will not produce the directory names +`@t{.}' and `@t{..}' as possible completions. If this style is set to +`true', it will add both `@t{.}' and `@t{..}' as possible completions; +if it is set to `@t{..}', only `@t{..}' will be added. + +@noindent +The following example sets @t{special-dirs} to `@t{..}' when the +current prefix is empty, is a single `@t{.}', or consists only of a path +beginning with `@t{../}'. Otherwise the value is `false'. + +@noindent +@example +zstyle -e ':completion:*' special-dirs \ + '[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)' +@end example + +@kindex squeeze-slashes, completion style +@item @t{squeeze-slashes} +If set to `true', sequences of slashes in filename paths (for example in +`@t{foo//bar}') will be treated as a single slash. This is the usual +behaviour of UNIX paths. However, by default the file completion +function behaves as if there were a `@t{*}' between the slashes. + +@kindex stop, completion style +@item @t{stop} +If set to `true', the @t{_history_complete_word} bindable +command will stop once when reaching the beginning or end of the +history. Invoking @t{_history_complete_word} will then wrap around to +the opposite end of the history. If this style is set to `false' (the +default), @t{_history_complete_word} will loop immediately as in a +menu completion. + +@kindex strip-comments, completion style +@item @t{strip-comments} +If set to `true', this style causes non-essential comment text to be +removed from completion matches. Currently it is only used when +completing e-mail addresses where it removes any display name from the +addresses, cutting them down to plain @var{user@@host} form. + +@kindex subst-globs-only, completion style +@item @t{subst-globs-only} +This is used by the @t{_expand} completer. If it is set to `true', +the expansion will only be used if it resulted from globbing; hence, +if expansions resulted from the use of the @t{substitute} style +described below, but these were not further changed by globbing, the +expansions will be rejected. + +@noindent +The default for this style is `false'. + +@kindex substitute, completion style +@item @t{substitute} +This boolean style controls whether the @t{_expand} completer will +first try to expand all substitutions in the string (such as +`@t{$(}@var{...}@t{)}' and `@t{$@{}@var{...}@t{@}}'). + +@noindent +The default is `true'. + +@kindex suffix, completion style +@item @t{suffix} +This is used by the @t{_expand} completer if the word starts with a +tilde or contains a parameter expansion. If it is set to `true', the +word will only be expanded if it doesn't have a suffix, i.e. if it is +something like `@t{~foo}' or `@t{$foo}' rather than `@t{~foo/}' or +`@t{$foo/bar}', unless that suffix itself contains characters eligible +for expansion. The default for this style is `true'. + +@kindex tag-order, completion style +@item @t{tag-order} +This provides a mechanism for sorting how the tags available in a +particular context will be used. + +@noindent +The values for the style are sets of space-separated lists of tags. +The tags in each value will be tried at the same time; if no match is +found, the next value is used. (See the @t{file-patterns} style for +an exception to this behavior.) + +@noindent +For example: + +@noindent +@example +zstyle ':completion:*:complete:-command-:*:*' tag-order \ + 'commands functions' +@end example + +@noindent +specifies that completion in command position first offers +external commands and shell functions. Remaining tags will be tried if +no completions are found. + +@noindent +In addition to tag names, each string in the value may take one of the +following forms: + +@noindent +@table @asis +@item @t{-} +If any value consists of only a hyphen, +then @emph{only} the tags specified in the other values are +generated. Normally all tags not explicitly selected are tried last +if the specified tags fail to generate any matches. This means +that a single value consisting only of a single hyphen +turns off completion. + +@item @t{!} @var{tags}... +A string starting with an exclamation mark +specifies names of tags that are @emph{not} to be used. The effect is +the same as if all other possible tags for the context had been +listed. + +@item @var{tag}@t{:}@var{label} ... +Here, @var{tag} is one of the standard tags and @var{label} is an +arbitrary name. Matches are generated as normal but the name @var{label} +is used in contexts instead of @var{tag}. This is not useful in words +starting with @t{!}. + +@noindent +If the @var{label} starts with a hyphen, the @var{tag} is prepended to the +@var{label} to form the name used for lookup. This can be +used to make the completion system try a certain tag more than once, +supplying different style settings for each attempt; see below for an +example. + +@item @var{tag}@t{:}@var{label}@t{:}@var{description} +As before, but @t{description} will replace the `@t{%d}' in +the value of the @t{format} style instead of the default description +supplied by the completion function. Spaces in the description must +be quoted with a backslash. A `@t{%d}' appearing +in @var{description} is replaced with the description given by the +completion function. + +@end table + +@noindent +In any of the forms above the tag may be a pattern or several +patterns in the form `@t{@{}@var{pat1}@t{,}@var{pat2...}@t{@}}'. In this +case all matching tags will be used except +for any given explicitly in the same string. + +@noindent +One use of these features is to try +one tag more than once, setting other styles differently on +each attempt, but still to use all the other tags without having to +repeat them all. For example, to make completion of function names in +command position ignore all the completion functions starting with an +underscore the first time completion is tried: + +@noindent +@example +zstyle ':completion:*:*:-command-:*:*' tag-order \ + 'functions:-non-comp *' functions +zstyle ':completion:*:functions-non-comp' \ + ignored-patterns '_*' +@end example + +@noindent +On the first attempt, all tags will be offered but the @t{functions} tag +will be replaced by @t{functions-non-comp}. The @t{ignored-patterns} style +is set for this tag to exclude functions starting with an underscore. +If there are no matches, the second value of the +@t{tag-order} style is used which completes functions using the default +tag, this time presumably including all function names. + +@noindent +The matches for one tag can be split into different groups. For example: + +@noindent +@example +zstyle ':completion:*' tag-order \ + 'options:-long:long\ options + options:-short:short\ options + options:-single-letter:single\ letter\ options' +zstyle ':completion:*:options-long' \ + ignored-patterns '[-+](|-|[^-]*)' +zstyle ':completion:*:options-short' \ + ignored-patterns '--*' '[-+]?' +zstyle ':completion:*:options-single-letter' \ + ignored-patterns '???*' +@end example + +@noindent +With the @t{group-names} style set, options beginning with +`@t{-}@t{-}', options beginning with a single `@t{-}' or `@t{+}' but +containing multiple characters, and single-letter options will be +displayed in separate groups with different descriptions. + +@noindent +Another use of patterns is to +try multiple match specifications one after another. The +@t{matcher-list} style offers something similar, but it is tested very +early in the completion system and hence can't be set for single +commands nor for more specific contexts. Here is how to +try normal completion without any match specification and, if that +generates no matches, try again with case-insensitive matching, restricting +the effect to arguments of the command @t{foo}: + +@noindent +@example +zstyle ':completion:*:*:foo:*:*' tag-order '*' '*:-case' +zstyle ':completion:*-case' matcher 'm:@{a-z@}=@{A-Z@}' +@end example + +@noindent +First, all the tags offered when completing after @t{foo} are tried using +the normal tag name. If that generates no matches, the second value of +@t{tag-order} is used, which tries all tags again except that this time +each has @t{-case} appended to its name for lookup of styles. Hence this +time the value for the @t{matcher} style from the second call to @t{zstyle} +in the example is used to make completion case-insensitive. + +@noindent +It is possible to use the @t{-e} option of the @t{zstyle} builtin +command to specify conditions for the use of particular tags. For +example: + +@noindent +@example +zstyle -e '*:-command-:*' tag-order ' + if [[ -n $PREFIX$SUFFIX ]]; then + reply=( ) + else + reply=( - ) + fi' +@end example + +@noindent +Completion in command position will be attempted only if the string +typed so far is not empty. This is tested using the @t{PREFIX} +special parameter; see +@ref{Completion Widgets} +for a description of parameters which are special inside completion widgets. +Setting @t{reply} to an empty array provides the default +behaviour of trying all tags at once; setting it to an +array containing only a hyphen disables the use of all tags and hence of +all completions. + +@noindent +If no @t{tag-order} style has been defined for a context, the strings +`@t{(|*-)argument-* (|*-)option-* values}' and `@t{options}' plus all +tags offered by the completion function will be used to provide a +sensible default behavior that causes arguments (whether normal command +arguments or arguments of options) to be completed before option names for +most commands. + +@kindex urls, completion style +@item @t{urls} +This is used together with the @t{urls} tag by +functions completing URLs. + +@noindent +If the value consists of more than one string, or if the only string +does not name a file or directory, the strings are used as the URLs to +complete. + +@noindent +If the value contains only one string which is the name of a normal +file the URLs are taken from that file (where the URLs may be +separated by white space or newlines). + +@noindent +Finally, if the only string in the value names a directory, the +directory hierarchy rooted at this directory gives the completions. The +top level directory should be the file access method, such as +`@t{http}', `@t{ftp}', `@t{bookmark}' and so on. In many cases the next +level of directories will be a filename. The directory hierarchy can +descend as deep as necessary. + +@noindent +For example, + +@noindent +@example +zstyle ':completion:*' urls ~/.urls +mkdir -p ~/.urls/ftp/ftp.zsh.org/pub + +@end example + +@noindent +allows completion of all the components of the URL +@t{ftp://ftp.zsh.org/pub} after suitable commands such as +`@t{netscape}' or `@t{lynx}'. Note, however, that access methods and +files are completed separately, so if the @t{hosts} style is set hosts +can be completed without reference to the @t{urls} style. + +@noindent +See the description in the function @t{_urls} itself +for more information (e.g. `@t{more $^fpath/_urls(N)}'). + +@kindex use-cache, completion style +@item @t{use-cache} +If this is set, the completion caching layer is activated for any completions +which use it (via the @t{_store_cache}, @t{_retrieve_cache}, and +@t{_cache_invalid} functions). The directory containing the cache +files can be changed with the @t{cache-path} style. + +@kindex use-compctl, completion style +@item @t{use-compctl} +If this style is set to a string @emph{not} equal to @t{false}, @t{0}, +@t{no}, and @t{off}, the completion system may use any completion +specifications defined with the @t{compctl} builtin command. If the +style is unset, this is done only if the @t{zsh/compctl} module +is loaded. The string may also contain the substring `@t{first}' to +use completions defined with `@t{compctl -T}', and the substring +`@t{default}' to use the completion defined with `@t{compctl -D}'. + +@noindent +Note that this is only intended to smooth the transition from +@t{compctl} to the new completion system and may disappear in the +future. + +@noindent +Note also that the definitions from @t{compctl} will only be used if +there is no specific completion function for the command in question. For +example, if there is a function @t{_foo} to complete arguments to the +command @t{foo}, @t{compctl} will never be invoked for @t{foo}. +However, the @t{compctl} version will be tried if @t{foo} only uses +default completion. + +@kindex use-ip, completion style +@item @t{use-ip} +By default, the function @t{_hosts} that completes host names strips +IP addresses from entries read from host databases such as NIS and +ssh files. If this style is `true', the corresponding IP addresses +can be completed as well. This style is not use in any context +where the @t{hosts} style is set; note also it must be set before +the cache of host names is generated (typically the first completion +attempt). + +@kindex users, completion style +@item @t{users} +This may be set to a list of usernames to be completed. +If it is not set all usernames will be completed. +Note that if it is set only that list of users will be completed; +this is because on some systems querying all users can take +a prohibitive amount of time. + +@kindex users-hosts, completion style +@item @t{users-hosts} +The values of this style should be of the form +`@var{user}@t{@@}@var{host}' or `@var{user}@t{:}@var{host}'. It is used for +commands that need pairs of +user- and hostnames. These commands will complete usernames from this +style (only), and will restrict subsequent hostname completion to hosts +paired with that user in one of the values of the style. + +@noindent +It is possible to group values for sets of commands which allow a remote +login, such as @t{rlogin} and @t{ssh}, by using the @t{my-accounts} tag. +Similarly, values for sets of commands which usually refer to the +accounts of other people, such as @t{talk} and @t{finger}, can be +grouped by using the @t{other-accounts} tag. More ambivalent commands +may use the @t{accounts} tag. + +@kindex users-hosts-ports, completion style +@item @t{users-hosts-ports} +Like @t{users-hosts} but used for commands like @t{telnet} and +containing strings of the form `@var{user}@t{@@}@var{host}@t{:}@var{port}'. + +@kindex verbose, completion style +@item @t{verbose} +If set, as it is by default, the completion listing is more verbose. +In particular many commands show descriptions for options if this +style is `true'. + +@kindex word, completion style +@item @t{word} +This is used by the @t{_list} completer, which prevents the insertion of +completions until a second completion attempt when the line has not +changed. The normal way of finding out if the line has changed is to +compare its entire contents between the two occasions. If this style is +`true', the comparison is instead performed only on the current word. +Hence if completion is performed on another word with the same contents, +completion will not be delayed. + +@end table + +@noindent +@node Control Functions, Bindable Commands, Completion System Configuration, Completion System + +@section Control Functions +@noindent +@cindex completion system, choosing completers + +@noindent +The initialization script @t{compinit} redefines all the widgets +which perform completion to call the supplied widget function +@t{_main_complete}. This function acts as a wrapper calling the +so-called `completer' functions that generate matches. If +@t{_main_complete} is called with arguments, these are taken as the +names of completer functions to be called in the order given. If no +arguments are given, the set of functions to try is taken from the +@t{completer} style. For example, to use normal completion and +correction if that doesn't generate any matches: + +@noindent +@example +zstyle ':completion:*' completer _complete _correct +@end example + +@noindent +after calling @t{compinit}. The default value for this style is +`@t{_complete _ignored}', i.e. normally only ordinary completion is tried, +first with the effect of the @t{ignored-patterns} style and then without +it. The @t{_main_complete} function uses the return status of the completer +functions to decide if other completers should be called. If the return +status is zero, no other completers are tried and the @t{_main_complete} +function returns. + +@noindent +If the first argument to @t{_main_complete} is a single hyphen, the +arguments will not be taken as names of completers. Instead, the +second argument gives a name to use in the @var{completer} field of the +context and the other arguments give a command name and arguments to +call to generate the matches. + +@noindent +The following completer functions are contained in the distribution, +although users may write their own. Note that in contexts the leading +underscore is stripped, for example basic completion is performed in the +context `@t{:completion::complete:}@var{...}'. + +@noindent +@cindex completion system, completers +@table @asis +@findex _all_matches +@item @t{_all_matches} +This completer can be used to add a string consisting of all other +matches. As it influences later completers it must appear as the first +completer in the list. The list of all matches is affected by the +@t{avoid-completer} and @t{old-matches} styles described above. + +@noindent +It may be useful to use the @t{_generic} function described below +to bind @t{_all_matches} to its own keystroke, for example: + +@noindent +@example +zle -C all-matches complete-word _generic +bindkey '^Xa' all-matches +zstyle ':completion:all-matches:*' old-matches only +zstyle ':completion:all-matches::::' completer _all_matches +@end example + +@noindent +Note that this does not generate completions by itself: first use +any of the standard ways of generating a list of completions, +then use @t{^Xa} to show all matches. It is possible instead to +add a standard completer to the list and request that the +list of all matches should be directly inserted: + +@noindent +@example +zstyle ':completion:all-matches::::' completer \ + _all_matches _complete +zstyle ':completion:all-matches:*' insert true +@end example + +@noindent +In this case the @t{old-matches} style should not be set. + +@findex _approximate +@item @t{_approximate} +This is similar to the basic @t{_complete} completer but allows the +completions to undergo corrections. The maximum number of errors can be +specified by the @t{max-errors} style; see the description of +approximate matching in +@ref{Filename Generation} +for how errors are counted. Normally this completer will only be tried +after the normal @t{_complete} completer: + +@noindent +@example +zstyle ':completion:*' completer _complete _approximate +@end example + +@noindent +This will give correcting completion if and only if +normal completion yields no possible completions. When +corrected completions are found, the completer will normally start +menu completion allowing you to cycle through these strings. + +@noindent +This completer uses the tags @t{corrections} and @t{original} when +generating the possible corrections and the original string. The +@t{format} style for the former may contain the additional sequences +`@t{%e}' and `@t{%o}' which will be replaced by the number of errors +accepted to generate the corrections and the original string, +respectively. + +@noindent +The completer progressively increases the number of errors allowed up to +the limit by the @t{max-errors} style, hence if a completion is found +with one error, no completions with two errors will be shown, and so on. +It modifies the completer name in the context to indicate the number of +errors being tried: on the first try the completer field contains +`@t{approximate-1}', on the second try `@t{approximate-2}', and so on. + +@noindent +When @t{_approximate} is called from another function, the number of +errors to accept may be passed with the @t{-a} option. The argument +is in the same format as the @t{max-errors} style, all in one string. + +@noindent +Note that this completer (and the @t{_correct} completer mentioned +below) can be quite expensive to call, especially when a large number +of errors are allowed. One way to avoid this is to set up the +@t{completer} style using the @t{-e} option to zstyle so that some +completers are only used when completion is attempted a second time on +the same string, e.g.: + +@noindent +@example +zstyle -e ':completion:*' completer ' + if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then + _last_try="$HISTNO$BUFFER$CURSOR" + reply=(_complete _match _prefix) + else + reply=(_ignored _correct _approximate) + fi' +@end example + +@noindent +This uses the @t{HISTNO} parameter and the @t{BUFFER} and @t{CURSOR} +special parameters that are available inside zle and completion +widgets to find out if the command line hasn't changed since the last +time completion was tried. Only then are the @t{_ignored}, +@t{_correct} and @t{_approximate} completers called. + +@findex _canonical_paths +@item @t{_canonical_paths} [ @t{-A} @var{var} ] [ @t{-N} ] [ @t{-MJV12nfX} ] @var{tag} @var{descr} [ @var{paths} ... ] +This completion function completes all paths given to it, and also tries to +offer completions which point to the same file as one of the paths given +(relative path when an absolute path is given, and vice versa; when @t{..}'s +are present in the word to be completed; and some paths got from symlinks). + +@noindent +@t{-A}, if specified, takes the paths from the array variable specified. Paths can +also be specified on the command line as shown above. @t{-N}, if specified, +prevents canonicalizing the paths given before using them for completion, in +case they are already so. The options @t{-M}, @t{-J}, @t{-V}, @t{-1}, @t{-2}, +@t{-n}, @t{-F}, @t{-X} are passed to @t{compadd}. + +@noindent +See @t{_description} for a description of @var{tag} and @var{descr}. + +@findex _cmdambivalent +@item @t{_cmdambivalent} +Completes the remaining positional arguments as an external command. +The external command and its arguments are completed as separate arguments +(in a manner appropriate for completing @t{/usr/bin/env}) +if there are two or more remaining positional arguments on the command line, +and as a quoted command string (in the manner of @t{system(...)}) otherwise. +See also @t{_cmdstring} and @t{_precommand}. + +@noindent +This function takes no arguments. + +@findex _cmdstring +@item @t{_cmdstring} +Completes an external command as a single argument, as for +@t{system(...)}. + +@findex _complete +@item @t{_complete} +This completer generates all possible completions in a context-sensitive +manner, i.e. using the settings defined with the @t{compdef} function +explained above and the current settings of all special parameters. +This gives the normal completion behaviour. + +@noindent +To complete arguments of commands, @t{_complete} uses the utility function +@t{_normal}, which is in turn responsible for finding the particular +function; it is described below. Various contexts of the form +@t{-}@var{context}@t{-} are handled specifically. These are all +mentioned above as possible arguments to the @t{#compdef} tag. + +@noindent +Before trying to find a function for a specific context, @t{_complete} +checks if the parameter `@t{compcontext}' is set. Setting +`@t{compcontext}' allows the usual completion dispatching to be +overridden which is useful in places such as a function that uses +@t{vared} for input. If it is set to an array, the elements are taken +to be the possible matches which will be completed using the tag +`@t{values}' and the description `@t{value}'. If it is set to an +associative array, the keys are used as the possible completions and +the values (if non-empty) are used as descriptions for the matches. If +`@t{compcontext}' is set to a string containing colons, it should be of +the form `@var{tag}@t{:}@var{descr}@t{:}@var{action}'. In this case the +@var{tag} and @var{descr} give the tag and description to use and the +@var{action} indicates what should be completed in one of the forms +accepted by the @t{_arguments} utility function described below. + +@noindent +Finally, if `@t{compcontext}' is set to a string without colons, the +value is taken as the name of the context to use and the function +defined for that context will be called. For this purpose, there is a +special context named @t{-command-line-} that completes whole command +lines (commands and their arguments). This is not used by the completion +system itself but is nonetheless handled when explicitly called. + +@findex _correct +@item @t{_correct} +Generate corrections, but not completions, for the current word; this is +similar to @t{_approximate} but will not allow any number of extra +characters at the cursor as that completer does. The effect is +similar to spell-checking. It is based on @t{_approximate}, but the +completer field in the context name is @t{correct}. + +@noindent +For example, with: + +@noindent +@example +zstyle ':completion:::::' completer \ + _complete _correct _approximate +zstyle ':completion:*:correct:::' max-errors 2 not-numeric +zstyle ':completion:*:approximate:::' max-errors 3 numeric +@end example + +@noindent +correction will accept up to two errors. If a numeric argument is +given, correction will not be performed, but correcting completion +will be, and will accept as many errors as given by the numeric +argument. Without a numeric argument, first correction and then +correcting completion will be tried, with the first one accepting two +errors and the second one accepting three errors. + +@noindent +When @t{_correct} is called as a function, the number of errors to accept +may be given following the @t{-a} option. The argument is in the same +form a values to the @t{accept} style, all in one string. + +@noindent +This completer function is intended to be used without the +@t{_approximate} completer or, as in the example, just before +it. Using it after the @t{_approximate} completer is useless since +@t{_approximate} will at least generate the corrected strings +generated by the @t{_correct} completer --- and probably more. + +@findex _expand +@item @t{_expand} +This completer function does not really perform completion, but instead +checks if the word on the command line is eligible for expansion and, +if it is, gives detailed control over how this expansion is done. For +this to happen, the completion system needs to be invoked with +@t{complete-word}, not @t{expand-or-complete} (the default binding for +@t{TAB}), as otherwise the string will be expanded by the shell's +internal mechanism before the completion system is started. +Note also this completer should be called before the @t{_complete} +completer function. + +@noindent +The tags used when generating expansions are @t{all-expansions} for the +string containing all possible expansions, @t{expansions} when adding +the possible expansions as single matches and @t{original} when adding +the original string from the line. The order in which these strings are +generated, if at all, can be controlled by the @t{group-order} and +@t{tag-order} styles, as usual. + +@noindent +The format string for @t{all-expansions} and for @t{expansions} may +contain the sequence `@t{%o}' which will be replaced by the original +string from the line. + +@noindent +The kind of expansion to be tried is controlled by the @t{substitute}, +@t{glob} and @t{subst-globs-only} styles. + +@noindent +It is also possible to call @t{_expand} as a function, in which case the +different modes may be selected with options: @t{-s} for +@t{substitute}, @t{-g} for @t{glob} and @t{-o} for @t{subst-globs-only}. + +@findex _expand_alias +@item @t{_expand_alias} +If the word the cursor is on is an alias, it is expanded and no other +completers are called. The types of aliases which are to be expanded can +be controlled with the styles @t{regular}, @t{global} and @t{disabled}. + +@noindent +This function is also a bindable command, see +@ref{Bindable Commands}. + +@findex _extensions +@item @t{_extensions} +If the cursor follows the string `@t{*.}', filename extensions are +completed. The extensions are taken from files in current directory or a +directory specified at the beginning of the current word. For exact matches, +completion continues to allow other completers such as @t{_expand} to +expand the pattern. The standard @t{add-space} and @t{prefix-hidden} +styles are observed. + +@findex _external_pwds +@item @t{_external_pwds} +Completes current directories of other zsh processes belonging to the +current user. + +@noindent +This is intended to be used via @t{_generic}, bound to a custom key +combination. Note that pattern matching is enabled so matching is +performed similar to how it works with the @t{_match} completer. + +@findex _history +@item @t{_history} +Complete words from the shell's command history. This completer +can be controlled by the @t{remove-all-dups}, and @t{sort} styles as for the +@t{_history_complete_word} bindable command, see +@ref{Bindable Commands} +and +@ref{Completion System Configuration}. + +@findex _ignored +@item @t{_ignored} +The @t{ignored-patterns} style can be set to a list of patterns which are +compared against possible completions; matching ones are removed. +With this completer those matches can be reinstated, as +if no @t{ignored-patterns} style were set. The completer actually +generates its own list of matches; which completers are invoked +is determined in the same way as for the @t{_prefix} completer. +The @t{single-ignored} style is also available as described above. + +@findex _list +@item @t{_list} +This completer allows the insertion of matches to be delayed until +completion is attempted a second time without the word on the line +being changed. On the first attempt, only the list of matches will be +shown. It is affected by the styles @t{condition} and @t{word}, see +@ref{Completion System Configuration}. + +@findex _match +@item @t{_match} +This completer is intended to be used after the @t{_complete} +completer. It behaves similarly but the string on the command line may +be a pattern to match against trial completions. This gives the effect +of the @t{GLOB_COMPLETE} option. + +@noindent +Normally completion will be performed by taking the pattern from the line, +inserting a `@t{*}' at the cursor position and comparing the resulting +pattern with the possible completions generated. This can be modified +with the @t{match-original} style described above. + +@noindent +The generated matches will be offered in a menu completion unless the +@t{insert-unambiguous} style is set to `true'; see the description above +for other options for this style. + +@noindent +Note that matcher specifications defined globally or used by the +completion functions (the styles @t{matcher-list} and @t{matcher}) will +not be used. + +@findex _menu +@item @t{_menu} +This completer was written as simple example function to show how menu +completion can be enabled in shell code. However, it has the notable +effect of disabling menu selection which can be useful with +@t{_generic} based widgets. It should be used as the first completer in +the list. Note that this is independent of the setting of the +@t{MENU_COMPLETE} option and does not work with the other menu +completion widgets such as @t{reverse-menu-complete}, or +@t{accept-and-menu-complete}. + +@findex _oldlist +@item @t{_oldlist} +This completer controls how the standard completion widgets behave +when there is an existing list of completions which may have been +generated by a special completion (i.e. a separately-bound completion +command). It allows the ordinary completion keys to continue to use the +list of completions thus generated, instead of producing a new list of +ordinary contextual completions. +It should appear in the list of completers before any of +the widgets which generate matches. It uses two styles: @t{old-list} and +@t{old-menu}, see +@ref{Completion System Configuration}. + +@findex _precommand +@item @t{_precommand} +Complete an external command in word-separated arguments, as for +@t{exec} and @t{/usr/bin/env}. + +@findex _prefix +@item @t{_prefix} +This completer can be used to try completion with the suffix (everything +after the cursor) ignored. In other words, the suffix will not be +considered to be part of the word to complete. The effect is similar +to the @t{expand-or-complete-prefix} command. + +@noindent +The @t{completer} style is used to decide which other completers are to +be called to generate matches. If this style is unset, the list of +completers set for the current context is used --- except, of course, the +@t{_prefix} completer itself. Furthermore, if this completer appears +more than once in the list of completers only those completers not +already tried by the last invocation of @t{_prefix} will be called. + +@noindent +For example, consider this global @t{completer} style: + +@noindent +@example +zstyle ':completion:*' completer \ + _complete _prefix _correct _prefix:foo +@end example + +@noindent +Here, the @t{_prefix} completer tries normal completion but ignoring the +suffix. If that doesn't generate any matches, and neither does +the call to the @t{_correct} completer after it, @t{_prefix} will +be called a second time and, now only trying correction with the +suffix ignored. On the second invocation the completer part of the +context appears as `@t{foo}'. + +@noindent +To use @t{_prefix} as the last resort and try only normal completion +when it is invoked: + +@noindent +@example +zstyle ':completion:*' completer _complete ... _prefix +zstyle ':completion::prefix:*' completer _complete +@end example + +@noindent +The @t{add-space} style is also respected. If it is set to `true' then +@t{_prefix} will insert a space between the matches generated (if any) +and the suffix. + +@noindent +Note that this completer is only useful if the +@t{COMPLETE_IN_WORD} option is set; otherwise, the cursor will +be moved to the end of the current word before the completion code is +called and hence there will be no suffix. + +@findex _user_expand +@item @t{_user_expand} +This completer behaves similarly to the @t{_expand} completer but +instead performs expansions defined by users. The styles @t{add-space} and +@t{sort} styles specific to the @t{_expand} completer are usable with +@t{_user_expand} in addition to other styles handled more generally by +the completion system. The tag @t{all-expansions} is also available. + +@noindent +The expansion depends on the array style @t{user-expand} being defined +for the current context; remember that the context for completers is less +specific than that for contextual completion as the full context has not +yet been determined. Elements of the array may have one of the following +forms: + +@noindent +@table @asis +@item @t{$}@var{hash} + +@var{hash} is the name of an associative array. Note this is not a full +parameter expression, merely a @t{$}, suitably quoted to prevent immediate +expansion, followed by the name of an associative array. If the trial +expansion word matches a key in @var{hash}, the resulting expansion is the +corresponding value. + +@item @var{_func} + +@var{_func} is the name of a shell function whose name must begin with +@t{_} but is not otherwise special to the completion system. The function +is called with the trial word as an argument. If the word is to be +expanded, the function should set the array @t{reply} to a list of +expansions. Optionally, it can set @t{REPLY} to a word that will +be used as a description for the set of expansions. +The return status of the function is irrelevant. + +@end table + +@end table + +@noindent +@node Bindable Commands, Completion Functions, Control Functions, Completion System + +@section Bindable Commands +@noindent +@cindex completion system, bindable commands + +@noindent +In addition to the context-dependent completions provided, which are +expected to work in an intuitively obvious way, there are a few widgets +implementing special behaviour which can be bound separately to keys. The +following is a list of these and their default bindings. + +@noindent +@table @asis +@findex _bash_completions +@item @t{_bash_completions} +This function is used by two widgets, @t{_bash_complete-word} and +@t{_bash_list-choices}. It exists to provide compatibility with +completion bindings in bash. The last character of the binding determines +what is completed: `@t{!}', command names; `@t{$}', environment variables; +`@t{@@}', host names; `@t{/}', file names; `@t{~}' user names. In bash, the +binding preceded by `@t{\e}' gives completion, and preceded by `@t{^X}' +lists options. As some of these bindings clash with standard zsh +bindings, only `@t{\e~}' and `@t{^X~}' are bound by default. To add the +rest, the following should be added to @t{.zshrc} after @t{compinit} has +been run: + +@noindent +@example +for key in '!' '$' '@@' '/' '~'; do + bindkey "\e$key" _bash_complete-word + bindkey "^X$key" _bash_list-choices +done +@end example + +@noindent +This includes the bindings for `@t{~}' in case they were already bound to +something else; the completion code does not override user bindings. + +@findex _correct_filename (^XC) +@item @t{_correct_filename} (@t{^XC}) +Correct the filename path at the cursor position. Allows up to six errors +in the name. Can also be called with an argument to correct +a filename path, independently of zle; the correction is printed on +standard output. + +@findex _correct_word (^Xc) +@item @t{_correct_word} (@t{^Xc}) +Performs correction of the current argument using the usual contextual +completions as possible choices. This stores the string +`@t{correct-word}' in the @var{function} field of the context name and +then calls the @t{_correct} completer. + +@findex _expand_alias (^Xa) +@item @t{_expand_alias} (@t{^Xa}) +This function can be used as a completer and as a bindable command. +It expands the word the cursor is on if it is an alias. The types of +alias expanded can be controlled with the styles @t{regular}, @t{global} +and @t{disabled}. + +@noindent +When used as a bindable command there is one additional feature that +can be selected by setting the @t{complete} style to `true'. In this +case, if the word is not the name of an alias, @t{_expand_alias} tries +to complete the word to a full alias name without expanding it. It +leaves the cursor directly after the completed word so that invoking +@t{_expand_alias} once more will expand the now-complete alias name. + +@findex _expand_word (^Xe) +@item @t{_expand_word} (@t{^Xe}) +Performs expansion on the current word: equivalent to the standard +@t{expand-word} command, but using the @t{_expand} completer. Before +calling it, the @var{function} field of the context is set to +`@t{expand-word}'. + +@findex _generic +@item @t{_generic} +This function is not defined as a widget and not bound by +default. However, it can be used to define a widget and will then +store the name of the widget in the @var{function} field of the context +and call the completion system. This allows custom completion widgets +with their own set of style settings to be defined easily. For example, +to define a widget that performs normal completion and starts +menu selection: + +@noindent +@example +zle -C foo complete-word _generic +bindkey '...' foo +zstyle ':completion:foo:*' menu yes select=1 +@end example + +@noindent +Note in particular that the @t{completer} style may be set for the context +in order to change the set of functions used to generate possible matches. +If @t{_generic} is called with arguments, those are passed through to +@t{_main_complete} as the list of completers in place of those defined by +the @t{completer} style. + +@findex _history_complete_word (\e/) +@item @t{_history_complete_word} (@t{\e/}) +Complete words from the shell's command history. This uses the +@t{list}, @t{remove-all-dups}, @t{sort}, and @t{stop} styles. + +@findex _most_recent_file (^Xm) +@item @t{_most_recent_file} (@t{^Xm}) +Complete the name of the most recently modified file matching the pattern +on the command line (which may be blank). If given a numeric argument +@var{N}, complete the @var{N}th most recently modified file. Note the +completion, if any, is always unique. + +@findex _next_tags (^Xn) +@item @t{_next_tags} (@t{^Xn}) +This command alters the set of matches used to that for the next tag, or +set of tags, either as given by the @t{tag-order} style or as set by +default; these matches would otherwise not be available. +Successive invocations of the command cycle through all possible sets of +tags. + +@findex _read_comp (^X^R) +@item @t{_read_comp} (@t{^X^R}) +Prompt the user for a string, and use that to perform completion on the +current word. There are two possibilities for the string. First, it can +be a set of words beginning `@t{_}', for example `@t{_files -/}', in which +case the function with any arguments will be called to generate the +completions. Unambiguous parts of the function name will be completed +automatically (normal completion is not available at this point) until a +space is typed. + +@noindent +Second, any other string will be passed as a set of arguments to +@t{compadd} and should hence be an expression specifying what should +be completed. + +@noindent +A very restricted set of editing commands is available when reading the +string: `@t{DEL}' and `@t{^H}' delete the last character; `@t{^U}' deletes +the line, and `@t{^C}' and `@t{^G}' abort the function, while `@t{RET}' +accepts the completion. Note the string is used verbatim as a command +line, so arguments must be quoted in accordance with standard shell rules. + +@noindent +Once a string has been read, the next call to @t{_read_comp} will use the +existing string instead of reading a new one. To force a new string to be +read, call @t{_read_comp} with a numeric argument. + +@findex _complete_debug (^X?) +@item @t{_complete_debug} (@t{^X?}) +This widget performs ordinary completion, but captures in a temporary file +a trace of the shell commands executed by the completion system. Each +completion attempt gets its own file. A command to view each of these +files is pushed onto the editor buffer stack. + +@findex _complete_help (^Xh) +@item @t{_complete_help} (@t{^Xh}) +This widget displays information about the context names, +the tags, and the completion functions used +when completing at the current cursor position. If given a numeric +argument other than @t{1} (as in `@t{ESC-2 ^Xh}'), then the styles +used and the contexts for which they are used will be shown, too. + +@noindent +Note that the information about styles may be incomplete; it depends on the +information available from the completion functions called, which in turn +is determined by the user's own styles and other settings. + +@findex _complete_help_generic +@item @t{_complete_help_generic} +Unlike other commands listed here, this must be created as a normal ZLE +widget rather than a completion widget (i.e. with @t{zle -N}). It +is used for generating help with a widget bound to the @t{_generic} +widget that is described above. + +@noindent +If this widget is created using the name of the function, as it is by +default, then when executed it will read a key sequence. This is expected +to be bound to a call to a completion function that uses the @t{_generic} +widget. That widget will be executed, and information provided in +the same format that the @t{_complete_help} widget displays for +contextual completion. + +@noindent +If the widget's name contains @t{debug}, for example if it is created +as `@t{zle -N _complete_debug_generic _complete_help_generic}', it +will read and execute the keystring for a generic widget as before, +but then generate debugging information as done by @t{_complete_debug} +for contextual completion. + +@noindent +If the widget's name contains @t{noread}, it will not read a keystring +but instead arrange that the next use of a generic widget run in +the same shell will have the effect as described above. + +@noindent +The widget works by setting the shell parameter +@t{ZSH_TRACE_GENERIC_WIDGET} which is read by @t{_generic}. Unsetting +the parameter cancels any pending effect of the @t{noread} form. + +@noindent +For example, after executing the following: + +@noindent +@example +zle -N _complete_debug_generic _complete_help_generic +bindkey '^x:' _complete_debug_generic +@end example + +@noindent +typing `@t{C-x :}' followed by the key sequence for a generic widget +will cause trace output for that widget to be saved to a file. + +@findex _complete_tag (^Xt) +@item @t{_complete_tag} (@t{^Xt}) +This widget completes symbol tags created by the @t{etags} or @t{ctags} +programmes (note there is no connection with the completion system's tags) +stored in a file @t{TAGS}, in the format used by @t{etags}, or @t{tags}, in the +format created by @t{ctags}. It will look back up the path hierarchy for +the first occurrence of either file; if both exist, the file @t{TAGS} is +preferred. You can specify the full path to a @t{TAGS} or @t{tags} file by +setting the parameter @t{$TAGSFILE} or @t{$tagsfile} respectively. +The corresponding completion tags used are @t{etags} and @t{vtags}, after +emacs and vi respectively. + +@end table + +@noindent +@node Completion Functions, Completion System Variables, Bindable Commands, Completion System + +@section Utility Functions +@noindent +@cindex completion system, utility functions + +@noindent +Descriptions follow for utility functions that may be +useful when writing completion functions. If functions are installed in +subdirectories, most of these reside in the +@t{Base} subdirectory. Like the example +functions for commands in the distribution, the utility functions +generating matches all follow the convention of returning status zero if they +generated completions and non-zero if no matching completions could be +added. + +@noindent +@table @asis +@findex _absolute_command_paths +@item @t{_absolute_command_paths} +This function completes external commands as absolute paths (unlike +@t{_command_names -e} which completes their basenames). It takes no +arguments. + +@findex _all_labels +@item @t{_all_labels} [ @t{-x} ] [ @t{-12VJ} ] @var{tag} @var{name} @var{descr} [ @var{command} @var{arg} ... ] +This is a convenient interface to the @t{_next_label} function below, +implementing the loop shown in the @t{_next_label} example. The +@var{command} and its arguments are called to generate the matches. The +options stored in the parameter @var{name} will automatically be inserted +into the @var{arg}s passed to the @var{command}. Normally, they are put +directly after the @var{command}, but if one of the @var{arg}s is a single +hyphen, they are inserted directly before that. If the hyphen is the last +argument, it will be removed from the argument list before the +@var{command} is called. This allows @t{_all_labels} to be used in almost all +cases where the matches can be generated by a single call to the +@t{compadd} builtin command or by a call to one of the utility functions. + +@noindent +For example: + +@noindent +@example +local expl +... +if _requested foo; then + ... + _all_labels foo expl '...' compadd ... - $matches +fi +@end example + +@noindent +Will complete the strings from the @t{matches} parameter, using +@t{compadd} with additional options which will take precedence over +those generated by @t{_all_labels}. + +@findex _alternative +@item @t{_alternative} [ @t{-O} @var{name} ] [ @t{-C} @var{name} ] @var{spec} ... +This function is useful in simple cases where multiple tags are available. +Essentially it implements a loop like the one described for the @t{_tags} +function below. + +@noindent +The tags to use and the action to perform if a tag is requested are +described using the @var{spec}s which are of the form: +`@var{tag}@t{:}@var{descr}@t{:}@var{action}'. The @var{tag}s are offered using +@t{_tags} and if the tag is requested, the @var{action} is executed with the +given description @var{descr}. The @var{action}s are those accepted +by the @t{_arguments} function (described below), excluding the +`@t{->}@var{state}' and `@t{=}@var{...}' forms. + +@noindent +For example, the @var{action} may be a simple function call: + +@noindent +@example +_alternative \ + 'users:user:_users' \ + 'hosts:host:_hosts' +@end example + +@noindent +offers usernames and hostnames as possible matches, +generated by the @t{_users} and @t{_hosts} functions respectively. + +@noindent +Like @t{_arguments}, this function uses @t{_all_labels} to execute +the actions, which will loop over all sets of tags. Special handling is +only required if there is an additional valid tag, for example inside a +function called from @t{_alternative}. + +@noindent +The option `@t{-O} @var{name}' is used in the same way as by the +@t{_arguments} function. In other words, the elements of the @var{name} +array will be passed to @t{compadd} when executing an action. + +@noindent +Like @t{_tags} this function supports the @t{-C} option to give a +different name for the argument context field. + +@findex _arguments + +@item @t{_arguments }[ @t{-nswWCRS} ] [ @t{-A} @var{pat} ] [ @t{-O} @var{name} ] [ @t{-M} @var{matchspec} ] +@itemx @t{@ @ @ @ @ @ @ @ @ @ @ }[ @t{:} ] @var{spec} ... +@itemx @t{_arguments }[ @var{opt} ... ] @t{-}@t{-} [ @t{-l} ] [ @t{-i} @var{pats} ] [ @t{-s} @var{pair} ] +@itemx @t{@ @ @ @ @ @ @ @ @ @ @ }[ @var{helpspec} ...] +This function can be used to give a complete specification for completion +for a command whose arguments follow standard UNIX option and argument +conventions. + +@noindent +@emph{Options Overview} + +@noindent +Options to @t{_arguments} itself must be in separate words, i.e. @t{-s -w}, +not @t{-sw}. The options are followed by @var{spec}s that describe options and +arguments of the analyzed command. To avoid ambiguity, all +options to @t{_arguments} itself may be separated from the @var{spec} forms +by a single colon. + +@noindent +The `@t{-}@t{-}' +form is used to intuit @var{spec} forms from the help output of the command +being analyzed, and is described in detail below. The @var{opts} for the +`@t{-}@t{-}' form are otherwise the same options as the first form. Note +that `@t{-s}' following `@t{-}@t{-}' has a distinct meaning from `@t{-s}' +preceding `@t{-}@t{-}', and both may appear. + +@noindent +The option switches @t{-s}, @t{-S}, @t{-A}, @t{-w}, and @t{-W} affect how +@t{_arguments} parses the analyzed command line's options. These switches are +useful for commands with standard argument parsing. + +@noindent +The options of @t{_arguments} have the following meanings: + +@noindent +@table @asis +@item @t{-n} +With this option, @t{_arguments} sets the parameter @t{NORMARG} +to the position of the first normal argument in the @t{$words} array, +i.e. the position after the end of the options. If that argument +has not been reached, @t{NORMARG} is set to @t{-1}. The caller +should declare `@t{integer NORMARG}' if the @t{-n} option is passed; +otherwise the parameter is not used. + +@item @t{-s} +Enable @emph{option stacking} for single-letter options, whereby multiple +single-letter options may be combined into a single word. For example, +the two options `@t{-x}' and `@t{-y}' may be combined into +a single word `@t{-xy}'. By default, every word corresponds to a single +option name (`@t{-xy}' is a single option named `@t{xy}'). + +@noindent +Options beginning with a single hyphen or plus sign are eligible for stacking; +words beginning with two hyphens are not. + +@noindent +Note that @t{-s} after @t{-}@t{-} has a different meaning, which is documented +in the segment entitled `Deriving @var{spec} forms from the help output'. + +@item @t{-w} +In combination with @t{-s}, allow option stacking +even if one or more of the options take +arguments. For example, if @t{-x} takes an argument, with no +@t{-s}, `@t{-xy}' is considered as a single (unhandled) option; with +@t{-s}, @t{-xy} is an option with the argument `@t{y}'; with both @t{-s} +and @t{-w}, @t{-xy} is the option @t{-x} and the option @t{-y} with +arguments to @t{-x} (and to @t{-y}, if it takes arguments) still to come +in subsequent words. + +@item @t{-W} +This option takes @t{-w} a stage further: it is possible to +complete single-letter options even after an argument that occurs in the +same word. However, it depends on the action performed whether options +will really be completed at this point. For more control, use a +utility function like @t{_guard} as part of the action. + +@item @t{-C} +Modify the @t{curcontext} parameter for an action of the form `@t{->}@var{state}'. +This is discussed in detail below. + +@item @t{-R} +Return status 300 instead of zero when a @t{$state} is to +be handled, in the `@t{->}@var{string}' syntax. + +@item @t{-S} +Do not complete options after a `@t{-}@t{-}' appearing on the line, +and ignore the `@t{-}@t{-}'. For example, with @t{-S}, in the line + +@noindent +@example +foobar -x -- -y +@end example + +@noindent +the `@t{-x}' is considered an option, the `@t{-y}' is considered an +argument, and the `@t{-}@t{-}' is considered to be neither. + +@item @t{-A} @var{pat} +Do not complete options after the first non-option +argument on the line. @var{pat} is a pattern matching +all strings which are not to be taken as arguments. For example, to make +@t{_arguments} stop completing options after the first normal argument, but +ignoring all strings starting with a hyphen even if they are not described +by one of the @var{optspec}s, the form is `@t{-A "-*"}'. + +@item @t{-O} @var{name} +Pass the elements of the array @var{name} as arguments to functions called to +execute @var{action}s. +This is discussed in detail below. + +@item @t{-M} @var{matchspec} +Use the match specification @var{matchspec} for completing option names and values. +The default @var{matchspec} allows partial word completion after `@t{_}' and +`@t{-}', such as completing `@t{-f-b}' to `@t{-foo-bar}'. The default +@var{matchspec} is: +@example +@t{r:|[_-]=* r:|=*} +@end example + +@end table + +@noindent +@emph{@var{spec}s: overview} + +@noindent +Each of the following forms is a @var{spec} describing individual sets of +options or arguments on the command line being analyzed. + +@noindent +@table @asis +@item @var{n}@t{:}@var{message}@t{:}@var{action} +@itemx @var{n}@t{::}@var{message}@t{:}@var{action} +This describes the @var{n}'th normal argument. The @var{message} will be +printed above the matches generated and the @var{action} indicates what can +be completed in this position (see below). If there are two colons +before the @var{message} the argument is optional. If the +@var{message} contains only white space, nothing will be printed above +the matches unless the action adds an explanation string itself. + +@item @t{:}@var{message}@t{:}@var{action} +@itemx @t{::}@var{message}@t{:}@var{action} +Similar, but describes the @emph{next} argument, whatever number that +happens to be. If all arguments are specified in this form in the +correct order the numbers are unnecessary. + +@item @t{*:}@var{message}@t{:}@var{action} +@itemx @t{*::}@var{message}@t{:}@var{action} +@itemx @t{*:::}@var{message}@t{:}@var{action} +This describes how arguments (usually non-option arguments, those not +beginning with @t{-} or @t{+}) are to be completed when neither +of the first two forms was provided. Any number of arguments can +be completed in this fashion. + +@noindent +With two colons before the @var{message}, the @t{words} special array and +the @t{CURRENT} special parameter are modified to refer only to the +normal arguments when the @var{action} is executed or evaluated. With +three colons before the @var{message} they are modified to refer only to +the normal arguments covered by this description. + +@item @var{optspec} +@itemx @var{optspec}@t{:}@var{...} +This describes an option. The colon indicates handling for one or more +arguments to the option; if it is not present, the option is assumed to +take no arguments. + +@noindent +The following forms are available for the initial @var{optspec}, whether +or not the option has arguments. + +@noindent +@table @asis +@item @t{*}@var{optspec} +Here @var{optspec} is one of the remaining forms below. This indicates +the following @var{optspec} may be repeated. Otherwise if the +corresponding option is already present on the command line to the left +of the cursor it will not be offered again. + +@item @t{-}@var{optname} +@itemx @t{+}@var{optname} +In the simplest form the @var{optspec} is just the option name beginning +with a minus or a plus sign, such as `@t{-foo}'. The first argument for +the option (if any) must follow as a @emph{separate} word directly after the +option. + +@noindent +Either of `@t{-+}@var{optname}' and `@t{+-}@var{optname}' can be used to +specify that @t{-}@var{optname} and @t{+}@var{optname} are both valid. + +@noindent +In all the remaining forms, the leading `@t{-}' may be replaced by or +paired with `@t{+}' in this way. + +@item @t{-}@var{optname}@t{-} +The first argument of the option must come directly after the option name +@emph{in the same word}. For example, `@t{-foo-:}@var{...}' specifies that +the completed option and argument will look like `@t{-foo}@var{arg}'. + +@item @t{-}@var{optname}@t{+} +The first argument may appear immediately after @var{optname} in the same +word, or may appear as a separate word after the option. For example, +`@t{-foo+:}@var{...}' specifies that the completed option and argument +will look like either `@t{-foo}@var{arg}' or `@t{-foo} @var{arg}'. + +@item @t{-}@var{optname}@t{=} +The argument may appear as the next word, or in same word as the option +name provided that it is separated from it by an equals sign, for +example `@t{-foo=}@var{arg}' or `@t{-foo} @var{arg}'. + +@item @t{-}@var{optname}@t{=-} +The argument to the option must appear after an equals sign in the same +word, and may not be given in the next argument. + +@item @var{optspec}@t{[}@var{explanation}@t{]} +An explanation string may be appended to any of the preceding forms of +@var{optspec} by enclosing it in brackets, as in `@t{-q[query operation]}'. + +@noindent +The @t{verbose} style is used to decide whether the explanation strings +are displayed with the option in a completion listing. + +@noindent +If no bracketed explanation string is given but the @t{auto-description} +style is set and only one argument is described for this @var{optspec}, the +value of the style is displayed, with any appearance of the sequence +`@t{%d}' in it replaced by the @var{message} of the first @var{optarg} +that follows the @var{optspec}; see below. + +@end table + +@noindent +It is possible for options with a literal `@t{+}' or `@t{=}' to +appear, but that character must be quoted, for example `@t{-\+}'. + +@noindent +Each @var{optarg} following an @var{optspec} must take one of the +following forms: + +@noindent +@table @asis +@item @t{:}@var{message}@t{:}@var{action} +@itemx @t{::}@var{message}@t{:}@var{action} +An argument to the option; @var{message} and @var{action} are treated as +for ordinary arguments. In the first form, the argument is mandatory, +and in the second form it is optional. + +@noindent +This group may be repeated for options which take multiple arguments. +In other words, +@t{:}@var{message1}@t{:}@var{action1}@t{:}@var{message2}@t{:}@var{action2} +specifies that the option takes two arguments. + +@item @t{:*}@var{pattern}@t{:}@var{message}@t{:}@var{action} +@itemx @t{:*}@var{pattern}@t{::}@var{message}@t{:}@var{action} +@itemx @t{:*}@var{pattern}@t{:::}@var{message}@t{:}@var{action} +This describes multiple arguments. Only the last @var{optarg} for +an option taking multiple arguments may be +given in this form. If the @var{pattern} is empty (i.e. @t{:*:}), all +the remaining words on the line are to be completed as described by the +@var{action}; otherwise, all the words up to and including a word matching +the @var{pattern} are to be completed using the @var{action}. + +@noindent +Multiple colons are treated as for the `@t{*:}@var{...}' forms for +ordinary arguments: when the @var{message} is preceded by two colons, +the @t{words} special array and the @t{CURRENT} special parameter are +modified during the execution or evaluation of the @var{action} to refer +only to the words after the option. When preceded by three colons, they +are modified to refer only to the words covered by this description. + +@end table + +@end table + +@noindent +Any literal colon in an @var{optname}, @var{message}, or @var{action} +must be preceded by a backslash, `@t{\:}'. + +@noindent +Each of the forms above may be preceded by a list in parentheses +of option names and argument numbers. If the given option is on +the command line, the options and arguments indicated in parentheses +will not be offered. For example, +`@t{(-two -three 1)-one:}@var{...}' completes the option `@t{-one}'; if this +appears on the command line, the options @t{-two} and @t{-three} and the +first ordinary argument will not be completed after it. +`@t{(-foo):}@var{...}' specifies an ordinary argument completion; +@t{-foo} will not be completed if that argument is already present. + +@noindent +Other items may appear in the list of excluded options to indicate +various other items that should not be applied when the current +specification is matched: a single star (@t{*}) for the rest arguments +(i.e. a specification of the form `@t{*:}@var{...}'); a colon (@t{:}) +for all normal (non-option-) arguments; and a hyphen (@t{-}) for all +options. For example, if `@t{(*)}' appears before an option and the +option appears on the command line, the list of remaining arguments +(those shown in the above table beginning with `@t{*:}') will not be +completed. + +@noindent +To aid in reuse of specifications, it is possible to precede any of the +forms above with `@t{!}'; then the form will no longer be completed, +although if the option or argument appears on the command line they will +be skipped as normal. The main use for this is when the arguments are +given by an array, and @t{_arguments} is called repeatedly for more +specific contexts: on the first call `@t{_arguments $global_options}' is +used, and on subsequent calls `@t{_arguments !$^global_options}'. + +@noindent +@emph{@var{spec}s: actions} + +@noindent +In each of the forms above the @var{action} determines how +completions should be generated. Except for the `@t{->}@var{string}' +form below, the @var{action} will be executed by calling the +@t{_all_labels} function to process all tag labels. No special handling +of tags is needed unless a function call introduces a new one. + +@noindent +The functions called to execute @var{action}s will be called with the +elements of the array named by the `@t{-O} @var{name}' option as arguments. +This can be used, for example, to pass the same set of options for the +@t{compadd} builtin to all @var{action}s. + +@noindent +The forms for @var{action} are as follows. + +@noindent +@table @asis +@item @t{@ }(single unquoted space) +This is useful where an argument is required but it is not possible or +desirable to generate matches for it. The +@var{message} will be displayed but no completions listed. Note +that even in this case the colon at the end of the @var{message} is +needed; it may only be omitted when neither a @var{message} +nor an @var{action} is given. + +@item @t{(}@var{item1} @var{item2} @var{...}@t{)} +One of a list of possible matches, for example: + +@noindent +@example +@t{:foo:(foo bar baz}@t{)} +@end example + +@item @t{((@var{item1}\:@var{desc1} @var{...}))} +Similar to the above, but with descriptions for each possible match. +Note the backslash before the colon. For example, + +@noindent +@example +@t{:foo:((a\:bar b\:baz}@t{))} +@end example + +@noindent +The matches will be listed together with their descriptions if the +@t{description} style is set with the @t{values} tag in the context. + +@item @t{->}@var{string} +@vindex context, use of +@vindex line, use of +@vindex opt_args, use of +In this form, @t{_arguments} processes the arguments and options and then +returns control to the calling function with parameters set to indicate the +state of processing; the calling function then makes its own arrangements +for generating completions. For example, functions that implement a state +machine can use this type of action. + +@noindent +Where @t{_arguments} encounters @var{action} in the `@t{->}@var{string}' +format, it will strip all leading and trailing whitespace from @var{string} +and set the array @t{state} to the set of all @var{string}s for which an +action is to be performed. The elements of the array @t{state_descr} are +assigned the corresponding @var{message} field from each @var{optarg} +containing such an @var{action}. + +@noindent +By default and in common with all other well behaved completion +functions, _arguments returns status zero if it was able to add matches and +non-zero otherwise. However, if the @t{-R} option is given, +@t{_arguments} will instead return a status of 300 to indicate that +@t{$state} is to be handled. + +@noindent +In addition to @t{$state} and @t{$state_descr}, @t{_arguments} also +sets the global +parameters `@t{context}', `@t{line}' and `@t{opt_args}' as described +below, and does not reset any changes made to the special parameters +such as @t{PREFIX} and @t{words}. This gives the calling function the +choice of resetting these parameters or propagating changes in them. + +@noindent +A function calling @t{_arguments} with at least +one action containing a `@t{->}@var{string}' must therefore declare +appropriate local parameters: + +@noindent +@example +local context state state_descr line +typeset -A opt_args +@end example + +@noindent +to prevent @t{_arguments} from altering the global environment. + +@item @t{@{}@var{eval-string}@t{@}} +@vindex expl, use of +A string in braces is evaluated as shell code to generate matches. If the +@var{eval-string} itself does not begin with an opening parenthesis or +brace it is split into separate words before execution. + +@item @t{= }@var{action} +If the @var{action} starts with `@t{= }' (an equals sign followed by a +space), @t{_arguments} will insert the contents of the @var{argument} +field of the current context as the new first element in the @t{words} +special array and increment the value of the @t{CURRENT} special +parameter. This has the effect of inserting a dummy word onto the +completion command line while not changing the point at which completion is +taking place. + +@noindent +This is most useful with one of the specifiers that restrict the words on +the command line on which the @var{action} is to operate (the two- and +three-colon forms above). One particular use is when an @var{action} itself +causes @t{_arguments} on a restricted range; it is necessary to use this +trick to insert an appropriate command name into the range for the second +call to @t{_arguments} to be able to parse the line. + +@item @var{@t{@ }word...} +@itemx @var{word...} +This covers all forms other than those above. If the @var{action} +starts with a space, the remaining list of words will be invoked unchanged. + +@noindent +Otherwise it will be invoked with some extra strings placed after the +first word; these are to be passed down as options to the @t{compadd} +builtin. They ensure that the state specified by @t{_arguments}, in +particular the descriptions of options and arguments, is correctly passed +to the completion command. These additional arguments +are taken from the array parameter `@t{expl}'; this will be set up +before executing the @var{action} and hence may be referred to inside it, +typically in an expansion of the form `@t{$expl[@@]}' which preserves empty +elements of the array. + +@end table + +@noindent +During the performance of the action the array `@t{line}' will be set to +the normal arguments from the command line, i.e. the words from the +command line after the command name excluding all options and their +arguments. Options are stored in the associative array +`@t{opt_args}' with option names as keys and their arguments as +the values. For options that have more than one argument these are +given as one string, separated by colons. All colons and backslashes +in the original arguments are preceded with backslashes. + +@noindent +The parameter `@t{context}' is set when returning to the calling function +to perform an action of the form `@t{->}@var{string}'. It is set to an +array of elements corresponding to the elements of @t{$state}. Each +element is a suitable name for the argument field of the context: either a +string of the form `@t{option}@var{-opt}@t{-}@var{n}' for the @var{n}'th +argument of the option @var{-opt}, or a string of the form +`@t{argument-}@var{n}' for the @var{n}'th argument. For `rest' arguments, +that is those in the list at the end not handled by position, @var{n} is the +string `@t{rest}'. For example, when completing the argument of the @t{-o} +option, the name is `@t{option-o-1}', while for the second normal +(non-option-) argument it is `@t{argument-2}'. + +@noindent +Furthermore, during the evaluation of the @var{action} the context name in +the @t{curcontext} parameter is altered to append the same string that is +stored in the @t{context} parameter. + +@noindent +The option @t{-C} tells @t{_arguments} to modify the @t{curcontext} +parameter for an action of the form `@t{->}@var{state}'. This is the +standard parameter used to keep track of the current context. Here it +(and not the @t{context} array) should be made local to the calling +function to avoid passing back the modified value and should be +initialised to the current value at the start of the function: + +@noindent +@example +local curcontext="$curcontext" +@end example + +@noindent +This is useful where it is not possible for multiple states to be valid +together. + +@noindent +@emph{Grouping Options} + +@noindent +Options can be grouped to simplify exclusion lists. A group is +introduced with `@t{+}' followed by a name for the group in the +subsequent word. Whole groups can then be referenced in an exclusion +list or a group name can be used to disambiguate between two forms of +the same option. For example: + +@noindent +@example +_arguments \ + '(group2--x)-a' \ + + group1 \ + -m \ + '(group2)-n' \ + + group2 \ + -x -y +@end example + +@noindent +If the name of a group is specified in the form +`@t{(}@var{name}@t{)}' then only one value from that group +will ever be completed; more formally, all specifications are mutually +exclusive to all other specifications in that group. This is useful for +defining options that are aliases for each other. For example: + +@noindent +@example +_arguments \ + -a -b \ + + '(operation)' \ + @{-c,--compress@}'[compress]' \ + @{-d,--decompress@}'[decompress]' \ + @{-l,--list@}'[list]' +@end example + +@noindent +If an option in a group appears on the command line, it is stored in the +associative array `@t{opt_args}' with '@var{group}@t{-}@var{option}' +as a key. In the example above, a key `@t{operation--c}' is used if the option +`@t{-c}' is present on the command line. + +@noindent +@emph{Specifying Multiple Sets of Arguments} + +@noindent +It is possible to specify multiple sets of options and arguments with +the sets separated by single hyphens. This differs from groups in that +sets are considered to be mutually exclusive of each other. + +@noindent +Specifications before the first set and from any group are common to +all sets. For example: + +@noindent +@example +_arguments \ + -a \ + - set1 \ + -c \ + - set2 \ + -d \ + ':arg:(x2 y2)' +@end example + +@noindent +This defines two sets. When the command line contains the option +`@t{-c}', the `@t{-d}' option and the argument will not be considered +possible completions. When it contains `@t{-d}' or an argument, the +option `@t{-c}' will not be considered. However, after `@t{-a}' +both sets will still be considered valid. + +@noindent +As for groups, the name of a set may appear in exclusion lists, either +alone or preceding a normal option or argument specification. + +@noindent +The completion code has to parse the command line separately for each +set. This can be slow so sets should only be used when necessary. +A useful alternative is often an option specification with rest-arguments +(as in `@t{-foo:*:...}'); here the option @t{-foo} swallows up all +remaining arguments as described by the @var{optarg} definitions. + +@noindent +@emph{Deriving @var{spec} forms from the help output} + +@noindent +The option `@t{-}@t{-}' allows @t{_arguments} to work out the names of long +options that support the `@t{-}@t{-help}' option which is standard in many +GNU commands. The command word is called with the argument +`@t{-}@t{-help}' and the output examined for option names. Clearly, it can +be dangerous to pass this to commands which may not support this option as +the behaviour of the command is unspecified. + +@noindent +In addition to options, `@t{_arguments -}@t{-}' will try to deduce the +types of arguments available for options when the form +`@t{-}@t{-}@var{opt}@t{=}@var{val}' is valid. It is also possible to provide +hints by examining the help text of the command and adding @var{helpspec} of +the form `@var{pattern}@t{:}@var{message}@t{:}@var{action}'; note that other +@t{_arguments} @var{spec} forms are not used. The @var{pattern} is matched +against the help text for an option, and if it matches the @var{message} and +@var{action} are used as for other argument specifiers. The special case +of `@t{*:}' means both @var{message} and @var{action} are empty, which has +the effect of causing options having no description in the help output to +be ordered in listings ahead of options that have a description. + +@noindent +For example: + +@noindent +@example +_arguments -- '*\*:toggle:(yes no)' \ + '*=FILE*:file:_files' \ + '*=DIR*:directory:_files -/' \ + '*=PATH*:directory:_files -/' +@end example + +@noindent +Here, `@t{yes}' and `@t{no}' will be completed as the argument of +options whose description ends in a star; file names will be completed for +options that contain the substring `@t{=FILE}' in the description; and +directories will be completed for options whose description contains +`@t{=DIR}' or `@t{=PATH}'. The last three are in fact the default and so +need not be given explicitly, although it is possible to override the use +of these patterns. A typical help text which uses this feature is: + +@noindent +@example + -C, --directory=DIR change to directory DIR +@end example + +@noindent +so that the above specifications will cause directories to be completed +after `@t{-}@t{-directory}', though not after `@t{-C}'. + +@noindent +Note also that @t{_arguments} tries to find out automatically if the +argument for an option is optional. This can be specified explicitly by +doubling the colon before the @var{message}. + +@noindent +If the @var{pattern} ends in `@t{(-)}', this will be removed from the +pattern and the @var{action} will be used only directly after the +`@t{=}', not in the next word. This is the behaviour of a normal +specification defined with the form `@t{=-}'. + +@noindent +By default, the command (with the option `@t{--help}') is run after +resetting all the locale categories (except for @t{LC_CTYPE}) to `@t{C}'. +If the localized help output is known to work, the option `@t{-l}' can +be specified after the `@t{_arguments -}@t{-}' so that the command is +run in the current locale. + +@noindent +The `@t{_arguments -}@t{-}' can be followed by the option `@t{-i} +@var{patterns}' to give patterns for options which are not to be +completed. The patterns can be given as the name of an array parameter +or as a literal list in parentheses. For example, + +@noindent +@example +_arguments -- -i \ + "(--(en|dis)able-FEATURE*)" +@end example + +@noindent +will cause completion to ignore the options +`@t{-}@t{-enable-FEATURE}' and `@t{-}@t{-disable-FEATURE}' (this example is +useful with GNU @t{configure}). + +@noindent +The `@t{_arguments -}@t{-}' form can also be followed by the option `@t{-s} +@var{pair}' to describe option aliases. The @var{pair} consists of a list +of alternating patterns and corresponding replacements, enclosed in parens +and quoted so that it forms a single argument word in the @t{_arguments} +call. + +@noindent +For example, some @t{configure}-script help output describes options only +as `@t{-}@t{-enable-foo}', but the script also accepts the negated form +`@t{-}@t{-disable-foo}'. To allow completion of the second form: + +@noindent +@example +_arguments -- -s "((#s)--enable- --disable-)" +@end example + +@noindent +@emph{Miscellaneous notes} + +@noindent +Finally, note that @t{_arguments} generally expects to be the primary +function handling any completion for which it is used. It may have side +effects which change the treatment of any matches added by other functions +called after it. To combine @t{_arguments} with other functions, those +functions should be called either before @t{_arguments}, as an @var{action} +within a @var{spec}, or in handlers for `@t{->}@var{state}' actions. + +@noindent +Here is a more general example of the use of @t{_arguments}: + +@noindent +@example +_arguments '-l+:left border:' \ + '-format:paper size:(letter A4)' \ + '*-copy:output file:_files::resolution:(300 600)' \ + ':postscript file:_files -g \*.\(ps\|eps\)' \ + '*:page number:' +@end example + +@noindent +This describes three options: `@t{-l}', `@t{-format}', and +`@t{-copy}'. The first takes one argument described as `@var{left +border}' for which no completion will be offered because of the empty +action. Its argument may come directly after the `@t{-l}' or it may be +given as the next word on the line. + +@noindent +The `@t{-format}' option takes one +argument in the next word, described as `@var{paper size}' for which +only the strings `@t{letter}' and `@t{A4}' will be completed. + +@noindent +The `@t{-copy}' option may appear more than once on the command line and +takes two arguments. The first is mandatory and will be completed as a +filename. The second is optional (because of the second colon before +the description `@var{resolution}') and will be completed from the strings +`@t{300}' and `@t{600}'. + +@noindent +The last two descriptions say what should be completed as +arguments. The first describes the first argument as a +`@var{postscript file}' and makes files ending in `@t{ps}' or `@t{eps}' +be completed. The last description gives all other arguments the +description `@var{page numbers}' but does not offer completions. + +@findex _cache_invalid +@item @t{_cache_invalid} @var{cache_identifier} +This function returns status zero if the completions cache corresponding to +the given cache identifier needs rebuilding. It determines this by +looking up the @t{cache-policy} style for the current context. +This should provide a function name which is run with the full path to the +relevant cache file as the only argument. + +@noindent +Example: + +@noindent +@example +_example_caching_policy () @{ + # rebuild if cache is more than a week old + local -a oldp + oldp=( "$1"(Nm+7) ) + (( $#oldp )) +@} +@end example + +@findex _call_function +@item @t{_call_function} @var{return} @var{name} [ @var{arg} ... ] +If a function @var{name} exists, it is called with the arguments +@var{arg}s. The @var{return} argument gives the name of a parameter in which +the return status from the function @var{name} should be stored; if @var{return} +is empty or a single hyphen it is ignored. + +@noindent +The return status of @t{_call_function} itself is zero if the function +@var{name} exists and was called and non-zero otherwise. + +@findex _call_program +@item @t{_call_program} [ @t{-l} ] [ @t{-p} ] @var{tag} @var{string} ... +This function provides a mechanism for the user to override the use of an +external command. It looks up the @t{command} style with the supplied +@var{tag}. If the style is set, its value is used as the command to +execute. The @var{string}s from the call to @t{_call_program}, or from the +style if set, are concatenated with spaces between them and the resulting +string is evaluated. The return status is the return status of the command +called. + +@noindent +By default, the command is run in an environment where all the locale +categories (except for @t{LC_CTYPE}) are reset to `@t{C}' by calling the +utility function @t{_comp_locale} (see below). If the option `@t{-l}' is +given, the command is run with the current locale. + +@noindent +If the option `@t{-p}' is supplied it indicates that the command +output is influenced by the permissions it is run with. If the +@t{gain-privileges} style is set to true, @t{_call_program} will make +use of commands such as @t{sudo}, if present on the command-line, to +match the permissions to whatever the final command is likely to run +under. When looking up the @t{gain-privileges} and @t{command} styles, +the command component of the zstyle context will end with a slash +(`@t{/}') followed by the command that would be used to gain privileges. + +@findex _combination +@item @t{_combination} [ @t{-s} @var{pattern} ] @var{tag} @var{style} @var{spec} ... @var{field} @var{opts} ... +This function is used to complete combinations of values, for example +pairs of hostnames and usernames. The @var{style} argument gives the style +which defines the pairs; it is looked up in a context with the @var{tag} +specified. + +@noindent +The style name consists of field names separated by hyphens, for example +`@t{users-hosts-ports}'. For each field for a value is already known, a +@var{spec} of the form `@var{field}@t{=}@var{pattern}' is given. For example, +if the command line so far specifies a user `@t{pws}', the argument +`@t{users=pws}' should appear. + +@noindent +The next argument with no equals sign is taken as the name of the field +for which completions should be generated (presumably not one of the +@var{field}s for which the value is known). + +@noindent +The matches generated will be taken from the value of the style. These +should contain the possible values for the combinations in the appropriate +order (users, hosts, ports in the example above). +The values for the different fields are separated by colons. This +can be altered with the option @t{-s} to @t{_combination} which specifies a +pattern. Typically this is a character class, as for example +`@t{-s "[:@@]"}' in the case of the @t{users-hosts} style. Each +`@var{field}@t{=}@var{pattern}' specification restricts the +completions which apply to elements of the style with appropriately +matching fields. + +@noindent +If no style with the given name is defined for the given tag, +or if none of the strings in style's value match, but a +function name of the required field preceded by an +underscore is defined, that function will be called to generate the +matches. For example, if there is no `@t{users-hosts-ports}' or no +matching hostname when a host is required, the function `@t{_hosts}' will +automatically be called. + +@noindent +If the same name is used for more than one field, in both the +`@var{field}@t{=}@var{pattern}' and the argument that gives the name of the +field to be completed, the number of the field (starting with one) may +be given after the fieldname, separated from it by a colon. + +@noindent +All arguments after the required field name are passed to +@t{compadd} when generating matches from the style value, or to +the functions for the fields if they are called. + +@findex _command_names +@item @t{_command_names} [ @t{-e} | @t{-} ] +This function completes words that are valid at command position: names of +aliases, builtins, hashed commands, functions, and so on. With the @t{-e} +flag, only hashed commands are completed. The @t{-} flag is ignored. + +@findex _comp_locale +@item @t{_comp_locale} +This function resets all the locale categories other than @t{LC_CTYPE} to +`@t{C}' so that the output from external commands can be easily analyzed by +the completion system. @t{LC_CTYPE} retains the current value (taking +@t{LC_ALL} and @t{LANG} into account), ensuring that non-ASCII characters +in file names are still handled properly. + +@noindent +This function should normally be run only in a subshell, because the new +locale is exported to the environment. Typical usage would be +`@t{$(_comp_locale; }@var{command} ...@t{)}'. + +@findex _completers +@item @t{_completers} [ @t{-p} ] +This function completes names of completers. + +@noindent +@table @asis +@item @t{-p} +Include the leading underscore (`@t{_}') in the matches. + +@end table + +@findex _describe + +@item @t{_describe }[@t{-12JVx}] [ @t{-oO} | @t{-t} @var{tag} ] @var{descr} @var{name1} [ @var{name2} ] [ @var{opt} ... ] +@itemx @t{@ @ @ @ @ @ @ @ @ @ }[ @t{-}@t{-} @var{name1} [ @var{name2} ] [ @var{opt} ... ] ... ] +This function associates completions with descriptions. +Multiple groups separated by @t{-}@t{-} can be supplied, potentially with +different completion options @var{opt}s. + +@noindent +The @var{descr} is taken as a string to display above the matches if the +@t{format} style for the @t{descriptions} tag is set. This is followed by +one or two names of arrays followed by options to pass to @t{compadd}. The +array @var{name1} contains the possible completions with their descriptions in +the form `@var{completion}@t{:}@var{description}'. Any literal colons in +@var{completion} must be quoted with a backslash. If a @var{name2} is +given, it should have the same number of elements as @var{name1}; in this +case the corresponding elements are added as possible completions instead +of the @var{completion} strings from @var{name1}. The completion list +will retain the descriptions from @var{name1}. Finally, a set of +completion options can appear. + +@noindent +If the option `@t{-o}' appears before the first argument, the matches added +will be treated as names of command options (N.B. not shell options), +typically following a `@t{-}', `@t{-}@t{-}' or `@t{+}' on the command +line. In this case @t{_describe} uses the @t{prefix-hidden}, +@t{prefix-needed} and @t{verbose} styles to find out if the strings should +be added as completions and if the descriptions should be shown. Without +the `@t{-o}' option, only the @t{verbose} style is used to decide how +descriptions are shown. If `@t{-O}' is used instead of `@t{-o}', command +options are completed as above but @t{_describe} will not handle the +@t{prefix-needed} style. + +@noindent +With the @t{-t} option a @var{tag} can be specified. The default is +`@t{values}' or, if the @t{-o} option is given, `@t{options}'. + +@noindent +The options @t{-1}, @t{-2}, @t{-J}, @t{-V}, @t{-x} are passed to +@t{_next_label}. + +@noindent +If selected by the @t{list-grouped} style, strings with the same +description will appear together in the list. + +@noindent +@t{_describe} uses the @t{_all_labels} function to generate the matches, so +it does not need to appear inside a loop over tag labels. + +@findex _description +@item @t{_description} [ @t{-x} ] [ @t{-12VJ} ] @var{tag} @var{name} @var{descr} [ @var{spec} ... ] +This function is not to be confused with the previous one; it is used as +a helper function for creating options to @t{compadd}. It is buried +inside many of the higher level completion functions and so often does +not need to be called directly. + +@noindent +The styles listed below are tested in the current context using the +given @var{tag}. The resulting options for @t{compadd} are put into the +array named @var{name} (this is traditionally `@t{expl}', but this +convention is not enforced). The description for the corresponding set +of matches is passed to the function in @var{descr}. + +@noindent +The styles tested are: @t{format}, @t{hidden}, @t{matcher}, +@t{ignore-line}, @t{ignored-patterns}, @t{group-name} and @t{sort}. +The @t{format} style is first tested for the given @var{tag} and then for +the @t{descriptions} tag if no value was found, while the remainder are +only tested for the tag given as the first argument. The function also +calls @t{_setup} which tests some more styles. + +@noindent +The string returned by the @t{format} style (if any) will be modified so +that the sequence `@t{%d}' is replaced by the @var{descr} given as the third +argument without any leading or trailing white space. If, after +removing the white space, the @var{descr} is the empty string, the format +style will not be used and the options put into the @var{name} array will +not contain an explanation string to be displayed above the matches. + +@noindent +If @t{_description} is called with more than three arguments, +the additional @var{spec}s should be of the form `@var{char}@t{:}@var{str}'. +These supply escape sequence replacements for the @t{format} style: +every appearance of `@t{%}@var{char}' will be +replaced by @var{string}. + +@noindent +If the @t{-x} option is given, the description will be passed to +@t{compadd} using the @t{-x} option instead of the default @t{-X}. This +means that the description will be displayed even if there are no +corresponding matches. + +@noindent +The options placed in the array @var{name} take account of the +@t{group-name} style, so matches are placed in a separate group where +necessary. The group normally has its elements sorted (by passing the +option @t{-J} to @t{compadd}), but if an option starting with `@t{-V}', +`@t{-J}', `@t{-1}', or `@t{-2}' is passed to @t{_description}, that +option will be included in the array. Hence it is possible for the +completion group to be unsorted by giving the option `@t{-V}', +`@t{-1V}', or `@t{-2V}'. + +@noindent +In most cases, the function will be used like this: + +@noindent +@example +local expl +_description files expl file +compadd "$expl[@@]" - "$files[@@]" +@end example + +@noindent +Note the use of the parameter @t{expl}, the hyphen, and the list of +matches. Almost all calls to @t{compadd} within the completion system use +a similar format; this ensures that user-specified styles are correctly +passed down to the builtins which implement the internals of completion. + +@findex _dir_list +@item @t{_dir_list} [ @t{-s} @var{sep} ] [ @t{-S} ] +Complete a list of directory names separated by colons +(the same format as @t{$PATH}). + +@noindent +@table @asis +@item @t{-s} @var{sep} +Use @var{sep} as separator between items. +@var{sep} defaults to a colon (`@t{:}'). + +@item @t{-S} +Add @var{sep} instead of slash (`@t{/}') as an autoremoveable suffix. + +@end table + +@findex _dispatch +@item @t{_dispatch} @var{context string} ... +This sets the current context to @var{context} and looks for completion +functions to handle this context by hunting through the list of command +names or special contexts (as described above for @t{compdef}) +given as @var{string}s. The first completion function to be defined +for one of the contexts in the list is used to generate matches. +Typically, the last @var{string} is @t{-default-} to cause the function +for default completion to be used as a fallback. + +@noindent +The function sets the parameter +@t{$service} to the @var{string} being tried, and sets +the @var{context/command} field (the fourth) of the @t{$curcontext} +parameter to the @var{context} given as the first argument. + +@findex _email_addresses +@item @t{_email_addresses} [ @t{-c} ] [ @t{-n} @var{plugin} ] +Complete email addresses. Addresses are provided by plugins. + +@noindent +@table @asis +@item @t{-c} +Complete bare @t{localhost@@domain.tld} addresses, without a name part or +a comment. +Without this option, RFC822 `@var{Firstname Lastname} @t{<}@var{address}@t{>}' +strings are completed. + +@item @t{-n} @var{plugin} +Complete aliases from @var{plugin}. + +@end table + +@noindent +The following plugins are available by default: +@t{_email-ldap} (see the @t{filter} style), +@t{_email-local} (completes @var{user}@t{@@}@var{hostname} Unix addresses), +@t{_email-mail} (completes aliases from @t{~/.mailrc}), +@t{_email-mush}, +@t{_email-mutt}, +and +@t{_email-pine}. + +@noindent +Addresses from the @t{_email-}@var{foo} plugin are added under the +tag `@t{email-}@var{foo}'. + +@noindent +@emph{Writing plugins} + +@noindent +Plugins are written as separate functions with names starting with `@t{_email-}'. +They are invoked with the @t{-c} option and @t{compadd} options. +They should either do their own completion or +set the @t{$reply} array to a list of `@var{alias}@t{:}@var{address}' elements and return @t{300}. +New plugins will be picked up and run automatically. + +@findex _files +@item @t{_files} +The function @t{_files} is a wrapper around @t{_path_files}. It supports +all of the same functionality, with some enhancements --- notably, it +respects the @t{list-dirs-first} style, and it allows users to override +the behaviour of the @t{-g} and @t{-/} options with the @t{file-patterns} +style. @t{_files} should therefore be preferred over @t{_path_files} in +most cases. + +@noindent +This function accepts the full set of options allowed by +@t{_path_files}, described below. + +@findex _gnu_generic +@item @t{_gnu_generic} +This function is a simple wrapper around the @t{_arguments} function +described above. It can be used to determine automatically the long +options understood by commands that produce a list when passed the +option `@t{-}@t{-help}'. It is intended to be used as a top-level +completion function in its own right. For example, to enable option +completion for the commands @t{foo} and @t{bar}, use + +@noindent +@example +compdef _gnu_generic foo bar +@end example + +@noindent +after the call to @t{compinit}. + +@noindent +The completion system as supplied is conservative in its use of this +function, since it is important to be sure the command understands the +option `@t{-}@t{-help}'. + +@findex _guard +@item @t{_guard} [ @var{options} ] @var{pattern descr} +This function displays @var{descr} if @var{pattern} matches the string to +be completed. It is intended to be used in the @var{action} for the +specifications passed to @t{_arguments} and similar functions. + +@noindent +The return status is zero if the message was displayed and the word to +complete is not empty, and non-zero otherwise. + +@noindent +The @var{pattern} may be preceded by any of the options understood by +@t{compadd} that are passed down from @t{_description}, namely @t{-M}, +@t{-J}, @t{-V}, @t{-1}, @t{-2}, @t{-n}, @t{-F} and @t{-X}. All of these +options will be ignored. This fits in conveniently with the +argument-passing conventions of actions for @t{_arguments}. + +@noindent +As an example, consider a command taking the options @t{-n} and +@t{-none}, where @t{-n} must be followed by a numeric value in the +same word. By using: + +@noindent +@example +_arguments '-n-: :_guard "[0-9]#" "numeric value"' '-none' +@end example + +@noindent +@t{_arguments} can be made to both display the message `@t{numeric +value}' and complete options after `@t{-n<TAB>}'. If the `@t{-n}' is +already followed by one or more digits (the pattern passed to +@t{_guard}) only the message will be displayed; if the `@t{-n}' is +followed by another character, only options are completed. + +@findex _message +@item @t{_message} [ @t{-r12} ] [ @t{-VJ} @var{group} ] @var{descr} +@itemx @t{_message -e} [ @var{tag} ] @var{descr} +The @var{descr} is used in the same way as the third +argument to the @t{_description} function, except that the resulting +string will always be shown whether or not matches were +generated. This is useful for displaying a help message in places where +no completions can be generated. + +@noindent +The @t{format} style is examined with the @t{messages} tag to find a +message; the usual tag, @t{descriptions}, is used only if the style is +not set with the former. + +@noindent +If the @t{-r} option is given, no style is used; the @var{descr} is +taken literally as the string to display. This is most useful +when the @var{descr} comes from a pre-processed argument list +which already contains an expanded description. Note that this +option does not disable the `@t{%}'-sequence parsing done by +@t{compadd}. + +@noindent +The @t{-12VJ} options and the @var{group} are passed to @t{compadd} and +hence determine the group the message string is added to. + +@noindent +The second @t{-e} form gives a description for completions with the tag +@var{tag} to be shown even if there are no matches for that tag. This form +is called by @t{_arguments} in the event that there is no action for an +option specification. The tag can be omitted and if so the tag is taken +from the parameter @t{$curtag}; this is maintained by the completion +system and so is usually correct. Note that if there are no matches at +the time this function is called, @t{compstate[insert]} is cleared, so +additional matches generated later are not inserted on the command line. + +@findex _multi_parts +@item @t{_multi_parts} [ @t{-i} ] @var{sep} @var{array} +The argument @var{sep} is a separator character. +The @var{array} may be either the +name of an array parameter or a literal array in the form +`@t{(foo bar}@t{)}', a parenthesised list of words separated +by whitespace. The possible completions are the +strings from the array. However, each chunk delimited by @var{sep} will be +completed separately. For example, the @t{_tar} function uses +`@t{_multi_parts} @t{/} @var{patharray}' to complete partial file paths +from the given array of complete file paths. + +@noindent +The @t{-i} option causes @t{_multi_parts} to insert a unique match even +if that requires multiple separators to be inserted. This is not usually +the expected behaviour with filenames, but certain other types of +completion, for example those with a fixed set of possibilities, may be +more suited to this form. + +@noindent +Like other utility functions, this function accepts the `@t{-V}', +`@t{-J}', `@t{-1}', `@t{-2}', `@t{-n}', `@t{-f}', `@t{-X}', `@t{-M}', +`@t{-P}', `@t{-S}', `@t{-r}', `@t{-R}', and `@t{-q}' options and passes +them to the @t{compadd} builtin. + +@findex _next_label +@item @t{_next_label} [ @t{-x} ] [ @t{-12VJ} ] @var{tag} @var{name} @var{descr} [ @var{option} ... ] +This function is used to implement the loop over different tag +labels for a particular tag as described above for the @t{tag-order} +style. On each call it checks to see if there are any more tag labels; if +there is it returns status zero, otherwise non-zero. +As this function requires a current tag to be set, it must always follow +a call to @t{_tags} or @t{_requested}. + +@noindent +The @t{-x12VJ} options and the first three arguments are passed to the +@t{_description} function. Where appropriate the @var{tag} will be +replaced by a tag label in this call. Any description given in +the @t{tag-order} style is preferred to the @var{descr} passed to +@t{_next_label}. + +@noindent +The @var{option}s given after the @var{descr} +are set in the parameter given by @var{name}, and hence are to be passed +to @t{compadd} or whatever function is called to add the matches. + +@noindent +Here is a typical use of this function for the tag @t{foo}. The call to +@t{_requested} determines if tag @t{foo} is required at all; the loop +over @t{_next_label} handles any labels defined for the tag in the +@t{tag-order} style. + +@noindent +@example +local expl ret=1 +... +if _requested foo; then + ... + while _next_label foo expl '...'; do + compadd "$expl[@@]" ... && ret=0 + done + ... +fi +return ret +@end example + +@findex _normal +@item @t{_normal} [ @t{-P} | @t{-p} @var{precommand} ] +This is the standard function called to handle completion outside +any special @t{-}@var{context}@t{-}. It is called both to complete the command +word and also the arguments for a command. In the second case, +@t{_normal} looks for a special completion for that command, and if +there is none it uses the completion for the @t{-default-} context. + +@noindent +A second use is to reexamine the command line specified by the @t{$words} +array and the @t{$CURRENT} parameter after those have been modified. +For example, the function @t{_precommand}, which +completes after precommand specifiers such as @t{nohup}, removes the +first word from the @t{words} array, decrements the @t{CURRENT} parameter, +then calls `@t{_normal -p $service}'. The effect is that +`@t{nohup} @var{cmd ...}' is treated in the same way as `@var{cmd ...}'. + +@noindent +@table @asis +@item @t{-P} +Reset the list of precommands. This option should be used if completing +a command line which allows internal commands (e.g. builtins and +functions) regardless of prior precommands (e.g. `@t{zsh -c}'). + +@item @t{-p} @var{precommand} +Append @var{precommand} to the list of precommands. This option should be +used in nearly all cases in which @t{-P} is not applicable. + +@end table + +@noindent +If the command name matches one of the patterns given by one of the +options @t{-p} or @t{-P} to @t{compdef}, the corresponding completion +function is called and then the parameter @t{_compskip} is +checked. If it is set completion is terminated at that point even if +no matches have been found. This is the same effect as in the +@t{-first-} context. + +@findex _options +@item @t{_options} +This can be used to complete the names of shell options. It provides a +matcher specification that ignores a leading `@t{no}', ignores +underscores and allows upper-case letters to +match their lower-case counterparts (for example, `@t{glob}', +`@t{noglob}', `@t{NO_GLOB}' are all completed). Any arguments +are propagated to the @t{compadd} builtin. + +@findex _options_set +@findex _options_unset +@item @t{_options_set} and @t{_options_unset} +These functions complete only set or unset options, with the same +matching specification used in the @t{_options} function. + +@noindent +Note that you need to uncomment a few lines in the @t{_main_complete} +function for these functions to work properly. The lines in question +are used to store the option settings in effect before the completion +widget locally sets the options it needs. Hence these functions are not +generally used by the completion system. + +@findex _parameters +@item @t{_parameters} +This is used to complete the names of shell parameters. + +@noindent +The option `@t{-g} @var{pattern}' limits the completion to parameters +whose type matches the @var{pattern}. The type of a parameter is that +shown by `@t{print $@{(t)}@var{param}@t{@}}', hence judicious use of +`@t{*}' in @var{pattern} is probably necessary. + +@noindent +All other arguments are passed to the @t{compadd} builtin. + +@findex _path_files +@item @t{_path_files} +This function is used throughout the completion system +to complete filenames. It allows completion of partial paths. For +example, the string `@t{/u/i/s/sig}' may be completed to +`@t{/usr/include/sys/signal.h}'. + +@noindent +The options accepted by both @t{_path_files} and @t{_files} are: + +@noindent +@table @asis +@item @t{-f} +Complete all filenames. This is the default. + +@item @t{-/} +Specifies that only directories should be completed. + +@item @t{-g} @var{pattern} +Specifies that only files matching the @var{pattern} should be completed. + +@item @t{-W} @var{paths} +Specifies path prefixes that are to be prepended to the string from the +command line to generate the filenames but that should not be inserted +as completions nor shown in completion listings. Here, @var{paths} may be +the name of an array parameter, a literal list of paths enclosed in +parentheses or an absolute pathname. + +@item @t{-F} @var{ignored-files} +This behaves as for the corresponding option to the @t{compadd} builtin. +It gives direct control over which +filenames should be ignored. If the option is not present, the +@t{ignored-patterns} style is used. + +@end table + +@noindent +Both @t{_path_files} and @t{_files} also accept the following options +which are passed to @t{compadd}: `@t{-J}', `@t{-V}', +`@t{-1}', `@t{-2}', `@t{-n}', `@t{-X}', `@t{-M}', `@t{-P}', `@t{-S}', +`@t{-q}', `@t{-r}', and `@t{-R}'. + +@noindent +Finally, the @t{_path_files} function uses the styles @t{expand}, +@t{ambiguous}, @t{special-dirs}, @t{list-suffixes} and @t{file-sort} +described above. + +@findex _pick_variant + +@item @t{_pick_variant }[ @t{-b} @var{builtin-label} ] [ @t{-c} @var{command} ] [ @t{-r} @var{name} ] +@itemx @t{@ @ @ @ @ @ @ @ @ @ @ @ @ @ }@var{label}@t{=}@var{pattern} ... @var{label} [ @var{arg} ... ] +This function is used to resolve situations where a single command name +requires more than one type of handling, either because it +has more than one variant or because there is a name clash between two +different commands. + +@noindent +The command to run is taken from the first element of the array +@t{words} unless this is overridden by the option @t{-c}. This command +is run and its output is compared with a series of patterns. Arguments +to be passed to the command can be specified at the end after all the +other arguments. The patterns to try in order are given by the arguments +@var{label}@t{=}@var{pattern}; if the output of `@var{command} @var{arg} +...' contains @var{pattern}, then @var{label} is selected as the label +for the command variant. If none of the patterns match, the final +command label is selected and status 1 is returned. + +@noindent +If the `@t{-b} @var{builtin-label}' is given, the command is tested to +see if it is provided as a shell builtin, possibly autoloaded; if so, +the label @var{builtin-label} is selected as the label for the variant. + +@noindent +If the `@t{-r} @var{name}' is given, the @var{label} picked is stored in +the parameter named @var{name}. + +@noindent +The results are also cached in the @t{_cmd_variant} associative array +indexed by the name of the command run. + +@findex _regex_arguments +@item @t{_regex_arguments} @var{name} @var{spec} ... +This function generates a completion function @var{name} which matches +the specifications @var{spec}s, a set of regular expressions as +described below. After running @t{_regex_arguments}, the function +@var{name} should be called as a normal completion function. +The pattern to be matched is given by the contents of +the @t{words} array up to the current cursor position joined together +with null characters; no quotation is applied. + +@noindent +The arguments are grouped as sets of alternatives separated by `@t{|}', +which are tried one after the other until one matches. Each alternative +consists of a one or more specifications which are tried left to right, +with each pattern matched being stripped in turn from the command line +being tested, until all of the group succeeds or until one fails; in the +latter case, the next alternative is tried. This structure can be +repeated to arbitrary depth by using parentheses; matching proceeds from +inside to outside. + +@noindent +A special procedure is applied if no test succeeds but the remaining +command line string contains no null character (implying the remaining +word is the one for which completions are to be generated). The +completion target is restricted to the remaining word and any +@var{action}s for the corresponding patterns are executed. In this case, +nothing is stripped from the command line string. The order of +evaluation of the @var{action}s can be determined by the @t{tag-order} +style; the various formats supported by @t{_alternative} can be used +in @var{action}. The @var{descr} is used for setting up the array +parameter @t{expl}. + +@noindent +Specification arguments take one of following forms, in which +metacharacters such as `@t{(}', `@t{)}', `@t{#}' and `@t{|}' +should be quoted. + +@noindent +@table @asis +@item @t{/}@var{pattern}@t{/} [@t{%}@var{lookahead}@t{%}] [@t{-}@var{guard}] [@t{:}@var{tag}@t{:}@var{descr}@t{:}@var{action}] +This is a single primitive component. +The function tests whether the combined pattern +`@t{(#b)((#B)}@var{pattern}@t{)}@var{lookahead}@t{*}' matches +the command line string. If so, `@var{guard}' is evaluated and +its return status is examined to determine if the test has succeeded. +The @var{pattern} string `@t{[]}' is guaranteed never to match. +The @var{lookahead} is not stripped from the command line before the next +pattern is examined. + +@noindent +The argument starting with @t{:} is used in the same manner as an argument to +@t{_alternative}. + +@noindent +A component is used as follows: @var{pattern} is tested to +see if the component already exists on the command line. If +it does, any following specifications are examined to find something to +complete. If a component is reached but no such pattern exists yet on the +command line, the string containing the @var{action} is used to generate +matches to insert at that point. + +@item @t{/}@var{pattern}@t{/+} [@t{%}@var{lookahead}@t{%}] [@t{-}@var{guard}] [@t{:}@var{tag}@t{:}@var{descr}@t{:}@var{action}] +This is similar to `@t{/}@var{pattern}@t{/} ...' but the left part of the +command line string (i.e. the part already matched by previous patterns) +is also considered part of the completion target. + +@item @t{/}@var{pattern}@t{/-} [@t{%}@var{lookahead}@t{%}] [@t{-}@var{guard}] [@t{:}@var{tag}@t{:}@var{descr}@t{:}@var{action}] +This is similar to `@t{/}@var{pattern}@t{/} ...' but the @var{action}s of the +current and previously matched patterns are ignored even if the +following `@var{pattern}' matches the empty string. + +@item @t{(} @var{spec} @t{)} +Parentheses may be used to groups @var{spec}s; note each parenthesis +is a single argument to @t{_regex_arguments}. + +@item @var{spec} @t{#} +This allows any number of repetitions of @var{spec}. + +@item @var{spec} @var{spec} +The two @var{spec}s are to be matched one after the other as described +above. + +@item @var{spec} @t{|} @var{spec} +Either of the two @var{spec}s can be matched. + +@end table + +@noindent +The function @t{_regex_words} can be used as a helper function to +generate matches for a set of alternative words possibly with +their own arguments as a command line argument. + +@noindent +Examples: + +@noindent +@example +_regex_arguments _tst /$'[^\0]#\0'/ \ + /$'[^\0]#\0'/ :'compadd aaa' +@end example + +@noindent +This generates a function @t{_tst} that completes @t{aaa} as its only +argument. The @var{tag} and @var{description} for the action have been +omitted for brevity (this works but is not recommended in normal use). +The first component matches the command word, which is arbitrary; the +second matches any argument. As the argument is also arbitrary, any +following component would not depend on @t{aaa} being present. + +@noindent +@example +_regex_arguments _tst /$'[^\0]#\0'/ \ + /$'aaa\0'/ :'compadd aaa' +@end example + +@noindent +This is a more typical use; it is similar, but any following patterns +would only match if @t{aaa} was present as the first argument. + +@noindent +@example +_regex_arguments _tst /$'[^\0]#\0'/ \( \ + /$'aaa\0'/ :'compadd aaa' \ + /$'bbb\0'/ :'compadd bbb' \) \# +@end example + +@noindent +In this example, an indefinite number of command arguments may be +completed. Odd arguments are completed as @t{aaa} and even arguments +as @t{bbb}. Completion fails unless the set of @t{aaa} and @t{bbb} +arguments before the current one is matched correctly. + +@noindent +@example +_regex_arguments _tst /$'[^\0]#\0'/ \ + \( /$'aaa\0'/ :'compadd aaa' \| \ + /$'bbb\0'/ :'compadd bbb' \) \# +@end example + +@noindent +This is similar, but either @t{aaa} or @t{bbb} may be completed for +any argument. In this case @t{_regex_words} could be used to generate +a suitable expression for the arguments. + +@noindent + +@findex _regex_words [ @t{-t} @var{term} ] +@item @t{_regex_words} @var{tag} @var{description} @var{spec} ... +This function can be used to generate arguments for the +@t{_regex_arguments} command which may be inserted at any point where +a set of rules is expected. The @var{tag} and @var{description} give a +standard tag and description pertaining to the current context. Each +@var{spec} contains two or three arguments separated by a colon: note +that there is no leading colon in this case. + +@noindent +Each @var{spec} gives one of a set of words that may be completed at +this point, together with arguments. It is thus roughly equivalent to +the @t{_arguments} function when used in normal (non-regex) completion. + +@noindent +The part of the @var{spec} before the first colon is the word to be +completed. This may contain a @t{*}; the entire word, before and after +the @t{*} is completed, but only the text before the @t{*} is required +for the context to be matched, so that further arguments may be +completed after the abbreviated form. + +@noindent +The second part of @var{spec} is a description for the word being +completed. + +@noindent +The optional third part of the @var{spec} describes how words following +the one being completed are themselves to be completed. It will be +evaluated in order to avoid problems with quoting. This means that +typically it contains a reference to an array containing previously +generated regex arguments. + +@noindent +The option @t{-t} @var{term} specifies a terminator for the word +instead of the usual space. This is handled as an auto-removable suffix +in the manner of the option @t{-s} @var{sep} to @t{_values}. + +@noindent +The result of the processing by @t{_regex_words} is placed in the array +@t{reply}, which should be made local to the calling function. +If the set of words and arguments may be matched repeatedly, a @t{#} +should be appended to the generated array at that point. + +@noindent +For example: + +@noindent +@example +local -a reply +_regex_words mydb-commands 'mydb commands' \ + 'add:add an entry to mydb:$mydb_add_cmds' \ + 'show:show entries in mydb' +_regex_arguments _mydb "$reply[@@]" +_mydb "$@@" +@end example + +@noindent +This shows a completion function for a command @t{mydb} which takes +two command arguments, @t{add} and @t{show}. @t{show} takes no arguments, +while the arguments for @t{add} have already been prepared in an +array @t{mydb_add_cmds}, quite possibly by a previous call to +@t{_regex_words}. + +@findex _requested +@item @t{_requested} [ @t{-x} ] [ @t{-12VJ} ] @var{tag} [ @var{name} @var{descr} [ @var{command} [ @var{arg} ... ] ] +This function is called to decide whether a tag already registered by a +call to @t{_tags} (see below) has been requested by the user and hence +completion should be performed for it. It returns status zero if the +tag is requested and non-zero otherwise. The function is typically used +as part of a loop over different tags as follows: + +@noindent +@example +_tags foo bar baz +while _tags; do + if _requested foo; then + ... # perform completion for foo + fi + ... # test the tags bar and baz in the same way + ... # exit loop if matches were generated +done +@end example + +@noindent +Note that the test for whether matches were generated is not performed +until the end of the @t{_tags} loop. This is so that the user can set +the @t{tag-order} style to specify a set of tags to be completed at the +same time. + +@noindent +If @var{name} and @var{descr} are given, @t{_requested} calls the +@t{_description} function with these arguments together with the options +passed to @t{_requested}. + +@noindent +If @var{command} is given, the @t{_all_labels} function will be called +immediately with the same arguments. In simple cases this makes it +possible to perform the test for the tag and the matching in one go. +For example: + +@noindent +@example +local expl ret=1 +_tags foo bar baz +while _tags; do + _requested foo expl 'description' \ + compadd foobar foobaz && ret=0 + ... + (( ret )) || break +done +@end example + +@noindent +If the @var{command} is not @t{compadd}, it must nevertheless be prepared +to handle the same options. + +@findex _retrieve_cache +@item @t{_retrieve_cache} @var{cache_identifier} +This function retrieves completion information from the file given by +@var{cache_identifier}, stored in a directory specified by the +@t{cache-path} style which defaults to @t{~/.zcompcache}. The return status +is zero if retrieval was successful. It will only attempt retrieval +if the @t{use-cache} style is set, so you can call this function +without worrying about whether the user wanted to use the caching +layer. + +@noindent +See @t{_store_cache} below for more details. + +@findex _sep_parts +@item @t{_sep_parts} +This function is passed alternating arrays and separators as arguments. +The arrays specify completions for parts of strings to be separated by the +separators. The arrays may be the names of array parameters or +a quoted list of words in parentheses. For example, with the array +`@t{hosts=(ftp news)}' the call `@t{_sep_parts '(foo bar)' @@ hosts}' will +complete the string `@t{f}' to `@t{foo}' and the string `@t{b@@n}' to +`@t{bar@@news}'. + +@noindent +This function accepts the @t{compadd} options `@t{-V}', `@t{-J}', +`@t{-1}', `@t{-2}', `@t{-n}', `@t{-X}', `@t{-M}', `@t{-P}', `@t{-S}', +`@t{-r}', `@t{-R}', and `@t{-q}' and passes them on to the @t{compadd} +builtin used to add the matches. + +@findex _sequence +@item @t{_sequence} [ @t{-s} @var{sep} ] [ @t{-n} @var{max} ] [ @t{-d} ] @var{function} [ @t{-} ] ... +This function is a wrapper to other functions for completing items in a +separated list. The same function is used to complete each item in the +list. The separator is specified with the @t{-s} option. If @t{-s} is +omitted it will use `@t{,}'. Duplicate values are not matched unless +@t{-d} is specified. If there is a fixed or maximum number of items in +the list, this can be specified with the @t{-n} option. + +@noindent +Common @t{compadd} options are passed on to the function. It is possible +to use @t{compadd} directly with @t{_sequence}, though @t{_values} may +be more appropriate in this situation. + +@findex _setup +@item @t{_setup} @var{tag} [ @var{group} ] +This function sets up the special +parameters used by the completion system appropriately for the @var{tag} +given as the first argument. It uses the styles @t{list-colors}, +@t{list-packed}, @t{list-rows-first}, @t{last-prompt}, @t{accept-exact}, +@t{menu} and @t{force-list}. + +@noindent +The optional @var{group} supplies the name of the group in which the +matches will be placed. If it is not given, the @var{tag} is used as +the group name. + +@noindent +This function is called automatically from @t{_description} +and hence is not normally called explicitly. + +@findex _store_cache +@item @t{_store_cache} @var{cache_identifier} @var{param} ... +This function, together with @t{_retrieve_cache} and +@t{_cache_invalid}, implements a caching layer which can be used +in any completion function. Data obtained by +costly operations are stored in parameters; +this function then dumps the values of those parameters to a file. The +data can then be retrieved quickly from that file via @t{_retrieve_cache}, +even in different instances of the shell. + +@noindent +The @var{cache_identifier} specifies the file which the data should be +dumped to. The file is stored in a directory specified by the +@t{cache-path} style which defaults to @t{~/.zcompcache}. The remaining +@var{param}s arguments are the parameters to dump to the file. + +@noindent +The return status is zero if storage was successful. The function will +only attempt storage if the @t{use-cache} style is set, so you can +call this function without worrying about whether the user wanted to +use the caching layer. + +@noindent +The completion function may avoid calling @t{_retrieve_cache} when it +already has the completion data available as parameters. +However, in that case it should +call @t{_cache_invalid} to check whether the data in the parameters and +in the cache are still valid. + +@noindent +See the _perl_modules completion function for a simple example of +the usage of the caching layer. + +@findex _tags +@item @t{_tags} [ [ @t{-C} @var{name} ] @var{tag} ... ] +If called with arguments, these are taken to be the names of tags +valid for completions in the current context. These tags are stored +internally and sorted by using the @t{tag-order} style. + +@noindent +Next, @t{_tags} is called repeatedly without arguments from the same +completion function. This successively selects the first, second, +etc. set of tags requested by the user. The return status is zero if at +least one of the tags is requested and non-zero otherwise. To test if a +particular tag is to be tried, the @t{_requested} function should be +called (see above). + +@noindent +If `@t{-C} @var{name}' is given, @var{name} is temporarily stored in the +@var{argument} field (the fifth) of the context in the @t{curcontext} parameter +during the call to @t{_tags}; the field is restored on exit. This +allows @t{_tags} to use a more +specific context without having to change and reset the +@t{curcontext} parameter (which has the same effect). + +@findex _tilde_files +@item @t{_tilde_files} +Like @t{_files}, but resolve leading tildes according to the rules of +filename expansion, so the suggested completions don't start with +a `@t{~}' even if the filename on the command-line does. + +@findex _values +@item @t{_values} [ @t{-O} @var{name} ] [ @t{-s} @var{sep} ] [ @t{-S} @var{sep} ] [ @t{-wC} ] @var{desc} @var{spec} ... +This is used to complete arbitrary keywords (values) and their arguments, +or lists of such combinations. + +@noindent +If the first argument is the option `@t{-O} @var{name}', it will be used +in the same way as by the @t{_arguments} function. In other words, the +elements of the @var{name} array will be passed to @t{compadd} +when executing an action. + +@noindent +If the first argument (or the first argument after `@t{-O} @var{name}') +is `@t{-s}', the next argument is used as the character that separates +multiple values. This character is automatically added after each value +in an auto-removable fashion (see below); all values completed by +`@t{_values -s}' appear in the same word on the command line, unlike +completion using @t{_arguments}. If this option is not present, only a +single value will be completed per word. + +@noindent +Normally, @t{_values} will only use the current word to determine +which values are already present on the command line and hence are not +to be completed again. If the @t{-w} option is given, other arguments +are examined as well. + +@noindent +The first non-option argument, @var{desc}, is used as a string to print as a +description before listing the values. + +@noindent +All other arguments describe the possible values and their +arguments in the same format used for the description of options by +the @t{_arguments} function (see above). The only differences are that +no minus or plus sign is required at the beginning, +values can have only one argument, and the forms of action +beginning with an equal sign are not supported. + +@noindent +The character separating a value from its argument can be set using the +option @t{-S} (like @t{-s}, followed by the character to use as the +separator in the next argument). By default the equals +sign will be used as the separator between values and arguments. + +@noindent +Example: + +@noindent +@example +_values -s , 'description' \ + '*foo[bar]' \ + '(two)*one[number]:first count:' \ + 'two[another number]::second count:(1 2 3)' +@end example + +@noindent +This describes three possible values: `@t{foo}', `@t{one}', and +`@t{two}'. The first is described as `@t{bar}', takes no argument +and may appear more than once. The second is described as +`@t{number}', may appear more than once, and takes one mandatory +argument described as `@t{first count}'; no action is +specified, so it will not be completed. The +`@t{(two)}' at the beginning says that if the value `@t{one}' is on +the line, the value `@t{two}' will no longer be considered a possible +completion. Finally, the last value (`@t{two}') is described +as `@t{another number}' and takes an optional argument described as +`@t{second count}' for which the completions (to appear after an +`@t{=}') are `@t{1}', `@t{2}', and `@t{3}'. The @t{_values} function +will complete lists of these values separated by commas. + +@noindent +Like @t{_arguments}, this function temporarily adds another context name +component to the arguments element (the fifth) of the current context +while executing the @var{action}. Here this name is just the name of the +value for which the argument is completed. + +@noindent +The style @t{verbose} is used to decide if the descriptions for the +values (but not those for the arguments) should be printed. + +@noindent +The associative array @t{val_args} is used to report values and their +arguments; this works similarly to the @t{opt_args} associative array +used by @t{_arguments}. Hence the function calling @t{_values} should +declare the local parameters @t{state}, @t{state_descr}, @t{line}, +@t{context} and @t{val_args}: + +@noindent +@example +local context state state_descr line +typeset -A val_args +@end example + +@noindent +when using an action of the form `@t{->}@var{string}'. With this +function the @t{context} parameter will be set to the name of the +value whose argument is to be completed. Note that for @t{_values}, +the @t{state} and @t{state_descr} are scalars rather than arrays. +Only a single matching state is returned. + +@noindent +Note also that @t{_values} normally adds the character used as the +separator between values as an auto-removable suffix (similar to a +`@t{/}' after a directory). However, this is not possible for a +`@t{->}@var{string}' action as the matches for the argument are +generated by the calling function. To get the usual behaviour, +the calling function can add the separator @var{x} as a suffix by +passing the options `@t{-qS} @var{x}' either directly or indirectly to +@t{compadd}. + +@noindent +The option @t{-C} is treated in the same way as it is by @t{_arguments}. +In that case the parameter @t{curcontext} should be made local instead +of @t{context} (as described above). + +@findex _wanted +@item @t{_wanted} [ @t{-x} ] [ @t{-C} @var{name} ] [ @t{-12VJ} ] @var{tag} @var{name} @var{descr} @var{command} [ @var{arg} ...] +In many contexts, completion can only generate one particular set of +matches, usually corresponding to a single tag. However, it is +still necessary to decide whether the user requires matches of this type. +This function is useful in such a case. + +@noindent +The arguments to @t{_wanted} are the same as those to @t{_requested}, +i.e. arguments to be passed to @t{_description}. However, in this case +the @var{command} is not optional; all the processing of tags, including +the loop over both tags and tag labels and the generation of matches, +is carried out automatically by @t{_wanted}. + +@noindent +Hence to offer only one tag and immediately add the corresponding +matches with the given description: + +@noindent +@example +local expl +_wanted tag expl 'description' \ + compadd matches... +@end example + +@noindent +Note that, as for @t{_requested}, the @var{command} must be able to +accept options to be passed down to @t{compadd}. + +@noindent +Like @t{_tags} this function supports the @t{-C} option to give a +different name for the argument context field. The @t{-x} option has +the same meaning as for @t{_description}. + +@findex _widgets +@item @t{_widgets} [ @t{-g} @var{pattern} ] +This function completes names of zle widgets (see +@ref{Zle Widgets}). The @var{pattern}, if present, is matched against values of the @t{$widgets} +special parameter, documented in +@ref{The zsh/zleparameter Module}. + +@end table + +@noindent +@node Completion System Variables, Completion Directories, Completion Functions, Completion System + +@section Completion System Variables +@noindent +@cindex completion system, variables + +@noindent +There are some standard variables, initialised by the @t{_main_complete} +function and then used from other functions. + +@noindent +The standard variables are: + +@noindent +@table @asis +@item @t{_comp_caller_options} +The completion system uses @t{setopt} to set a number of options. This +allows functions to be written without concern for compatibility with +every possible combination of user options. However, sometimes completion +needs to know what the user's option preferences are. These are saved +in the @t{_comp_caller_options} associative array. Option names, spelled +in lowercase without underscores, are mapped to one or other of the +strings `@t{on}' and `@t{off}'. + + +@noindent +@item @t{_comp_priv_prefix} +Completion functions such as @t{_sudo} can set the @t{_comp_priv_prefix} +array to a command prefix that may then be used by @t{_call_program} to +match the privileges when calling programs to generate matches. + +@end table + +@noindent +Two more features are offered by the @t{_main_complete} function. The +arrays @t{compprefuncs} and @t{comppostfuncs} may contain +names of functions that are to be called immediately before or after +completion has been tried. A function will only be called once unless +it explicitly reinserts itself into the array. + +@noindent +@node Completion Directories, , Completion System Variables, Completion System + +@section Completion Directories +@noindent +@cindex completion system, directory structure + +@noindent +In the source distribution, the files are contained in various +subdirectories of the @t{Completion} directory. They may have been +installed in the same structure, or into one single function directory. +The following is a description of the files found in the original directory +structure. If you wish to alter an installed file, you will need to copy +it to some directory which appears earlier in your @t{fpath} than the +standard directory where it appears. + +@noindent +@table @asis +@item @t{Base} +The core functions and special completion widgets automatically bound +to keys. You will certainly need most of these, though will +probably not need to alter them. Many of these are documented above. + +@item @t{Zsh} +Functions for completing arguments of shell builtin commands and +utility functions for this. Some of these are also used by functions from +the @t{Unix} directory. + +@item @t{Unix} +Functions for completing arguments of external commands and suites of +commands. They may need modifying for your system, although in many cases +some attempt is made to decide which version of a command is present. For +example, completion for the @t{mount} command tries to determine the system +it is running on, while completion for many other utilities try to decide +whether the GNU version of the command is in use, and hence whether the +@t{-}@t{-help} option is supported. + +@item @t{X}, @t{AIX}, @t{BSD}, ... +Completion and utility function for commands available only on some systems. +These are not arranged hierarchically, so, for example, both the +@t{Linux} and @t{Debian} directories, as well as the @t{X} directory, +may be useful on your system. + +@end table +@c (avoiding a yodl bug) +@c Yodl file: Zsh/compctl.yo +@node Completion Using compctl, Zsh Modules, Completion System, Top + +@chapter Completion Using compctl +@noindent +@cindex completion, programmable +@cindex completion, controlling + +@section Types of completion +@noindent +This version of zsh has two ways of performing completion of words on the +command line. New users of the shell may prefer to use the newer +and more powerful system based on shell functions; this is described +in @ref{Completion System}, and the basic shell mechanisms which support +it are described in @ref{Completion Widgets}. This chapter describes +the older @t{compctl} command. + +@section Description +@noindent +@findex compctl + +@table @asis +@item @t{compctl} [ @t{-CDT} ] @var{options} [ @var{command} ... ] +@item @t{compctl }[ @t{-CDT} ] @var{options} [ @t{-x} @var{pattern} @var{options} @t{-} ... @t{-}@t{-} ] +@item @t{@ @ @ @ @ @ @ @ }[ @t{+} @var{options} [ @t{-x} ... @t{-}@t{-} ] ... [@t{+}] ] [ @var{command} ... ] +@item @t{compctl} @t{-M} @var{match-specs} ... +@item @t{compctl} @t{-L} [ @t{-CDTM} ] [ @var{command} ... ] +@item @t{compctl} @t{+} @var{command} ... +@end table +@sp 1 + +@noindent +Control the editor's completion behavior according to the supplied set +of @var{options}. Various editing commands, notably +@t{expand-or-complete-word}, usually bound to tab, will +attempt to complete a word typed by the user, while others, notably +@t{delete-char-or-list}, usually bound to ^D in EMACS editing +mode, list the possibilities; @t{compctl} controls what those +possibilities are. They may for example be filenames (the most common +case, and hence the default), shell variables, or words from a +user-specified list. +@menu +* Command Flags:: +* Option Flags:: +* Alternative Completion:: +* Extended Completion:: +* Example:: +@end menu + +@noindent +@node Command Flags, Option Flags, , Completion Using compctl + +@section Command Flags +@noindent +Completion of the arguments of a command may be different for each +command or may use the default. The behavior when completing the +command word itself may also be separately specified. These +correspond to the following flags and arguments, all of which (except +for @t{-L}) may be combined with any combination of the +@var{options} described subsequently in @ref{Option Flags}: + +@noindent +@table @asis +@item @var{command} ... +controls completion for the named commands, which must be listed last +on the command line. If completion is attempted for a command with a +pathname containing slashes and no completion definition is found, the +search is retried with the last pathname component. If the command starts +with a @t{=}, completion is tried with the pathname of the command. + +@noindent +Any of the @var{command} strings may be patterns of the form normally +used for filename generation. These should be quoted to protect them +from immediate expansion; for example the command string @t{'foo*'} +arranges for completion of the words of any command beginning with +@t{foo}. When completion is attempted, all pattern completions are +tried in the reverse order of their definition until one matches. By +default, completion then proceeds as normal, i.e. the shell will try to +generate more matches for the specific command on the command line; this +can be overridden by including @t{-tn} in the flags for the pattern +completion. + +@noindent +Note that aliases +are expanded before the command name is determined unless the +@t{COMPLETE_ALIASES} option is set. Commands may not be combined +with the @t{-C}, @t{-D} or @t{-T} flags. + +@item @t{-C} +controls completion when the command word itself is being completed. +If no @t{compctl -C} command has been issued, the names of any +executable command (whether in the path or specific to the shell, such +as aliases or functions) are completed. + +@item @t{-D} +controls default completion behavior for the arguments of commands not +assigned any special behavior. If no @t{compctl -D} command has +been issued, filenames are completed. + +@item @t{-T} +supplies completion flags to be used before any other processing is +done, even before processing for @t{compctl}s defined for specific +commands. This is especially useful when combined with extended +completion (the @t{-x} flag, see @ref{Extended Completion} below). +Using this flag you can define default behavior +which will apply to all commands without exception, or you can alter +the standard behavior for all commands. For example, if your access +to the user database is too slow and/or it contains too many users (so +that completion after `@t{~}' is too slow to be usable), you can use + +@noindent +@example +compctl -T -x 's[~] C[0,[^/]#]' -k friends -S/ -tn +@end example + +@noindent +to complete the strings in the array @t{friends} after a `@t{~}'. +The @t{C[}@var{...}@t{]} argument is necessary so that this form of +@t{~}-completion is +not tried after the directory name is finished. + +@item @t{-L} +lists the existing completion behavior in a manner suitable for +putting into a start-up script; the existing behavior is not changed. +Any combination of the above forms, or the @t{-M} flag (which must +follow the @t{-L} flag), may be specified, otherwise all defined +completions are listed. Any other flags supplied are ignored. + +@item @emph{no argument} +If no argument is given, @t{compctl} lists all defined completions +in an abbreviated form; with a list of @var{options}, all completions +with those flags set (not counting extended completion) are listed. + +@end table + +@noindent +If the @t{+} flag is alone and followed immediately by the @var{command} +list, the completion behavior for all the commands in the list is reset to +the default. In other words, completion will subsequently use the +options specified by the @t{-D} flag. + +@noindent +The form with @t{-M} as the first and only option defines global +matching specifications (see +@ref{Completion Matching Control}). The match specifications given will be used for every completion +attempt (only when using @t{compctl}, not with the new completion +system) and are tried in the order in which they are defined until one +generates at least one match. E.g.: + +@noindent +@example +compctl -M @value{dsq} 'm:@{a-zA-Z@}=@{A-Za-z@}' +@end example + +@noindent +This will first try completion without any global match specifications +(the empty string) and, if that generates no matches, will try case +insensitive completion. + +@noindent +@node Option Flags, Alternative Completion, Command Flags, Completion Using compctl + +@section Option Flags +@noindent +@table @asis +@item [ @t{-fcFBdeaRGovNAIOPZEnbjrzu/12} ] +@item [ @t{-k} @var{array} ] [ @t{-g} @var{globstring} ] [ @t{-s} @var{subststring} ] +@item [ @t{-K} @var{function} ] +@item [ @t{-Q} ] [ @t{-P} @var{prefix} ] [ @t{-S} @var{suffix} ] +@item [ @t{-W} @var{file-prefix} ] [ @t{-H} @var{num pattern} ] +@item [ @t{-q} ] [ @t{-X} @var{explanation} ] [ @t{-Y} @var{explanation} ] +@item [ @t{-y} @var{func-or-var} ] [ @t{-l} @var{cmd} ] [ @t{-h} @var{cmd} ] [ @t{-U} ] +@item [ @t{-t} @var{continue} ] [ @t{-J} @var{name} ] [ @t{-V} @var{name} ] +@item [ @t{-M} @var{match-spec} ] +@end table +@sp 1 + +@noindent +The remaining @var{options} specify the type of command arguments +to look for during completion. Any combination of these flags may be +specified; the result is a sorted list of all the possibilities. The +options are as follows. +@menu +* Simple Flags:: +* Flags with Arguments:: +* Control Flags:: +@end menu + +@noindent +@node Simple Flags, Flags with Arguments, , Option Flags + +@subsection Simple Flags +@noindent +These produce completion lists made up by the shell itself: + +@noindent +@table @asis +@item @t{-f} +Filenames and file system paths. + +@item @t{-/} +Just file system paths. + +@item @t{-c} +Command names, including aliases, shell functions, builtins +and reserved words. + +@item @t{-F} +Function names. + +@item @t{-B} +Names of builtin commands. + +@item @t{-m} +Names of external commands. + +@item @t{-w} +Reserved words. + +@item @t{-a} +Alias names. + +@item @t{-R} +Names of regular (non-global) aliases. + +@item @t{-G} +Names of global aliases. + +@item @t{-d} +This can be combined with @t{-F}, @t{-B}, @t{-w}, +@t{-a}, @t{-R} and @t{-G} to get names of disabled +functions, builtins, reserved words or aliases. + +@item @t{-e} +This option (to show enabled commands) is in effect by default, but +may be combined with @t{-d}; @t{-de} in combination with +@t{-F}, @t{-B}, @t{-w}, @t{-a}, @t{-R} and @t{-G} +will complete names of functions, builtins, reserved words or aliases +whether or not they are disabled. + +@item @t{-o} +Names of shell options (see +@ref{Options}). + +@item @t{-v} +Names of any variable defined in the shell. + +@item @t{-N} +Names of scalar (non-array) parameters. + +@item @t{-A} +Array names. + +@item @t{-I} +Names of integer variables. + +@item @t{-O} +Names of read-only variables. + +@item @t{-p} +Names of parameters used by the shell (including special parameters). + +@item @t{-Z} +Names of shell special parameters. + +@item @t{-E} +Names of environment variables. + +@item @t{-n} +Named directories. + +@item @t{-b} +Key binding names. + +@item @t{-j} +Job names: the first word of the job leader's command line. This is useful +with the @t{kill} builtin. + +@item @t{-r} +Names of running jobs. + +@item @t{-z} +Names of suspended jobs. + +@item @t{-u} +User names. + +@end table + +@noindent +@node Flags with Arguments, Control Flags, Simple Flags, Option Flags + +@subsection Flags with Arguments +@noindent +These have user supplied arguments to determine how the list of +completions is to be made up: + +@noindent +@table @asis +@item @t{-k} @var{array} +Names taken from the elements of @t{$}@var{array} (note that the `@t{$}' +does not appear on the command line). +Alternatively, the argument @var{array} itself may be a set +of space- or comma-separated values in parentheses, in which any +delimiter may be escaped with a backslash; in this case the argument +should be quoted. For example, + +@noindent +@example +compctl -k "(cputime filesize datasize stacksize + coredumpsize resident descriptors)" limit +@end example + +@item @t{-g} @var{globstring} +The @var{globstring} is expanded using filename globbing; it should be +quoted to protect it from immediate expansion. The resulting +filenames are taken as the possible completions. Use `@t{*(/)}' instead of +`@t{*/}' for directories. The @t{fignore} special parameter is not +applied to the resulting files. More than one pattern may be given +separated by blanks. (Note that brace expansion is @emph{not} part of +globbing. Use the syntax `@t{(either|or)}' to match alternatives.) + +@item @t{-s} @var{subststring} +The @var{subststring} is split into words and these words are than +expanded using all shell expansion mechanisms (see +@ref{Expansion}). The resulting words are taken as possible +completions. The @t{fignore} special parameter is not applied to the +resulting files. Note that @t{-g} is faster for filenames. + +@item @t{-K} @var{function} +@vindex reply, use of +Call the given function to get the completions. Unless the name +starts with an underscore, the function is +passed two arguments: the prefix and the suffix of the word on which +completion is to be attempted, in other words those characters before +the cursor position, and those from the cursor position onwards. The +whole command line can be accessed with the @t{-c} and @t{-l} flags +of the @t{read} builtin. The +function should set the variable @t{reply} to an array containing +the completions (one completion per element); note that @t{reply} +should not be made local to the function. From such a function the +command line can be accessed with the @t{-c} and @t{-l} flags to +the @t{read} builtin. For example, + +@noindent +@example +function whoson @{ reply=(`users`); @} +compctl -K whoson talk +@end example + +@noindent +completes only logged-on users after `@t{talk}'. Note that `@t{whoson}' must +return an array, so `@t{reply=`users`}' would be incorrect. + +@item @t{-H} @var{num pattern} +The possible completions are taken from the last @var{num} history +lines. Only words matching @var{pattern} are taken. If @var{num} is +zero or negative the whole history is searched and if @var{pattern} is +the empty string all words are taken (as with `@t{*}'). A typical +use is + +@noindent +@example +compctl -D -f + -H 0 @value{dsq} +@end example + +@noindent +which forces completion to look back in the history list for a word if +no filename matches. + +@end table + +@noindent +@node Control Flags, , Flags with Arguments, Option Flags + +@subsection Control Flags +@noindent +These do not directly specify types of name to be completed, but +manipulate the options that do: + +@noindent +@table @asis +@item @t{-Q} +This instructs the shell not to quote any metacharacters in the possible +completions. Normally the results of a completion are inserted into +the command line with any metacharacters quoted so that they are +interpreted as normal characters. This is appropriate for filenames +and ordinary strings. However, for special effects, such as inserting +a backquoted expression from a completion array (@t{-k}) so that +the expression will not be evaluated until the complete line is +executed, this option must be used. + +@item @t{-P} @var{prefix} +The @var{prefix} is inserted just before the completed string; any +initial part already typed will be completed and the whole @var{prefix} +ignored for completion purposes. For example, + +@noindent +@example +compctl -j -P "%" kill +@end example + +@noindent +inserts a `%' after the kill command and then completes job names. + +@item @t{-S} @var{suffix} +When a completion is found the @var{suffix} is inserted after +the completed string. In the case of menu completion the suffix is +inserted immediately, but it is still possible to cycle through the +list of completions by repeatedly hitting the same key. + +@item @t{-W} @var{file-prefix} +With directory @var{file-prefix}: for command, file, directory and +globbing completion (options @t{-c}, @t{-f}, @t{-/}, @t{-g}), the file +prefix is implicitly added in front of the completion. For example, + +@noindent +@example +compctl -/ -W ~/Mail maildirs +@end example + +@noindent +completes any subdirectories to any depth beneath the directory +@t{~/Mail}, although that prefix does not appear on the command line. +The @var{file-prefix} may also be of the form accepted by the @t{-k} +flag, i.e. the name of an array or a literal list in parenthesis. In +this case all the directories in the list will be searched for +possible completions. + +@item @t{-q} +If used with a suffix as specified by the @t{-S} option, this +causes the suffix to be removed if the next character typed is a blank +or does not insert anything or if the suffix consists of only one character +and the next character typed is the same character; this the same rule used +for the @t{AUTO_REMOVE_SLASH} option. The option is most useful for list +separators (comma, colon, etc.). + +@item @t{-l} @var{cmd} +This option restricts the range +of command line words that are considered to be arguments. If +combined with one of the extended completion patterns `@t{p[}...@t{]}', +`@t{r[}...@t{]}', or `@t{R[}...@t{]}' (see @ref{Extended Completion} +below) the range is restricted to the range of arguments +specified in the brackets. Completion is then performed as if these +had been given as arguments to the @var{cmd} supplied with the +option. If the @var{cmd} string is empty the first word in the range +is instead taken as the command name, and command name completion +performed on the first word in the range. For example, + +@noindent +@example +compctl -x 'r[-exec,;]' -l @value{dsq} -- find +@end example + +@noindent +completes arguments between `@t{-exec}' and the following `@t{;}' (or the end +of the command line if there is no such string) as if they were +a separate command line. + +@item @t{-h} @var{cmd} +Normally zsh completes quoted strings as a whole. With this option, +completion can be done separately on different parts of such +strings. It works like the @t{-l} option but makes the completion code +work on the parts of the current word that are separated by +spaces. These parts are completed as if they were arguments to the +given @var{cmd}. If @var{cmd} is the empty string, the first part is +completed as a command name, as with @t{-l}. + +@item @t{-U} +Use the whole list of possible completions, whether or not they +actually match the word on the command line. The word typed so far +will be deleted. This is most useful with a function (given by the +@t{-K} option) which can examine the word components passed to it +(or via the @t{read} builtin's @t{-c} and @t{-l} flags) and +use its own criteria to decide what matches. If there is no +completion, the original word is retained. Since the produced +possible completions seldom have interesting common prefixes +and suffixes, menu completion is started immediately if @t{AUTO_MENU} is +set and this flag is used. + +@item @t{-y} @var{func-or-var} +@vindex reply, use of +The list provided by @var{func-or-var} is displayed instead of the list +of completions whenever a listing is required; the actual completions +to be inserted are not affected. It can be provided in two +ways. Firstly, if @var{func-or-var} begins with a @t{$} it defines a +variable, or if it begins with a left parenthesis a literal +array, which contains the list. A variable may have been set by a +call to a function using the @t{-K} option. Otherwise it contains the +name of a function which will be executed to create the list. The +function will be passed as an argument list all matching completions, +including prefixes and suffixes expanded in full, and should set the +array @t{reply} to the result. In both cases, the display list will +only be retrieved after a complete list of matches has been created. + +@noindent +Note that the returned list does not have to correspond, even in +length, to the original set of matches, and may be passed as a scalar +instead of an array. No special formatting of characters is +performed on the output in this case; in particular, newlines are +printed literally and if they appear output in columns is suppressed. + +@item @t{-X} @var{explanation} +Print @var{explanation} when trying completion on the current set of +options. A `@t{%n}' in this string is replaced by the number of +matches that were added for this explanation string. +The explanation only appears if completion was tried and there was +no unique match, or when listing completions. Explanation strings +will be listed together with the matches of the group specified +together with the @t{-X} option (using the @t{-J} or @t{-V} +option). If the same explanation string is given to multiple @t{-X} +options, the string appears only once (for each group) and the number +of matches shown for the `@t{%n}' is the total number of all matches +for each of these uses. In any case, the explanation string will only +be shown if there was at least one match added for the explanation +string. + +@noindent +The sequences @t{%B}, @t{%b}, @t{%S}, @t{%s}, @t{%U}, and @t{%u} specify +output attributes (bold, standout, and underline), @t{%F}, @t{%f}, @t{%K}, +@t{%k} specify foreground and background colours, and @t{%@{}@var{...}@t{%@}} can +be used to include literal escape sequences as in prompts. + +@item @t{-Y} @var{explanation} +Identical to @t{-X}, except that the @var{explanation} first undergoes +expansion following the usual rules for strings in double quotes. +The expansion will be carried out after any functions are called for +the @t{-K} or @t{-y} options, allowing them to set variables. + +@item @t{-t} @var{continue} +The @var{continue}-string contains a character that specifies which set +of completion flags should be used next. It is useful: + +@noindent +(i) With @t{-T}, or when trying a list of pattern completions, when +@t{compctl} would usually continue with ordinary processing after +finding matches; this can be suppressed with `@t{-tn}'. + +@noindent +(ii) With a list of alternatives separated by @t{+}, when @t{compctl} +would normally stop when one of the alternatives generates matches. It +can be forced to consider the next set of completions by adding `@t{-t+}' +to the flags of the alternative before the `@t{+}'. + +@noindent +(iii) In an extended completion list (see below), when @t{compctl} would +normally continue until a set of conditions succeeded, then use only +the immediately following flags. With `@t{-t-}', @t{compctl} will +continue trying extended completions after the next `@t{-}'; with +`@t{-tx}' it will attempt completion with the default flags, in other +words those before the `@t{-x}'. + +@item @t{-J} @var{name} +This gives the name of the group the matches should be placed in. Groups +are listed and sorted separately; likewise, menu completion will offer +the matches in the groups in the order in which the groups were +defined. If no group name is explicitly given, the matches are stored in +a group named @t{default}. The first time a group name is encountered, +a group with that name is created. After that all matches with the same +group name are stored in that group. + +@noindent +This can be useful with non-exclusive alternative completions. For +example, in + +@noindent +@example +compctl -f -J files -t+ + -v -J variables foo +@end example + +@noindent +both files and variables are possible completions, as the @t{-t+} forces +both sets of alternatives before and after the @t{+} to be considered at +once. Because of the @t{-J} options, however, all files are listed +before all variables. + +@item @t{-V} @var{name} +Like @t{-J}, but matches within the group will not be sorted in listings +nor in menu completion. These unsorted groups are in a different name +space from the sorted ones, so groups defined as @t{-J files} and @t{-V +files} are distinct. + +@item @t{-1} +If given together with the @t{-V} option, makes +only consecutive duplicates in the group be removed. Note that groups +with and without this flag are in different name spaces. + +@item @t{-2} +If given together with the @t{-J} or @t{-V} option, makes all +duplicates be kept. Again, groups with and without this flag are in +different name spaces. + +@item @t{-M} @var{match-spec} +This defines additional matching control specifications that should be used +only when testing words for the list of flags this flag appears in. The format +of the @var{match-spec} string is described in +@ref{Completion Matching Control}. + +@end table + +@noindent +@node Alternative Completion, Extended Completion, Option Flags, Completion Using compctl + +@section Alternative Completion +@noindent +@table @asis +@item @t{compctl} [ @t{-CDT} ] @var{options} @t{+} @var{options} [ @t{+} ... ] [ @t{+} ] @var{command} ... +@end table +@sp 1 + +@noindent +The form with `@t{+}' specifies alternative options. Completion is +tried with the options before the first `@t{+}'. If this produces no +matches completion is tried with the flags after the `@t{+}' and so on. If +there are no flags after the last `@t{+}' and a match has not been found +up to that point, default completion is tried. +If the list of flags contains a @t{-t} with a @t{+} character, the next +list of flags is used even if the current list produced matches. + +@noindent +@node Extended Completion, Example, Alternative Completion, Completion Using compctl + +@noindent +Additional options are available that restrict completion to some part +of the command line; this is referred to as `extended completion'. + +@noindent + +@section Extended Completion +@noindent + +@table @asis +@item @t{compctl }[ @t{-CDT} ] @var{options} @t{-x} @var{pattern} @var{options} @t{-} ... @t{-}@t{-} +@item @t{@ @ @ @ @ @ @ @ }[ @var{command} ... ] +@item @t{compctl }[ @t{-CDT} ] @var{options} [ @t{-x} @var{pattern} @var{options} @t{-} ... @t{-}@t{-} ] +@item @t{@ @ @ @ @ @ @ @ }[ @t{+} @var{options} [ @t{-x} ... @t{-}@t{-} ] ... [@t{+}] ] [ @var{command} ... ] +@end table +@sp 1 + +@noindent +The form with `@t{-x}' specifies extended completion for the +commands given; as shown, it may be combined with alternative +completion using `@t{+}'. Each @var{pattern} is examined in turn; when a +match is found, the corresponding @var{options}, as described in +@ref{Option Flags} above, are used to generate possible +completions. If no @var{pattern} matches, the @var{options} given +before the @t{-x} are used. + +@noindent +Note that each pattern should be supplied as a single argument and +should be quoted to prevent expansion of metacharacters by the +shell. + +@noindent +A @var{pattern} is built of sub-patterns separated by commas; it +matches if at least one of these sub-patterns matches (they are +`or'ed). These sub-patterns are in turn composed of other +sub-patterns separated by white spaces which match if all of the +sub-patterns match (they are `and'ed). An element of the +sub-patterns is of the form `@var{c}@t{[}...@t{][}...@t{]}', where the pairs of +brackets may be repeated as often as necessary, and matches if any of +the sets of brackets match (an `or'). The example below makes this +clearer. + +@noindent +The elements may be any of the following: + +@noindent +@table @asis +@item @t{s[}@var{string}@t{]}... +Matches if the current word on the command line starts with +one of the strings given in brackets. The @var{string} is not removed +and is not part of the completion. + +@item @t{S[}@var{string}@t{]}... +Like @t{s[}@var{string}@t{]} except that the @var{string} is part of the +completion. + +@item @t{p[}@var{from}@t{,}@var{to}@t{]}... +Matches if the number of the current word is between one of +the @var{from} and @var{to} pairs inclusive. The comma and @var{to} +are optional; @var{to} defaults to the same value as @var{from}. The +numbers may be negative: @t{-}@var{n} refers to the @var{n}'th last word +on the line. + +@item @t{c[}@var{offset}@t{,}@var{string}@t{]}... +Matches if the @var{string} matches the word offset by +@var{offset} from the current word position. Usually @var{offset} +will be negative. + +@item @t{C[}@var{offset}@t{,}@var{pattern}@t{]}... +Like @t{c} but using pattern matching instead. + +@item @t{w[}@var{index}@t{,}@var{string}@t{]}... +Matches if the word in position @var{index} is equal +to the corresponding @var{string}. Note that the word count is made +after any alias expansion. + +@item @t{W[}@var{index}@t{,}@var{pattern}@t{]}... +Like @t{w} but using pattern matching instead. + +@item @t{n[}@var{index}@t{,}@var{string}@t{]}... +Matches if the current word contains @var{string}. Anything up to and +including the @var{index}th occurrence of this string will not be +considered part of the completion, but the rest will. @var{index} may +be negative to count from the end: in most cases, @var{index} will be +1 or -1. For example, + +@noindent +@example +compctl -s '`users`' -x 'n[1,@@]' -k hosts -- talk +@end example + +@noindent +will usually complete usernames, but if you insert an @t{@@} after the +name, names from the array @var{hosts} (assumed to contain hostnames, +though you must make the array yourself) will be completed. Other +commands such as @t{rcp} can be handled similarly. + +@item @t{N[}@var{index}@t{,}@var{string}@t{]}... +Like @t{n} except that the string will be +taken as a character class. Anything up to and including the +@var{index}th occurrence of any of the characters in @var{string} +will not be considered part of the completion. + +@item @t{m[}@var{min}@t{,}@var{max}@t{]}... +Matches if the total number of words lies between @var{min} and +@var{max} inclusive. + +@item @t{r[}@var{str1}@t{,}@var{str2}@t{]}... +Matches if the cursor is after a word with prefix @var{str1}. If there +is also a word with prefix @var{str2} on the command line after the one +matched by @var{str1} it matches +only if the cursor is before this word. If the comma and @var{str2} are +omitted, it matches if the cursor is after a word with prefix @var{str1}. + +@item @t{R[}@var{str1}@t{,}@var{str2}@t{]}... +Like @t{r} but using pattern matching instead. + +@item @t{q[}@var{str}@t{]}... +Matches the word currently being completed is in single quotes and the +@var{str} begins with the letter `s', or if completion is done in +double quotes and @var{str} starts with the letter `d', or if +completion is done in backticks and @var{str} starts with a `b'. + +@end table + +@noindent +@node Example, , Extended Completion, Completion Using compctl + +@section Example +@noindent + +@noindent +@example +compctl -u -x 's[+] c[-1,-f],s[-f+]' \ + -g '~/Mail/*(:t)' - 's[-f],c[-1,-f]' -f -- mail +@end example + +@noindent +This is to be interpreted as follows: + +@noindent +If the current command is @t{mail}, then + +@noindent +@quotation + +if ((the current word begins with @t{+} and the previous word is @t{-f}) +or (the current word begins with @t{-f+})), then complete the +non-directory part (the `@t{:t}' glob modifier) of files in the directory +@t{~/Mail}; else + +@noindent +if the current word begins with @t{-f} or the previous word was @t{-f}, then +complete any file; else + +@noindent +complete user names. + +@end quotation +@c (avoiding a yodl bug) +@c Yodl file: Zsh/modules.yo +@node Zsh Modules, Calendar Function System, Completion Using compctl, Top + +@chapter Zsh Modules +@noindent +@cindex modules + +@section Description +@noindent +Some optional parts of zsh are in modules, separate from the core +of the shell. Each of these modules may be linked in to the +shell at build time, +or can be dynamically linked while the shell is running +if the installation supports this feature. +Modules are linked at runtime with the @t{zmodload} command, +see @ref{Shell Builtin Commands}. + +@noindent +The modules that are bundled with the zsh distribution are: + +@noindent +@c Yodl file: Zsh/modlist.yo +@table @asis +@item @t{zsh/attr} +Builtins for manipulating extended attributes (xattr). + +@item @t{zsh/cap} +Builtins for manipulating POSIX.1e (POSIX.6) capability (privilege) sets. + +@item @t{zsh/clone} +A builtin that can clone a running shell onto another terminal. + +@item @t{zsh/compctl} +The @t{compctl} builtin for controlling completion. + +@item @t{zsh/complete} +The basic completion code. + +@item @t{zsh/complist} +Completion listing extensions. + +@item @t{zsh/computil} +A module with utility builtins needed for the shell function based +completion system. + +@item @t{zsh/curses} +curses windowing commands + +@item @t{zsh/datetime} +Some date/time commands and parameters. + +@item @t{zsh/db/gdbm} +Builtins for managing associative array parameters tied to GDBM databases. + +@item @t{zsh/deltochar} +A ZLE function duplicating EMACS' @t{zap-to-char}. + +@item @t{zsh/example} +An example of how to write a module. + +@item @t{zsh/files} +Some basic file manipulation commands as builtins. + +@item @t{zsh/langinfo} +Interface to locale information. + +@item @t{zsh/mapfile} +Access to external files via a special associative array. + +@item @t{zsh/mathfunc} +Standard scientific functions for use in mathematical evaluations. + +@item @t{zsh/nearcolor} +Map colours to the nearest colour in the available palette. + +@item @t{zsh/newuser} +Arrange for files for new users to be installed. + +@item @t{zsh/parameter} +Access to internal hash tables via special associative arrays. + +@item @t{zsh/pcre} +Interface to the PCRE library. + +@item @t{zsh/param/private} +Builtins for managing private-scoped parameters in function context. + +@item @t{zsh/regex} +Interface to the POSIX regex library. + +@item @t{zsh/sched} +A builtin that provides a timed execution facility within the shell. + +@item @t{zsh/net/socket} +Manipulation of Unix domain sockets + +@item @t{zsh/stat} +A builtin command interface to the @t{stat} system call. + +@item @t{zsh/system} +A builtin interface to various low-level system features. + +@item @t{zsh/net/tcp} +Manipulation of TCP sockets + +@item @t{zsh/termcap} +Interface to the termcap database. + +@item @t{zsh/terminfo} +Interface to the terminfo database. + +@item @t{zsh/zftp} +A builtin FTP client. + +@item @t{zsh/zle} +The Zsh Line Editor, including the @t{bindkey} and @t{vared} builtins. + +@item @t{zsh/zleparameter} +Access to internals of the Zsh Line Editor via parameters. + +@item @t{zsh/zprof} +A module allowing profiling for shell functions. + +@item @t{zsh/zpty} +A builtin for starting a command in a pseudo-terminal. + +@item @t{zsh/zselect} +Block and return when file descriptors are ready. + +@item @t{zsh/zutil} +Some utility builtins, e.g. the one for supporting configuration via +styles. + +@end table +@c Yodl file: Zsh/modmenu.yo +@menu +* The zsh/attr Module:: +* The zsh/cap Module:: +* The zsh/clone Module:: +* The zsh/compctl Module:: +* The zsh/complete Module:: +* The zsh/complist Module:: +* The zsh/computil Module:: +* The zsh/curses Module:: +* The zsh/datetime Module:: +* The zsh/db/gdbm Module:: +* The zsh/deltochar Module:: +* The zsh/example Module:: +* The zsh/files Module:: +* The zsh/langinfo Module:: +* The zsh/mapfile Module:: +* The zsh/mathfunc Module:: +* The zsh/nearcolor Module:: +* The zsh/newuser Module:: +* The zsh/parameter Module:: +* The zsh/pcre Module:: +* The zsh/param/private Module:: +* The zsh/regex Module:: +* The zsh/sched Module:: +* The zsh/net/socket Module:: +* The zsh/stat Module:: +* The zsh/system Module:: +* The zsh/net/tcp Module:: +* The zsh/termcap Module:: +* The zsh/terminfo Module:: +* The zsh/zftp Module:: +* The zsh/zle Module:: +* The zsh/zleparameter Module:: +* The zsh/zprof Module:: +* The zsh/zpty Module:: +* The zsh/zselect Module:: +* The zsh/zutil Module:: +@end menu +@c (avoiding a yodl bug) +@node The zsh/attr Module, The zsh/cap Module, , Zsh Modules + +@section The zsh/attr Module +@noindent +@c Yodl file: Zsh/mod_attr.yo + +The @t{zsh/attr} module is used for manipulating extended attributes. +The @t{-h} option causes all commands to operate on symbolic links instead +of their targets. +The builtins in this module are: + +@noindent +@table @asis +@findex zgetattr +@cindex extended attributes, xattr, getting from files +@item @t{zgetattr} [ @t{-h} ] @var{filename} @var{attribute} [ @var{parameter} ] +Get the extended attribute @var{attribute} from the specified +@var{filename}. If the optional argument @var{parameter} is given, the +attribute is set on that parameter instead of being printed to stdout. + +@findex zsetattr +@cindex extended attributes, xattr, setting on files +@item @t{zsetattr} [ @t{-h} ] @var{filename} @var{attribute} @var{value} +Set the extended attribute @var{attribute} on the specified +@var{filename} to @var{value}. + +@findex zdelattr +@cindex extended attributes, xattr, removing, deleting +@item @t{zdelattr} [ @t{-h} ] @var{filename} @var{attribute} +Remove the extended attribute @var{attribute} from the specified +@var{filename}. + +@findex zlistattr +@cindex extended attributes, xattr, listing +@item @t{zlistattr} [ @t{-h} ] @var{filename} [ @var{parameter} ] +List the extended attributes currently set on the specified +@var{filename}. If the optional argument @var{parameter} is given, the +list of attributes is set on that parameter instead of being printed to stdout. + +@end table + +@noindent +@t{zgetattr} and @t{zlistattr} allocate memory dynamically. If the +attribute or list of attributes grows between the allocation and the call +to get them, they return 2. On all other errors, 1 is returned. This +allows the calling function to check for this case and retry. +@c (avoiding a yodl bug) +@node The zsh/cap Module, The zsh/clone Module, The zsh/attr Module, Zsh Modules + +@section The zsh/cap Module +@noindent +@c Yodl file: Zsh/mod_cap.yo + +The @t{zsh/cap} module is used for manipulating POSIX.1e (POSIX.6) capability +sets. If the operating system does not support this interface, the +builtins defined by this module will do nothing. +The builtins in this module are: + +@noindent +@table @asis +@findex cap +@cindex capabilities, setting +@item @t{cap} [ @var{capabilities} ] +Change the shell's process capability sets to the specified @var{capabilities}, +otherwise display the shell's current capabilities. + +@findex getcap +@cindex capabilities, getting from files +@item @t{getcap} @var{filename} ... +This is a built-in implementation of the POSIX standard utility. It displays +the capability sets on each specified @var{filename}. + +@findex setcap +@cindex capabilities, setting on files +@item @t{setcap} @var{capabilities} @var{filename} ... +This is a built-in implementation of the POSIX standard utility. It sets +the capability sets on each specified @var{filename} to the specified +@var{capabilities}. + +@end table +@c (avoiding a yodl bug) +@node The zsh/clone Module, The zsh/compctl Module, The zsh/cap Module, Zsh Modules + +@section The zsh/clone Module +@noindent +@c Yodl file: Zsh/mod_clone.yo + +The @t{zsh/clone} module makes available one builtin command: + +@noindent +@table @asis +@findex clone +@cindex shell, cloning +@cindex cloning the shell +@cindex terminal +@item @t{clone} @var{tty} +Creates a forked instance of the current shell, attached to the specified +@var{tty}. In the new shell, the @t{PID}, @t{PPID} and @t{TTY} special +parameters are changed appropriately. @t{$!} is set to zero in the new +shell, and to the new shell's PID in the original shell. + +@noindent +The return status of the builtin is zero in both shells if successful, +and non-zero on error. + +@noindent +The target of @t{clone} should be an unused terminal, such as an unused virtual +console or a virtual terminal created by + +@noindent +@example +xterm -e sh -c 'trap : INT QUIT TSTP; tty; + while :; do sleep 100000000; done' +@end example + +@noindent +Some words of explanation are warranted about this long xterm command +line: when doing clone on a pseudo-terminal, some other session +("session" meant as a unix session group, or SID) is already owning +the terminal. Hence the cloned zsh cannot acquire the pseudo-terminal +as a controlling tty. That means two things: + +@noindent +@itemize @bullet + +@item +the job control signals will go to the sh-started-by-xterm process +group (that's why we disable INT QUIT and TSTP with trap; otherwise +the while loop could get suspended or killed) +@item +the cloned shell will have job control disabled, and the job +control keys (control-C, control-\ and control-Z) will not work. +@end itemize + +@noindent +This does not apply when cloning to an @emph{unused} vc. + +@noindent +Cloning to a used (and unprepared) terminal will result in two +processes reading simultaneously from the same terminal, with +input bytes going randomly to either process. + +@noindent +@t{clone} is mostly useful as a shell built-in replacement for +openvt. + +@end table +@c (avoiding a yodl bug) +@node The zsh/compctl Module, The zsh/complete Module, The zsh/clone Module, Zsh Modules + +@section The zsh/compctl Module +@noindent +@c Yodl file: Zsh/mod_compctl.yo + +The @t{zsh/compctl} module makes available two builtin commands. @t{compctl}, +is the old, deprecated way to control completions for ZLE. See +@ref{Completion Using compctl}. +The other builtin command, @t{compcall} can be used in user-defined +completion widgets, see +@ref{Completion Widgets}. +@c (avoiding a yodl bug) +@node The zsh/complete Module, The zsh/complist Module, The zsh/compctl Module, Zsh Modules + +@section The zsh/complete Module +@noindent +@c Yodl file: Zsh/mod_complete.yo + +The @t{zsh/complete} module makes available several builtin commands which +can be used in user-defined completion widgets, see +@ref{Completion Widgets}. +@c (avoiding a yodl bug) +@node The zsh/complist Module, The zsh/computil Module, The zsh/complete Module, Zsh Modules + +@section The zsh/complist Module +@noindent +@c Yodl file: Zsh/mod_complist.yo + +@cindex completion, listing +@cindex completion, coloured listings +@cindex completion, scroll listings +The @t{zsh/complist} module offers three extensions to completion listings: +the ability to highlight matches in such a list, the ability to +scroll through long lists and a different style of menu completion. + +@noindent + +@subsection Colored completion listings +@noindent +Whenever one of the parameters @t{ZLS_COLORS} or @t{ZLS_COLOURS} is set +and the @t{zsh/complist} module is loaded or linked into the shell, +completion lists will be colored. Note, however, that @t{complist} will +not automatically be loaded if it is not linked in: on systems with +dynamic loading, `@t{zmodload zsh/complist}' is required. + +@noindent +@vindex ZLS_COLORS +@vindex ZLS_COLOURS +The parameters @t{ZLS_COLORS} and @t{ZLS_COLOURS} describe how matches +are highlighted. To turn on highlighting an empty value suffices, in +which case all the default values given below will be used. The format of +the value of these parameters is the same as used by the GNU version of the +@t{ls} command: a colon-separated list of specifications of the form +`@var{name}@t{=}@var{value}'. The @var{name} may be one of the following strings, +most of which specify file types for which the @var{value} will be used. +The strings and their default values are: + +@noindent +@table @asis +@item @t{no 0} +for normal text (i.e. when displaying something other than a matched file) + +@item @t{fi 0} +for regular files + +@item @t{di 32} +for directories + +@item @t{ln 36} +for symbolic links. If this has the special value @t{target}, +symbolic links are dereferenced and the target file used to +determine the display format. + +@item @t{pi 31} +for named pipes (FIFOs) + +@item @t{so 33} +for sockets + +@item @t{bd 44;37} +for block devices + +@item @t{cd 44;37} +for character devices + +@item @t{or} @var{none} +for a symlink to nonexistent file (default is the value defined for @t{ln}) + +@item @t{mi} @var{none} +for a non-existent file (default is the value defined for @t{fi}); this code +is currently not used + +@item @t{su 37;41} +for files with setuid bit set + +@item @t{sg 30;43} +for files with setgid bit set + +@item @t{tw 30;42} +for world writable directories with sticky bit set + +@item @t{ow 34;43} +for world writable directories without sticky bit set + +@item @t{sa} @var{none} +for files with an associated suffix alias; this is only tested +after specific suffixes, as described below + +@item @t{st 37;44} +for directories with sticky bit set but not world writable + +@item @t{ex 35} +for executable files + +@item @t{lc \e[} +for the left code (see below) + +@item @t{rc m} +for the right code + +@item @t{tc 0} +for the character indicating the file type printed after filenames if +the @t{LIST_TYPES} option is set + +@item @t{sp 0} +for the spaces printed after matches to align the next column + +@item @t{ec} @var{none} +for the end code + +@end table + +@noindent +Apart from these strings, the @var{name} may also be an asterisk +(`@t{*}') followed by any string. The @var{value} given for such a +string will be used for all files whose name ends with the string. +The @var{name} may also be an equals sign (`@t{=}') followed by a +pattern; the @t{EXTENDED_GLOB} option will be turned on for evaluation +of the pattern. The @var{value} given for this pattern will be used for all +matches (not just filenames) whose display string are matched by +the pattern. Definitions for the form with the leading equal sign take +precedence over the values defined for file types, which in turn take +precedence over the form with the leading asterisk (file extensions). + +@noindent +The leading-equals form also allows different parts of the displayed +strings to be colored differently. For this, the pattern has to use the +`@t{(#b)}' globbing flag and pairs of parentheses surrounding the +parts of the strings that are to be colored differently. In this case +the @var{value} may consist of more than one color code separated by +equal signs. The first code will be used for all parts for which no +explicit code is specified and the following codes will be used for +the parts matched by the sub-patterns in parentheses. For example, +the specification `@t{=(#b)(?)*(?)=0=3=7}' will be used for all +matches which are at least two characters long and will use +the code `@t{3}' for the first character, `@t{7}' for the last +character and `@t{0}' for the rest. + +@noindent +All three forms of @var{name} may be preceded by a pattern in +parentheses. If this is given, the @var{value} will be used +only for matches in groups whose names are matched by the pattern +given in the parentheses. For example, `@t{(g*)m*=43}' highlights all +matches beginning with `@t{m}' in groups whose names begin with +`@t{g}' using the color code `@t{43}'. In case of the `@t{lc}', +`@t{rc}', and `@t{ec}' codes, the group pattern is ignored. + +@noindent +Note also that all patterns are tried in the order in which they +appear in the parameter value until the first one matches which is +then used. Patterns may be matched against completions, descriptions +(possibly with spaces appended for padding), or lines consisting of a +completion followed by a description. For consistent coloring it may be +necessary to use more than one pattern or a pattern with backreferences. + +@noindent +When printing a match, the code prints the value of @t{lc}, the value +for the file-type or the last matching specification with a `@t{*}', +the value of @t{rc}, the string to display for the match itself, and +then the value of @t{ec} if that is defined or the values of @t{lc}, +@t{no}, and @t{rc} if @t{ec} is not defined. + +@noindent +The default values are ISO 6429 (ANSI) compliant and can be used on +vt100 compatible terminals such as @t{xterm}s. On monochrome terminals +the default values will have no visible effect. The @t{colors} +function from the contribution can be used to get associative arrays +containing the codes for ANSI terminals (see +@ref{Other Functions}). For example, after loading @t{colors}, one could use +`@t{$color[red]}' to get the code for foreground color red and +`@t{$color[bg-green]}' for the code for background color green. + +@noindent +If the completion system invoked by compinit is used, these +parameters should not be set directly because the system controls them +itself. Instead, the @t{list-colors} style should be used (see +@ref{Completion System Configuration}). + +@noindent + +@subsection Scrolling in completion listings +@noindent +To enable scrolling through a completion list, the @t{LISTPROMPT} +parameter must be set. Its value will be used as the prompt; if it +is the empty string, a default prompt will be used. The value may +contain escapes of the form `@t{%x}'. It supports the escapes +`@t{%B}', `@t{%b}', `@t{%S}', `@t{%s}', `@t{%U}', `@t{%u}', `@t{%F}', +`@t{%f}', `@t{%K}', `@t{%k}' and +`@t{%@{}@var{...}@t{%@}}' used also in shell prompts as well as three pairs of +additional sequences: a `@t{%l}' or `@t{%L}' is replaced by the number +of the last line shown and the total number of lines in the form +`@var{number}@t{/}@var{total}'; a `@t{%m}' or `@t{%M}' is replaced with +the number of the last match shown and the total number of matches; and +`@t{%p}' or `@t{%P}' is replaced with `@t{Top}', `@t{Bottom}' or the +position of the first line shown in percent of the total number of +lines, respectively. In each of these cases the form with the uppercase +letter will be replaced with a string of fixed width, padded to the +right with spaces, while the lowercase form will not be padded. + +@noindent +If the parameter @t{LISTPROMPT} is set, the completion code will not ask if +the list should be shown. Instead it immediately starts displaying the +list, stopping after the first screenful, showing the prompt at the bottom, +waiting for a keypress after temporarily switching to the @t{listscroll} +keymap. Some of the zle functions have a special meaning while scrolling +lists: + +@noindent +@table @asis +@item @t{send-break} +stops listing discarding the key pressed + +@item @t{accept-line}, @t{down-history}, @t{down-line-or-history} +@itemx @t{down-line-or-search}, @t{vi-down-line-or-history} +scrolls forward one line + +@item @t{complete-word}, @t{menu-complete}, @t{expand-or-complete} +@itemx @t{expand-or-complete-prefix}, @t{menu-complete-or-expand} +scrolls forward one screenful + +@item @t{accept-search} +stop listing but take no other action + +@end table + +@noindent +Every other character stops listing and immediately processes the key +as usual. Any key that is not bound in the @t{listscroll} keymap or +that is bound to @t{undefined-key} is looked up in the keymap +currently selected. + +@noindent +As for the @t{ZLS_COLORS} and @t{ZLS_COLOURS} parameters, +@t{LISTPROMPT} should not be set directly when using the shell +function based completion system. Instead, the @t{list-prompt} style +should be used. + +@noindent + +@subsection Menu selection +@noindent +@cindex completion, selecting by cursor +@vindex MENUSELECT +@tindex menu-select +The @t{zsh/complist} module also offers an alternative style of selecting +matches from a list, called menu selection, which can be used if the +shell is set up to return to the last prompt after showing a +completion list (see the @t{ALWAYS_LAST_PROMPT} option in +@ref{Options}). + +@noindent +Menu selection can be invoked directly by +the widget @t{menu-select} defined by this module. This is a standard +ZLE widget that can be bound to a key in the usual way as described +in @ref{Zsh Line Editor}. + +@noindent +Alternatively, +the parameter @t{MENUSELECT} can be set to an integer, which gives the +minimum number of matches that must be present before menu selection is +automatically turned on. This second method requires that menu completion +be started, either directly from a widget such as @t{menu-complete}, or due +to one of the options @t{MENU_COMPLETE} or @t{AUTO_MENU} being set. If +@t{MENUSELECT} is set, but is 0, 1 or empty, menu selection will always be +started during an ambiguous menu completion. + +@noindent +When using the completion system based on shell functions, the +@t{MENUSELECT} parameter should not be used (like the @t{ZLS_COLORS} +and @t{ZLS_COLOURS} parameters described above). Instead, the @t{menu} +style should be used with the @t{select=}@var{...} keyword. + +@noindent +After menu selection is started, the matches will be listed. If there +are more matches than fit on the screen, only the first screenful is +shown. The +matches to insert into the command line can be selected from this +list. In the list one match is highlighted using the value for @t{ma} +from the @t{ZLS_COLORS} or @t{ZLS_COLOURS} parameter. The default +value for this is `@t{7}' which forces the selected match to be +highlighted using standout mode on a vt100-compatible terminal. If +neither @t{ZLS_COLORS} nor @t{ZLS_COLOURS} is set, the same terminal +control sequence as for the `@t{%S}' escape in prompts is used. + +@noindent +If there are more matches than fit on the screen and the parameter +@t{MENUPROMPT} is set, its value will be shown below the matches. It +supports the same escape sequences as @t{LISTPROMPT}, but the number +of the match or line shown will be that of the one where the mark is +placed. If its value is the empty string, a default prompt will be +used. + +@noindent +The @t{MENUSCROLL} parameter can be used to specify how the list is +scrolled. If the parameter is unset, this is done line by line, if it +is set to `@t{0}' (zero), the list will scroll half the number of +lines of the screen. If the value is positive, it gives the number of +lines to scroll and if it is negative, the list will be scrolled +the number of lines of the screen minus the (absolute) value. + +@noindent +As for the @t{ZLS_COLORS}, @t{ZLS_COLOURS} and @t{LISTPROMPT} +parameters, neither @t{MENUPROMPT} nor @t{MENUSCROLL} should be +set directly when using the shell function based completion +system. Instead, the @t{select-prompt} and @t{select-scroll} styles +should be used. + +@noindent +The completion code sometimes decides not to show all of the matches +in the list. These hidden matches are either matches for which the +completion function which added them explicitly requested that they +not appear in the list (using the @t{-n} option of the @t{compadd} +builtin command) or they are matches which duplicate a string already +in the list (because they differ only in things like prefixes or +suffixes that are not displayed). In the list used for menu selection, +however, even these matches are shown so that it is possible to select +them. To highlight such matches the @t{hi} and @t{du} capabilities in +the @t{ZLS_COLORS} and @t{ZLS_COLOURS} parameters are supported for +hidden matches of the first and second kind, respectively. + +@noindent +Selecting matches is done by moving the mark around using the zle movement +functions. When not all matches can be shown on the screen at the same +time, the list will scroll up and down when crossing the top or +bottom line. The following zle functions have special meaning during +menu selection. Note that the following always +perform the same task within the menu selection map and cannot be +replaced by user defined widgets, nor can the set of functions +be extended: + +@noindent +@table @asis +@item @t{accept-line}, @t{accept-search} +accept the current match and leave menu selection (but do +not cause the command line to be accepted) + +@item @t{send-break} +leaves menu selection and restores the previous contents of the +command line + +@item @t{redisplay}, @t{clear-screen} +execute their normal function without leaving menu selection + +@item @t{accept-and-hold}, @t{accept-and-menu-complete} +accept the currently inserted match and continue selection allowing to +select the next match to insert into the line + +@item @t{accept-and-infer-next-history} +accepts the current match and then tries completion with +menu selection again; in the case of files this allows one to select +a directory and immediately attempt to complete files in it; if there +are no matches, a message is shown and one can use @t{undo} to go back +to completion on the previous level, every other key leaves menu +selection (including the other zle functions which are otherwise +special during menu selection) + +@item @t{undo} +removes matches inserted during the menu selection by one of the three +functions before + +@item @t{down-history}, @t{down-line-or-history} +@itemx @t{vi-down-line-or-history}, @t{down-line-or-search} +moves the mark one line down + +@item @t{up-history}, @t{up-line-or-history} +@itemx @t{vi-up-line-or-history}, @t{up-line-or-search} +moves the mark one line up + +@item @t{forward-char}, @t{vi-forward-char} +moves the mark one column right + +@item @t{backward-char}, @t{vi-backward-char} +moves the mark one column left + +@item @t{forward-word}, @t{vi-forward-word} +@itemx @t{vi-forward-word-end}, @t{emacs-forward-word} +moves the mark one screenful down + +@item @t{backward-word}, @t{vi-backward-word}, @t{emacs-backward-word} +moves the mark one screenful up + +@item @t{vi-forward-blank-word}, @t{vi-forward-blank-word-end} +moves the mark to the first line of the next group of matches + +@item @t{vi-backward-blank-word} +moves the mark to the last line of the previous group of matches + +@item @t{beginning-of-history} +moves the mark to the first line + +@item @t{end-of-history} +moves the mark to the last line + +@item @t{beginning-of-buffer-or-history}, @t{beginning-of-line} +@itemx @t{beginning-of-line-hist}, @t{vi-beginning-of-line} +moves the mark to the leftmost column + +@item @t{end-of-buffer-or-history}, @t{end-of-line} +@itemx @t{end-of-line-hist}, @t{vi-end-of-line} +moves the mark to the rightmost column + +@item @t{complete-word}, @t{menu-complete}, @t{expand-or-complete} +@itemx @t{expand-or-complete-prefix}, @t{menu-expand-or-complete} +moves the mark to the next match + +@item @t{reverse-menu-complete} +moves the mark to the previous match + +@item @t{vi-insert} +this toggles between normal and interactive mode; in interactive mode +the keys bound to @t{self-insert} and @t{self-insert-unmeta} insert +into the command line as in normal editing mode but without leaving +menu selection; after each character completion is tried again and the +list changes to contain only the new matches; the completion widgets +make the longest unambiguous string be inserted in the command line +and @t{undo} and @t{backward-delete-char} go back to the previous set +of matches + +@item @t{history-incremental-search-forward} +@itemx @t{history-incremental-search-backward} +this starts incremental searches in the list of completions displayed; +in this mode, @t{accept-line} only leaves incremental search, going +back to the normal menu selection mode + +@end table + +@noindent +All movement functions wrap around at the edges; any other zle function not +listed leaves menu selection and executes that function. It is possible to +make widgets in the above list do the same by using the form of the widget +with a `@t{.}' in front. For example, the widget `@t{.accept-line}' has +the effect of leaving menu selection and accepting the entire command line. + +@noindent +During this selection the widget uses the keymap @t{menuselect}. Any +key that is not defined in this keymap or that is bound to +@t{undefined-key} is looked up in the keymap currently selected. This +is used to ensure that the most important keys used during selection +(namely the cursor keys, return, and TAB) have sensible defaults. However, +keys in the @t{menuselect} keymap can be modified directly using the +@t{bindkey} builtin command (see +@ref{The zsh/zle Module}). For example, to make the return key leave menu selection without +accepting the match currently selected one could call + +@noindent +@example +bindkey -M menuselect '^M' send-break +@end example + +@noindent +after loading the @t{zsh/complist} module. +@c (avoiding a yodl bug) +@node The zsh/computil Module, The zsh/curses Module, The zsh/complist Module, Zsh Modules + +@section The zsh/computil Module +@noindent +@c Yodl file: Zsh/mod_computil.yo + +@cindex completion, utility +The @t{zsh/computil} module adds several builtin commands that are used by +some of the completion functions in the completion system based on shell +functions (see +@ref{Completion System} +). Except for @t{compquote} these builtin commands are very +specialised and thus not very interesting when writing your own +completion functions. In summary, these builtin commands are: + +@noindent +@table @asis +@findex comparguments +@item @t{comparguments} +This is used by the @t{_arguments} function to do the argument and +command line parsing. Like @t{compdescribe} it has an option @t{-i} to +do the parsing and initialize some internal state and various options +to access the state information to decide what should be completed. + +@findex compdescribe +@item @t{compdescribe} +This is used by the @t{_describe} function to build the displays for +the matches and to get the strings to add as matches with their +options. On the first call one of the options @t{-i} or @t{-I} should be +supplied as the first argument. In the first case, display strings without +the descriptions will be generated, in the second case, the string used to +separate the matches from their descriptions must be given as the +second argument and the descriptions (if any) will be shown. All other +arguments are like the definition arguments to @t{_describe} itself. + +@noindent +Once @t{compdescribe} has been called with either the @t{-i} or the +@t{-I} option, it can be repeatedly called with the @t{-g} option and +the names of four parameters as its arguments. This will step through +the different sets of matches and store the value of @t{compstate[list]} +in the first scalar, the options for @t{compadd} in the second array, +the matches in the third array, and the strings to be displayed in the +completion listing in the fourth array. The arrays may then be directly +given to @t{compadd} to register the matches with the completion code. + +@findex compfiles +@item @t{compfiles} +Used by the @t{_path_files} function to optimize complex recursive +filename generation (globbing). It does three things. With the +@t{-p} and @t{-P} options it builds the glob patterns to use, +including the paths already handled and trying to optimize the +patterns with respect to the prefix and suffix from the line and the +match specification currently used. The @t{-i} option does the +directory tests for the @t{ignore-parents} style and the @t{-r} option +tests if a component for some of the matches are equal to the string +on the line and removes all other matches if that is true. + +@findex compgroups +@item @t{compgroups} +Used by the @t{_tags} function to implement the internals of the +@t{group-order} style. This only takes its arguments as names of +completion groups and creates the groups for it (all six types: sorted +and unsorted, both without removing duplicates, with removing all +duplicates and with removing consecutive duplicates). + +@findex compquote +@item @t{compquote} [ @t{-p} ] @var{names} ... +There may be reasons to write completion functions that have to add +the matches using the @t{-Q} option to @t{compadd} and perform quoting +themselves. Instead of interpreting the first character of the +@t{all_quotes} key of the @t{compstate} special association and using +the @t{q} flag for parameter expansions, one can use this builtin +command. The arguments are the names of scalar or array parameters +and the values of these parameters are quoted as needed for the +innermost quoting level. If the @t{-p} option is given, quoting is +done as if there is some prefix before the values of the parameters, +so that a leading equal sign will not be quoted. + +@noindent +The return status is non-zero in case of an error and zero otherwise. + +@findex comptags +@findex comptry +@item @t{comptags} +@itemx @t{comptry} +These implement the internals of the tags mechanism. + +@findex compvalues +@item @t{compvalues} +Like @t{comparguments}, but for the @t{_values} function. + +@end table +@c (avoiding a yodl bug) +@node The zsh/curses Module, The zsh/datetime Module, The zsh/computil Module, Zsh Modules + +@section The zsh/curses Module +@noindent +@c Yodl file: Zsh/mod_curses.yo + +The @t{zsh/curses} module makes available one builtin command and +various parameters. + +@noindent + +@subsection Builtin +@noindent + +@noindent +@table @asis +@findex zcurses +@cindex windows, curses +@item @t{zcurses} @t{init} +@itemx @t{zcurses} @t{end} +@itemx @t{zcurses} @t{addwin} @var{targetwin} @var{nlines} @var{ncols} @var{begin_y} @var{begin_x} [ @var{parentwin} ] +@itemx @t{zcurses} @t{delwin} @var{targetwin} +@itemx @t{zcurses} @t{refresh} [ @var{targetwin} ... ] +@itemx @t{zcurses} @t{touch} @var{targetwin} ... +@itemx @t{zcurses} @t{move} @var{targetwin} @var{new_y} @var{new_x} +@itemx @t{zcurses} @t{clear} @var{targetwin} [ @t{redraw} | @t{eol} | @t{bot} ] +@itemx @t{zcurses} @t{position} @var{targetwin} @var{array} +@itemx @t{zcurses} @t{char} @var{targetwin} @var{character} +@itemx @t{zcurses} @t{string} @var{targetwin} @var{string} +@itemx @t{zcurses} @t{border} @var{targetwin} @var{border} +@itemx @t{zcurses} @t{attr} @var{targetwin} [ [@t{+}|@t{-}]@var{attribute} | @var{fg_col}@t{/}@var{bg_col} ] [...] +@itemx @t{zcurses} @t{bg} @var{targetwin} [ [@t{+}|@t{-}]@var{attribute} | @var{fg_col}@t{/}@var{bg_col} | @t{@@}@var{char} ] [...] +@itemx @t{zcurses} @t{scroll} @var{targetwin} [ @t{on} | @t{off} | [@t{+}|@t{-}]@var{lines} ] +@itemx @t{zcurses} @t{input} @var{targetwin} [ @var{param} [ @var{kparam} [ @var{mparam} ] ] ] +@itemx @t{zcurses} @t{mouse} [ @t{delay} @var{num} | [@t{+}|@t{-}]@t{motion} ] +@itemx @t{zcurses} @t{timeout} @var{targetwin} @var{intval} +@itemx @t{zcurses} @t{querychar} @var{targetwin} [ @var{param} ] +@itemx @t{zcurses} @t{resize} @var{height} @var{width} [ @t{endwin} | @t{nosave} | @t{endwin_nosave} ] +Manipulate curses windows. All uses of this command should be +bracketed by `@t{zcurses init}' to initialise use of curses, and +`@t{zcurses end}' to end it; omitting `@t{zcurses end}' can cause +the terminal to be in an unwanted state. + +@noindent +The subcommand @t{addwin} creates a window with @var{nlines} lines and +@var{ncols} columns. Its upper left corner will be placed at row +@var{begin_y} and column +@var{begin_x} of the screen. @var{targetwin} is a string and refers +to the name of a window that is not currently assigned. Note +in particular the curses convention that vertical values appear +before horizontal values. + +@noindent +If @t{addwin} is given an existing window as the final argument, the new +window is created as a subwindow of @var{parentwin}. This differs from an +ordinary new window in that the memory of the window contents is shared +with the parent's memory. Subwindows must be deleted before their parent. +Note that the coordinates of subwindows are relative to the screen, not +the parent, as with other windows. + +@noindent +Use the subcommand @t{delwin} to delete a window created with +@t{addwin}. Note that @t{end} does @emph{not} implicitly delete windows, +and that @t{delwin} does not erase the screen image of the window. + +@noindent +The window corresponding to the full visible screen is called +@t{stdscr}; it always exists after `@t{zcurses init}' and cannot +be delete with @t{delwin}. + +@noindent +The subcommand @t{refresh} will refresh window @var{targetwin}; this is +necessary to make any pending changes (such as characters you have +prepared for output with @t{char}) visible on the screen. @t{refresh} +without an argument causes the screen to be cleared and redrawn. +If multiple windows are given, the screen is updated once at the end. + +@noindent +The subcommand @t{touch} marks the @var{targetwin}s listed as changed. +This is necessary before @t{refresh}ing windows if a window that +was in front of another window (which may be @t{stdscr}) is deleted. + +@noindent +The subcommand @t{move} moves the cursor position in @var{targetwin} to +new coordinates @var{new_y} and @var{new_x}. Note that the +subcommand @t{string} (but not the subcommand @t{char}) advances the +cursor position over the characters added. + +@noindent +The subcommand @t{clear} erases the contents of @var{targetwin}. One +(and no more than one) of three options may be specified. With the +option @t{redraw}, in addition the next @t{refresh} of @var{targetwin} +will cause the screen to be cleared and repainted. With the option +@t{eol}, @var{targetwin} is only cleared to the end of the current cursor +line. With the option +@t{bot}, @var{targetwin} is cleared to the end of the window, i.e +everything to the right and below the cursor is cleared. + +@noindent +The subcommand @t{position} writes various positions associated with +@var{targetwin} into the array named @var{array}. +These are, in order: +@table @asis +@item - +The y and x coordinates of the cursor relative to the top left +of @var{targetwin} +@item - +The y and x coordinates of the top left of @var{targetwin} on the +screen +@item - +The size of @var{targetwin} in y and x dimensions. +@end table + +@noindent +Outputting characters and strings are achieved by @t{char} and @t{string} +respectively. + +@noindent +To draw a border around window @var{targetwin}, use @t{border}. Note +that the border is not subsequently handled specially: in other words, +the border is simply a set of characters output at the edge of the +window. Hence it can be overwritten, can scroll off the window, etc. + +@noindent +The subcommand @t{attr} will set @var{targetwin}'s attributes or +foreground/background color pair for any successive character output. +Each @var{attribute} given on the line may be prepended by a @t{+} to set +or a @t{-} to unset that attribute; @t{+} is assumed if absent. The +attributes supported are @t{blink}, @t{bold}, @t{dim}, @t{reverse}, +@t{standout}, and @t{underline}. + +@noindent +Each @var{fg_col}@t{/}@var{bg_col} attribute (to be read as +`@var{fg_col} on @var{bg_col}') sets the foreground and background color +for character output. The color @t{default} is sometimes available +(in particular if the library is ncurses), specifying the foreground +or background color with which the terminal started. The color pair +@t{default/default} is always available. To use more than the 8 named +colors (red, green, etc.) construct the @var{fg_col}@t{/}@var{bg_col} +pairs where @var{fg_col} and @var{bg_col} are decimal integers, e.g +@t{128/200}. The maximum color value is 254 if the terminal supports +256 colors. + +@noindent +@t{bg} overrides the color and other attributes of all characters in the +window. Its usual use is to set the background initially, but it will +overwrite the attributes of any characters at the time when it is called. +In addition to the arguments allowed with @t{attr}, an argument @t{@@}@var{char} +specifies a character to be shown in otherwise blank areas of the window. +Owing to limitations of curses this cannot be a multibyte character +(use of ASCII characters only is recommended). As the specified set +of attributes override the existing background, turning attributes +off in the arguments is not useful, though this does not cause an error. + +@noindent +The subcommand @t{scroll} can be used with @t{on} or @t{off} to enabled +or disable scrolling of a window when the cursor would otherwise move +below the window due to typing or output. It can also be used with a +positive or negative integer to scroll the window up or down the given +number of lines without changing the current cursor position (which +therefore appears to move in the opposite direction relative to the +window). In the second case, if scrolling is @t{off} it is temporarily +turned @t{on} to allow the window to be scrolled. + +@noindent +The subcommand @t{input} reads a single character from the window +without echoing it back. If @var{param} is supplied the character is +assigned to the parameter @var{param}, else it is assigned to the +parameter @t{REPLY}. + +@noindent +If both @var{param} and @var{kparam} are supplied, the key is read in +`keypad' mode. In this mode special keys such as function keys and +arrow keys return the name of the key in the parameter @var{kparam}. The +key names are the macros defined in the @t{curses.h} or @t{ncurses.h} +with the prefix `@t{KEY_}' removed; see also the description of the +parameter @t{zcurses_keycodes} below. Other keys cause a value to be +set in @var{param} as before. On a successful return only one of +@var{param} or @var{kparam} contains a non-empty string; the other is set +to an empty string. + +@noindent +If @var{mparam} is also supplied, @t{input} attempts to handle mouse +input. This is only available with the ncurses library; mouse handling +can be detected by checking for the exit status of `@t{zcurses mouse}' with +no arguments. If a mouse +button is clicked (or double- or triple-clicked, or pressed or released with +a configurable delay from being clicked) then @t{kparam} is set to the string +@t{MOUSE}, and @var{mparam} is set to an array consisting of the +following elements: +@table @asis +@item - +An identifier to discriminate different input devices; this +is only rarely useful. +@item - +The x, y and z coordinates of the mouse click relative to +the full screen, as three elements in that order (i.e. the y coordinate +is, unusually, after the x coordinate). The z coordinate is only +available for a few unusual input devices and is otherwise set to zero. +@item - +Any events that occurred as separate items; usually +there will be just one. An event consists of @t{PRESSED}, @t{RELEASED}, +@t{CLICKED}, @t{DOUBLE_CLICKED} or @t{TRIPLE_CLICKED} followed +immediately (in the same element) by the number of the button. +@item - +If the shift key was pressed, the string @t{SHIFT}. +@item - +If the control key was pressed, the string @t{CTRL}. +@item - +If the alt key was pressed, the string @t{ALT}. +@end table + +@noindent +Not all mouse events may be passed through to the terminal window; +most terminal emulators handle some mouse events themselves. Note +that the ncurses manual implies that using input both with and +without mouse handling may cause the mouse cursor to appear and +disappear. + +@noindent +The subcommand @t{mouse} can be used to configure the use of the mouse. +There is no window argument; mouse options are global. +`@t{zcurses mouse}' with no arguments returns status 0 if mouse handling +is possible, else status 1. Otherwise, the possible arguments (which +may be combined on the same command line) are as follows. +@t{delay} @var{num} sets the maximum delay in milliseconds between press and +release events to be considered as a click; the value 0 disables click +resolution, and the default is one sixth of a second. @t{motion} proceeded +by an optional `@t{+}' (the default) or @t{-} turns on or off +reporting of mouse motion in addition to clicks, presses and releases, +which are always reported. However, it appears reports for mouse +motion are not currently implemented. + +@noindent +The subcommand @t{timeout} specifies a timeout value for input from +@var{targetwin}. If @var{intval} is negative, `@t{zcurses input}' waits +indefinitely for a character to be typed; this is the default. If +@var{intval} is zero, `@t{zcurses input}' returns immediately; if there +is typeahead it is returned, else no input is done and status 1 is +returned. If @var{intval} is positive, `@t{zcurses input}' waits +@var{intval} milliseconds for input and if there is none at the end of +that period returns status 1. + +@noindent +The subcommand @t{querychar} queries the character at the current cursor +position. The return values are stored in the array named @var{param} if +supplied, else in the array @t{reply}. The first value is the character +(which may be a multibyte character if the system supports them); the +second is the color pair in the usual @var{fg_col}@t{/}@var{bg_col} +notation, or @t{0} if color is not supported. Any attributes other than +color that apply to the character, as set with the subcommand @t{attr}, +appear as additional elements. + +@noindent +The subcommand @t{resize} resizes @t{stdscr} and all windows to given +dimensions (windows that stick out from the new dimensions are resized +down). The underlying curses extension (@t{resize_term call}) can be +unavailable. To verify, zeroes can be used for @var{height} and +@var{width}. If the result of the subcommand is @t{0}, resize_term is +available (@t{2} otherwise). Tests show that resizing can be normally +accomplished by calling @t{zcurses end} and @t{zcurses refresh}. The +@t{resize} subcommand is provided for versatility. Multiple system +configurations have been checked and @t{zcurses end} and @t{zcurses +refresh} are still needed for correct terminal state after resize. To +invoke them with @t{resize}, use @var{endwin} argument. Using +@var{nosave} argument will cause new terminal state to not be saved +internally by @t{zcurses}. This is also provided for versatility and +should normally be not needed. + +@end table + +@noindent + +@subsection Parameters +@noindent + +@noindent +@table @asis +@vindex ZCURSES_COLORS +@item @t{ZCURSES_COLORS} +Readonly integer. The maximum number of colors the terminal +supports. This value is initialised by the curses library and is not +available until the first time @t{zcurses init} is run. + +@vindex ZCURSES_COLOR_PAIRS +@item @t{ZCURSES_COLOR_PAIRS} +Readonly integer. The maximum number of color pairs +@var{fg_col}@t{/}@var{bg_col} that may be defined in `@t{zcurses attr}' +commands; note this limit applies to all color pairs that have been +used whether or not they are currently active. This value is initialised +by the curses library and is not available until the first time @t{zcurses +init} is run. + +@vindex zcurses_attrs +@item @t{zcurses_attrs} +Readonly array. The attributes supported by @t{zsh/curses}; available +as soon as the module is loaded. + +@vindex zcurses_colors +@item @t{zcurses_colors} +Readonly array. The colors supported by @t{zsh/curses}; available +as soon as the module is loaded. + +@vindex zcurses_keycodes +@item @t{zcurses_keycodes} +Readonly array. The values that may be returned in the second +parameter supplied to `@t{zcurses input}' in the order in which they +are defined internally by curses. Not all function keys +are listed, only @t{F0}; curses reserves space for @t{F0} up to @t{F63}. + +@vindex zcurses_windows +@item @t{zcurses_windows} +Readonly array. The current list of windows, i.e. all windows that +have been created with `@t{zcurses addwin}' and not removed with +`@t{zcurses delwin}'. + +@end table +@c (avoiding a yodl bug) +@node The zsh/datetime Module, The zsh/db/gdbm Module, The zsh/curses Module, Zsh Modules + +@section The zsh/datetime Module +@noindent +@c Yodl file: Zsh/mod_datetime.yo + +The @t{zsh/datetime} module makes available one builtin command: + +@noindent +@table @asis +@findex strftime +@cindex date string, printing +@item @t{strftime} [ @t{-s} @var{scalar} ] @var{format} [ @var{epochtime} [ @var{nanoseconds} ] ] +@itemx @t{strftime} @t{-r} [ @t{-q} ] [ @t{-s} @var{scalar} ] @var{format} @var{timestring} +Output the date in the @var{format} specified. With no @var{epochtime}, the +current system date/time is used; optionally, @var{epochtime} may be used to +specify the number of seconds since the epoch, and @var{nanoseconds} may +additionally be used to specify the number of nanoseconds past the second +(otherwise that number is assumed to be 0). +See man page strftime(3) for details. The zsh extensions described in +@ref{Prompt Expansion} are also available. + +@noindent +@table @asis +@item @t{-q} +Run quietly; suppress printing of all error messages described below. +Errors for invalid @var{epochtime} values are always printed. + +@item @t{-r} +With the option @t{-r} (reverse), use @var{format} to parse the input +string @var{timestring} and output the number of seconds since the epoch at +which the time occurred. The parsing is implemented by the system +function @t{strptime}; see man page strptime(3). This means that zsh +format extensions are not available, but for reverse lookup they are not +required. + +@noindent +In most implementations of @t{strftime} any timezone in the +@var{timestring} is ignored and the local timezone declared by the @t{TZ} +environment variable is used; other parameters are set to zero if not +present. + +@noindent +If @var{timestring} does not match @var{format} the command returns status 1 +and prints an error message. If @var{timestring} matches @var{format} but +not all characters in @var{timestring} were used, the conversion succeeds +but also prints an error message. + +@noindent +If either of the system functions @t{strptime} or @t{mktime} is not +available, status 2 is returned and an error message is printed. + +@item @t{-s} @var{scalar} +Assign the date string (or epoch time in seconds if @t{-r} is given) to +@var{scalar} instead of printing it. + +@end table + +@noindent +Note that depending on the system's declared integral time type, +@t{strftime} may produce incorrect results for epoch times greater than +2147483647 which corresponds to 2038-01-19 03:14:07 +0000. + +@end table + +@noindent +The @t{zsh/datetime} module makes available several parameters; +all are readonly: + +@noindent +@table @asis +@vindex EPOCHREALTIME +@item @t{EPOCHREALTIME} +A floating point value representing the number of seconds since +the epoch. The notional accuracy is to nanoseconds if the +@t{clock_gettime} call is available and to microseconds otherwise, +but in practice the range of double precision floating point and +shell scheduling latencies may be significant effects. + +@vindex EPOCHSECONDS +@item @t{EPOCHSECONDS} +An integer value representing the number of seconds since the +epoch. + +@vindex epochtime +@item @t{epochtime} +An array value containing the number of seconds since the epoch +in the first element and the remainder of the time since the epoch +in nanoseconds in the second element. To ensure the two elements +are consistent the array should be copied or otherwise referenced +as a single substitution before the values are used. The following +idiom may be used: + +@noindent +@example +for secs nsecs in $epochtime; do + ... +done +@end example + +@noindent + +@end table +@c (avoiding a yodl bug) +@node The zsh/db/gdbm Module, The zsh/deltochar Module, The zsh/datetime Module, Zsh Modules + +@section The zsh/db/gdbm Module +@noindent +@c Yodl file: Zsh/mod_db_gdbm.yo + +The @t{zsh/db/gdbm} module is used to create "tied" associative arrays +that interface to database files. If the GDBM interface is not available, +the builtins defined by this module will report an error. This module is +also intended as a prototype for creating additional database interfaces, +so the @t{ztie} builtin may move to a more generic module in the future. + +@noindent +The builtins in this module are: + +@noindent +@table @asis +@findex ztie +@cindex database tied array, creating +@item @t{ztie -d db/gdbm -f} @var{filename} [ @t{-r} ] @var{arrayname} +Open the GDBM database identified by @var{filename} and, if successful, +create the associative array @var{arrayname} linked to the file. To create +a local tied array, the parameter must first be declared, so commands +similar to the following would be executed inside a function scope: + +@noindent +@example +local -A sampledb +ztie -d db/gdbm -f sample.gdbm sampledb +@end example + +@noindent +The @t{-r} option opens the database file for reading only, creating a +parameter with the readonly attribute. Without this option, using +`@t{ztie}' on a file for which the user does not have write permission is +an error. If writable, the database is opened synchronously so fields +changed in @var{arrayname} are immediately written to @var{filename}. + +@noindent +Changes to the file modes @var{filename} after it has been opened do not +alter the state of @var{arrayname}, but `@t{typeset -r} @var{arrayname}' +works as expected. + +@findex zuntie +@cindex database tied array, destroying +@item @t{zuntie} [ @t{-u} ] @var{arrayname} ... +Close the GDBM database associated with each @var{arrayname} and then +unset the parameter. The @t{-u} option forces an unset of parameters +made readonly with `@t{ztie -r}'. + +@noindent +This happens automatically if the parameter is explicitly unset or its +local scope (function) ends. Note that a readonly parameter may not be +explicitly unset, so the only way to unset a global parameter created with +`@t{ztie -r}' is to use `@t{zuntie -u}'. + +@findex zgdbmpath +@cindex database file path, reading +@item @t{zgdbmpath} @var{parametername} +Put path to database file assigned to @var{parametername} into @t{REPLY} +scalar. + +@findex zgdbm_tied +@cindex database tied arrays, enumerating +@item @t{zgdbm_tied} +Array holding names of all tied parameters. + +@end table + +@noindent +The fields of an associative array tied to GDBM are neither cached nor +otherwise stored in memory, they are read from or written to the database +on each reference. Thus, for example, the values in a readonly array may +be changed by a second writer of the same database file. +@c (avoiding a yodl bug) +@node The zsh/deltochar Module, The zsh/example Module, The zsh/db/gdbm Module, Zsh Modules + +@section The zsh/deltochar Module +@noindent +@c Yodl file: Zsh/mod_deltochar.yo + +The @t{zsh/deltochar} module makes available two ZLE functions: + +@noindent +@table @asis +@tindex delete-to-char +@item @t{delete-to-char} +Read a character from the keyboard, and +delete from the cursor position up to and including the next +(or, with repeat count @var{n}, the @var{n}th) instance of that character. +Negative repeat counts mean delete backwards. + +@tindex zap-to-char +@item @t{zap-to-char} +This behaves like @t{delete-to-char}, except that the final occurrence of +the character itself is not deleted. + +@end table +@c (avoiding a yodl bug) +@node The zsh/example Module, The zsh/files Module, The zsh/deltochar Module, Zsh Modules + +@section The zsh/example Module +@noindent +@c Yodl file: Zsh/mod_example.yo + +The @t{zsh/example} module makes available one builtin command: + +@noindent +@table @asis +@findex example +@cindex modules, example +@cindex modules, writing +@cindex writing modules +@item @t{example} [ @t{-flags} ] [ @var{args} ... ] +Displays the flags and arguments it is invoked with. + +@end table + +@noindent +The purpose of the module is to serve as an example of how to write a +module. +@c (avoiding a yodl bug) +@node The zsh/files Module, The zsh/langinfo Module, The zsh/example Module, Zsh Modules + +@section The zsh/files Module +@noindent +@c Yodl file: Zsh/mod_files.yo + +@cindex files, manipulating +The @t{zsh/files} module makes available some common commands for file +manipulation as builtins; these commands are probably not needed for +many normal situations but can be useful in emergency recovery +situations with constrained resources. The commands do not implement +all features now required by relevant standards committees. + +@noindent +For all commands, a variant beginning @t{zf_} is also available and loaded +automatically. Using the features capability of zmodload will let you load +only those names you want. Note that it's possible to load only the +builtins with zsh-specific names using the following command: + +@noindent +@example +zmodload -m -F zsh/files b:zf_\* +@end example + +@noindent +The commands loaded by default are: + +@noindent +@table @asis +@findex chgrp +@item @t{chgrp} [ @t{-hRs} ] @var{group} @var{filename} ... +Changes group of files specified. This is equivalent to @t{chown} with +a @var{user-spec} argument of `@t{:}@var{group}'. + +@findex chmod +@item @t{chmod} [ @t{-Rs} ] @var{mode} @var{filename} ... +Changes mode of files specified. + +@noindent +The specified @var{mode} must be in octal. + +@noindent +The @t{-R} option causes @t{chmod} to recursively descend into directories, +changing the mode of all files in the directory after +changing the mode of the directory itself. + +@noindent +The @t{-s} option is a zsh extension to @t{chmod} functionality. It enables +paranoid behaviour, intended to avoid security problems involving +a @t{chmod} being tricked into affecting files other than the ones +intended. It will refuse to follow symbolic links, so that (for example) +@value{dsbq}@t{chmod 600 /tmp/foo/passwd}@value{dsq} can't accidentally chmod @t{/etc/passwd} +if @t{/tmp/foo} happens to be a link to @t{/etc}. It will also check +where it is after leaving directories, so that a recursive chmod of +a deep directory tree can't end up recursively chmoding @t{/usr} as +a result of directories being moved up the tree. + +@findex chown +@item @t{chown} [ @t{-hRs} ] @var{user-spec} @var{filename} ... +Changes ownership and group of files specified. + +@noindent +The @var{user-spec} can be in four forms: + +@noindent +@table @asis +@item @var{user} +change owner to @var{user}; do not change group +@item @var{user}@t{::} +change owner to @var{user}; do not change group +@item @var{user}@t{:} +change owner to @var{user}; change group to @var{user}'s primary group +@item @var{user}@t{:}@var{group} +change owner to @var{user}; change group to @var{group} +@item @t{:}@var{group} +do not change owner; change group to @var{group} +@end table + +@noindent +In each case, the `@t{:}' may instead be a `@t{.}'. The rule is that +if there is a `@t{:}' then the separator is `@t{:}', otherwise +if there is a `@t{.}' then the separator is `@t{.}', otherwise +there is no separator. + +@noindent +Each of @var{user} and @var{group} may be either a username (or group name, as +appropriate) or a decimal user ID (group ID). Interpretation as a name +takes precedence, if there is an all-numeric username (or group name). + +@noindent +If the target is a symbolic link, the @t{-h} option causes @t{chown} to set +the ownership of the link instead of its target. + +@noindent +The @t{-R} option causes @t{chown} to recursively descend into directories, +changing the ownership of all files in the directory after +changing the ownership of the directory itself. + +@noindent +The @t{-s} option is a zsh extension to @t{chown} functionality. It enables +paranoid behaviour, intended to avoid security problems involving +a @t{chown} being tricked into affecting files other than the ones +intended. It will refuse to follow symbolic links, so that (for example) +@value{dsbq}@t{chown luser /tmp/foo/passwd}@value{dsq} can't accidentally chown @t{/etc/passwd} +if @t{/tmp/foo} happens to be a link to @t{/etc}. It will also check +where it is after leaving directories, so that a recursive chown of +a deep directory tree can't end up recursively chowning @t{/usr} as +a result of directories being moved up the tree. + +@findex ln +@item @t{ln} [ @t{-dfhins} ] @var{filename} @var{dest} +@itemx @t{ln} [ @t{-dfhins} ] @var{filename} ... @var{dir} +Creates hard (or, with @t{-s}, symbolic) links. In the first form, the +specified @var{dest}ination is created, as a link to the specified +@var{filename}. In the second form, each of the @var{filename}s is +taken in turn, and linked to a pathname in the specified @var{dir}ectory +that has the same last pathname component. + +@noindent +Normally, @t{ln} will not attempt to create hard links to +directories. This check can be overridden using the @t{-d} option. +Typically only the super-user can actually succeed in creating +hard links to directories. +This does not apply to symbolic links in any case. + +@noindent +By default, existing files cannot be replaced by links. +The @t{-i} option causes the user to be queried about replacing +existing files. The @t{-f} option causes existing files to be +silently deleted, without querying. @t{-f} takes precedence. + +@noindent +The @t{-h} and @t{-n} options are identical and both exist for +compatibility; either one indicates that if the target is a symlink +then it should not be dereferenced. +Typically this is used in combination with @t{-sf} so that if an +existing link points to a directory then it will be removed, +instead of followed. +If this option is used with multiple filenames and the target +is a symbolic link pointing to a directory then the result is +an error. + +@findex mkdir +@item @t{mkdir} [ @t{-p} ] [ @t{-m} @var{mode} ] @var{dir} ... +Creates directories. With the @t{-p} option, non-existing parent +directories are first created if necessary, and there will be +no complaint if the directory already exists. +The @t{-m} option can be used to specify (in octal) a set of file permissions +for the created directories, otherwise mode 777 modified by the current +@t{umask} (see man page umask(2)) is used. + +@findex mv +@item @t{mv} [ @t{-fi} ] @var{filename} @var{dest} +@itemx @t{mv} [ @t{-fi} ] @var{filename} ... @var{dir} +Moves files. In the first form, the specified @var{filename} is moved +to the specified @var{dest}ination. In the second form, each of the +@var{filename}s is +taken in turn, and moved to a pathname in the specified @var{dir}ectory +that has the same last pathname component. + +@noindent +By default, the user will be queried before replacing any file +that the user cannot write to, but writable files will be silently +removed. +The @t{-i} option causes the user to be queried about replacing +any existing files. The @t{-f} option causes any existing files to be +silently deleted, without querying. @t{-f} takes precedence. + +@noindent +Note that this @t{mv} will not move files across devices. +Historical versions of @t{mv}, when actual renaming is impossible, +fall back on copying and removing files; if this behaviour is desired, +use @t{cp} and @t{rm} manually. This may change in a future version. + +@findex rm +@item @t{rm} [ @t{-dfiRrs} ] @var{filename} ... +Removes files and directories specified. + +@noindent +Normally, @t{rm} will not remove directories (except with the @t{-R} or @t{-r} +options). The @t{-d} option causes @t{rm} to try removing directories +with @t{unlink} (see man page unlink(2)), the same method used for files. +Typically only the super-user can actually succeed in unlinking +directories in this way. +@t{-d} takes precedence over @t{-R} and @t{-r}. + +@noindent +By default, the user will be queried before removing any file +that the user cannot write to, but writable files will be silently +removed. +The @t{-i} option causes the user to be queried about removing +any files. The @t{-f} option causes files to be +silently deleted, without querying, and suppresses all error indications. +@t{-f} takes precedence. + +@noindent +The @t{-R} and @t{-r} options cause @t{rm} to recursively descend into +directories, deleting all files in the directory before removing the directory +with the @t{rmdir} system call (see man page rmdir(2)). + +@noindent +The @t{-s} option is a zsh extension to @t{rm} functionality. It enables +paranoid behaviour, intended to avoid common security problems involving +a root-run @t{rm} being tricked into removing files other than the ones +intended. It will refuse to follow symbolic links, so that (for example) +@value{dsbq}@t{rm /tmp/foo/passwd}@value{dsq} can't accidentally remove @t{/etc/passwd} +if @t{/tmp/foo} happens to be a link to @t{/etc}. It will also check +where it is after leaving directories, so that a recursive removal of +a deep directory tree can't end up recursively removing @t{/usr} as +a result of directories being moved up the tree. + +@findex rmdir +@item @t{rmdir} @var{dir} ... +Removes empty directories specified. + +@findex sync +@item @t{sync} +Calls the system call of the same name (see man page sync(2)), which +flushes dirty buffers to disk. It might return before the I/O has +actually been completed. + +@end table +@c (avoiding a yodl bug) +@node The zsh/langinfo Module, The zsh/mapfile Module, The zsh/files Module, Zsh Modules + +@section The zsh/langinfo Module +@noindent +@c Yodl file: Zsh/mod_langinfo.yo + +The @t{zsh/langinfo} module makes available one parameter: + +@noindent +@table @asis +@vindex langinfo +@item @t{langinfo} +An associative array that maps langinfo elements to +their values. + +@noindent +Your implementation may support a number of the following keys: + +@noindent +@t{CODESET}, +@t{D_T_FMT}, +@t{D_FMT}, +@t{T_FMT}, +@t{RADIXCHAR}, +@t{THOUSEP}, +@t{YESEXPR}, +@t{NOEXPR}, +@t{CRNCYSTR}, +@t{ABDAY_@{1..7@}}, +@t{DAY_@{1..7@}}, +@t{ABMON_@{1..12@}}, +@t{MON_@{1..12@}}, +@t{T_FMT_AMPM}, +@t{AM_STR}, +@t{PM_STR}, +@t{ERA}, +@t{ERA_D_FMT}, +@t{ERA_D_T_FMT}, +@t{ERA_T_FMT}, +@t{ALT_DIGITS} + +@noindent + +@end table +@c (avoiding a yodl bug) +@node The zsh/mapfile Module, The zsh/mathfunc Module, The zsh/langinfo Module, Zsh Modules + +@section The zsh/mapfile Module +@noindent +@c Yodl file: Zsh/mod_mapfile.yo + +@cindex parameter, file access via +The @t{zsh/mapfile} module provides one special associative array parameter of +the same name. + +@noindent +@table @asis +@vindex mapfile +@item @t{mapfile} +This associative array takes as keys the names of files; the resulting +value is the content of the file. The value is treated identically to any +other text coming from a parameter. The value may also be assigned to, in +which case the file in question is written (whether or not it originally +existed); or an element may be unset, which will delete the file in +question. For example, `@t{vared mapfile[myfile]}' works as expected, +editing the file `@t{myfile}'. + +@noindent +When the array is accessed as a whole, the keys are the names of files in +the current directory, and the values are empty (to save a huge overhead in +memory). Thus @t{$@{(k)mapfile@}} has the same effect as the glob operator +@t{*(D)}, since files beginning with a dot are not special. Care must be +taken with expressions such as @t{rm $@{(k)mapfile@}}, which will delete +every file in the current directory without the usual `@t{rm *}' test. + +@noindent +The parameter @t{mapfile} may be made read-only; in that case, files +referenced may not be written or deleted. + +@noindent +A file may conveniently be read into an array as one line per element +with the form +`@var{array}@t{=("$@{(f@@)mapfile[}@var{filename}@t{]@}")}'. +The double quotes and the `@t{@@}' are necessary to prevent empty lines +from being removed. Note that if the file ends with a newline, +the shell will split on the final newline, generating an additional +empty field; this can be suppressed by using +`@var{array}@t{=("$@{(f@@)$@{mapfile[}@var{filename}@t{]%$'\n'@}@}")}'. + +@end table + +@noindent + +@subsection Limitations +@noindent + +@noindent +Although reading and writing of the file in question is efficiently +handled, zsh's internal memory management may be arbitrarily baroque; +however, @t{mapfile} is usually very much more efficient than +anything involving a loop. Note in particular that +the whole contents of the file will always reside physically in memory when +accessed (possibly multiple times, due to standard parameter substitution +operations). In particular, this means handling of sufficiently long files +(greater than the machine's swap space, or than the range of the pointer +type) will be incorrect. + +@noindent +No errors are printed or flagged for non-existent, unreadable, or +unwritable files, as the parameter mechanism is too low in the shell +execution hierarchy to make this convenient. + +@noindent +It is unfortunate that the mechanism for loading modules does not yet allow +the user to specify the name of the shell parameter to be given the special +behaviour. +@c (avoiding a yodl bug) +@node The zsh/mathfunc Module, The zsh/nearcolor Module, The zsh/mapfile Module, Zsh Modules + +@section The zsh/mathfunc Module +@noindent +@c Yodl file: Zsh/mod_mathfunc.yo + +@cindex functions, mathematical +@cindex mathematical functions +The @t{zsh/mathfunc} module provides standard +mathematical functions for use when +evaluating mathematical formulae. The syntax agrees with normal C and +FORTRAN conventions, for example, + +@noindent +@example +(( f = sin(0.3) )) +@end example + +@noindent +assigns the sine of 0.3 to the parameter f. + +@noindent +Most functions take floating point arguments and return a floating point +value. However, any necessary conversions from or to integer type will be +performed automatically by the shell. Apart from @t{atan} with a second +argument and the @t{abs}, @t{int} and @t{float} functions, all functions +behave as noted in the manual page for the corresponding C function, +except that any arguments out of range for the function in question will be +detected by the shell and an error reported. + +@noindent +The following functions take a single floating point argument: @t{acos}, +@t{acosh}, @t{asin}, @t{asinh}, @t{atan}, @t{atanh}, @t{cbrt}, @t{ceil}, +@t{cos}, @t{cosh}, @t{erf}, @t{erfc}, @t{exp}, @t{expm1}, @t{fabs}, +@t{floor}, @t{gamma}, @t{j0}, @t{j1}, @t{lgamma}, @t{log}, @t{log10}, +@t{log1p}, @t{log2}, @t{logb}, @t{sin}, @t{sinh}, @t{sqrt}, @t{tan}, +@t{tanh}, @t{y0}, @t{y1}. The @t{atan} function can optionally take a +second argument, in which case it behaves like the C function @t{atan2}. +The @t{ilogb} function takes a single floating point argument, but +returns an integer. + +@noindent +The function @t{signgam} takes no arguments, and returns an integer, which +is the C variable of the same name, as described in man page gamma(3). Note +that it is therefore only useful immediately after a call to @t{gamma} or +@t{lgamma}. Note also that `@t{signgam()}' and `@t{signgam}' are +distinct expressions. + +@noindent +The functions @t{min}, @t{max}, and @t{sum} are defined not in this module +but in the @t{zmathfunc} autoloadable function, described in +@ref{Mathematical Functions}. + +@noindent +The following functions take two floating point arguments: @t{copysign}, +@t{fmod}, @t{hypot}, @t{nextafter}. + +@noindent +The following take an integer first argument and a floating point second +argument: @t{jn}, @t{yn}. + +@noindent +The following take a floating point first argument and an integer second +argument: @t{ldexp}, @t{scalb}. + +@noindent +The function @t{abs} does not convert the type of its single argument; it +returns the absolute value of either a floating point number or an +integer. The functions @t{float} and @t{int} convert their arguments into +a floating point or integer value (by truncation) respectively. + +@noindent +Note that the C @t{pow} function is available in ordinary math evaluation +as the `@t{**}' operator and is not provided here. + +@noindent +The function @t{rand48} is available if your system's mathematical library +has the function @t{erand48(3)}. It returns a pseudo-random floating point +number between 0 and 1. It takes a single string optional argument. + +@noindent +If the argument is not present, the random number seed is initialised by +three calls to the @t{rand(3)} function --- this produces the +same random +numbers as the next three values of @t{$RANDOM}. + +@noindent +If the argument is present, it gives the name of a scalar parameter where +the current random number seed will be stored. On the first call, the +value must contain at least twelve hexadecimal digits (the remainder of the +string is ignored), or the seed will be initialised in the same manner as +for a call to @t{rand48} with no argument. Subsequent calls to +@t{rand48}(@var{param}) will then maintain the seed in the +parameter @var{param} as a string of twelve hexadecimal digits, with no base +signifier. The random number sequences for different parameters are +completely independent, and are also independent from that used by calls to +@t{rand48} with no argument. + +@noindent +For example, consider + +@noindent +@example +print $(( rand48(seed) )) +print $(( rand48() )) +print $(( rand48(seed) )) +@end example + +@noindent +Assuming @t{$seed} does not exist, it will be initialised by the first +call. In the second call, the default seed is initialised; note, however, +that because of the properties of @t{rand()} there is a +correlation between +the seeds used for the two initialisations, so for more secure uses, you +should generate your own 12-byte seed. The third call returns to the same +sequence of random numbers used in the first call, unaffected by the +intervening @t{rand48()}. +@c (avoiding a yodl bug) +@node The zsh/nearcolor Module, The zsh/newuser Module, The zsh/mathfunc Module, Zsh Modules + +@section The zsh/nearcolor Module +@noindent +@c Yodl file: Zsh/mod_nearcolor.yo + +The @t{zsh/nearcolor} module replaces colours specified as hex triplets +with the nearest colour in the 88 or 256 colour palettes that are widely +used by terminal emulators. By default, 24-bit true colour escape codes +are generated when colours are specified using hex triplets. These are +not supported by all terminals. The purpose of this module is to make +it easier to define colour preferences in a form that can work across a +range of terminal emulators. + +@noindent +Aside from the default colour, the ANSI standard for terminal escape +codes provides for eight colours. The bright attribute brings this to +sixteen. These basic colours are commonly used in terminal applications +due to being widely supported. Expanded 88 and 256 colour palettes are +also common and, while the first sixteen colours vary somewhat between +terminals and configurations, these add a generally consistent and +predictable set of colours. + +@noindent +In order to use the @t{zsh/nearcolor} module, it only needs to be +loaded. Thereafter, whenever a colour is specified using a hex triplet, +it will be compared against each of the available colours and the +closest will be selected. The first sixteen colours are never matched in +this process due to being unpredictable. + +@noindent +It isn't possible to reliably detect support for true colour in the +terminal emulator. It is therefore recommended to be selective in +loading the @t{zsh/nearcolor} module. For example, the following +checks the @t{COLORTERM} environment variable: + +@noindent +@example +[[ $COLORTERM = *(24bit|truecolor)* ]] || zmodload zsh/nearcolor +@end example + +@noindent +Note that some terminals accept the true color escape codes but map +them internally to a more limited palette in a similar manner to the +@t{zsh/nearcolor} module. +@c (avoiding a yodl bug) +@node The zsh/newuser Module, The zsh/parameter Module, The zsh/nearcolor Module, Zsh Modules + +@section The zsh/newuser Module +@noindent +@c Yodl file: Zsh/mod_newuser.yo + +The @t{zsh/newuser} module is loaded at boot if it is +available, the @t{RCS} option is set, and the @t{PRIVILEGED} option is not +set (all three are true by default). This takes +place immediately after commands in the global @t{zshenv} file (typically +@t{/etc/zshenv}), if any, have been executed. If the module is not +available it is silently ignored by the shell; the module may safely be +removed from @t{$MODULE_PATH} by the administrator if it is not required. + +@noindent +On loading, the module tests if any of the start-up files @t{.zshenv}, +@t{.zprofile}, @t{.zshrc} or @t{.zlogin} exist in the directory given by +the environment variable @t{ZDOTDIR}, or the user's home directory if that +is not set. The test is not performed and the module halts processing if +the shell was in an emulation mode (i.e. had been invoked as some other +shell than zsh). + +@noindent +If none of the start-up files were found, the module then looks for the +file @t{newuser} first in a sitewide directory, usually the parent +directory of the @t{site-functions} directory, and if that is not found the +module searches in a version-specific directory, usually the parent of the +@t{functions} directory containing version-specific functions. (These +directories can be configured when zsh is built using the +@t{--enable-site-scriptdir=}@var{dir} and @t{--enable-scriptdir=}@var{dir} +flags to @t{configure}, respectively; the defaults are +@var{prefix}@t{/share/zsh} and @var{prefix}@t{/share/zsh/$ZSH_VERSION} where +the default @var{prefix} is @t{/usr/local}.) + +@noindent +If the file @t{newuser} is found, it is then sourced in the same manner as +a start-up file. The file is expected to contain code to install start-up +files for the user, however any valid shell code will be executed. + +@noindent +The @t{zsh/newuser} module is then unconditionally unloaded. + +@noindent +Note that it is possible to achieve exactly the same effect as the +@t{zsh/newuser} module by adding code to @t{/etc/zshenv}. The module +exists simply to allow the shell to make arrangements for new users without +the need for intervention by package maintainers and system administrators. + +@noindent +The script supplied with the module invokes the shell function +@t{zsh-newuser-install}. This may be invoked directly by the user +even if the @t{zsh/newuser} module is disabled. Note, however, that +if the module is not installed the function will not be installed either. +The function is documented in +@ref{User Configuration Functions}. +@c (avoiding a yodl bug) +@node The zsh/parameter Module, The zsh/pcre Module, The zsh/newuser Module, Zsh Modules + +@section The zsh/parameter Module +@noindent +@c Yodl file: Zsh/mod_parameter.yo + +@cindex parameters, special +The @t{zsh/parameter} module gives access to some of the internal hash +tables used by the shell by defining some special parameters. + +@noindent +@table @asis +@vindex options +@item @t{options} +The keys for this associative array are the names of the options that +can be set and unset using the @t{setopt} and @t{unsetopt} +builtins. The value of each key is either the string @t{on} if the +option is currently set, or the string @t{off} if the option is unset. +Setting a key to one of these strings is like setting or unsetting +the option, respectively. Unsetting a key in this array is like +setting it to the value @t{off}. + +@vindex commands +@item @t{commands} +This array gives access to the command hash table. The keys are the +names of external commands, the values are the pathnames of the files +that would be executed when the command would be invoked. Setting a +key in this array defines a new entry in this table in the same way as +with the @t{hash} builtin. Unsetting a key as in `@t{unset +"commands[foo]"}' removes the entry for the given key from the command +hash table. + +@vindex functions +@item @t{functions} +This associative array maps names of enabled functions to their +definitions. Setting a key in it is like defining a function with the +name given by the key and the body given by the value. Unsetting a key +removes the definition for the function named by the key. + +@vindex dis_functions +@item @t{dis_functions} +Like @t{functions} but for disabled functions. + +@vindex functions_source +@item @t{functions_source} +This readonly associative array maps names of enabled functions to the +name of the file containing the source of the function. + +@noindent +For an autoloaded function that has already been loaded, or marked for +autoload with an absolute path, or that has had its path resolved with +`@t{functions -r}', this is the file found for autoloading, resolved +to an absolute path. + +@noindent +For a function defined within the body of a script or sourced file, +this is the name of that file. In this case, this is the exact path +originally used to that file, which may be a relative path. + +@noindent +For any other function, including any defined at an interactive prompt or +an autoload function whose path has not yet been resolved, this is +the empty string. However, the hash element is reported as defined +just so long as the function is present: the keys to this hash are +the same as those to @t{$functions}. + +@vindex dis_functions_source +@item @t{dis_functions_source} +Like @t{functions_source} but for disabled functions. + +@vindex builtins +@item @t{builtins} +This associative array gives information about the builtin commands +currently enabled. The keys are the names of the builtin commands and +the values are either `@t{undefined}' for builtin commands that will +automatically be loaded from a module if invoked or `@t{defined}' for +builtin commands that are already loaded. + +@vindex dis_builtins +@item @t{dis_builtins} +Like @t{builtins} but for disabled builtin commands. + +@vindex reswords +@item @t{reswords} +This array contains the enabled reserved words. + +@vindex dis_reswords +@item @t{dis_reswords} +Like @t{reswords} but for disabled reserved words. + +@vindex patchars +@item @t{patchars} +This array contains the enabled pattern characters. + +@vindex dis_patchars +@item @t{dis_patchars} +Like @t{patchars} but for disabled pattern characters. + +@vindex aliases +@item @t{aliases} +This maps the names of the regular aliases currently enabled to their +expansions. + +@vindex dis_aliases +@item @t{dis_aliases} +Like @t{aliases} but for disabled regular aliases. + +@vindex galiases +@item @t{galiases} +Like @t{aliases}, but for global aliases. + +@vindex dis_galiases +@item @t{dis_galiases} +Like @t{galiases} but for disabled global aliases. + +@vindex saliases +@item @t{saliases} +Like @t{raliases}, but for suffix aliases. + +@vindex dis_saliases +@item @t{dis_saliases} +Like @t{saliases} but for disabled suffix aliases. + +@vindex parameters +@item @t{parameters} +The keys in this associative array are the names of the parameters +currently defined. The values are strings describing the type of the +parameter, in the same format used by the @t{t} parameter flag, see +@ref{Parameter Expansion} +. +Setting or unsetting keys in this array is not possible. + +@vindex modules +@item @t{modules} +An associative array giving information about modules. The keys are the names +of the modules loaded, registered to be autoloaded, or aliased. The +value says which state the named module is in and is one of the +strings `@t{loaded}', `@t{autoloaded}', or `@t{alias:}@var{name}', +where @var{name} is the name the module is aliased to. + +@noindent +Setting or unsetting keys in this array is not possible. + +@vindex dirstack +@item @t{dirstack} +A normal array holding the elements of the directory stack. Note that +the output of the @t{dirs} builtin command includes one more +directory, the current working directory. + +@vindex history +@item @t{history} +This associative array maps history event numbers to the full history lines. +Although it is presented as an associative array, the array of all values +(@t{$@{history[@@]@}}) is guaranteed to be returned in order from most recent +to oldest history event, that is, by decreasing history event number. + +@vindex historywords +@item @t{historywords} +A special array containing the words stored in the history. These also +appear in most to least recent order. + +@vindex jobdirs +@item @t{jobdirs} +This associative array maps job numbers to the directories from which the +job was started (which may not be the current directory of the job). + +@noindent +The keys of the associative arrays are usually valid job numbers, +and these are the values output with, for example, @t{$@{(k)jobdirs@}}. +Non-numeric job references may be used when looking up a value; +for example, @t{$@{jobdirs[%+]@}} refers to the current job. + +@vindex jobtexts +@item @t{jobtexts} +This associative array maps job numbers to the texts of the command lines +that were used to start the jobs. + +@noindent +Handling of the keys of the associative array is as described for +@t{jobdirs} above. + +@vindex jobstates +@item @t{jobstates} +This associative array gives information about the states of the jobs +currently known. The keys are the job numbers and the values are +strings of the form +`@var{job-state}@t{:}@var{mark}@t{:}@var{pid}@t{=}@var{state}...'. The +@var{job-state} gives the state the whole job is currently in, one of +`@t{running}', `@t{suspended}', or `@t{done}'. The @var{mark} is +`@t{+}' for the current job, `@t{-}' for the previous job and empty +otherwise. This is followed by one `@t{:}@var{pid}@t{=}@var{state}' for every +process in the job. The @var{pid}s are, of course, the process IDs and +the @var{state} describes the state of that process. + +@noindent +Handling of the keys of the associative array is as described for +@t{jobdirs} above. + +@vindex nameddirs +@item @t{nameddirs} +This associative array maps the names of named directories to the pathnames +they stand for. + +@vindex userdirs +@item @t{userdirs} +This associative array maps user names to the pathnames of their home +directories. + +@vindex usergroups +@item @t{usergroups} +This associative array maps names of system groups of which the current +user is a member to the corresponding group identifiers. The contents +are the same as the groups output by the @t{id} command. + +@vindex funcfiletrace +@item @t{funcfiletrace} +This array contains the absolute line numbers and corresponding file +names for the point where the current function, sourced file, or (if +@t{EVAL_LINENO} is set) @t{eval} command was +called. The array is of the same length as @t{funcsourcetrace} and +@t{functrace}, but differs from @t{funcsourcetrace} in that the line and +file are the point of call, not the point of definition, and differs +from @t{functrace} in that all values are absolute line numbers in +files, rather than relative to the start of a function, if any. + +@vindex funcsourcetrace +@item @t{funcsourcetrace} +This array contains the file names and line numbers of the +points where the functions, sourced files, and (if @t{EVAL_LINENO} is set) +@t{eval} commands currently being executed were +defined. The line number is the line where the `@t{function} @var{name}' +or `@var{name} @t{()}' started. In the case of an autoloaded +function the line number is reported as zero. +The format of each element is @var{filename}@t{:}@var{lineno}. + +@noindent +For functions autoloaded from a file in native zsh format, where only the +body of the function occurs in the file, or for files that have been +executed by the @t{source} or `@t{.}' builtins, the trace information is +shown as @var{filename}@t{:}@var{0}, since the entire file is the +definition. The source file name is resolved to an absolute path when +the function is loaded or the path to it otherwise resolved. + +@noindent +Most users will be interested in the information in the +@t{funcfiletrace} array instead. + +@vindex funcstack +@item @t{funcstack} +This array contains the names of the functions, sourced files, +and (if @t{EVAL_LINENO} is set) @t{eval} commands. currently being +executed. The first element is the name of the function using the +parameter. + +@noindent +The standard shell array @t{zsh_eval_context} can be used to +determine the type of shell construct being executed at each depth: +note, however, that is in the opposite order, with the most recent +item last, and it is more detailed, for example including an +entry for @t{toplevel}, the main shell code being executed +either interactively or from a script, which is not present +in @t{$funcstack}. + +@vindex functrace +@item @t{functrace} +This array contains the names and line numbers of the callers +corresponding to the functions currently being executed. +The format of each element is @var{name}@t{:}@var{lineno}. +Callers are also shown for sourced files; the caller is the point +where the @t{source} or `@t{.}' command was executed. + +@end table +@c (avoiding a yodl bug) +@node The zsh/pcre Module, The zsh/param/private Module, The zsh/parameter Module, Zsh Modules + +@section The zsh/pcre Module +@noindent +@c Yodl file: Zsh/mod_pcre.yo + +@cindex regular expressions, perl-compatible +The @t{zsh/pcre} module makes some commands available as builtins: + +@noindent +@table @asis +@findex pcre_compile +@item @t{pcre_compile} [ @t{-aimxs} ] @var{PCRE} +Compiles a perl-compatible regular expression. + +@noindent +Option @t{-a} will force the pattern to be anchored. +Option @t{-i} will compile a case-insensitive pattern. +Option @t{-m} will compile a multi-line pattern; that is, +@t{^} and @t{$} will match newlines within the pattern. +Option @t{-x} will compile an extended pattern, wherein +whitespace and @t{#} comments are ignored. +Option @t{-s} makes the dot metacharacter match all characters, +including those that indicate newline. + +@findex pcre_study +@item @t{pcre_study} +Studies the previously-compiled PCRE which may result in faster +matching. + +@findex pcre_match +@item @t{pcre_match} [ @t{-v} @var{var} ] [ @t{-a} @var{arr} ] [ @t{-n} @var{offset} ] [ @t{-b} ] @var{string} +Returns successfully if @t{string} matches the previously-compiled +PCRE. + +@noindent +Upon successful match, +if the expression captures substrings within parentheses, +@t{pcre_match} will set the array @t{match} to those +substrings, unless the @t{-a} option is given, in which +case it will set the array @var{arr}. Similarly, the variable +@t{MATCH} will be set to the entire matched portion of the +string, unless the @t{-v} option is given, in which case the variable +@var{var} will be set. +No variables are altered if there is no successful match. +A @t{-n} option starts searching for a match from the +byte @var{offset} position in @var{string}. If the @t{-b} option is given, +the variable @t{ZPCRE_OP} will be set to an offset pair string, +representing the byte offset positions of the entire matched portion +within the @var{string}. For example, a @t{ZPCRE_OP} set to "32 45" indicates +that the matched portion began on byte offset 32 and ended on byte offset 44. +Here, byte offset position 45 is the position directly after the matched +portion. Keep in mind that the byte position isn't necessarily the same +as the character position when UTF-8 characters are involved. +Consequently, the byte offset positions are only to be relied on in the +context of using them for subsequent searches on @var{string}, using an offset +position as an argument to the @t{-n} option. This is mostly +used to implement the "find all non-overlapping matches" functionality. + +@noindent +A simple example of "find all non-overlapping matches": + +@noindent +@example +string="The following zip codes: 78884 90210 99513" +pcre_compile -m "\d@{5@}" +accum=() +pcre_match -b -- $string +while [[ $? -eq 0 ]] do + b=($=ZPCRE_OP) + accum+=$MATCH + pcre_match -b -n $b[2] -- $string +done +print -l $accum +@end example + +@end table + +@noindent +The @t{zsh/pcre} module makes available the following test condition: + +@noindent +@table @asis +@findex pcre-match +@item @var{expr} @t{-pcre-match} @var{pcre} +Matches a string against a perl-compatible regular expression. + +@noindent +For example, + +@noindent +@example +[[ "$text" -pcre-match ^d+$ ]] && +print text variable contains only "d's". +@end example + +@noindent +@pindex REMATCH_PCRE +@pindex NO_CASE_MATCH +If the @t{REMATCH_PCRE} option is set, the @t{=~} operator is equivalent to +@t{-pcre-match}, and the @t{NO_CASE_MATCH} option may be used. Note that +@t{NO_CASE_MATCH} never applies to the @t{pcre_match} builtin, instead use +the @t{-i} switch of @t{pcre_compile}. + +@end table +@c (avoiding a yodl bug) +@node The zsh/param/private Module, The zsh/regex Module, The zsh/pcre Module, Zsh Modules + +@section The zsh/param/private Module +@noindent +@c Yodl file: Zsh/mod_private.yo + +The @t{zsh/param/private} module is used to create parameters whose scope +is limited to the current function body, and @emph{not} to other functions +called by the current function. + +@noindent +This module provides a single autoloaded builtin: + +@table @asis +@findex private +@cindex private parameter, creating +@item @t{private} [ @{@t{+}|@t{-}@}@t{AHUahlprtux} ] [ @{@t{+}|@t{-}@}@t{EFLRZi} [ @var{n} ] ] [ @var{name}[@t{=}@var{value}] ... ] +The @t{private} builtin accepts all the same options and arguments as @t{local} +(@ref{Shell Builtin Commands}) except +for the `@t{-}@t{T}' option. Tied parameters may not be made private. + +@noindent +If used at the top level (outside a function scope), @t{private} creates a +normal parameter in the same manner as @t{declare} or @t{typeset}. A +warning about this is printed if @t{WARN_CREATE_GLOBAL} is set +(@ref{Options}). Used inside a +function scope, @t{private} creates a local parameter similar to one +declared with @t{local}, except having special properties noted below. + +@noindent +Special parameters which expose or manipulate internal shell state, such +as @t{ARGC}, @t{argv}, @t{COLUMNS}, @t{LINES}, @t{UID}, @t{EUID}, @t{IFS}, +@t{PROMPT}, @t{RANDOM}, @t{SECONDS}, etc., cannot be made private unless +the `@t{-}@t{h}' option is used to hide the special meaning of the +parameter. This may change in the future. + +@end table + +@noindent +As with other @t{typeset} equivalents, @t{private} is both a builtin and a +reserved word, so arrays may be assigned with parenthesized word list +@var{name}@t{=(}@var{value}...@t{)} syntax. However, the reserved +word `@t{private}' is not available until @t{zsh/param/private} is loaded, +so care must be taken with order of execution and parsing for function +definitions which use @t{private}. To compensate for this, the module +also adds the option `@t{-P}' to the `@t{local}' builtin to declare private +parameters. + +@noindent +For example, this construction fails if @t{zsh/param/private} has not yet +been loaded when `@t{bad_declaration}' is defined: +@example +bad_declaration() @{ + zmodload zsh/param/private + private array=( one two three ) +@} +@end example + +@noindent +This construction works because @t{local} is already a keyword, and the +module is loaded before the statement is executed: +@example +good_declaration() @{ + zmodload zsh/param/private + local -P array=( one two three ) +@} +@end example + +@noindent +The following is usable in scripts but may have trouble with @t{autoload}: +@example +zmodload zsh/param/private +iffy_declaration() @{ + private array=( one two three ) +@} +@end example + +@noindent +The @t{private} builtin may always be used with scalar assignments and +for declarations without assignments. + +@noindent +Parameters declared with @t{private} have the following properties: + +@itemize @bullet + +@item +Within the function body where it is declared, the parameter +behaves as a local, except as noted above for tied or special parameters. +@item +The type of a parameter declared private cannot be changed in the +scope where it was declared, even if the parameter is unset. Thus an +array cannot be assigned to a private scalar, etc. +@item +Within any other function called by the declaring function, the +private parameter does @emph{NOT} hide other parameters of the same name, so +for example a global parameter of the same name is visible and may be +assigned or unset. This includes calls to anonymous functions, although +that may also change in the future. +@item +An exported private remains in the environment of inner scopes but +appears unset for the current shell in those scopes. Generally, exporting +private parameters should be avoided. +@end itemize + +@noindent +Note that this differs from the static scope defined by compiled languages +derived from C, in that the a new call to the same function creates a new +scope, i.e., the parameter is still associated with the call stack rather +than with the function definition. It differs from ksh `@t{typeset -S}' +because the syntax used to define the function has no bearing on whether +the parameter scope is respected. +@c (avoiding a yodl bug) +@node The zsh/regex Module, The zsh/sched Module, The zsh/param/private Module, Zsh Modules + +@section The zsh/regex Module +@noindent +@c Yodl file: Zsh/mod_regex.yo + +@cindex regular expressions +@cindex regex +The @t{zsh/regex} module makes available the following test condition: + +@noindent +@table @asis +@findex regex-match +@item @var{expr} @t{-regex-match} @var{regex} +Matches a string against a POSIX extended regular expression. +On successful match, +matched portion of the string will normally be placed in the @t{MATCH} +variable. If there are any capturing parentheses within the regex, then +the @t{match} array variable will contain those. +If the match is not successful, then the variables will not be altered. + +@noindent +For example, + +@noindent +@example +[[ alphabetical -regex-match ^a([^a]+)a([^a]+)a ]] && +print -l $MATCH X $match +@end example + +@noindent +If the option @t{REMATCH_PCRE} is not set, then the @t{=~} operator will +automatically load this module as needed and will invoke the +@t{-regex-match} operator. + +@noindent +If @t{BASH_REMATCH} is set, then the array @t{BASH_REMATCH} will be set +instead of @t{MATCH} and @t{match}. + +@end table +@c (avoiding a yodl bug) +@node The zsh/sched Module, The zsh/net/socket Module, The zsh/regex Module, Zsh Modules + +@section The zsh/sched Module +@noindent +@c Yodl file: Zsh/mod_sched.yo + +The @t{zsh/sched} module makes available one builtin command and one +parameter. + +@noindent +@table @asis +@findex sched +@cindex timed execution +@cindex execution, timed +@item @t{sched} [@t{-o}] [@t{+}]@var{hh}@t{:}@var{mm}[@t{:}@var{ss}] @var{command} ... +@itemx @t{sched} [@t{-o}] [@t{+}]@var{seconds} @var{command} ... +@itemx @t{sched} [ @t{-}@var{item} ] +Make an entry in the scheduled list of commands to execute. +The time may be specified in either absolute or relative time, +and either as hours, minutes and (optionally) seconds separated by a +colon, or seconds alone. +An absolute number of seconds indicates the time since the epoch +(1970/01/01 00:00); this is useful in combination with the features in +the @t{zsh/datetime} module, see +@ref{The zsh/datetime Module}. + +@noindent +With no arguments, prints the list of scheduled commands. If the +scheduled command has the @t{-o} flag set, this is shown at the +start of the command. + +@noindent +With the argument `@t{-}@var{item}', removes the given item +from the list. The numbering of the list is continuous and entries are +in time order, so the numbering can change when entries are added or +deleted. + +@noindent +Commands are executed either immediately before a prompt, or while +the shell's line editor is waiting for input. In the latter case +it is useful to be able to produce output that does not interfere +with the line being edited. Providing the option @t{-o} causes +the shell to clear the command line before the event and redraw it +afterwards. This should be used with any scheduled event that produces +visible output to the terminal; it is not needed, for example, with +output that updates a terminal emulator's title bar. + +@noindent +To effect changes to the editor buffer when an event executes, use the +`@t{zle}' command with no arguments to test whether the editor is active, +and if it is, then use `@t{zle }@var{widget}' to access the editor via +the named @var{widget}. + +@noindent +The @t{sched} builtin is not made available by default when the shell +starts in a mode emulating another shell. It can be made available +with the command `@t{zmodload -F zsh/sched b:sched}'. + +@end table + +@noindent +@table @asis +@vindex zsh_scheduled_events +@item @t{zsh_scheduled_events} +A readonly array corresponding to the events scheduled by the +@t{sched} builtin. The indices of the array correspond to the numbers +shown when @t{sched} is run with no arguments (provided that the +@t{KSH_ARRAYS} option is not set). The value of the array +consists of the scheduled time in seconds since the epoch +(see @ref{The zsh/datetime Module} for facilities for +using this number), followed by a colon, followed by any options +(which may be empty but will be preceded by a `@t{-}' otherwise), +followed by a colon, followed by the command to be executed. + +@noindent +The @t{sched} builtin should be used for manipulating the events. Note +that this will have an immediate effect on the contents of the array, +so that indices may become invalid. + +@end table +@c (avoiding a yodl bug) +@node The zsh/net/socket Module, The zsh/stat Module, The zsh/sched Module, Zsh Modules + +@section The zsh/net/socket Module +@noindent +@c Yodl file: Zsh/mod_socket.yo + +The @t{zsh/net/socket} module makes available one builtin command: + +@noindent +@table @asis +@findex zsocket +@cindex sockets +@cindex sockets, Unix domain +@item @t{zsocket} [ @t{-altv} ] [ @t{-d} @var{fd} ] [ @var{args} ] +@t{zsocket} is implemented as a builtin to allow full use of shell +command line editing, file I/O, and job control mechanisms. + +@end table + +@noindent + +@subsection Outbound Connections +@noindent +@cindex sockets, outbound Unix domain + +@noindent +@table @asis +@item @t{zsocket} [ @t{-v} ] [ @t{-d} @var{fd} ] @var{filename} +Open a new Unix domain connection to @var{filename}. +The shell parameter @t{REPLY} will be set to the file descriptor +associated with that connection. Currently, only stream connections +are supported. + +@noindent +If @t{-d} is specified, its argument +will be taken as the target file descriptor for the +connection. + +@noindent +In order to elicit more verbose output, use @t{-v}. + +@noindent +File descriptors can be closed with normal shell syntax when no longer +needed, for example: + +@noindent +@example +exec @{REPLY@}>&- +@end example + +@end table + +@noindent + +@subsection Inbound Connections +@noindent +@cindex sockets, inbound Unix domain + +@noindent +@table @asis +@item @t{zsocket} @t{-l} [ @t{-v} ] [ @t{-d} @var{fd} ] @var{filename} +@t{zsocket -l} will open a socket listening on @var{filename}. +The shell parameter @t{REPLY} will be set to the file descriptor +associated with that listener. The file descriptor remains open in subshells +and forked external executables. + +@noindent +If @t{-d} is specified, its argument +will be taken as the target file descriptor for +the connection. + +@noindent +In order to elicit more verbose output, use @t{-v}. + +@item @t{zsocket} @t{-a} [ @t{-tv} ] [ @t{-d} @var{targetfd} ] @var{listenfd} +@t{zsocket -a} will accept an incoming connection +to the socket associated with @var{listenfd}. +The shell parameter @t{REPLY} will +be set to the file descriptor associated with +the inbound connection. The file descriptor remains open in subshells +and forked external executables. + +@noindent +If @t{-d} is specified, its argument +will be taken as the target file descriptor for the +connection. + +@noindent +If @t{-t} is specified, @t{zsocket} will return +if no incoming connection is pending. Otherwise +it will wait for one. + +@noindent +In order to elicit more verbose output, use @t{-v}. + +@end table +@c (avoiding a yodl bug) +@node The zsh/stat Module, The zsh/system Module, The zsh/net/socket Module, Zsh Modules + +@section The zsh/stat Module +@noindent +@c Yodl file: Zsh/mod_stat.yo + +The @t{zsh/stat} module makes available one builtin command under +two possible names: + +@noindent +@table @asis +@findex zstat +@findex stat +@cindex files, listing +@cindex files, examining + +@item @t{zstat }[ @t{-gnNolLtTrs} ] [ @t{-f} @var{fd} ] [ @t{-H} @var{hash} ] [ @t{-A} @var{array} ] [ @t{-F} @var{fmt} ] +@itemx @t{@ @ @ @ @ @ }[ @t{+}@var{element} ] [ @var{file} ... ] +@itemx @t{stat} @var{...} +The command acts as a front end to the @t{stat} system call (see +man page stat(2)). The same command is provided with two names; as +the name @t{stat} is often used by an external command it is recommended +that only the @t{zstat} form of the command is used. This can be +arranged by loading the module with the command `@t{zmodload -F zsh/stat +b:zstat}'. + +@noindent +If the @t{stat} call fails, the appropriate system error message +printed and status 1 is returned. +The fields of @t{struct stat} give information about +the files provided as arguments to the command. In addition to those +available from the @t{stat} call, an extra element `@t{link}' is provided. +These elements are: + +@noindent +@table @asis +@item @t{device} +The number of the device on which the file resides. + +@item @t{inode} +The unique number of the file on this device (`@emph{inode}' number). + +@item @t{mode} +The mode of the file; that is, the file's type and access permissions. +With the @t{-s} option, this will +be returned as a string corresponding to the first column in the +display of the @t{ls -l} command. + +@item @t{nlink} +The number of hard links to the file. + +@item @t{uid} +The user ID of the owner of the file. With the @t{-s} +option, this is displayed as a user name. + +@item @t{gid} +The group ID of the file. With the @t{-s} option, this +is displayed as a group name. + +@item @t{rdev} +The raw device number. This is only useful for special devices. + +@item @t{size} +The size of the file in bytes. + +@item @t{atime} +@itemx @t{mtime} +@itemx @t{ctime} +The last access, modification and inode change times +of the file, respectively, as the number of seconds since +midnight GMT on 1st January, 1970. With the @t{-s} option, +these are printed as strings for the local time zone; the format +can be altered with the @t{-F} option, and with the @t{-g} +option the times are in GMT. + +@item @t{blksize} +The number of bytes in one allocation block on the +device on which the file resides. + +@item @t{block} +The number of disk blocks used by the file. + +@item @t{link} +If the file is a link and the @t{-L} option is in +effect, this contains the name of the file linked to, otherwise +it is empty. Note that if this element is selected (@value{dsbq}@t{zstat +link}@value{dsq}) +then the @t{-L} option is automatically used. + +@end table + +@noindent +A particular element may be selected by including its name +preceded by a `@t{+}' in the option list; only one element is allowed. +The element may be shortened to any unique set of leading +characters. Otherwise, all elements will be shown for all files. + +@noindent +Options: + +@noindent +@table @asis +@item @t{-A} @var{array} +Instead of displaying the results on standard +output, assign them to an @var{array}, one @t{struct stat} element per array +element for each file in order. In this case neither the name +of the element nor the name of the files appears in @var{array} unless the +@t{-t} or @t{-n} options were given, respectively. If @t{-t} is given, +the element name appears as a prefix to the +appropriate array element; if @t{-n} is given, the file name +appears as a separate array element preceding all the others. +Other formatting options are respected. + +@item @t{-H} @var{hash} +Similar to @t{-A}, but instead assign the values to @var{hash}. The keys +are the elements listed above. If the @t{-n} option is provided then the +name of the file is included in the hash with key @t{name}. + +@item @t{-f} @var{fd} +Use the file on file descriptor @var{fd} instead of +named files; no list of file names is allowed in this case. + +@item @t{-F} @var{fmt} +Supplies a @t{strftime} (see man page strftime(3)) string for the +formatting of the time elements. The format string supports all of the +zsh extensions described in +@ref{Prompt Expansion}. +The @t{-s} option is implied. + +@item @t{-g} +Show the time elements in the GMT time zone. The +@t{-s} option is implied. + +@item @t{-l} +List the names of the type elements (to standard +output or an array as appropriate) and return immediately; +arguments, and options other than @t{-A}, are ignored. + +@item @t{-L} +Perform an @t{lstat} (see man page lstat(2)) rather than a @t{stat} +system call. In this case, if the file is a link, information +about the link itself rather than the target file is returned. +This option is required to make the @t{link} element useful. +It's important to note that this is the exact opposite from man page ls(1), +etc. + +@item @t{-n} +Always show the names of files. Usually these are +only shown when output is to standard output and there is more +than one file in the list. + +@item @t{-N} +Never show the names of files. + +@item @t{-o} +If a raw file mode is printed, show it in octal, which is more useful for +human consumption than the default of decimal. A leading zero will be +printed in this case. Note that this does not affect whether a raw or +formatted file mode is shown, which is controlled by the @t{-r} and @t{-s} +options, nor whether a mode is shown at all. + +@item @t{-r} +Print raw data (the default format) alongside string +data (the @t{-s} format); the string data appears in parentheses +after the raw data. + +@item @t{-s} +Print @t{mode}, @t{uid}, @t{gid} and the three time +elements as strings instead of numbers. In each case the format +is like that of @t{ls -l}. + +@item @t{-t} +Always show the type names for the elements of +@t{struct stat}. Usually these are only shown when output is to +standard output and no individual element has been selected. + +@item @t{-T} +Never show the type names of the @t{struct stat} elements. + +@end table + +@end table +@c (avoiding a yodl bug) +@node The zsh/system Module, The zsh/net/tcp Module, The zsh/stat Module, Zsh Modules + +@section The zsh/system Module +@noindent +@c Yodl file: Zsh/mod_system.yo + +The @t{zsh/system} module makes available various builtin commands and +parameters. + +@noindent + +@subsection Builtins +@noindent + +@noindent +@table @asis +@findex syserror +@item @t{syserror} [ @t{-e} @var{errvar} ] [ @t{-p} @var{prefix} ] [ @var{errno} | @var{errname} ] +This command prints out the error message associated with @var{errno}, a +system error number, followed by a newline to standard error. + +@noindent +Instead of the error number, a name @var{errname}, for example +@t{ENOENT}, may be used. The set of names is the same as the contents +of the array @t{errnos}, see below. + +@noindent +If the string @var{prefix} is given, it is printed in front of the error +message, with no intervening space. + +@noindent +If @var{errvar} is supplied, the entire message, without a newline, is +assigned to the parameter names @var{errvar} and nothing is output. + +@noindent +A return status of 0 indicates the message was successfully printed +(although it may not be useful if the error number was out of the +system's range), a return status of 1 indicates an error in the +parameters, and a return status of 2 indicates the error name was +not recognised (no message is printed for this). + +@findex sysopen + +@item @t{sysopen} [ @t{-arw} ] [ @t{-m} @var{permissions} ] [ @t{-o} @var{options} ] +@itemx @t{@ @ @ @ @ @ @ @ }@t{-u} @var{fd} @var{file} +This command opens a file. The @t{-r}, @t{-w} and @t{-a} flags indicate +whether the file should be opened for reading, writing and appending, +respectively. The @t{-m} option allows the initial permissions to use when +creating a file to be specified in octal form. The file descriptor is +specified with @t{-u}. Either an explicit file descriptor in the range 0 to 9 can +be specified or a variable name can be given to which the file descriptor +number will be assigned. + +@noindent +The @t{-o} option allows various system specific options to be +specified as a comma-separated list. The following is a list of possible +options. Note that, depending on the system, some may not be available. +@table @asis +@item @t{cloexec} +mark file to be closed when other programs are executed (else +the file descriptor remains open in subshells and forked external +executables) + +@item @t{create} +@itemx @t{creat} +create file if it does not exist + +@item @t{excl} +create file, error if it already exists + +@item @t{noatime} +suppress updating of the file atime + +@item @t{nofollow} +fail if @var{file} is a symbolic link + +@item @t{sync} +request that writes wait until data has been physically written + +@item @t{truncate} +@itemx @t{trunc} +truncate file to size 0 + +@end table + +@noindent +To close the file, use one of the following: + +@noindent +@example +@t{exec @{}@var{fd}@t{@}<&-} +@t{exec @{}@var{fd}@t{@}>&-} +@end example + +@findex sysread + +@item @t{sysread }[ @t{-c} @var{countvar} ] [ @t{-i} @var{infd} ] [ @t{-o} @var{outfd} ] +@itemx @t{@ @ @ @ @ @ @ @ }[ @t{-s} @var{bufsize} ] [ @t{-t} @var{timeout} ] [ @var{param} ] +Perform a single system read from file descriptor @var{infd}, or zero if +that is not given. The result of the read is stored in @var{param} or +@t{REPLY} if that is not given. If @var{countvar} is given, the number +of bytes read is assigned to the parameter named by @var{countvar}. + +@noindent +The maximum number of bytes read is @var{bufsize} or 8192 if that is not +given, however the command returns as soon as any number of bytes was +successfully read. + +@noindent +If @var{timeout} is given, it specifies a timeout in seconds, which may +be zero to poll the file descriptor. This is handled by the @t{poll} +system call if available, otherwise the @t{select} system call if +available. + +@noindent +If @var{outfd} is given, an attempt is made to write all the bytes just +read to the file descriptor @var{outfd}. If this fails, because of a +system error other than @t{EINTR} or because of an internal zsh error +during an interrupt, the bytes read but not written are stored in the +parameter named by @var{param} if supplied (no default is used in this +case), and the number of bytes read but not written is stored in the +parameter named by @var{countvar} if that is supplied. If it was +successful, @var{countvar} contains the full number of bytes transferred, +as usual, and @var{param} is not set. + +@noindent +The error @t{EINTR} (interrupted system call) is handled internally so +that shell interrupts are transparent to the caller. Any other error +causes a return. + +@noindent +The possible return statuses are +@table @asis +@item 0 +At least one byte of data was successfully read and, if appropriate, +written. + +@item 1 +There was an error in the parameters to the command. This is the only +error for which a message is printed to standard error. + +@item 2 +There was an error on the read, or on polling the input file descriptor +for a timeout. The parameter @t{ERRNO} gives the error. + +@item 3 +Data were successfully read, but there was an error writing them +to @var{outfd}. The parameter @t{ERRNO} gives the error. + +@item 4 +The attempt to read timed out. Note this does not set @t{ERRNO} as this +is not a system error. + +@item 5 +No system error occurred, but zero bytes were read. This usually +indicates end of file. The parameters are set according to the +usual rules; no write to @var{outfd} is attempted. + +@end table + +@item @t{sysseek} [ @t{-u} @var{fd} ] [ @t{-w} @t{start}|@t{end}|@t{current} ] @var{offset} +The current file position at which future reads and writes will take place is +adjusted to the specified byte offset. The @var{offset} is evaluated as a math +expression. The @t{-u} option allows the file descriptor to be specified. By +default the offset is specified relative to the start or the file but, with the +@t{-w} option, it is possible to specify that the offset should be relative to +the current position or the end of the file. + +@item @t{syswrite} [ @t{-c} @var{countvar} ] [ @t{-o} @var{outfd} ] @var{data} +The data (a single string of bytes) are written to the file descriptor +@var{outfd}, or 1 if that is not given, using the @t{write} system call. +Multiple write operations may be used if the first does not write all +the data. + +@noindent +If @var{countvar} is given, the number of byte written is stored in the +parameter named by @var{countvar}; this may not be the full length of +@var{data} if an error occurred. + +@noindent +The error @t{EINTR} (interrupted system call) is handled internally by +retrying; otherwise an error causes the command to return. For example, +if the file descriptor is set to non-blocking output, an error +@t{EAGAIN} (on some systems, @t{EWOULDBLOCK}) may result in the command +returning early. + +@noindent +The return status may be 0 for success, 1 for an error in the parameters +to the command, or 2 for an error on the write; no error message is +printed in the last case, but the parameter @t{ERRNO} will reflect +the error that occurred. + +@item @t{zsystem flock} [ @t{-t} @var{timeout} ] [ @t{-f} @var{var} ] [@t{-er}] @var{file} +@itemx @t{zsystem flock -u} @var{fd_expr} +The builtin @t{zsystem}'s subcommand @t{flock} performs advisory file +locking (via the man page fcntl(2) system call) over the entire contents +of the given file. This form of locking requires the processes +accessing the file to cooperate; its most obvious use is between two +instances of the shell itself. + +@noindent +In the first form the named @var{file}, which must already exist, is +locked by opening a file descriptor to the file and applying a lock to +the file descriptor. The lock terminates when the shell process that +created the lock exits; it is therefore often convenient to create file +locks within subshells, since the lock is automatically released when +the subshell exits. Note that use of the @t{print} builtin with the +@t{-u} option will, as a side effect, release the lock, as will redirection +to the file in the shell holding the lock. To work around this use a +subshell, e.g. `@t{(print message) >> }@var{file}'. Status 0 is +returned if the lock succeeds, else status 1. + +@noindent +In the second form the file descriptor given by the arithmetic +expression @var{fd_expr} is closed, releasing a lock. The file descriptor +can be queried by using the `@t{-f} @var{var}' form during the lock; +on a successful lock, the shell variable @var{var} is set to the file +descriptor used for locking. The lock will be released if the +file descriptor is closed by any other means, for example using +`@t{exec @{}@var{var}@t{@}>&-}'; however, the form described here performs +a safety check that the file descriptor is in use for file locking. + +@noindent +By default the shell waits indefinitely for the lock to succeed. +The option @t{-t} @var{timeout} specifies a timeout for the lock in +seconds; currently this must be an integer. The shell will attempt +to lock the file once a second during this period. If the attempt +times out, status 2 is returned. + +@noindent +If the option @t{-e} is given, the file descriptor for the lock is +preserved when the shell uses @t{exec} to start a new process; +otherwise it is closed at that point and the lock released. + +@noindent +If the option @t{-r} is given, the lock is only for reading, otherwise +it is for reading and writing. The file descriptor is opened +accordingly. + +@item @t{zsystem supports} @var{subcommand} +The builtin @t{zsystem}'s subcommand @t{supports} tests whether a +given subcommand is supported. It returns status 0 if so, else +status 1. It operates silently unless there was a syntax error +(i.e. the wrong number of arguments), in which case status 255 +is returned. Status 1 can indicate one of two things: @var{subcommand} +is known but not supported by the current operating system, or +@var{subcommand} is not known (possibly because this is an older +version of the shell before it was implemented). + +@end table + +@noindent + +@subsection Math Functions +@noindent + +@noindent +@table @asis +@item @t{systell(@var{fd})} +The systell math function returns the current file position for the file +descriptor passed as an argument. + +@end table + +@noindent + +@subsection Parameters +@noindent + +@noindent +@table @asis +@vindex errnos +@item @t{errnos} +A readonly array of the names of errors defined on the system. These +are typically macros defined in C by including the system header file +@t{errno.h}. The index of each name (assuming the option @t{KSH_ARRAYS} +is unset) corresponds to the error number. Error numbers @var{num} +before the last known error which have no name are given the name +@t{E}@var{num} in the array. + +@noindent +Note that aliases for errors are not handled; only the canonical name is +used. + +@vindex sysparams +@item @t{sysparams} +A readonly associative array. The keys are: + +@noindent +@table @asis +@item @t{pid} +@vindex pid, sysparams +Returns the process ID of the current process, even in subshells. Compare +@t{$$}, which returns the process ID of the main shell process. + +@item @t{ppid} +@vindex ppid, sysparams +Returns the process ID of the parent of the current process, even in +subshells. Compare @t{$PPID}, which returns the process ID of the parent +of the main shell process. + +@item @t{procsubstpid} +Returns the process ID of the last process started for process +substitution, i.e. the @t{<(}@var{...}@t{)} and +@t{>(}@var{...}@t{)} expansions. + +@end table + +@end table +@c (avoiding a yodl bug) +@node The zsh/net/tcp Module, The zsh/termcap Module, The zsh/system Module, Zsh Modules + +@section The zsh/net/tcp Module +@noindent +@c Yodl file: Zsh/mod_tcp.yo + +The @t{zsh/net/tcp} module makes available one builtin command: + +@noindent +@table @asis +@findex ztcp +@cindex TCP +@cindex sockets, TCP +@item @t{ztcp} [ @t{-acflLtv} ] [ @t{-d} @var{fd} ] [ @var{args} ] +@t{ztcp} is implemented as a builtin to allow full use of shell +command line editing, file I/O, and job control mechanisms. + +@noindent +If @t{ztcp} is run with no options, it will output +the contents of its session table. + +@noindent +If it is run with only the option @t{-L}, it will output the contents of +the session table in a format suitable for automatic parsing. The option +is ignored if given with a command to open or close a session. The output +consists of a set of lines, one per session, each containing the following +elements separated by spaces: + +@noindent +@table @asis +@item File descriptor +The file descriptor in use for the connection. For normal inbound (@t{I}) +and outbound (@t{O}) connections this may be read and written by the usual +shell mechanisms. However, it should only be close with `@t{ztcp -c}'. + +@item Connection type +A letter indicating how the session was created: + +@noindent +@table @asis +@item @t{Z} +A session created with the @t{zftp} command. + +@item @t{L} +A connection opened for listening with `@t{ztcp -l}'. + +@item @t{I} +An inbound connection accepted with `@t{ztcp -a}'. + +@item @t{O} +An outbound connection created with `@t{ztcp} @var{host} @var{...}'. + +@end table + +@noindent + +@item The local host +This is usually set to an all-zero IP address as the address of the +localhost is irrelevant. + +@item The local port +This is likely to be zero unless the connection is for listening. + +@item The remote host +This is the fully qualified domain name of the peer, if available, else an +IP address. It is an all-zero IP address for a session opened for +listening. + +@item The remote port +This is zero for a connection opened for listening. + +@end table + +@end table + +@noindent + +@subsection Outbound Connections +@noindent +@cindex sockets, outbound TCP + +@noindent +@table @asis +@item @t{ztcp} [ @t{-v} ] [ @t{-d} @var{fd} ] @var{host} [ @var{port} ] +Open a new TCP connection to @var{host}. If the @var{port} is +omitted, it will default to port 23. The connection will +be added to the session table and the shell parameter +@t{REPLY} will be set to the file descriptor associated +with that connection. + +@noindent +If @t{-d} is specified, its argument will be taken as the target file +descriptor for the connection. + +@noindent +In order to elicit more verbose output, use @t{-v}. + +@end table + +@noindent + +@subsection Inbound Connections +@noindent +@cindex sockets, inbound TCP + +@noindent +@table @asis +@item @t{ztcp} @t{-l} [ @t{-v} ] [ @t{-d} @var{fd} ] @var{port} +@t{ztcp -l} will open a socket listening on TCP +@var{port}. The socket will be added to the +session table and the shell parameter @t{REPLY} +will be set to the file descriptor associated +with that listener. + +@noindent +If @t{-d} is specified, its argument will be taken as the target file +descriptor for the connection. + +@noindent +In order to elicit more verbose output, use @t{-v}. + +@item @t{ztcp} @t{-a} [ @t{-tv} ] [ @t{-d} @var{targetfd} ] @var{listenfd} +@t{ztcp -a} will accept an incoming connection +to the port associated with @var{listenfd}. +The connection will be added to the session +table and the shell parameter @t{REPLY} will +be set to the file descriptor associated with +the inbound connection. + +@noindent +If @t{-d} is specified, its argument +will be taken as the target file descriptor for the +connection. + +@noindent +If @t{-t} is specified, @t{ztcp} will return +if no incoming connection is pending. Otherwise +it will wait for one. + +@noindent +In order to elicit more verbose output, use @t{-v}. + +@end table + +@noindent + +@subsection Closing Connections +@noindent +@cindex sockets, closing TCP + +@noindent +@table @asis +@item @t{ztcp} @t{-cf} [ @t{-v} ] [ @var{fd} ] +@itemx @t{ztcp} @t{-c} [ @t{-v} ] [ @var{fd} ] +@t{ztcp -c} will close the socket associated +with @var{fd}. The socket will be removed from the +session table. If @var{fd} is not specified, +@t{ztcp} will close everything in the session table. + +@noindent +Normally, sockets registered by zftp (see +@ref{The zsh/zftp Module} +) cannot be closed this way. In order +to force such a socket closed, use @t{-f}. + +@noindent +In order to elicit more verbose output, use @t{-v}. + +@end table + +@noindent + +@subsection Example +@noindent +@cindex TCP, example +Here is how to create a TCP connection between two instances of zsh. We +need to pick an unassigned port; here we use the randomly chosen 5123. + +@noindent +On @t{host1}, +@example +zmodload zsh/net/tcp +ztcp -l 5123 +listenfd=$REPLY +ztcp -a $listenfd +fd=$REPLY +@end example +The second from last command blocks until there is an incoming connection. + +@noindent +Now create a connection from @t{host2} (which may, of course, be the same +machine): +@example +zmodload zsh/net/tcp +ztcp host1 5123 +fd=$REPLY +@end example + +@noindent +Now on each host, @t{$fd} contains a file descriptor for talking to the +other. For example, on @t{host1}: +@example +print This is a message >&$fd +@end example +and on @t{host2}: +@example +read -r line <&$fd; print -r - $line +@end example +prints `@t{This is a message}'. + +@noindent +To tidy up, on @t{host1}: +@example +ztcp -c $listenfd +ztcp -c $fd +@end example +and on @t{host2} +@example +ztcp -c $fd +@end example +@c (avoiding a yodl bug) +@node The zsh/termcap Module, The zsh/terminfo Module, The zsh/net/tcp Module, Zsh Modules + +@section The zsh/termcap Module +@noindent +@c Yodl file: Zsh/mod_termcap.yo + +The @t{zsh/termcap} module makes available one builtin command: + +@noindent +@table @asis +@findex echotc +@cindex termcap value, printing +@item @t{echotc} @var{cap} [ @var{arg} ... ] +Output the termcap value corresponding to the capability +@var{cap}, with optional arguments. + +@end table + +@noindent +The @t{zsh/termcap} module makes available one parameter: + +@noindent +@table @asis +@vindex termcap +@item @t{termcap} +An associative array that maps termcap capability codes to +their values. + +@end table +@c (avoiding a yodl bug) +@node The zsh/terminfo Module, The zsh/zftp Module, The zsh/termcap Module, Zsh Modules + +@section The zsh/terminfo Module +@noindent +@c Yodl file: Zsh/mod_terminfo.yo + +The @t{zsh/terminfo} module makes available one builtin command: + +@noindent +@table @asis +@findex echoti +@cindex terminfo value, printing +@item @t{echoti} @var{cap} [ @var{arg} ] +Output the terminfo value corresponding to the capability +@var{cap}, instantiated with @var{arg} if applicable. + +@end table + +@noindent +The @t{zsh/terminfo} module makes available one parameter: + +@noindent +@table @asis +@vindex terminfo +@item @t{terminfo} +An associative array that maps terminfo capability names to +their values. + +@end table +@c (avoiding a yodl bug) +@node The zsh/zftp Module, The zsh/zle Module, The zsh/terminfo Module, Zsh Modules + +@section The zsh/zftp Module +@noindent +@c Yodl file: Zsh/mod_zftp.yo + +The @t{zsh/zftp} module makes available one builtin command: + +@noindent +@table @asis +@findex zftp +@cindex FTP +@cindex files, transferring +@item @t{zftp} @var{subcommand} [ @var{args} ] +The @t{zsh/zftp} module is a client for FTP (file transfer protocol). It +is implemented as a builtin to allow full use of shell command line +editing, file I/O, and job control mechanisms. Often, users will +access it via shell functions providing a more powerful interface; a set is +provided with the @t{zsh} distribution and is described in +@ref{Zftp Function System}. However, the @t{zftp} command is entirely usable in its +own right. + +@noindent +All commands consist of the command name @t{zftp} followed by the name +of a subcommand. These are listed below. The return status of each +subcommand is supposed to reflect the success or failure of the remote +operation. See a description of the variable @t{ZFTP_VERBOSE} for +more information on how responses from the server may be printed. + +@end table + +@noindent + +@subsection Subcommands +@noindent +@cindex zftp, subcommands + +@noindent +@table @asis +@cindex FTP, starting a session +@item @t{open} @var{host}[@t{:}@var{port}] [ @var{user} [ @var{password} [ @var{account} ] ] ] +Open a new FTP session to @var{host}, which may be the name of a TCP/IP +connected host or an IP number in the standard dot notation. If the +argument is in the form @var{host}@t{:}@var{port}, open a connection to +TCP port @var{port} instead of the standard FTP port 21. This may be +the name of a TCP service or a number: see the description of +@t{ZFTP_PORT} below for more information. + +@noindent +If IPv6 addresses in colon format are used, the @var{host} should be +surrounded by quoted square brackets to distinguish it from the @var{port}, +for example @t{'[fe80::203:baff:fe02:8b56]'}. For consistency this is +allowed with all forms of @var{host}. + +@noindent +Remaining arguments are passed to the @t{login} subcommand. Note that +if no arguments beyond @var{host} are supplied, @t{open} will @emph{not} +automatically call @t{login}. If no arguments at all are supplied, +@t{open} will use the parameters set by the @t{params} subcommand. + +@noindent +After a successful open, the shell variables @t{ZFTP_HOST}, @t{ZFTP_PORT}, +@t{ZFTP_IP} and @t{ZFTP_SYSTEM} are available; see `Variables' +below. + +@item @t{login} [ @var{name} [ @var{password} [ @var{account} ] ] ] +@itemx @t{user} [ @var{name} [ @var{password} [ @var{account} ] ] ] +Login the user @var{name} with parameters @var{password} and @var{account}. +Any of the parameters can be omitted, and will be read from standard +input if needed (@var{name} is always needed). If +standard input is a terminal, a prompt for each one will be printed on +standard error and @var{password} will not be echoed. If any of the +parameters are not used, a warning message is printed. + +@noindent +After a successful login, the shell variables @t{ZFTP_USER}, +@t{ZFTP_ACCOUNT} and @t{ZFTP_PWD} are available; see `Variables' +below. + +@noindent +This command may be re-issued when a user is already logged in, and +the server will first be reinitialized for a new user. + +@item @t{params} [ @var{host} [ @var{user} [ @var{password} [ @var{account} ] ] ] ] +@itemx @t{params} @t{-} +Store the given parameters for a later @t{open} command with no +arguments. Only those given on the command line will be remembered. +If no arguments are given, the parameters currently set are printed, +although the password will appear as a line of stars; the return status is +one if no parameters were set, zero otherwise. + +@noindent +Any of the parameters may be specified as a `@t{?}', which +may need to be quoted to protect it from shell expansion. In this case, +the appropriate parameter will be read from stdin as with the +@t{login} subcommand, including special handling of @var{password}. If the +`@t{?}' is followed by a string, that is used as the prompt for reading the +parameter instead of the default message (any necessary punctuation and +whitespace should be included at the end of the prompt). The first letter +of the parameter (only) may be quoted with a `@t{\}'; hence an argument +@t{"\\$word"} guarantees that the string from the shell parameter @t{$word} +will be treated literally, whether or not it begins with a `@t{?}'. + +@noindent +If instead a single `@t{-}' is given, the existing parameters, if any, +are deleted. In that case, calling @t{open} with no arguments will +cause an error. + +@noindent +The list of parameters is not deleted after a @t{close}, however it +will be deleted if the @t{zsh/zftp} module is unloaded. + +@noindent +For example, + +@noindent +@example +zftp params ftp.elsewhere.xx juser '?Password for juser: ' +@end example + +@noindent +will store the host @t{ftp.elsewhere.xx} and the user @t{juser} and +then prompt the user for the corresponding password with the given prompt. + +@item @t{test} +Test the connection; if the server has reported +that it has closed the connection (maybe due to a timeout), return +status 2; if no connection was open anyway, return status 1; else +return status 0. The @t{test} subcommand is +silent, apart from messages printed by the @t{$ZFTP_VERBOSE} +mechanism, or error messages if the connection closes. There is no +network overhead for this test. + +@noindent +The test is only supported on systems with either the +@t{select(2)} or +@t{poll(2)} system calls; otherwise the message `@t{not +supported on this system}' is printed instead. + +@noindent +The @t{test} subcommand will automatically be called at the start of any +other subcommand for the current session when a connection is open. + +@item @t{cd} @var{directory} +Change the remote directory to @var{directory}. Also alters the shell +variable @t{ZFTP_PWD}. + +@item @t{cdup} +Change the remote directory to the one higher in the directory tree. +Note that @t{cd ..} will also work correctly on non-UNIX systems. + +@item @t{dir} [ @var{arg} ... ] +Give a (verbose) listing of the remote directory. The @var{arg}s are +passed directly to the server. The command's behaviour is implementation +dependent, but a UNIX server will typically interpret @var{arg}s as +arguments to the @t{ls} command and with no arguments return the +result of `@t{ls -l}'. The directory is listed to standard output. + +@item @t{ls} [ @var{arg} ... ] +Give a (short) listing of the remote directory. With no @var{arg}, +produces a raw list of the files in the directory, one per line. +Otherwise, up to vagaries of the server implementation, behaves +similar to @t{dir}. + +@item @t{type} [ @var{type} ] +Change the type for the transfer to @var{type}, or print the current type +if @var{type} is absent. The allowed values are `@t{A}' (ASCII), +`@t{I}' (Image, i.e. binary), or `@t{B}' (a synonym for `@t{I}'). + +@noindent +The FTP default for a transfer is ASCII. However, if @t{zftp} finds +that the remote host is a UNIX machine with 8-bit byes, it will +automatically switch to using binary for file transfers upon +@t{open}. This can subsequently be overridden. + +@noindent +The transfer type is only passed to the remote host when a data +connection is established; this command involves no network overhead. + +@item @t{ascii} +The same as @t{type A}. + +@item @t{binary} +The same as @t{type I}. + +@item @t{mode} [ @t{S} | @t{B} ] +Set the mode type to stream (@t{S}) or block (@t{B}). Stream mode is +the default; block mode is not widely supported. + +@item @t{remote} @var{file} ... +@itemx @t{local} [ @var{file} ... ] +Print the size and last modification time of the remote or local +files. If there is more than one item on the list, the name of the +file is printed first. The first number is the file size, the second +is the last modification time of the file in the format +@t{CCYYMMDDhhmmSS} consisting of year, month, date, hour, minutes and +seconds in GMT. Note that this format, including the length, is +guaranteed, so that time strings can be directly compared via the +@t{[[} builtin's @t{<} and @t{>} operators, even if they are too long +to be represented as integers. + +@noindent +Not all servers support the commands for retrieving this information. +In that case, the @t{remote} command will print nothing and return +status 2, compared with status 1 for a file not found. + +@noindent +The @t{local} command (but not @t{remote}) may be used with no +arguments, in which case the information comes from examining file +descriptor zero. This is the same file as seen by a @t{put} command +with no further redirection. + +@item @t{get} @var{file} ... +Retrieve all @var{file}s from the server, concatenating them +and sending them to standard output. + +@item @t{put} @var{file} ... +For each @var{file}, read a file from standard input and send that to +the remote host with the given name. + +@item @t{append} @var{file} ... +As @t{put}, but if the remote @var{file} already exists, data is +appended to it instead of overwriting it. + +@item @t{getat} @var{file} @var{point} +@itemx @t{putat} @var{file} @var{point} +@itemx @t{appendat} @var{file} @var{point} +Versions of @t{get}, @t{put} and @t{append} which will start the +transfer at the given @var{point} in the remote @var{file}. This is +useful for appending to an incomplete local file. However, note that +this ability is not universally supported by servers (and is not quite +the behaviour specified by the standard). + +@item @t{delete} @var{file} ... +Delete the list of files on the server. + +@item @t{mkdir} @var{directory} +Create a new directory @var{directory} on the server. + +@item @t{rmdir} @var{directory} +Delete the directory @var{directory} on the server. + +@item @t{rename} @var{old-name} @var{new-name} +Rename file @var{old-name} to @var{new-name} on the server. + +@item @t{site} @var{arg} ... +Send a host-specific command to the server. You will probably +only need this if instructed by the server to use it. + +@item @t{quote} @var{arg} ... +Send the raw FTP command sequence to the server. You should be +familiar with the FTP command set as defined in RFC959 before doing +this. Useful commands may include @t{STAT} and @t{HELP}. Note also +the mechanism for returning messages as described for the variable +@t{ZFTP_VERBOSE} below, in particular that all messages from the +control connection are sent to standard error. + +@item @t{close} +@itemx @t{quit} +Close the current data connection. This unsets the shell parameters +@t{ZFTP_HOST}, @t{ZFTP_PORT}, @t{ZFTP_IP}, @t{ZFTP_SYSTEM}, @t{ZFTP_USER}, +@t{ZFTP_ACCOUNT}, @t{ZFTP_PWD}, @t{ZFTP_TYPE} and @t{ZFTP_MODE}. + +@item @t{session} [ @var{sessname} ] +Allows multiple FTP sessions to be used at once. The name of the session +is an arbitrary string of characters; the default session is called +`@t{default}'. If this command is called without an argument, it will list +all the current sessions; with an argument, it will either switch to the +existing session called @var{sessname}, or create a new session of that name. + +@noindent +Each session remembers the status of the connection, the set of +connection-specific shell parameters (the same set as are unset when a +connection closes, as given in the description of @t{close}), and any user +parameters specified with the @t{params} subcommand. Changing to a +previous session restores those values; changing to a new session +initialises them in the same way as if @t{zftp} had just been loaded. The +name of the current session is given by the parameter @t{ZFTP_SESSION}. + +@item @t{rmsession} [ @var{sessname} ] +Delete a session; if a name is not given, the current session is deleted. +If the current session is deleted, the earliest existing session becomes +the new current session, otherwise the current session is not changed. +If the session being deleted is the only one, a new session called +`@t{default}' is created and becomes the current session; note that this is +a new session even if the session being deleted is also called +`@t{default}'. It is recommended that sessions not be deleted while +background commands which use @t{zftp} are still active. + +@end table + +@noindent + +@subsection Parameters +@noindent +@cindex zftp, parameters +The following shell parameters are used by @t{zftp}. Currently none +of them are special. + +@noindent +@table @asis +@vindex ZFTP_TMOUT +@item @t{ZFTP_TMOUT} +Integer. The time in seconds to wait for a network operation to +complete before returning an error. If this is not set when the +module is loaded, it will be given the default value 60. A value of +zero turns off timeouts. If a timeout occurs on the control +connection it will be closed. Use a larger value if this occurs too +frequently. + +@vindex ZFTP_IP +@item @t{ZFTP_IP} +Readonly. The IP address of the current connection in dot notation. + +@vindex ZFTP_HOST +@item @t{ZFTP_HOST} +Readonly. The hostname of the current remote server. If the host was +opened as an IP number, @t{ZFTP_HOST} contains that instead; this +saves the overhead for a name lookup, as IP numbers are most commonly +used when a nameserver is unavailable. + +@vindex ZFTP_PORT +@item @t{ZFTP_PORT} +Readonly. The number of the remote TCP port to which the connection is +open (even if the port was originally specified as a named service). +Usually this is the standard FTP port, 21. + +@noindent +In the unlikely event that your system does not have the appropriate +conversion functions, this appears in network byte order. If your +system is little-endian, the port then consists of two swapped bytes and the +standard port will be reported as 5376. In that case, numeric ports passed +to @t{zftp open} will also need to be in this format. + +@vindex ZFTP_SYSTEM +@item @t{ZFTP_SYSTEM} +Readonly. The system type string returned by the server in response +to an FTP @t{SYST} request. The most interesting case is a string +beginning @t{"UNIX Type: L8"}, which ensures maximum compatibility +with a local UNIX host. + +@vindex ZFTP_TYPE +@item @t{ZFTP_TYPE} +Readonly. The type to be used for data transfers , either `@t{A}' or +`@t{I}'. Use the @t{type} subcommand to change this. + +@vindex ZFTP_USER +@item @t{ZFTP_USER} +Readonly. The username currently logged in, if any. + +@vindex ZFTP_ACCOUNT +@item @t{ZFTP_ACCOUNT} +Readonly. The account name of the current user, if any. Most servers +do not require an account name. + +@vindex ZFTP_PWD +@item @t{ZFTP_PWD} +Readonly. The current directory on the server. + +@vindex ZFTP_CODE +@item @t{ZFTP_CODE} +Readonly. The three digit code of the last FTP reply from the server +as a string. This can still be read after the connection is closed, and +is not changed when the current session changes. + +@vindex ZFTP_REPLY +@item @t{ZFTP_REPLY} +Readonly. The last line of the last reply sent by the server. This +can still be read after the connection is closed, and is not changed when +the current session changes. + +@vindex ZFTP_SESSION +@item @t{ZFTP_SESSION} +Readonly. The name of the current FTP session; see the description of the +@t{session} subcommand. + +@vindex ZFTP_PREFS +@item @t{ZFTP_PREFS} +A string of preferences for altering aspects of @t{zftp}'s behaviour. +Each preference is a single character. The following are defined: + +@noindent +@table @asis +@item @t{P} +Passive: attempt to make the remote server initiate data transfers. +This is slightly more efficient than sendport mode. If the letter +@t{S} occurs later in the string, @t{zftp} will use sendport mode if +passive mode is not available. + +@item @t{S} +Sendport: initiate transfers by the FTP @t{PORT} command. If this +occurs before any @t{P} in the string, passive mode will never be +attempted. + +@item @t{D} +Dumb: use only the bare minimum of FTP commands. This prevents +the variables @t{ZFTP_SYSTEM} and @t{ZFTP_PWD} from being set, and +will mean all connections default to ASCII type. It may prevent +@t{ZFTP_SIZE} from being set during a transfer if the server +does not send it anyway (many servers do). + +@end table + +@noindent +If @t{ZFTP_PREFS} is not set when @t{zftp} is loaded, it will be set to a +default of `@t{PS}', i.e. use passive mode if available, otherwise +fall back to sendport mode. + +@vindex ZFTP_VERBOSE +@item @t{ZFTP_VERBOSE} +A string of digits between 0 and 5 inclusive, specifying which +responses from the server should be printed. All responses go to +standard error. If any of the numbers 1 to 5 appear in the string, +raw responses from the server with reply codes beginning with that +digit will be printed to standard error. The first digit of the three +digit reply code is defined by RFC959 to correspond to: + +@noindent +@table @asis +@item 1. +A positive preliminary reply. + +@item 2. +A positive completion reply. + +@item 3. +A positive intermediate reply. + +@item 4. +A transient negative completion reply. + +@item 5. +A permanent negative completion reply. + +@end table + +@noindent +It should be noted that, for unknown reasons, the reply `Service not +available', which forces termination of a connection, is classified as +421, i.e. `transient negative', an interesting interpretation of the word +`transient'. + +@noindent +The code 0 is special: it indicates that all but the last line of +multiline replies read from the server will be printed to standard +error in a processed format. By convention, servers use this +mechanism for sending information for the user to read. The +appropriate reply code, if it matches the same response, takes +priority. + +@noindent +If @t{ZFTP_VERBOSE} is not set when @t{zftp} is loaded, it will be +set to the default value @t{450}, i.e., messages destined for the user +and all errors will be printed. A null string is valid and +specifies that no messages should be printed. + +@end table + +@noindent + +@subsection Functions +@noindent +@cindex zftp, functions + +@noindent +@table @asis +@findex zftp_chpwd, specification +@item @t{zftp_chpwd} +If this function is set by the user, it is called every time the +directory changes on the server, including when a user is logged +in, or when a connection is closed. In the last case, @t{$ZFTP_PWD} +will be unset; otherwise it will reflect the new directory. + +@findex zftp_progress, specification +@item @t{zftp_progress} +If this function is set by the user, it will be called during +a @t{get}, @t{put} or @t{append} operation each time sufficient data +has been received from the host. During a @t{get}, the data is sent +to standard output, so it is vital that this function should write +to standard error or directly to the terminal, @emph{not} to standard +output. + +@noindent +When it is called with a transfer in progress, the following +additional shell parameters are set: + +@noindent +@table @asis +@vindex ZFTP_FILE +@item @t{ZFTP_FILE} +The name of the remote file being transferred from or to. + +@vindex ZFTP_TRANSFER +@item @t{ZFTP_TRANSFER} +A @t{G} for a @t{get} operation and a @t{P} for a @t{put} operation. + +@vindex ZFTP_SIZE +@item @t{ZFTP_SIZE} +The total size of the complete file being transferred: +the same as the first value provided by the +@t{remote} and @t{local} subcommands for a particular file. +If the server cannot supply this value for a remote file being +retrieved, it will not be set. If input is from a pipe the value may +be incorrect and correspond simply to a full pipe buffer. + +@vindex ZFTP_COUNT +@item @t{ZFTP_COUNT} +The amount of data so far transferred; a number between zero and +@t{$ZFTP_SIZE}, if that is set. This number is always available. + +@end table + +@noindent +The function is initially called with @t{ZFTP_TRANSFER} set +appropriately and @t{ZFTP_COUNT} set to zero. After the transfer is +finished, the function will be called one more time with +@t{ZFTP_TRANSFER} set to @t{GF} or @t{PF}, in case it wishes to tidy +up. It is otherwise never called twice with the same value of +@t{ZFTP_COUNT}. + +@noindent +Sometimes the progress meter may cause disruption. It is up to the +user to decide whether the function should be defined and to use +@t{unfunction} when necessary. + +@end table + +@noindent + +@subsection Problems +@noindent +@cindex zftp, problems + +@noindent +A connection may not be opened in the left hand side of a pipe as this +occurs in a subshell and the file information is not updated in the main +shell. In the case of type or mode changes or closing the connection in a +subshell, the information is returned but variables are not updated until +the next call to @t{zftp}. Other status changes in subshells will not be +reflected by changes to the variables (but should be otherwise harmless). + +@noindent +Deleting sessions while a @t{zftp} command is active in the background can +have unexpected effects, even if it does not use the session being deleted. +This is because all shell subprocesses share information on the state of +all connections, and deleting a session changes the ordering of that +information. + +@noindent +On some operating systems, the control connection is not valid after a +fork(), so that operations in subshells, on the left hand side +of a pipeline, or in the background are not possible, as they should be. +This is presumably a bug in the operating system. +@c (avoiding a yodl bug) +@node The zsh/zle Module, The zsh/zleparameter Module, The zsh/zftp Module, Zsh Modules + +@section The zsh/zle Module +@noindent +@c Yodl file: Zsh/mod_zle.yo + +The @t{zsh/zle} module contains the Zsh Line Editor. See +@ref{Zsh Line Editor}. +@c (avoiding a yodl bug) +@node The zsh/zleparameter Module, The zsh/zprof Module, The zsh/zle Module, Zsh Modules + +@section The zsh/zleparameter Module +@noindent +@c Yodl file: Zsh/mod_zleparameter.yo + +@cindex parameters, special +The @t{zsh/zleparameter} module defines two special parameters that can be +used to access internal information of the Zsh Line Editor (see +@ref{Zsh Line Editor}). + +@noindent +@table @asis +@vindex keymaps +@item @t{keymaps} +This array contains the names of the keymaps currently defined. + +@vindex widgets +@item @t{widgets} +This associative array contains one entry per widget. The name +of the widget is the key and the value gives information about the +widget. It is either + the string `@t{builtin}' for builtin widgets, + a string of the form `@t{user:}@var{name}' for user-defined widgets, + where @var{name} is the name of the shell function implementing the widget, + a string of the form `@t{completion:}@var{type}@t{:}@var{name}' + for completion widgets, + or a null value if the widget is not yet fully defined. +In the penultimate case, @var{type} is the name of the builtin widget the +completion widget imitates in its behavior and @var{name} is the name +of the shell function implementing the completion widget. + +@end table +@c (avoiding a yodl bug) +@node The zsh/zprof Module, The zsh/zpty Module, The zsh/zleparameter Module, Zsh Modules + +@section The zsh/zprof Module +@noindent +@c Yodl file: Zsh/mod_zprof.yo + +@cindex functions, profiling +When loaded, the @t{zsh/zprof} causes shell functions to be profiled. +The profiling results can be obtained with the @t{zprof} +builtin command made available by this module. There is no way to turn +profiling off other than unloading the module. + +@noindent +@table @asis +@findex zprof +@item @t{zprof} [ @t{-c} ] +Without the @t{-c} option, @t{zprof} lists profiling results to +standard output. The format is comparable to that of commands like +@t{gprof}. + +@noindent +At the top there is a summary listing all functions that were called +at least once. This summary is sorted in decreasing order of the +amount of time spent in each. The lines contain +the number of the function in order, which is used in +other parts of the list in suffixes of the form +`@t{[}@var{num}@t{]}', then the number of calls made to the function. +The next three columns list the time in +milliseconds spent in the function and its descendants, the average +time in milliseconds spent in the function and its descendants per +call and the percentage of time spent in all shell functions used in +this function and its descendants. The following three columns give +the same information, but counting only the time spent in the function +itself. The final column shows the name of the function. + +@noindent +After the summary, detailed information about every function that was +invoked is listed, sorted in decreasing order of the amount of time spent +in each function and its descendants. Each of these entries consists of +descriptions for the functions that called the function described, the +function itself, and the functions that were called from it. The +description for the function itself has the same format as in the summary +(and shows the same information). The other lines don't show the number of +the function at the beginning and have their function named indented to +make it easier to distinguish the line showing the function described in +the section from the surrounding lines. + +@noindent +The information shown in this case is almost the same as in the summary, +but only refers to the call hierarchy being displayed. For example, for a +calling function the column showing the total running time lists the time +spent in the described function and its descendants only for the times when +it was called from that particular calling function. Likewise, for a +called function, this columns lists the total time spent in the called +function and its descendants only for the times when it was called from the +function described. + +@noindent +Also in this case, the column showing the number of calls to a function +also shows a slash and then the total number of invocations made to the +called function. + +@noindent +As long as the @t{zsh/zprof} module is loaded, profiling will be done and +multiple invocations of the @t{zprof} builtin command will show the +times and numbers of calls since the module was loaded. With the +@t{-c} option, the @t{zprof} builtin command will reset its internal +counters and will not show the listing. + +@end table +@c (avoiding a yodl bug) +@node The zsh/zpty Module, The zsh/zselect Module, The zsh/zprof Module, Zsh Modules + +@section The zsh/zpty Module +@noindent +@c Yodl file: Zsh/mod_zpty.yo + +The @t{zsh/zpty} module offers one builtin: + +@noindent +@table @asis +@findex zpty +@item @t{zpty} [ @t{-e} ] [ @t{-b} ] @var{name} [ @var{arg} ... ] +The arguments following @var{name} are concatenated with spaces between, +then executed as a command, as if passed to the @t{eval} builtin. The +command runs under a newly assigned pseudo-terminal; this is useful for +running commands non-interactively which expect an interactive +environment. The @var{name} is not part of the command, but is used to +refer to this command in later calls to @t{zpty}. + +@noindent +With the @t{-e} option, the pseudo-terminal is set up so that input +characters are echoed. + +@noindent +With the @t{-b} option, input to and output from the pseudo-terminal are +made non-blocking. + +@noindent +The shell parameter @t{REPLY} is set to the file descriptor assigned to +the master side of the pseudo-terminal. This allows the terminal to be +monitored with ZLE descriptor handlers (see @ref{Zle Builtins}) or manipulated with @t{sysread} and +@t{syswrite} (see @ref{The zsh/system Module}). @emph{Warning}: Use of @t{sysread} +and @t{syswrite} is @emph{not} recommended; use @t{zpty -r} and @t{zpty -w} +unless you know exactly what you are doing. + +@item @t{zpty} @t{-d} [ @var{name} ... ] +The second form, with the @t{-d} option, is used to delete commands +previously started, by supplying a list of their @var{name}s. If no +@var{name} is given, all commands are deleted. Deleting a command causes +the HUP signal to be sent to the corresponding process. + +@item @t{zpty} @t{-w} [ @t{-n} ] @var{name} [ @var{string} ... ] +The @t{-w} option can be used to send the to command @var{name} the given +@var{string}s as input (separated by spaces). If the @t{-n} option is +@emph{not} given, a newline is added at the end. + +@noindent +If no @var{string} is provided, the standard input is copied to the +pseudo-terminal; this may stop before copying the full input if the +pseudo-terminal is non-blocking. The exact input is always copied: +the @t{-n} option is not applied. + +@noindent +Note that the command under the pseudo-terminal sees this input as if it +were typed, so beware when sending special tty driver characters such as +word-erase, line-kill, and end-of-file. + +@item @t{zpty} @t{-r} [ @t{-mt} ] @var{name} [ @var{param} [ @var{pattern} ] ] +The @t{-r} option can be used to read the output of the command @var{name}. +With only a @var{name} argument, the output read is copied to the standard +output. Unless the pseudo-terminal is non-blocking, copying continues +until the command under the pseudo-terminal exits; when non-blocking, only +as much output as is immediately available is copied. The return status is +zero if any output is copied. + +@noindent +When also given a @var{param} argument, at most one line is read and stored +in the parameter named @var{param}. Less than a full line may be read if +the pseudo-terminal is non-blocking. The return status is zero if at least +one character is stored in @var{param}. + +@noindent +If a @var{pattern} is given as well, output is read until the whole string +read matches the @var{pattern}, even in the non-blocking case. The return +status is zero if the string read matches the pattern, or if the command +has exited but at least one character could still be read. If the option +@t{-m} is present, the return status is zero only if the pattern matches. +As of this writing, a maximum of one megabyte of output can be consumed +this way; if a full megabyte is read without matching the pattern, the +return status is non-zero. + +@noindent +In all cases, the return status is non-zero if nothing could be read, and +is @t{2} if this is because the command has finished. + +@noindent +If the @t{-r} option is combined with the @t{-t} option, @t{zpty} tests +whether output is available before trying to read. If no output is +available, @t{zpty} immediately returns the status @t{1}. When used +with a @var{pattern}, the behaviour on a failed poll is similar to +when the command has exited: the return value is zero if at least +one character could still be read even if the pattern failed to match. + +@item @t{zpty} @t{-t} @var{name} +The @t{-t} option without the @t{-r} option can be used to test +whether the command @var{name} is still running. It returns a zero +status if the command is running and a non-zero value otherwise. + +@item @t{zpty} [ @t{-L} ] +The last form, without any arguments, is used to list the commands +currently defined. If the @t{-L} option is given, this is done in the +form of calls to the @t{zpty} builtin. + +@end table +@c (avoiding a yodl bug) +@node The zsh/zselect Module, The zsh/zutil Module, The zsh/zpty Module, Zsh Modules + +@section The zsh/zselect Module +@noindent +@c Yodl file: Zsh/mod_zselect.yo + +The @t{zsh/zselect} module makes available one builtin command: + +@noindent +@table @asis +@findex zselect +@cindex select, system call +@cindex file descriptors, waiting for +@item @t{zselect} [ @t{-rwe} ] [ @t{-t} @var{timeout} ] [ @t{-a} @var{array} ] [ @t{-A} @var{assoc} ] [ @var{fd} ... ] +The @t{zselect} builtin is a front-end to the `select' system call, which +blocks until a file descriptor is ready for reading or writing, or has an +error condition, with an optional timeout. If this is not available on +your system, the command prints an error message and returns status 2 +(normal errors return status 1). For more information, see your systems +documentation for man page select(3). Note there is no connection with the +shell builtin of the same name. + +@noindent +Arguments and options may be intermingled in any order. Non-option +arguments are file descriptors, which must be decimal integers. By +default, file descriptors are to be tested for reading, i.e. @t{zselect} +will return when data is available to be read from the file descriptor, or +more precisely, when a read operation from the file descriptor will not +block. After a @t{-r}, @t{-w} and @t{-e}, the given file descriptors are +to be tested for reading, writing, or error conditions. These options and +an arbitrary list of file descriptors may be given in any order. + +@noindent +(The presence of an `error condition' is not well defined in the +documentation for many implementations of the select system call. +According to recent versions of the POSIX specification, it is really an +@emph{exception} condition, of which the only standard example is out-of-band +data received on a socket. So zsh users are unlikely to find the @t{-e} +option useful.) + +@noindent +The option `@t{-t} @var{timeout}' specifies a timeout in hundredths of a +second. This may be zero, in which case the file descriptors will simply +be polled and @t{zselect} will return immediately. It is possible to call +zselect with no file descriptors and a non-zero timeout for use as a +finer-grained replacement for `sleep'; note, however, the return status is +always 1 for a timeout. + +@noindent +The option `@t{-a} @var{array}' indicates that @var{array} should be set to +indicate the file descriptor(s) which are ready. If the option +is not +given, the array @t{reply} will be used for this purpose. The array will +contain a string similar to the arguments for @t{zselect}. For example, + +@noindent +@example +zselect -t 0 -r 0 -w 1 +@end example + +@noindent +might return immediately with status 0 and @t{$reply} containing `@t{-r 0 -w +1}' to show that both file descriptors are ready for the requested +operations. + +@noindent +The option `@t{-A} @var{assoc}' indicates that the associative array +@var{assoc} should be set to indicate the file descriptor(s) +which are ready. This option overrides the option @t{-a}, nor will +@t{reply} be modified. The keys of @t{assoc} are the file descriptors, and +the corresponding values are any of the characters `@t{rwe}' to indicate +the condition. + +@noindent +The command returns status 0 if some file descriptors are ready for +reading. If the operation timed out, or a timeout of 0 was given and no +file descriptors were ready, or there was an error, it returns status 1 and +the array will not be set (nor modified in any way). If there was an error +in the select operation the appropriate error message is printed. + +@end table +@c (avoiding a yodl bug) +@node The zsh/zutil Module, , The zsh/zselect Module, Zsh Modules + +@section The zsh/zutil Module +@noindent +@c Yodl file: Zsh/mod_zutil.yo + +@cindex builtins, utility +The @t{zsh/zutil} module only adds some builtins: + +@noindent +@table @asis +@findex zstyle +@item @t{zstyle} [ @t{-L} [ @var{metapattern} [ @var{style} ] ] ] +@itemx @t{zstyle} [ @t{-e} | @t{-} | @t{-}@t{-} ] @var{pattern} @var{style} @var{string} ... +@itemx @t{zstyle -d} [ @var{pattern} [ @var{style} ... ] ] +@itemx @t{zstyle -g} @var{name} [ @var{pattern} [ @var{style} ] ] +@itemx @t{zstyle -}@{@t{a}|@t{b}|@t{s}@} @var{context} @var{style} @var{name} [ @var{sep} ] +@itemx @t{zstyle -}@{@t{T}|@t{t}@} @var{context} @var{style} [ @var{string} ... ] +@itemx @t{zstyle -m} @var{context} @var{style} @var{pattern} +This builtin command is used to define and lookup styles. Styles are +pairs of names and values, where the values consist of any number of +strings. They are stored together with patterns and lookup is done by +giving a string, called the `@emph{context}', which is matched against the +patterns. The definition stored for the most specific pattern that matches +will be returned. + +@noindent +A pattern is considered to be more specific +than another if it contains more components (substrings separated by +colons) or if the patterns for the components are more specific, where +simple strings are considered to be more specific than patterns and +complex patterns are considered to be more specific than the pattern +`@t{*}'. A `@t{*}' in the pattern will match zero or more characters +in the context; colons are not treated specially in this regard. +If two patterns are equally specific, the tie is broken in favour of +the pattern that was defined first. + +@noindent +@emph{Example} + +@noindent +For example, to define your preferred form of precipitation depending on which +city you're in, you might set the following in your @t{zshrc}: + +@noindent +@example +zstyle ':weather:europe:*' preferred-precipitation rain +zstyle ':weather:europe:germany:* preferred-precipitation none +zstyle ':weather:europe:germany:*:munich' preferred-precipitation snow +@end example + +@noindent +Then, the fictional `@t{weather}' plugin might run under the hood a command +such as + +@noindent +@example +zstyle -s ":weather:$@{continent@}:$@{country@}:$@{county@}:$@{city@}" preferred-precipitation REPLY +@end example + +@noindent +in order to retrieve your preference into the scalar variable @t{$REPLY}. + +@noindent +@emph{Usage} + +@noindent +The forms that operate on patterns are the following. + +@noindent +@table @asis +@item @t{zstyle} [ @t{-L} [ @var{metapattern} [ @var{style} ] ] ] +Without arguments, lists style definitions. Styles +are shown in alphabetic order and patterns are shown in the order +@t{zstyle} will test them. + +@noindent +If the @t{-L} option is given, listing is done in the form of calls to +@t{zstyle}. The optional first argument, @var{metapattern}, is a pattern which +will be matched against the string supplied as @var{pattern} when the style was +defined. Note: +this means, for example, `@t{zstyle -L ":completion:*"}' will +match any supplied pattern beginning `@t{:completion:}', not +just @t{":completion:*"}: use @t{':completion:\*'} to match that. +The optional second argument limits the output to a specific @var{style} (not a +pattern). @t{-L} is not compatible with any other options. + +@item @t{zstyle} [ @t{-} | @t{-}@t{-} | @t{-e} ] @var{pattern} @var{style} @var{string} ... +@vindex reply, use of +Defines the given @var{style} for the @var{pattern} with the @var{string}s as +the value. If the @t{-e} option is given, the @var{string}s will be +concatenated (separated by spaces) and the resulting string will be +evaluated (in the same way as it is done by the @t{eval} builtin +command) when the style is looked up. In this case the parameter +`@t{reply}' must be assigned to set the strings returned after the +evaluation. Before evaluating the value, @t{reply} is unset, and +if it is still unset after the evaluation, the style is treated as if +it were not set. + +@item @t{zstyle -d} [ @var{pattern} [ @var{style} ... ] ] +Delete style definitions. Without arguments all definitions are deleted, +with a @var{pattern} all definitions for that pattern are deleted and if +any @var{style}s are given, then only those styles are deleted for the +@var{pattern}. + +@item @t{zstyle -g} @var{name} [ @var{pattern} [ @var{style} ] ] +Retrieve a style definition. The @var{name} is +used as the name of an array in which the results are stored. Without +any further arguments, all patterns defined are returned. With a +@var{pattern} the styles defined for that pattern are returned and with +both a @var{pattern} and a @var{style}, the value strings of that +combination is returned. + +@end table + +@noindent +The other forms can be used to look up or test styles for a given context. + +@noindent +@table @asis +@item @t{zstyle -s} @var{context} @var{style} @var{name} [ @var{sep} ] +The parameter @var{name} is set to the value of the style interpreted as a +string. If the value contains several strings they are concatenated with +spaces (or with the @var{sep} string if that is given) between them. + +@noindent +Return @t{0} if the style is set, @t{1} otherwise. + +@item @t{zstyle -b} @var{context} @var{style} @var{name} +The value is stored in @var{name} as a boolean, i.e. as the string +`@t{yes}' if the value has only one string and that string is equal to one +of `@t{yes}', `@t{true}', `@t{on}', or `@t{1}'. If the value is any other +string or has more than one string, the parameter is set to `@t{no}'. + +@noindent +Return @t{0} if @var{name} is set to `@t{yes}', @t{1} otherwise. + +@item @t{zstyle -a} @var{context} @var{style} @var{name} +The value is stored in @var{name} as an array. If @var{name} is declared +as an associative array, the first, third, etc. strings are used as the +keys and the other strings are used as the values. + +@noindent +Return @t{0} if the style is set, @t{1} otherwise. + +@item @t{zstyle -t} @var{context} @var{style} [ @var{string} ... ] +@itemx @t{zstyle -T} @var{context} @var{style} [ @var{string} ... ] +Test the value of a style, i.e. the @t{-t} option only returns a status +(sets @t{$?}). Without any @var{string} the return status is zero if the +style is defined for at least one matching pattern, has only one string in +its value, and that is equal to one of `@t{true}', `@t{yes}', `@t{on}' or +`@t{1}'. If any @var{string}s are given the status is zero if and only if +at least one of the @var{string}s is equal to at least one of the strings +in the value. If the style is defined but doesn't match, the return status +is @t{1}. If the style is not defined, the status is @t{2}. + +@noindent +The @t{-T} option tests the values of the style like @t{-t}, but it +returns status zero (rather than @t{2}) if the style is not defined for any +matching pattern. + +@item @t{zstyle -m} @var{context} @var{style} @var{pattern} +Match a value. Returns status zero if the +@var{pattern} matches at least one of the strings in the value. + +@end table + +@findex zformat +@item @t{zformat -f} @var{param} @var{format} @var{spec} ... +@itemx @t{zformat -a} @var{array} @var{sep} @var{spec} ... +This builtin provides two different forms of formatting. The first form +is selected with the @t{-f} option. In this case the @var{format} +string will be modified by replacing sequences starting with a percent +sign in it with strings from the @var{spec}s. Each @var{spec} should be +of the form `@var{char}@t{:}@var{string}' which will cause every +appearance of the sequence `@t{%}@var{char}' in @var{format} to be replaced +by the @var{string}. The `@t{%}' sequence may also contain optional +minimum and maximum field width specifications between the `@t{%}' and +the `@var{char}' in the form `@t{%}@var{min}@t{.}@var{max}@t{c}', +i.e. the minimum field width is given first and if the maximum field +width is used, it has to be preceded by a dot. Specifying a minimum field +width makes the result be padded with spaces to the right if the +@var{string} is shorter than the requested width. Padding to the left +can be achieved by giving a negative minimum field width. If a maximum +field width is specified, the @var{string} will be truncated after that +many characters. After all `@t{%}' sequences for the given @var{spec}s +have been processed, the resulting string is stored in the parameter +@var{param}. + +@noindent +The @t{%}-escapes also understand ternary expressions in the form used by +prompts. The @t{%} is followed by a `@t{(}' and then an ordinary +format specifier character as described above. There may be a set of +digits either before or after the `@t{(}'; these specify a test +number, which defaults to zero. Negative numbers are also allowed. An +arbitrary delimiter character follows the format specifier, which is +followed by a piece of `true' text, the delimiter character again, a piece +of `false' text, and a closing parenthesis. The complete expression +(without the digits) thus looks like +`@t{%(}@var{X}@t{.}@var{text1}@t{.}@var{text2}@t{)}', except that +the `@t{.}' character is arbitrary. The value given for the format +specifier in the @var{char}@t{:}@var{string} expressions is evaluated as a +mathematical expression, and compared with the test number. If they are +the same, @var{text1} is output, else @var{text2} is output. A parenthesis +may be escaped in @var{text2} as @t{%)}. Either of @var{text1} or +@var{text2} may contain nested @t{%}-escapes. + +@noindent +For example: + +@noindent +@example +zformat -f REPLY "The answer is '%3(c.yes.no)'." c:3 +@end example + +@noindent +outputs "The answer is 'yes'." to @t{REPLY} since the value for the format +specifier @t{c} is 3, agreeing with the digit argument to the ternary +expression. + +@noindent +The second form, using the @t{-a} option, can be used for aligning +strings. Here, the @var{spec}s are of the form +`@var{left}@t{:}@var{right}' where `@var{left}' and `@var{right}' are +arbitrary strings. These strings are modified by replacing the colons +by the @var{sep} string and padding the @var{left} strings with spaces +to the right so that the @var{sep} strings in the result (and hence the +@var{right} strings after them) are all aligned if the strings are +printed below each other. All strings without a colon are left +unchanged and all strings with an empty @var{right} string have the +trailing colon removed. In both cases the lengths of the strings +are not used to determine how the other strings are to be aligned. +A colon in the @var{left} string can be escaped with a backslash. +The resulting strings are stored in the @var{array}. + +@findex zregexparse +@item @t{zregexparse} +This implements some internals of the @t{_regex_arguments} function. + +@findex zparseopts +@item @t{zparseopts} [ @t{-D} @t{-E} @t{-F} @t{-K} @t{-M} ] [ @t{-a} @var{array} ] [ @t{-A} @var{assoc} ] [ @t{-} ] @var{spec} ... +This builtin simplifies the parsing of options in positional parameters, +i.e. the set of arguments given by @t{$*}. Each @var{spec} describes one +option and must be of the form `@var{opt}[@t{=}@var{array}]'. If an option +described by @var{opt} is found in the positional parameters it is copied +into the @var{array} specified with the @t{-a} option; if the optional +`@t{=}@var{array}' is given, it is instead copied into that array, which +should be declared as a normal array and never as an associative array. + +@noindent +Note that it is an error to give any @var{spec} without an +`@t{=}@var{array}' unless one of the @t{-a} or @t{-A} options is used. + +@noindent +Unless the @t{-E} option is given, parsing stops at the first string +that isn't described by one of the @var{spec}s. Even with @t{-E}, +parsing always stops at a positional parameter equal to `@t{-}' or +`@t{-}@t{-}'. See also @t{-F}. + +@noindent +The @var{opt} description must be one of the following. Any of the special +characters can appear in the option name provided it is preceded by a +backslash. + +@noindent +@table @asis +@item @var{name} +@itemx @var{name}@t{+} +The @var{name} is the name of the option without the leading `@t{-}'. To +specify a GNU-style long option, one of the usual two leading `@t{-}' must +be included in @var{name}; for example, a `@t{-}@t{-file}' option is +represented by a @var{name} of `@t{-file}'. + +@noindent +If a `@t{+}' appears after @var{name}, the option is appended to @var{array} +each time it is found in the positional parameters; without the `@t{+}' +only the @emph{last} occurrence of the option is preserved. + +@noindent +If one of these forms is used, the option takes no argument, so parsing +stops if the next positional parameter does not also begin with `@t{-}' +(unless the @t{-E} option is used). + +@item @var{name}@t{:} +@itemx @var{name}@t{:-} +@itemx @var{name}@t{::} +If one or two colons are given, the option takes an argument; with one +colon, the argument is mandatory and with two colons it is optional. The +argument is appended to the @var{array} after the option itself. + +@noindent +An optional argument is put into the same array element as the option name +(note that this makes empty strings as arguments indistinguishable). A +mandatory argument is added as a separate element unless the `@t{:-}' form +is used, in which case the argument is put into the same element. + +@noindent +A `@t{+}' as described above may appear between the @var{name} and the +first colon. + +@end table + +@noindent +In all cases, option-arguments must appear either immediately following the +option in the same positional parameter or in the next one. Even an optional +argument may appear in the next parameter, unless it begins with a `@t{-}'. +There is no special handling of `@t{=}' as with GNU-style argument parsers; +given the @var{spec} `@t{-foo:}', the positional parameter `@t{-}@t{-foo=bar}' +is parsed as `@t{-}@t{-foo}' with an argument of `@t{=bar}'. + +@noindent +When the names of two options that take no arguments overlap, the longest one +wins, so that parsing for the @var{spec}s `@t{-foo -foobar}' (for example) is +unambiguous. However, due to the aforementioned handling of option-arguments, +ambiguities may arise when at least one overlapping @var{spec} takes an +argument, as in `@t{-foo: -foobar}'. In that case, the last matching +@var{spec} wins. + +@noindent +The options of @t{zparseopts} itself cannot be stacked because, for +example, the stack `@t{-DEK}' is indistinguishable from a @var{spec} for +the GNU-style long option `@t{-}@t{-DEK}'. The options of @t{zparseopts} +itself are: + +@noindent +@table @asis +@item @t{-a} @var{array} +As described above, this names the default array in which to store the +recognised options. + +@item @t{-A} @var{assoc} +If this is given, the options and their values are also put into an +associative array with the option names as keys and the arguments (if any) +as the values. + +@item @t{-D} +If this option is given, all options found are removed from the positional +parameters of the calling shell or shell function, up to but not including +any not described by the @var{spec}s. If the first such parameter is `@t{-}' +or `@t{-}@t{-}', it is removed as well. This is similar to using the +@t{shift} builtin. + +@item @t{-E} +This changes the parsing rules to @emph{not} stop at the first string +that isn't described by one of the @var{spec}s. It can be used to test +for or (if used together with @t{-D}) extract options and their +arguments, ignoring all other options and arguments that may be in the +positional parameters. As indicated above, parsing still stops at the +first `@t{-}' or `@t{-}@t{-}' not described by a @var{spec}, but it is not +removed when used with @t{-D}. + +@item @t{-F} +If this option is given, @t{zparseopts} immediately stops at the first +option-like parameter not described by one of the @var{spec}s, prints an +error message, and returns status 1. Removal (@t{-D}) and extraction +(@t{-E}) are not performed, and option arrays are not updated. This +provides basic validation for the given options. + +@noindent +Note that the appearance in the positional parameters of an option without +its required argument always aborts parsing and returns an error as described +above regardless of whether this option is used. + +@item @t{-K} +With this option, the arrays specified with the @t{-a} option and with the +`@t{=}@var{array}' forms are kept unchanged when none of the @var{spec}s for +them is used. Otherwise the entire array is replaced when any of the +@var{spec}s is used. Individual elements of associative arrays specified +with the @t{-A} option are preserved by @t{-K}. This allows assignment of +default values to arrays before calling @t{zparseopts}. + +@item @t{-M} +This changes the assignment rules to implement a map among equivalent +option names. If any @var{spec} uses the `@t{=}@var{array}' form, the +string @var{array} is interpreted as the name of another @var{spec}, +which is used to choose where to store the values. If no other @var{spec} +is found, the values are stored as usual. This changes only the way the +values are stored, not the way @t{$*} is parsed, so results may be +unpredictable if the `@var{name}@t{+}' specifier is used inconsistently. + +@end table + +@noindent +For example, + +@noindent +@example +set -- -a -bx -c y -cz baz -cend +zparseopts a=foo b:=bar c+:=bar +@end example + +@noindent +will have the effect of + +@noindent +@example +foo=(-a) +bar=(-b x -c y -c z) +@end example + +@noindent +The arguments from `@t{baz}' on will not be used. + +@noindent +As an example for the @t{-E} option, consider: + +@noindent +@example +set -- -a x -b y -c z arg1 arg2 +zparseopts -E -D b:=bar +@end example + +@noindent +will have the effect of + +@noindent +@example +bar=(-b y) +set -- -a x -c z arg1 arg2 +@end example + +@noindent +I.e., the option @t{-b} and its arguments are taken from the +positional parameters and put into the array @t{bar}. + +@noindent +The @t{-M} option can be used like this: + +@noindent +@example +set -- -a -bx -c y -cz baz -cend +zparseopts -A bar -M a=foo b+: c:=b +@end example + +@noindent +to have the effect of + +@noindent +@example +foo=(-a) +bar=(-a @value{dsq} -b xyz) +@end example + +@end table +@c (avoiding a yodl bug) +@c (avoiding a yodl bug) +@c (avoiding a yodl bug) +@c Yodl file: Zsh/calsys.yo +@node Calendar Function System, TCP Function System, Zsh Modules, Top + +@chapter Calendar Function System +@noindent +@cindex calendar function system +@cindex zsh/datetime, function system based on + +@section Description +@noindent + +@noindent +The shell is supplied with a series of functions to replace and enhance the +traditional Unix @t{calendar} programme, which warns the user of imminent +or future events, details of which are stored in a text file (typically +@t{calendar} in the user's home directory). The version provided here +includes a mechanism for alerting the user when an event is due. + +@noindent +In addition functions @t{age}, @t{before} and @t{after} are provided +that can be used in a glob qualifier; they allow files to be selected +based on their modification times. + +@noindent +The format of the @t{calendar} file and the dates used there in and in +the @t{age} function are described first, then the functions that can +be called to examine and modify the @t{calendar} file. + +@noindent +The functions here depend on the availability of the @t{zsh/datetime} +module which is usually installed with the shell. The library function +@t{strptime()} must be available; it is present on most recent +operating systems. + +@noindent +@menu +* Calendar File and Date Formats:: +* Calendar System User Functions:: +* Calendar Styles:: +* Calendar Utility Functions:: +* Calendar Bugs:: +@end menu + +@noindent +@node Calendar File and Date Formats, Calendar System User Functions, , Calendar Function System + +@section File and Date Formats +@noindent + +@noindent + +@subsection Calendar File Format +@noindent + +@noindent +The calendar file is by default @t{~/calendar}. This can be configured +by the @t{calendar-file} style, see +@ref{Calendar Styles}. The basic format consists +of a series of separate lines, with no indentation, each including +a date and time specification followed by a description of the event. + +@noindent +Various enhancements to this format are supported, based on the syntax +of Emacs calendar mode. An indented line indicates a continuation line +that continues the description of the event from the preceding line +(note the date may not be continued in this way). An initial ampersand +(@t{&}) is ignored for compatibility. + +@noindent +An indented line on which the first non-whitespace character is @t{#} +is not displayed with the calendar entry, but is still scanned for +information. This can be used to hide information useful to the +calendar system but not to the user, such as the unique identifier +used by @t{calendar_add}. + +@noindent +The Emacs extension that a date with no description may refer to a number +of succeeding events at different times is not supported. + +@noindent +Unless the @t{done-file} style has been altered, any events which +have been processed are appended to the file with the same name as the +calendar file with the suffix @t{.done}, hence @t{~/calendar.done} by +default. + +@noindent +An example is shown below. + +@noindent + +@subsection Date Format +@noindent + +@noindent +The format of the date and time is designed to allow flexibility without +admitting ambiguity. (The words `date' and `time' are both used in the +documentation below; except where specifically noted this implies a string +that may include both a date and a time specification.) Note that there is +no localization support; month and day names must be in English and +separator characters are fixed. Matching is case insensitive, and only the +first three letters of the names are significant, although as a special +case a form beginning "month" does not match "Monday". Furthermore, time +zones are not handled; all times are assumed to be local. + +@noindent +It is recommended that, rather than exploring the intricacies of the +system, users find a date format that is natural to them and stick to it. +This will avoid unexpected effects. Various key facts should be noted. + +@noindent +@itemize @bullet + +@item +In particular, note the confusion between +@var{month}@t{/}@var{day}@t{/}@var{year} and +@var{day}@t{/}@var{month}@t{/}@var{year} when the month is numeric; these +formats should be avoided if at all possible. Many alternatives are +available. +@item +The year must be given in full to avoid confusion, and only years +from 1900 to 2099 inclusive are matched. +@end itemize + +@noindent +The following give some obvious examples; users finding here +a format they like and not subject to vagaries of style may skip +the full description. As dates and times are matched separately +(even though the time may be embedded in the date), any date format +may be mixed with any format for the time of day provide the +separators are clear (whitespace, colons, commas). + +@noindent +@example +2007/04/03 13:13 +2007/04/03:13:13 +2007/04/03 1:13 pm +3rd April 2007, 13:13 +April 3rd 2007 1:13 p.m. +Apr 3, 2007 13:13 +Tue Apr 03 13:13:00 2007 +13:13 2007/apr/3 +@end example + +@noindent +More detailed rules follow. + +@noindent +Times are parsed and extracted before dates. They must use colons +to separate hours and minutes, though a dot is allowed before seconds +if they are present. This limits time formats to the following: + +@noindent +@itemize @bullet + +@item +@var{HH}@t{:}@var{MM}[@t{:}@var{SS}[@t{.}@var{FFFFF}]] [@t{am}|@t{pm}|@t{a.m.}|@t{p.m.}] +@item +@var{HH}@t{:}@var{MM}@t{.}@var{SS}[@t{.}@var{FFFFF}] [@t{am}|@t{pm}|@t{a.m.}|@t{p.m.}] +@end itemize + +@noindent +Here, square brackets indicate optional elements, possibly with +alternatives. Fractions of a second are recognised but ignored. For +absolute times (the normal format require by the @t{calendar} file and the +@t{age}, @t{before} and @t{after} functions) a date is mandatory but a +time of day is not; the time returned is at the start of the date. One +variation is allowed: if @t{a.m.} or @t{p.m.} or one of their variants +is present, an hour without a minute is allowed, e.g. @t{3 p.m.}. + +@noindent +Time zones are not handled, though if one is matched following a time +specification it will be removed to allow a surrounding date to be +parsed. This only happens if the format of the timezone is not too +unusual. The following are examples of forms that are understood: + +@noindent +@example ++0100 +GMT +GMT-7 +CET+1CDT +@end example + +@noindent +Any part of the timezone that is not numeric must have exactly three +capital letters in the name. + +@noindent +Dates suffer from the ambiguity between @var{DD}@t{/}@var{MM}@t{/}@var{YYYY} +and @var{MM}@t{/}@var{DD}@t{/}@var{YYYY}. It is recommended this form is +avoided with purely numeric dates, but use of ordinals, +eg. @t{3rd/04/2007}, will resolve the ambiguity as the ordinal is always +parsed as the day of the month. Years must be four digits (and the first +two must be @t{19} or @t{20}); @t{03/04/08} is not recognised. Other +numbers may have leading zeroes, but they are not required. The following +are handled: + +@noindent +@itemize @bullet + +@item +@var{YYYY}@t{/}@var{MM}@t{/}@var{DD} +@item +@var{YYYY}@t{-}@var{MM}@t{-}@var{DD} +@item +@var{YYYY}@t{/}@var{MNM}@t{/}@var{DD} +@item +@var{YYYY}@t{-}@var{MNM}@t{-}@var{DD} +@item +@var{DD}[@t{th}|@t{st}|@t{rd}] @var{MNM}[@t{,}] [ @var{YYYY} ] +@item +@var{MNM} @var{DD}[@t{th}|@t{st}|@t{rd}][@t{,}] [ @var{YYYY} ] +@item +@var{DD}[@t{th}|@t{st}|@t{rd}]@t{/}@var{MM}[@t{,}] @var{YYYY} +@item +@var{DD}[@t{th}|@t{st}|@t{rd}]@t{/}@var{MM}@t{/}@var{YYYY} +@item +@var{MM}@t{/}@var{DD}[@t{th}|@t{st}|@t{rd}][@t{,}] @var{YYYY} +@item +@var{MM}@t{/}@var{DD}[@t{th}|@t{st}|@t{rd}]@t{/}@var{YYYY} +@end itemize + +@noindent +Here, @var{MNM} is at least the first three letters of a month name, +matched case-insensitively. The remainder of the month name may appear but +its contents are irrelevant, so janissary, febrile, martial, apricot, +maybe, junta, etc. are happily handled. + +@noindent +Where the year is shown as optional, the current year is assumed. There +are only two such cases, the form @t{Jun 20} or @t{14 September} (the only +two commonly occurring forms, apart from a "the" in some forms of English, +which isn't currently supported). Such dates will of course become +ambiguous in the future, so should ideally be avoided. + +@noindent +Times may follow dates with a colon, e.g. @t{1965/07/12:09:45}; this is in +order to provide a format with no whitespace. A comma and whitespace are +allowed, e.g. @t{1965/07/12, 09:45}. Currently the order of these +separators is not checked, so illogical formats such as @t{1965/07/12, : +,09:45} will also be matched. For simplicity such variations are not shown +in the list above. Otherwise, a time is only recognised as being +associated with a date if there is only whitespace in between, or if the +time was embedded in the date. + +@noindent +Days of the week are not normally scanned, but will be ignored if they +occur at the start of the date pattern only. However, in contexts where it +is useful to specify dates relative to today, days of the week with no +other date specification may be given. The day is assumed to be either +today or within the past week. Likewise, the words @t{yesterday}, +@t{today} and @t{tomorrow} are handled. All matches are case-insensitive. +Hence if today is Monday, then @t{Sunday} is equivalent to @t{yesterday}, +@t{Monday} is equivalent to @t{today}, but @t{Tuesday} gives a date six +days ago. This is not generally useful within the calendar file. +Dates in this format may be combined with a time specification; for +example @t{Tomorrow, 8 p.m.}. + +@noindent +For example, the standard date format: + +@noindent +@example +Fri Aug 18 17:00:48 BST 2006 +@end example + +@noindent +is handled by matching @var{HH}@t{:}@var{MM}@t{:}@var{SS} and removing it +together with the matched (but unused) time zone. This leaves the following: + +@noindent +@example +Fri Aug 18 2006 +@end example + +@noindent +@t{Fri} is ignored and the rest is matched according to the standard rules. + +@noindent + +@subsection Relative Time Format +@noindent + +@noindent +In certain places relative times are handled. Here, a date is not allowed; +instead a combination of various supported periods are allowed, together +with an optional time. The periods must be in order from most to +least significant. + +@noindent +In some cases, a more accurate calculation is possible when there is an +anchor date: offsets of months or years pick the correct day, rather than +being rounded, and it is possible to pick a particular day in a month as +`(1st Friday)', etc., as described in more detail below. + +@noindent +Anchors are available in the following cases. If one or two times are +passed to the function @t{calendar}, the start time acts an anchor for the +end time when the end time is relative (even if the start time is +implicit). When examining calendar files, the scheduled event being +examined anchors the warning time when it is given explicitly by means of +the @t{WARN} keyword; likewise, the scheduled event anchors a repetition +period when given by the @t{RPT} keyword, so that specifications such as +@t{RPT 2 months, 3rd Thursday} are handled properly. Finally, the @t{-R} +argument to @t{calendar_scandate} directly provides an anchor for relative +calculations. + +@noindent +The periods handled, with possible abbreviations are: + +@noindent +@table @asis +@item Years +@t{years}, @t{yrs}, @t{ys}, @t{year}, @t{yr}, @t{y}, @t{yearly}. +A year is 365.25 days unless there is an anchor. + +@item Months +@t{months}, @t{mons}, @t{mnths}, @t{mths}, @t{month}, @t{mon}, +@t{mnth}, @t{mth}, @t{monthly}. Note that @t{m}, @t{ms}, @t{mn}, @t{mns} +are ambiguous and are @emph{not} handled. A month is a period +of 30 days rather than a calendar month unless there is an anchor. + +@item Weeks +@t{weeks}, @t{wks}, @t{ws}, @t{week}, @t{wk}, @t{w}, @t{weekly} + +@item Days +@t{days}, @t{dys}, @t{ds}, @t{day}, @t{dy}, @t{d}, @t{daily} + +@item Hours +@t{hours}, @t{hrs}, @t{hs}, @t{hour}, @t{hr}, @t{h}, @t{hourly} + +@item Minutes +@t{minutes}, @t{mins}, @t{minute}, @t{min}, but @emph{not} @t{m}, +@t{ms}, @t{mn} or @t{mns} + +@item Seconds +@t{seconds}, @t{secs}, @t{ss}, @t{second}, @t{sec}, @t{s} + +@end table + +@noindent +Spaces between the numbers are optional, but are required between items, +although a comma may be used (with or without spaces). + +@noindent +The forms @t{yearly} to @t{hourly} allow the number to be omitted; it is +assumed to be 1. For example, @t{1 d} and @t{daily} are equivalent. Note +that using those forms with plurals is confusing; @t{2 yearly} is the same +as @t{2 years}, @emph{not} twice yearly, so it is recommended they only +be used without numbers. + +@noindent +When an anchor time is present, there is an extension to handle regular +events in the form of the @var{n}th @var{some}day of the month. Such a +specification must occur immediately after any year and month +specification, but before any time of day, and must be in the form +@var{n}(@t{th}|@t{st}|@t{rd}) @var{day}, for example @t{1st Tuesday} or +@t{3rd Monday}. As in other places, days are matched case insensitively, +must be in English, and only the first three letters are significant except +that a form beginning `month' does not match `Monday'. No attempt is made +to sanitize the resulting date; attempts to squeeze too many occurrences +into a month will push the day into the next month (but in the obvious +fashion, retaining the correct day of the week). + +@noindent +Here are some examples: + +@noindent +@example +30 years 3 months 4 days 3:42:41 +14 days 5 hours +Monthly, 3rd Thursday +4d,10hr +@end example + +@noindent + +@subsection Example +@noindent + +@noindent +Here is an example calendar file. It uses a consistent date format, +as recommended above. + +@noindent +@example +Feb 1, 2006 14:30 Pointless bureaucratic meeting +Mar 27, 2006 11:00 Mutual recrimination and finger pointing + Bring water pistol and waterproofs +Mar 31, 2006 14:00 Very serious managerial pontification + # UID 12C7878A9A50 +Apr 10, 2006 13:30 Even more pointless blame assignment exercise WARN 30 mins +May 18, 2006 16:00 Regular moaning session RPT monthly, 3rd Thursday +@end example + +@noindent +The second entry has a continuation line. The third entry has a +continuation line that will not be shown when the entry is displayed, but +the unique identifier will be used by the @t{calendar_add} function when +updating the event. The fourth entry will produce a warning 30 minutes +before the event (to allow you to equip yourself appropriately). The fifth +entry repeats after a month on the 3rd Thursday, i.e. June 15, 2006, at the +same time. + +@noindent +@node Calendar System User Functions, Calendar Styles, Calendar File and Date Formats, Calendar Function System + +@section User Functions +@noindent + +@noindent +This section describes functions that are designed to be called +directly by the user. The first part describes those functions +associated with the user's calendar; the second part describes +the use in glob qualifiers. + +@noindent + +@subsection Calendar system functions +@noindent + +@noindent +@table @asis +@findex calendar + +@item @t{calendar }[ @t{-abdDsv} ] [ @t{-C} @var{calfile} ] [ @t{-n} @var{num} ] [ @t{-S} @var{showprog} ] +@itemx @t{@ @ @ @ @ @ @ @ @ }[ [ @var{start} ] @var{end} ] +@itemx @t{calendar -r} [ @t{-abdDrsv} ] [ @t{-C} @var{calfile} ] [ @t{-n} @var{num} ] [ @t{-S} @var{showprog} ] +@itemx @t{@ @ @ @ @ @ @ @ @ }[ @var{start} ] +Show events in the calendar. + +@noindent +With no arguments, show events from the start of today until the end of +the next working day after today. In other words, if today is Friday, +Saturday, or Sunday, show up to the end of the following Monday, otherwise +show today and tomorrow. + +@noindent +If @var{end} is given, show events from the start of today up to the time +and date given, which is in the format described in the previous section. +Note that if this is a date the time is assumed to be midnight at the +start of the date, so that effectively this shows all events before +the given date. + +@noindent +@var{end} may start with a @t{+}, in which case the remainder of the +specification is a relative time format as described in the previous +section indicating the range of time from the start time that is to +be included. + +@noindent +If @var{start} is also given, show events starting from that time and date. +The word @t{now} can be used to indicate the current time. + +@noindent +To implement an alert when events are due, include @t{calendar -s} in your +@t{~/.zshrc} file. + +@noindent +Options: + +@noindent +@table @asis +@item @t{-a} +Show all items in the calendar, regardless of the @t{start} and +@t{end}. + +@item @t{-b} +Brief: don't display continuation lines (i.e. indented lines following +the line with the date/time), just the first line. + +@item @t{-B} @var{lines} +Brief: display at most the first @var{lines} lines of the calendar +entry. `@t{-B 1}' is equivalent to `@t{-b}'. + +@item @t{-C} @var{calfile} +Explicitly specify a calendar file instead of the value of +the @t{calendar-file} style or the default @t{~/calendar}. + +@item @t{-d} +Move any events that have passed from the calendar file to the +"done" file, as given by the @t{done-file} style or the default +which is the calendar file with @t{.done} appended. This option +is implied by the @t{-s} option. + +@item @t{-D} +Turns off the option @t{-d}, even if the @t{-s} option is also present. + +@item @t{-n} @var{num}, @t{-}@var{num} +Show at least @var{num} events, if present in the calendar file, regardless +of the @t{start} and @t{end}. + +@item @t{-r} +Show all the remaining options in the calendar, ignoring the given @var{end} +time. The @var{start} time is respected; any argument given is treated +as a @var{start} time. + +@item @t{-s} +Use the shell's @t{sched} command to schedule a timed event that +will warn the user when an event is due. Note that the @t{sched} command +only runs if the shell is at an interactive prompt; a foreground task +blocks the scheduled task from running until it is finished. + +@noindent +The timed event usually runs the programme @t{calendar_show} to show +the event, as described in +@ref{Calendar Utility Functions}. + +@noindent +By default, a warning of the event is shown five minutes before it is due. +The warning period can be configured by the style @t{warn-time} or +for a single calendar entry by including @t{WARN} @var{reltime} in the first +line of the entry, where @var{reltime} is one of the usual relative time +formats. + +@noindent +A repeated event may be indicated by including @t{RPT} @var{reldate} in the +first line of the entry. After the scheduled event has been displayed +it will be re-entered into the calendar file at a time @var{reldate} +after the existing event. Note that this is currently the only use +made of the repeat count, so that it is not possible to query the schedule +for a recurrence of an event in the calendar until the previous event +has passed. + +@noindent +If @t{RPT} is used, it is also possible to specify that certain +recurrences of an event are rescheduled or cancelled. This is +done with the @t{OCCURRENCE} keyword, followed by whitespace and the +date and time of the occurrence in the regular sequence, followed by +whitespace and either the date and time of the rescheduled event or +the exact string @t{CANCELLED}. In this case the date and time must +be in exactly the "date with local time" format used by the +@t{text/calendar} MIME type (RFC 2445), +@var{<YYYY><MM><DD>}@t{T}@var{<hh><mm><ss>} (note the presence of the literal +character @t{T}). The first word (the regular recurrence) may be +something other than a proper date/time to indicate that the event +is additional to the normal sequence; a convention that retains +the formatting appearance is @t{XXXXXXXXTXXXXXX}. + +@noindent +Furthermore, it is useful to record the next regular recurrence +(as then the displayed date may be for a rescheduled event so cannot +be used for calculating the regular sequence). This is specified by +@t{RECURRENCE} and a time or date in the same format. @t{calendar_add} +adds such an indication when it encounters a recurring event that does not +include one, based on the headline date/time. + +@noindent +If @t{calendar_add} is used to update occurrences the @t{UID} keyword +described there should be present in both the existing entry and the added +occurrence in order to identify recurring event sequences. + +@noindent +For example, + +@noindent +@example +Thu May 6, 2010 11:00 Informal chat RPT 1 week + # RECURRENCE 20100506T110000 + # OCCURRENCE 20100513T110000 20100513T120000 + # OCCURRENCE 20100520T110000 CANCELLED +@end example + +@noindent +The event that occurs at 11:00 on 13th May 2010 is rescheduled an hour +later. The event that occurs a week later is cancelled. The occurrences +are given on a continuation line starting with a @t{#} character so will +not usually be displayed as part of the event. As elsewhere, no account of +time zones is taken with the times. After the next event occurs the headline +date/time will be `@t{Thu May 13, 2010 12:00}' while the @t{RECURRENCE} +date/time will be `@t{20100513T110000}' (note that cancelled and +moved events are not taken account of in the @t{RECURRENCE}, which +records what the next regular recurrence is, but they are accounted for in +the headline date/time). + +@noindent +It is safe to run @t{calendar -s} to reschedule an existing event +(if the calendar file has changed, for example), and also to have it +running in multiples instances of the shell since the calendar file +is locked when in use. + +@noindent +By default, expired events are moved to the "done" file; see the @t{-d} +option. Use @t{-D} to prevent this. + +@item @t{-S} @var{showprog} +Explicitly specify a programme to be used for showing events instead +of the value of the @t{show-prog} style or the default @t{calendar_show}. + +@item @t{-v} +Verbose: show more information about stages of processing. This +is useful for confirming that the function has successfully parsed +the dates in the calendar file. + +@end table + +@findex calendar_add +@item @t{calendar_add} [ @t{-BL} ] @var{event} ... +Adds a single event to the calendar in the appropriate location. +The event can contain multiple lines, as described in +@ref{Calendar File and Date Formats}. +Using this function ensures that the calendar file is sorted in date +and time order. It also makes special arrangements for locking +the file while it is altered. The old calendar is left in a file +with the suffix @t{.old}. + +@noindent +The option @t{-B} indicates that backing up the calendar file will be +handled by the caller and should not be performed by @t{calendar_add}. The +option @t{-L} indicates that @t{calendar_add} does not need to lock the +calendar file as it is already locked. These options will not usually be +needed by users. + +@noindent +If the style @t{reformat-date} is true, the date and time of the +new entry will be rewritten into the standard date format: see +the descriptions of this style and the style @t{date-format}. + +@noindent +The function can use a unique identifier stored with each event to ensure +that updates to existing events are treated correctly. The entry +should contain the word @t{UID}, followed by whitespace, followed by +a word consisting entirely of hexadecimal digits of arbitrary length +(all digits are significant, including leading zeroes). As the UID +is not directly useful to the user, it is convenient to hide it on +an indented continuation line starting with a @t{#}, for example: + +@noindent +@example +Aug 31, 2007 09:30 Celebrate the end of the holidays + # UID 045B78A0 +@end example + +@noindent +The second line will not be shown by the @t{calendar} function. + +@noindent +It is possible to specify the @t{RPT} keyword followed by @t{CANCELLED} +instead of a relative time. This causes any matched event or series +of events to be cancelled (the original event does not have to be marked +as recurring in order to be cancelled by this method). A @t{UID} is +required in order to match an existing event in the calendar. + +@noindent +@t{calendar_add} will attempt to manage recurrences and occurrences of +repeating events as described for event scheduling by @t{calendar -s} +above. To reschedule or cancel a single event @t{calendar_add} should be +called with an entry that includes the correct @t{UID} but does @emph{not} +include the @t{RPT} keyword as this is taken to mean the entry applies to a +series of repeating events and hence replaces all existing information. +Each rescheduled or cancelled occurrence must have an @t{OCCURRENCE} +keyword in the entry passed to @t{calendar_add} which will be merged into +the calendar file. Any existing reference to the occurrence is replaced. +An occurrence that does not refer to a valid existing event is added as a +one-off occurrence to the same calendar entry. + +@findex calendar_edit +@item @t{calendar_edit} +This calls the user's editor to edit the calendar file. If +there are arguments, they are taken as the editor to use (the file name +is appended to the commands); otherwise, the editor is given by the +variable @t{VISUAL}, if set, else the variable @t{EDITOR}. + +@noindent +If the calendar scheduler was running, then after editing the file +@t{calendar -s} is called to update it. + +@noindent +This function locks out the calendar system during the edit. +Hence it should be used to edit the calendar file if there is any +possibility of a calendar event occurring meanwhile. Note this +can lead to another shell with calendar functions enabled hanging waiting +for a lock, so it is necessary to quit the editor as soon as possible. + +@findex calendar_parse +@item @t{calendar_parse} @var{calendar-entry} +This is the internal function that analyses the parts of a calendar +entry, which is passed as the only argument. The function returns +status 1 if the argument could not be parsed as a calendar entry +and status 2 if the wrong number of arguments were passed; it also sets the +parameter @t{reply} to an empty associative array. Otherwise, +it returns status 0 and sets elements of the associative +array @t{reply} as follows: + +@noindent +@table @asis +@item @t{time} +The time as a string of digits in the same units as +@t{$EPOCHSECONDS} +@item @t{schedtime} +The regularly scheduled time. This may differ from +the actual event time @t{time} if this is a recurring event and the next +occurrence has been rescheduled. Then @t{time} gives the actual time +and @t{schedtime} the time of the regular recurrence before modification. +@item @t{text1} +The text from the line not including the date and time of the +event, but including any @t{WARN} or @t{RPT} keywords and values. +@item @t{warntime} +Any warning time given by the @t{WARN} keyword as a string +of digits containing the time at which to warn in the same units as +@t{$EPOCHSECONDS}. (Note this is an absolute time, not the relative time +passed down.) Not set no @t{WARN} keyword and value were +matched. +@item @t{warnstr} +The raw string matched after the @t{WARN} keyword, else unset. +@item @t{rpttime} +Any recurrence time given by the @t{RPT} keyword as a string +of digits containing the time of the recurrence in the same units +as @t{$EPOCHSECONDS}. (Note this is an absolute time.) Not set if +no @t{RPT} keyword and value were matched. +@item @t{schedrpttime} +The next regularly scheduled occurrence of a recurring +event before modification. This may differ from @t{rpttime}, which is the +actual time of the event that may have been rescheduled from the regular +time. +@item @t{rptstr} +The raw string matched after the @t{RPT} keyword, else unset. +@item @t{text2} +The text from the line after removal of the date and any +keywords and values. + +@end table + +@noindent +@findex calendar_showdate +@item @t{calendar_showdate} [ @t{-r} ] [ @t{-f} @var{fmt} ] @var{date-spec} ... +The given @var{date-spec} is interpreted and the corresponding date and +time printed. If the initial @var{date-spec} begins with a @t{+} or +@t{-} it is treated as relative to the current time; @var{date-spec}s after +the first are treated as relative to the date calculated so far and +a leading @t{+} is optional in that case. This allows one to +use the system as a date calculator. For example, @t{calendar_showdate '+1 +month, 1st Friday'} shows the date of the first Friday of next month. + +@noindent +With the option @t{-r} nothing is printed but the value of the date and +time in seconds since the epoch is stored in the parameter @t{REPLY}. + +@noindent +With the option @t{-f} @var{fmt} the given date/time conversion format +is passed to @t{strftime}; see notes on the @t{date-format} style below. + +@noindent +In order to avoid ambiguity with negative relative date specifications, +options must occur in separate words; in other words, @t{-r} and @t{-f} +should not be combined in the same word. + +@findex calendar_sort +@item @t{calendar_sort} +Sorts the calendar file into date and time order. The old calendar is +left in a file with the suffix @t{.old}. + +@end table + +@noindent + +@subsection Glob qualifiers +@noindent + +@noindent +@table @asis +@item @t{age} +@findex age +The function @t{age} can be autoloaded and use separately from +the calendar system, although it uses the function @t{calendar_scandate} +for date formatting. It requires the @t{zsh/stat} builtin, but uses +only the builtin @t{zstat}. + +@noindent +@t{age} selects files having a given modification time for use +as a glob qualifier. The format of the date is the same as that +understood by the calendar system, described in +@ref{Calendar File and Date Formats}. + +@noindent +The function can take one or two arguments, which can be supplied either +directly as command or arguments, or separately as shell parameters. + +@noindent +@example +print *(e:age 2006/10/04 2006/10/09:) +@end example + +@noindent +The example above matches all files modified between the start of those +dates. The second argument may alternatively be a relative time +introduced by a @t{+}: + +@noindent +@example +print *(e:age 2006/10/04 +5d:) +@end example + +@noindent +The example above is equivalent to the previous example. + +@noindent +In addition to the special use of days of the week, @t{today} and +@t{yesterday}, times with no date may be specified; these apply to today. +Obviously such uses become problematic around midnight. + +@noindent +@example +print *(e-age 12:00 13:30-) +@end example + +@noindent +The example above shows files modified between 12:00 and 13:00 today. + +@noindent +@example +print *(e:age 2006/10/04:) +@end example + +@noindent +The example above matches all files modified on that date. If the second +argument is omitted it is taken to be exactly 24 hours after the first +argument (even if the first argument contains a time). + +@noindent +@example +print *(e-age 2006/10/04:10:15 2006/10/04:10:45-) +@end example + +@noindent +The example above supplies times. Note that whitespace within the time and +date specification must be quoted to ensure @t{age} receives the correct +arguments, hence the use of the additional colon to separate the date and +time. + +@noindent +@example +AGEREF=2006/10/04:10:15 +AGEREF2=2006/10/04:10:45 +print *(+age) +@end example + +@noindent +This shows the same example before using another form of argument +passing. The dates and times in the parameters @t{AGEREF} and @t{AGEREF2} +stay in effect until unset, but will be overridden if any argument is +passed as an explicit argument to age. Any explicit argument +causes both parameters to be ignored. + +@noindent +Instead of an explicit date and time, it's possible to use the +modification time of a file as the date and time for either argument +by introducing the file name with a colon: + +@noindent +@example +print *(e-age :file1-) +@end example + +@noindent +matches all files created on the same day (24 hours starting from +midnight) as @t{file1}. + +@noindent +@example +print *(e-age :file1 :file2-) +@end example + +@noindent +matches all files modified no earlier than @t{file1} and +no later than @t{file2}; precision here is to the nearest second. + +@item @t{after} +@itemx @t{before} +@findex after +@findex before +The functions @t{after} and @t{before} are simpler versions of @t{age} +that take just one argument. The argument is parsed similarly to an +argument of @t{age}; if it is not given the variable @t{AGEREF} is +consulted. As the names of the functions suggest, a file matches if its +modification time is after or before the time and date specified. If +a time only is given the date is today. + +@noindent +The two following examples are therefore equivalent: +@example +print *(e-after 12:00-) +print *(e-after today:12:00-) +@end example + +@end table + +@noindent +@node Calendar Styles, Calendar Utility Functions, Calendar System User Functions, Calendar Function System + +@section Styles +@noindent + +@noindent +The zsh style mechanism using the @t{zstyle} command is describe in +@ref{The zsh/zutil Module}. This is the same mechanism +used in the completion system. + +@noindent +The styles below are all examined in the context +@t{:datetime:}@var{function}@t{:}, for example @t{:datetime:calendar:}. + +@noindent +@table @asis +@kindex calendar-file +@item @t{calendar-file} +The location of the main calendar. The default is @t{~/calendar}. + +@kindex date-format +@item @t{date-format} +A @t{strftime} format string (see man page strftime(3)) with the zsh +extensions providing various numbers with no leading zero or space +if the number is a single digit as described for the +@t{%D@{}@var{string}@t{@}} prompt format in +@ref{Prompt Expansion}. + +@noindent +This is used for outputting dates in @t{calendar}, both to support +the @t{-v} option and when adding recurring events back to the calendar +file, and in @t{calendar_showdate} as the final output format. + +@noindent +If the style is not set, the default used is similar the standard system +format as output by the @t{date} command (also known as `ctime format'): +`@t{%a %b %d %H:%M:%S %Z %Y}'. + +@kindex done-file +@item @t{done-file} +The location of the file to which events which have passed are appended. +The default is the calendar file location with the suffix @t{.done}. +The style may be set to an empty string in which case a "done" file +will not be maintained. + +@kindex reformat-date +@item @t{reformat-date} +Boolean, used by @t{calendar_add}. If it is true, the date and time +of new entries added to the calendar will be reformatted to the format +given by the style @t{date-format} or its default. Only the date and +time of the event itself is reformatted; any subsidiary dates and times +such as those associated with repeat and warning times are left alone. + +@kindex show-prog +@item @t{show-prog} +The programme run by @t{calendar} for showing events. It will +be passed the start time and stop time of the events requested in seconds +since the epoch followed by the event text. Note that @t{calendar -s} uses +a start time and stop time equal to one another to indicate alerts +for specific events. + +@noindent +The default is the function @t{calendar_show}. + +@kindex warn-time +@item @t{warn-time} +The time before an event at which a warning will be displayed, if the +first line of the event does not include the text @t{EVENT} @var{reltime}. +The default is 5 minutes. + +@end table + +@noindent +@node Calendar Utility Functions, Calendar Bugs, Calendar Styles, Calendar Function System + +@section Utility functions +@noindent + +@noindent +@table @asis +@findex calendar_lockfiles +@item @t{calendar_lockfiles} +Attempt to lock the files given in the argument. To prevent +problems with network file locking this is done in an ad hoc fashion +by attempting to create a symbolic link to the file with the name +@var{file}@t{.lockfile}. No other system level functions are used +for locking, i.e. the file can be accessed and modified by any +utility that does not use this mechanism. In particular, the user is not +prevented from editing the calendar file at the same time unless +@t{calendar_edit} is used. + +@noindent +Three attempts are made to lock the file before giving up. If the module +@t{zsh/zselect} is available, the times of the attempts are jittered so that +multiple instances of the calling function are unlikely to retry at the +same time. + +@noindent +The files locked are appended to the array @t{lockfiles}, which should +be local to the caller. + +@noindent +If all files were successfully locked, status zero is returned, else status one. + +@noindent +This function may be used as a general file locking function, although +this will only work if only this mechanism is used to lock files. + +@findex calendar_read +@item @t{calendar_read} +This is a backend used by various other functions to parse the +calendar file, which is passed as the only argument. The array +@t{calendar_entries} is set to the list of events in the file; no +pruning is done except that ampersands are removed from the start of +the line. Each entry may contain multiple lines. + +@findex calendar_scandate +@item @t{calendar_scandate} +This is a generic function to parse dates and times that may be +used separately from the calendar system. The argument is a date +or time specification as described in +@ref{Calendar File and Date Formats}. The parameter @t{REPLY} +is set to the number of seconds since the epoch corresponding to that date +or time. By default, the date and time may occur anywhere within the given +argument. + +@noindent +Returns status zero if the date and time were successfully parsed, +else one. + +@noindent +Options: +@table @asis +@item @t{-a} +The date and time are anchored to the start of the argument; they +will not be matched if there is preceding text. + +@item @t{-A} +The date and time are anchored to both the start and end of the argument; +they will not be matched if the is any other text in the argument. + +@item @t{-d} +Enable additional debugging output. + +@item @t{-m} +Minus. When @t{-R} @var{anchor_time} is also given the relative time is +calculated backwards from @var{anchor_time}. + +@item @t{-r} +The argument passed is to be parsed as a relative time. + +@item @t{-R} @var{anchor_time} +The argument passed is to be parsed as a relative time. The time is +relative to @var{anchor_time}, a time in seconds since the epoch, +and the returned value is the absolute time corresponding to advancing +@var{anchor_time} by the relative time given. +This allows lengths of months to be correctly taken into account. If +the final day does not exist in the given month, the last day of the +final month is given. For example, if the anchor time is during 31st +January 2007 and the relative time is 1 month, the final time is the +same time of day during 28th February 2007. + +@item @t{-s} +In addition to setting @t{REPLY}, set @t{REPLY2} to the remainder of +the argument after the date and time have been stripped. This is +empty if the option @t{-A} was given. + +@item @t{-t} +Allow a time with no date specification. The date is assumed to be +today. The behaviour is unspecified if the iron tongue of midnight +is tolling twelve. + +@end table + +@findex calendar_show +@item @t{calendar_show} +The function used by default to display events. It accepts a start time +and end time for events, both in epoch seconds, and an event description. + +@noindent +The event is always printed to standard output. If the command line editor +is active (which will usually be the case) the command line will be +redisplayed after the output. + +@noindent +If the parameter @t{DISPLAY} is set and the start and end times are +the same (indicating a scheduled event), the function uses the +command @t{xmessage} to display a window with the event details. + +@end table + +@noindent +@node Calendar Bugs, , Calendar Utility Functions, Calendar Function System + +@section Bugs +@noindent + +@noindent +As the system is based entirely on shell functions (with a little support +from the @t{zsh/datetime} module) the mechanisms used are not as robust as +those provided by a dedicated calendar utility. Consequently the user +should not rely on the shell for vital alerts. + +@noindent +There is no @t{calendar_delete} function. + +@noindent +There is no localization support for dates and times, nor any support +for the use of time zones. + +@noindent +Relative periods of months and years do not take into account the variable +number of days. + +@noindent +The @t{calendar_show} function is currently hardwired to use @t{xmessage} +for displaying alerts on X Window System displays. This should be +configurable and ideally integrate better with the desktop. + +@noindent +@t{calendar_lockfiles} hangs the shell while waiting for a lock on a file. +If called from a scheduled task, it should instead reschedule the event +that caused it. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/tcpsys.yo +@node TCP Function System, Zftp Function System, Calendar Function System, Top + +@chapter TCP Function System +@noindent +@cindex TCP function system +@cindex ztcp, function system based on + +@section Description +@noindent + +@noindent +A module @t{zsh/net/tcp} is provided to provide network I/O over +TCP/IP from within the shell; see its description in +@ref{Zsh Modules}. This manual page describes a function suite based on the module. +If the module is installed, the functions are usually installed at the +same time, in which case they will be available for +autoloading in the default function search path. In addition to the +@t{zsh/net/tcp} module, the @t{zsh/zselect} module is used to implement +timeouts on read operations. For troubleshooting tips, consult the +corresponding advice for the @t{zftp} functions described in +@ref{Zftp Function System}. + +@noindent +There are functions corresponding to the basic I/O operations open, close, +read and send, named @t{tcp_open} etc., as well as a function +@t{tcp_expect} for pattern match analysis of data read as input. The +system makes it easy to receive data from and send data to multiple named +sessions at once. In addition, it can be linked with the shell's line +editor in such a way that input data is automatically shown at the +terminal. Other facilities available including logging, filtering and +configurable output prompts. + +@noindent +To use the system where it is available, it should be enough to +`@t{autoload -U tcp_open}' and run @t{tcp_open} as documented below to +start a session. The @t{tcp_open} function will autoload the remaining +functions. + +@noindent +@menu +* TCP Functions:: +* TCP Parameters:: +* TCP Examples:: +* TCP Bugs:: +@end menu + +@noindent +@node TCP Functions, TCP Parameters, , TCP Function System + +@section TCP User Functions +@noindent + +@noindent + +@subsection Basic I/O +@noindent + +@noindent +@table @asis +@findex tcp_open +@item @t{tcp_open} [ @t{-qz} ] @var{host port} [ @var{sess} ] +@itemx @t{tcp_open} [ @t{-qz} ] [ @t{-s} @var{sess} | @t{-l} @var{sess}[@t{,}...] ] ... +@itemx @t{tcp_open} [ @t{-qz} ] [ @t{-a} @var{fd} | @t{-f} @var{fd} ] [ @var{sess} ] +Open a new session. In the first and simplest form, open a TCP connection +to host @var{host} at port @var{port}; numeric and symbolic forms are +understood for both. + +@noindent +If @var{sess} is given, this becomes the name of the session which can be +used to refer to multiple different TCP connections. If @var{sess} is +not given, the function will invent a numeric name value (note this is +@emph{not} the same as the file descriptor to which the session is attached). +It is recommended that session names not include `funny' characters, where +funny characters are not well-defined but certainly do not include +alphanumerics or underscores, and certainly do include whitespace. + +@noindent +In the second case, one or more sessions to be opened are given by name. +A single session name is given after @t{-s} and a comma-separated list +after @t{-l}; both options may be repeated as many times as necessary. +A failure to open any session causes @t{tcp_open} to abort. +The host and port are read from the file @t{.ztcp_sessions} in the same +directory as the user's zsh initialisation files, i.e. usually the home +directory, but @t{$ZDOTDIR} if that is set. The file consists of lines +each giving a session name and the corresponding host and port, in that +order (note the session name comes first, not last), separated by +whitespace. + +@noindent +The third form allows passive and fake TCP connections. If the option +@t{-a} is used, its argument is a file descriptor open for listening for +connections. No function front-end is provided to open such a file +descriptor, but a call to `@t{ztcp -l} @var{port}' will create one with the +file descriptor stored in the parameter @t{$REPLY}. The listening port can +be closed with `@t{ztcp -c} @var{fd}'. A call to `@t{tcp_open -a} @var{fd}' +will block until a remote TCP connection is made to @var{port} on the local +machine. At this point, a session is created in the usual way and is +largely indistinguishable from an active connection created with one of the +first two forms. + +@noindent +If the option @t{-f} is used, its argument is a file descriptor which is +used directly as if it were a TCP session. How well the remainder of the +TCP function system copes with this depends on what actually underlies this +file descriptor. A regular file is likely to be unusable; a FIFO (pipe) of +some sort will work better, but note that it is not a good idea for two +different sessions to attempt to read from the same FIFO at once. + +@noindent +If the option @t{-q} is given with any of the three forms, @t{tcp_open} +will not print informational messages, although it will in any case exit +with an appropriate status. + +@noindent +If the line editor (zle) is in use, which is typically the case if the +shell is interactive, @t{tcp_open} installs a handler inside zle which +will check for new data at the same time as it checks for keyboard input. +This is convenient as the shell consumes no CPU time while waiting; the +test is performed by the operating system. Giving the option @t{-z} to +any of the forms of @t{tcp_open} prevents the handler from being +installed, so data must be read explicitly. Note, however, this is not +necessary for executing complete sets of send and read commands from a +function, as zle is not active at this point. Generally speaking, the +handler is only active when the shell is waiting for input at a command +prompt or in the @t{vared} builtin. The option has no effect if zle is not +active; `@t{[[ -o zle]]}' will test for this. + +@noindent +The first session to be opened becomes the current session and subsequent +calls to @t{tcp_open} do not change it. The current session is stored +in the parameter @t{$TCP_SESS}; see below for more detail about the +parameters used by the system. + +@noindent +The function @t{tcp_on_open}, if defined, is called when a session +is opened. See the description below. + +@findex tcp_close +@item @t{tcp_close} [ @t{-qn} ] [ @t{-a} | @t{-l} @var{sess}[@t{,}...] | @var{sess} ... ] +Close the named sessions, or the current session if none is given, +or all open sessions if @t{-a} is given. The options @t{-l} and @t{-s} are +both handled for consistency with @t{tcp_open}, although the latter is +redundant. + +@noindent +If the session being closed is the current one, @t{$TCP_SESS} is unset, +leaving no current session, even if there are other sessions still open. + +@noindent +If the session was opened with @t{tcp_open -f}, the file descriptor is +closed so long as it is in the range 0 to 9 accessible directly from the +command line. If the option @t{-n} is given, no attempt will be made to +close file descriptors in this case. The @t{-n} option is not used for +genuine @t{ztcp} session; the file descriptors are always closed with the +session. + +@noindent +If the option @t{-q} is given, no informational messages will be printed. + +@findex tcp_read + +@item @t{tcp_read }[ @t{-bdq} ] [ @t{-t} @var{TO} ] [ @t{-T} @var{TO} ] +@itemx @t{@ @ @ @ @ @ @ @ @ }[ @t{-a} | @t{-u} @var{fd}[@t{,}...] | @t{-l} @var{sess}[@t{,}...] | @t{-s} @var{sess} ... ] +Perform a read operation on the current session, or on a list of +sessions if any are given with @t{-u}, @t{-l} or @t{-s}, or all open +sessions if the option @t{-a} is given. Any of the @t{-u}, @t{-l} or +@t{-s} options may be repeated or mixed together. The @t{-u} option +specifies a file descriptor directly (only those managed by this system +are useful), the other two specify sessions as described for +@t{tcp_open} above. + +@noindent +The function checks for new data available on all the sessions listed. +Unless the @t{-b} option is given, it will not block waiting for new data. +Any one line of data from any of the available sessions will be read, +stored in the parameter @t{$TCP_LINE}, and displayed to standard output +unless @t{$TCP_SILENT} contains a non-empty string. When printed to +standard output the string @t{$TCP_PROMPT} will be shown at the start of +the line; the default form for this includes the name of the session being +read. See below for more information on these parameters. In this mode, +@t{tcp_read} can be called repeatedly until it returns status 2 which +indicates all pending input from all specified sessions has been handled. + +@noindent +With the option @t{-b}, equivalent to an infinite timeout, the function +will block until a line is available to read from one of the specified +sessions. However, only a single line is returned. + +@noindent +The option @t{-d} indicates that all pending input should be drained. In +this case @t{tcp_read} may process multiple lines in the manner given +above; only the last is stored in @t{$TCP_LINE}, but the complete set is +stored in the array @t{$tcp_lines}. This is cleared at the start of each +call to @t{tcp_read}. + +@noindent +The options @t{-t} and @t{-T} specify a timeout in seconds, which may be a +floating point number for increased accuracy. With @t{-t} the timeout is +applied before each line read. With @t{-T}, the timeout applies to the +overall operation, possibly including multiple read operations if the +option @t{-d} is present; without this option, there is no distinction +between @t{-t} and @t{-T}. + +@noindent +The function does not print informational messages, but if the option +@t{-q} is given, no error message is printed for a non-existent session. + +@noindent +A return status of 2 indicates a timeout or no data to read. Any other +non-zero return status indicates some error condition. + +@noindent +See @t{tcp_log} for how to control where data is sent by @t{tcp_read}. + +@findex tcp_send +@item @t{tcp_send} [ @t{-cnq} ] [ @t{-s} @var{sess} | @t{-l} @var{sess}[@t{,}...] ] @var{data} ... +@itemx @t{tcp_send} [ @t{-cnq} ] @t{-a} @var{data} ... +Send the supplied data strings to all the specified sessions in turn. The +underlying operation differs little from a `@t{print -r}' to the session's +file descriptor, although it attempts to prevent the shell from dying owing +to a @t{SIGPIPE} caused by an attempt to write to a defunct session. + +@noindent +The option @t{-c} causes @t{tcp_send} to behave like @t{cat}. It reads +lines from standard input until end of input and sends them in turn to the +specified session(s) exactly as if they were given as @var{data} +arguments to individual @t{tcp_send} commands. + +@noindent +The option @t{-n} prevents @t{tcp_send} from putting a newline at the end +of the data strings. + +@noindent +The remaining options all behave as for @t{tcp_read}. + +@noindent +The data arguments are not further processed once they have been passed to +@t{tcp_send}; they are simply passed down to @t{print -r}. + +@noindent +If the parameter @t{$TCP_OUTPUT} is a non-empty string and logging is +enabled then the data sent to each session will be echoed to the log +file(s) with @t{$TCP_OUTPUT} in front where appropriate, much +in the manner of @t{$TCP_PROMPT}. + +@end table + +@noindent + +@subsection Session Management +@noindent + +@noindent +@table @asis +@findex tcp_alias +@item @t{tcp_alias} [ @t{-q} ] @var{alias}@t{=}@var{sess} ... +@itemx @t{tcp_alias} [ @t{-q} ] [ @var{alias} ... ] +@itemx @t{tcp_alias} @t{-d} [ @t{-q} ] @var{alias} ... +This function is not particularly well tested. + +@noindent +The first form creates an alias for a session name; @var{alias} can then be +used to refer to the existing session @var{sess}. As many aliases may be +listed as required. + +@noindent +The second form lists any aliases specified, or all aliases if none. + +@noindent +The third form deletes all the aliases listed. The underlying sessions are +not affected. + +@noindent +The option @t{-q} suppresses an inconsistently chosen subset of error +messages. + +@findex tcp_log +@item @t{tcp_log} [ @t{-asc} ] [ @t{-n} | @t{-N} ] [ @var{logfile} ] +With an argument @var{logfile}, all future input from @t{tcp_read} will be +logged to the named file. Unless @t{-a} (append) is given, this file will +first be truncated or created empty. With no arguments, show the current +status of logging. + +@noindent +With the option @t{-s}, per-session logging is enabled. Input from +@t{tcp_read} is output to the file @var{logfile}@t{.}@var{sess}. As the +session is automatically discriminated by the filename, the contents are +raw (no @t{$TCP_PROMPT}). The option @t{-a} applies as above. +Per-session logging and logging of all data in one file are not mutually +exclusive. + +@noindent +The option @t{-c} closes all logging, both complete and per-session logs. + +@noindent +The options @t{-n} and @t{-N} respectively turn off or restore output of +data read by @t{tcp_read} to standard output; hence `@t{tcp_log -cn}' turns +off all output by @t{tcp_read}. + +@noindent +The function is purely a convenient front end to setting the parameters +@t{$TCP_LOG}, @t{$TCP_LOG_SESS}, @t{$TCP_SILENT}, which are described below. + +@findex tcp_rename +@item @t{tcp_rename} @var{old} @var{new} +Rename session @var{old} to session @var{new}. The old name becomes invalid. + +@findex tcp_sess +@item @t{tcp_sess} [ @var{sess} [ @var{command} [ @var{arg} ... ] ] ] +With no arguments, list all the open sessions and associated file +descriptors. The current session is marked with a star. For use in +functions, direct access to the parameters @t{$tcp_by_name}, @t{$tcp_by_fd} +and @t{$TCP_SESS} is probably more convenient; see below. + +@noindent +With a @var{sess} argument, set the current session to @var{sess}. +This is equivalent to changing @t{$TCP_SESS} directly. + +@noindent +With additional arguments, temporarily set the current session while +executing `@var{command} @var{arg} ...'. @var{command} is re-evaluated +so as to expand aliases etc., but the remaining @var{arg}s are passed +through as that appear to @t{tcp_sess}. The original session is restored +when @t{tcp_sess} exits. + +@end table + +@noindent + +@subsection Advanced I/O +@noindent + +@noindent +@table @asis +@findex tcp_command +@item @t{tcp_command} @var{send-option} ... @var{send-argument} ... +This is a convenient front-end to @t{tcp_send}. All arguments are passed +to @t{tcp_send}, then the function pauses waiting for data. While data is +arriving at least every @t{$TCP_TIMEOUT} (default 0.3) seconds, data is +handled and printed out according to the current settings. Status 0 is +always returned. + +@noindent +This is generally only useful for interactive use, to prevent the display +becoming fragmented by output returned from the connection. Within a +programme or function it is generally better to handle reading data by a +more explicit method. + +@findex tcp_expect + +@item @t{tcp_expect }[ @t{-q} ] [ @t{-p} @var{var} | @t{-P} @var{var} ] [ @t{-t} @var{TO} | @t{-T} @var{TO} ] +@itemx @t{@ @ @ @ @ @ @ @ @ @ @ }[ @t{-a} | @t{-s} @var{sess} | @t{-l} @var{sess}[@t{,}...] ] @var{pattern} ... +Wait for input matching any of the given @var{pattern}s from any of the +specified sessions. Input is ignored until an input line matches one of +the given patterns; at this point status zero is returned, the matching +line is stored in @t{$TCP_LINE}, and the full set of lines read during the +call to @t{tcp_expect} is stored in the array @t{$tcp_expect_lines}. + +@noindent +Sessions are specified in the same way as @t{tcp_read}: the default is to +use the current session, otherwise the sessions specified by @t{-a}, +@t{-s}, or @t{-l} are used. + +@noindent +Each @var{pattern} is a standard zsh extended-globbing pattern; note that it +needs to be quoted to avoid it being expanded immediately by filename +generation. It must match the full line, so to match a substring there +must be a `@t{*}' at the start and end. The line matched against includes +the @t{$TCP_PROMPT} added by @t{tcp_read}. It is possible to include the +globbing flags `@t{#b}' or `@t{#m}' in the patterns to make backreferences +available in the parameters @t{$MATCH}, @t{$match}, etc., as described in +the base zsh documentation on pattern matching. + +@noindent +Unlike @t{tcp_read}, the default behaviour of @t{tcp_expect} is to block +indefinitely until the required input is found. This can be modified by +specifying a timeout with @t{-t} or @t{-T}; these function as in +@t{tcp_read}, specifying a per-read or overall timeout, respectively, in +seconds, as an integer or floating-point number. As @t{tcp_read}, the +function returns status 2 if a timeout occurs. + +@noindent +The function returns as soon as any one of the patterns given match. If +the caller needs to know which of the patterns matched, the option @t{-p} +@var{var} can be used; on return, @t{$var} is set to the number of the +pattern using ordinary zsh indexing, i.e. the first is 1, and so on. Note +the absence of a `@t{$}' in front of @var{var}. To avoid clashes, the +parameter cannot begin with `@t{_expect}'. The index -1 is used if +there is a timeout and 0 if there is no match. + +@noindent +The option @t{-P} @var{var} works similarly to @t{-p}, but instead of +numerical indexes the regular arguments must begin with a prefix +followed by a colon: that prefix is then used as a tag to which @var{var} +is set when the argument matches. The tag @t{timeout} is used if there +is a timeout and the empty string if there is no match. Note it is +acceptable for different arguments to start with the same prefix if the +matches do not need to be distinguished. + +@noindent +The option @t{-q} is passed directly down to @t{tcp_read}. + +@noindent +As all input is done via @t{tcp_read}, all the usual rules about output of +lines read apply. One exception is that the parameter @t{$tcp_lines} will +only reflect the line actually matched by @t{tcp_expect}; use +@t{$tcp_expect_lines} for the full set of lines read during the function +call. + +@findex tcp_proxy +@item @t{tcp_proxy} +This is a simple-minded function to accept a TCP connection and execute a +command with I/O redirected to the connection. Extreme caution should be +taken as there is no security whatsoever and this can leave your computer +open to the world. Ideally, it should only be used behind a firewall. + +@noindent +The first argument is a TCP port on which the function will listen. + +@noindent +The remaining arguments give a command and its arguments to execute with +standard input, standard output and standard error redirected to the +file descriptor on which the TCP session has been accepted. +If no command is given, a new zsh is started. This gives everyone on +your network direct access to your account, which in many cases will be a +bad thing. + +@noindent +The command is run in the background, so @t{tcp_proxy} can then accept new +connections. It continues to accept new connections until interrupted. + +@findex tcp_spam +@item @t{tcp_spam} [ @t{-ertv} ] [ @t{-a} | @t{-s} @var{sess} | @t{-l} @var{sess}[@t{,}...] ] @var{cmd} [ @var{arg} ... ] +Execute `@var{cmd} [ @var{arg} ... ]' for each session in turn. Note this executes +the command and arguments; it does not send the command line as data +unless the @t{-t} (transmit) option is given. + +@noindent +The sessions may be selected explicitly with the standard @t{-a}, @t{-s} or +@t{-l} options, or may be chosen implicitly. If none of the three options +is given the rules are: first, if the array @t{$tcp_spam_list} is set, this +is taken as the list of sessions, otherwise all sessions are taken. +Second, any sessions given in the array @t{$tcp_no_spam_list} are removed +from the list of sessions. + +@noindent +Normally, any sessions added by the `@t{-a}' flag or when all sessions are +chosen implicitly are spammed in alphabetic order; sessions given by the +@t{$tcp_spam_list} array or on the command line are spammed in the order +given. The @t{-r} flag reverses the order however it was arrived it. + +@noindent +The @t{-v} flag specifies that a @t{$TCP_PROMPT} will be output before each +session. This is output after any modification to @t{TCP_SESS} by the +user-defined @t{tcp_on_spam} function described below. (Obviously that +function is able to generate its own output.) + +@noindent +If the option @t{-e} is present, the line given as `@var{cmd} [ @var{arg} ... ]' is executed +using @t{eval}, otherwise it is executed without any further processing. + +@findex tcp_talk +@item @t{tcp_talk} +This is a fairly simple-minded attempt to force input to the line editor to +go straight to the default @t{TCP_SESS}. + +@noindent +An escape string, @t{$TCP_TALK_ESCAPE}, default `@t{:}', is used to allow +access to normal shell operation. If it is on its own at the start of the +line, or followed only by whitespace, the line editor returns to normal +operation. Otherwise, the string and any following whitespace are skipped +and the remainder of the line executed as shell input without any change of +the line editor's operating mode. + +@noindent +The current implementation is somewhat deficient in terms of use of the +command history. For this reason, many users will prefer to use some form +of alternative approach for sending data easily to the current session. +One simple approach is to alias some special character (such as `@t{%}') to +`@t{tcp_command -}@t{-}'. + +@findex tcp_wait +@item @t{tcp_wait} +The sole argument is an integer or floating point number which gives the +seconds to delay. The shell will do nothing for that period except wait +for input on all TCP sessions by calling @t{tcp_read -a}. This is similar +to the interactive behaviour at the command prompt when zle handlers are +installed. + +@end table + +@noindent + +@subsection `One-shot' file transfer +@noindent +@table @asis +@item @t{tcp_point} @var{port} +@itemx @t{tcp_shoot} @var{host} @var{port} +This pair of functions provide a simple way to transfer a file between +two hosts within the shell. Note, however, that bulk data transfer is +currently done using @t{cat}. @t{tcp_point} reads any data arriving at +@var{port} and sends it to standard output; @t{tcp_shoot} connects to +@var{port} on @var{host} and sends its standard input. Any unused @var{port} +may be used; the standard mechanism for picking a port is to think of a +random four-digit number above 1024 until one works. + +@noindent +To transfer a file from host @t{woodcock} to host @t{springes}, on +@t{springes}: + +@noindent +@example +tcp_point 8091 >output_file +@end example + +@noindent +and on @t{woodcock}: + +@noindent +@example +tcp_shoot springes 8091 <input_file +@end example + +@noindent +As these two functions do not require @t{tcp_open} to set up a TCP +connection first, they may need to be autoloaded separately. + +@end table + +@noindent + +@section TCP User-defined Functions +@noindent + +@noindent +Certain functions, if defined by the user, will be called by the function +system in certain contexts. This facility depends on the module +@t{zsh/parameter}, which is usually available in interactive shells as the +completion system depends on it. None of the functions need be defined; +they simply provide convenient hooks when necessary. + +@noindent +Typically, these are called after the requested action has been taken, so +that the various parameters will reflect the new state. + +@noindent +@table @asis +@findex tcp_on_alias +@item @t{tcp_on_alias} @var{alias} @var{fd} +When an alias is defined, this function will be called with two arguments: +the name of the alias, and the file descriptor of the corresponding session. + +@findex tcp_on_awol +@item @t{tcp_on_awol} @var{sess} @var{fd} +If the function @t{tcp_fd_handler} is handling input from the line +editor and detects that the file descriptor is no longer reusable, +by default it removes it from the list of file descriptors handled +by this method and prints a message. If the function @t{tcp_on_awol} +is defined it is called immediately before this point. It may +return status 100, which indicates that the normal handling should +still be performed; any other return status indicates that no further +action should be taken and the @t{tcp_fd_handler} should return +immediately with the given status. Typically the action of @t{tcp_on_awol} +will be to close the session. + +@noindent +The variable @t{TCP_INVALIDATE_ZLE} will be a non-empty string if it is +necessary to invalidate the line editor display using `@t{zle -I}' before +printing output from the function. + +@noindent +(`AWOL' is military jargon for `absent without leave' or some +variation. It has no pre-existing technical meaning known to the author.) + +@findex tcp_on_close +@item @t{tcp_on_close} @var{sess} @var{fd} +This is called with the name of a session being closed and the file +descriptor which corresponded to that session. Both will be invalid by +the time the function is called. + +@findex tcp_on_open +@item @t{tcp_on_open} @var{sess} @var{fd} +This is called after a new session has been defined with the session name +and file descriptor as arguments. If it returns a non-zero status, +opening the session is assumed to fail and the session is closed +again; however, @t{tcp_open} will continue to attempt to open any +remaining sessions given on the command line. + +@findex tcp_on_rename +@item @t{tcp_on_rename} @var{oldsess} @var{fd} @var{newsess} +This is called after a session has been renamed with the three arguments +old session name, file descriptor, new session name. + +@findex tcp_on_spam +@item @t{tcp_on_spam} @var{sess} @var{command ...} +This is called once for each session spammed, just @emph{before} a command is +executed for a session by @t{tcp_spam}. The arguments are the session name +followed by the command list to be executed. If @t{tcp_spam} was called +with the option @t{-t}, the first command will be @t{tcp_send}. + +@noindent +This function is called after @t{$TCP_SESS} is set to reflect the session +to be spammed, but before any use of it is made. Hence it is possible to +alter the value of @t{$TCP_SESS} within this function. For example, the +session arguments to @t{tcp_spam} could include extra information to be +stripped off and processed in @t{tcp_on_spam}. + +@noindent +If the function sets the parameter @t{$REPLY} to `@t{done}', the command +line is not executed; in addition, no prompt is printed for the @t{-v} +option to @t{tcp_spam}. + +@findex tcp_on_unalias +@item @t{tcp_on_unalias} @var{alias} @var{fd} +This is called with the name of an alias and the corresponding session's +file descriptor after an alias has been deleted. + +@end table + +@noindent + +@section TCP Utility Functions +@noindent + +@noindent +The following functions are used by the TCP function system but will rarely +if ever need to be called directly. + +@noindent +@table @asis +@findex tcp_fd_handler +@item @t{tcp_fd_handler} +This is the function installed by @t{tcp_open} for handling input from +within the line editor, if that is required. It is in the format +documented for the builtin `@t{zle -F}' in +@ref{Zle Builtins} +. + +@noindent +While active, the function sets the parameter @t{TCP_HANDLER_ACTIVE} to 1. +This allows shell code called internally (for example, by setting +@t{tcp_on_read}) to tell if is being called when the shell is otherwise +idle at the editor prompt. + +@findex tcp_output +@item @t{tcp_output} [ @t{-q} ] @t{-P} @var{prompt} @t{-F} @var{fd} @t{-S} @var{sess} +This function is used for both logging and handling output to standard +output, from within @t{tcp_read} and (if @t{$TCP_OUTPUT} is set) +@t{tcp_send}. + +@noindent +The @var{prompt} to use is specified by @t{-P}; the default is the empty +string. It can contain: +@table @asis +@item @t{%c} +Expands to 1 if the session is the current session, otherwise 0. Used +with ternary expressions such as `@t{%(c.-.+)}' to +output `@t{+}' for the current session and `@t{-}' otherwise. + +@item @t{%f} +Replaced by the session's file descriptor. + +@item @t{%s} +Replaced by the session name. + +@item @t{%%} +Replaced by a single `@t{%}'. + +@end table + +@noindent +The option @t{-q} suppresses output to standard output, but not to any log +files which are configured. + +@noindent +The @t{-S} and @t{-F} options are used to pass in the session name and file +descriptor for possible replacement in the prompt. + +@end table + +@noindent +@node TCP Parameters, TCP Examples, TCP Functions, TCP Function System + +@section TCP User Parameters +@noindent + +@noindent +Parameters follow the usual convention that uppercase is used for scalars +and integers, while lowercase is used for normal and associative array. +It is always safe for user code to read these parameters. Some parameters +may also be set; these are noted explicitly. Others are included in this +group as they are set by the function system for the user's benefit, +i.e. setting them is typically not useful but is benign. + +@noindent +It is often also useful to make settable parameters local to a function. +For example, `@t{local TCP_SILENT=1}' specifies that data read during the +function call will not be printed to standard output, regardless of the +setting outside the function. Likewise, `@t{local TCP_SESS=}@var{sess}' +sets a session for the duration of a function, and `@t{local +TCP_PROMPT=}' specifies that no prompt is used for input during the +function. + +@noindent +@table @asis +@vindex tcp_expect_lines +@item @t{tcp_expect_lines} +Array. The set of lines read during the last call to @t{tcp_expect}, +including the last (@t{$TCP_LINE}). + +@vindex tcp_filter +@item @t{tcp_filter} +Array. May be set directly. A set of extended globbing patterns which, +if matched in @t{tcp_output}, will cause the line not to be printed to +standard output. The patterns should be defined as described for the +arguments to @t{tcp_expect}. Output of line to log files is not affected. + +@vindex TCP_HANDLER_ACTIVE +@item @t{TCP_HANDLER_ACTIVE} +Scalar. Set to 1 within @t{tcp_fd_handler} to indicate to functions +called recursively that they have been called during an editor session. +Otherwise unset. + +@vindex TCP_LINE +@item @t{TCP_LINE} +The last line read by @t{tcp_read}, and hence also @t{tcp_expect}. + +@vindex TCP_LINE_FD +@item @t{TCP_LINE_FD} +The file descriptor from which @t{$TCP_LINE} was read. +@t{$@{tcp_by_fd[$TCP_LINE_FD]@}} will give the corresponding session name. + +@vindex tcp_lines +@item @t{tcp_lines} +Array. The set of lines read during the last call to @t{tcp_read}, +including the last (@t{$TCP_LINE}). + +@vindex TCP_LOG +@item @t{TCP_LOG} +May be set directly, although it is also controlled by @t{tcp_log}. +The name of a file to which output from all sessions will be sent. +The output is proceeded by the usual @t{$TCP_PROMPT}. If it is not an +absolute path name, it will follow the user's current directory. + +@findex TCP_LOG_SESS +@item @t{TCP_LOG_SESS} +May be set directly, although it is also controlled by @t{tcp_log}. +The prefix for a set of files to which output from each session separately +will be sent; the full filename is @t{$@{TCP_LOG_SESS@}.}@var{sess}. +Output to each file is raw; no prompt is added. If it is not an absolute +path name, it will follow the user's current directory. + +@vindex tcp_no_spam_list +@item @t{tcp_no_spam_list} +Array. May be set directly. See @t{tcp_spam} for how this is used. + +@vindex TCP_OUTPUT +@item @t{TCP_OUTPUT} +May be set directly. If a non-empty string, any data sent to a session by +@t{tcp_send} will be logged. This parameter gives the prompt to be used +in a file specified by @t{$TCP_LOG} but not in a file generated from +@t{$TCP_LOG_SESS}. The prompt string has the same format as +@t{TCP_PROMPT} and the same rules for its use apply. + +@vindex TCP_PROMPT +@item @t{TCP_PROMPT} +May be set directly. Used as the prefix for data read by @t{tcp_read} +which is printed to standard output or to the log file given by +@t{$TCP_LOG}, if any. Any `@t{%s}', `@t{%f}' or `@t{%%}' occurring in the +string will be replaced by the name of the session, the session's +underlying file descriptor, or a single `@t{%}', respectively. The +expression `@t{%c}' expands to 1 if the session being read is the current +session, else 0; this is most useful in ternary expressions such as +`@t{%(c.-.+)}' which outputs `@t{+}' if the session is +the current one, else `@t{-}'. + +@noindent +If the prompt starts with @t{%P}, this is stripped and the complete +result of the previous stage is passed through standard prompt @t{%}-style +formatting before being output. + +@vindex TCP_READ_DEBUG +@item @t{TCP_READ_DEBUG} +May be set directly. If this has non-zero length, @t{tcp_read} will give +some limited diagnostics about data being read. + +@vindex TCP_SECONDS_START +@item @t{TCP_SECONDS_START} +This value is created and initialised to zero by tcp_open. + +@noindent +The functions @t{tcp_read} and @t{tcp_expect} use the shell's +@t{SECONDS} parameter for their own timing purposes. If that parameter +is not of floating point type on entry to one of the functions, it will +create a local parameter @t{SECONDS} which is floating point and set the +parameter @t{TCP_SECONDS_START} to the previous value of @t{$SECONDS}. +If the parameter is already floating point, it is used without a local +copy being created and @t{TCP_SECONDS_START} is not set. As the global +value is zero, the shell elapsed time is guaranteed to be the sum of +@t{$SECONDS} and @t{$TCP_SECONDS_START}. + +@noindent +This can be avoided by setting @t{SECONDS} globally to a floating point +value using `@t{typeset -F SECONDS}'; then the TCP functions will never +make a local copy and never set @t{TCP_SECONDS_START} to a non-zero value. + +@vindex TCP_SESS +@item @t{TCP_SESS} +May be set directly. The current session; must refer to one of the +sessions established by @t{tcp_open}. + +@vindex TCP_SILENT +@item @t{TCP_SILENT} +May be set directly, although it is also controlled by @t{tcp_log}. +If of non-zero length, data read by @t{tcp_read} will not be written to +standard output, though may still be written to a log file. + +@vindex tcp_spam_list +@item @t{tcp_spam_list} +Array. May be set directly. See the description of the function +@t{tcp_spam} for how this is used. + +@vindex TCP_TALK_ESCAPE +@item @t{TCP_TALK_ESCAPE} +May be set directly. See the description of the function @t{tcp_talk} for +how this is used. + +@vindex TCP_TIMEOUT +@item @t{TCP_TIMEOUT} +May be set directly. Currently this is only used by the function +@t{tcp_command}, see above. + +@end table + +@noindent + +@section TCP User-defined Parameters +@noindent + +@noindent +The following parameters are not set by the function system, but have +a special effect if set by the user. + +@noindent +@table @asis +@vindex tcp_on_read +@item @t{tcp_on_read} +This should be an associative array; if it is not, the behaviour is +undefined. Each key is the name of a shell function or other command, +and the corresponding value is a shell pattern (using @t{EXTENDED_GLOB}). +Every line read from a TCP session directly or indirectly using +@t{tcp_read} (which includes lines read by @t{tcp_expect}) is compared +against the pattern. If the line matches, the command given in the key is +called with two arguments: the name of the session from which the line was +read, and the line itself. + +@noindent +If any function called to handle a line returns a non-zero status, the +line is not output. Thus a @t{tcp_on_read} handler containing only +the instruction `@t{return 1}' can be used to suppress output of +particular lines (see, however, @t{tcp_filter} above). However, the line +is still stored in @t{TCP_LINE} and @t{tcp_lines}; this occurs after all +@t{tcp_on_read} processing. + +@end table + +@noindent + +@section TCP Utility Parameters +@noindent + +@noindent +These parameters are controlled by the function system; they may be read +directly, but should not usually be set by user code. + +@noindent +@table @asis +@findex tcp_aliases +@item @t{tcp_aliases} +Associative array. The keys are the names of sessions established with +@t{tcp_open}; each value is a space-separated list of aliases which refer +to that session. + +@findex tcp_by_fd +@item @t{tcp_by_fd} +Associative array. The keys are session file descriptors; each +value is the name of that session. + +@findex tcp_by_name +@item @t{tcp_by_name} +Associative array. The keys are the names of sessions; each value is the +file descriptor associated with that session. + +@end table + +@noindent +@node TCP Examples, TCP Bugs, TCP Parameters, TCP Function System + +@section TCP Examples +@noindent + +@noindent +Here is a trivial example using a remote calculator. + +@noindent +To create a calculator server on port 7337 (see the @t{dc} manual page for +quite how infuriating the underlying command is): + +@noindent +@example +tcp_proxy 7337 dc +@end example + +@noindent +To connect to this from the same host with a session also named `@t{dc}': + +@noindent +@example +tcp_open localhost 7337 dc +@end example + +@noindent +To send a command to the remote session and wait a short while for output +(assuming @t{dc} is the current session): + +@noindent +@example +tcp_command 2 4 + p +@end example + +@noindent +To close the session: + +@noindent +@example +tcp_close +@end example + +@noindent +The @t{tcp_proxy} needs to be killed to be stopped. Note this will not +usually kill any connections which have already been accepted, and also +that the port is not immediately available for reuse. + +@noindent +The following chunk of code puts a list of sessions into an xterm header, +with the current session followed by a star. + +@noindent +@example +print -n "\033]2;TCP:" $@{(k)tcp_by_name:/$TCP_SESS/$TCP_SESS\*@} "\a" +@end example + +@noindent +@node TCP Bugs, , TCP Examples, TCP Function System + +@section TCP Bugs +@noindent + +@noindent +The function @t{tcp_read} uses the shell's normal @t{read} builtin. As +this reads a complete line at once, data arriving without a terminating +newline can cause the function to block indefinitely. + +@noindent +Though the function suite works well for interactive use and for data +arriving in small amounts, the performance when large amounts of data are +being exchanged is likely to be extremely poor. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/zftpsys.yo +@node Zftp Function System, User Contributions, TCP Function System, Top + +@chapter Zftp Function System +@noindent +@cindex zftp function system +@cindex FTP, functions for using shell as client + +@section Description +@noindent + +@noindent +This describes the set of shell functions supplied with the source +distribution as an interface to the @t{zftp} builtin command, allowing you +to perform FTP operations from the shell command line or within functions +or scripts. The interface is similar to a traditional FTP client (e.g. the +@t{ftp} command itself, see man page ftp(1)), but as it is entirely done +within the shell all the familiar completion, editing and globbing features, +and so on, are present, and macros are particularly simple to write as they +are just ordinary shell functions. + +@noindent +The prerequisite is that the @t{zftp} command, as described in +@ref{The zsh/zftp Module} +, must be available in the +version of @t{zsh} installed at your site. If the shell is configured to +load new commands at run time, it probably is: typing `@t{zmodload zsh/zftp}' +will make sure (if that runs silently, it has worked). If this is not the +case, it is possible @t{zftp} was linked into the shell anyway: to test +this, type `@t{which zftp}' and if @t{zftp} is available you will get the +message `@t{zftp: shell built-in command}'. + +@noindent +Commands given directly with @t{zftp} builtin may be interspersed between +the functions in this suite; in a few cases, using @t{zftp} directly may +cause some of the status information stored in shell parameters to become +invalid. Note in particular the description of the variables +@t{$ZFTP_TMOUT}, @t{$ZFTP_PREFS} and @t{$ZFTP_VERBOSE} for @t{zftp}. + +@noindent +@menu +* Installation:: +* Zftp Functions:: +* Miscellaneous Features:: +@end menu + +@noindent +@node Installation, Zftp Functions, , Zftp Function System + +@section Installation +@noindent + +@noindent +You should make sure all the functions from the @t{Functions/Zftp} +directory of the source distribution are available; they all begin with the +two letters `@t{zf}'. They may already have been installed on your system; +otherwise, you will need to find them and copy them. The directory should +appear as one of the elements of the @t{$fpath} array (this should already +be the case if they were installed), and at least the function @t{zfinit} +should be autoloaded; it will autoload the rest. Finally, to initialize +the use of the system you need to call the @t{zfinit} function. The +following code in your @t{.zshrc} will arrange for this; assume the +functions are stored in the directory @t{~/myfns}: + +@noindent +@example +fpath=(~/myfns $fpath) +autoload -U zfinit +zfinit +@end example + +@noindent +Note that @t{zfinit} assumes you are using the @t{zmodload} method to +load the @t{zftp} command. If it is already built into the shell, change +@t{zfinit} to @t{zfinit -n}. It is helpful (though not essential) if the +call to @t{zfinit} appears after any code to initialize the new completion +system, else unnecessary @t{compctl} commands will be given. + +@noindent +@node Zftp Functions, Miscellaneous Features, Installation, Zftp Function System + +@section Functions +@noindent + +@noindent +The sequence of operations in performing a file transfer is essentially the +same as that in a standard FTP client. Note that, due to a quirk of the +shell's @t{getopts} builtin, for those functions that handle options you +must use `@t{-}@t{-}' rather than `@t{-}' to ensure the remaining arguments +are treated literally (a single `@t{-}' is treated as an argument). + +@noindent + +@subsection Opening a connection +@noindent +@table @asis +@findex zfparams +@item @t{zfparams} [ @var{host} [ @var{user} [ @var{password} ... ] ] ] +Set or show the parameters for a future @t{zfopen} with no arguments. If +no arguments are given, the current parameters are displayed (the password +will be shown as a line of asterisks). If a @var{host} is given, and either the +@var{user} or @var{password} is not, they will be prompted for; also, any +parameter given as `@t{?}' will be prompted for, and if the `@t{?}' is +followed by a string, that will be used as the prompt. As @t{zfopen} calls +@t{zfparams} to store the parameters, this usually need not be called +directly. + +@noindent +A single argument `@t{-}' will delete the stored parameters. This will +also cause the memory of the last directory (and so on) on the other host +to be deleted. + +@findex zfopen +@item @t{zfopen} [ @t{-1} ] [ @var{host} [ @var{user} [ @var{password} [ @var{account} ] ] ] ] +If @var{host} is present, open a connection to that host under username +@var{user} with password @var{password} (and, on the rare occasions when it +is necessary, account @var{account}). If a necessary parameter is missing or +given as `@t{?}' it will be prompted for. If @var{host} is not present, use +a previously stored set of parameters. + +@noindent +If the command was successful, and the terminal is compatible with +@t{xterm} or is @t{sun-cmd}, a summary will appear in the title bar, +giving the local @t{host:directory} and the remote @t{host:directory}; +this is handled by the function @t{zftp_chpwd}, described below. + +@noindent +Normally, the @var{host}, @var{user} and @var{password} are internally +recorded for later re-opening, either by a @t{zfopen} with no arguments, or +automatically (see below). With the option `@t{-1}', no information is +stored. Also, if an open command with arguments failed, the parameters +will not be retained (and any previous parameters will also be deleted). +A @t{zfopen} on its own, or a @t{zfopen -1}, never alters the stored +parameters. + +@noindent +Both @t{zfopen} and @t{zfanon} (but not @t{zfparams}) understand URLs of +the form @t{ftp://}@var{host}/@var{path...} as meaning to connect to the +@var{host}, then change directory to @var{path} (which must be a directory, +not a file). The `@t{ftp://}' can be omitted; the trailing `@t{/}' is enough +to trigger recognition of the @var{path}. Note prefixes other than +`@t{ftp:}' are not recognized, and that all characters after the first +slash beyond @var{host} are significant in @var{path}. + +@findex zfanon +@item @t{zfanon} [ @t{-1} ] @var{host} +Open a connection @var{host} for anonymous FTP. The username used is +`@t{anonymous}'. The password (which will be reported the first time) is +generated as @var{user}@t{@@}@var{host}; this is then stored in the shell +parameter @t{$EMAIL_ADDR} which can alternatively be set manually to a +suitable string. + +@end table + +@noindent + +@subsection Directory management +@noindent +@table @asis +@findex zfcd +@item @t{zfcd} [ @var{dir} ] +@itemx @t{zfcd -} +@itemx @t{zfcd} @var{old} @var{new} +Change the current directory on the remote server: this is implemented to +have many of the features of the shell builtin @t{cd}. + +@noindent +In the first form with @var{dir} present, change to the directory @var{dir}. +The command `@t{zfcd ..}' is treated specially, so is guaranteed to work on +non-UNIX servers (note this is handled internally by @t{zftp}). If @var{dir} +is omitted, has the effect of `@t{zfcd ~}'. + +@noindent +The second form changes to the directory previously current. + +@noindent +The third form attempts to change the current directory by replacing the +first occurrence of the string @var{old} with the string @var{new} in the +current directory. + +@noindent +Note that in this command, and indeed anywhere a remote filename is +expected, the string which on the local host corresponds to `@t{~}' is +converted back to a `@t{~}' before being passed to the remote machine. +This is convenient because of the way expansion is performed on the command +line before @t{zfcd} receives a string. For example, suppose the command +is `@t{zfcd ~/foo}'. The shell will expand this to a full path such as +`@t{zfcd /home/user2/pws/foo}'. At this stage, @t{zfcd} recognises the +initial path as corresponding to `@t{~}' and will send the directory to +the remote host as @t{~/foo}, so that the `@t{~}' will be expanded by the +server to the correct remote host directory. Other named directories of +the form `@t{~name}' are not treated in this fashion. + +@findex zfhere +@item @t{zfhere} +Change directory on the remote server to the one corresponding to the +current local directory, with special handling of `@t{~}' as in @t{zfcd}. +For example, if the current local directory is @t{~/foo/bar}, then +@t{zfhere} performs the effect of `@t{zfcd ~/foo/bar}'. + +@findex zfdir +@item @t{zfdir} [ @t{-rfd} ] [ @t{-} ] [ @var{dir-options} ] [ @var{dir} ] +Produce a long directory listing. The arguments @var{dir-options} and +@var{dir} are passed directly to the server and their effect is +implementation dependent, but specifying a particular remote directory +@var{dir} is usually possible. The output is passed through a pager +given by the environment variable @t{$PAGER}, or `@t{more}' if that is not +set. + +@noindent +The directory is usually cached for re-use. In fact, two caches are +maintained. One is for use when there is no @var{dir-options} or @var{dir}, +i.e. a full listing of the current remote directory; it is flushed +when the current remote directory changes. The other is +kept for repeated use of @t{zfdir} with the same arguments; for example, +repeated use of `@t{zfdir /pub/gnu}' will only require the directory to be +retrieved on the first call. Alternatively, this cache can be re-viewed with +the @t{-r} option. As relative directories will confuse +@t{zfdir}, the @t{-f} option can be used to force the cache to be flushed +before the directory is listed. The option @t{-d} will delete both +caches without showing a directory listing; it will also delete the cache +of file names in the current remote directory, if any. + +@findex zfls +@item @t{zfls} [ @var{ls-options} ] [ @var{dir} ] +List files on the remote server. With no arguments, this will produce a +simple list of file names for the current remote directory. Any arguments +are passed directly to the server. No pager and no caching is used. + +@end table + +@noindent + +@subsection Status commands +@noindent +@table @asis +@findex zftype +@item @t{zftype} [ @var{type} ] +With no arguments, show the type of data to be transferred, usually ASCII +or binary. With an argument, change the type: the types `@t{A}' or +`@t{ASCII}' for ASCII data and `@t{B}' or `@t{BINARY}', `@t{I}' or +`@t{IMAGE}' for binary data are understood case-insensitively. + +@findex zfstat +@item @t{zfstat} [ @t{-v} ] +Show the status of the current or last connection, as well as the status of +some of @t{zftp}'s status variables. With the @t{-v} option, a more +verbose listing is produced by querying the server for its version of +events, too. + +@end table + +@noindent + +@subsection Retrieving files +@noindent +The commands for retrieving files all take at least two options. @t{-G} +suppresses remote filename expansion which would otherwise be performed +(see below for a more detailed description of that). @t{-t} attempts +to set the modification time of the local file to that of the remote file: +see the description of the function @t{zfrtime} below for more information. + +@noindent +@table @asis +@findex zfget +@item @t{zfget} [ @t{-Gtc} ] @var{file1} ... +Retrieve all the listed files @var{file1} ... one at a time from the remote +server. If a file contains a `@t{/}', the full name is passed to the +remote server, but the file is stored locally under the name given by the +part after the final `@t{/}'. The option @t{-c} (cat) forces all files to +be sent as a single stream to standard output; in this case the @t{-t} +option has no effect. + +@findex zfuget +@item @t{zfuget} [ @t{-Gvst} ] @var{file1} ... +As @t{zfget}, but only retrieve files where the version on the remote +server is newer (has a later modification time), or where the local file +does not exist. If the remote file is older but the files have different +sizes, or if the sizes are the same but the remote file is newer, the user +will usually be queried. With the option @t{-s}, the command runs silently +and will always retrieve the file in either of those two cases. With the +option @t{-v}, the command prints more information about the files while it +is working out whether or not to transfer them. + +@findex zfcget +@item @t{zfcget} [ @t{-Gt} ] @var{file1} ... +As @t{zfget}, but if any of the local files exists, and is shorter than +the corresponding remote file, the command assumes that it is the result of +a partially completed transfer and attempts to transfer the rest of the +file. This is useful on a poor connection which keeps failing. + +@noindent +Note that this requires a commonly implemented, but non-standard, version +of the FTP protocol, so is not guaranteed to work on all servers. + +@findex zfgcp +@item @t{zfgcp} [ @t{-Gt} ] @var{remote-file} @var{local-file} +@itemx @t{zfgcp} [ @t{-Gt} ] @var{rfile1} ... @var{ldir} +This retrieves files from the remote server with arguments behaving +similarly to the @t{cp} command. + +@noindent +In the first form, copy @var{remote-file} from the server to the local file +@var{local-file}. + +@noindent +In the second form, copy all the remote files @var{rfile1} ... into the +local directory @var{ldir} retaining the same basenames. This assumes UNIX +directory semantics. + +@end table + +@noindent + +@subsection Sending files +@noindent +@table @asis +@findex zfput +@item @t{zfput} [ @t{-r} ] @var{file1} ... +Send all the @var{file1} ... given separately to the remote server. If a +filename contains a `@t{/}', the full filename is used locally to find the +file, but only the basename is used for the remote file name. + +@noindent +With the option @t{-r}, if any of the @var{files} are directories they are +sent recursively with all their subdirectories, including files beginning +with `@t{.}'. This requires that the remote machine understand UNIX file +semantics, since `@t{/}' is used as a directory separator. + +@findex zfuput +@item @t{zfuput} [ @t{-vs} ] @var{file1} ... +As @t{zfput}, but only send files which are newer than their remote +equivalents, or if the remote file does not exist. The logic is the same +as for @t{zfuget}, but reversed between local and remote files. + +@findex zfcput +@item @t{zfcput} @var{file1} ... +As @t{zfput}, but if any remote file already exists and is shorter than the +local equivalent, assume it is the result of an incomplete transfer and +send the rest of the file to append to the existing part. As the FTP +append command is part of the standard set, this is in principle more +likely to work than @t{zfcget}. + +@findex zfpcp +@item @t{zfpcp} @var{local-file} @var{remote-file} +@itemx @t{zfpcp} @var{lfile1} ... @var{rdir} +This sends files to the remote server with arguments behaving similarly to +the @t{cp} command. + +@noindent +With two arguments, copy @var{local-file} to the server as +@var{remote-file}. + +@noindent +With more than two arguments, copy all the local files @var{lfile1} ... into +the existing remote directory @var{rdir} retaining the same basenames. This +assumes UNIX directory semantics. + +@noindent +A problem arises if you attempt to use @t{zfpcp} @var{lfile1} @var{rdir}, +i.e. the second form of copying but with two arguments, as the command has +no simple way of knowing if @var{rdir} corresponds to a directory or a +filename. It attempts to resolve this in various ways. First, if the +@var{rdir} argument is `@t{.}' or `@t{..}' or ends in a slash, it is assumed +to be a directory. Secondly, if the operation of copying to a remote file +in the first form failed, and the remote server sends back the expected +failure code 553 and a reply including the string `@t{Is a directory}', +then @t{zfpcp} will retry using the second form. + +@end table + +@noindent + +@subsection Closing the connection +@noindent +@table @asis +@findex zfclose +@item @t{zfclose} +Close the connection. + +@end table + +@noindent + +@subsection Session management +@noindent +@table @asis +@findex zfsession +@item @t{zfsession} [ @t{-lvod} ] [ @var{sessname} ] +Allows you to manage multiple FTP sessions at once. By default, +connections take place in a session called `@t{default}'; by giving the +command `@t{zfsession} @var{sessname}' you can change to a new or existing +session with a name of your choice. The new session remembers its own +connection, as well as associated shell parameters, and also the host/user +parameters set by @t{zfparams}. Hence you can have different sessions set +up to connect to different hosts, each remembering the appropriate host, +user and password. + +@noindent +With no arguments, @t{zfsession} prints the name of the current session; +with the option @t{-l} it lists all sessions which currently exist, and +with the option @t{-v} it gives a verbose list showing the host and +directory for each session, where the current session is marked with an +asterisk. With @t{-o}, it will switch to the most recent previous session. + +@noindent +With @t{-d}, the given session (or else the current one) is removed; +everything to do with it is completely forgotten. If it was the only +session, a new session called `@t{default}' is created and made current. +It is safest not to delete sessions while background commands using +@t{zftp} are active. + +@findex zftransfer +@item @t{zftransfer} @var{sess1}@t{:}@var{file1} @var{sess2}@t{:}@var{file2} +Transfer files between two sessions; no local copy is made. The file +is read from the session @var{sess1} as @var{file1} and written to session +@var{sess2} as file @var{file2}; @var{file1} and @var{file2} may be relative to +the current directories of the session. Either @var{sess1} or @var{sess2} +may be omitted (though the colon should be retained if there is a +possibility of a colon appearing in the file name) and defaults to the +current session; @var{file2} may be omitted or may end with a slash, in +which case the basename of @var{file1} will be added. The sessions +@var{sess1} and @var{sess2} must be distinct. + +@noindent +The operation is performed using pipes, so it is required that the +connections still be valid in a subshell, which is not the case under +versions of some operating systems, presumably due to a system bug. + +@end table + +@noindent + +@subsection Bookmarks +@noindent +The two functions @t{zfmark} and @t{zfgoto} allow you to `bookmark' the +present location (host, user and directory) of the current FTP connection +for later use. The file to be used for storing and retrieving bookmarks is +given by the parameter @t{$ZFTP_BMFILE}; if not set when one of the two +functions is called, it will be set to the file @t{.zfbkmarks} in the +directory where your zsh startup files live (usually @t{~}). + +@noindent +@table @asis +@findex zfmark +@item @t{zfmark} [ @var{bookmark} ] +If given an argument, mark the current host, user and directory under the +name @var{bookmark} for later use by @t{zfgoto}. If there is no connection +open, use the values for the last connection immediately before it was +closed; it is an error if there was none. Any existing bookmark +under the same name will be silently replaced. + +@noindent +If not given an argument, list the existing bookmarks and the points to +which they refer in the form @var{user}@t{@@}@var{host}@t{:}@var{directory}; +this is the format in which they are stored, and the file may be edited +directly. + +@findex zfgoto +@item @t{zfgoto} [ @t{-n} ] @var{bookmark} +Return to the location given by @var{bookmark}, as previously set by +@t{zfmark}. If the location has user `@t{ftp}' or `@t{anonymous}', open +the connection with @t{zfanon}, so that no password is required. If the +user and host parameters match those stored for the current session, if +any, those will be used, and again no password is required. Otherwise a +password will be prompted for. + +@noindent +With the option @t{-n}, the bookmark is taken to be a nickname stored by +the @t{ncftp} program in its bookmark file, which is assumed to be +@t{~/.ncftp/bookmarks}. The function works identically in other ways. +Note that there is no mechanism for adding or modifying @t{ncftp} bookmarks +from the zftp functions. + +@end table + +@noindent + +@subsection Other functions +@noindent +Mostly, these functions will not be called directly (apart from +@t{zfinit}), but are described here for completeness. You may wish to +alter @t{zftp_chpwd} and @t{zftp_progress}, in particular. + +@noindent +@table @asis +@findex zfinit +@item @t{zfinit} [ @t{-n} ] +As described above, this is used to initialize the zftp function system. +The @t{-n} option should be used if the zftp command is already built into +the shell. + +@findex zfautocheck +@item @t{zfautocheck} [ @t{-dn} ] +This function is called to implement automatic reopening behaviour, as +described in more detail below. The options must appear in the first +argument; @t{-n} prevents the command from changing to the old directory, +while @t{-d} prevents it from setting the variable @t{do_close}, which it +otherwise does as a flag for automatically closing the connection after a +transfer. The host and directory for the last session are stored in the +variable @t{$zflastsession}, but the internal host/user/password parameters +must also be correctly set. + +@findex zfcd_match +@item @t{zfcd_match @var{prefix} @var{suffix}} +This performs matching for completion of remote directory names. If the +remote server is UNIX, it will attempt to persuade the server to list the +remote directory with subdirectories marked, which usually works but is not +guaranteed. On other hosts it simply calls @t{zfget_match} and hence +completes all files, not just directories. On some systems, directories +may not even look like filenames. + +@findex zfget_match +@item @t{zfget_match @var{prefix} @var{suffix}} +This performs matching for completion of remote filenames. It caches files +for the current directory (only) in the shell parameter @t{$zftp_fcache}. +It is in the form to be called by the @t{-K} option of @t{compctl}, but +also works when called from a widget-style completion function with +@var{prefix} and @var{suffix} set appropriately. + +@findex zfrglob +@item @t{zfrglob @var{varname}} +Perform remote globbing, as describes in more detail below. @var{varname} +is the name of a variable containing the pattern to be expanded; if there +were any matches, the same variable will be set to the expanded set of +filenames on return. + +@findex zfrtime +@item @t{zfrtime} @var{lfile} @var{rfile} [ @var{time} ] +Set the local file @var{lfile} to have the same modification time as the +remote file @var{rfile}, or the explicit time @var{time} in FTP format +@t{CCYYMMDDhhmmSS} for the GMT timezone. This uses the shell's +@t{zsh/datetime} module to perform the conversion from +GMT to local time. + +@findex zftp_chpwd, supplied version +@item @t{zftp_chpwd} +This function is called every time a connection is opened, or closed, or +the remote directory changes. This version alters the title bar of an +@t{xterm}-compatible or @t{sun-cmd} terminal emulator to reflect the +local and remote hostnames and current directories. It works best when +combined with the function @t{chpwd}. In particular, a function of +the form + +@noindent +@example +chpwd() @{ + if [[ -n $ZFTP_USER ]]; then + zftp_chpwd + else + # usual chpwd e.g put host:directory in title bar + fi +@} +@end example + +@noindent +fits in well. + +@findex zftp_progress, supplied version +@item @t{zftp_progress} +This function shows the status of the transfer. It will not write anything +unless the output is going to a terminal; however, if you transfer files in +the background, you should turn off progress reports by hand using +`@t{zstyle ':zftp:*' progress none}'. Note also that if you alter it, any +output @emph{must} be to standard error, as standard output may be a file +being received. The form of the progress meter, or whether it is used at +all, can be configured without altering the function, as described in the +next section. + +@findex zffcache +@item @t{zffcache} +This is used to implement caching of files in the current directory for +each session separately. It is used by @t{zfget_match} and @t{zfrglob}. + +@end table + +@noindent +@node Miscellaneous Features, , Zftp Functions, Zftp Function System + +@section Miscellaneous Features +@noindent + +@noindent + +@subsection Configuration +@noindent +@cindex zftp function system, configuration +@cindex zftp function system, styles +@cindex styles in zftp functions + +@noindent +Various styles are available using the standard shell style mechanism, +described in +@ref{The zsh/zutil Module}. Briefly, the +command `@t{zstyle ':zftp:*'} @var{style} @var{value} ...'. +defines the @var{style} to have value @var{value}; more than one value may be +given, although that is not useful in the cases described here. These +values will then be used throughout the zftp function system. For more +precise control, the first argument, which gives a context in which the +style applies, can be modified to include a particular function, as for +example `@t{:zftp:zfget}': the style will then have the given value only +in the @t{zfget} function. Values for the same style in different contexts +may be set; the most specific function will be used, where +strings are held to be more specific than patterns, and longer patterns and +shorter patterns. Note that only the top level function name, as called by +the user, is used; calling of lower level functions is transparent to the +user. Hence modifications to the title bar in @t{zftp_chpwd} use the +contexts @t{:zftp:zfopen}, @t{:zftp:zfcd}, etc., depending where it was +called from. The following styles are understood: + +@noindent +@table @asis +@kindex progress, zftp style +@item @t{progress} +Controls the way that @t{zftp_progress} reports on the progress of a +transfer. If empty, unset, or `@t{none}', no progress report is made; if +`@t{bar}' a growing bar of inverse video is shown; if `@t{percent}' (or any +other string, though this may change in future), the percentage of the file +transferred is shown. The bar meter requires that the width of the +terminal be available via the @t{$COLUMNS} parameter (normally this is set +automatically). If the size of the file being transferred is not +available, @t{bar} and @t{percent} meters will simply show the number of +bytes transferred so far. + +@noindent +When @t{zfinit} is run, if this style is not defined for the context +@t{:zftp:*}, it will be set to `bar'. + +@kindex update, zftp style +@item @t{update} +Specifies the minimum time interval between updates of the progress meter +in seconds. No update is made unless new data has been received, so the +actual time interval is limited only by @t{$ZFTP_TIMEOUT}. + +@noindent +As described for @t{progress}, @t{zfinit} will force this to default to 1. + +@kindex remote-glob, zftp style +@item @t{remote-glob} +If set to `@t{1}', `@t{yes}' or `@t{true}', filename generation (globbing) is +performed on the remote machine instead of by zsh itself; see below. + +@kindex titlebar, zftp style +@item @t{titlebar} +If set to `@t{1}', `@t{yes}' or `@t{true}', @t{zftp_chpwd} will put the remote host and +remote directory into the titlebar of terminal emulators such as xterm or +sun-cmd that allow this. + +@noindent +As described for @t{progress}, @t{zfinit} will force this to default to 1. + +@kindex chpwd, zftp style +@item @t{chpwd} +If set to `@t{1}' `@t{yes}' or `@t{true}', @t{zftp_chpwd} will call the function +@t{chpwd} when a connection is closed. This is useful if the remote host +details were put into the terminal title bar by @t{zftp_chpwd} and your +usual @t{chpwd} also modifies the title bar. + +@noindent +When @t{zfinit} is run, it will determine whether @t{chpwd} exists and if +so it will set the default value for the style to 1 if none exists +already. + +@end table + +@noindent +Note that there is also an associative array @t{zfconfig} which contains +values used by the function system. This should not be modified or +overwritten. + +@noindent + +@subsection Remote globbing +@noindent +@cindex zftp function system, remote globbing + +@noindent +The commands for retrieving files usually perform filename generation +(globbing) on their arguments; this can be turned off by passing the option +@t{-G} to each of the commands. Normally this operates by retrieving a +complete list of files for the directory in question, then matching these +locally against the pattern supplied. This has the advantage that the full +range of zsh patterns (respecting the setting of the option +@t{EXTENDED_GLOB}) can be used. However, it means that the directory part +of a filename will not be expanded and must be given exactly. If the +remote server does not support the UNIX directory semantics, directory +handling is problematic and it is recommended that globbing only be used +within the current directory. The list of files in the current directory, +if retrieved, will be cached, so that subsequent globs in the same +directory without an intervening @t{zfcd} are much faster. + +@noindent +If the @t{remote-glob} style (see above) is set, globbing is instead +performed on the remote host: the server is asked for a list of matching +files. This is highly dependent on how the server is implemented, though +typically UNIX servers will provide support for basic glob patterns. This +may in some cases be faster, as it avoids retrieving the entire list of +directory contents. + +@noindent + +@subsection Automatic and temporary reopening +@noindent +@cindex zftp function system, automatic reopening + +@noindent +As described for the @t{zfopen} command, a subsequent @t{zfopen} with no +parameters will reopen the connection to the last host (this includes +connections made with the @t{zfanon} command). Opened in this fashion, the +connection starts in the default remote directory and will remain open +until explicitly closed. + +@noindent +Automatic re-opening is also available. If a connection is not currently +open and a command requiring a connection is given, the last connection is +implicitly reopened. In this case the directory which was current when the +connection was closed again becomes the current directory (unless, of +course, the command given changes it). Automatic reopening will also take +place if the connection was close by the remote server for whatever reason +(e.g. a timeout). It is not available if the @t{-1} option to @t{zfopen} +or @t{zfanon} was used. + +@noindent +Furthermore, if the command issued is a file transfer, the connection will +be closed after the transfer is finished, hence providing a one-shot mode +for transfers. This does not apply to directory changing or listing +commands; for example a @t{zfdir} may reopen a connection but will leave it +open. Also, automatic closure will only ever happen in the same command as +automatic opening, i.e a @t{zfdir} directly followed by a @t{zfget} will +never close the connection automatically. + +@noindent +Information about the previous connection is given by the @t{zfstat} +function. So, for example, if that reports: + +@noindent +@example +Session: default +Not connected. +Last session: ftp.bar.com:/pub/textfiles +@end example + +@noindent +then the command @t{zfget file.txt} will attempt to reopen a connection to +@t{ftp.bar.com}, retrieve the file @t{/pub/textfiles/file.txt}, and +immediately close the connection again. On the other hand, @t{zfcd ..} +will open the connection in the directory @t{/pub} and leave it open. + +@noindent +Note that all the above is local to each session; if you return to a +previous session, the connection for that session is the one which will be +reopened. + +@noindent + +@subsection Completion +@noindent + +@noindent +Completion of local and remote files, directories, sessions and bookmarks +is supported. The older, @t{compctl}-style completion is defined when +@t{zfinit} is called; support for the new widget-based completion system is +provided in the function @t{Completion/Zsh/Command/_zftp}, which should be +installed with the other functions of the completion system and hence +should automatically be available. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/contrib.yo +@node User Contributions, , Zftp Function System, Top + +@chapter User Contributions +@noindent +@cindex user contributions + +@section Description +@noindent + +@noindent +The Zsh source distribution includes a number of items contributed by the +user community. These are not inherently a part of the shell, and some +may not be available in every zsh installation. The most significant of +these are documented here. For documentation on other contributed items +such as shell functions, look for comments in the function source files. + +@noindent +@menu +* Utilities:: +* Recent Directories:: +* Other Directory Functions:: +* Version Control Information:: +* Prompt Themes:: +* ZLE Functions:: +* Exception Handling:: +* MIME Functions:: +* Mathematical Functions:: +* User Configuration Functions:: +* Other Functions:: +@end menu + +@noindent +@node Utilities, Recent Directories, , User Contributions + +@section Utilities +@noindent + +@noindent + +@subsection Accessing On-Line Help +@noindent +@cindex helpfiles utility + +@noindent +The key sequence @t{ESC h} is normally bound by ZLE to execute the +@t{run-help} widget (see +@ref{Zsh Line Editor}). This invokes the @t{run-help} command with the command word from the +current input line as its argument. By default, @t{run-help} is an alias +for the @t{man} command, so this often fails when the command word is a +shell builtin or a user-defined function. By redefining the @t{run-help} +alias, one can improve the on-line help provided by the shell. + +@noindent +The @t{helpfiles} utility, found in the @t{Util} directory of the +distribution, is a Perl program that can be used to process the zsh manual +to produce a separate help file for each shell builtin and for many other +shell features as well. The autoloadable @t{run-help} function, found in +@t{Functions/Misc}, searches for these helpfiles and performs several +other tests to produce the most complete help possible for the command. + +@noindent +Help files are installed by default to a subdirectory of @t{/usr/share/zsh} +or @t{/usr/local/share/zsh}. + +@noindent +To create your own help files with @t{helpfiles}, choose or create a +directory where the individual command help files will reside. For +example, you might choose @t{~/zsh_help}. If you unpacked the zsh +distribution in your home directory, you would use the commands: + +@noindent +@example +mkdir ~/zsh_help +perl ~/zsh-5.8/Util/helpfiles ~/zsh_help +@end example + +@noindent +@vindex HELPDIR +The @t{HELPDIR} parameter tells @t{run-help} where to look for the help +files. When unset, it uses the default installation path. +To use your own set of help files, set this to the appropriate path +in one of your startup files: + +@noindent +@example +HELPDIR=~/zsh_help +@end example + +@noindent +@findex run-help, use of +To use the @t{run-help} function, you need to add lines something +like the following to your @t{.zshrc} or equivalent startup file: + +@noindent +@example +unalias run-help +autoload run-help +@end example + +@noindent +Note that in order for `@t{autoload run-help}' to work, the @t{run-help} +file must be in one of the directories named in your @t{fpath} array (see +@ref{Parameters Used By The Shell}). This should already be the case if you have a standard zsh +installation; if it is not, copy @t{Functions/Misc/run-help} to an +appropriate directory. + +@noindent + +@subsection Recompiling Functions +@noindent +@cindex functions, recompiling +@cindex zrecompile utility + +@noindent +If you frequently edit your zsh functions, or periodically update your zsh +installation to track the latest developments, you may find that function +digests compiled with the @t{zcompile} builtin are frequently out of date +with respect to the function source files. This is not usually a problem, +because zsh always looks for the newest file when loading a function, but +it may cause slower shell startup and function loading. Also, if a digest +file is explicitly used as an element of @t{fpath}, zsh won't check whether +any of its source files has changed. + +@noindent +The @t{zrecompile} autoloadable function, found in @t{Functions/Misc}, can +be used to keep function digests up to date. + +@noindent +@table @asis +@findex zrecompile +@item @t{zrecompile} [ @t{-qt} ] [ @var{name} ... ] +@itemx @t{zrecompile} [ @t{-qt} ] @t{-p} @var{arg} ... [ @t{-}@t{-} @var{arg} ... ] +This tries to find @t{*.zwc} files and automatically re-compile them if at +least one of the original files is newer than the compiled file. This +works only if the names stored in the compiled files are full paths or are +relative to the directory that contains the @t{.zwc} file. + +@noindent +In the first form, each @var{name} is the name of a compiled file or a +directory containing @t{*.zwc} files that should be checked. If no +arguments are given, the directories and @t{*.zwc} files in @t{fpath} are +used. + +@noindent +When @t{-t} is given, no compilation is performed, but a return status of +zero (true) is set if there are files that need to be re-compiled and +non-zero (false) otherwise. The @t{-q} option quiets the chatty output +that describes what @t{zrecompile} is doing. + +@noindent +Without the @t{-t} option, the return status is zero if all files that +needed re-compilation could be compiled and non-zero if compilation for at +least one of the files failed. + +@noindent +If the @t{-p} option is given, the @var{arg}s are interpreted as one +or more sets of arguments for @t{zcompile}, separated by `@t{-}@t{-}'. +For example: + +@noindent +@example +zrecompile -p \ + -R ~/.zshrc -- \ + -M ~/.zcompdump -- \ + ~/zsh/comp.zwc ~/zsh/Completion/*/_* +@end example + +@noindent +This compiles @t{~/.zshrc} into @t{~/.zshrc.zwc} if that doesn't exist or +if it is older than @t{~/.zshrc}. The compiled file will be marked for +reading instead of mapping. The same is done for @t{~/.zcompdump} and +@t{~/.zcompdump.zwc}, but this compiled file is marked for mapping. The +last line re-creates the file @t{~/zsh/comp.zwc} if any of the files +matching the given pattern is newer than it. + +@noindent +Without the @t{-p} option, @t{zrecompile} does not create function digests +that do not already exist, nor does it add new functions to the digest. + +@end table + +@noindent +The following shell loop is an example of a method for creating function +digests for all functions in your @t{fpath}, assuming that you have write +permission to the directories: + +@noindent +@example +for ((i=1; i <= $#fpath; ++i)); do + dir=$fpath[i] + zwc=$@{dir:t@}.zwc + if [[ $dir == (.|..) || $dir == (.|..)/* ]]; then + continue + fi + files=($dir/*(N-.)) + if [[ -w $dir:h && -n $files ]]; then + files=($@{$@{(M)files%/*/*@}#/@}) + if ( cd $dir:h && + zrecompile -p -U -z $zwc $files ); then + fpath[i]=$fpath[i].zwc + fi + fi +done +@end example + +@noindent +The @t{-U} and @t{-z} options are appropriate for functions in the default +zsh installation @t{fpath}; you may need to use different options for your +personal function directories. + +@noindent +Once the digests have been created and your @t{fpath} modified to refer to +them, you can keep them up to date by running @t{zrecompile} with no +arguments. + +@noindent + +@subsection Keyboard Definition +@noindent +@cindex keyboard definition + +@noindent +@findex zkbd +The large number of possible combinations of keyboards, workstations, +terminals, emulators, and window systems makes it impossible for zsh to +have built-in key bindings for every situation. The @t{zkbd} utility, +found in @t{Functions/Misc}, can help you quickly create key bindings for your +configuration. + +@noindent +Run @t{zkbd} either as an autoloaded function, or as a shell script: + +@noindent +@example +zsh -f ~/zsh-5.8/Functions/Misc/zkbd +@end example + +@noindent +When you run @t{zkbd}, it first asks you to enter your terminal type; if +the default it offers is correct, just press return. It then asks you to +press a number of different keys to determine characteristics of your +keyboard and terminal; @t{zkbd} warns you if it finds anything out of the +ordinary, such as a Delete key that sends neither @t{^H} nor @t{^?}. + +@noindent +The keystrokes read by @t{zkbd} are recorded as a definition for an +associative array named @t{key}, written to a file in the subdirectory +@t{.zkbd} within either your @t{HOME} or @t{ZDOTDIR} directory. The name +of the file is composed from the @t{TERM}, @t{VENDOR} and @t{OSTYPE} +parameters, joined by hyphens. + +@noindent +You may read this file into your @t{.zshrc} or another startup file with +the `@t{source}' or `@t{.}' commands, then reference the @t{key} parameter +in bindkey commands, like this: + +@noindent +@example +source $@{ZDOTDIR:-$HOME@}/.zkbd/$TERM-$VENDOR-$OSTYPE +[[ -n $@{key[Left]@} ]] && bindkey "$@{key[Left]@}" backward-char +[[ -n $@{key[Right]@} ]] && bindkey "$@{key[Right]@}" forward-char +# etc. +@end example + +@noindent +Note that in order for `@t{autoload zkbd}' to work, the @t{zkdb} file must +be in one of the directories named in your @t{fpath} array (see +@ref{Parameters Used By The Shell}). This should already be the case if you have a standard zsh +installation; if it is not, copy @t{Functions/Misc/zkbd} to an +appropriate directory. + +@noindent + +@subsection Dumping Shell State +@noindent +@cindex reporter utility + +@noindent +Occasionally you may encounter what appears to be a bug in the shell, +particularly if you are using a beta version of zsh or a development +release. Usually it is sufficient to send a description of the +problem to one of the zsh mailing lists (see +@ref{Mailing Lists}), but sometimes one of the zsh developers will need to recreate your +environment in order to track the problem down. + +@noindent +The script named @t{reporter}, found in the @t{Util} directory of the +distribution, is provided for this purpose. (It is also possible to +@t{autoload reporter}, but @t{reporter} is not installed in @t{fpath} +by default.) This script outputs a detailed dump of the shell state, +in the form of another script that can be read with `@t{zsh -f}' to +recreate that state. + +@noindent +To use @t{reporter}, read the script into your shell with the `@t{.}' +command and redirect the output into a file: + +@noindent +@example +. ~/zsh-5.8/Util/reporter > zsh.report +@end example + +@noindent +You should check the @t{zsh.report} file for any sensitive information +such as passwords and delete them by hand before sending the script to the +developers. Also, as the output can be voluminous, it's best to wait for +the developers to ask for this information before sending it. + +@noindent +You can also use @t{reporter} to dump only a subset of the shell state. +This is sometimes useful for creating startup files for the first time. +Most of the output from reporter is far more detailed than usually is +necessary for a startup file, but the @t{aliases}, @t{options}, and +@t{zstyles} states may be useful because they include only changes from +the defaults. The @t{bindings} state may be useful if you have created +any of your own keymaps, because @t{reporter} arranges to dump the keymap +creation commands as well as the bindings for every keymap. + +@noindent +As is usual with automated tools, if you create a startup file with +@t{reporter}, you should edit the results to remove unnecessary commands. +Note that if you're using the new completion system, you should @emph{not} +dump the @t{functions} state to your startup files with @t{reporter}; use +the @t{compdump} function instead (see +@ref{Completion System}). + +@noindent +@table @asis +@item @t{reporter} [ @var{state} ... ] +@findex reporter +Print to standard output the indicated subset of the current shell state. +The @var{state} arguments may be one or more of: + +@noindent +@table @asis +@item @t{all} +Output everything listed below. +@item @t{aliases} +Output alias definitions. +@item @t{bindings} +Output ZLE key maps and bindings. +@item @t{completion} +Output old-style @t{compctl} commands. +New completion is covered by @t{functions} and @t{zstyles}. +@item @t{functions} +Output autoloads and function definitions. +@item @t{limits} +Output @t{limit} commands. +@item @t{options} +Output @t{setopt} commands. +@item @t{styles} +Same as @t{zstyles}. +@item @t{variables} +Output shell parameter assignments, plus @t{export} +commands for any environment variables. +@item @t{zstyles} +Output @t{zstyle} commands. +@end table + +@noindent +If the @var{state} is omitted, @t{all} is assumed. + + +@noindent +With the exception of `@t{all}', every @var{state} can be abbreviated by +any prefix, even a single letter; thus @t{a} is the same as @t{aliases}, +@t{z} is the same as @t{zstyles}, etc. +@end table + +@noindent + +@subsection Manipulating Hook Functions +@noindent +@cindex hook function utility + +@noindent +@table @asis +@findex add-zsh-hook +@item @t{add-zsh-hook} [ @t{-L} | @t{-dD} ] [ @t{-Uzk} ] @var{hook} @var{function} +Several functions are special to the shell, as described in the section +Special Functions, @ref{Functions}, +in that they are automatically called at specific points during shell execution. +Each has an associated array consisting of names of functions to be +called at the same point; these are so-called `hook functions'. +The shell function @t{add-zsh-hook} provides a simple way of adding or +removing functions from the array. + +@noindent +@var{hook} is one of @t{chpwd}, @t{periodic}, @t{precmd}, @t{preexec}, +@t{zshaddhistory}, @t{zshexit}, or @t{zsh_directory_name}, +the special functions in question. Note that @t{zsh_directory_name} +is called in a different way from the other functions, but may +still be manipulated as a hook. + +@noindent +@var{function} is name of an ordinary shell function. If no options +are given this will be added to the array of functions to be executed +in the given context. +Functions are invoked in the order they were added. + +@noindent +If the option @t{-L} is given, the current values for the hook arrays +are listed with @t{typeset}. + +@noindent +If the option @t{-d} is given, the @var{function} is removed from +the array of functions to be executed. + +@noindent +If the option @t{-D} is given, the @var{function} is treated as a pattern +and any matching names of functions are removed from the array of +functions to be executed. + +@noindent +The options @t{-U}, @t{-z} and @t{-k} are passed as arguments to +@t{autoload} for @var{function}. For functions contributed with zsh, the +options @t{-Uz} are appropriate. + +@findex add-zle-hook-widget +@item @t{add-zle-hook-widget} [ @t{-L} | @t{-dD} ] [ @t{-Uzk} ] @var{hook} @var{widgetname} +Several widget names are special to the line editor, as described in the section +Special Widgets, @ref{Zle Widgets}, +in that they are automatically called at specific points during editing. +Unlike function hooks, these do not use a predefined array of other names +to call at the same point; the shell function @t{add-zle-hook-widget} +maintains a similar array and arranges for the special widget to invoke +those additional widgets. + +@noindent +@var{hook} is one of @t{isearch-exit}, @t{isearch-update}, +@t{line-pre-redraw}, @t{line-init}, @t{line-finish}, @t{history-line-set}, +or @t{keymap-select}, corresponding to each of the special widgets +@t{zle-isearch-exit}, etc. The special widget names are also accepted +as the @var{hook} argument. + +@noindent +@var{widgetname} is the name of a ZLE widget. If no options are given this +is added to the array of widgets to be invoked in the given hook context. +Widgets are invoked in the order they were added, with +@example +@t{zle }@var{widgetname}@t{ -Nw -- "$@@"} +@end example + +@noindent +@vindex WIDGET, in hooks +Note that this means that the `@t{WIDGET}' special parameter tracks the +@var{widgetname} when the widget function is called, rather than tracking +the name of the corresponding special hook widget. + +@noindent +If the option @t{-d} is given, the @var{widgetname} is removed from +the array of widgets to be executed. + +@noindent +If the option @t{-D} is given, the @var{widgetname} is treated as a pattern +and any matching names of widgets are removed from the array. + +@noindent +If @var{widgetname} does not name an existing widget when added to the +array, it is assumed that a shell function also named @var{widgetname} is +meant to provide the implementation of the widget. This name is therefore +marked for autoloading, and the options @t{-U}, @t{-z} and @t{-k} are +passed as arguments to @t{autoload} as with @t{add-zsh-hook}. The +widget is also created with `@t{zle -N }@var{widgetname}' to cause the +corresponding function to be loaded the first time the hook is called. + +@noindent +The arrays of @var{widgetname} are currently maintained in @t{zstyle} +contexts, one for each @var{hook} context, with a style of `@t{widgets}'. +If the @t{-L} option is given, this set of styles is listed with +`@t{zstyle -L}'. This implementation may change, and the special widgets +that refer to the styles are created only if @t{add-zle-hook-widget} is +called to add at least one widget, so if this function is used for any +hooks, then all hooks should be managed only via this function. + +@end table + +@noindent +@node Recent Directories, Other Directory Functions, Utilities, User Contributions +@cindex recent directories, maintaining list of +@cindex directories, maintaining list of recent +@findex cdr +@findex _cdr +@findex chpwd_recent_add +@findex chpwd_recent_dirs +@findex chpwd_recent_filehandler + +@section Remembering Recent Directories +@noindent + +@noindent +The function @t{cdr} allows you to change the working directory to a +previous working directory from a list maintained automatically. It is +similar in concept to the directory stack controlled by the @t{pushd}, +@t{popd} and @t{dirs} builtins, but is more configurable, and as it stores +all entries in files it is maintained across sessions and (by default) +between terminal emulators in the current session. Duplicates are +automatically removed, so that the list reflects the single most recent +use of each directory. + +@noindent +Note that the @t{pushd} directory stack is not actually modified or used +by @t{cdr} unless you configure it to do so as described in the +configuration section below. + +@noindent + +@subsection Installation +@noindent + +@noindent +The system works by means of a hook function that is called every time the +directory changes. To install the system, autoload the required functions +and use the @t{add-zsh-hook} function described above: + +@noindent +@example +autoload -Uz chpwd_recent_dirs cdr add-zsh-hook +add-zsh-hook chpwd chpwd_recent_dirs +@end example + +@noindent +Now every time you change directly interactively, no matter which +command you use, the directory to which you change will be remembered +in most-recent-first order. + +@noindent + +@subsection Use +@noindent + +@noindent +All direct user interaction is via the @t{cdr} function. + +@noindent +The argument to cdr is a number @var{N} corresponding to the @var{N}th most +recently changed-to directory. 1 is the immediately preceding directory; +the current directory is remembered but is not offered as a destination. +Note that if you have multiple windows open 1 may refer to a directory +changed to in another window; you can avoid this by having per-terminal +files for storing directory as described for the +@t{recent-dirs-file} style below. + +@noindent +If you set the @t{recent-dirs-default} style described below @t{cdr} +will behave the same as @t{cd} if given a non-numeric argument, or more +than one argument. The recent directory list is updated just the same +however you change directory. + +@noindent +If the argument is omitted, 1 is assumed. This is similar to @t{pushd}'s +behaviour of swapping the two most recent directories on the stack. + +@noindent +Completion for the argument to @t{cdr} is available if compinit has been +run; menu selection is recommended, using: + +@noindent +@example +zstyle ':completion:*:*:cdr:*:*' menu selection +@end example + +@noindent +to allow you to cycle through recent directories; the order is preserved, +so the first choice is the most recent directory before the current one. +The verbose style is also recommended to ensure the directory is shown; this +style is on by default so no action is required unless you have changed it. + +@noindent + +@subsection Options +@noindent + +@noindent +The behaviour of @t{cdr} may be modified by the following options. + +@noindent +@table @asis +@item @t{-l} +lists the numbers and the corresponding directories in +abbreviated form (i.e. with @t{~} substitution reapplied), one per line. +The directories here are not quoted (this would only be an issue if a +directory name contained a newline). This is used by the completion +system. + +@item @t{-r} +sets the variable @t{reply} to the current set of directories. Nothing +is printed and the directory is not changed. + +@item @t{-e} +allows you to edit the list of directories, one per line. The +list can be edited to any extent you like; no sanity checking is +performed. Completion is available. No quoting is necessary (except for +newlines, where I have in any case no sympathy); directories are in +unabbreviated from and contain an absolute path, i.e. they start with @t{/}. +Usually the first entry should be left as the current directory. + +@item @t{-p '}@var{pattern}@t{'} +Prunes any items in the directory list that match the given extended glob +pattern; the pattern needs to be quoted from immediate expansion on the +command line. The pattern is matched against each completely expanded +file name in the list; the full string must match, so wildcards at the +end (e.g. @t{'*removeme*'}) are needed to remove entries with a given +substring. + +@noindent +If output is to a terminal, then the function will print the new list +after pruning and prompt for confirmation by the user. This output and +confirmation step can be skipped by using @t{-P} instead of @t{-p}. + +@end table + +@noindent + +@subsection Configuration +@noindent + +@noindent +Configuration is by means of the styles mechanism that should be familiar +from completion; if not, see the description of the @t{zstyle} command in +@ref{The zsh/zutil Module}. The context for setting styles +should be @t{':chpwd:*'} in case the meaning of the context is extended in +future, for example: + +@noindent +@example +zstyle ':chpwd:*' recent-dirs-max 0 +@end example + +@noindent +sets the value of the @t{recent-dirs-max} style to 0. In practice the +style name is specific enough that a context of '*' should be fine. + +@noindent +An exception is @t{recent-dirs-insert}, which is used exclusively by the +completion system and so has the usual completion system context +(@t{':completion:*'} if nothing more specific is needed), though again +@t{'*'} should be fine in practice. + +@noindent +@table @asis +@item @t{recent-dirs-default} +If true, and the command is expecting a recent directory index, and +either there is more than one argument or the argument is not an +integer, then fall through to "cd". This allows the lazy to use only +one command for directory changing. Completion recognises this, too; +see recent-dirs-insert for how to control completion when this option +is in use. + +@item @t{recent-dirs-file} +The file where the list of directories is saved. The default +is @t{$@{ZDOTDIR:-$HOME@}/.chpwd-recent-dirs}, i.e. this is in your +home directory unless you have set the variable @t{ZDOTDIR} to point +somewhere else. Directory names are saved in @t{$'}@var{...}@t{'} quoted +form, so each line in the file can be supplied directly to the shell as an +argument. + +@noindent +The value of this style may be an array. In this case, the first +file in the list will always be used for saving directories while any +other files are left untouched. When reading the recent directory +list, if there are fewer than the maximum number of entries in the +first file, the contents of later files in the array will be appended +with duplicates removed from the list shown. The contents of the two +files are not sorted together, i.e. all the entries in the first file +are shown first. The special value @t{+} can appear in the list to +indicate the default file should be read at that point. This allows +effects like the following: + +@noindent +@example +zstyle ':chpwd:*' recent-dirs-file \ +~/.chpwd-recent-dirs-$@{TTY##*/@} + +@end example + +@noindent +Recent directories are read from a file numbered according to +the terminal. If there are insufficient entries the list +is supplemented from the default file. + +@noindent +It is possible to use @t{zstyle -e} to make the directory configurable +at run time: + +@noindent +@example +zstyle -e ':chpwd:*' recent-dirs-file pick-recent-dirs-file +pick-recent-dirs-file() @{ + if [[ $PWD = ~/text/writing(|/*) ]]; then + reply=(~/.chpwd-recent-dirs-writing) + else + reply=(+) + fi +@} +@end example + +@noindent +In this example, if the current directory is @t{~/text/writing} or a +directory under it, then use a special file for saving recent +directories, else use the default. + +@item @t{recent-dirs-insert} +Used by completion. If @t{recent-dirs-default} is true, then setting +this to @t{true} causes the actual directory, rather than its index, to +be inserted on the command line; this has the same effect as using +the corresponding index, but makes the history clearer and the line +easier to edit. With this setting, if part of an argument was +already typed, normal directory completion rather than recent +directory completion is done; this is because recent directory +completion is expected to be done by cycling through entries menu +fashion. + +@noindent +If the value of the style is @t{always}, then only recent directories will +be completed; in that case, use the @t{cd} command when you want to +complete other directories. + +@noindent +If the value is @t{fallback}, recent directories will be tried first, then +normal directory completion is performed if recent directory completion +failed to find a match. + +@noindent +Finally, if the value is @t{both} then both sets of completions are +presented; the usual tag mechanism can be used to distinguish results, with +recent directories tagged as @t{recent-dirs}. Note that the recent +directories inserted are abbreviated with directory names where appropriate. + +@item @t{recent-dirs-max} +The maximum number of directories to save to the file. If +this is zero or negative there is no maximum. The default is 20. +Note this includes the current directory, which isn't offered, +so the highest number of directories you will be offered +is one less than the maximum. + +@item @t{recent-dirs-prune} +This style is an array determining what directories should (or should +not) be added to the recent list. Elements of the array can include: + +@noindent +@table @asis +@item @t{parent} +Prune parents (more accurately, ancestors) from the recent list. +If present, changing directly down by any number of directories +causes the current directory to be overwritten. For example, +changing from ~pws to ~pws/some/other/dir causes ~pws not to be +left on the recent directory stack. This only applies to direct +changes to descendant directories; earlier directories on the +list are not pruned. For example, changing from ~pws/yet/another +to ~pws/some/other/dir does not cause ~pws to be pruned. + +@item @t{pattern:@var{pattern}} +Gives a zsh pattern for directories that should not be +added to the recent list (if not already there). This element +can be repeated to add different patterns. For example, +@t{'pattern:/tmp(|/*)'} stops @t{/tmp} or its descendants +from being added. The @t{EXTENDED_GLOB} option is always turned on +for these patterns. + +@end table + +@item @t{recent-dirs-pushd} +If set to true, @t{cdr} will use @t{pushd} instead of @t{cd} to change the +directory, so the directory is saved on the directory stack. As the +directory stack is completely separate from the list of files saved +by the mechanism used in this file there is no obvious reason to do +this. + +@end table + +@noindent + +@subsection Use with dynamic directory naming +@noindent + +@noindent +It is possible to refer to recent directories using the dynamic directory +name syntax by using the supplied function @t{zsh_directory_name_cdr} +a hook: + +@noindent +@example +autoload -Uz add-zsh-hook +add-zsh-hook -Uz zsh_directory_name zsh_directory_name_cdr +@end example + +@noindent +When this is done, @t{~[1]} will refer to the most recent +directory other than $PWD, and so on. Completion after @t{~[}@var{...} +also works. + +@noindent + +@subsection Details of directory handling +@noindent + +@noindent +This section is for the curious or confused; most users will not +need to know this information. + +@noindent +Recent directories are saved to a file immediately and hence are +preserved across sessions. Note currently no file locking is applied: +the list is updated immediately on interactive commands and nowhere else +(unlike history), and it is assumed you are only going to change +directory in one window at once. This is not safe on shared accounts, +but in any case the system has limited utility when someone else is +changing to a different set of directories behind your back. + +@noindent +To make this a little safer, only directory changes instituted from the +command line, either directly or indirectly through shell function calls +(but not through subshells, evals, traps, completion functions and the +like) are saved. Shell functions should use @t{cd -q} or @t{pushd -q} to +avoid side effects if the change to the directory is to be invisible at the +command line. See the contents of the function @t{chpwd_recent_dirs} for +more details. + +@noindent +@node Other Directory Functions, Version Control Information, Recent Directories, User Contributions +@cindex directories, named, dynamic, helper function +@cindex dynamic directory naming, helper function +@cindex named directories, dynamic, helper function +@findex zsh_directory_name_generic + +@section Abbreviated dynamic references to directories +@noindent + +@noindent +The dynamic directory naming system is described in the subsection +@emph{Dynamic named directories} of +@ref{Filename Expansion}. In this, a reference to +@t{~[}@var{...}@t{]} is expanded by a function found by the hooks +mechanism. + +@noindent +The contributed function @t{zsh_directory_name_generic} provides a +system allowing the user to refer to directories with only a limited +amount of new code. It supports all three of the standard interfaces +for directory naming: converting from a name to a directory, converting +in the reverse direction to find a short name, and completion of names. + +@noindent +The main feature of this function is a path-like syntax, +combining abbreviations at multiple levels separated by ":". +As an example, ~[g:p:s] might specify: +@table @asis +@item @t{g} +The top level directory for your git area. This first component +has to match, or the function will return indicating another +directory name hook function should be tried. + +@item @t{p} +The name of a project within your git area. + +@item @t{s} +The source area within that project. + +@end table +This allows you to collapse references to long hierarchies to a very +compact form, particularly if the hierarchies are similar across different +areas of the disk. + +@noindent +Name components may be completed: if a description is shown at the top +of the list of completions, it includes the path to which previous +components expand, while the description for an individual completion +shows the path segment it would add. No additional configuration is +needed for this as the completion system is aware of the dynamic +directory name mechanism. + +@noindent + +@subsection Usage +@noindent + +@noindent +To use the function, first define a wrapper function for your specific +case. We'll assume it's to be autoloaded. This can have any name but +we'll refer to it as zdn_mywrapper. This wrapper function will define +various variables and then call this function with the same arguments +that the wrapper function gets. This configuration is described below. + +@noindent +Then arrange for the wrapper to be run as a zsh_directory_name hook: + +@noindent +@example +autoload -Uz add-zsh-hook zsh_diretory_name_generic zdn_mywrapper +add-zsh-hook -U zsh_directory_name zdn_mywrapper +@end example + +@noindent + +@subsection Configuration +@noindent + +@noindent +The wrapper function should define a local associative array zdn_top. +Alternatively, this can be set with a style called @t{mapping}. The +context for the style is @t{:zdn:}@var{wrapper-name} where +@var{wrapper-name} is the function calling zsh_directory_name_generic; +for example: + +@noindent +@example +zstyle :zdn:zdn_mywrapper: mapping zdn_mywrapper_top +@end example + +@noindent +The keys in this associative array correspond to the first component of +the name. The values are matching directories. They may have an +optional suffix with a slash followed by a colon and the name of a +variable in the same format to give the next component. (The slash +before the colon is to disambiguate the case where a colon is needed in +the path for a drive. There is otherwise no syntax for escaping this, +so path components whose names start with a colon are not supported.) A +special component @t{:default:} specifies a variable in the form +@t{/:}@var{var} (the path section is ignored and so is usually empty) +that will be used for the next component if no variable is given for the +path. Variables referred to within @t{zdn_top} have the same format as +@t{zdn_top} itself, but contain relative paths. + +@noindent +For example, + +@noindent +@example +local -A zdn_top=( + g ~/git + ga ~/alternate/git + gs /scratch/$USER/git/:second2 + :default: /:second1 +) +@end example + +@noindent +This specifies the behaviour of a directory referred to as @t{~[g:...]} +or @t{~[ga:...]} or @t{~[gs:...]}. Later path components are optional; +in that case @t{~[g]} expands to @t{~/git}, and so on. @t{gs} expands +to @t{/scratch/$USER/git} and uses the associative array @t{second2} to +match the second component; @t{g} and @t{ga} use the associative array +@t{second1} to match the second component. + +@noindent +When expanding a name to a directory, if the first component is not @t{g} or +@t{ga} or @t{gs}, it is not an error; the function simply returns 1 so that a +later hook function can be tried. However, matching the first component +commits the function, so if a later component does not match, an error +is printed (though this still does not stop later hooks from being +executed). + +@noindent +For components after the first, a relative path is expected, but note that +multiple levels may still appear. Here is an example of @t{second1}: + +@noindent +@example +local -A second1=( + p myproject + s somproject + os otherproject/subproject/:third +) +@end example + +@noindent +The path as found from @t{zdn_top} is extended with the matching +directory, so @t{~[g:p]} becomes @t{~/git/myproject}. The slash between +is added automatically (it's not possible to have a later component +modify the name of a directory already matched). Only @t{os} specifies +a variable for a third component, and there's no @t{:default:}, so it's +an error to use a name like @t{~[g:p:x]} or @t{~[ga:s:y]} because +there's nowhere to look up the @t{x} or @t{y}. + +@noindent +The associative arrays need to be visible within this function; the +generic function therefore uses internal variable names beginning +@t{_zdn_} in order to avoid clashes. Note that the variable @t{reply} +needs to be passed back to the shell, so should not be local in the +calling function. + +@noindent +The function does not test whether directories assembled by component +actually exist; this allows the system to work across automounted +file systems. The error from the command trying to use a non-existent +directory should be sufficient to indicate the problem. + +@noindent + +@subsection Complete example +@noindent + +@noindent +Here is a full fictitious but usable autoloadable definition of the +example function defined by the code above. So @t{~[gs:p:s]} expands +to @t{/scratch/$USER/git/myscratchproject/top/srcdir} (with @t{$USER} +also expanded). + +@noindent +@example +local -A zdn_top=( + g ~/git + ga ~/alternate/git + gs /scratch/$USER/git/:second2 + :default: /:second1 +) + +local -A second1=( + p myproject + s somproject + os otherproject/subproject/:third +) + +local -A second2=( + p myscratchproject + s somescratchproject +) + +local -A third=( + s top/srcdir + d top/documentation +) + +# autoload not needed if you did this at initialisation... +autoload -Uz zsh_directory_name_generic +zsh_directory_name_generic "$@@ +@end example + +@noindent +It is also possible to use global associative arrays, suitably named, +and set the style for the context of your wrapper function to +refer to this. Then your set up code would contain the following: + +@noindent +@example +typeset -A zdn_mywrapper_top=(...) +# ... and so on for other associative arrays ... +zstyle ':zdn:zdn_mywrapper:' mapping zdn_mywrapper_top +autoload -Uz add-zsh-hook zsh_directory_name_generic zdn_mywrapper +add-zsh-hook -U zsh_directory_name zdn_mywrapper +@end example + +@noindent +and the function @t{zdn_mywrapper} would contain only the following: + +@noindent +@example +zsh_directory_name_generic "$@@" +@end example + +@noindent +@node Version Control Information, Prompt Themes, Other Directory Functions, User Contributions + +@section Gathering information from version control systems +@noindent +@cindex version control utility + +@noindent +In a lot of cases, it is nice to automatically retrieve information from +version control systems (VCSs), such as subversion, CVS or git, to be able +to provide it to the user; possibly in the user's prompt. So that you can +instantly tell which branch you are currently on, for example. + +@noindent +In order to do that, you may use the @t{vcs_info} function. + +@noindent +The following VCSs are supported, showing the abbreviated name by which +they are referred to within the system: +@table @asis +@item Bazaar (@t{bzr}) +@t{@uref{https://bazaar.canonical.com/}} +@item Codeville (@t{cdv}) +@t{@uref{http://freecode.com/projects/codeville/}} +@item Concurrent Versioning System (@t{cvs}) +@t{@uref{https://www.nongnu.org/cvs/}} +@item Darcs (@t{darcs}) +@t{@uref{http://darcs.net/}} +@item Fossil (@t{fossil}) +@t{@uref{https://fossil-scm.org/}} +@item Git (@t{git}) +@t{@uref{https://git-scm.com/}} +@item GNU arch (@t{tla}) +@t{@uref{https://www.gnu.org/software/gnu-arch/}} +@item Mercurial (@t{hg}) +@t{@uref{https://www.mercurial-scm.org/}} +@item Monotone (@t{mtn}) +@t{@uref{https://monotone.ca/}} +@item Perforce (@t{p4}) +@t{@uref{https://www.perforce.com/}} +@item Subversion (@t{svn}) +@t{@uref{https://subversion.apache.org/}} +@item SVK (@t{svk}) +@t{@uref{https://svk.bestpractical.com/}} +@end table + +@noindent +There is also support for the patch management system @t{quilt} +(@t{@uref{https://savannah.nongnu.org/projects/quilt}}). See +@ref{vcs_info Quilt Support} +below for details. + +@noindent +To load @t{vcs_info}: + +@noindent +@example +autoload -Uz vcs_info +@end example + +@noindent +It can be used in any existing prompt, because it does not require any +specific @t{$psvar} entries to be available. + +@noindent +@menu +* vcs_info Quickstart:: +* vcs_info Configuration:: +* vcs_info Oddities:: +* vcs_info Quilt Support:: +* vcs_info API:: +* vcs_info Variables:: +* vcs_info Hooks:: +* vcs_info Examples:: +@end menu + +@noindent +@node vcs_info Quickstart, vcs_info Configuration, , Version Control Information + +@subsection Quickstart +@noindent + +@noindent +To get this feature working quickly (including colors), you can do the +following (assuming, you loaded @t{vcs_info} properly - see above): + +@noindent +@example +zstyle ':vcs_info:*' actionformats \ + '%F@{5@}(%f%s%F@{5@})%F@{3@}-%F@{5@}[%F@{2@}%b%F@{3@}|%F@{1@}%a%F@{5@}]%f ' +zstyle ':vcs_info:*' formats \ + '%F@{5@}(%f%s%F@{5@})%F@{3@}-%F@{5@}[%F@{2@}%b%F@{5@}]%f ' +zstyle ':vcs_info:(sv[nk]|bzr):*' branchformat '%b%F@{1@}:%F@{3@}%r' +precmd () @{ vcs_info @} +PS1='%F@{5@}[%F@{2@}%n%F@{5@}] %F@{3@}%3~ $@{vcs_info_msg_0_@}%f%# ' +@end example + +@noindent +Obviously, the last two lines are there for demonstration. You need to +call @t{vcs_info} from your @t{precmd} function. Once that is done you need +a @emph{single quoted} @t{'$@{vcs_info_msg_0_@}'} in your prompt. + +@noindent +To be able to use @t{'$@{vcs_info_msg_0_@}'} directly in your prompt like +this, you will need to have the @t{PROMPT_SUBST} option enabled. + +@noindent +Now call the @t{vcs_info_printsys} utility from the command line: + +@noindent +@example +% vcs_info_printsys +## list of supported version control backends: +## disabled systems are prefixed by a hash sign (#) +bzr +cdv +cvs +darcs +fossil +git +hg +mtn +p4 +svk +svn +tla +## flavours (cannot be used in the enable or disable styles; they +## are enabled and disabled with their master [git-svn -> git]) +## they *can* be used in contexts: ':vcs_info:git-svn:*'. +git-p4 +git-svn +hg-git +hg-hgsubversion +hg-hgsvn +@end example + +@noindent +You may not want all of these because there is no point in running the +code to detect systems you do not use. So there is a way to disable +some backends altogether: + +@noindent +@example +zstyle ':vcs_info:*' disable bzr cdv darcs mtn svk tla +@end example + +@noindent +You may also pick a few from that list and enable only those: + +@noindent +@example +zstyle ':vcs_info:*' enable git cvs svn +@end example + +@noindent +If you rerun @t{vcs_info_printsys} after one of these commands, you will +see the backends listed in the @t{disable} style (or backends not in the +@t{enable} style - if you used that) marked as disabled by a hash sign. +That means the detection of these systems is skipped @emph{completely}. No +wasted time there. + +@noindent +@node vcs_info Configuration, vcs_info Oddities, vcs_info Quickstart, Version Control Information + +@subsection Configuration +@noindent + +@noindent +The @t{vcs_info} feature can be configured via @t{zstyle}. + +@noindent +First, the context in which we are working: +@example +:vcs_info:@var{vcs-string}:@var{user-context}:@var{repo-root-name} +@end example + +@noindent +@table @asis +@item @var{vcs-string} +is one of: @t{git}, @t{git-svn}, @t{git-p4}, @t{hg}, @t{hg-git}, +@t{hg-hgsubversion}, @t{hg-hgsvn}, @t{darcs}, @t{bzr}, @t{cdv}, @t{mtn}, +@t{svn}, @t{cvs}, @t{svk}, @t{tla}, @t{p4} or @t{fossil}. +This is followed by `@t{.quilt-}@var{quilt-mode}' in Quilt mode +(see @ref{vcs_info Quilt Support} for details) +and by `@t{+}@var{hook-name}' while hooks are active +(see @ref{vcs_info Hooks} for details). + +@noindent + +Currently, hooks in quilt mode don't add the `@t{.quilt-}@var{quilt-mode}' information. +This may change in the future. + +@item @var{user-context} +is a freely configurable string, assignable by +the user as the first argument to @t{vcs_info} (see its description +below). + +@item @var{repo-root-name} +is the name of a repository in which you want a +style to match. So, if you want a setting specific to @t{/usr/src/zsh}, +with that being a CVS checkout, you can set @var{repo-root-name} to +@t{zsh} to make it so. + +@end table + +@noindent +There are three special values for @var{vcs-string}: The first is named +@t{-init-}, that is in effect as long as there was no decision what VCS +backend to use. The second is @t{-preinit-}; it is used @emph{before} +@t{vcs_info} is run, when initializing the data exporting variables. The +third special value is @t{formats} and is used by the @t{vcs_info_lastmsg} +for looking up its styles. + +@noindent +The initial value of @var{repo-root-name} is @t{-all-} and it is replaced +with the actual name, as soon as it is known. Only use this part of the +context for defining the @t{formats}, @t{actionformats} or +@t{branchformat} styles, as it is guaranteed that @var{repo-root-name} is +set up correctly for these only. For all other styles, just use @t{'*'} +instead. + +@noindent +There are two pre-defined values for @var{user-context}: +@table @asis +@item @t{default} +the one used if none is specified +@item @t{command} +used by vcs_info_lastmsg to lookup its styles +@end table + +@noindent +You can of course use @t{':vcs_info:*'} to match all VCSs in all +user-contexts at once. + +@noindent +This is a description of all styles that are looked up. + +@noindent +@table @asis +@kindex formats +@item @t{formats} +A list of formats, used when actionformats is not used +(which is most of the time). + +@kindex actionformats +@item @t{actionformats} +A list of formats, used if there is a special +action going on in your current repository; like an interactive rebase or +a merge conflict. + +@kindex branchformat +@item @t{branchformat} +Some backends replace @t{%b} in the formats and +actionformats styles above, not only by a branch name but also by a +revision number. This style lets you modify how that string should look. + +@kindex nvcsformats +@item @t{nvcsformats} +These "formats" are set when we didn't detect a version control system +for the current directory or @t{vcs_info} was disabled. This is useful if +you want @t{vcs_info} to completely take over the generation of your +prompt. You would do something like @t{PS1='$@{vcs_info_msg_0_@}'} to +accomplish that. + +@kindex hgrevformat +@item @t{hgrevformat} +@t{hg} uses both a hash and a revision number to reference a specific +changeset in a repository. With this style you can format the revision +string (see @t{branchformat}) to include either or both. It's only +useful when @t{get-revision} is true. Note, the full 40-character revision id +is not available (except when using the @t{use-simple} option) because +executing hg more than once per prompt is too slow; you may customize this +behavior using hooks. + +@kindex max-exports +@item @t{max-exports} +Defines the maximum number of +@t{vcs_info_msg_*_} variables @t{vcs_info} will set. + +@kindex enable +@item @t{enable} +A list of backends you want to use. Checked in the @t{-init-} context. If +this list contains an item called @t{NONE} no backend is used at all and +@t{vcs_info} will do nothing. If this list contains @t{ALL}, @t{vcs_info} +will use all known backends. Only with @t{ALL} in @t{enable} will the +@t{disable} style have any effect. @t{ALL} and @t{NONE} are case insensitive. + +@kindex disable +@item @t{disable} +A list of VCSs you don't want @t{vcs_info} to test for +repositories (checked in the @t{-init-} context, too). Only used if +@t{enable} contains @t{ALL}. + +@kindex disable-patterns +@item @t{disable-patterns} +A list of patterns that are checked against @t{$PWD}. If a pattern +matches, @t{vcs_info} will be disabled. This style is checked in the +@t{:vcs_info:-init-:*:-all-} context. + +@noindent +Say, @t{~/.zsh} is a directory under version control, in which you do +not want @t{vcs_info} to be active, do: +@example +zstyle ':vcs_info:*' disable-patterns "$@{(b)HOME@}/.zsh(|/*)" +@end example + +@kindex use-quilt +@item @t{use-quilt} +If enabled, the @t{quilt} support code is active in `addon' mode. +See @ref{vcs_info Quilt Support} for details. + +@kindex quilt-standalone +@item @t{quilt-standalone} +If enabled, `standalone' mode detection is attempted if no VCS is active +in a given directory. See @ref{vcs_info Quilt Support} for details. + +@kindex quilt-patch-dir +@item @t{quilt-patch-dir} +Overwrite the value of the @t{$QUILT_PATCHES} environment variable. See +@ref{vcs_info Quilt Support} for details. + +@kindex quiltcommand +@item @t{quiltcommand} +When @t{quilt} itself is called in quilt support, the value of this style +is used as the command name. + +@kindex check-for-changes +@item @t{check-for-changes} +If enabled, this style causes the @t{%c} and @t{%u} format escapes to show +when the working directory has uncommitted changes. The strings displayed by +these escapes can be controlled via the @t{stagedstr} and @t{unstagedstr} +styles. The only backends that currently support this option are @t{git}, +@t{hg}, and @t{bzr} (the latter two only support unstaged). + +@noindent +For this style to be evaluated with the @t{hg} backend, the @t{get-revision} +style needs to be set and the @t{use-simple} style needs to be unset. The +latter is the default; the former is not. + +@noindent +With the @t{bzr} backend, @emph{lightweight checkouts} only honor this style if +the @t{use-server} style is set. + +@noindent +Note, the actions taken if this style is enabled are potentially expensive +(read: they may be slow, depending on how big the current repository is). +Therefore, it is disabled by default. + +@kindex check-for-staged-changes +@item @t{check-for-staged-changes} +This style is like @t{check-for-changes}, but it never checks the worktree +files, only the metadata in the @t{.$@{vcs@}} dir. Therefore, +this style initializes only the @t{%c} escape (with @t{stagedstr}) but +not the @t{%u} escape. This style is faster than @t{check-for-changes}. + +@noindent +In the @t{git} backend, this style checks for changes in the index. +Other backends do not currently implement this style. + +@noindent +This style is disabled by default. + +@kindex stagedstr +@item @t{stagedstr} +This string will be used in the @t{%c} escape if there are staged changes in +the repository. + +@kindex unstagedstr +@item @t{unstagedstr} +This string will be used in the @t{%u} escape if there are unstaged changes +in the repository. + +@kindex command +@item @t{command} +This style causes @t{vcs_info} to use the supplied string as the command +to use as the VCS's binary. Note, that setting this in '@t{:vcs_info:*}' is +not a good idea. + +@noindent +If the value of this style is empty (which is the default), the used binary +name is the name of the backend in use (e.g. @t{svn} is used in an @t{svn} +repository). + +@noindent +The @t{repo-root-name} part in the context is always the default @t{-all-} +when this style is looked up. + +@noindent +For example, this style can be used to use binaries from non-default +installation directories. Assume, @t{git} is installed in /usr/bin but +your sysadmin installed a newer version in /usr/local/bin. Instead of +changing the order of your @t{$PATH} parameter, you can do this: +@example +zstyle ':vcs_info:git:*:-all-' command /usr/local/bin/git +@end example + +@kindex use-server +@item @t{use-server} +This is used by the Perforce backend (@t{p4}) to decide if it should +contact the Perforce server to find out if a directory is managed +by Perforce. This is the only reliable way of doing this, but runs +the risk of a delay if the server name cannot be found. If the +server (more specifically, the @t{host}@t{:}@t{port} pair describing the +server) cannot be contacted, its name is put into the associative array +@t{vcs_info_p4_dead_servers} and is not contacted again during the session +until it is removed by hand. If you do not set this style, the @t{p4} +backend is only usable if you have set the environment variable +@t{P4CONFIG} to a file name and have corresponding files in the root +directories of each Perforce client. See comments in the function +@t{VCS_INFO_detect_p4} for more detail. + +@noindent +The Bazaar backend (@t{bzr}) uses this to permit contacting the server +about lightweight checkouts, see the @t{check-for-changes} style. + +@kindex use-simple +@item @t{use-simple} +If there are two different ways of gathering +information, you can select the simpler one by setting this style to true; +the default is to use the not-that-simple code, which is potentially a lot +slower but might be more accurate in all possible cases. This style is +used by the @t{bzr} and @t{hg} backends. In the case of @t{hg} it will invoke +the external hexdump program to parse the binary dirstate cache file; this +method will not return the local revision number. + +@kindex get-revision +@item @t{get-revision} +If set to true, vcs_info goes the extra mile to figure out the revision of +a repository's work tree (currently for the @t{git} and @t{hg} backends, +where this kind of information is not always vital). For @t{git}, the +hash value of the currently checked out commit is available via the @t{%i} +expansion. With @t{hg}, the local revision number and the corresponding +global hash are available via @t{%i}. + +@kindex get-mq +@item @t{get-mq} +If set to true, the @t{hg} backend will look for a Mercurial Queue (@t{mq}) +patch directory. Information will be available via the `@t{%m}' replacement. + +@kindex get-bookmarks +@item @t{get-bookmarks} +If set to true, the @t{hg} backend will try to get a list of current +bookmarks. They will be available via the `@t{%m}' replacement. + +@noindent +The default is to generate a comma-separated list of all bookmark names +that refer to the currently checked out revision. If a bookmark is active, +its name is suffixed an asterisk and placed first in the list. + +@kindex use-prompt-escapes +@item @t{use-prompt-escapes} +Determines if we assume that the assembled +string from @t{vcs_info} includes prompt escapes. (Used by +@t{vcs_info_lastmsg}.) + +@kindex debug +@item @t{debug} +Enable debugging output to track possible problems. Currently this style +is only used by @t{vcs_info}'s hooks system. + +@kindex hooks +@item @t{hooks} +A list style that defines hook-function names. See @ref{vcs_info Hooks} +below for details. + +@kindex patch-format +@kindex nopatch-format +@item @t{patch-format} +@itemx @t{nopatch-format} +This pair of styles format the patch information used by the @t{%m} expando in +formats and actionformats for the @t{git} and @t{hg} backends. The value is +subject to certain @t{%}-expansions described below. +The expanded value is made available in the global @t{backend_misc} array as +@t{$@{backend_misc[patches]@}} (also if a @t{set-patch-format} hook is used). + +@kindex get-unapplied +@item @t{get-unapplied} +This boolean style controls whether a backend should attempt to gather a list +of unapplied patches (for example with Mercurial Queue patches). + +@noindent +Used by the @t{quilt} and @t{hg} backends. + +@end table + +@noindent +The default values for these styles in all contexts are: + +@noindent +@table @asis +@item @t{formats} +" (%s)-[%b]%u%c-" +@item @t{actionformats} +" (%s)-[%b|%a]%u%c-" +@item @t{branchformat} +"%b:%r" (for bzr, svn, svk and hg) +@item @t{nvcsformats} +"" +@item @t{hgrevformat} +"%r:%h" +@item @t{max-exports} +2 +@item @t{enable} +ALL +@item @t{disable} +(empty list) +@item @t{disable-patterns} +(empty list) +@item @t{check-for-changes} +false +@item @t{check-for-staged-changes} +false +@item @t{stagedstr} +(string: "S") +@item @t{unstagedstr} +(string: "U") +@item @t{command} +(empty string) +@item @t{use-server} +false +@item @t{use-simple} +false +@item @t{get-revision} +false +@item @t{get-mq} +true +@item @t{get-bookmarks} +false +@item @t{use-prompt-escapes} +true +@item @t{debug} +false +@item @t{hooks} +(empty list) +@item @t{use-quilt} +false +@item @t{quilt-standalone} +false +@item @t{quilt-patch-dir} +empty - use @t{$QUILT_PATCHES} +@item @t{quiltcommand} +quilt +@item @t{patch-format} +@var{backend dependent} +@item @t{nopatch-format} +@var{backend dependent} +@item @t{get-unapplied} +false +@end table + +@noindent +In normal @t{formats} and @t{actionformats} the following replacements are +done: + +@noindent +@table @asis +@item @t{%s} +The VCS in use (git, hg, svn, etc.). +@item @t{%b} +Information about the current branch. +@item @t{%a} +An identifier that describes the action. Only makes sense in +@t{actionformats}. +@item @t{%i} +The current revision number or identifier. For @t{hg} +the @t{hgrevformat} style may be used to customize the output. +@item @t{%c} +The string from the @t{stagedstr} style if there are staged +changes in the repository. +@item @t{%u} +The string from the @t{unstagedstr} style if there are +unstaged changes in the repository. +@item @t{%R} +The base directory of the repository. +@item @t{%r} +The repository name. If @t{%R} is @t{/foo/bar/repoXY}, @t{%r} +is @t{repoXY}. +@item @t{%S} +A subdirectory within a repository. If @t{$PWD} is +@t{/foo/bar/repoXY/beer/tasty}, @t{%S} is @t{beer/tasty}. +@end table +@table @asis +@item @t{%m} +A "misc" replacement. It is at the discretion of the backend to +decide what this replacement expands to. + +@noindent +The @t{hg} and @t{git} backends use this expando to display patch information. +@t{hg} sources patch information from the @t{mq} extensions; @t{git} from in-progress +@t{rebase} and @t{cherry-pick} operations and from the @t{stgit} extension. The @t{patch-format} +and @t{nopatch-format} styles control the generated string. The former is used +when at least one patch from the patch queue has been applied, and the latter +otherwise. + +@noindent +The @t{hg} backend displays bookmark information in this expando (in addition +to @t{mq} information). See the @t{get-mq} and @t{get-bookmarks} styles. Both +of these styles may be enabled at the same time. If both are enabled, both +resulting strings will be shown separated by a semicolon (that cannot currently +be customized). + +@noindent +The @t{quilt} `standalone' backend sets this expando to the same value as the +@t{%Q} expando. + +@item @t{%Q} +Quilt series information. +When quilt is used (either in `addon' mode or as a `standalone' backend), +this expando is set to quilt series' @t{patch-format} string. +The @t{set-patch-format} hook and @t{nopatch-format} style are honoured. + +@noindent +See @ref{vcs_info Quilt Support} below for details. + +@end table + +@noindent +In @t{branchformat} these replacements are done: + +@noindent +@table @asis +@item @t{%b} +The branch name. +@item @t{%r} +The current revision number or the @t{hgrevformat} style for +@t{hg}. +@end table + +@noindent +In @t{hgrevformat} these replacements are done: + +@noindent +@table @asis +@item @t{%r} +The current local revision number. +@item @t{%h} +The current global revision identifier. +@end table + +@noindent +In @t{patch-format} and @t{nopatch-format} these replacements are done: + +@noindent +@table @asis +@item @t{%p} +The name of the top-most applied patch; may be overridden by the @t{applied-string} hook. +@item @t{%u} +The number of unapplied patches; may be overridden by the @t{unapplied-string} hook. +@item @t{%n} +The number of applied patches. +@item @t{%c} +The number of unapplied patches. +@item @t{%a} +The number of all patches (@t{%a = %n + %c}). +@item @t{%g} +The names of active @t{mq} guards (@t{hg} backend). +@item @t{%G} +The number of active @t{mq} guards (@t{hg} backend). +@end table + +@noindent +Not all VCS backends have to support all replacements. For @t{nvcsformats} +no replacements are performed at all, it is just a string. + +@noindent +@node vcs_info Oddities, vcs_info Quilt Support, vcs_info Configuration, Version Control Information + +@subsection Oddities +@noindent + +@noindent +If you want to use the @t{%b} (bold off) prompt expansion in @t{formats}, +which expands @t{%b} itself, use @t{%%b}. That will cause the @t{vcs_info} +expansion to replace @t{%%b} with @t{%b}, so that zsh's prompt expansion +mechanism can handle it. Similarly, to hand down @t{%b} from +@t{branchformat}, use @t{%%%%b}. Sorry for this inconvenience, but it +cannot be easily avoided. Luckily we do not clash with a lot of prompt +expansions and this only needs to be done for those. + +@noindent +When one of the @t{gen-applied-string}, @t{gen-unapplied-string}, and +@t{set-patch-format} hooks is defined, +applying @t{%}-escaping (`@t{foo=$@{foo//'%'/%%@}}') to the interpolated values +for use in the prompt is the responsibility of those hooks (jointly); +when neither of those hooks is defined, @t{vcs_info} handles escaping by itself. +We regret this coupling, but it was required for backwards compatibility. + +@noindent +@node vcs_info Quilt Support, vcs_info API, vcs_info Oddities, Version Control Information + +@subsection Quilt Support +@noindent + +@noindent +@cite{Quilt} is not a version control system, therefore this is not implemented +as a backend. It can help keeping track of a series of patches. People use it +to keep a set of changes they want to use on top of software packages (which +is tightly integrated into the package build process - the Debian project +does this for a large number of packages). Quilt can also help individual +developers keep track of their own patches on top of real version control +systems. + +@noindent +The @t{vcs_info} integration tries to support both ways of using quilt by +having two slightly different modes of operation: `addon' mode and +`standalone' mode). + +@noindent +Quilt integration is off by default; to enable it, set the @t{use-quilt} style, +and add @t{%Q} to your @t{formats} or @t{actionformats} style: +@example +zstyle ':vcs_info:*' use-quilt true +@end example + +@noindent +Styles looked up from the Quilt support code include `@t{.quilt-}@var{quilt-mode}' +in the @var{vcs-string} part of the context, where @var{quilt-mode} is either +@t{addon} or @t{standalone}. +Example: @t{:vcs_info:git.quilt-addon:default:}@var{repo-root-name}. + +@noindent +For `addon' mode to become active @t{vcs_info} must have already detected a +real version control system controlling the directory. If that is the case, +a directory that holds quilt's patches needs to be found. That directory is +configurable via the `@t{QUILT_PATCHES}' environment variable. If that +variable exists its value is used, otherwise the value `@t{patches}' is +assumed. The value from @t{$QUILT_PATCHES} can be overwritten using the +`@t{quilt-patches}' style. (Note: you can use @t{vcs_info} to keep the value +of @t{$QUILT_PATCHES} correct all the time via the @t{post-quilt} hook). + +@noindent +When the directory in question is found, quilt is assumed to be active. To +gather more information, @t{vcs_info} looks for a directory called `.pc'; +Quilt uses that directory to track its current state. If this directory does +not exist we know that quilt has not done anything to the working directory +(read: no patches have been applied yet). + +@noindent +If patches are applied, @t{vcs_info} will try to find out which. If you want +to know which patches of a series are not yet applied, you need to activate +the @t{get-unapplied} style in the appropriate context. + +@noindent +@t{vcs_info} allows for very detailed control over how the gathered +information is presented (see +@ref{vcs_info Configuration} and @ref{vcs_info Hooks}), +all of which are documented below. Note there are a number of +other patch tracking systems that work on top of a certain version control +system (like @t{stgit} for @cite{git}, or @t{mq} for @cite{hg}); the configuration +for systems like that are generally configured the same way as the @cite{quilt} +support. + +@noindent +If the @cite{quilt} support is working in `addon' mode, the produced string is +available as a simple format replacement (@t{%Q} to be precise), which can +be used in @t{formats} and @t{actionformats}; see below for details). + +@noindent +If, on the other hand, the support code is working in `standalone' mode, +@t{vcs_info} will pretend as if @t{quilt} were an actual version control +system. That means that the version control system identifier (which +otherwise would be something like `svn' or `cvs') will be set to +`@t{-quilt-}'. This has implications on the used style context where this +identifier is the second element. @t{vcs_info} will have filled in a proper +value for the "repository's" root directory and the string containing the +information about quilt's state will be available as the `misc' replacement +(and @t{%Q} for compatibility with `addon' mode). + +@noindent +What is left to discuss is how `standalone' mode is detected. The detection +itself is a series of searches for directories. You can have this detection +enabled all the time in every directory that is not otherwise under version +control. If you know there is only a limited set of trees where you would +like @t{vcs_info} to try and look for Quilt in `standalone' mode to minimise +the amount of searching on every call to @t{vcs_info}, there are a number of +ways to do that: + +@noindent +Essentially, `standalone' mode detection is controlled by a style called +`@t{quilt-standalone}'. It is a string style and its value can have different +effects. The simplest values are: `@t{always}' to run detection every time +@t{vcs_info} is run, and `@t{never}' to turn the detection off entirely. + +@noindent +If the value of @t{quilt-standalone} is something else, it is interpreted +differently. If the value is the name of a scalar variable the value of that +variable is checked and that value is used in the same `always'/`never' way +as described above. + +@noindent +If the value of @t{quilt-standalone} is an array, the elements of that array +are used as directory names under which you want the detection to be active. + +@noindent +If @t{quilt-standalone} is an associative array, the keys are taken as +directory names under which you want the detection to be active, but only if +the corresponding value is the string `@t{true}'. + +@noindent +Last, but not least, if the value of @t{quilt-standalone} is the name of a +function, the function is called without arguments and the return value +decides whether detection should be active. A `0' return value is true; a +non-zero return value is interpreted as false. + +@noindent +Note, if there is both a function and a variable by the name of +@t{quilt-standalone}, the function will take precedence. + +@noindent +@node vcs_info API, vcs_info Variables, vcs_info Quilt Support, Version Control Information + +@subsection Function Descriptions (Public API) +@noindent + +@noindent +@table @asis +@findex vcs_info +@item @t{vcs_info} [@var{user-context}] +The main function, that runs all backends and assembles all data into +@t{$@{vcs_info_msg_*_@}}. This is the function you want to call from +@t{precmd} if you want to include up-to-date information in your prompt (see +@ref{vcs_info Variables} +below). If an argument is given, that string will be +used instead of @t{default} in the @var{user-context} field of the style +context. + +@findex vcs_info_hookadd +@item @t{vcs_info_hookadd} +Statically registers a number of functions to a given hook. The hook needs +to be given as the first argument; what follows is a list of hook-function +names to register to the hook. The `@t{+vi-}' prefix needs to be left out +here. See @ref{vcs_info Hooks} +below for details. + +@findex vcs_info_hookdel +@item @t{vcs_info_hookdel} +Remove hook-functions from a given hook. The hook needs to be given as the +first non-option argument; what follows is a list of hook-function +names to un-register from the hook. If `@t{-a}' is used as the first +argument, @t{all} occurrences of the functions are unregistered. Otherwise +only the last occurrence is removed (if a function was registered to a hook +more than once). The `@t{+vi-}' prefix needs to be left out here. +See @ref{vcs_info Hooks} +below for details. + +@findex vcs_info_lastmsg +@item @t{vcs_info_lastmsg} +Outputs the last @t{$@{vcs_info_msg_*_@}} value. +Takes into account the value of the @t{use-prompt-escapes} style in +@t{':vcs_info:formats:command:-all-'}. It also only prints @t{max-exports} +values. + +@findex vcs_info_printsys +@item @t{vcs_info_printsys} [@var{user-context}] +Prints a list of all +supported version control systems. Useful to find out possible contexts +(and which of them are enabled) or values for the @t{disable} style. + +@findex vcs_info_setsys +@item @t{vcs_info_setsys} +Initializes @t{vcs_info}'s internal list of +available backends. With this function, you can add support for new VCSs +without restarting the shell. + +@end table + +@noindent +All functions named @t{VCS_INFO_*} are for internal use only. + +@noindent +@node vcs_info Variables, vcs_info Hooks, vcs_info API, Version Control Information + +@subsection Variable Description +@noindent + +@noindent +@table @asis +@item @t{$@{vcs_info_msg_}@var{N}@t{_@}} (Note the trailing underscore) +Where @var{N} is an integer, e.g., @t{vcs_info_msg_0_}. These variables +are the storage for the informational message the last @t{vcs_info} call +has assembled. These are strongly connected to the @t{formats}, +@t{actionformats} and @t{nvcsformats} styles described above. Those styles +are lists. The first member of that list gets expanded into +@t{$@{vcs_info_msg_0_@}}, the second into @t{$@{vcs_info_msg_1_@}} +and the Nth into @t{$@{vcs_info_msg_N-1_@}}. (See the @t{max-exports} +style above.) + +@end table + +@noindent +All variables named @t{VCS_INFO_*} are for internal use only. + +@noindent +@node vcs_info Hooks, vcs_info Examples, vcs_info Variables, Version Control Information + +@subsection Hooks in vcs_info +@noindent + +@noindent +Hooks are places in @t{vcs_info} where you can run your own code. That +code can communicate with the code that called it and through that, +change the system's behaviour. + +@noindent +For configuration, hooks change the style context: +@example +:vcs_info:@var{vcs-string}+@var{hook-name}:@var{user-context}:@var{repo-root-name} +@end example + +@noindent +To register functions to a hook, you need to list them in the @t{hooks} +style in the appropriate context. + +@noindent +Example: +@example +zstyle ':vcs_info:*+foo:*' hooks bar baz +@end example + +@noindent +This registers functions to the hook `foo' for all backends. In order to +avoid namespace problems, all registered function names are prepended by +a `@t{+vi-}', so the actual functions called for the `foo' hook are +`@t{+vi-bar}' and `@t{+vi-baz}'. + +@noindent +If you would like to register a function to a hook regardless of the +current context, you may use the @t{vcs_info_hookadd} function. To remove +a function that was added like that, the @t{vcs_info_hookdel} function +can be used. + +@noindent +If something seems weird, you can enable the `debug' boolean style in +the proper context and the hook-calling code will print what it tried +to execute and whether the function in question existed. + +@noindent +When you register more than one function to a hook, all functions are +executed one after another until one function returns non-zero or until +all functions have been called. Context-sensitive hook functions are +executed @t{before} statically registered ones (the ones added by +@t{vcs_info_hookadd}). + +@noindent +You may pass data between functions via an associative array, @t{user_data}. +For example: +@example + ++vi-git-myfirsthook()@{ + user_data[myval]=$myval +@} ++vi-git-mysecondhook()@{ + # do something with $@{user_data[myval]@} +@} +@end example + +@noindent +There are a number of variables that are special in hook contexts: + +@noindent +@table @asis +@item @t{ret} +The return value that the hooks system will return to the caller. The +default is an integer `zero'. If and how a changed @t{ret} value changes +the execution of the caller depends on the specific hook. See the hook +documentation below for details. + +@item @t{hook_com} +An associated array which is used for bidirectional communication from +the caller to hook functions. The used keys depend on the specific hook. + +@item @t{context} +The active context of the hook. Functions that wish to change this +variable should make it local scope first. + +@item @t{vcs} +The current VCS after it was detected. The same values as in the +enable/disable style are used. Available in all hooks except @t{start-up}. + +@end table + +@noindent +Finally, the full list of currently available hooks: + +@noindent +@table @asis +@item @t{start-up} +Called after starting @t{vcs_info} but before the VCS in this directory is +determined. It can be used to deactivate @t{vcs_info} temporarily if +necessary. When @t{ret} is set to @t{1}, @t{vcs_info} aborts and does +nothing; when set to @t{2}, @t{vcs_info} sets up everything as if no +version control were active and exits. + +@item @t{pre-get-data} +Same as @t{start-up} but after the VCS was detected. + +@item @t{gen-hg-bookmark-string} +Called in the Mercurial backend when a bookmark string is generated; the +@t{get-revision} and @t{get-bookmarks} styles must be true. + +@noindent +This hook gets the names of the Mercurial bookmarks that +@t{vcs_info} collected from `hg'. + +@noindent +If a bookmark is active, the key @t{$@{hook_com[hg-active-bookmark]@}} is +set to its name. The key is otherwise unset. + +@noindent +When setting @t{ret} to non-zero, the string in +@t{$@{hook_com[hg-bookmark-string]@}} will be used in the @t{%m} escape in +@t{formats} and @t{actionformats} and will be available in the global +@t{backend_misc} array as @t{$@{backend_misc[bookmarks]@}}. + +@item @t{gen-applied-string} +Called in the @t{git} (with @t{stgit} or during rebase or merge), and @t{hg} +(with @t{mq}) backends and in @t{quilt} support when the @t{applied-string} +is generated; the @t{use-quilt} zstyle must be true for @t{quilt} (the @t{mq} +and @t{stgit} backends are active by default). + +@noindent +This hook gets the names of all applied patches which @t{vcs_info} collected +so far in the opposite order, which means that the first argument is the +top-most patch and so forth. + +@noindent +When setting @t{ret} to non-zero, the string in +@t{$@{hook_com[applied-string]@}} will be +available as @t{%p} in the @t{patch-format} and @t{nopatch-format} styles. +This hook is, in concert with @t{set-patch-format}, responsible for +@t{%}-escaping that value for use in the prompt. +(See @ref{vcs_info Oddities}.) + +@item @t{gen-unapplied-string} +Called in the @t{git} (with @t{stgit} or during rebase), and @t{hg} (with +@t{mq}) backend and in @t{quilt} support when the @t{unapplied-string} is +generated; the @t{get-unapplied} style must be true. + +@noindent +This hook gets the names of all unapplied patches which @t{vcs_info} +collected so far in order, which means that the first argument is +the patch next-in-line to be applied and so forth. + +@noindent +When setting @t{ret} to non-zero, the string in +@t{$@{hook_com[unapplied-string]@}} will be available as @t{%u} in the +@t{patch-format} and @t{nopatch-format} styles. +This hook is, in concert with @t{set-patch-format}, responsible for +@t{%}-escaping that value for use in the prompt. +(See @ref{vcs_info Oddities}.) + +@item @t{gen-mqguards-string} +Called in the @t{hg} backend when @t{guards-string} is generated; the +@t{get-mq} style must be true (default). + +@noindent +This hook gets the names of any active @t{mq} guards. + +@noindent +When setting @t{ret} to non-zero, the string in +@t{$@{hook_com[guards-string]@}} will be used in the @t{%g} escape in the +@t{patch-format} and @t{nopatch-format} styles. + +@item @t{no-vcs} +This hooks is called when no version control system was detected. + +@noindent +The `@t{hook_com}' parameter is not used. + +@item @t{post-backend} +Called as soon as the backend has finished collecting information. + +@noindent +The `@t{hook_com}' keys available are as for the @t{set-message} hook. + +@item @t{post-quilt} +Called after the @t{quilt} support is done. The following information +is passed as arguments to the hook: 1. the quilt-support mode (`addon' or +`standalone'); 2. the directory that contains the patch series; 3. the +directory that holds quilt's status information (the `.pc' directory) or +the string @t{"-nopc-"} if that directory wasn't found. + +@noindent +The `hook_com' parameter is not used. + +@item @t{set-branch-format} +Called before `@t{branchformat}' is set. The only argument to the +hook is the format that is configured at this point. + +@noindent +The `@t{hook_com}' keys considered are `@t{branch}' and `@t{revision}'. +They are set to the values figured out so far by @t{vcs_info} and any +change will be used directly when the actual replacement is done. + +@noindent +If @t{ret} is set to non-zero, the string in +@t{$@{hook_com[branch-replace]@}} will be used unchanged as the +`@t{%b}' replacement in the variables set by @t{vcs_info}. + +@item @t{set-hgrev-format} +Called before a `@t{hgrevformat}' is set. The only argument to the +hook is the format that is configured at this point. + +@noindent +The `@t{hook_com}' keys considered are `@t{hash}' and `@t{localrev}'. +They are set to the values figured out so far by @t{vcs_info} and any +change will be used directly when the actual replacement is done. + +@noindent +If @t{ret} is set to non-zero, the string in +@t{$@{hook_com[rev-replace]@}} will be used unchanged as the +`@t{%i}' replacement in the variables set by @t{vcs_info}. + +@item @t{pre-addon-quilt} +This hook is used when @t{vcs_info}'s quilt functionality is active in "addon" +mode (quilt used on top of a real version control system). It is activated +right before any quilt specific action is taken. + +@noindent +Setting the `@t{ret}' variable in this hook to a non-zero value avoids any +quilt specific actions from being run at all. + +@item @t{set-patch-format} +This hook is used to control some of the possible expansions in +@t{patch-format} and @t{nopatch-format} styles with patch queue systems such as +quilt, mqueue and the like. + +@noindent +This hook is used in the @t{git}, @t{hg} and @t{quilt} backends. + +@noindent +The hook allows the control of the @t{%p} (@t{$@{hook_com[applied]@}}) and @t{%u} +(@t{$@{hook_com[unapplied]@}}) expansion in all backends that use the hook. With +the mercurial backend, the @t{%g} (@t{$@{hook_com[guards]@}}) expansion is +controllable in addition to that. + +@noindent +If @t{ret} is set to non-zero, the string in @t{$@{hook_com[patch-replace]@}} +will be used unchanged instead of an expanded format from @t{patch-format} or +@t{nopatch-format}. + +@noindent +This hook is, in concert with the @t{gen-applied-string} or +@t{gen-unapplied-string} hooks if they are defined, responsible for +@t{%}-escaping the final @t{patch-format} value for use in the prompt. +(See @ref{vcs_info Oddities}.) + +@item @t{set-message} +Called each time before a `@t{vcs_info_msg_}@var{N}@t{_}' message is set. +It takes two arguments; the first being the `@var{N}' in the message +variable name, the second is the currently configured @t{formats} or +@t{actionformats}. + +@noindent +There are a number of `@t{hook_com}' keys, that are used here: +`@t{action}', `@t{branch}', `@t{base}', `@t{base-name}', `@t{subdir}', +`@t{staged}', `@t{unstaged}', `@t{revision}', `@t{misc}', `@t{vcs}' +and one `@t{miscN}' entry for each backend-specific data field (@t{N} +starting at zero). They are set to the values figured out so far by +@t{vcs_info} and any change will be used directly when the actual +replacement is done. + +@noindent +Since this hook is triggered multiple times (once for each configured +@t{formats} or @t{actionformats}), each of the `@t{hook_com}' keys mentioned +above (except for the @t{miscN} entries) has an `@t{_orig}' counterpart, +so even if you changed a value to your liking you can still get the +original value in the next run. Changing the `@t{_orig}' values is +probably not a good idea. + +@noindent +If @t{ret} is set to non-zero, the string in +@t{$@{hook_com[message]@}} will be used unchanged as the message by +@t{vcs_info}. + +@end table + +@noindent +If all of this sounds rather confusing, take a look at +@ref{vcs_info Examples} +and also in the @t{Misc/vcs_info-examples} file in the Zsh source. +They contain some explanatory code. + +@noindent +@node vcs_info Examples, , vcs_info Hooks, Version Control Information + +@subsection Examples +@noindent + +@noindent +Don't use @t{vcs_info} at all (even though it's in your prompt): +@example +zstyle ':vcs_info:*' enable NONE +@end example + +@noindent +Disable the backends for @t{bzr} and @t{svk}: +@example +zstyle ':vcs_info:*' disable bzr svk +@end example + +@noindent +Disable everything @emph{but} @t{bzr} and @t{svk}: +@example +zstyle ':vcs_info:*' enable bzr svk +@end example + +@noindent +Provide a special formats for @t{git}: +@example +zstyle ':vcs_info:git:*' formats ' GIT, BABY! [%b]' +zstyle ':vcs_info:git:*' actionformats ' GIT ACTION! [%b|%a]' +@end example + +@noindent +All @t{%x} expansion in all sorts of formats (@t{formats}, @t{actionformats}, +@t{branchformat}, you name it) are done using the `@t{zformat}' builtin from +the `@t{zsh/zutil}' module. That means you can do everything with these +@t{%x} items what zformat supports. In particular, if you want something +that is really long to have a fixed width, like a hash in a mercurial +branchformat, you can do this: @t{%12.12i}. That'll shrink the 40 character +hash to its 12 leading characters. The form is actually +`@t{%}@var{min}@t{.}@var{max}@t{x}'. More is possible. +See @ref{The zsh/zutil Module} for details. + +@noindent +Use the quicker @t{bzr} backend +@example +zstyle ':vcs_info:bzr:*' use-simple true +@end example + +@noindent +If you do use @t{use-simple}, please report if it does `the-right-thing[tm]'. + +@noindent +Display the revision number in yellow for @t{bzr} and @t{svn}: +@example +zstyle ':vcs_info:(svn|bzr):*' \ + branchformat '%b%@{'$@{fg[yellow]@}'%@}:%r' +@end example + +@noindent +If you want colors, make sure you enclose the color codes in @t{%@{}@var{...}@t{%@}} +if you want to use the string provided by @t{vcs_info} in prompts. + +@noindent +Here is how to print the VCS information as a command (not in a prompt): +@example +alias vcsi='vcs_info command; vcs_info_lastmsg' +@end example + +@noindent +This way, you can even define different formats for output via +@t{vcs_info_lastmsg} in the '@t{:vcs_info:*:command:*}' namespace. + +@noindent +Now as promised, some code that uses hooks: +say, you'd like to replace the string `svn' by `subversion' in +@t{vcs_info}'s @t{%s} @t{formats} replacement. + +@noindent +First, we will tell @t{vcs_info} to call a function when populating +the message variables with the gathered information: +@example +zstyle ':vcs_info:*+set-message:*' hooks svn2subversion +@end example + +@noindent +Nothing happens. Which is reasonable, since we didn't define the actual +function yet. To see what the hooks subsystem is trying to do, enable the +`@t{debug}' style: +@example +zstyle ':vcs_info:*+*:*' debug true +@end example + +@noindent +That should give you an idea what is going on. Specifically, the function +that we are looking for is `@t{+vi-svn2subversion}'. Note, the `@t{+vi-}' +prefix. So, everything is in order, just as documented. When you are done +checking out the debugging output, disable it again: +@example +zstyle ':vcs_info:*+*:*' debug false +@end example + +@noindent +Now, let's define the function: +@example + +function +vi-svn2subversion() @{ + [[ $@{hook_com[vcs_orig]@} == svn ]] && hook_com[vcs]=subversion +@} +@end example + +@noindent +Simple enough. And it could have even been simpler, if only we had +registered our function in a less generic context. If we do it only in +the `@t{svn}' backend's context, we don't need to test which the active +backend is: +@example +zstyle ':vcs_info:svn+set-message:*' hooks svn2subversion +@end example +@example + +function +vi-svn2subversion() @{ + hook_com[vcs]=subversion +@} +@end example + +@noindent +And finally a little more elaborate example, that uses a hook to create +a customised bookmark string for the @t{hg} backend. + +@noindent +Again, we start off by registering a function: +@example +zstyle ':vcs_info:hg+gen-hg-bookmark-string:*' hooks hgbookmarks +@end example + +@noindent +And then we define the `@t{+vi-hgbookmarks}' function: +@example + +function +vi-hgbookmarks() @{ + # The default is to connect all bookmark names by + # commas. This mixes things up a little. + # Imagine, there's one type of bookmarks that is + # special to you. Say, because it's *your* work. + # Those bookmarks look always like this: "sh/*" + # (because your initials are sh, for example). + # This makes the bookmarks string use only those + # bookmarks. If there's more than one, it + # concatenates them using commas. + # The bookmarks returned by `hg' are available in + # the function's positional parameters. + local s="$@{(Mj:,:)@@:#sh/*@}" + # Now, the communication with the code that calls + # the hook functions is done via the hook_com[] + # hash. The key at which the `gen-hg-bookmark-string' + # hook looks is `hg-bookmark-string'. So: + hook_com[hg-bookmark-string]=$s + # And to signal that we want to use the string we + # just generated, set the special variable `ret' to + # something other than the default zero: + ret=1 + return 0 +@} +@end example + +@noindent +Some longer examples and code snippets which might be useful are available in +the examples file located at Misc/vcs_info-examples in the Zsh source +directory. + +@noindent +This concludes our guided tour through zsh's @t{vcs_info}. + +@noindent +@node Prompt Themes, ZLE Functions, Version Control Information, User Contributions + +@section Prompt Themes +@noindent + +@noindent + +@subsection Installation +@noindent + +@noindent +You should make sure all the functions from the @t{Functions/Prompts} +directory of the source distribution are available; they all begin with +the string `@t{prompt_}' except for the special function`@t{promptinit}'. +You also need the `@t{colors}' and `@t{add-zsh-hook}' functions from +@t{Functions/Misc}. +All these functions may already be installed on your system; if not, +you will need to find them and copy them. The directory should appear as +one of the elements of the @t{fpath} array (this should already be the +case if they were installed), and at least the function @t{promptinit} +should be autoloaded; it will autoload the rest. Finally, to initialize +the use of the system you need to call the @t{promptinit} function. The +following code in your @t{.zshrc} will arrange for this; assume the +functions are stored in the directory @t{~/myfns}: + +@noindent +@example +fpath=(~/myfns $fpath) +autoload -U promptinit +promptinit +@end example + +@noindent + +@subsection Theme Selection +@noindent + +@noindent +Use the @t{prompt} command to select your preferred theme. This command +may be added to your @t{.zshrc} following the call to @t{promptinit} in +order to start zsh with a theme already selected. + +@noindent +@table @asis +@item @t{prompt} [ @t{-c} | @t{-l} ] +@itemx @t{prompt} [ @t{-p} | @t{-h} ] [ @var{theme} ... ] +@itemx @t{prompt} [ @t{-s} ] @var{theme} [ @var{arg} ... ] +Set or examine the prompt theme. With no options and a @var{theme} +argument, the theme with that name is set as the current theme. The +available themes are determined at run time; use the @t{-l} option to see +a list. The special @var{theme} `@t{random}' selects at random one of the +available themes and sets your prompt to that. + +@noindent +In some cases the @var{theme} may be modified by one or more arguments, +which should be given after the theme name. See the help for each theme +for descriptions of these arguments. + +@noindent +Options are: + +@noindent +@table @asis +@item @t{-c} +Show the currently selected theme and its parameters, if any. +@item @t{-l} +List all available prompt themes. +@item @t{-p} +Preview the theme named by @var{theme}, or all themes if no +@var{theme} is given. +@item @t{-h} +Show help for the theme named by @var{theme}, or for the +@t{prompt} function if no @var{theme} is given. +@item @t{-s} +Set @var{theme} as the current theme and save state. +@end table + +@item @t{prompt_}@var{theme}@t{_setup} +Each available @var{theme} has a setup function which is called by the +@t{prompt} function to install that theme. This function may define +other functions as necessary to maintain the prompt, including functions +used to preview the prompt or provide help for its use. You should not +normally call a theme's setup function directly. + +@end table + +@noindent + +@subsection Utility Themes +@noindent + +@noindent +@table @asis +@item @t{prompt off} +The theme `@t{off}' sets all the prompt variables to minimal values with +no special effects. + +@item @t{prompt default} +The theme `@t{default}' sets all prompt variables to the same state as +if an interactive zsh was started with no initialization files. + +@item @t{prompt restore} +The special theme `@t{restore}' erases all theme settings and sets prompt +variables to their state before the first time the `@t{prompt}' function +was run, provided each theme has properly defined its cleanup (see below). + +@noindent +Note that you can undo `@t{prompt off}' and `@t{prompt default}' with +`@t{prompt restore}', but a second restore does not undo the first. + +@end table + +@noindent + +@subsection Writing Themes +@noindent + +@noindent +The first step for adding your own theme is to choose a name for it, +and create a file `@t{prompt_@var{name}_setup}' in a directory in your +@t{fpath}, such as @t{~/myfns} in the example above. The file should +at minimum contain assignments for the prompt variables that your +theme wishes to modify. By convention, themes use @t{PS1}, @t{PS2}, +@t{RPS1}, etc., rather than the longer @t{PROMPT} and @t{RPROMPT}. + +@noindent +The file is autoloaded as a function in the current shell context, so +it may contain any necessary commands to customize your theme, including +defining additional functions. To make some complex tasks easier, your +setup function may also do any of the following: + +@noindent +@table @asis +@item Assign @t{prompt_opts} +The array @t{prompt_opts} may be assigned any of @t{"bang"}, @t{"cr"}, +@t{"percent"}, @t{"sp"}, and/or @t{"subst"} as values. The corresponding +setopts (@t{promptbang}, etc.) are turned on, all other prompt-related +options are turned off. The @t{prompt_opts} array preserves setopts even +beyond the scope of @t{localoptions}, should your function need that. + +@item Modify precmd and preexec +Use of @t{add-zsh-hook} is recommended. The @t{precmd} and @t{preexec} +hooks are automatically adjusted if the prompt theme changes or is +disabled. + +@item Declare cleanup +If your function makes any other changes that should be undone when the +theme is disabled, your setup function may call +@example +prompt_cleanup @var{command} +@end example +where @var{command} should be suitably quoted. If your theme is ever +disabled or replaced by another, @var{command} is executed with @t{eval}. +You may declare more than one such cleanup hook. + +@item Define preview +Define or autoload a function @t{prompt_@var{name}_preview} to display +a simulated version of your prompt. A simple default previewer is +defined by @t{promptinit} for themes that do not define their own. +This preview function is called by `@t{prompt -p}'. + +@item Provide help +Define or autoload a function @t{prompt_@var{name}_help} to display +documentation or help text for your theme. +This help function is called by `@t{prompt -h}'. + +@end table + +@noindent +@node ZLE Functions, Exception Handling, Prompt Themes, User Contributions + +@section ZLE Functions +@noindent + +@noindent + +@subsection Widgets +@noindent + +@noindent +These functions all implement user-defined ZLE widgets (see +@ref{Zsh Line Editor}) which can be bound to keystrokes in interactive shells. To use them, +your @t{.zshrc} should contain lines of the form + +@noindent +@example +autoload @var{function} +zle -N @var{function} +@end example + +@noindent +followed by an appropriate @t{bindkey} command to associate the function +with a key sequence. Suggested bindings are described below. + +@noindent +@table @asis +@item bash-style word functions +If you are looking for functions to implement moving over and editing +words in the manner of bash, where only alphanumeric characters are +considered word characters, you can use the functions described in +the next section. The following is sufficient: + +@noindent +@example +autoload -U select-word-style +select-word-style bash +@end example + +@noindent + +@tindex forward-word-match +@tindex backward-word-match +@tindex kill-word-match +@tindex backward-kill-word-match +@tindex transpose-words-match +@tindex capitalize-word-match +@tindex up-case-word-match +@tindex down-case-word-match +@tindex delete-whole-word-match +@tindex select-word-match +@tindex select-word-style +@tindex match-word-context +@tindex match-words-by-style +@item @t{forward-word-match}, @t{backward-word-match} +@itemx @t{kill-word-match}, @t{backward-kill-word-match} +@itemx @t{transpose-words-match}, @t{capitalize-word-match} +@itemx @t{up-case-word-match}, @t{down-case-word-match} +@itemx @t{delete-whole-word-match}, @t{select-word-match} +@itemx @t{select-word-style}, @t{match-word-context}, @t{match-words-by-style} +The first eight `@t{-match}' functions are drop-in replacements for the +builtin widgets without the suffix. By default they behave in a similar +way. However, by the use of styles and the function @t{select-word-style}, +the way words are matched can be altered. @t{select-word-match} is intended +to be used as a text object in vi mode but with custom word styles. For +comparison, the widgets described in @ref{Text Objects} use fixed definitions of words, compatible +with the @t{vim} editor. + +@noindent +The simplest way of configuring the functions is to use +@t{select-word-style}, which can either be called as a normal function with +the appropriate argument, or invoked as a user-defined widget that will +prompt for the first character of the word style to be used. The first +time it is invoked, the first eight @t{-match} functions will automatically +replace the builtin versions, so they do not need to be loaded explicitly. + +@noindent +The word styles available are as follows. Only the first character +is examined. + +@noindent +@table @asis +@item @t{bash} +Word characters are alphanumeric characters only. + +@item @t{normal} +As in normal shell operation: word characters are alphanumeric characters +plus any characters present in the string given by the parameter +@t{$WORDCHARS}. + +@item @t{shell} +Words are complete shell command arguments, possibly including complete +quoted strings, or any tokens special to the shell. + +@item @t{whitespace} +Words are any set of characters delimited by whitespace. + +@item @t{default} +Restore the default settings; this is usually the same as `@t{normal}'. + +@end table + +@noindent +All but `@t{default}' can be input as an upper case character, which has +the same effect but with subword matching turned on. In this case, words +with upper case characters are treated specially: each separate run of +upper case characters, or an upper case character followed by any number of +other characters, is considered a word. The style @t{subword-range} +can supply an alternative character range to the default `@t{[:upper:]}'; +the value of the style is treated as the contents of a `@t{[}@var{...}@t{]}' +pattern (note that the outer brackets should not be supplied, only +those surrounding named ranges). + +@noindent +More control can be obtained using the @t{zstyle} command, as described in +@ref{The zsh/zutil Module}. Each style is looked up in the +context @t{:zle:}@var{widget} where @var{widget} is the name of the +user-defined widget, not the name of the function implementing it, so in +the case of the definitions supplied by @t{select-word-style} the +appropriate contexts are @t{:zle:forward-word}, and so on. The function +@t{select-word-style} itself always defines styles for the context +`@t{:zle:*}' which can be overridden by more specific (longer) patterns as +well as explicit contexts. + +@noindent +The style @t{word-style} specifies the rules to use. This may have the +following values. + +@noindent +@table @asis +@item @t{normal} +Use the standard shell rules, i.e. alphanumerics and @t{$WORDCHARS}, unless +overridden by the styles @t{word-chars} or @t{word-class}. + +@item @t{specified} +Similar to @t{normal}, but @emph{only} the specified characters, and not also +alphanumerics, are considered word characters. + +@item @t{unspecified} +The negation of specified. The given characters are those which will +@emph{not} be considered part of a word. + +@item @t{shell} +Words are obtained by using the syntactic rules for generating shell +command arguments. In addition, special tokens which are never command +arguments such as `@t{()}' are also treated as words. + +@item @t{whitespace} +Words are whitespace-delimited strings of characters. + +@end table + +@noindent +The first three of those rules usually use @t{$WORDCHARS}, but the value +in the parameter can be overridden by the style @t{word-chars}, which works +in exactly the same way as @t{$WORDCHARS}. In addition, the style +@t{word-class} uses character class syntax to group characters and takes +precedence over @t{word-chars} if both are set. The @t{word-class} style +does not include the surrounding brackets of the character class; for +example, `@t{-:[:alnum:]}' is a valid @t{word-class} to include all +alphanumerics plus the characters `@t{-}' and `@t{:}'. Be careful +including `@t{]}', `@t{^}' and `@t{-}' as these are special inside +character classes. + +@noindent +@t{word-style} may also have `@t{-subword}' appended to its value to +turn on subword matching, as described above. + +@noindent +The style @t{skip-chars} is mostly useful for +@t{transpose-words} and similar functions. If set, it gives a count of +characters starting at the cursor position which will not be considered +part of the word and are treated as space, regardless of what they actually +are. For example, if + +@noindent +@example +zstyle ':zle:transpose-words' skip-chars 1 +@end example + +@noindent +has been set, and @t{transpose-words-match} is called with the cursor on +the @var{X} of @t{foo}@var{X}@t{bar}, where @var{X} can be any character, then +the resulting expression is @t{bar}@var{X}@t{foo}. + +@noindent +Finer grained control can be obtained by setting the style @t{word-context} +to an array of pairs of entries. Each pair of entries consists of a +@var{pattern} and a @var{subcontext}. The shell argument the cursor is on is +matched against each @var{pattern} in turn until one matches; if it does, +the context is extended by a colon and the corresponding @var{subcontext}. +Note that the test is made against the original word on the line, with no +stripping of quotes. Special handling is done between words: the current +context is examined and if it contains the string @t{between} the word +is set to a single space; else if it is contains the string @t{back}, +the word before the cursor is considered, else the word after cursor is +considered. Some examples are given below. + +@noindent +The style @t{skip-whitespace-first} is only used with the +@t{forward-word} widget. If it is set to true, then @t{forward-word} +skips any non-word-characters, followed by any non-word-characters: +this is similar to the behaviour of other word-orientated widgets, +and also that used by other editors, however it differs from the +standard zsh behaviour. When using @t{select-word-style} the widget +is set in the context @t{:zle:*} to @t{true} if the word style is +@t{bash} and @t{false} otherwise. It may be overridden by setting it in +the more specific context @t{:zle:forward-word*}. + +@noindent +It is possible to create widgets with specific behaviour by defining +a new widget implemented by the appropriate generic function, then +setting a style for the context of the specific widget. For example, +the following defines a widget @t{backward-kill-space-word} using +@t{backward-kill-word-match}, the generic widget implementing +@t{backward-kill-word} behaviour, and ensures that the new widget +always implements space-delimited behaviour. + +@noindent +@example +zle -N backward-kill-space-word backward-kill-word-match +zstyle :zle:backward-kill-space-word word-style space +@end example + +@noindent +The widget @t{backward-kill-space-word} can now be bound to a key. + +@noindent +Here are some further examples of use of the styles, actually taken from the +simplified interface in @t{select-word-style}: + +@noindent +@example +zstyle ':zle:*' word-style standard +zstyle ':zle:*' word-chars @value{dsq} +@end example + +@noindent +Implements bash-style word handling for all widgets, i.e. only +alphanumerics are word characters; equivalent to setting +the parameter @t{WORDCHARS} empty for the given context. + +@noindent +@example +style ':zle:*kill*' word-style space +@end example + +@noindent +Uses space-delimited words for widgets with the word `kill' in the name. +Neither of the styles @t{word-chars} nor @t{word-class} is used in this case. + +@noindent +Here are some examples of use of the @t{word-context} style to extend +the context. + +@noindent +@example +zstyle ':zle:*' word-context \ + "*/*" filename "[[:space:]]" whitespace +zstyle ':zle:transpose-words:whitespace' word-style shell +zstyle ':zle:transpose-words:filename' word-style normal +zstyle ':zle:transpose-words:filename' word-chars @value{dsq} +@end example + +@noindent +This provides two different ways of using @t{transpose-words} depending on +whether the cursor is on whitespace between words or on a filename, here +any word containing a @t{/}. On whitespace, complete arguments as defined +by standard shell rules will be transposed. In a filename, only +alphanumerics will be transposed. Elsewhere, words will be transposed +using the default style for @t{:zle:transpose-words}. + +@noindent +The word matching and all the handling of @t{zstyle} settings is actually +implemented by the function @t{match-words-by-style}. This can be used to +create new user-defined widgets. The calling function should set the local +parameter @t{curcontext} to @t{:zle:}@var{widget}, create the local +parameter @t{matched_words} and call @t{match-words-by-style} with no +arguments. On return, @t{matched_words} will be set to an array with the +elements: (1) the start of the line (2) the word before the cursor (3) any +non-word characters between that word and the cursor (4) any non-word +character at the cursor position plus any remaining non-word characters +before the next word, including all characters specified by the +@t{skip-chars} style, (5) the word at or following the cursor (6) any +non-word characters following that word (7) the remainder of the line. Any +of the elements may be an empty string; the calling function should test +for this to decide whether it can perform its function. + +@noindent +If the variable @t{matched_words} is defined by the caller to +@t{match-words-by-style} as an associative array (@t{local -A +matched_words}), then the seven values given above should be retrieved +from it as elements named @t{start}, @t{word-before-cursor}, +@t{ws-before-cursor}, @t{ws-after-cursor}, @t{word-after-cursor}, +@t{ws-after-word}, and @t{end}. In addition the element +@t{is-word-start} is 1 if the cursor is on the start of a word or +subword, or on white space before it (the cases can be distinguished by +testing the @t{ws-after-cursor} element) and 0 otherwise. This form is +recommended for future compatibility. + +@noindent +It is possible to pass options with arguments to @t{match-words-by-style} +to override the use of styles. The options are: +@table @asis +@item @t{-w} +@var{word-style} +@item @t{-s} +@var{skip-chars} +@item @t{-c} +@var{word-class} +@item @t{-C} +@var{word-chars} +@item @t{-r} +@var{subword-range} +@end table + +@noindent +For example, @t{match-words-by-style -w shell -c 0} may be used to +extract the command argument around the cursor. + +@noindent +The @t{word-context} style is implemented by the function +@t{match-word-context}. This should not usually need to be called +directly. + +@tindex bracketed-paste-magic +@item @t{bracketed-paste-magic} +The @t{bracketed-paste} widget (see @ref{Miscellaneous} in @ref{Zle Widgets}) +inserts pasted text literally into the editor buffer rather than interpret +it as keystrokes. This disables some common usages where the self-insert +widget is replaced in order to accomplish some extra processing. An +example is the contributed @t{url-quote-magic} widget described below. + +@noindent +The @t{bracketed-paste-magic} widget is meant to replace @t{bracketed-paste} +with a wrapper that re-enables these self-insert actions, and other +actions as selected by zstyles. Therefore this widget is installed with + +@example +autoload -Uz bracketed-paste-magic +zle -N bracketed-paste bracketed-paste-magic +@end example + +@noindent +Other than enabling some widget processing, @t{bracketed-paste-magic} +attempts to replicate @t{bracketed-paste} as faithfully as possible. + +@noindent +The following zstyles may be set to control processing of pasted text. +All are looked up in the context `@t{:bracketed-paste-magic}'. + +@noindent +@table @asis +@item @t{active-widgets} +A list of patterns matching widget names that should be activated during +the paste. All other key sequences are processed as self-insert-unmeta. +The default is `@t{self-*}' so any user-defined widgets named with that +prefix are active along with the builtin self-insert. + +@noindent +If this style is not set (explicitly deleted) or set to an empty value, +no widgets are active and the pasted text is inserted literally. If the +value includes `@t{undefined-key}', any unknown sequences are discarded +from the pasted text. + +@item @t{inactive-keys} +The inverse of @t{active-widgets}, a list of key sequences that always use +@t{self-insert-unmeta} even when bound to an active widget. Note that +this is a list of literal key sequences, not patterns. + +@item @t{paste-init} +A list of function names, called in widget context (but not as widgets). +The functions are called in order until one of them returns a non-zero +status. The parameter `@t{PASTED}' contains the initial state of the +pasted text. All other ZLE parameters such as `@t{BUFFER}' have their +normal values and side-effects, and full history is available, so for +example @t{paste-init} functions may move words from @t{BUFFER} into +@t{PASTED} to make those words visible to the @t{active-widgets}. + +@noindent +A non-zero return from a @t{paste-init} function does @emph{not} prevent the +paste itself from proceeding. + +@noindent +Loading @t{bracketed-paste-magic} defines @t{backward-extend-paste}, a +helper function for use in @t{paste-init}. + +@noindent +@example +zstyle :bracketed-paste-magic paste-init \ + backward-extend-paste +@end example + +@noindent +When a paste would insert into the middle of a word or append text to a +word already on the line, @t{backward-extend-paste} moves the prefix +from @t{LBUFFER} into @t{PASTED} so that the @t{active-widgets} see the +full word so far. This may be useful with @t{url-quote-magic}. + +@item @t{paste-finish} +Another list of function names called in order until one returns non-zero. +These functions are called @emph{after} the pasted text has been processed +by the @t{active-widgets}, but @emph{before} it is inserted into `@t{BUFFER}'. +ZLE parameters have their normal values and side-effects. + +@noindent +A non-zero return from a @t{paste-finish} function does @emph{not} prevent +the paste itself from proceeding. + +@noindent +Loading @t{bracketed-paste-magic} also defines @t{quote-paste}, a helper +function for use in @t{paste-finish}. + +@noindent +@example +zstyle :bracketed-paste-magic paste-finish \ + quote-paste +zstyle :bracketed-paste-magic:finish quote-style \ + qqq +@end example + +@noindent +When the pasted text is inserted into @t{BUFFER}, it is quoted per the +@t{quote-style} value. To forcibly turn off the built-in numeric prefix +quoting of @t{bracketed-paste}, use: + +@noindent +@example +zstyle :bracketed-paste-magic:finish quote-style \ + none +@end example + +@end table + +@noindent +@emph{Important:} During @t{active-widgets} processing of the paste (after +@t{paste-init} and before @t{paste-finish}), @t{BUFFER} starts empty and +history is restricted, so cursor motions, etc., may not pass outside of +the pasted content. Text assigned to @t{BUFFER} by the active widgets +is copied back into @t{PASTED} before @t{paste-finish}. + +@tindex copy-earlier-word +@item @t{copy-earlier-word} +This widget works like a combination of @t{insert-last-word} and +@t{copy-prev-shell-word}. Repeated invocations of the widget retrieve +earlier words on the relevant history line. With a numeric argument +@var{N}, insert the @var{N}th word from the history line; @var{N} may be +negative to count from the end of the line. + +@noindent +If @t{insert-last-word} has been used to retrieve the last word on a +previous history line, repeated invocations will replace that word with +earlier words from the same line. + +@noindent +Otherwise, the widget applies to words on the line currently being edited. +The @t{widget} style can be set to the name of another widget that should +be called to retrieve words. This widget must accept the same three +arguments as @t{insert-last-word}. + +@tindex cycle-completion-positions +@item @t{cycle-completion-positions} +After inserting an unambiguous string into the command line, the new +function based completion system may know about multiple places in +this string where characters are missing or differ from at least one +of the possible matches. It will then place the cursor on the +position it considers to be the most interesting one, i.e. the one +where one can disambiguate between as many matches as possible with as +little typing as possible. + +@noindent +This widget allows the cursor to be easily moved to the other interesting +spots. It can be invoked repeatedly to cycle between all positions +reported by the completion system. + +@tindex delete-whole-word-match +@item @t{delete-whole-word-match} +This is another function which works like the @t{-match} functions +described immediately above, i.e. using styles to decide the word +boundaries. However, it is not a replacement for any existing function. + +@noindent +The basic behaviour is to delete the word around the cursor. There is no +numeric argument handling; only the single word around the cursor is +considered. If the widget contains the string @t{kill}, the removed text +will be placed in the cutbuffer for future yanking. This can be obtained +by defining @t{kill-whole-word-match} as follows: + +@noindent +@example +zle -N kill-whole-word-match delete-whole-word-match +@end example + +@noindent +and then binding the widget @t{kill-whole-word-match}. + +@tindex down-line-or-beginning-search +@tindex up-line-or-beginning-search +@item @t{up-line-or-beginning-search}, @t{down-line-or-beginning-search} +These widgets are similar to the builtin functions @t{up-line-or-search} +and @t{down-line-or-search}: if in a multiline buffer they move up or +down within the buffer, otherwise they search for a history line matching +the start of the current line. In this case, however, they search for +a line which matches the current line up to the current cursor position, in +the manner of @t{history-beginning-search-backward} and @t{-forward}, rather +than the first word on the line. + +@tindex edit-command-line +@item @t{edit-command-line} +Edit the command line using your visual editor, as in @t{ksh}. + +@noindent +@example +bindkey -M vicmd v edit-command-line +@end example + +@tindex expand-absolute-path +@item @t{expand-absolute-path} +Expand the file name under the cursor to an absolute path, resolving +symbolic links. Where possible, the initial path segment is turned +into a named directory or reference to a user's home directory. + +@tindex history-beginning-search-backward-end +@tindex history-beginning-search-forward-end +@item @t{history-search-end} +This function implements the widgets +@t{history-beginning-search-backward-end} and +@t{history-beginning-search-forward-end}. These commands work by first +calling the corresponding builtin widget (see +@ref{History Control}) and then moving the cursor to the end of the line. The original cursor +position is remembered and restored before calling the builtin widget a +second time, so that the same search is repeated to look farther through +the history. + +@noindent +Although you @t{autoload} only one function, the commands to use it are +slightly different because it implements two widgets. + +@noindent +@example +zle -N history-beginning-search-backward-end \ + history-search-end +zle -N history-beginning-search-forward-end \ + history-search-end +bindkey '\e^P' history-beginning-search-backward-end +bindkey '\e^N' history-beginning-search-forward-end +@end example + +@tindex history-beginning-search-menu +@item @t{history-beginning-search-menu} +This function implements yet another form of history searching. The +text before the cursor is used to select lines from the history, +as for @t{history-beginning-search-backward} except that all matches are +shown in a numbered menu. Typing the appropriate digits inserts the +full history line. Note that leading zeroes must be typed (they are only +shown when necessary for removing ambiguity). The entire history is +searched; there is no distinction between forwards and backwards. + +@noindent +With a numeric argument, the search is not anchored to the start of +the line; the string typed by the use may appear anywhere in the line +in the history. + +@noindent +If the widget name contains `@t{-end}' the cursor is moved to the end of +the line inserted. If the widget name contains `@t{-space}' any space +in the text typed is treated as a wildcard and can match anything (hence +a leading space is equivalent to giving a numeric argument). Both +forms can be combined, for example: + +@noindent +@example +zle -N history-beginning-search-menu-space-end \ + history-beginning-search-menu +@end example + +@tindex history-pattern-search +@tindex history-pattern-search-backward +@tindex history-pattern-search-forward +@item @t{history-pattern-search} +The function @t{history-pattern-search} implements widgets which prompt +for a pattern with which to search the history backwards or forwards. The +pattern is in the usual zsh format, however the first character may be +@t{^} to anchor the search to the start of the line, and the last character +may be @t{$} to anchor the search to the end of the line. If the +search was not anchored to the end of the line the cursor is positioned +just after the pattern found. + +@noindent +The commands to create bindable widgets are similar to those in the +example immediately above: + +@noindent +@example +autoload -U history-pattern-search +zle -N history-pattern-search-backward history-pattern-search +zle -N history-pattern-search-forward history-pattern-search +@end example + +@tindex incarg +@vindex incarg, use of +@item @t{incarg} +Typing the keystrokes for this widget with the cursor placed on or to the +left of an integer causes that integer to be incremented by one. With a +numeric argument, the number is incremented by the amount of the +argument (decremented if the numeric argument is negative). The shell +parameter @t{incarg} may be set to change the default increment to +something other than one. + +@noindent +@example +bindkey '^X+' incarg +@end example + +@tindex incremental-complete-word +@item @t{incremental-complete-word} +This allows incremental completion of a word. After starting this +command, a list of completion choices can be shown after every character +you type, which you can delete with @t{^H} or @t{DEL}. Pressing return +accepts the completion so far and returns you to normal editing (that is, +the command line is @emph{not} immediately executed). You can hit @t{TAB} to +do normal completion, @t{^G} to abort back to the state when you started, +and @t{^D} to list the matches. + +@noindent +This works only with the new function based completion system. + +@noindent +@example +bindkey '^Xi' incremental-complete-word +@end example + +@tindex insert-composed-char +@item @t{insert-composed-char} +This function allows you to compose characters that don't appear on the +keyboard to be inserted into the command line. The command is followed by +two keys corresponding to ASCII characters (there is no prompt). For +accented characters, the two keys are a base character followed by a code +for the accent, while for other special characters the two characters +together form a mnemonic for the character to be inserted. The +two-character codes are a subset of those given by RFC 1345 (see for +example @t{@uref{http://www.faqs.org/rfcs/rfc1345.html}}). + +@noindent +The function may optionally be followed by up to two characters which +replace one or both of the characters read from the keyboard; if both +characters are supplied, no input is read. For example, +@t{insert-composed-char a:} can be used within a widget to insert an a with +umlaut into the command line. This has the advantages over use of a +literal character that it is more portable. + +@noindent +For best results zsh should have been built with support for multibyte +characters (configured with @t{--enable-multibyte}); however, the function +works for the limited range of characters available in single-byte +character sets such as ISO-8859-1. + +@noindent +The character is converted into the local representation and +inserted into the command line at the cursor position. +(The conversion is done within the shell, using whatever facilities +the C library provides.) With a numeric argument, the character and its +code are previewed in the status line + +@noindent +The function may be run outside zle in which case it prints the character +(together with a newline) to standard output. Input is still read from +keystrokes. + +@noindent +See @t{insert-unicode-char} for an alternative way of inserting Unicode +characters using their hexadecimal character number. + +@noindent +The set of accented characters is reasonably complete up to Unicode +character U+0180, the set of special characters less so. However, it +is very sporadic from that point. Adding new characters is easy, +however; see the function @t{define-composed-chars}. Please send any +additions to @t{zsh-workers@@zsh.org}. + +@noindent +The codes for the second character when used to accent the first are as +follows. Note that not every character can take every accent. +@table @asis +@item @t{!} +Grave. +@item @t{'} +Acute. +@item @t{>} +Circumflex. +@item @t{?} +Tilde. (This is not @t{~} as RFC 1345 does not assume that +character is present on the keyboard.) +@item @t{-} +Macron. (A horizontal bar over the base character.) +@item @t{(} +Breve. (A shallow dish shape over the base character.) +@item @t{.} +Dot above the base character, or in the case of @t{i} no dot, +or in the case of @t{L} and @t{l} a centered dot. +@item @t{:} +Diaeresis (Umlaut). +@item @t{c} +Cedilla. +@item @t{_} +Underline, however there are currently no underlined characters. +@item @t{/} +Stroke through the base character. +@item @t{"} +Double acute (only supported on a few letters). +@item @t{;} +Ogonek. (A little forward facing hook at the bottom right +of the character.) +@item @t{<} +Caron. (A little v over the letter.) +@item @t{0} +Circle over the base character. +@item @t{2} +Hook over the base character. +@item @t{9} +Horn over the base character. +@end table + +@noindent +The most common characters from the Arabic, Cyrillic, Greek and Hebrew +alphabets are available; consult RFC 1345 for the appropriate sequences. +In addition, a set of two letter codes not in RFC 1345 are available for +the double-width characters corresponding to ASCII characters from @t{!} +to @t{~} (0x21 to 0x7e) by preceding the character with @t{^}, for +example @t{^A} for a double-width @t{A}. + +@noindent +The following other two-character sequences are understood. + +@noindent +@table @asis +@item ASCII characters +These are already present on most keyboards: +@table @asis +@item @t{<(} +Left square bracket +@item @t{//} +Backslash (solidus) +@item @t{)>} +Right square bracket +@item @t{(!} +Left brace (curly bracket) +@item @t{!!} +Vertical bar (pipe symbol) +@item @t{!)} +Right brace (curly bracket) +@item @t{'?} +Tilde +@end table + +@item Special letters +Characters found in various variants of the Latin alphabet: +@table @asis +@item @t{ss} +Eszett (scharfes S) +@item @t{D-}, @t{d-} +Eth +@item @t{TH}, @t{th} +Thorn +@item @t{kk} +Kra +@item @t{'n} +'n +@item @t{NG}, @t{ng} +Ng +@item @t{OI}, @t{oi} +Oi +@item @t{yr} +yr +@item @t{ED} +ezh +@end table + +@item Currency symbols +@table @asis +@item @t{Ct} +Cent +@item @t{Pd} +Pound sterling (also lira and others) +@item @t{Cu} +Currency +@item @t{Ye} +Yen +@item @t{Eu} +Euro (N.B. not in RFC 1345) +@end table + +@item Punctuation characters +References to "right" quotes indicate the shape (like a 9 rather than 6) +rather than their grammatical use. (For example, a "right" low double +quote is used to open quotations in German.) +@table @asis +@item @t{!I} +Inverted exclamation mark +@item @t{BB} +Broken vertical bar +@item @t{SE} +Section +@item @t{Co} +Copyright +@item @t{-a} +Spanish feminine ordinal indicator +@item @t{<<} +Left guillemet +@item @t{-}@t{-} +Soft hyphen +@item @t{Rg} +Registered trade mark +@item @t{PI} +Pilcrow (paragraph) +@item @t{-o} +Spanish masculine ordinal indicator +@item @t{>>} +Right guillemet +@item @t{?I} +Inverted question mark +@item @t{-1} +Hyphen +@item @t{-N} +En dash +@item @t{-M} +Em dash +@item @t{-3} +Horizontal bar +@item @t{:3} +Vertical ellipsis +@item @t{.3} +Horizontal midline ellipsis +@item @t{!2} +Double vertical line +@item @t{=2} +Double low line +@item @t{'6} +Left single quote +@item @t{'9} +Right single quote +@item @t{.9} +"Right" low quote +@item @t{9'} +Reversed "right" quote +@item @t{"6} +Left double quote +@item @t{"9} +Right double quote +@item @t{:9} +"Right" low double quote +@item @t{9"} +Reversed "right" double quote +@item @t{/-} +Dagger +@item @t{/=} +Double dagger +@end table + +@item Mathematical symbols +@table @asis +@item @t{DG} +Degree +@item @t{-2}, @t{+-}, @t{-+} +- sign, +/- sign, -/+ sign +@item @t{2S} +Superscript 2 +@item @t{3S} +Superscript 3 +@item @t{1S} +Superscript 1 +@item @t{My} +Micro +@item @t{.M} +Middle dot +@item @t{14} +Quarter +@item @t{12} +Half +@item @t{34} +Three quarters +@item @t{*X} +Multiplication +@item @t{-:} +Division +@item @t{%0} +Per mille +@item @t{FA}, @t{TE}, @t{/0} +For all, there exists, empty set +@item @t{dP}, @t{DE}, @t{NB} +Partial derivative, delta (increment), del +(nabla) +@item @t{(-}, @t{-)} +Element of, contains +@item @t{*P}, @t{+Z} +Product, sum +@item @t{*-}, @t{Ob}, @t{Sb} +Asterisk, ring, bullet +@item @t{RT}, @t{0(}, @t{00} +Root sign, proportional to, infinity +@end table + +@item Other symbols +@table @asis +@item @t{cS}, @t{cH}, @t{cD}, @t{cC} +Card suits: spades, hearts, diamonds, +clubs +@item @t{Md}, @t{M8}, @t{M2}, @t{Mb}, @t{Mx}, @t{MX} +Musical notation: +crotchet (quarter note), quaver (eighth note), semiquavers (sixteenth +notes), flag sign, natural sign, sharp sign +@item @t{Fm}, @t{Ml} +Female, male +@end table + +@item Accents on their own +@table @asis +@item @t{'>} +Circumflex (same as caret, @t{^}) +@item @t{'!} +Grave (same as backtick, @t{`}) +@item @t{',} +Cedilla +@item @t{':} +Diaeresis (Umlaut) +@item @t{'m} +Macron +@item @t{''} +Acute +@end table + +@end table + +@tindex insert-files +@item @t{insert-files} +This function allows you type a file pattern, and see the results of the +expansion at each step. When you hit return, all expansions are inserted +into the command line. + +@noindent +@example +bindkey '^Xf' insert-files +@end example + +@tindex insert-unicode-char +@item @t{insert-unicode-char} +When first executed, the user inputs a set of hexadecimal digits. +This is terminated with another call to @t{insert-unicode-char}. +The digits are then turned into the corresponding Unicode character. +For example, if the widget is bound to @t{^XU}, the character sequence +`@t{^XU 4 c ^XU}' inserts @t{L} (Unicode U+004c). + +@noindent +See @t{insert-composed-char} for a way of inserting characters +using a two-character mnemonic. + +@tindex narrow-to-region +@tindex narrow-to-region-invisible + +@item @t{narrow-to-region }[ @t{-p} @var{pre} ] [ @t{-P} @var{post} ] +@itemx @t{@ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ }[ @t{-S} @var{statepm} | @t{-R} @var{statepm} | [ @t{-l} @var{lbufvar} ] [ @t{-r} @var{rbufvar} ] ] +@itemx @t{@ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ }[ @t{-n} ] [ @var{start} @var{end} ] +@itemx @t{narrow-to-region-invisible} +Narrow the editable portion of the buffer to the region between the cursor +and the mark, which may be in either order. The region may not be empty. + +@noindent +@t{narrow-to-region} may be used as a widget or called as a function from a +user-defined widget; by default, the text outside the editable area remains +visible. A @t{recursive-edit} is performed and the original widening +status is then restored. Various options and arguments are available when +it is called as a function. + +@noindent +The options @t{-p} @var{pretext} and @t{-P} @var{posttext} may be +used to replace the text before and after the display for the duration of +the function; either or both may be an empty string. + +@noindent +If the option @t{-n} is also given, @var{pretext} or @var{posttext} will only +be inserted if there is text before or after the region respectively which +will be made invisible. + +@noindent +Two numeric arguments may be given which will be used instead of the cursor +and mark positions. + +@noindent +The option @t{-S} @var{statepm} is used to narrow according to the other +options while saving the original state in the parameter with name +@var{statepm}, while the option @t{-R} @var{statepm} is used to restore the +state from the parameter; note in both cases the @emph{name} of the parameter +is required. In the second case, other options and arguments are +irrelevant. When this method is used, no @t{recursive-edit} is performed; +the calling widget should call this function with the option @t{-S}, +perform its own editing on the command line or pass control to the user +via `@t{zle recursive-edit}', then call this function with the option +@t{-R}. The argument @var{statepm} must be a suitable name for an ordinary +parameter, except that parameters beginning with the prefix @t{_ntr_} are +reserved for use within @t{narrow-to-region}. Typically the parameter will +be local to the calling function. + +@noindent +The options @t{-l} @var{lbufvar} and @t{-r} @var{rbufvar} may be used to +specify parameters where the widget will store the resulting text from +the operation. The parameter @var{lbufvar} will contain @t{LBUFFER} +and @var{rbufvar} will contain @t{RBUFFER}. Neither of these two options +may be used with @t{-S} or @t{-R}. + +@noindent +@t{narrow-to-region-invisible} is a simple widget which calls +@t{narrow-to-region} with arguments which replace any text outside the +region with `@t{...}'. It does not take any arguments. + +@noindent +The display is restored (and the widget returns) upon any zle command +which would usually cause the line to be accepted or aborted. Hence an +additional such command is required to accept or abort the current line. + +@noindent +The return status of both widgets is zero if the line was accepted, else +non-zero. + +@noindent +Here is a trivial example of a widget using this feature. +@example +local state +narrow-to-region -p $'Editing restricted region\n' \ + -P @value{dsq} -S state +zle recursive-edit +narrow-to-region -R state +@end example + +@tindex predict-on +@tindex predict-off +@item @t{predict-on} +This set of functions implements predictive typing using history search. +After @t{predict-on}, typing characters causes the editor to look backward +in the history for the first line beginning with what you have typed so +far. After @t{predict-off}, editing returns to normal for the line found. +In fact, you often don't even need to use @t{predict-off}, because if the +line doesn't match something in the history, adding a key performs +standard completion, and then inserts itself if no completions were found. +However, editing in the middle of a line is liable to confuse prediction; +see the @t{toggle} style below. + +@noindent +With the function based completion system (which is needed for this), you +should be able to type @t{TAB} at almost any point to advance the cursor +to the next @value{dsbq}interesting@value{dsq} character position (usually the end of the +current word, but sometimes somewhere in the middle of the word). And of +course as soon as the entire line is what you want, you can accept with +return, without needing to move the cursor to the end first. + +@noindent +The first time @t{predict-on} is used, it creates several additional +widget functions: + +@noindent +@table @asis +@item @t{delete-backward-and-predict} +Replaces the @t{backward-delete-char} +widget. You do not need to bind this yourself. +@item @t{insert-and-predict} +Implements predictive typing by replacing the +@t{self-insert} widget. You do not need to bind this yourself. +@item @t{predict-off} +Turns off predictive typing. +@end table + +@noindent +Although you @t{autoload} only the @t{predict-on} function, it is +necessary to create a keybinding for @t{predict-off} as well. + +@noindent +@example +zle -N predict-on +zle -N predict-off +bindkey '^X^Z' predict-on +bindkey '^Z' predict-off +@end example + +@tindex read-from-minibuffer +@item @t{read-from-minibuffer} +This is most useful when called as a function from inside a widget, but will +work correctly as a widget in its own right. It prompts for a value +below the current command line; a value may be input using all of the +standard zle operations (and not merely the restricted set available +when executing, for example, @t{execute-named-cmd}). The value is then +returned to the calling function in the parameter @t{$REPLY} and the +editing buffer restored to its previous state. If the read was aborted +by a keyboard break (typically @t{^G}), the function returns status 1 +and @t{$REPLY} is not set. + +@noindent +If one argument is supplied to the function it is taken as a prompt, +otherwise `@t{? }' is used. If two arguments are supplied, they are the +prompt and the initial value of @t{$LBUFFER}, and if a third argument is +given it is the initial value of @t{$RBUFFER}. This provides a default +value and starting cursor placement. Upon return the entire buffer is the +value of @t{$REPLY}. + +@noindent +One option is available: `@t{-k} @var{num}' specifies that @var{num} +characters are to be read instead of a whole line. The line editor is not +invoked recursively in this case, so depending on the terminal settings +the input may not be visible, and only the input keys are placed in +@t{$REPLY}, not the entire buffer. Note that unlike the @t{read} builtin +@var{num} must be given; there is no default. + +@noindent +The name is a slight misnomer, as in fact the shell's own minibuffer is +not used. Hence it is still possible to call @t{executed-named-cmd} and +similar functions while reading a value. + +@tindex replace-argument +@tindex replace-argument-edit +@item @t{replace-argument}, @t{replace-argument-edit} +The function @t{replace-argument} can be used to replace a command +line argument in the current command line or, if the current command +line is empty, in the last command line executed (the new command line +is not executed). Arguments are as delimited by standard shell syntax, + +@noindent +If a numeric argument is given, that specifies the argument to be +replaced. 0 means the command name, as in history expansion. +A negative numeric argument counts backward from the last word. + +@noindent +If no numeric argument is given, the current argument is replaced; +this is the last argument if the previous history line is being used. + +@noindent +The function prompts for a replacement argument. + +@noindent +If the widget contains the string @t{edit}, for example is defined as + +@noindent +@example +zle -N replace-argument-edit replace-argument +@end example + +@noindent +then the function presents the current value of the argument for +editing, otherwise the editing buffer for the replacement is +initially empty. + +@tindex replace-string +@tindex replace-string-again +@tindex replace-pattern +@item @t{replace-string}, @t{replace-pattern} +@itemx @t{replace-string-again}, @t{replace-pattern-again} +The function @t{replace-string} implements three widgets. +If defined under the same name as the function, it prompts for two +strings; the first (source) string will be replaced by the second +everywhere it occurs in the line editing buffer. + +@noindent +If the widget name contains the word `@t{pattern}', for example by +defining the widget using the command `@t{zle -N replace-pattern +replace-string}', then the matching is performed using zsh patterns. All +zsh extended globbing patterns can be used in the source string; note +that unlike filename generation the pattern does not need to match an +entire word, nor do glob qualifiers have any effect. In addition, the +replacement string can contain parameter or command substitutions. +Furthermore, a `@t{&}' in the replacement string will be replaced with +the matched source string, and a backquoted digit `@t{\}@var{N}' will be +replaced by the @var{N}th parenthesised expression matched. The form +`@t{\@{}@var{N}@t{@}}' may be used to protect the digit from following +digits. + +@noindent +If the widget instead contains the word `@t{regex}' (or `@t{regexp}'), +then the matching is performed using regular expressions, respecting +the setting of the option @t{RE_MATCH_PCRE} (see the description of the +function @t{regexp-replace} below). The special replacement facilities +described above for pattern matching are available. + +@noindent +By default the previous source or replacement string will not be offered +for editing. However, this feature can be activated by setting the style +@t{edit-previous} in the context @t{:zle:}@var{widget} (for example, +@t{:zle:replace-string}) to @t{true}. In addition, a positive +numeric argument forces the previous values to be offered, a negative or +zero argument forces them not to be. + +@noindent +The function @t{replace-string-again} can be used to repeat the previous +replacement; no prompting is done. As with @t{replace-string}, if the name +of the widget contains the word `@t{pattern}' or `@t{regex}', pattern or +regular expression matching is performed, else a literal string +replacement. Note that the previous source and replacement text are the +same whether pattern, regular expression or string matching is used. + +@noindent +In addition, @t{replace-string} shows the previous replacement above +the prompt, so long as there was one during the current session; if the +source string is empty, that replacement will be repeated without +the widget prompting for a replacement string. + +@noindent +For example, starting from the line: + +@noindent +@example +print This line contains fan and fond +@end example + +@noindent +and invoking @t{replace-pattern} with the source string +`@t{f(?)n}' and +the replacement string `@t{c\1r}' produces the not very useful line: + +@noindent +@example +print This line contains car and cord +@end example + +@noindent +The range of the replacement string can be limited by using the +@t{narrow-to-region-invisible} widget. One limitation of the current +version is that @t{undo} will cycle through changes to the replacement +and source strings before undoing the replacement itself. + +@tindex send-invisible +@item @t{send-invisible} +This is similar to read-from-minibuffer in that it may be called as a +function from a widget or as a widget of its own, and interactively reads +input from the keyboard. However, the input being typed is concealed and +a string of asterisks (`@t{*}') is shown instead. The value is saved in +the parameter @t{$INVISIBLE} to which a reference is inserted into the +editing buffer at the restored cursor position. If the read was aborted +by a keyboard break (typically @t{^G}) or another escape from editing such +as @t{push-line}, @t{$INVISIBLE} is set to empty and the original buffer +is restored unchanged. + +@noindent +If one argument is supplied to the function it is taken as a prompt, +otherwise `@t{Non-echoed text: }' is used (as in emacs). If a second and +third argument are supplied they are used to begin and end the reference +to @t{$INVISIBLE} that is inserted into the buffer. The default is to +open with @t{$@{}, then @t{INVISIBLE}, and close with @t{@}}, but many +other effects are possible. + +@tindex smart-insert-last-word +@item @t{smart-insert-last-word} +This function may replace the @t{insert-last-word} widget, like so: + +@noindent +@example +zle -N insert-last-word smart-insert-last-word +@end example + +@noindent +With a numeric argument, or when passed command line arguments in a call +from another widget, it behaves like @t{insert-last-word}, except that +words in comments are ignored when @t{INTERACTIVE_COMMENTS} is set. + +@noindent +Otherwise, the rightmost @value{dsbq}interesting@value{dsq} word from the previous command is +found and inserted. The default definition of @value{dsbq}interesting@value{dsq} is that the +word contains at least one alphabetic character, slash, or backslash. +This definition may be overridden by use of the @t{match} style. The +context used to look up the style is the widget name, so usually the +context is @t{:insert-last-word}. However, you can bind this function to +different widgets to use different patterns: + +@noindent +@example +zle -N insert-last-assignment smart-insert-last-word +zstyle :insert-last-assignment match '[[:alpha:]][][[:alnum:]]#=*' +bindkey '\e=' insert-last-assignment +@end example + +@noindent +If no interesting word is found and the @t{auto-previous} style is set to +a true value, the search continues upward through the history. When +@t{auto-previous} is unset or false (the default), the widget must be +invoked repeatedly in order to search earlier history lines. + +@tindex transpose-lines +@item @t{transpose-lines} +Only useful with a multi-line editing buffer; the lines here are +lines within the current on-screen buffer, not history lines. +The effect is similar to the function of the same name in Emacs. + +@noindent +Transpose the current line with the previous line and move the cursor +to the start of the next line. Repeating this (which can be done by +providing a positive numeric argument) has the effect of moving +the line above the cursor down by a number of lines. + +@noindent +With a negative numeric argument, requires two lines above the +cursor. These two lines are transposed and the cursor moved to the +start of the previous line. Using a numeric argument less than -1 +has the effect of moving the line above the cursor up by minus that +number of lines. + +@tindex url-quote-magic +@item @t{url-quote-magic} +This widget replaces the built-in @t{self-insert} to make it easier to +type URLs as command line arguments. As you type, the input character is +analyzed and, if it may need quoting, the current word is checked for a +URI scheme. If one is found and the current word is not already in +quotes, a backslash is inserted before the input character. + +@noindent +Styles to control quoting behavior: + +@noindent +@table @asis +@item @t{url-metas} +This style is looked up in the context `@t{:url-quote-magic:}@var{scheme}' +(where @var{scheme} is that of the current URL, e.g. "@t{ftp}"). The value +is a string listing the characters to be treated as globbing +metacharacters when appearing in a URL using that scheme. The default is +to quote all zsh extended globbing characters, excluding '@t{<}' and +'@t{>}' but including braces (as in brace expansion). See also +@t{url-seps}. + +@item @t{url-seps} +Like @t{url-metas}, but lists characters that should be considered command +separators, redirections, history references, etc. The default is to +quote the standard set of shell separators, excluding those that overlap +with the extended globbing characters, but including '@t{<}' and +'@t{>}' and the first character of @t{$histchars}. + +@item @t{url-globbers} +This style is looked up in the context `@t{:url-quote-magic}'. The values +form a list of command names that are expected to do their own globbing +on the URL string. This implies that they are aliased to use the +`@t{noglob}' modifier. When the first word on the line matches one of the +values @emph{and} the URL refers to a local file (see @t{url-local-schema}), +only the @t{url-seps} characters are quoted; the @t{url-metas} are left +alone, allowing them to affect command-line parsing, completion, etc. The +default values are a literal `@t{noglob}' plus (when the @t{zsh/parameter} +module is available) any commands aliased to the helper function +`@t{urlglobber}' or its alias `@t{globurl}'. + +@item @t{url-local-schema} +This style is always looked up in the context `@t{:urlglobber}', even +though it is used by both url-quote-magic and urlglobber. The values form +a list of URI schema that should be treated as referring to local files by +their real local path names, as opposed to files which are specified +relative to a web-server-defined document root. The defaults are +"@t{ftp}" and "@t{file}". + +@item @t{url-other-schema} +Like @t{url-local-schema}, but lists all other URI schema upon which +@t{urlglobber} and @t{url-quote-magic} should act. If the URI on the +command line does not have a scheme appearing either in this list or in +@t{url-local-schema}, it is not magically quoted. The default values are +"@t{http}", "@t{https}", and "@t{ftp}". When a scheme appears both here +and in @t{url-local-schema}, it is quoted differently depending on whether +the command name appears in @t{url-globbers}. + +@end table + +@noindent +Loading @t{url-quote-magic} also defines a helper function `@t{urlglobber}' +and aliases `@t{globurl}' to `@t{noglob urlglobber}'. This function takes +a local URL apart, attempts to pattern-match the local file portion of the +URL path, and then puts the results back into URL format again. + +@tindex vi-pipe +@item @t{vi-pipe} +This function reads a movement command from the keyboard and then +prompts for an external command. The part of the buffer covered by +the movement is piped to the external command and then replaced by +the command's output. If the movement command is bound to vi-pipe, +the current line is used. + +@noindent +The function serves as an example for reading a vi movement command +from within a user-defined widget. + +@tindex which-command +@item @t{which-command} +This function is a drop-in replacement for the builtin widget +@t{which-command}. It has enhanced behaviour, in that it correctly +detects whether or not the command word needs to be expanded as an +alias; if so, it continues tracing the command word from the expanded +alias until it reaches the command that will be executed. + +@noindent +The style @t{whence} is available in the context @t{:zle:$WIDGET}; this +may be set to an array to give the command and options that will be used to +investigate the command word found. The default is @t{whence -c}. + +@tindex zcalc-auto-insert +@item @t{zcalc-auto-insert} +This function is useful together with the @t{zcalc} function described in +@ref{Mathematical Functions}. +It should be bound to a key representing a binary operator such +as `@t{+}', `@t{-}', `@t{*}' or `@t{/}'. When running in zcalc, +if the key occurs at the start of the line or immediately following +an open parenthesis, the text @t{"ans "} is inserted before the +representation of the key itself. This allows easy use of the +answer from the previous calculation in the current line. The +text to be inserted before the symbol typed can be modified by setting +the variable @t{ZCALC_AUTO_INSERT_PREFIX}. + +@noindent +Hence, for example, typing `@t{+12}' followed by return adds 12 +to the previous result. + +@noindent +If zcalc is in RPN mode (@t{-r} option) the effect of this binding is +automatically suppressed as operators alone on a line are meaningful. + +@noindent +When not in zcalc, the key simply inserts the symbol itself. + +@end table + +@noindent + +@subsection Utility Functions +@noindent + +@noindent +These functions are useful in constructing widgets. They +should be loaded with `@t{autoload -U} @var{function}' and called +as indicated from user-defined widgets. + +@noindent +@table @asis +@tindex split-shell-arguments +@item @t{split-shell-arguments} +This function splits the line currently being edited into shell arguments +and whitespace. The result is stored in the array @t{reply}. The array +contains all the parts of the line in order, starting with any whitespace +before the first argument, and finishing with any whitespace after the last +argument. Hence (so long as the option @t{KSH_ARRAYS} is not set) +whitespace is given by odd indices in the array and arguments by +even indices. Note that no stripping of quotes is done; joining together +all the elements of @t{reply} in order is guaranteed to produce the +original line. + +@noindent +The parameter @t{REPLY} is set to the index of the word in @t{reply} which +contains the character after the cursor, where the first element has index +1. The parameter @t{REPLY2} is set to the index of the character under the +cursor in that word, where the first character has index 1. + +@noindent +Hence @t{reply}, @t{REPLY} and @t{REPLY2} should all be made local to +the enclosing function. + +@noindent +See the function @t{modify-current-argument}, described below, for +an example of how to call this function. + +@tindex modify-current-argument +@item @t{modify-current-argument} [ @var{expr-using-}@t{$ARG} | @var{func} ] +This function provides a simple method of allowing user-defined widgets +to modify the command line argument under the cursor (or immediately to the +left of the cursor if the cursor is between arguments). + +@noindent +The argument can be an expression which when evaluated operates on the shell +parameter @t{ARG}, which will have been set to the command line argument +under the cursor. The expression should be suitably quoted to prevent +it being evaluated too early. + +@noindent +Alternatively, if the argument does not contain the string @t{ARG}, it +is assumed to be a shell function, to which the current command line +argument is passed as the only argument. The function should set the +variable @t{REPLY} to the new value for the command line argument. +If the function returns non-zero status, so does the calling function. + +@noindent +For example, a user-defined widget containing the following code +converts the characters in the argument under the cursor into all upper +case: + +@noindent +@example +modify-current-argument '$@{(U)ARG@}' +@end example + +@noindent +The following strips any quoting from the current word (whether backslashes +or one of the styles of quotes), and replaces it with single quoting +throughout: + +@noindent +@example +modify-current-argument '$@{(qq)$@{(Q)ARG@}@}' +@end example + +@noindent +The following performs directory expansion on the command line +argument and replaces it by the absolute path: + +@noindent +@example +expand-dir() @{ + REPLY=$@{~1@} + REPLY=$@{REPLY:a@} +@} +modify-current-argument expand-dir +@end example + +@noindent +In practice the function @t{expand-dir} would probably not be defined +within the widget where @t{modify-current-argument} is called. + +@end table + +@noindent + +@subsection Styles +@noindent + +@noindent +The behavior of several of the above widgets can be controlled by the use +of the @t{zstyle} mechanism. In particular, widgets that interact with +the completion system pass along their context to any completions that +they invoke. + +@noindent +@table @asis +@kindex break-keys, widget style +@item @t{break-keys} +This style is used by the @t{incremental-complete-word} widget. Its value +should be a pattern, and all keys matching this pattern will cause the +widget to stop incremental completion without the key having any further +effect. Like all styles used directly by +@t{incremental-complete-word}, this style is looked up using the +context `@t{:incremental}'. + +@kindex completer, completion style +@item @t{completer} +The @t{incremental-complete-word} and @t{insert-and-predict} widgets set +up their top-level context name before calling completion. This allows +one to define different sets of completer functions for normal completion +and for these widgets. For example, to use completion, approximation and +correction for normal completion, completion and correction for +incremental completion and only completion for prediction one could use: + +@noindent +@example +zstyle ':completion:*' completer \ + _complete _correct _approximate +zstyle ':completion:incremental:*' completer \ + _complete _correct +zstyle ':completion:predict:*' completer \ + _complete +@end example + +@noindent +It is a good idea to restrict the completers used in prediction, because +they may be automatically invoked as you type. The @t{_list} and +@t{_menu} completers should never be used with prediction. The +@t{_approximate}, @t{_correct}, @t{_expand}, and @t{_match} completers may +be used, but be aware that they may change characters anywhere in the word +behind the cursor, so you need to watch carefully that the result is what +you intended. + +@kindex cursor, completion style +@item @t{cursor} +The @t{insert-and-predict} widget uses this style, in the context +`@t{:predict}', to decide where to place the cursor after completion has +been tried. Values are: + +@noindent +@table @asis +@item @t{complete} +The cursor is left where it was when completion finished, but only if +it is after a character equal to the one just inserted by the user. If +it is after another character, this value is the same as `@t{key}'. + +@item @t{key} +The cursor is left +after the @var{n}th occurrence of the character just inserted, where +@var{n} is the number of times that character appeared in the word +before completion was attempted. In short, this has the effect of +leaving the cursor after the character just typed even if the +completion code found out that no other characters need to be inserted +at that position. + +@end table + +@noindent +Any other value for this style unconditionally leaves the cursor at the +position where the completion code left it. + +@kindex list, widget style +@item @t{list} +When using the @t{incremental-complete-word} widget, this style says +if the matches should be listed on every key press (if they fit on the +screen). Use the context prefix `@t{:completion:incremental}'. + +@noindent +The @t{insert-and-predict} widget uses this style to decide if the +completion should be shown even if there is only one possible completion. +This is done if the value of this style is the string @t{always}. In this +case the context is `@t{:predict}' (@emph{not} `@t{:completion:predict}'). + +@kindex match, widget style +@item @t{match} +This style is used by @t{smart-insert-last-word} to provide a pattern +(using full @t{EXTENDED_GLOB} syntax) that matches an interesting word. +The context is the name of the widget to which @t{smart-insert-last-word} +is bound (see above). The default behavior of @t{smart-insert-last-word} +is equivalent to: + +@noindent +@example +zstyle :insert-last-word match '*[[:alpha:]/\\]*' +@end example + +@noindent +However, you might want to include words that contain spaces: + +@noindent +@example +zstyle :insert-last-word match '*[[:alpha:][:space:]/\\]*' +@end example + +@noindent +Or include numbers as long as the word is at least two characters long: + +@noindent +@example +zstyle :insert-last-word match '*([[:digit:]]?|[[:alpha:]/\\])*' +@end example + +@noindent +The above example causes redirections like "2>" to be included. + +@kindex prompt, widget style +@item @t{prompt} +The @t{incremental-complete-word} widget shows the value of this +style in the status line during incremental completion. The string +value may contain any of the following substrings in the manner of +the @t{PS1} and other prompt parameters: + +@noindent +@table @asis +@item @t{%c} +Replaced by the name of the completer function that generated the +matches (without the leading underscore). + +@item @t{%l} +When the @t{list} style is set, +replaced by `@t{...}' if the list of matches is too long to fit on the +screen and with an empty string otherwise. If the @t{list} style is +`false' or not set, `@t{%l}' is always removed. + +@item @t{%n} +Replaced by the number of matches generated. + +@item @t{%s} +Replaced by `@t{-no match-}', `@t{-no prefix-}', or an empty string +if there is no completion matching the word on the line, if the +matches have no common prefix different from the word on the line, or +if there is such a common prefix, respectively. + +@item @t{%u} +Replaced by the unambiguous part of all matches, if there +is any, and if it is different from the word on the line. + +@end table + +@noindent +Like `@t{break-keys}', this uses the `@t{:incremental}' context. + +@kindex stop-keys, widget style +@item @t{stop-keys} +This style is used by the @t{incremental-complete-word} widget. Its value +is treated similarly to the one for the @t{break-keys} style (and uses +the same context: `@t{:incremental}'). However, in +this case all keys matching the pattern given as its value will stop +incremental completion and will then execute their usual function. + +@kindex toggle, widget style +@item @t{toggle} +This boolean style is used by @t{predict-on} and its related widgets in +the context `@t{:predict}'. If set to one of the standard `true' values, +predictive typing is automatically toggled off in situations where it is +unlikely to be useful, such as when editing a multi-line buffer or after +moving into the middle of a line and then deleting a character. The +default is to leave prediction turned on until an explicit call to +@t{predict-off}. + +@kindex verbose, widget style +@item @t{verbose} +This boolean style is used by @t{predict-on} and its related widgets in +the context `@t{:predict}'. If set to one of the standard `true' values, +these widgets display a message below the prompt when the predictive state +is toggled. This is most useful in combination with the @t{toggle} style. +The default does not display these messages. + +@kindex widget, widget style +@item @t{widget} +This style is similar to the @t{command} style: For widget functions that +use @t{zle} to call other widgets, this style can sometimes be used to +override the widget which is called. The context for this style is the +name of the calling widget (@emph{not} the name of the calling function, +because one function may be bound to multiple widget names). + +@noindent +@example +zstyle :copy-earlier-word widget smart-insert-last-word +@end example + +@noindent +Check the documentation for the calling widget or function to determine +whether the @t{widget} style is used. + +@end table + +@noindent +@node Exception Handling, MIME Functions, ZLE Functions, User Contributions + +@section Exception Handling +@noindent + +@noindent +Two functions are provided to enable zsh to provide exception handling in a +form that should be familiar from other languages. + +@noindent +@table @asis +@findex throw +@item @t{throw} @var{exception} +The function @t{throw} throws the named @var{exception}. The name is +an arbitrary string and is only used by the @t{throw} and @t{catch} +functions. An exception is for the most part treated the same as a +shell error, i.e. an unhandled exception will cause the shell to abort all +processing in a function or script and to return to the top level in an +interactive shell. + +@item @t{catch} @var{exception-pattern} +The function @t{catch} returns status zero if an exception was thrown and +the pattern @var{exception-pattern} matches its name. Otherwise it +returns status 1. @var{exception-pattern} is a standard +shell pattern, respecting the current setting of the @t{EXTENDED_GLOB} +option. An alias @t{catch} is also defined to prevent the argument to the +function from matching filenames, so patterns may be used unquoted. Note +that as exceptions are not fundamentally different from other shell errors +it is possible to catch shell errors by using an empty string as the +exception name. The shell variable @t{CAUGHT} is set by @t{catch} to the +name of the exception caught. It is possible to rethrow an exception by +calling the @t{throw} function again once an exception has been caught. +@findex catch + +@end table + +@noindent +The functions are designed to be used together with the @t{always} construct +described in +@ref{Complex Commands}. This is important as only this +construct provides the required support for exceptions. A typical example +is as follows. + +@noindent +@example +@{ + # "try" block + # ... nested code here calls "throw MyExcept" +@} always @{ + # "always" block + if catch MyExcept; then + print "Caught exception MyExcept" + elif catch @value{dsq}; then + print "Caught a shell error. Propagating..." + throw @value{dsq} + fi + # Other exceptions are not handled but may be caught further + # up the call stack. +@} +@end example + +@noindent +If all exceptions should be caught, the following idiom might be +preferable. + +@noindent +@example +@{ + # ... nested code here throws an exception +@} always @{ + if catch *; then + case $CAUGHT in + (MyExcept) + print "Caught my own exception" + ;; + (*) + print "Caught some other exception" + ;; + esac + fi +@} +@end example + +@noindent +In common with exception handling in other languages, the exception may be +thrown by code deeply nested inside the `try' block. However, note that it +must be thrown inside the current shell, not in a subshell forked for a +pipeline, parenthesised current-shell construct, or some form of +command or process substitution. + +@noindent +The system internally uses the shell variable @t{EXCEPTION} to record the +name of the exception between throwing and catching. One drawback of this +scheme is that if the exception is not handled the variable @t{EXCEPTION} +remains set and may be incorrectly recognised as the name of an exception +if a shell error subsequently occurs. Adding @t{unset EXCEPTION} at the +start of the outermost layer of any code that uses exception handling will +eliminate this problem. + +@noindent +@node MIME Functions, Mathematical Functions, Exception Handling, User Contributions + +@section MIME Functions +@noindent + +@noindent +Three functions are available to provide handling of files recognised by +extension, for example to dispatch a file @t{text.ps} when executed as a +command to an appropriate viewer. + +@noindent +@table @asis +@findex zsh-mime-setup +@findex zsh-mime-handler +@item @t{zsh-mime-setup} [ @t{-fv} ] [ @t{-l} [ @var{suffix} ... ] ] +@itemx @t{zsh-mime-handler} [ @t{-l} ] @var{command argument} ... +These two functions use the files @t{~/.mime.types} and @t{/etc/mime.types}, +which associate types and extensions, as well as @t{~/.mailcap} and +@t{/etc/mailcap} files, which associate types and the programs that +handle them. These are provided on many systems with the Multimedia +Internet Mail Extensions. + +@noindent +To enable the system, the function @t{zsh-mime-setup} should be +autoloaded and run. This allows files with extensions to be treated +as executable; such files be completed by the function completion system. +The function @t{zsh-mime-handler} should not need to be called by the +user. + +@noindent +The system works by setting up suffix aliases with `@t{alias -s}'. +Suffix aliases already installed by the user will not be overwritten. + +@noindent +For suffixes defined in lower case, upper case variants will also +automatically be handled (e.g. @t{PDF} is automatically handled if +handling for the suffix @t{pdf} is defined), but not vice versa. + +@noindent +Repeated calls to @t{zsh-mime-setup} do not override the existing +mapping between suffixes and executable files unless the option @t{-f} +is given. Note, however, that this does not override existing suffix +aliases assigned to handlers other than @t{zsh-mime-handler}. + +@noindent +Calling @t{zsh-mime-setup} with the option @t{-l} lists the existing +mappings without altering them. Suffixes to list (which may contain +pattern characters that should be quoted from immediate interpretation +on the command line) may be given as additional arguments, otherwise +all suffixes are listed. + +@noindent +Calling @t{zsh-mime-setup} with the option +@t{-v} causes verbose output to be shown during the setup operation. + +@noindent +The system respects the @t{mailcap} flags @t{needsterminal} and +@t{copiousoutput}, see man page mailcap(4). + +@noindent +The functions use the following styles, which are defined with the +@t{zstyle} builtin command (@ref{The zsh/zutil Module}). They should be defined +before @t{zsh-mime-setup} is run. The contexts used all +start with @t{:mime:}, with additional components in some cases. +It is recommended that a trailing @t{*} (suitably quoted) be appended +to style patterns in case the system is extended in future. Some +examples are given below. + +@noindent +For files that have multiple suffixes, e.g. @t{.pdf.gz}, where the +context includes the suffix it will be looked up starting with the +longest possible suffix until a match for the style is found. +For example, if @t{.pdf.gz} produces a match for the handler, that +will be used; otherwise the handler for @t{.gz} will be used. Note +that, owing to the way suffix aliases work, it is always required that +there be a handler for the shortest possible suffix, so in this example +@t{.pdf.gz} can only be handled if @t{.gz} is also handled (though +not necessarily in the same way). Alternatively, if no handling +for @t{.gz} on its own is needed, simply adding the command + +@noindent +@example +alias -s gz=zsh-mime-handler +@end example + +@noindent +to the initialisation code is sufficient; @t{.gz} will not be handled +on its own, but may be in combination with other suffixes. + +@noindent +@table @asis +@kindex current-shell, MIME style +@item @t{current-shell} +If this boolean style is true, the mailcap handler for the context in +question is run using the @t{eval} builtin instead of by starting a new +@t{sh} process. This is more efficient, but may not work in the occasional +cases where the mailcap handler uses strict POSIX syntax. + +@kindex disown, MIME style +@item @t{disown} +If this boolean style is true, mailcap handlers started in the +background will be disowned, i.e. not subject to job control within +the parent shell. Such handlers nearly always produce their own +windows, so the only likely harmful side effect of setting the style is +that it becomes harder to kill jobs from within the shell. + +@kindex execute-as-is, MIME style +@item @t{execute-as-is} +This style gives a list of patterns to be matched against files +passed for execution with a handler program. If the file matches +the pattern, the entire command line is executed in its current form, +with no handler. This is useful for files which might have suffixes +but nonetheless be executable in their own right. If the style +is not set, the pattern @t{*(*) *(/)} is used; +hence executable files are executed directly and not passed to a +handler, and the option @t{AUTO_CD} may be used to change to directories +that happen to have MIME suffixes. + +@kindex execute-never, MIME style +@item @t{execute-never} +This style is useful in combination with @t{execute-as-is}. It is +set to an array of patterns corresponding to full paths to files that +should never be treated as executable, even if the file passed to +the MIME handler matches @t{execute-as-is}. This is useful for file +systems that don't handle execute permission or that contain executables +from another operating system. For example, if @t{/mnt/windows} is a +Windows mount, then + +@noindent +@example +zstyle ':mime:*' execute-never '/mnt/windows/*' +@end example + +@noindent +will ensure that any files found in that area will be executed as MIME +types even if they are executable. As this example shows, the complete +file name is matched against the pattern, regardless of how the file +was passed to the handler. The file is resolved to a full path using +the @t{:P} modifier described in +@ref{Modifiers}; +this means that symbolic links are resolved where possible, so that +links into other file systems behave in the correct fashion. + +@kindex file-path, MIME style +@item @t{file-path} +Used if the style @t{find-file-in-path} is true for the same context. +Set to an array of directories that are used for searching for the +file to be handled; the default is the command path given by the +special parameter @t{path}. The shell option @t{PATH_DIRS} is respected; +if that is set, the appropriate path will be searched even if the +name of the file to be handled as it appears on the command line contains +a `@t{/}'. +The full context is @t{:mime:.}@var{suffix}@t{:}, as described for the style +@t{handler}. + +@kindex find-file-in-path, MIME style +@item @t{find-file-in-path} +If set, allows files whose names do not contain absolute paths +to be searched for in the command path or the path specified by the +@t{file-path} style. If the file is not found in the path, it is looked +for locally (whether or not the current directory is in the path); if it is +not found locally, the handler will abort unless the @t{handle-nonexistent} +style is set. Files found in the path are tested as described for +the style @t{execute-as-is}. +The full context is @t{:mime:.}@var{suffix}@t{:}, as described for the style +@t{handler}. + +@kindex flags, MIME style +@item @t{flags} +Defines flags to go with a handler; the context is as for the +@t{handler} style, and the format is as for the flags in @t{mailcap}. + +@kindex handle-nonexistent, MIME style +@item @t{handle-nonexistent} +By default, arguments that don't correspond to files are not passed +to the MIME handler in order to prevent it from intercepting commands found +in the path that happen to have suffixes. This style may be set to +an array of extended glob patterns for arguments that will be passed to the +handler even if they don't exist. If it is not explicitly set it +defaults to @t{[[:alpha:]]#:/*} which allows URLs to be passed to the MIME +handler even though they don't exist in that format in the file system. +The full context is @t{:mime:.}@var{suffix}@t{:}, as described for the style +@t{handler}. + +@kindex handler, MIME style +@item @t{handler} +Specifies a handler for a suffix; the suffix is given by the context as +@t{:mime:.}@var{suffix}@t{:}, and the format of the handler is exactly +that in @t{mailcap}. Note in particular the `@t{.}' and trailing colon +to distinguish this use of the context. This overrides any handler +specified by the @t{mailcap} files. If the handler requires a terminal, +the @t{flags} style should be set to include the word @t{needsterminal}, +or if the output is to be displayed through a pager (but not if the +handler is itself a pager), it should include @t{copiousoutput}. + +@kindex mailcap, MIME style +@item @t{mailcap} +A list of files in the format of @t{~/.mailcap} and +@t{/etc/mailcap} to be read during setup, replacing the default list +which consists of those two files. The context is @t{:mime:}. +A @t{+} in the list will be replaced by the default files. + +@kindex mailcap-priorities, MIME style +@item @t{mailcap-priorities} +This style is used to resolve multiple mailcap entries for the same MIME +type. It consists of an array of the following elements, in descending +order of priority; later entries will be used if earlier entries are +unable to resolve the entries being compared. If none of the tests +resolve the entries, the first entry encountered is retained. + +@noindent +@table @asis +@item @t{files} +The order of files (entries in the @t{mailcap} style) read. Earlier +files are preferred. (Note this does not resolve entries in the same file.) + +@item @t{priority} +The priority flag from the mailcap entry. The priority is an integer +from 0 to 9 with the default value being 5. + +@item @t{flags} +The test given by the @t{mailcap-prio-flags} option is used to resolve +entries. + +@item @t{place} +Later entries are preferred; as the entries are strictly ordered, this +test always succeeds. + +@end table + +@noindent +Note that as this style is handled during initialisation, the context +is always @t{:mime:}, with no discrimination by suffix. + +@kindex mailcap-prio-flags, MIME style +@item @t{mailcap-prio-flags} +This style is used when the keyword @t{flags} is encountered in the +list of tests specified by the @t{mailcap-priorities} style. +It should be set to a list of patterns, each of which is tested against +the flags specified in the mailcap entry (in other words, the sets of +assignments found with some entries in the mailcap file). Earlier +patterns in the list are preferred to later ones, and matched patterns +are preferred to unmatched ones. + +@kindex mime-types, MIME style +@item @t{mime-types} +A list of files in the format of @t{~/.mime.types} and +@t{/etc/mime.types} to be read during setup, replacing the default list +which consists of those two files. The context is @t{:mime:}. +A @t{+} in the list will be replaced by the default files. + +@kindex never-background, MIME style +@item @t{never-background} +If this boolean style is set, the handler for the given context is +always run in the foreground, even if the flags provided in the mailcap +entry suggest it need not be (for example, it doesn't require a +terminal). + +@kindex pager, MIME style +@item @t{pager} +If set, will be used instead of @t{$PAGER} or @t{more} to handle +suffixes where the @t{copiousoutput} flag is set. The context is +as for @t{handler}, i.e. @t{:mime:.}@var{suffix}@t{:} for handling +a file with the given @var{suffix}. + +@end table + +@noindent +Examples: + +@noindent +@example +zstyle ':mime:*' mailcap ~/.mailcap /usr/local/etc/mailcap +zstyle ':mime:.txt:' handler less %s +zstyle ':mime:.txt:' flags needsterminal +@end example + +@noindent +When @t{zsh-mime-setup} is subsequently run, it will look for +@t{mailcap} entries in the two files given. Files of suffix @t{.txt} +will be handled by running `@t{less} @var{file.txt}'. The flag +@t{needsterminal} is set to show that this program must run attached to a +terminal. + +@noindent +As there are several steps to dispatching a command, the following +should be checked if attempting to execute a file by extension +@t{.}@var{ext} does not have the expected effect. + +@noindent +The command `@t{alias -s} @var{ext}' should show +`@t{ps=zsh-mime-handler}'. If it shows something else, another suffix +alias was already installed and was not overwritten. If it shows +nothing, no handler was installed: this is most likely because no +handler was found in the @t{.mime.types} and @t{mailcap} combination for +@t{.ext} files. In that case, appropriate handling should be added to +@t{~/.mime.types} and @t{mailcap}. + +@noindent +If the extension is handled by @t{zsh-mime-handler} but the file is +not opened correctly, either the handler defined for the type is +incorrect, or the flags associated with it are in appropriate. Running +@t{zsh-mime-setup -l} will show the handler and, if there are any, the +flags. A @t{%s} in the handler is replaced by the file (suitably quoted +if necessary). Check that the handler program listed lists and can +be run in the way shown. Also check that the flags @t{needsterminal} or +@t{copiousoutput} are set if the handler needs to be run under a +terminal; the second flag is used if the output should be sent to a pager. +An example of a suitable @t{mailcap} entry for such a program is: + +@noindent +@example +text/html; /usr/bin/lynx '%s'; needsterminal +@end example + +@noindent +Running `@t{zsh-mime-handler -l} @var{command line}' prints the command +line that would be executed, simplified to remove the effect of any +flags, and quoted so that the output can be run as a complete zsh +command line. This is used by the completion system to decide how to +complete after a file handled by @t{zsh-mime-setup}. + +@findex pick-web-browser +@item @t{pick-web-browser} +This function is separate from the two MIME functions described above +and can be assigned directly to a suffix: + +@noindent +@example +autoload -U pick-web-browser +alias -s html=pick-web-browser +@end example + +@noindent +It is provided as an intelligent front end to dispatch a web browser. +It may be run as either a function or a shell script. The status +255 is returned if no browser could be started. + +@noindent +Various styles are available to customize the choice of browsers: + +@noindent +@table @asis +@item @t{browser-style} +The value of the style is an array giving preferences in decreasing order +for the type of browser to use. The values of elements may be + +@noindent +@table @asis +@item @t{running} +Use a GUI browser that is already running when an X Window display is +available. The browsers listed in the @t{x-browsers} style are tried +in order until one is found; if it is, the file will be displayed in +that browser, so the user may need to check whether it has appeared. +If no running browser is found, one is not started. Browsers other than +Firefox, Opera and Konqueror are assumed to understand the Mozilla +syntax for opening a URL remotely. + +@item @t{x} +Start a new GUI browser when an X Window display is available. Search for +the availability of one of the browsers listed in the @t{x-browsers} style +and start the first one that is found. No check is made for an already +running browser. + +@item @t{tty} +Start a terminal-based browser. Search for the availability of one +of the browsers listed in the @t{tty-browsers} style and start the +first one that is found. + +@end table + +@noindent +If the style is not set the default @t{running x tty} is used. + +@item @t{x-browsers} +An array in decreasing order +of preference of browsers to use when running under the X Window System. +The array consists of the command name under which to start the +browser. They are looked up in the context @t{:mime:} (which may +be extended in future, so appending `@t{*}' is recommended). For +example, + +@noindent +@example +zstyle ':mime:*' x-browsers opera konqueror firefox +@end example + +@noindent +specifies that @t{pick-web-browser} should first look for a running +instance of Opera, Konqueror or Firefox, in that order, and if it +fails to find any should attempt to start Opera. The default is +@t{firefox mozilla netscape opera konqueror}. + +@item @t{tty-browsers} +An array similar to @t{x-browsers}, except that it gives browsers to +use when no X Window display is available. The default is +@t{elinks links lynx}. + +@item @t{command} +If it is set this style is used to pick the command +used to open a page for a browser. The context is +@t{:mime:browser:new:$browser:} to start a new browser or +@t{:mime:browser:running:$browser:} to open a URL in a browser already +running on the current X display, where @t{$browser} is the value matched +in the @t{x-browsers} or @t{tty-browsers} style. The escape sequence +@t{%b} in the style's value will be replaced by the browser, while @t{%u} +will be replaced by the URL. If the style is not set, the default for all +new instances is equivalent to @t{%b %u} and the defaults for using running +browsers are equivalent to the values @t{kfmclient openURL %u} for +Konqueror, @t{firefox -new-tab %u} for Firefox, @t{opera -newpage %u} +for Opera, and @t{%b -remote "openUrl(%u)"} for all others. + +@end table + +@end table + +@noindent +@node Mathematical Functions, User Configuration Functions, MIME Functions, User Contributions + +@section Mathematical Functions +@noindent + +@noindent +@table @asis +@findex zcalc +@item @t{zcalc} [ @t{-erf} ] [ @var{expression} ... ] +A reasonably powerful calculator based on zsh's arithmetic evaluation +facility. The syntax is similar to that of formulae in most programming +languages; see +@ref{Arithmetic Evaluation} for details. + +@noindent +Non-programmers should note that, as in many other programming +languages, expressions involving only integers (whether constants +without a `@t{.}', variables containing such constants as strings, or +variables declared to be integers) are by default evaluated using +integer arithmetic, which is not how an ordinary desk calculator +operates. To force floating point operation, pass the option @t{-f}; +see further notes below. + +@noindent +If the file @t{~/.zcalcrc} exists it will be sourced inside the function +once it is set up and about to process the command line. This +can be used, for example, to set shell options; @t{emulate -L zsh} +and @t{setopt extendedglob} are in effect at this point. Any +failure to source the file if it exists is treated as fatal. +As with other initialisation files, the directory @t{$ZDOTDIR} is used +instead of @t{$HOME} if it is set. + +@noindent +The mathematical library @t{zsh/mathfunc} will be loaded if it is +available; see +@ref{The zsh/mathfunc Module}. The mathematical functions +correspond to the raw system libraries, so trigonometric functions are +evaluated using radians, and so on. + +@noindent +Each line typed is evaluated as an expression. The prompt shows a number, +which corresponds to a positional parameter where the result of that +calculation is stored. For example, the result of the calculation on the +line preceded by `@t{4> }' is available as @t{$4}. The last value +calculated is available as @t{ans}. Full command line editing, including +the history of previous calculations, is available; the history is saved in +the file @t{~/.zcalc_history}. To exit, enter a blank line or type `@t{:q}' +on its own (`@t{q}' is allowed for historical compatibility). + +@noindent +A line ending with a single backslash is treated in the same fashion +as it is in command line editing: the backslash is removed, the +function prompts for more input (the prompt is preceded by `@t{...}' +to indicate this), and the lines are combined into one to get the final +result. In addition, if the input so far contains more open than +close parentheses @t{zcalc} will prompt for more input. + +@noindent +If arguments are given to @t{zcalc} on start up, they are used to prime the +first few positional parameters. A visual indication of this is given when +the calculator starts. + +@noindent +The constants @t{PI} (3.14159...) and @t{E} (2.71828...) are provided. +Parameter assignment is possible, but note that all parameters will be +put into the global namespace unless the @t{:local} special command is +used. The function creates local variables whose names start with +@t{_}, so users should avoid doing so. The variables @t{ans} (the last +answer) and @t{stack} (the stack in RPN mode) may be referred to +directly; @t{stack} is an array but elements of it are numeric. Various +other special variables are used locally with their standard meaning, +for example @t{compcontext}, @t{match}, @t{mbegin}, @t{mend}, @t{psvar}. + +@noindent +The output base can be initialised by passing the option `@t{-#}@var{base}', +for example `@t{zcalc -#16}' (the `@t{#}' may have to be quoted, depending +on the globbing options set). + +@noindent +If the option `@t{-e}' is set, the function runs non-interactively: +the arguments are treated as expressions to be evaluated as if entered +interactively line by line. + +@noindent +If the option `@t{-f}' is set, all numbers are treated as floating +point, hence for example the expression `@t{3/4}' evaluates to 0.75 +rather than 0. Options must appear in separate words. + +@noindent +If the option `@t{-r}' is set, RPN (Reverse Polish Notation) mode is +entered. This has various additional properties: +@table @asis +@item Stack +Evaluated values are maintained in a stack; this is contained in +an array named @t{stack} with the most recent value in @t{$@{stack[1]@}}. + +@item Operators and functions +If the line entered matches an operator (@t{+}, @t{-}, @t{*}, +@t{/}, @t{**}, @t{^}, @t{|} or @t{&}) or a function supplied by the +@t{zsh/mathfunc} library, the bottom element or elements of the stack +are popped to use as the argument or arguments. The higher elements +of stack (least recent) are used as earlier arguments. The result is +then pushed into @t{$@{stack[1]@}}. + +@item Expressions +Other expressions are evaluated normally, printed, and added to the +stack as numeric values. The syntax within expressions on a single line +is normal shell arithmetic (not RPN). + +@item Stack listing +If an integer follows the option @t{-r} with no space, then +on every evaluation that many elements of the stack, where available, +are printed instead of just the most recent result. Hence, for example, +@t{zcalc -r4} shows @t{$stack[4]} to @t{$stack[1]} each time results +are printed. + +@item Duplication: @t{=} +The pseudo-operator @t{=} causes the most recent element of +the stack to be duplicated onto the stack. + +@item @t{pop} +The pseudo-function @t{pop} causes the most recent element of +the stack to be popped. A `@t{>}' on its own has the same effect. + +@item @t{>}@var{ident} +The expression @t{>} followed (with no space) by a shell identifier +causes the most recent element of the stack to be popped and +assigned to the variable with that name. The variable is +local to the @t{zcalc} function. + +@item @t{<}@var{ident} +The expression @t{<} followed (with no space) by a shell identifier +causes the value of the variable with that name to be pushed +onto the stack. @var{ident} may be an integer, in which +case the previous result with that number (as shown before +the @t{>} in the standard @t{zcalc} prompt) is put on the stack. + +@item Exchange: @t{xy} +The pseudo-function @t{xy} causes the most recent two elements of +the stack to be exchanged. `@t{<>}' has the same effect. + +@end table + +@noindent +The prompt is configurable via the parameter @t{ZCALCPROMPT}, which +undergoes standard prompt expansion. The index of the current entry is +stored locally in the first element of the array @t{psvar}, which can be +referred to in @t{ZCALCPROMPT} as `@t{%1v}'. The default prompt is +`@t{%1v> }'. + +@noindent +The variable @t{ZCALC_ACTIVE} is set within the function and can +be tested by nested functions; it has the value @t{rpn} if RPN mode is +active, else 1. + +@noindent +A few special commands are available; these are introduced by a colon. +For backward compatibility, the colon may be omitted for certain +commands. Completion is available if @t{compinit} has been run. + +@noindent +The output precision may be specified within zcalc by special commands +familiar from many calculators. +@table @asis +@item @t{:norm} +The default output format. It corresponds to the printf @t{%g} +specification. Typically this shows six decimal digits. + +@item @t{:sci} @var{digits} +Scientific notation, corresponding to the printf @t{%g} output format with +the precision given by @var{digits}. This produces either fixed point or +exponential notation depending on the value output. + +@item @t{:fix} @var{digits} +Fixed point notation, corresponding to the printf @t{%f} output format with +the precision given by @var{digits}. + +@item @t{:eng} @var{digits} +Exponential notation, corresponding to the printf @t{%E} output format with +the precision given by @var{digits}. + +@item @t{:raw} +Raw output: this is the default form of the output from a math +evaluation. This may show more precision than the number actually +possesses. + +@end table + +@noindent +Other special commands: +@table @asis +@item @t{:!}@var{line...} +Execute @var{line...} as a normal shell command line. Note that it +is executed in the context of the function, i.e. with local variables. +Space is optional after @t{:!}. + +@item @t{:local} @var{arg} ... +Declare variables local to the function. Other variables +may be used, too, but they will be taken from or put into the global +scope. + +@item @t{:function} @var{name} [ @var{body} ] +Define a mathematical function or (with no @var{body}) delete it. +@t{:function} may be abbreviated to @t{:func} or simply @t{:f}. +The @var{name} may contain the same characters as a shell function name. +The function is defined using @t{zmathfuncdef}, see below. + +@noindent +Note that @t{zcalc} takes care of all quoting. Hence for example: + +@noindent +@example +:f cube $1 * $1 * $1 +@end example + +@noindent +defines a function to cube the sole argument. Functions so defined, or +indeed any functions defined directly or indirectly using @t{functions +-M}, are available to execute by typing only the name on the line in RPN +mode; this pops the appropriate number of arguments off the stack +to pass to the function, i.e. 1 in the case of the example @t{cube} +function. If there are optional arguments only the mandatory +arguments are supplied by this means. + +@item @t{[#}@var{base}@t{]} +This is not a special command, rather part of normal arithmetic +syntax; however, when this form appears on a line by itself the default +output radix is set to @var{base}. Use, for example, `@t{[#16]}' to display +hexadecimal output preceded by an indication of the base, or `@t{[##16]}' +just to display the raw number in the given base. Bases themselves are +always specified in decimal. `@t{[#]}' restores the normal output format. +Note that setting an output base suppresses floating point output; use +`@t{[#]}' to return to normal operation. + +@item @t{$}@var{var} +Print out the value of var literally; does not affect the calculation. +To use the value of var, omit the leading `@t{$}'. + +@end table + +@noindent +See the comments in the function for a few extra tips. + +@findex max +@findex min +@findex sum +@findex zmathfunc +@item @t{min(}@var{arg}@t{, ...)} +@itemx @t{max(}@var{arg}@t{, ...)} +@itemx @t{sum(}@var{arg}@t{, ...)} +@itemx @t{zmathfunc} +The function @t{zmathfunc} defines the three mathematical functions +@t{min}, @t{max}, and @t{sum}. The functions @t{min} and @t{max} take +one or more arguments. The function @t{sum} takes zero or more arguments. +Arguments can be of different types (ints and floats). + +@noindent +Not to be confused with the @t{zsh/mathfunc} module, described in +@ref{The zsh/mathfunc Module}. + +@findex zmathfuncdef +@item @t{zmathfuncdef} [ @var{mathfunc} [ @var{body} ] ] +A convenient front end to @t{functions -M}. + +@noindent +With two arguments, define a mathematical function named @var{mathfunc} +which can be used in any form of arithmetic evaluation. @var{body} +is a mathematical expression to implement the function. It may +contain references to position parameters @t{$1}, @t{$2}, ... +to refer to mandatory parameters and @t{$@{1:-}@var{defvalue}@t{@}} ... +to refer to optional parameters. Note that the forms must be +strictly adhered to for the function to calculate the correct number +of arguments. The implementation is held in a shell function named +@t{zsh_math_func_}@var{mathfunc}; usually the user will not need +to refer to the shell function directly. Any existing function +of the same name is silently replaced. + +@noindent +With one argument, remove the mathematical function @var{mathfunc} +as well as the shell function implementation. + +@noindent +With no arguments, list all @var{mathfunc} functions in a form +suitable for restoring the definition. +The functions have not necessarily been defined by @t{zmathfuncdef}. + +@end table + +@noindent +@node User Configuration Functions, Other Functions, Mathematical Functions, User Contributions + +@section User Configuration Functions +@noindent + +@noindent +The @t{zsh/newuser} module comes with a function to aid in configuring +shell options for new users. If the module is installed, this function can +also be run by hand. It is available even if the module's default +behaviour, namely running the function for a new user logging in without +startup files, is inhibited. + +@noindent +@table @asis +@item @t{zsh-newuser-install} [ @t{-f} ] +The function presents the user with various options for customizing +their initialization scripts. Currently only @t{~/.zshrc} is handled. +@t{$ZDOTDIR/.zshrc} is used instead if the parameter @t{ZDOTDIR} is +set; this provides a way for the user to configure a file without +altering an existing @t{.zshrc}. + +@noindent +By default the function exits immediately if it finds any of the files +@t{.zshenv}, @t{.zprofile}, @t{.zshrc}, or @t{.zlogin} in the appropriate +directory. The option @t{-f} is required in order to force the function +to continue. Note this may happen even if @t{.zshrc} itself does not +exist. + +@noindent +As currently configured, the function will exit immediately if the +user has root privileges; this behaviour cannot be overridden. + +@noindent +Once activated, the function's behaviour is supposed to be +self-explanatory. Menus are present allowing the user to alter +the value of options and parameters. Suggestions for improvements are +always welcome. + +@noindent +When the script exits, the user is given the opportunity to save the new +file or not; changes are not irreversible until this point. However, +the script is careful to restrict changes to the file only to a group +marked by the lines `@t{# Lines configured by zsh-newuser-install}' and +`@t{# End of lines configured by zsh-newuser-install}'. In addition, +the old version of @t{.zshrc} is saved to a file with the suffix +@t{.zni} appended. + +@noindent +If the function edits an existing @t{.zshrc}, it is up to the user +to ensure that the changes made will take effect. For example, if +control usually returns early from the existing @t{.zshrc} the lines +will not be executed; or a later initialization file may override +options or parameters, and so on. The function itself does not attempt to +detect any such conflicts. + +@end table + +@noindent +@node Other Functions, , User Configuration Functions, User Contributions + +@section Other Functions +@noindent + +@noindent +There are a large number of helpful functions in the @t{Functions/Misc} +directory of the zsh distribution. Most are very simple and do not +require documentation here, but a few are worthy of special mention. + +@noindent + +@subsection Descriptions +@noindent + +@noindent +@table @asis +@findex colors +@item @t{colors} +This function initializes several associative arrays to map color names to +(and from) the ANSI standard eight-color terminal codes. These are used +by the prompt theme system (@ref{Prompt Themes}). You seldom should need to run +@t{colors} more than once. + +@noindent +The eight base colors are: @t{black}, @t{red}, @t{green}, @t{yellow}, +@t{blue}, @t{magenta}, @t{cyan}, and @t{white}. Each of these has codes for +foreground and background. In addition there are seven intensity attributes: +@t{bold}, @t{faint}, @t{standout}, @t{underline}, @t{blink}, @t{reverse}, +and @t{conceal}. Finally, there are seven codes used to negate attributes: +@t{none} (reset all attributes to the defaults), @t{normal} +(neither bold nor faint), @t{no-standout}, @t{no-underline}, @t{no-blink}, +@t{no-reverse}, and @t{no-conceal}. + +@noindent +Some terminals do not support all combinations of colors and intensities. + +@noindent +The associative arrays are: + +@noindent +@table @asis +@item @t{color} +@itemx @t{colour} +Map all the color names to their integer codes, and integer codes to the +color names. The eight base names map to the foreground color codes, as +do names prefixed with `@t{fg-}', such as `@t{fg-red}'. Names prefixed +with `@t{bg-}', such as `@t{bg-blue}', refer to the background codes. The +reverse mapping from code to color yields base name for foreground codes +and the @t{bg-} form for backgrounds. + +@noindent +Although it is a misnomer to call them `colors', these arrays also map the +other fourteen attributes from names to codes and codes to names. + +@item @t{fg} +@itemx @t{fg_bold} +@itemx @t{fg_no_bold} +Map the eight basic color names to ANSI terminal escape sequences that set +the corresponding foreground text properties. The @t{fg} sequences change +the color without changing the eight intensity attributes. + +@item @t{bg} +@itemx @t{bg_bold} +@itemx @t{bg_no_bold} +Map the eight basic color names to ANSI terminal escape sequences that set +the corresponding background properties. The @t{bg} sequences change the +color without changing the eight intensity attributes. + +@end table + +@noindent +In addition, the scalar parameters @t{reset_color} and @t{bold_color} are +set to the ANSI terminal escapes that turn off all attributes and turn on +bold intensity, respectively. + +@findex fned +@item @t{fned} [ @t{-x} @var{num} ] @var{name} +Same as @t{zed -f}. This function does not appear in the zsh +distribution, but can be created by linking @t{zed} to the name @t{fned} +in some directory in your @t{fpath}. + +@findex is-at-least +@item @t{is-at-least} @var{needed} [ @var{present} ] +Perform a greater-than-or-equal-to comparison of two strings having the +format of a zsh version number; that is, a string of numbers and text with +segments separated by dots or dashes. If the @var{present} string is not +provided, @t{$ZSH_VERSION} is used. Segments are paired left-to-right in +the two strings with leading non-number parts ignored. If one string has +fewer segments than the other, the missing segments are considered zero. + +@noindent +This is useful in startup files to set options and other state that are +not available in all versions of zsh. + +@noindent +@example +is-at-least 3.1.6-15 && setopt NO_GLOBAL_RCS +is-at-least 3.1.0 && setopt HIST_REDUCE_BLANKS +is-at-least 2.6-17 || print "You can't use is-at-least here." +@end example + +@findex nslookup +@item @t{nslookup} [ @var{arg} ... ] +This wrapper function for the @t{nslookup} command requires the +@t{zsh/zpty} module (see +@ref{The zsh/zpty Module}). It behaves exactly like the standard @t{nslookup} +except that it provides customizable prompts (including a right-side +prompt) and completion of nslookup commands, host names, etc. (if you use +the function-based completion system). Completion styles may be set with +the context prefix `@t{:completion:nslookup}'. + +@noindent +See also the @t{pager}, @t{prompt} and @t{rprompt} styles below. + +@findex regexp-replace +@item @t{regexp-replace} @var{var} @var{regexp} @var{replace} +Use regular expressions to perform a global search and replace operation +on a variable. POSIX extended regular expressions are used, +unless the option @t{RE_MATCH_PCRE} has been set, in which case +Perl-compatible regular expressions are used +(this requires the shell to be linked against the @t{pcre} +library). + +@noindent +@var{var} is the name of the variable containing the string to be matched. +The variable will be modified directly by the function. The +variables @t{MATCH}, @t{MBEGIN}, @t{MEND}, @t{match}, @t{mbegin}, @t{mend} +should be avoided as these are used by the regular expression code. + +@noindent +@var{regexp} is the regular expression to match against the string. + +@noindent +@var{replace} is the replacement text. This can contain parameter, command +and arithmetic expressions which will be replaced: in particular, a +reference to @t{$MATCH} will be replaced by the text matched by the pattern. + +@noindent +The return status is 0 if at least one match was performed, else 1. + +@findex run-help +@item @t{run-help} @var{cmd} +This function is designed to be invoked by the @t{run-help} ZLE widget, +in place of the default alias. See `Accessing On-Line Help' +(@ref{Utilities}) for setup instructions. + +@noindent +In the discussion which follows, if @var{cmd} is a file system path, it is +first reduced to its rightmost component (the file name). + +@noindent +Help is first sought by looking for a file named @var{cmd} in the directory +named by the @t{HELPDIR} parameter. If no file is found, an assistant +function, alias, or command named @t{run-help-@var{cmd}} is sought. If +found, the assistant is executed with the rest of the current command line +(everything after the command name @var{cmd}) as its arguments. When +neither file nor assistant is found, the external command +`@t{man} @var{cmd}' is run. + +@noindent +An example assistant for the "ssh" command: + +@noindent +@example +run-help-ssh() @{ + emulate -LR zsh + local -a args + # Delete the "-l username" option + zparseopts -D -E -a args l: + # Delete other options, leaving: host command + args=($@{@@:#-*@}) + if [[ $@{#args@} -lt 2 ]]; then + man ssh + else + run-help $args[2] + fi +@} +@end example + +@noindent +Several of these assistants are provided in the @t{Functions/Misc} +directory. These must be autoloaded, or placed as executable scripts in +your search path, in order to be found and used by @t{run-help}. + +@noindent +@table @asis +@findex run-help-git +@findex run-help-ip +@findex run-help-openssl +@findex run-help-p4 +@findex run-help-sudo +@findex run-help-svk +@findex run-help-svn +@item run-help-git +@itemx run-help-ip +@itemx run-help-openssl +@itemx run-help-p4 +@itemx run-help-sudo +@itemx run-help-svk +@itemx @t{run-help-svn} +Assistant functions for the +@t{git}, +@t{ip}, +@t{openssl}, +@t{p4}, +@t{sudo}, +@t{svk}, +and +@t{svn}, +commands. + +@end table + +@item @t{tetris} +Zsh was once accused of not being as complete as Emacs, +because it lacked a Tetris game. This function was written to +refute this vicious slander. + +@noindent +This function must be used as a ZLE widget: + +@noindent +@example +autoload -U tetris +zle -N tetris +bindkey @var{keys} tetris +@end example + +@noindent +To start a game, execute the widget by typing the @var{keys}. Whatever command +line you were editing disappears temporarily, and your keymap is also +temporarily replaced by the Tetris control keys. The previous editor state +is restored when you quit the game (by pressing `@t{q}') or when you lose. + +@noindent +If you quit in the middle of a game, the next invocation of the @t{tetris} +widget will continue where you left off. If you lost, it will start a new +game. + +@item @t{tetriscurses} +This is a port of the above to zcurses. The input handling is improved +a bit so that moving a block sideways doesn't automatically advance a +timestep, and the graphics use unicode block graphics. + +@noindent +This version does not save the game state between invocations, and is not +invoked as a widget, but rather as: + +@noindent +@example +autoload -U tetriscurses +tetriscurses +@end example + +@findex zargs +@item @t{zargs} [ @var{option} ... @t{-}@t{-} ] [ @var{input} ... ] [ @t{-}@t{-} @var{command} [ @var{arg} ... ] ] +This function has a similar purpose to GNU xargs. Instead of +reading lines of arguments from the standard input, it takes them from +the command line. This is useful because zsh, especially with recursive +glob operators, often can construct a command line for a shell function +that is longer than can be accepted by an external command. + +@noindent +The @var{option} list represents options of the @t{zargs} command itself, +which are the same as those of @t{xargs}. The @var{input} list is the +collection of strings (often file names) that become the arguments of the +@t{command}, analogous to the standard input of @t{xargs}. Finally, the +@var{arg} list consists of those arguments (usually options) that are +passed to the @var{command} each time it runs. The @var{arg} list precedes +the elements from the @t{input} list in each run. If no @var{command} is +provided, then no @var{arg} list may be provided, and in that event the +default command is `@t{print}' with arguments `@t{-r -}@t{-}'. + +@noindent +For example, to get a long @t{ls} listing of all non-hidden plain files +in the current directory or its subdirectories: + +@noindent +@example +autoload -U zargs +zargs -- **/*(.) -- ls -ld -- +@end example + +@noindent +The first and third occurrences of `@t{-}@t{-}' are used to mark the end +of options for @t{zargs} and @t{ls} respectively to guard against +filenames starting with `@t{-}', while the second is used to separate the +list of files from the command to run (`@t{ls -ld --}'). + +@noindent +The first `@t{-}@t{-}' would also be needed if there was a chance the +list might be empty as in: + +@noindent +@example +zargs -r -- ./*.back(#qN) -- rm -f +@end example + +@noindent +In the event that the string `@t{-}@t{-}' is or may be an @var{input}, the +@t{-e} option may be used to change the end-of-inputs marker. Note that +this does @emph{not} change the end-of-options marker. For example, to use +`@t{..}' as the marker: + +@noindent +@example +zargs -e.. -- **/*(.) .. ls -ld -- +@end example + +@noindent +This is a good choice in that example because no plain file can be named +`@t{..}', but the best end-marker depends on the circumstances. + +@noindent +The options @t{-i}, @t{-I}, @t{-l}, @t{-L}, and @t{-n} differ slightly +from their usage in @t{xargs}. There are no input lines for @t{zargs} to +count, so @t{-l} and @t{-L} count through the @var{input} list, and @t{-n} +counts the number of arguments passed to each execution of @var{command}, +@emph{including} any @var{arg} list. Also, any time @t{-i} or @t{-I} is used, +each @var{input} is processed separately as if by `@t{-L} @t{1}'. + +@noindent +For details of the other @t{zargs} options, see man page xargs(1) (but note +the difference in function between @t{zargs} and @t{xargs}) or run +@t{zargs} with the @t{-}@t{-help} option. + +@findex zed +@item @t{zed} [ @t{-f} [ @t{-x} @var{num} ] ] @var{name} +@itemx @t{zed -b} +This function uses the ZLE editor to edit a file or function. + +@noindent +Only one @var{name} argument is allowed. +If the @t{-f} option is given, the name is taken to be that of +a function; if the function is marked for autoloading, @t{zed} searches +for it in the @t{fpath} and loads it. Note that functions edited this way +are installed into the current shell, but @emph{not} written back to the +autoload file. In this case the @t{-x} option specifies that leading +tabs indenting the function according to syntax should be converted into +the given number of spaces; `@t{-x 2}' is consistent with the layout +of functions distributed with the shell. + +@noindent +Without @t{-f}, @var{name} is the path name of the file to edit, which need +not exist; it is created on write, if necessary. + +@noindent +While editing, the function sets the main keymap to @t{zed} and the +vi command keymap to @t{zed-vicmd}. These will be copied from the existing +@t{main} and @t{vicmd} keymaps if they do not exist the first time @t{zed} +is run. They can be used to provide special key bindings used only in zed. + +@noindent +If it creates the keymap, @t{zed} rebinds the return key to insert a line +break and `@t{^X^W}' to accept the edit in the @t{zed} keymap, and binds +`@t{ZZ}' to accept the edit in the @t{zed-vicmd} keymap. + +@noindent +The bindings alone can be installed by running `@t{zed -b}'. This is +suitable for putting into a startup file. Note that, if rerun, +this will overwrite the existing @t{zed} and @t{zed-vicmd} keymaps. + +@noindent +Completion is available, and styles may be set with the context prefix +`@t{:completion:zed}'. + +@noindent +A zle widget @t{zed-set-file-name} is available. This can be called by +name from within zed using `@t{\ex zed-set-file-name}' (note, however, that +because of zed's rebindings you will have to type @t{^j} at the end instead +of the return key), or can be bound to a key in either of the @t{zed} or +@t{zed-vicmd} keymaps after `@t{zed -b}' has been run. When the widget is +called, it prompts for a new name for the file being edited. When zed +exits the file will be written under that name and the original file will +be left alone. The widget has no effect with `@t{zed -f}'. + +@noindent +While @t{zed-set-file-name} is running, zed uses the keymap +@t{zed-normal-keymap}, which is linked from the main keymap in effect +at the time zed initialised its bindings. (This is to make the return key +operate normally.) The result is that if the main keymap has been changed, +the widget won't notice. This is not a concern for most users. + +@findex zcp +@findex zln +@item @t{zcp} [ @t{-finqQvwW} ] @var{srcpat} @var{dest} +@itemx @t{zln} [ @t{-finqQsvwW} ] @var{srcpat} @var{dest} +Same as @t{zmv -C} and @t{zmv -L}, respectively. These functions do not +appear in the zsh distribution, but can be created by linking @t{zmv} to +the names @t{zcp} and @t{zln} in some directory in your @t{fpath}. + +@item @t{zkbd} +See `Keyboard Definition' +(@ref{Utilities}). + +@findex zmv + +@item @t{zmv} [ @t{-finqQsvwW} ] [ @t{-C} | @t{-L} | @t{-M} | -@{@t{p}|@t{P}@} @var{program} ] [ @t{-o} @var{optstring} ] +@itemx @t{@ @ @ @ }@var{srcpat} @var{dest} +Move (usually, rename) files matching the pattern @var{srcpat} to +corresponding files having names of the form given by @var{dest}, where +@var{srcpat} contains parentheses surrounding patterns which will be +replaced in turn by @t{$1}, @t{$2}, ... in @var{dest}. For example, + +@noindent +@example +zmv '(*).lis' '$1.txt' +@end example + +@noindent +renames `@t{foo.lis}' to `@t{foo.txt}', `@t{my.old.stuff.lis}' to +`@t{my.old.stuff.txt}', and so on. + +@noindent +The pattern is always treated as an @t{EXTENDED_GLOB} pattern. Any file +whose name is not changed by the substitution is simply ignored. Any +error (a substitution resulted in an empty string, two substitutions gave +the same result, the destination was an existing regular file and @t{-f} +was not given) causes the entire function to abort without doing +anything. + +@noindent +In addition to pattern replacement, the variable @t{$f} can be referrred +to in the second (replacement) argument. This makes it possible to +use variable substitution to alter the argument; see examples below. + +@noindent +Options: + +@noindent +@table @asis +@item @t{-f} +Force overwriting of destination files. Not currently +passed down to the @t{mv}/@t{cp}/@t{ln} command due to vagaries of +implementations (but you can use @t{-o-f} to do that). +@item @t{-i} +Interactive: show each line to be executed and ask the user +whether to execute it. `@t{Y}' or `@t{y}' will execute it, anything else will +skip it. Note that you just need to type one character. +@item @t{-n} +No execution: print what would happen, but don't do it. +@item @t{-q} +Turn bare glob qualifiers off: now assumed by default, so +this has no effect. +@item @t{-Q} +Force bare glob qualifiers on. Don't turn this on unless +you are actually using glob qualifiers in a pattern. +@item @t{-s} +Symbolic, passed down to @t{ln}; only works with @t{-L}. +@item @t{-v} +Verbose: print each command as it's being executed. +@item @t{-w} +Pick out wildcard parts of the pattern, as described above, +and implicitly add parentheses for referring to them. +@item @t{-W} +Just like @t{-w}, with the addition of turning wildcards in +the replacement pattern into sequential @t{$@{1@}} .. @t{$@{N@}} references. +@item @t{-C} +@itemx @t{-L} +@itemx @t{-M} +Force @t{cp}, @t{ln} or @t{mv}, respectively, regardless of +the name of the function. +@item @t{-p} @var{program} +Call @var{program} instead of @t{cp}, @t{ln} or +@t{mv}. Whatever it does, it should at least understand the form +@example +@var{program} @t{-}@t{-} @var{oldname} @var{newname} +@end example +where @var{oldname} and @var{newname} are filenames generated by @t{zmv}. +@var{program} will be split into words, so might be e.g. the name +of an archive tool plus a copy or rename subcommand. +@item @t{-P} @var{program} +As @t{-p} @var{program}, except that +@var{program} does not accept a following @t{-}@t{-} to indicate the +end of options. In this case filenames must already be in a sane +form for the program in question. +@item @t{-o} @var{optstring} +The @var{optstring} is split into words and +passed down verbatim to the @t{cp}, @t{ln} or @t{mv} command called to +perform the work. It should probably begin with a `@t{-}'. +@end table + +@noindent +Further examples: + +@noindent +@example +zmv -v '(* *)' '$@{1// /_@}' +@end example + +@noindent +For any file in the current directory with at least one space in the name, +replace every space by an underscore and display the commands executed. + +@noindent +@example +zmv -v '* *' '$@{f// /_@}' +@end example + +@noindent +This does exactly the same by referring to the file name stored in @t{$f}. + +@noindent +For more complete examples and other implementation details, see the +@t{zmv} source file, usually located in one of the directories named in +your @t{fpath}, or in @t{Functions/Misc/zmv} in the zsh distribution. + +@item @t{zrecompile} +See `Recompiling Functions' +(@ref{Utilities}). + +@findex zstyle+ +@item @t{zstyle+} @var{context} @var{style} @var{value} [ @t{+} @var{subcontext} @var{style} @var{value} ... ] +This makes defining styles a bit simpler by using a single `@t{+}' as a +special token that allows you to append a context name to the previously +used context name. Like this: + +@noindent +@example +zstyle+ ':foo:bar' @var{style1} @var{value1} \ + +':baz' @var{style2} @var{value2} \ + +':frob' @var{style3} @var{value3} +@end example + +@noindent +This defines @var{style1} with @var{value1} for the context @t{:foo:bar} as usual, +but it also defines @var{style2} with @var{value2} for the context +@t{:foo:bar:baz} and @var{style3} with @var{value3} for @t{:foo:bar:frob}. Any +@var{subcontext} may be the empty string to re-use the first context +unchanged. + +@end table + +@noindent + +@subsection Styles +@noindent + +@noindent +@table @asis +@kindex insert-tab, completion style +@item @t{insert-tab} +The @t{zed} function @emph{sets} this style in context `@t{:completion:zed:*}' +to turn off completion when @t{TAB} is typed at the beginning of a line. +You may override this by setting your own value for this context and style. + +@kindex pager, nslookup style +@item @t{pager} +The @t{nslookup} function looks up this style in the context +`@t{:nslookup}' to determine the program used to display output that does +not fit on a single screen. + +@kindex prompt, nslookup style +@kindex rprompt, nslookup style +@item @t{prompt} +@itemx @t{rprompt} +The @t{nslookup} function looks up this style in the context +`@t{:nslookup}' to set the prompt and the right-side prompt, respectively. +The usual expansions for the @t{PS1} and @t{RPS1} parameters may be used +(see +@ref{Prompt Expansion}). + +@end table +@c (avoiding a yodl bug) +@c (avoiding a yodl bug) +@c (avoiding a yodl bug) +@c Yodl file: Zsh/index.yo +@node Concept Index, Variables Index, Top, Top +@page +@unnumbered Concept Index + +@printindex cp + +@noindent +@node Variables Index, Options Index, Concept Index, Top +@page +@unnumbered Variables Index + +@printindex vr + +@noindent +@node Options Index, Functions Index, Variables Index, Top +@page +@unnumbered Options Index + +@printindex pg + +@noindent +@node Functions Index, Editor Functions Index, Options Index, Top +@page +@unnumbered Functions Index + +@printindex fn + +@noindent +@node Editor Functions Index, Style and Tag Index, Functions Index, Top +@page +@unnumbered Editor Functions Index + +@printindex tp + +@noindent +@node Style and Tag Index, , Editor Functions Index, Top +@page +@unnumbered Style and Tag Index + +@printindex ky +@c (avoiding a yodl bug) + +@bye |