// AUTO-GENERATED. DO NOT EDIT BY HAND.
//
// Source: zsh upstream `/Users/wizard/forkedRepos/zsh/Doc/Zsh/builtins.yo (+47 more)`.
// Regen: ./scripts/gen_option_docs.py --source builtins /Users/wizard/forkedRepos/zsh/Doc/Zsh/builtins.yo (+47 more) > <this file>
// Generated: 2026-05-23
/// Canonical builtin name → markdown documentation body.
/// Pulled verbatim from every `item(tt(NAME))(...)` block in
/// the upstream yodl source. Use [`lookup_builtin_doc`] to resolve
/// case-insensitive lookups and any negated/compact aliases.
pub const BUILTIN_DOCS: &[(&str, &str)] = &[
("ARG1", "See _Precommand Modifiers_ (zshmisc)."),
("ARG1", "Same as `ARG2`."),
("ARG1", "See _The ARG2 Module_ (zshmodules)."),
("ARG1", "See _Zle Builtins_ (zshzle)."),
(".", "Read commands from _file_ and execute them in the current shell\nenvironment.\n\nIf _file_ does not contain a slash, or if `PATH_DIRS` is set,\nthe shell looks in the components of `$path` to find the directory\ncontaining _file_. Files in the current directory are not read\nunless \".\" appears somewhere in `$path`. If a file named\n`_file_`.zwc`' is found, is newer than _file_, and is the\ncompiled form (created with the `zcompile` builtin) of _file_,\nthen commands are read from that file instead of _file_.\n\nIf any arguments _arg_ are given,\nthey become the positional parameters; the old positional\nparameters are restored when the _file_ is done executing.\nHowever, if no arguments are given,\nthe positional parameters remain those of the calling context,\nand no restoring is done.\n\nIf _file_ was not found the return status is 127; if _file_ was found\nbut contained a syntax error the return status is 126; else the return\nstatus is the exit status of the last command executed."),
("NOTRANS(:", "This command does nothing, although normal argument expansions is performed\nwhich may have effects on shell parameters. A zero exit status is returned."),
("alias", "For each _name_ with a corresponding _value_, define an alias\nwith that value. A trailing space in _value_ causes the next word\nto be checked for alias expansion. If the `-g` flag is present,\ndefine a global alias; global aliases are expanded even if they do not\noccur in command position:\n\n % perldoc --help 2>&1 | grep 'built-in functions'\n -f Search Perl built-in functions\n% alias -g HG='--help 2>&1 | grep'\n% perldoc HG 'built-in functions'\n -f Search Perl built-in functions\n\nIf the `-s` flag is present, define a suffix alias: if the command\nword on a command line is in the form `_text_`.\"_name_\", where\n_text_ is any non-empty string, it is replaced by the text\n`_value_ _text_`.\"_name_\". Note that _name_ is treated as\na literal string, not a pattern. A trailing space in _value_ is not\nspecial in this case. For example,\n\n alias -s ps='gv --'\n\nwill cause the command \"*.ps\" to be expanded to \"gv -- *.ps\". As\nalias expansion is carried out earlier than globbing, the \"*.ps\" will\nthen be expanded. Suffix aliases constitute a different name space from\nother aliases (so in the above example it is still possible\nto create an alias for the command `ps`) and the two sets are never\nlisted together.\n\nFor each _name_ with no _value_,\nprint the value of _name_, if any. With no arguments, print all\ncurrently defined aliases other than suffix aliases. If the `-m` flag\nis given the arguments are taken as patterns (they should be quoted to\npreserve them from being interpreted as glob patterns), and the aliases\nmatching these patterns are printed. When printing aliases and one of\nthe `-g`, `-r` or `-s` flags is present, restrict the printing to\nglobal, regular or suffix aliases, respectively; a regular alias is one\nwhich is neither a global nor a suffix alias. Using \"+\"\ninstead of \"-\", or ending the option list with a single\n\"+\", prevents the values of the aliases from being printed.\n\nIf the `-L` flag is present, then print each\nalias in a manner suitable for putting in a startup script. The exit\nstatus is nonzero if a _name_ (with no _value_) is given for\nwhich no alias has been defined.\n\nFor more on aliases, including common problems,\nsee _Aliasing_ (zshmisc)."),
("autoload", "vindex(fpath, searching)\nSee _Autoloading Functions_ (zshmisc)\nfor full details. The `fpath` parameter\nwill be searched to find the function definition when the function is\nfirst referenced.\n\nIf _name_ consists of an absolute path, the function is defined to\nload from the file given (searching as usual for dump files in the given\nlocation). The name of the function is the basename (non-directory\npart) of the file. It is normally an error if the function is not found\nin the given location; however, if the option `-d` is given, searching\nfor the function defaults to `$fpath`. If a function is loaded by\nabsolute path, any functions loaded from it that are marked for\n`autoload` without an absolute path have the load path of the parent\nfunction temporarily prepended to `$fpath`.\n\nIf the option `-r` or `-R` is given, the function is searched for\nimmediately and the location is recorded internally for use when the\nfunction is executed; a relative path is expanded using the value of\n`$PWD`. This protects against a change to `$fpath` after the call\nto `autoload`. With `-r`, if the function is not found, it is\nsilently left unresolved until execution; with `-R`, an error message\nis printed and command processing aborted immediately the search fails,\ni.e. at the `autoload` command rather than at function execution..\n\nThe flag `-X` may be used only inside a shell function. It causes the\ncalling function to be marked for autoloading and then immediately\nloaded and executed, with the current array of positional parameters as\narguments. This replaces the previous definition of the function. If\nno function definition is found, an error is printed and the function\nremains undefined and marked for autoloading. If an argument is given,\nit is used as a directory (i.e. it does not include the name of the\nfunction) in which the function is to be found; this may be combined\nwith the `-d` option to allow the function search to default to `$fpath`\nif it is not in the given location.\n\nThe flag `+X` attempts to load each _name_ as an autoloaded function,\nbut does _not_ execute it. The exit status is zero (success) if the\nfunction was not previously defined _and_ a definition for it was found.\nThis does _not_ replace any existing definition of the function. The\nexit status is nonzero (failure) if the function was already defined or\nwhen no definition was found. In the latter case the function remains\nundefined and marked for autoloading. If ksh-style autoloading is\nenabled, the function created will contain the contents of the file\nplus a call to the function itself appended to it, thus giving normal\nksh autoloading behaviour on the first call to the function.\nIf the `-m` flag is also given each _name_ is treated as a\npattern and all functions already marked for autoload that match the\npattern are loaded.\n\nWith the `-t` flag, turn on execution tracing; with `-T`, turn on\nexecution tracing only for the current function, turning it off on entry\nto any called functions that do not also have tracing enabled.\n\nWith the `-U` flag, alias expansion is suppressed when the function is\nloaded.\n\nWith the `-w` flag, the _name_s are taken as names of files compiled\nwith the `zcompile` builtin, and all functions defined in them are\nmarked for autoloading.\n\nThe flags `-z` and `-k` mark the function to be autoloaded using the\nzsh or ksh style, as if the option `KSH_AUTOLOAD` were unset or were\nset, respectively. The flags override the setting of the option at the\ntime the function is loaded.\n\nNote that the `autoload` command makes no attempt to ensure the\nshell options set during the loading or execution of the file have\nany particular value. For this, the `emulate` command can be used:\n\n emulate zsh -c 'autoload -Uz _func_'\n\narranges that when _func_ is loaded the shell is in native `zsh`\nemulation, and this emulation is also applied when _func_ is run.\n\nSome of the functions of `autoload` are also provided by `functions\n-u` or `functions -U`, but `autoload` is a more comprehensive\ninterface."),
("bg", "Put each specified _job_ in the background,\nor the current job if none is specified."),
("break", "Exit from an enclosing `for`, `while`,\n`until`, `select` or `repeat` loop. If an arithmetic expression _n_\nis specified, then break _n_ levels instead of just one."),
("builtin", "Executes the builtin _name_, with the given _args_."),
("cd", "Change the current directory. In the first form, change the\ncurrent directory to _arg_, or to the value of `$HOME` if\n_arg_ is not specified. If _arg_ is \"-\", change to the\nprevious directory.\n\nOtherwise, if _arg_ begins with a slash, attempt to change to the\ndirectory given by _arg_.\n\nIf _arg_ does not begin with a slash, the behaviour depends on whether\nthe current directory \".\" occurs in the list of directories contained\nin the shell parameter `cdpath`. If it does not, first attempt to change\nto the directory _arg_ under the current directory, and if that fails\nbut `cdpath` is set and contains at least one element attempt to change\nto the directory _arg_ under each component of `cdpath` in turn until\nsuccessful. If \".\" occurs in `cdpath`, then `cdpath` is searched\nstrictly in order so that \".\" is only tried at the appropriate point.\n\nThe order of testing `cdpath` is modified if the option `POSIX_CD`\nis set, as described in the documentation for the option.\n\nIf no directory is found, the option `CDABLE_VARS` is set, and a\nparameter named _arg_ exists whose value begins with a slash, treat its\nvalue as the directory. In that case, the parameter is added to the named\ndirectory hash table.\n\nThe second form of `cd` substitutes the string _new_\nfor the string _old_ in the name of the current directory,\nand tries to change to this new directory.\n\nThe third form of `cd` extracts an entry from the directory\nstack, and changes to that directory. An argument of the form\n``+\"_n_\" identifies a stack entry by counting from the left\nof the list shown by the `dirs` command, starting with zero.\nAn argument of the form ``-\"_n_\" counts from the right.\nIf the `PUSHD_MINUS` option is set, the meanings of \"+\"\nand \"-\" in this context are swapped.\nIf the `POSIX_CD` option is set, this form of `cd` is not recognised\nand will be interpreted as the first form.\n\nIf the `-q` (quiet) option is specified, the hook function `chpwd`\nand the functions in the array `chpwd_functions` are not called.\nThis is useful for calls to `cd` that do not change the environment\nseen by an interactive user.\n\nIf the `-s` option is specified, `cd` refuses to change the current\ndirectory if the given pathname contains symlinks. If the `-P` option\nis given or the `CHASE_LINKS` option is set, symbolic links are resolved\nto their true values. If the `-L` option is given symbolic links are\nretained in the directory (and not resolved) regardless of the state of\nthe `CHASE_LINKS` option."),
("command", "The simple command argument is taken as an external command instead of\na function or builtin and is executed. If the `POSIX_BUILTINS` option\nis set, builtins will also be executed but certain special properties\nof them are suppressed. The `-p` flag causes a default path to be\nsearched instead of that in `$path`. With the `-v` flag, `command`\nis similar to `whence` and with `-V`, it is equivalent to `whence\n-v`.\n\nSee also _Precommand Modifiers_ (zshmisc)."),
("continue", "Resume the next iteration of the enclosing\n`for`, `while`, `until`, `select` or\n`repeat` loop. If an arithmetic expression _n_ is specified, break out of\n_n_-1 loops and resume at the _n_th enclosing loop."),
("dirs", "With no arguments, print the contents of the directory stack.\nDirectories are added to this stack with the `pushd` command,\nand removed with the `cd` or `popd` commands.\nIf arguments are specified, load them onto the directory stack,\nreplacing anything that was there, and push the current directory\nonto the stack.\n\n- **`-c`** âÂÂ\nclear the directory stack.\n\n\n- **`-l`** â print directory names in full instead of using `~` expressions\n(see _Filename Expansion_ (zshexpn)).\n\n\n- **`-p`** âÂÂ\nprint directory entries one per line.\n\n- **`-v`** âÂÂ\nnumber the directories in the stack when printing."),
("disable", "Temporarily disable the _name_d hash table elements or patterns. The default\nis to disable builtin commands. This allows you to use an external\ncommand with the same name as a builtin command. The `-a` option\ncauses `disable` to act on regular or global aliases. The `-s`\noption causes `disable` to act on suffix aliases. The `-f` option causes\n`disable` to act on shell functions. The `-r` options causes\n`disable` to act on reserved words. Without arguments all disabled\nhash table elements from the corresponding hash table are printed.\nWith the `-m` flag the arguments are taken as patterns (which should be\nquoted to prevent them from undergoing filename expansion), and all hash\ntable elements from the corresponding hash table matching these patterns\nare disabled. Disabled objects can be enabled with the `enable`\ncommand.\n\nWith the option `-p`, _name_ ... refer to elements of the\nshell's pattern syntax as described in _Filename Generation_ (zshexpn).\nCertain elements can be disabled separately, as given below.\n\nNote that patterns\nnot allowed by the current settings for the options `EXTENDED_GLOB`,\n`KSH_GLOB` and `SH_GLOB` are never enabled, regardless of the\nsetting here. For example, if `EXTENDED_GLOB` is not active,\nthe pattern `^` is ineffective even if \"disable -p \"^\"\" has\nnot been issued. The list below indicates any option settings\nthat restrict the use of the pattern. It should be noted that\nsetting `SH_GLOB` has a wider effect than merely disabling patterns\nas certain expressions, in particular those involving parentheses,\nare parsed differently.\n\nThe following patterns may be disabled; all\nthe strings need quoting on the command line to prevent them from\nbeing interpreted immediately as patterns and the patterns are\nshown below in single quotes as a reminder.\n\n- **`'?'`** âÂÂ\nThe pattern character `?` wherever it occurs, including when preceding\na parenthesis with `KSH_GLOB`.\n\n- **`'*'`** âÂÂ\nThe pattern character `*` wherever it occurs, including recursive\nglobbing and when preceding a parenthesis with `KSH_GLOB`.\n\n\n- **`[`** â Character classes.\n\n\n- **`'<'` (`NO_SH_GLOB`)** â Numeric ranges.\n\n\n- **`'|'` (`NO_SH_GLOB`)** â Alternation in grouped patterns, case statements, or KSH_GLOB\nparenthesised expressions.\n\n\n- **`(` (`NO_SH_GLOB`)** â Grouping using single parentheses. Disabling this does not disable the\nuse of parentheses for `KSH_GLOB` where they are introduced by a\nspecial character, nor for glob qualifiers (use ``setopt\nNO_BARE_GLOB_QUAL`' to disable glob qualifiers that use parentheses\nonly).\n\n- **`'~'` (`EXTENDED_GLOB`)** â Exclusion in the form _A_`~`_B_.\n\n\n- **`'^'` (`EXTENDED_GLOB`)** â Exclusion in the form _A_`^`_B_.\n\n\n- **`'#'` (`EXTENDED_GLOB`)** â The pattern character `#` wherever it occurs, both for\nrepetition of a previous pattern and for indicating globbing flags.\n\n\n- **`?(` (`KSH_GLOB`)** â The grouping form `?(...)`. Note this is also\ndisabled if `'?'` is disabled.\n\n\n- **`*(` (`KSH_GLOB`)** â The grouping form `*(...)`. Note this is also\ndisabled if `'*'` is disabled.\n\n\n- **`+(` (`KSH_GLOB`)** â The grouping form `+(...)`.\n\n\n- **`!(` (`KSH_GLOB`)** â The grouping form `!(...)`.\n\n\n- **`@(` (`KSH_GLOB`)** â The grouping form `@(...)`.\n"),
("disown", "Remove the specified _job_s from the job table; the shell will\nno longer report their status, and will not complain if you\ntry to exit an interactive shell with them running or stopped.\nIf no _job_ is specified, disown the current job.\n\nIf the _job_s are currently stopped and the `AUTO_CONTINUE` option\nis not set, a warning is printed containing information about how to\nmake them running after they have been disowned. If one of the latter\ntwo forms is used, the _job_s will automatically be made running,\nindependent of the setting of the `AUTO_CONTINUE` option."),
("echo", "Write each _arg_ on the standard output, with a space separating\neach one.\nIf the `-n` flag is not present, print a newline at the end.\n`echo` recognizes the following escape sequences:\n\n- `\\a` â bell character\n- `\\b` â backspace\n- `\\c` â suppress subsequent characters and final newline\n- `\\e` â escape\n- `\\f` â form feed\n\n- **`\\n`** â linefeed (newline)\n\n- `\\r` â carriage return\n- `\\t` â horizontal tab\n- `\\v` â vertical tab\n- `\\\\` â backslash\n- `\\0`_NNN_ â character code in octal\n- `\\x`_NN_ â character code in hexadecimal\n- `\\u`_NNNN_ â unicode character code in hexadecimal\n- `\\U`_NNNNNNNN_ â unicode character code in hexadecimal\n\npindex(BSD_ECHO, use of)\nThe `-E` flag, or the `BSD_ECHO` option, can be used to disable\nthese escape sequences. In the latter case, `-e` flag can be used to\nenable them.\n\nNote that for standards compliance a double dash does not terminate\noption processing; instead, it is printed directly. However, a\nsingle dash does terminate option processing, so the first dash,\npossibly following options, is not printed, but everything following it\nis printed as an argument. The single dash behaviour is different\nfrom other shells. For a more portable way of printing text, see\n`printf`, and for a more controllable way of printing text within zsh,\nsee `print`."),
("emulate", "Without any argument print current emulation mode.\n\nWith single argument set up zsh options to emulate the specified shell\nas much as possible.\n**csh** will never be fully emulated.\nIf the argument is not one of the shells listed above, `zsh`\nwill be used as a default; more precisely, the tests performed on the\nargument are the same as those used to determine the emulation at startup\nbased on the shell name, see _Compatibility_ (zsh).\nIn addition to setting shell options, the command also restores\nthe pristine state of pattern enables, as if all patterns had been\nenabled using `enable -p`.\n\nIf the `emulate` command occurs inside a function that has been\nmarked for execution tracing with `functions -t` then the `xtrace`\noption will be turned on regardless of emulation mode or other options.\nNote that code executed inside the function by the `.`, `source`, or\n`eval` commands is not considered to be running directly from the\nfunction, hence does not provoke this behaviour.\n\nIf the `-R` switch is given, all settable options\nare reset to their default value corresponding to the specified emulation\nmode, except for certain options describing the interactive\nenvironment; otherwise, only those options likely to cause portability\nproblems in scripts and functions are altered. If the `-L` switch is given,\nthe options `LOCAL_OPTIONS`, `LOCAL_PATTERNS` and `LOCAL_TRAPS`\nwill be set as\nwell, causing the effects of the `emulate` command and any `setopt`,\n`disable -p` or `enable -p`, and `trap` commands to be local to\nthe immediately surrounding shell\nfunction, if any; normally these options are turned off in all emulation\nmodes except `ksh`. The `-L` switch is mutually exclusive with the\nuse of `-c` in _flags_.\n\nIf there is a single argument and the `-l` switch is given, the\noptions that would be set or unset (the latter indicated with the prefix\n\"no\") are listed. `-l` can be combined with `-L` or `-R` and\nthe list will be modified in the appropriate way. Note the list does\nnot depend on the current setting of options, i.e. it includes all\noptions that may in principle change, not just those that would actually\nchange.\n\nThe _flags_ may be any of the invocation-time flags described in\n_Invocation_ (zsh),\nexcept that \"-o EMACS\" and \"-o VI\" may not be used.\n\nIf `-c` _arg_ appears in _flags_, _arg_ is evaluated while the\nrequested emulation is temporarily in effect. In this case the emulation\nmode and all options are restored to their previous values before\n`emulate` returns. The `-R` switch may precede the name of the shell\nto emulate; note this has a meaning distinct from including `-R` in\n_flags_.\n\nUse of `-c` enables \"sticky\" emulation mode for functions defined\nwithin the evaluated expression: the emulation mode is associated\nthereafter with the function so that whenever the function is executed\nthe emulation (respecting the `-R` switch, if present) and all\noptions are set (and pattern disables cleared)\nbefore entry to the function, and the state is restored after exit.\nIf the function is called when the sticky emulation is already in\neffect, either within an ``emulate` _shell_ `-c`' expression or\nwithin another function with the same sticky emulation, entry and exit\nfrom the function do not cause options to be altered (except due to\nstandard processing such as the `LOCAL_OPTIONS` option). This also\napplies to functions marked for autoload within the sticky emulation;\nthe appropriate set of options will be applied at the point the\nfunction is loaded as well as when it is run.\n\nFor example:\n\nexample(emulate sh -c 'fni+() { setopt cshnullglob; }\nfno+() { fni; }'\nfno)\n\nThe two functions `fni` and `fno` are defined with sticky `sh`\nemulation. `fno` is then executed, causing options associated\nwith emulations to be set to their values in `sh`. `fno` then\ncalls `fni`; because `fni` is also marked for sticky `sh`\nemulation, no option changes take place on entry to or exit from it.\nHence the option `cshnullglob`, turned off by `sh` emulation, will\nbe turned on within `fni` and remain on return to `fno`. On exit\nfrom `fno`, the emulation mode and all options will be restored to the\nstate they were in before entry to the temporary emulation.\n\nThe documentation above is typically sufficient for the intended\npurpose of executing code designed for other shells in a suitable\nenvironment. More detailed rules follow.\n\n- 1. â The sticky emulation environment provided by ``emulate`\n_shell_ `-c`' is identical to that provided by entry to\na function marked for sticky emulation as a consequence of being\ndefined in such an environment. Hence, for example, the sticky\nemulation is inherited by subfunctions defined within functions\nwith sticky emulation.\n- 2. â No change of options takes place on entry to or exit from\nfunctions that are not marked for sticky emulation, other than those\nthat would normally take place, even if those functions are called\nwithin sticky emulation.\n- 3. â No special handling is provided for functions marked for\n`autoload` nor for functions present in wordcode created by\nthe `zcompile` command.\n- 4. â The presence or absence of the `-R` switch to `emulate`\ncorresponds to different sticky emulation modes, so for example\n\"emulate sh -c\", \"emulate -R sh -c\" and \"emulate csh -c\"\nare treated as three distinct sticky emulations.\n- 5. â Difference in shell options supplied in addition to the\nbasic emulation also mean the sticky emulations are different, so for\nexample \"emulate zsh -c\" and \"emulate zsh -o cbases -c\" are\ntreated as distinct sticky emulations."),
("enable", "Enable the _name_d hash table elements, presumably disabled\nearlier with `disable`. The default is to enable builtin commands.\nThe `-a` option causes `enable` to act on regular or global aliases.\nThe `-s` option causes `enable` to act on suffix aliases.\nThe `-f` option causes `enable` to act on shell functions. The `-r`\noption causes `enable` to act on reserved words. Without arguments\nall enabled hash table elements from the corresponding hash table are\nprinted. With the `-m` flag the arguments are taken as patterns\n(should be quoted) and all hash table elements from the corresponding\nhash table matching these patterns are enabled. Enabled objects can be\ndisabled with the `disable` builtin command.\n\n`enable -p` reenables patterns disabled with `disable -p`. Note\nthat it does not override globbing options; for example, ``enable -p\n\"~\"`' does not cause the pattern character `~` to be active unless\nthe `EXTENDED_GLOB` option is also set. To enable all possible\npatterns (so that they may be individually disabled with `disable -p`),\nuse \"setopt EXTENDED_GLOB KSH_GLOB NO_SH_GLOB\"."),
("eval", "Read the arguments as input to the shell and execute the resulting\ncommand+(s+) in the current shell process. The return status is\nthe same as if the commands had been executed directly by the shell;\nif there are no _args_ or they contain no commands (i.e. are\nan empty string or whitespace) the return status is zero."),
("exec", "Replace the current shell with _command_ rather than forking.\nIf _command_ is a shell builtin command or a shell function,\nthe shell executes it, and exits when the command is complete.\n\nWith `-c` clear the environment; with `-l` prepend `-` to the\n`argv[0]` string of the command executed (to simulate a login shell);\nwith `-a` _argv0_ set the `argv[0]` string of the command\nexecuted.\nSee _Precommand Modifiers_ (zshmisc).\n\nIf the option `POSIX_BUILTINS` is set, _command_ is never\ninterpreted as a shell builtin command or shell function. This\nmeans further precommand modifiers such as `builtin` and\n`noglob` are also not interpreted within the shell. Hence\n_command_ is always found by searching the command path.\n\ncindex(redirection, current shell's I/O)\nIf _command_ is omitted but any redirections are specified,\nthen the redirections will take effect in the current shell."),
("exit", "Exit the shell with the exit status specified by an arithmetic\nexpression _n_; if none\nis specified, use the exit status from the last command executed.\npindex(IGNORE_EOF, use of)\nAn EOF condition will also cause the shell to exit, unless\nthe `IGNORE_EOF` option is set.\n\nSee notes at the end of _Signals_ (zshmisc)\nfor some possibly unexpected interactions\nof the `exit` command with jobs."),
("export", "The specified _name_s are marked for automatic export\nto the environment of subsequently executed commands.\nEquivalent to `typeset -gx`.\nIf a parameter specified does not\nalready exist, it is created in the global scope."),
("false", "Do nothing and return an exit status of 1."),
("fc", "The `fc` command controls the interactive history mechanism. Note\nthat reading and writing of history options is only performed if the\nshell is interactive. Usually this is detected automatically, but\nit can be forced by setting the `interactive` option when starting the\nshell.\n\nThe first two forms of this command select a range of events from\n_first_ to _last_ from the history list. The arguments _first_\nand _last_ may be specified as a number or as a string. A negative\nnumber is used as an offset to the current history event number. A string\nspecifies the most recent event beginning with the given string. All\nsubstitutions _old_`=`_new_, if any, are then performed on the\ntext of the events.\n\nThe range of events selected by numbers can be narrowed further by the\nfollowing flags.\n\n\n- **`-I`** â restricts to only internal events (not from `$HISTFILE`)\n\n\n- **`-L`** â restricts to only local events (not from other shells, see\n`SHARE_HISTORY` in\nnmref(Description of Options)(zshoptions) -- note that `$HISTFILE` is\nconsidered local when read at startup)\n\n\n- **`-m`** â takes the first argument as a pattern (which should be\nquoted) and only the history events matching this pattern are considered\n\n\nIf _first_ is not specified, it will be set to -1 (the most recent\nevent), or to -16 if the `-l` flag is given.\nIf _last_ is not specified, it will be set to _first_,\nor to -1 if the `-l` flag is given.\nHowever, if the current event has added entries to the history with\n\"print -s\" or \"fc -R\", then the default _last_ for `-l`\nincludes all new history entries since the current event began.\n\nWhen the `-l` flag is given, the resulting events are listed on\nstandard output. Otherwise the editor program specified by `-e` _ename_\nis invoked on a file containing these history events. If `-e` is not given, the\nvalue of the parameter `FCEDIT` is used; if that is not set the value of\nthe parameter `EDITOR` is used; if that is not set a builtin default,\nusually \"vi\" is used. If _ename_ is \"-\", no editor is invoked.\nWhen editing is complete, the edited command is executed.\n\nThe flag \"-s\" is equivalent to \"-e -\".\nThe flag `-r` reverses the order of the events and the\nflag `-n` suppresses event numbers when listing.\n\nAlso when listing,\n\n- `-d` â prints timestamps for each event\n- `-f` â prints full time-date stamps in the US\n`_MM_`/`_DD_`/`_YY_ _hh_`:\"_mm_\" format\n- `-E` â prints full time-date stamps in the European\n`_dd_`.`_mm_`.`_yyyy_ _hh_`:\"_mm_\" format\n- `-i` â prints full time-date stamps in ISO8601\n`_yyyy_`-`_mm_`-`_dd_ _hh_`:\"_mm_\" format\n\n- **`-t` _fmt_** â prints time and date stamps in the given format;\n_fmt_ is formatted with the strftime function with the zsh extensions\ndescribed for the `%D{`_string_`}` prompt format in\n_Simple Prompt Escapes_ (zshmisc).\nThe resulting formatted string must be\nno more than 256 characters or will not be printed\n\n- `-D` â prints elapsed times; may be combined with one of the\noptions above\n\ncindex(history, stack)\ncindex(stack, history)\n\"fc -p\" pushes the current history list onto a stack and switches to a\nnew history list. If the `-a` option is also specified, this history list\nwill be automatically popped when the current function scope is exited, which\nis a much better solution than creating a trap function to call \"fc -P\"\nmanually. If no arguments are specified, the history list is left empty,\n`$HISTFILE` is unset, and `$HISTSIZE` & `$SAVEHIST` are set to their\ndefault values. If one argument is given, `$HISTFILE` is set to that\nfilename, `$HISTSIZE` & `$SAVEHIST` are left unchanged, and the history\nfile is read in (if it exists) to initialize the new list. If a second\nargument is specified, `$HISTSIZE` & `$SAVEHIST` are instead set to the\nsingle specified numeric value. Finally, if a third argument is specified,\n`$SAVEHIST` is set to a separate value from `$HISTSIZE`. You are free to\nchange these environment values for the new history list however you desire\nin order to manipulate the new history list.\n\n\"fc -P\" pops the history list back to an older list saved by \"fc -p\".\nThe current list is saved to its `$HISTFILE` before it is destroyed\n(assuming that `$HISTFILE` and `$SAVEHIST` are set appropriately, of\ncourse). The values of `$HISTFILE`, `$HISTSIZE`, and `$SAVEHIST` are\nrestored to the values they had when \"fc -p\" was called. Note that this\nrestoration can conflict with making these variables \"local\", so your best\nbet is to avoid local declarations for these variables in functions that use\n\"fc -p\". The one other guaranteed-safe combination is declaring these\nvariables to be local at the top of your function and using the automatic\noption (`-a`) with \"fc -p\". Finally, note that it is legal to manually\npop a push marked for automatic popping if you need to do so before the\nfunction exits.\n\ncindex(history, file)\ncindex(file, history)\n\"fc -R\" reads the history from the given file,\n\"fc -W\" writes the history out to the given file,\nand \"fc -A\" appends the history out to the given file.\nIf no filename is specified, the `$HISTFILE` is assumed.\nIf the `-I` option is added to `-R`, only those events that are\nnot already contained within the internal history list are added.\nIf the `-I` option is added to `-A` or `-W`, only those\nevents that are new since last incremental append/write to\nthe history file are appended/written.\nIn any case, the created file will have no more than `$SAVEHIST`\nentries."),
("fg", "Bring each specified _job_ in turn to the foreground.\nIf no _job_ is specified, resume the current job."),
("float", "Equivalent to `typeset -E`, except that options irrelevant to floating\npoint numbers are not permitted."),
("functions", "Equivalent to `typeset -f`, with the exception of the `-c`, `-x`,\n`-M` and `-W` options. For `functions -u` and `functions -U`,\nsee `autoload`, which provides additional options. For `functions -t`\nand `functions -T`, see `typeset -f`.\n\nThe `-x` option indicates that any functions output will have\neach leading tab for indentation, added by the shell to show syntactic\nstructure, expanded to the given number _num_ of spaces. _num_\ncan also be 0 to suppress all indentation.\n\nThe `-W` option turns on the option `WARN_NESTED_VAR` for the named\nfunction or functions only. The option is turned off at the start of\nnested functions (apart from anonymous functions) unless the called\nfunction also has the `-W` attribute.\n\nThe `-c` option causes _oldfn_ to be copied to _newfn_. The\ncopy is efficiently handled internally by reference counting. If\n_oldfn_ was marked for autoload it is first loaded and if this\nfails the copy fails. Either function may subsequently be redefined\nwithout affecting the other. A typical idiom is that _oldfn_ is the\nname of a library shell function which is then redefined to call\n`newfn`, thereby installing a modified version of the function.\n\n_The _`-M`_ and _`+M`_ flags_\ncindex(defining mathematical functions)\ncindex(functions, defining mathematical)\n\nUse of the `-M` option may not be combined with any of the options\nhandled by `typeset -f`.\n\n`functions -M` _mathfn_ defines _mathfn_ as the name of\na mathematical function recognised in all forms of arithmetical expressions;\nsee _Arithmetic Evaluation_ (zshmisc).\nBy default _mathfn_ may take\nany number of comma-separated arguments. If _min_ is given,\nit must have exactly _min_ args; if _min_ and _max_ are\nboth given, it must have at least _min_ and at most _max_\nargs. _max_ may be -1 to indicate that there is no upper limit.\n\nBy default the function is implemented by a shell function of the same\nname; if _shellfn_ is specified it gives the name of the corresponding\nshell function while _mathfn_ remains the name used in arithmetical\nexpressions. The name of the function in `$0` is _mathfn_ (not\n_shellfn_ as would usually be the case), provided the option\n`FUNCTION_ARGZERO` is in effect. The positional parameters in the shell\nfunction correspond to the arguments of the mathematical function call.\n\nThe result of the last arithmetical expression evaluated inside the shell\nfunction gives the result of the mathematical function. This is not limited to\narithmetic substitutions of the form tt($+(+()_..._`+`+)),\nbut also includes arithmetical expressions evaluated in any other way, including\nby the `let` builtin,\nby tt(+(+()_..._`+`+)) statements,\nand even\nby the `return` builtin\nand\nby array subscripts.\nTherefore, care must be taken not to use syntactical constructs that perform\narithmetic evaluation after evaluating what is to be the result of the function.\nFor example:\n\nfindex(zmath_cube)\nfindex(cube)\nexample(# WRONG\nzmath_cube+(+) {\n (( $1 * $1 * $1 ))\n return 0\n}\nfunctions -M cube 1 1 zmath_cube\nprint $(( cube+(3+) )))\n\nThis will print \"0\" because of the `return`.\n\nCommenting the `return` out would lead to a different problem: the\ntt(+(+()_..._`+`+)) statement would become\nthe last statement in the function, so the _return status_ (`$?`) of the\nfunction would be non-zero (indicating failure) whenever the _arithmetic\nresult_ of the function would happen to be zero (numerically):\n\nexample(# WRONG\nzmath_cube+(+) {\n (( $1 * $1 * $1 ))\n}\nfunctions -M cube 1 1 zmath_cube\nprint $(( cube+(0+) )))\n\nInstead, the `true` builtin can be used:\n\nexample(# RIGHT\nzmath_cube+(+) {\n (( $1 * $1 * $1 ))\n true\n}\nfunctions -M cube 1 1 zmath_cube\nprint $(( cube+(3+) )))\n\nIf the additional option `-s` is given to `functions -M`, the\nargument to the function is a single string: anything between the\nopening and matching closing parenthesis is passed to the function as a\nsingle argument, even if it includes commas or white space. The minimum\nand maximum argument specifiers must therefore be 1 if given. An empty\nargument list is passed as a zero-length string.\nThus, the following string function takes a single argument, including\nthe commas, and prints 11:\n\nexample(stringfn+() { (( $#1 )); true }\nfunctions -Ms stringfn\nprint $(( stringfn+(foo,bar,rod+) )))\n\n`functions -M` with no arguments lists all such user-defined functions in\nthe same form as a definition. With the additional option `-m` and\na list of arguments, all functions whose _mathfn_ matches one of\nthe pattern arguments are listed.\n\n`function +M` removes the list of mathematical functions; with the\nadditional option `-m` the arguments are treated as patterns and\nall functions whose _mathfn_ matches the pattern are removed. Note\nthat the shell function implementing the behaviour is not removed\n(regardless of whether its name coincides with _mathfn_)."),
("getln", "Read the top value from the buffer stack and put it in\nthe shell parameter _name_. Equivalent to\n`read -zr`."),
("getopts", "Checks the _arg_s for legal options. If the _arg_s are omitted,\nuse the positional parameters. A valid option argument\nbegins with a \"+\" or a \"-\". An argument not beginning with\na \"+\" or a \"-\", or the argument ``-\"-\", ends the options.\nNote that a single \"-\" is not considered a valid option argument.\n_optstring_ contains the letters that `getopts`\nrecognizes. If a letter is followed by a \":\", that option\nrequires an argument. The options can be\nseparated from the argument by blanks.\n\nEach time it is invoked, `getopts` places the option letter it finds\nin the shell parameter _name_, prepended with a \"+\" when\n_arg_ begins with a \"+\". The index of the next _arg_\nis stored in `OPTIND`. The option argument, if any,\nis stored in `OPTARG`.\nvindex(OPTIND, use of)\nvindex(OPTARG, use of)\n\nThe first option to be examined may be changed by explicitly assigning\nto `OPTIND`. `OPTIND` has an initial value of `1`, and is\nnormally set to `1` upon entry to a shell function and restored\nupon exit. (The `POSIX_BUILTINS` option disables this, and also changes\nthe way the value is calculated to match other shells.) `OPTARG`\nis not reset and retains its value from the most recent call to\n`getopts`. If either of `OPTIND` or `OPTARG` is explicitly\nunset, it remains unset, and the index or option argument is not\nstored. The option itself is still stored in _name_ in this case.\n\nA leading \":\" in _optstring_ causes `getopts` to store the\nletter of any invalid option in `OPTARG`, and to set _name_ to\n\"?\" for an unknown option and to \":\" when a required argument is\nmissing. Otherwise, `getopts` sets _name_ to \"?\" and prints\nan error message when an option is invalid. The exit status is\nnonzero when there are no more options."),
("hash", "`hash` can be used to directly modify the contents of the command\nhash table, and the named directory hash table. Normally one would\nmodify these tables by modifying one's `PATH`\n(for the command hash table) or by creating appropriate shell parameters\n(for the named directory hash table).\nThe choice of hash table to work on is determined by the `-d` option;\nwithout the option the command hash table is used, and with the option the\nnamed directory hash table is used.\n\nA command _name_ starting with a `/` or with a relative path\nstarting with `./` or `../` is never executed by lookup in\nthe command hash table, and these can only be added to the table by\nexplicit use of the `hash` command. Such a command is always\nfound by direct look up in the file system.\n\nGiven no arguments, and neither the `-r` or `-f` options,\nthe selected hash table will be listed in full.\n\nThe `-r` option causes the selected hash table to be emptied.\nIt will be subsequently rebuilt in the normal fashion.\nThe `-f` option causes the selected hash table to be fully\nrebuilt immediately. For the command hash table this hashes\nall (and _only_) the absolute directories in the `PATH`,\nand for the named directory hash table this adds all users' home\ndirectories.\nThese two options cannot be used with any arguments.\nBoth options remove any explicitly-added elements.\n\nThe `-m` option causes the arguments to be taken as patterns\n(which should be quoted) and the elements of the hash table\nmatching those patterns are printed. This is the only way to display\na limited selection of hash table elements.\n\nFor each _name_ with a corresponding _value_, put \"_name_\" in\nthe selected hash table, associating it with the pathname \"_value_\".\nIn the command hash table, this means that\nwhenever \"_name_\" is used as a command argument, the shell will try\nto execute the file given by \"_value_\".\nIn the named directory hash table, this means\nthat \"_value_\" may be referred to as ``~\"_name_\".\n\nFor each _name_ with no\ncorresponding _value_, attempt to add _name_ to the hash table,\nchecking what the appropriate `value` is in the normal manner for\nthat hash table. If an appropriate `value\" can\"t be found, then\nthe hash table will be unchanged.\n\nThe `-v` option causes hash table entries to be listed as they are\nadded by explicit specification. If has no effect if used with `-f`.\n\nIf the `-L` flag is present, then each hash table entry is printed in\nthe form of a call to hash."),
("integer", "Equivalent to `typeset -i`, except that options irrelevant to\nintegers are not permitted."),
("jobs", "Lists information about each given job, or all jobs\nif _job_ is omitted. The `-l` flag lists process\nIDs, and the `-p` flag lists process groups.\nIf the `-r` flag is specified only running jobs will be listed\nand if the `-s` flag is given only stopped jobs are shown.\nIf the `-d` flag is given, the directory from which the job was\nstarted (which may not be the current directory of the job) will also\nbe shown.\n\nThe `-Z\" option replaces the shell\"s argument and environment space with\nthe given string, truncated if necessary to fit. This will normally be\nvisible in `ps` (manref(ps)(1)) listings. This feature is typically\nused by daemons, to indicate their state.\n\nFull job control is only available in the top-level interactive shell,\nnot in commands run in the left hand side of pipelines or within\nthe tt(()_..._``) construct. However, a snapshot\nof the job state at that point is taken, so it is still possible\nto use the `jobs` builtin, or any parameter providing job information.\nThis gives information about the state of jobs at the point the subshell\nwas created. If background processes are created within the subshell,\nthen instead information about those processes is provided.\n\nFor example,\n\nexample(sleep 10 & # Job in background\n( # Shell forks\njobs # Shows information about \"sleep 10 &\"\nsleep 5 & # Process in background (no job control)\njobs # Shows information about \"sleep 5 &\"\n))"),
("kill", "Sends either `SIGTERM` or the specified signal to the given\njobs or processes.\nSignals are given by number or by names, with or without the \"SIG\"\nprefix.\nIf the signal being sent is not \"KILL\" or \"CONT\", then the job\nwill be sent a \"CONT\" signal if it is stopped.\nThe argument _job_ can be the process ID of a job\nnot in the job list.\nIn the second form, `kill -l`, if _sig_ is not\nspecified the signal names are listed. Otherwise, for each\n_sig_ that is a name, the corresponding signal number is\nlisted. For each _sig_ that is a signal number or a number\nrepresenting the exit status of a process which was terminated or\nstopped by a signal the name of the signal is printed. The final\nform with `-L` lists each signal name with its corresponding number.\n\nOn some systems, alternative signal names are allowed for a few signals.\nTypical examples are `SIGCHLD` and `SIGCLD` or `SIGPOLL` and\n`SIGIO`, assuming they correspond to the same signal number. `kill\n-l` will only list the preferred form, however `kill -l` _alt_ will\nshow if the alternative form corresponds to a signal number. For example,\nunder Linux `kill -l IO` and `kill -l POLL` both output 29, hence\n`kill -IO` and `kill -POLL` have the same effect.\n\nMany systems will allow process IDs to be negative to kill a process\ngroup or zero to kill the current process group.\n\nThe `-q` option allows an integer value to be sent with the signal\non systems that support tt(sigqueue+())."),
("let", "Evaluate each _arg_ as an arithmetic expression.\nSee _Arithmetic Evaluation_ (zshmisc)\nfor a description of arithmetic expressions. The exit status is 0 if the\nvalue of the last expression is nonzero, 1 if it is zero, and 2 if\nan error occurred."),
("limit", "Set or display resource limits. Unless the `-s` flag is given,\nthe limit applies only the children of the shell. If `-s` is\ngiven without other arguments, the resource limits of the current\nshell is set to the previously set resource limits of the children.\n\nIf _limit_ is not specified, print the current limit placed\non _resource_, otherwise\nset the limit to the specified value. If the `-h` flag\nis given, use hard limits instead of soft limits.\nIf no _resource_ is given, print all limits.\n\nWhen looping over multiple resources, the shell will abort immediately if\nit detects a badly formed argument. However, if it fails to set a limit\nfor some other reason it will continue trying to set the remaining limits.\n\n_resource_ can be one of:\n\n- `addressspace` â Maximum amount of address space used.\n- `aiomemorylocked` â Maximum amount of memory locked in RAM for AIO operations.\n- `aiooperations` â Maximum number of AIO operations.\n- `cachedthreads` â Maximum number of cached threads.\n- `coredumpsize` â Maximum size of a core dump.\n- `cputime` â Maximum CPU seconds per process.\n\n- **`datasize`** â Maximum data size (including stack) for each process.\n\n- `descriptors` â Maximum value for a file descriptor.\n- `filesize` â Largest single file allowed.\n- `kqueues` â Maximum number of kqueues allocated.\n- `maxfilelocks` â Maximum number of file locks.\n- `maxproc` â Maximum number of processes.\n- `maxpthreads` â Maximum number of threads per process.\n- `memorylocked` â Maximum amount of memory locked in RAM.\n- `memoryuse` â Maximum resident set size.\n- `msgqueue` â Maximum number of bytes in POSIX message queues.\n- `nice` â Maximum nice value.\n- `pipebuf` â Maximum size of buffers for pipes/fifos.\n- `posixlocks` â Maximum number of POSIX locks per user.\n- `pseudoterminals` â Maximum number of pseudo-terminals.\n- `resident` â Maximum resident set size.\n- `rt_priority` â Maximum real-time priority.\n- `rt_time` â Maximum CPU time without a blocking system call.\n- `sigpending` â Maximum number of pending signals.\n- `sockbufsize` â Maximum size of all socket buffers.\n- `stacksize` â Maximum stack size for each process.\n- `swapsize` â Maximum amount of swap used.\n- `umtxp` â Maximum number of POSIX thread library objects.\n- `vmemorysize` â Maximum amount of virtual memory.\n- `vnodemonitors` â Maximum number of open vnode monitors.\n\nWhich of these resource limits are available depends on the system.\n_resource_ can be abbreviated to any unambiguous prefix. It\ncan also be an integer, which corresponds to the integer defined\nfor the resource by the operating system.\n\nIf argument corresponds to a number which is out of the range of the\nresources configured into the shell, the shell will try to read or write\nthe limit anyway, and will report an error if this fails. As the shell\ndoes not store such resources internally, an attempt to set the limit will\nfail unless the `-s` option is present.\n\n_limit_ is a number, with an optional scaling factor, as follows:\n\n- _n_`h` â hours\n\n- **_n_`k`** â kilobytes (default)\n\n- _n_`m` â megabytes or minutes\n- _n_`g` â gigabytes\n- [_mm_`:`]_ss_ â minutes and seconds\n\nThe `limit` command is not made available by default when the\nshell starts in a mode emulating another shell. It can be made available\nwith the command \"zmodload -F zsh/rlimits b:limit\"."),
("local", "Same as `typeset`, except that the options `-g`, and\n`-f` are not permitted. In this case the `-x` option does not force\nthe use of `-g`, i.e. exported variables will be local to functions."),
("logout", "Same as `exit`, except that it only works in a login shell."),
("popd", "Remove an entry from the directory stack, and perform a `cd` to\nthe new top directory. With no argument, the current top entry is\nremoved. An argument of the form ``+\"_n_\" identifies a stack\nentry by counting from the left of the list shown by the `dirs` command,\nstarting with zero. An argument of the form `-`_n_ counts from the right.\npindex(PUSHD_MINUS, use of)\nIf the `PUSHD_MINUS` option is set, the meanings of \"+\" and\n\"-\" in this context are swapped.\n\nIf the `-q` (quiet) option is specified, the hook function `chpwd`\nand the functions in the array `$chpwd_functions` are not called,\nand the new directory stack is not printed. This is useful for calls to\n`popd` that do not change the environment seen by an interactive user."),
("print", "With the \"-f\" option the arguments are printed as described by `printf`.\nWith no flags or with the flag \"-\", the arguments are printed on\nthe standard output as described by `echo`, with the following differences:\nthe escape sequence ``\\M-\"_x_\" (or ``\\M\"_x_\") metafies the character\n_x_ (sets the highest bit),\n``\\C-\"_x_\" (or ``\\C\"_x_\") produces a control character\n(\"\\C-@\" and \"\\C-?\" give the characters NULL and delete),\na character code in octal is represented by ``\\\"_NNN_\"\n(instead of ``\\0\"_NNN_\"),\nand \"\\E\" is a synonym for \"\\e\".\nFinally, if not in an escape\nsequence, \"\\\" escapes the following character and is not printed.\n\n- **`-a`** âÂÂ\nPrint arguments with the column incrementing first. Only useful with the\n`-c` and `-C` options.\n\n\n- **`-b`** â Recognize all the escape sequences defined for the `bindkey` command,\nsee _Zle Builtins_ (zshzle).\n\n\n- **`-c`** âÂÂ\nPrint the arguments in columns. Unless `-a` is also given, arguments are\nprinted with the row incrementing first.\n\n- **`-C` _cols_** âÂÂ\nPrint the arguments in _cols_ columns. Unless `-a` is also given,\narguments are printed with the row incrementing first.\n\n- **`-D`** âÂÂ\nTreat the arguments as paths, replacing directory prefixes with `~`\nexpressions corresponding to directory names, as appropriate.\n\n- **`-i`** âÂÂ\nIf given together with `-o` or `-O`, sorting is performed\ncase-independently.\n\n- **`-l`** âÂÂ\nPrint the arguments separated by newlines instead of spaces. Note: if\nthe list of arguments is empty, `print -l` will still output one empty\nline. To print a possibly-empty list of arguments one per line, use\n`print -C1`, as in \"print -rC1 -- \"$list[@]\"\".\n\n\n- **`-m`** â Take the first argument as a pattern (should be quoted), and remove\nit from the argument list together with subsequent arguments that\ndo not match this pattern.\n\n\n- **`-n`** âÂÂ\nDo not add a newline to the output.\n\n- **`-N`** âÂÂ\nPrint the arguments separated and terminated by nulls. Again,\n`print -rNC1 -- \"$list[@]\"` is a canonical way to print an\narbitrary list as null-delimited records.\n\n- **`-o`** âÂÂ\nPrint the arguments sorted in ascending order.\n\n- **`-O`** âÂÂ\nPrint the arguments sorted in descending order.\n\n- **`-p`** âÂÂ\nPrint the arguments to the input of the coprocess.\n\n\n- **`-P`** â Perform prompt expansion (see\n_Expansion of Prompt Sequences_ (zshmisc)).\nIn combination with \"-f\",\nprompt escape sequences are parsed only within interpolated arguments,\nnot within the format string.\n\n\n- **`-r`** âÂÂ\nIgnore the escape conventions of `echo`.\n\n- **`-R`** âÂÂ\nEmulate the BSD `echo` command, which does not process escape sequences\nunless the `-e` flag is given. The `-n` flag suppresses the trailing\nnewline. Only the `-e` and `-n` flags are recognized after\n`-R`; all other arguments and options are printed.\n\n- **`-s`** âÂÂ\nPlace the results in the history list instead of on the standard output.\nEach argument to the `print` command is treated as a single word in the\nhistory, regardless of its content.\n\n- **`-S`** âÂÂ\nPlace the results in the history list instead of on the standard output.\nIn this case only a single argument is allowed; it will be split into\nwords as if it were a full shell command line. The effect is\nsimilar to reading the line from a history file with the\n`HIST_LEX_WORDS` option active.\n\n- **`-u` _n_** âÂÂ\nPrint the arguments to file descriptor _n_.\n\n- **`-v` _name_** âÂÂ\nStore the printed arguments as the value of the parameter _name_.\n\n\n- **`-x` _tab-stop_** â Expand leading tabs on each line of output in the printed string\nassuming a tab stop every _tab-stop_ characters. This is appropriate\nfor formatting code that may be indented with tabs. Note that leading\ntabs of any argument to print, not just the first, are expanded, even if\n`print` is using spaces to separate arguments (the column count\nis maintained across arguments but may be incorrect on output\nowing to previous unexpanded tabs).\n\nThe start of the output of each print command is assumed to be aligned\nwith a tab stop. Widths of multibyte characters are handled if the\noption `MULTIBYTE` is in effect. This option is ignored if other\nformatting options are in effect, namely column alignment or\n`printf` style, or if output is to a special location such as shell\nhistory or the command line editor.\n\n\n- **`-X` _tab-stop_** âÂÂ\nThis is similar to `-x`, except that all tabs in the printed string\nare expanded. This is appropriate if tabs in the arguments are\nbeing used to produce a table format.\n\n- **`-z`** âÂÂ\nPush the arguments onto the editing buffer stack, separated by spaces.\n\nIf any of \"-m\", \"-o\" or \"-O\" are used in combination with\n\"-f\" and there are no arguments (after the removal process in the\ncase of \"-m\") then nothing is printed."),
("printf", "Print the arguments according to the format specification. Formatting\nrules are the same as used in C. The same escape sequences as for `echo`\nare recognised in the format. All C conversion specifications ending in\none of `csdiouxXeEfgGn` are handled. In addition to this, \"%b\" can be\nused instead of \"%s\" to cause escape sequences in the argument to be\nrecognised and \"%q\" can be used to quote the argument in such a way\nthat allows it to be reused as shell input. With the numeric format\nspecifiers, if the corresponding argument starts with a quote character,\nthe numeric value of the following character is used as the number to\nprint; otherwise the argument is evaluated as an arithmetic expression. See\n_Arithmetic Evaluation_ (zshmisc) for a description of arithmetic\nexpressions. With \"%n\", the corresponding argument is taken as an\nidentifier which is created as an integer parameter.\n\nNormally, conversion specifications are applied to each argument in order\nbut they can explicitly specify the _n_th argument is to be used by\nreplacing \"%\" by ``%`_n_`$`' and \"*\" by ``*`_n_`$`'.\nIt is recommended that you do not mix references of this explicit style\nwith the normal style and the handling of such mixed styles may be subject\nto future change.\n\nIf arguments remain unused after formatting, the format string is reused\nuntil all arguments have been consumed. With the `print` builtin, this\ncan be suppressed by using the `-r` option. If more arguments are\nrequired by the format than have been specified, the behaviour is as if\nzero or an empty string had been specified as the argument.\n\nThe `-v` option causes the output to be stored as the value of the\nparameter _name_, instead of printed. If _name_ is an array and\nthe format string is reused when consuming arguments then one\narray element will be used for each use of the format string."),
("pushd", "Change the current directory, and push the old current directory\nonto the directory stack. In the first form, change the\ncurrent directory to _arg_.\nIf _arg_ is not specified, change to the second directory\non the stack (that is, exchange the top two entries), or\nchange to `$HOME` if the `PUSHD_TO_HOME`\noption is set or if there is only one entry on the stack.\nOtherwise, _arg_ is interpreted as it would be by `cd`.\nThe meaning of _old_ and _new_ in the second form is also\nthe same as for `cd`.\n\nThe third form of `pushd` changes directory by rotating the\ndirectory list. An argument of the form ``+\"_n_\" identifies a stack\nentry by counting from the left of the list shown by the `dirs`\ncommand, starting with zero. An argument of the form ``-\"_n_\" counts\nfrom the right. If the `PUSHD_MINUS` option is set, the meanings\nof \"+\" and \"-\" in this context are swapped.\n\nIf the `-q` (quiet) option is specified, the hook function `chpwd`\nand the functions in the array `$chpwd_functions` are not called,\nand the new directory stack is not printed. This is useful for calls to\n`pushd` that do not change the environment seen by an interactive user.\n\nIf the option `-q` is not specified and the shell option `PUSHD_SILENT`\nis not set, the directory stack will be printed after a `pushd` is\nperformed.\n\nThe options `-s`, `-L` and `-P` have the same meanings as for the\n`cd` builtin."),
("pushln", "Equivalent to `print -nz`."),
("pwd", "Print the absolute pathname of the current working directory.\nIf the `-r` or the `-P` flag is specified, or the `CHASE_LINKS`\noption is set and the `-L` flag is not given, the printed path will not\ncontain symbolic links."),
("read", "vindex(REPLY, use of)\nvindex(reply, use of)\nRead one line and break it into fields using the characters\nin `$IFS` as separators, except as noted below.\nThe first field is assigned to the first _name_, the second field\nto the second _name_, etc., with leftover\nfields assigned to the last _name_.\nIf _name_ is omitted then\n`REPLY` is used for scalars and `reply` for arrays.\n\n- **`-r`** âÂÂ\nRaw mode: a \"\\\" at the end of a line does not signify line\ncontinuation and backslashes in the line don't quote the following\ncharacter and are not removed.\n\n- **`-s`** âÂÂ\nDon't echo back characters if reading from the terminal.\n\n\n- **`-q`** â Read only one character from the terminal and set _name_ to\n\"y\" if this character was \"y\" or \"Y\" and to \"n\" otherwise.\nWith this flag set the return status is zero only if the character was\n\"y\" or \"Y\". This option may be used with a timeout (see `-t`); if\nthe read times out, or encounters end of file, status 2 is returned. Input is\nread from the terminal unless one of `-u` or `-p` is present. This option\nmay also be used within zle widgets.\n\n\n- **`-k` [ _num_ ]** â Read only one (or _num_) characters. All are assigned to the first\n_name_, without word splitting. This flag is ignored when `-q` is\npresent. Input is read from the terminal unless one of `-u` or `-p`\nis present. This option may also be used within zle widgets.\n\nNote that despite the mnemonic \"key\" this option does read full\ncharacters, which may consist of multiple bytes if the option\n`MULTIBYTE` is set.\n\n\n- **`-z`** â Read one entry from the editor buffer stack and assign it to the first\n_name_, without word splitting. Text is pushed onto the stack with\n\"print -z\" or with `push-line` from the line editor (see\nnmref(Zsh Line Editor)(zshzle)).\nThis flag is ignored when the `-k` or `-q` flags are present.\n\n\n- **`-e`**\n\n\n- **`-E`** â The input read is printed (echoed) to the standard output. If the `-e`\nflag is used, no input is assigned to the parameters.\n\n\n- **`-A`** âÂÂ\nThe first _name_ is taken as the name of an array and all words are\nassigned to it.\n\n- **`-c`**\n\n\n- **`-l`** â These flags are allowed only if called inside a\nfunction used for completion (specified with the `-K` flag to\n`compctl`). If the `-c` flag is given, the words of the\ncurrent command are read. If the `-l` flag is given, the whole\nline is assigned as a scalar. If both flags are present, `-l`\nis used and `-c` is ignored.\n\n\n- **`-n`** âÂÂ\nTogether with `-c`, the number of the word the cursor is on is\nread. With `-l`, the index of the character the cursor is on is\nread. Note that the command name is word number 1, not word 0,\nand that when the cursor is at the end of the line, its character\nindex is the length of the line plus one.\n\n- **`-u` _n_** âÂÂ\nInput is read from file descriptor _n_.\n\n- **`-p`** âÂÂ\nInput is read from the coprocess.\n\n- **`-d` _delim_** âÂÂ\nInput is terminated by the first character of _delim_ instead of\nby newline. For compatibility with other shells, if _delim_ is an\nempty string, input is terminated at the first NUL.\n\n\n- **`-t` [ _num_ ]** â Test if input is available before attempting to read. If _num_\nis present, it must begin with a digit and will be evaluated\nto give a number of seconds, which may be a floating point number;\nin this case the read times out if input is not available within this\ntime. If _num_ is not present, it is taken to be zero, so that\n`read` returns immediately if no input is available.\nIf no input is available, return status 1 and do not set any variables.\nifzman( )\nThis option is not available when reading from the editor buffer with\n`-z`, when called from within completion with `-c` or `-l`, with\n`-q` which clears the input queue before reading, or within zle where\nother mechanisms should be used to test for input.\nifzman( )\nNote that read does not attempt to alter the input processing mode. The\ndefault mode is canonical input, in which an entire line is read at a time,\nso usually \"read -t\" will not read anything until an entire line has\nbeen typed. However, when reading from the terminal with `-k`\ninput is processed one key at a time; in this case, only availability of\nthe first character is tested, so that e.g. \"read -t -k 2\" can still\nblock on the second character. Use two instances of \"read -t -k\" if\nthis is not what is wanted.\n\n\nIf the first argument contains a \"?\", the remainder of this\nword is used as a _prompt_ on standard error when the shell\nis interactive.\n\nThe value (exit status) of `read` is 1 when an end-of-file is\nencountered, or when `-c` or `-l` is present and the command is\nnot called from a `compctl` function, or as described for `-q`.\nOtherwise the value is 0.\n\nThe behavior of some combinations of the `-k`, `-p`, `-q`, `-u`\nand `-z` flags is undefined. Presently `-q` cancels all the others,\n`-p` cancels `-u`, `-k` cancels `-z`, and otherwise `-z`\ncancels both `-p` and `-u`.\n\nThe `-c` or `-l` flags cancel any and all of `-kpquz`."),
("readonly", "Same as `typeset -r`. With the `POSIX_BUILTINS` option set, same\nas `typeset -gr`."),
("return", "Causes a shell function or \".\" script to return to\nthe invoking script with the return status specified by\nan arithmetic expression _n_. Also causes a non-interactive\nshell to exit, allowing files containing shell code to be used\nboth as scripts and as autoloadable shell functions.\nFor example, the following prints \"42\":\n\nexample(() { integer foo=40; return \"foo + 2\" }\necho $?)\n\nIf _n_\nis omitted, the return status is that of the last command\nexecuted.\n\nIf `return` was executed from a trap in a `TRAP`_NAL_ function,\nthe effect is different for zero and non-zero return status. With zero\nstatus (or after an implicit return at the end of the trap), the shell\nwill return to whatever it was previously processing; with a non-zero\nstatus, the shell will behave as interrupted except that the return\nstatus of the trap is retained. Note that the numeric value of the signal\nwhich caused the trap is passed as the first argument, so the statement\n\"return \"128+$1\"\" will return the same status as if the signal\nhad not been trapped."),
("set", "Set the options for the shell and/or set the positional parameters, or\ndeclare and set an array. If the `-s` option is given, it causes the\nspecified arguments to be sorted before assigning them to the positional\nparameters (or to the array _name_ if `-A` is used). With `+s`\nsort arguments in descending order. For the meaning of the other flags, see\nnmref(Options)(zshoptions).\nFlags may be specified by name using the `-o` option. If no option\nname is supplied with `-o`, the current option states are printed: see\nthe description of `setopt` below for more information on the format.\nWith `+o` they are printed in a form that can be used as input\nto the shell.\n\nIf the `-A` flag is specified, _name_ is set to an array containing\nthe given _arg_s; if no _name_ is specified, all arrays are printed\ntogether with their values.\n\nIf `+A` is used and _name_ is an array, the\ngiven arguments will replace the initial elements of that array; if no\n_name_ is specified, all arrays are printed without their values.\n\nThe behaviour of arguments after `-A` _name_ or `+A` _name_\ndepends on whether the option `KSH_ARRAYS` is set. If it is not set, all\narguments following _name_ are treated as values for the array,\nregardless of their form. If the option is set, normal option processing\ncontinues at that point; only regular arguments are treated as values for\nthe array. This means that\n\n set -A array -x -- foo\n\nsets `array` to ``-x -\"- foo\" if `KSH_ARRAYS` is not set, but sets\nthe array to `foo` and turns on the option \"-x\" if it is set.\n\nIf the `-A` flag is not present, but there are arguments beyond the\noptions, the positional parameters are set. If the option list (if any)\nis terminated by ``-\"-\", and there are no further arguments, the\npositional parameters will be unset.\n\nIf no arguments and no ``-\"-\" are given, then the names and values of\nall parameters are printed on the standard output. If the only argument is\n\"+\", the names of all parameters are printed.\n\nFor historical reasons, \"set -\" is treated as \"set +xv\"\nand ``set -\" _args_\" as ``set +xv --\" _args_\" when in\nany other emulation mode than zsh's native mode."),
("setopt", "Set the options for the shell. All options specified either\nwith flags or by name are set.\n\nIf no arguments are supplied, the names of all options currently set are\nprinted. The form is chosen so as to minimize the differences from the\ndefault options for the current emulation (the default emulation being\nnative `zsh`, shown as `<Z>` in\n_Description of Options_ (zshoptions)).\nOptions that are on by default for the emulation are\nshown with the prefix `no` only if they are off, while other options are\nshown without the prefix `no` and only if they are on. In addition to\noptions changed from the default state by the user, any options activated\nautomatically by the shell (for example, `SHIN_STDIN` or `INTERACTIVE`)\nwill be shown in the list. The format is further modified by the option\n`KSH_OPTION_PRINT`, however the rationale for choosing options with\nor without the `no` prefix remains the same in this case.\n\nIf the `-m` flag is given the arguments are taken as patterns\n(which should be quoted to protect them from filename expansion), and all\noptions with names matching these patterns are set.\n\nNote that a bad option name does not cause execution of subsequent shell\ncode to be aborted; this is behaviour is different from that of ``set\n-o`'. This is because `set` is regarded as a special builtin by the\nPOSIX standard, but `setopt` is not."),
("shift", "The positional parameters `${`_n_+1tt(}) ... are renamed\nto `$1` ..., where _n_ is an arithmetic expression that\ndefaults to 1.\nIf any _name_s are given then the arrays with these names are\nshifted instead of the positional parameters.\n\nIf the option `-p` is given arguments are instead removed (popped)\nfrom the end rather than the start of the array."),
("source", "Same as \".\", except that the current directory is always searched and\nis always searched first, before directories in `$path`."),
("suspend", "Suspend the execution of the shell (send it a `SIGTSTP`)\nuntil it receives a `SIGCONT`.\nUnless the `-f` option is given, this will refuse to suspend a login shell."),
("test", "Like the system version of `test`. Added for compatibility;\nuse conditional expressions instead (see\n_Conditional Expressions_ (zshmisc)).\nThe main differences between the conditional expression syntax and the\n`test` and `[` builtins are: these commands are not handled\nsyntactically, so for example an empty variable expansion may cause an\nargument to be omitted; syntax errors cause status 2 to be returned instead\nof a shell error; and arithmetic operators expect integer arguments rather\nthan arithmetic expressions.\n\nThe command attempts to implement POSIX and its extensions where these\nare specified. Unfortunately there are intrinsic ambiguities in\nthe syntax; in particular there is no distinction between test operators\nand strings that resemble them. The standard attempts to resolve these\nfor small numbers of arguments (up to four); for five or more arguments\ncompatibility cannot be relied on. Users are urged wherever possible to\nuse the \"[[\" test syntax which does not have these ambiguities."),
("times", "Print the accumulated user and system times for the shell\nand for processes run from the shell."),
("trap", "_arg_ is a series of commands (usually quoted to protect it from\nimmediate evaluation by the shell) to be read and executed when the shell\nreceives any of the signals specified by one or more _sig_ args.\nEach _sig_ can be given as a number,\nor as the name of a signal either with or without the string `SIG`\nin front (e.g. 1, HUP, and SIGHUP are all the same signal).\n\nIf _arg_ is \"-\", then the specified signals are reset to their\ndefaults, or, if no _sig_ args are present, all traps are reset.\n\nIf _arg_ is an empty string, then the specified signals\nare ignored by the shell (and by the commands it invokes).\n\nIf _arg_ is omitted but one or more _sig_ args are provided (i.e.\nthe first argument is a valid signal number or name), the effect is the\nsame as if _arg_ had been specified as \"-\".\n\nThe `trap` command with no arguments prints a list of commands\nassociated with each signal.\n\nIf _sig_ is `ZERR` then _arg_ will be executed\nafter each command with a nonzero exit status. `ERR` is an alias\nfor `ZERR` on systems that have no `SIGERR` signal (this is the\nusual case).\n\nIf _sig_ is `DEBUG` then _arg_ will be executed\nbefore each command if the option `DEBUG_BEFORE_CMD` is set\n(as it is by default), else after each command. Here, a \"command\" is\nwhat is described as a \"sublist\" in the shell grammar, see\n_Simple Commands & Pipelines_ (zshmisc).\nIf `DEBUG_BEFORE_CMD` is set various additional features are available.\nFirst, it is possible to skip the next command by setting the option\n`ERR_EXIT`; see the description of the `ERR_EXIT` option in\nnmref(Description of Options)(zshoptions). Also, the shell parameter\n`ZSH_DEBUG_CMD` is set to the string corresponding to the command\nto be executed following the trap. Note that this string is reconstructed\nfrom the internal format and may not be formatted the same way as the\noriginal text. The parameter is unset after the trap is executed.\n\nIf _sig_ is `0` or `EXIT`\nand the `trap` statement is executed inside the body of a function,\nthen the command _arg_ is executed after the function completes.\nThe value of `$?` at the start of execution is the exit status of the\nshell or the return status of the function exiting.\nIf _sig_ is `0` or `EXIT`\nand the `trap` statement is not executed inside the body of a function,\nthen the command _arg_ is executed when the shell terminates; the\ntrap runs before any `zshexit` hook functions.\n\n`ZERR`, `DEBUG`, and `EXIT` traps are not executed inside other\ntraps. `ZERR` and `DEBUG` traps are kept within subshells, while\nother traps are reset.\n\nNote that traps defined with the `trap` builtin are slightly different\nfrom those defined as ``TRAP\"_NAL_ () { ... }\", as the latter have\ntheir own function environment (line numbers, local variables, etc.) while\nthe former use the environment of the command in which they were called.\nFor example,\n\n trap 'print $LINENO' DEBUG\n\nwill print the line number of a command executed after it has run, while\n\nexample(TRAPDEBUG+() { print $LINENO; })\n\nwill always print the number zero.\n\nAlternative signal names are allowed as described under `kill` above.\nDefining a trap under either name causes any trap under an alternative\nname to be removed. However, it is recommended that for consistency\nusers stick exclusively to one name or another."),
("true", "Do nothing and return an exit status of 0."),
("ttyctl", "The `-f` option freezes the tty (i.e. terminal or terminal emulator), and\n`-u` unfreezes it.\nWhen the tty is frozen, no changes made to the tty settings by\nexternal programs will be honored by the shell, except for changes in the\nsize of the screen; the shell will\nsimply reset the settings to their previous values as soon as each\ncommand exits or is suspended. Thus, `stty` and similar programs have\nno effect when the tty is frozen. Freezing the tty does not cause\nthe current state to be remembered: instead, it causes future changes\nto the state to be blocked.\n\nWithout options it reports whether the terminal is frozen or not.\n\nNote that, regardless of whether the tty is frozen or not, the\nshell needs to change the settings when the line editor starts, so\nunfreezing the tty does not guarantee settings made on the\ncommand line are preserved. Strings of commands run between\nediting the command line will see a consistent tty state.\nSee also the shell variable `STTY` for a means of initialising\nthe tty before running external commands and/or freezing the tty\naround a single command."),
("type", "Equivalent to `whence -v`."),
("typeset", "Set or display attributes and values for shell parameters.\n\nExcept as noted below for control flags that change the behavior,\na parameter is created for each _name_ that does not already refer\nto one. When inside a function, a new parameter is created for every\n_name_ (even those that already exist), and is unset again when the\nfunction completes. See _Local Parameters_ (zshparam).\nThe same rules apply to special shell parameters, which\nretain their special attributes when made local.\n\nFor each _name_`=`_value_ assignment, the parameter\n_name_ is set to _value_. If the assignment is omitted and _name_\ndoes _not_ refer to an existing parameter, a new parameter is initialized\nto empty string, zero, or empty array (as appropriate), _unless_ the\nshell option `TYPESET_TO_UNSET` is set. When that option is set,\nthe parameter attributes are recorded but the parameter remains unset.\n\nIf the shell option `TYPESET_SILENT` is not set, for each remaining\n_name_ that refers to a parameter that is already set, the name and\nvalue of the parameter are printed in the form of an assignment.\nNothing is printed for newly-created parameters, or when any attribute\nflags listed below are given along with the _name_. Using\n\"+\" instead of minus to introduce an attribute turns it off.\n\nIf no _name_ is present, the names and values of all parameters are\nprinted. In this case the attribute flags restrict the display to only\nthose parameters that have the specified attributes, and using \"+\"\nrather than \"-\" to introduce the flag suppresses printing of the values\nof parameters when there is no parameter name.\n\nAll forms of the command handle scalar assignment. Array assignment is\npossible if any of the reserved words `declare`, `export`, `float`,\n`integer`, `local`, `readonly` or `typeset` is matched when the\nline is parsed (N.B. not when it is executed). In this case the arguments\nare parsed as assignments, except that the \"+=\" syntax and the\n`GLOB_ASSIGN` option are not supported, and scalar values after `=`\nare _not_ split further into words, even if expanded (regardless of the\nsetting of the `KSH_TYPESET` option; this option is obsolete).\n\nExamples of the differences between command and reserved word parsing:\n\nexample(# Reserved word parsing\ntypeset svar=$(echo one word) avar=(several words))\n\nThe above creates a scalar parameter `svar` and an array\nparameter `avar` as if the assignments had been\n\nexample(svar=\"one word\"\navar=(several words))\n\nOn the other hand:\n\nexample(# Normal builtin interface\nbuiltin typeset svar=$(echo two words))\n\nThe `builtin` keyword causes the above to use the standard builtin\ninterface to `typeset` in which argument parsing is performed in the same\nway as for other commands. This example creates a scalar `svar`\ncontaining the value `two` and another scalar parameter `words` with\nno value. An array value in this case would either cause an error or be\ntreated as an obscure set of glob qualifiers.\n\nArbitrary arguments are allowed if they take the form of assignments\nafter command line expansion; however, these only perform scalar\nassignment:\n\n var='svar=val'\ntypeset $var\n\nThe above sets the scalar parameter `svar` to the value `val`.\nParentheses around the value within `var` would not cause array\nassignment as they will be treated as ordinary characters when `$var`\nis substituted. Any non-trivial expansion in the name part of the\nassignment causes the argument to be treated in this fashion:\n\n typeset {var1,var2,var3}=name\n\nThe above syntax is valid, and has the expected effect of setting the\nthree parameters to the same value, but the command line is parsed as\na set of three normal command line arguments to `typeset` after\nexpansion. Hence it is not possible to assign to multiple arrays by\nthis means.\n\nNote that each interface to any of the commands may be disabled\nseparately. For example, \"disable -r typeset\" disables the reserved\nword interface to `typeset`, exposing the builtin interface, while\n\"disable typeset\" disables the builtin. Note that disabling the\nreserved word interface for `typeset` may cause problems with the\noutput of \"typeset -p\", which assumes the reserved word interface is\navailable in order to restore array and associative array values.\n\nUnlike parameter assignment statements, `typeset`'s exit status on an\nassignment that involves a command substitution does not reflect the exit\nstatus of the command substitution. Therefore, to test for an error in\na command substitution, separate the declaration of the parameter from its\ninitialization:\n\nexample(# WRONG\ntypeset var1=$(exit 1) || echo \"Trouble with var1\"\n\n# RIGHT\ntypeset var1 && var1=$(exit 1) || echo \"Trouble with var1\"\n)\n\nTo initialize a parameter _param_ to a command output and mark it readonly,\nuse `typeset -r `_param_ or `readonly `_param_ after the parameter\nassignment statement.\n\ncindex(named reference)\ncindex(reference, named)\nThe flag `-n` creates a _named reference_ to another parameter.\nThe second parameter need not exist at the time the reference is\ncreated. Only the `-H`, `-g`, and `-r` flags may be used in\nconjunction with `-n`, having their usual meanings. The `-u`\nflag is special and may be applied to alter the scope of the reference.\nThe _name_ so created may not be an array element nor use\na subscript, but the _value_ assigned may be any valid parameter\nname syntax, even a subscripted array element (including an associative\narray element) or an array slice, which is evaluated when the named\nreference is expanded. It is an error for a named reference to refer\nto itself, even indirectly through a chain of references. When `-u`\nis applied to a named reference, the parameter identified by _value_\nis always found in the calling function scope rather than the current\nlocal scope. In this case, if there is no such parameter in the calling\nscope, assignments to the named reference may fail, setting `$?` to 1.\nSee _Parameter Expansion_ (zshexpn) and\n_Named References_ (zshparam) for details of the\nbehavior of named references.\n\nLocal function scoping rules for \"typeset\" do apply with \"-n\",\nso a declaration within a function persists only until the end of the\nfunction unless \"-g -n\" is specified, and any local parameter (of\nany type) with the same _name_ supplants a named reference from a\nsurrounding scope.\n\nA scalar parameter, including an existing named reference, may be\nconverted to a new named reference by ``typeset -n \"_name_\", so\nthe \"-p\" option must be included to display the value of a\nspecific named reference _name_.\n\nIf no attribute flags are given, and either no _name_ arguments are\npresent or the flag `+m` is used, then each parameter name printed is\npreceded by a list of the attributes of that parameter (`array`,\n`association`, `exported`, `float`, `integer`, `readonly`,\nor `undefined` for autoloaded parameters not yet loaded). If `+m` is\nused with attribute flags, and all those flags are introduced with\n`+`, the matching parameter names are printed but their values\nare not.\n\nThe following control flags change the behavior of `typeset`:\n\n\n- **`+`** â If \"+\" appears by itself in a separate word as the last option,\nthen the names of all parameters (functions with `-f`) are printed, but\nthe values (function bodies) are not. If _name_ arguments appear,\nboth those names and their values are printed in the form of assignments.\nIt is an error for any other options to follow \"+\", but the\neffect of \"+\" is as if all attribute flags which precede it were\ngiven with a \"+\" prefix. For example, \"typeset -U +\" is\nequivalent to \"typeset +U\" and displays the names of all arrays having\nthe uniqueness attribute, whereas \"typeset -f -U +\" displays the\nnames of all autoloadable functions. If `+` is the only option,\nthen type information (array, readonly, etc.) is also printed for each\nparameter, in the same manner as \"typeset +m \"*\"\".\n\n\n- **`-g`** â The `-g` (global) means that any resulting parameter will not be\nrestricted to local scope. Note that this does not necessarily mean that\nthe parameter will be global, as the flag will apply to any existing\nparameter (even if unset) from an enclosing function. This flag does not\naffect the parameter after creation, hence it has no effect when listing\nexisting parameters, nor does the flag `+g` have any effect except in\ncombination with `-m` (see below).\n\n\n- **`-m`** â If the `-m` flag is given the _name_ arguments are taken as patterns\n(use quoting to prevent these from being interpreted as file patterns).\nWith no attribute flags, all parameters (or functions with the `-f`\nflag) with matching names are printed (the shell option `TYPESET_SILENT`\nis not used in this case).\n\nIf the `+g` flag is combined with `-m`, a new local parameter is\ncreated for every matching parameter that is not already local. Otherwise\n`-m` applies all other flags or assignments to the existing parameters,\nexcept that the `-n` option cannot create named references in this way.\n\nExcept when assignments are made with _name_`=`_value_, using\n`+m` forces the matching parameters and their attributes to be printed,\neven inside a function. Note that `-m` is ignored if no patterns are\ngiven, so \"typeset -m\" displays attributes but \"typeset -a +m\"\ndoes not. Ordinary scalar string parameters have no attributes, so for\nthose `+m` prints only the names.\n\n\n- **`-p` [ _n_ ]** â If the `-p` option is given, parameters and values are printed in the\nform of a typeset command with an assignment, regardless of other flags\nand options. Note that the `-H` flag on parameters is respected; no\nvalue will be shown for these parameters.\n\n`-p` may be followed by an optional integer argument. Currently\nonly the value `1` is supported. In this case arrays and associative\narrays are printed with newlines between indented elements for\nreadability.\n\nThe names and values of readonly special parameters\n(most of the parameters marked \"<S>\" in\n_Parameters Set by the Shell_ (zshparam),\nexcept those documented as settable)\nare not printed with ``-\"p\" because to execute those typeset commands\nwould cause errors. However, these parameters are printed when they\nhave been made local to the scope where \"typeset -p\" is run.\n\n\n- **`-T` [ _scalar_[`=`_value_] _array_[`=()_value_ ...```] [ _sep_ ] ]** â This flag has a different meaning when used with `-f`; see below.\nOtherwise the `-T` option requires zero, two, or three arguments to be\npresent. With no arguments, the list of parameters created in this\nfashion is shown. With two or three arguments, the first two are the name\nof a scalar and of an array parameter (in that order) that will be tied\ntogether in the manner of `$PATH` and `$path`. The optional third\nargument is a single-character separator which will be used to join the\nelements of the array to form the scalar; if absent, a colon is used, as\nwith `$PATH`. Only the first character of the separator is significant;\nany remaining characters are ignored. Multibyte characters are not\nyet supported.\n\nOnly one of the scalar and array parameters may be assigned an initial\nvalue (the restrictions on assignment forms described above also apply).\n\nBoth the scalar and the array may be manipulated as normal. If one is\nunset, the other will automatically be unset too. There is no way of\nuntying the variables without unsetting them, nor of converting the type\nof one of them with another `typeset` command; `+T` does not work,\nassigning an array to _scalar_ is an error, and assigning a scalar to\n_array_ sets it to be a single-element array.\n\nNote that both \"typeset -xT ...\" and \"export -T ...\" work, but\nonly the scalar will be marked for export. Setting the value using the\nscalar version causes a split on all separators (which cannot be quoted).\nIt is possible to apply `-T` to two previously tied variables but with a\ndifferent separator character, in which case the variables remain joined\nas before but the separator is changed.\n\nWhen an existing scalar is tied to a new array, the value of the scalar\nis preserved but no attribute other than export will be preserved.\n\n\nAttribute flags that transform the final value (`-L`, `-R`, `-Z`,\n`-l`, `-u`) are only applied to the expanded value at the point\nof a parameter expansion expression using \"$\". They are not applied\nwhen a parameter is retrieved internally by the shell for any purpose.\n\nThe following attribute flags may be specified:\n\n\n- **`-A`** â The names refer to associative array parameters; see\n_Array Parameters_ (zshparam).\n\n\n- **`-L` [ _n_ ]** â Left justify and remove leading blanks from the value when the parameter\nis expanded.\nIf _n_ is nonzero, it defines the width of the field.\nIf _n_ is zero, the width is determined by the width of the value of\nthe first assignment. In the case of numeric parameters, the length of the\ncomplete value assigned to the parameter is used to determine the width,\nnot the value that would be output.\n\nThe width is the count of characters, which may be multibyte characters\nif the `MULTIBYTE` option is in effect. Note that the screen\nwidth of the character is not taken into account; if this is required,\nuse padding with parameter expansion flags\ntt(${+(ml)_..._``)_..._`}` as described in\nsubref(Parameter Expansion Flags)(zshexpn).\n\nWhen the parameter is expanded, it is filled on the right with\nblanks or truncated if necessary to fit the field.\nNote truncation can lead to unexpected results with numeric parameters.\nLeading zeros are removed if the `-Z` flag is also set.\n\n\n- **`-R` [ _n_ ]** âÂÂ\nSimilar to `-L`, except that right justification is used;\nwhen the parameter is expanded, the field is left filled with\nblanks or truncated from the end. May not be combined with the `-Z`\nflag.\n\n\n- **`-U`** â For arrays (but not for associative arrays), keep only the first\noccurrence of each duplicated value. This may also be set for tied\nparameters (see `-T`) or colon-separated special parameters like\n`PATH` or `FIGNORE`, etc. Note the flag takes effect on assignment,\nand the type of the variable being assigned to is determinative; for\nvariables with shared values it is therefore recommended to set the flag\nfor all interfaces, e.g. \"typeset -U PATH path\".\n\nThis flag has a different meaning when used with `-f`; see below.\n\n\n- **`-Z` [ _n_ ]** âÂÂ\nSpecially handled if set along with the `-L` flag.\nOtherwise, similar to `-R`, except that leading zeros are used for\npadding instead of blanks if the first non-blank character is a digit.\nNumeric parameters are specially handled: they are always eligible\nfor padding with zeroes, and the zeroes are inserted at an appropriate\nplace in the output.\n\n\n- **`-a`** â The names refer to array parameters. An array parameter may be\ncreated this way, but it may be assigned to in the `typeset`\nstatement only if the reserved word form of `typeset` is enabled\n(as it is by default). When displaying, both normal and associative\narrays are shown.\n\n\n- **`-f`** â The names refer to functions rather than parameters. No assignments\ncan be made, and the only other valid flags are `-t`, `-T`, `-k`,\n`-u`, `-U` and `-z`. The flag `-t` turns on execution tracing\nfor this function; the flag `-T` does the same, but turns off tracing\nfor any named (not anonymous) function called from the present one,\nunless that function also\nhas the `-t` or `-T` flag. The `-u` and `-U` flags cause the\nfunction to be marked for autoloading; `-U` also causes alias\nexpansion to be suppressed when the function is loaded. See the\ndescription of the \"autoload\" builtin for details.\n\nNote that the builtin `functions` provides the same basic capabilities\nas `typeset -f` but gives access to a few extra options; `autoload`\ngives further additional options for the case `typeset -fu` and\n`typeset -fU`.\n\n\n- **`-h`** â Hide: only useful for special parameters (those marked \"<S>\" in the table in\n_Parameters Set by the Shell_ (zshparam)),\nand for local parameters with the same name as a special parameter,\nthough harmless for others. A special parameter with this attribute will\nnot retain its special effect when made local. Thus after ``typeset -h\nPATH`', a function containing \"typeset PATH\" will create an ordinary\nlocal parameter without the usual behaviour of `PATH`. Alternatively,\nthe local parameter may itself be given this attribute; hence inside a\nfunction \"typeset -h PATH\" creates an ordinary local parameter and the\nspecial `PATH` parameter is not altered in any way. It is also possible\nto create a local parameter using ``typeset +h \"_special_\", where the\nlocal copy of _special_ will retain its special properties regardless of\nhaving the `-h` attribute. Global special parameters loaded from shell\nmodules (for example, those in `zsh/mapfile` and `zsh/parameter`) are\nautomatically given the `-h` attribute to avoid name clashes.\n\n- **`-H`** âÂÂ\nHide value: specifies that `typeset` will not display the value of the\nparameter when listing parameters; the display for such parameters is\nalways as if the \"+\" flag were given, but use of the parameter is\nin other respects normal. This effect does not apply when the parameter is\nspecified by name or by pattern with the `-m` option. This is on by\ndefault for the parameters in the `zsh/parameter` and `zsh/mapfile`\nmodules. Note, however, that unlike the `-h` flag this is also useful\nfor non-special parameters.\n\n- **`-i` [ _n_ ]** âÂÂ\nUse an internal integer representation. If _n_ is nonzero it\ndefines the output arithmetic base, otherwise it is determined by the\nfirst assignment. Bases from 2 to 36 inclusive are allowed.\n\n- **`-E` [ _n_ ]** âÂÂ\nUse an internal double-precision floating point representation. On output\nthe variable will be converted to scientific notation. If _n_ is\nnonzero it defines the number of significant figures to display; the\ndefault is ten.\n\n- **`-F` [ _n_ ]** âÂÂ\nUse an internal double-precision floating point representation. On output\nthe variable will be converted to fixed-point decimal notation. If _n_\nis nonzero it defines the number of digits to display after the decimal\npoint; the default is ten.\n\n- **`-l`** âÂÂ\nConvert the result to lower case whenever the parameter is expanded.\nThe value is _not_ converted when assigned.\n\n\n- **`-r`** â The given _name_s are marked readonly. Note that if _name_ is a\nspecial parameter, the readonly attribute can be turned on, but cannot then\nbe turned off.\n\nIf the `POSIX_BUILTINS` option is set, the readonly attribute is\nmore restrictive: unset variables can be marked readonly and cannot then\nbe set; furthermore, the readonly attribute cannot be removed from any\nvariable.\n\nIt is still possible to change other attributes of the variable though,\nsome of which like `-U` or `-Z` would affect the value. More generally,\nthe readonly attribute should not be relied on as a security mechanism.\n\nNote that in zsh (like in pdksh but unlike most other shells) it is\nstill possible to create a local variable of the same name as this is\nconsidered a different variable (though this variable, too, can be marked\nreadonly). Special variables that have been made readonly retain their value\nand readonly attribute when made local.\n\n\n- **`-t`** âÂÂ\nTags the named parameters. Tags only exist to flag the parameter for\nthe user's own purposes --- the list of tagged parameters can be queried\nusing \"typeset -t\". Tags have no other use. Note that the `-t`\nflag has a different meaning when used with `-f`; see above.\n\n- **`-u`** âÂÂ\nConvert the result to upper case whenever the parameter is expanded.\nThe value is _not_ converted when assigned.\nThis flag has different meanings when used with `-f` or `-n`; see above.\n\n- **`-x`** âÂÂ\nMark for automatic export to the environment of subsequently\nexecuted commands. If the option `GLOBAL_EXPORT` is set, this implies\nthe option `-g`, unless `+g` is also explicitly given; in other words\nthe parameter is not made local to the enclosing function. This is for\ncompatibility with previous versions of zsh."),
("ulimit", "Set or display resource limits of the shell and the processes started by\nthe shell. The value of _limit_ can be a number in the unit specified\nbelow or one of the values \"unlimited\", which removes the limit on the\nresource, or \"hard\", which uses the current value of the hard limit on\nthe resource.\n\nBy default, only soft limits are manipulated. If the `-H` flag\nis given use hard limits instead of soft limits. If the `-S` flag is given\ntogether with the `-H` flag set both hard and soft limits.\n\nIf no options are used, the file size limit (`-f`) is assumed.\n\nIf _limit_ is omitted the current value of the specified resources are\nprinted. When more than one resource value is printed, the limit name and\nunit is printed before each value.\n\nWhen looping over multiple resources, the shell will abort immediately if\nit detects a badly formed argument. However, if it fails to set a limit\nfor some other reason it will continue trying to set the remaining limits.\n\nNot all the following resources are supported on all systems. Running\n`ulimit -a` will show which are supported.\n\n- `-a` â List all of the current resource limits.\n\n- **`-b`** â Socket buffer size in bytes (N.B. not kilobytes+)\n\n- `-c` â 512-byte blocks on the size of core dumps.\n- `-d` â Kilobytes on the size of the data segment.\n- `-e` â Maximum nice value.\n- `-f` â 512-byte blocks on the size of files written.\n- `-i` â The number of pending signals.\n- `-k` â The number of kqueues allocated.\n- `-l` â Kilobytes on the size of locked-in memory.\n- `-m` â Kilobytes on the size of physical memory.\n- `-n` â Open file descriptors.\n- `-o` â Maximum number of POSIX thread library objects.\n- `-p` â The number of pseudo-terminals.\n- `-q` â Bytes in POSIX message queues.\n- `-r` â Maximum real time priority. On some systems where this\nis not available, such as NetBSD, this has the same effect as `-T`\nfor compatibility with `sh`.\n- `-s` â Kilobytes on the size of the stack.\n- `-T` â The number of simultaneous threads available to the user.\n- `-t` â CPU seconds to be used.\n- `-u` â The number of processes available to the user.\n- `-v` â Kilobytes on the size of virtual memory. On some systems this\nrefers to the limit called \"address space\".\n- `-w` â Kilobytes on the size of swapped out memory.\n- `-x` â The number of locks on files.\n- `-y` â Maximum size of buffers for pipes/fifos.\n\nA resource may also be specified by integer in the form ``-N`\n_resource_', where _resource_ corresponds to the integer defined for\nthe resource by the operating system. This may be used to set the limits\nfor resources known to the shell which do not correspond to option letters.\nSuch limits will be shown by number in the output of \"ulimit -a\".\n\nThe number may alternatively be out of the range of limits compiled into\nthe shell. The shell will try to read or write the limit anyway, and\nwill report an error if this fails."),
("umask", "The umask is set to _mask_. _mask_ can be either\nan octal number or a symbolic value as described in the manref(chmod)(1) man page.\nIf _mask_ is omitted, the current value is printed. The `-S`\noption causes the mask to be printed as a symbolic value. Otherwise,\nthe mask is printed as an octal number. Note that in\nthe symbolic form the permissions you specify are those which are to be\nallowed (not denied) to the users specified."),
("unalias", "Removes aliases. This command works the same as `unhash -a`, except that\nthe `-a` option removes all regular or global aliases, or with `-s`\nall suffix aliases: in this case no _name_ arguments may appear. The\noptions `-m` (remove by pattern) and `-s` without `-a` (remove\nlisted suffix aliases) behave as for `unhash -a`. Note that\nthe meaning of `-a` is different between `unalias` and `unhash`."),
("unhash", "Remove the element named _name_ from an internal hash table. The\ndefault is remove elements from the command hash table. The `-a`\noption causes `unhash` to remove regular or global aliases; note\nwhen removing a global aliases that the argument must be quoted to prevent\nit from being expanded before being passed to the command.\nThe `-s` option causes `unhash` to remove suffix aliases.\nThe `-f` option causes\n`unhash` to remove shell functions. The `-d` options causes\n`unhash` to remove named directories. If the `-m` flag is given\nthe arguments are taken as patterns (should be quoted) and all elements\nof the corresponding hash table with matching names will be removed."),
("unlimit", "The resource limit for each _resource_ is set to the hard limit.\nIf the `-h` flag is given and the shell has appropriate privileges,\nthe hard resource limit for each _resource_ is removed.\nThe resources of the shell process are only changed if the `-s`\nflag is given.\n\nThe `unlimit` command is not made available by default when the\nshell starts in a mode emulating another shell. It can be made available\nwith the command \"zmodload -F zsh/rlimits b:unlimit\"."),
("unset", "Each named parameter is unset.\nLocal parameters remain local even if unset; they appear unset within scope,\nbut the previous value will still reappear when the scope ends.\n\nIndividual elements of associative array parameters may be unset by using\nsubscript syntax on _name_, which should be quoted (or the entire command\nprefixed with `noglob`) to protect the subscript from filename generation.\n\nIf the `-m` flag is specified the arguments are taken as patterns (should\nbe quoted) and all parameters with matching names are unset. Note that this\ncannot be used when unsetting associative array elements, as the subscript\nwill be treated as part of the pattern.\n\nThe `-v` flag specifies that _name_ refers to parameters. This is\nthe default behaviour. If the `-n` option is supplied, and\n_name_ is a a named reference, _name_ will be unset rather than\nthe variable it references.\n\n`unset -f` is equivalent to `unfunction`. The `-n` option has\nno effect with `-f`."),
("unsetopt", "Unset the options for the shell. All options specified either\nwith flags or by name are unset. If no arguments are supplied,\nthe names of all options currently unset are printed.\nIf the `-m` flag is given the arguments are taken as patterns\n(which should be quoted to preserve them from being interpreted as glob\npatterns), and all options with names matching these patterns are unset."),
("wait", "Wait for the specified jobs or processes. If _job_ is not given\nthen all currently active child processes are waited for.\nEach _job_ can be either a job specification or the process ID\nof a job in the job table.\nThe exit status from this command is that of the job waited for.\nIf _job_ represents an unknown job or process ID, a warning is printed\n(unless the `POSIX_BUILTINS` option is set) and the exit status is 127.\n\nIt is possible to wait for recent processes (specified by process ID,\nnot by job) that were running in the background even if the process has\nexited. Typically the process ID will be recorded by capturing the\nvalue of the variable `$!` immediately after the process has been\nstarted. There is a limit on the number of process IDs remembered by\nthe shell; this is given by the value of the system configuration\nparameter `CHILD_MAX`. When this limit is reached, older process IDs\nare discarded, least recently started processes first.\n\nNote there is no protection against the process ID wrapping, i.e. if the\nwait is not executed soon enough there is a chance the process waited\nfor is the wrong one. A conflict implies both process IDs have been\ngenerated by the shell, as other processes are not recorded, and that\nthe user is potentially interested in both, so this problem is intrinsic\nto process IDs."),
("whence", "For each _name_, indicate how it would be interpreted if used as a\ncommand name.\n\nIf _name_ is not an alias, built-in command, external command, shell\nfunction, hashed command, or a reserved word, the exit status shall be\nnon-zero, and DASH()- if `-v`, `-c`, or `-w` was passed DASH()- a message\nwill be written to standard output. (This is different from other shells that\nwrite that message to standard error.)\n\n`whence` is most useful when _name_ is only the last path component\nof a command, i.e. does not include a \"/\"; in particular, pattern\nmatching only succeeds if just the non-directory component of the command is\npassed.\n\n- **`-v`** âÂÂ\nProduce a more verbose report.\n\n- **`-c`** âÂÂ\nPrint the results in a **csh**-like format.\nThis takes precedence over `-v`.\n\n- **`-w`** âÂÂ\nFor each _name_, print `_name_`:\" _word_\" where _word_\nis one of `alias`, `builtin`, `command`, `function`,\n`hashed`, `reserved` or `none`, according as _name_\ncorresponds to an alias, a built-in command, an external command, a\nshell function, a command defined with the `hash` builtin, a\nreserved word, or is not recognised. This takes precedence over\n`-v` and `-c`.\n\n- **`-f`** âÂÂ\nCauses the contents of a shell function to be\ndisplayed, which would otherwise not happen unless the `-c`\nflag were used.\n\n- **`-p`** âÂÂ\nDo a path search for _name_\neven if it is an alias, reserved word, shell function or builtin.\n\n- **`-a`** âÂÂ\nDo a search for all occurrences of _name_\nthroughout the command path.\nNormally only the first occurrence is printed.\nWhen combined with `-m`, only names appearing in the command hash\ntable are searched, but all occurrences of those names are printed.\n\n\n- **`-m`** â The arguments are taken as patterns (pattern characters should be\nquoted), and the information is displayed for each entry in the command\nhash table matching one of these patterns. The hash table is first\nrefilled, in case of changes to `PATH`.\n\n\n- **`-s`** âÂÂ\nIf a pathname contains symlinks, print the symlink-free pathname as well.\n\n- **`-S`** âÂÂ\nAs `-s`, but if the pathname had to be resolved by following\nmultiple symlinks, the intermediate steps are printed, too. The\nsymlink resolved at each step might be anywhere in the path.\n\n- **`-x` _num_** âÂÂ\nExpand tabs when outputting shell functions using the `-c` option.\nThis has the same effect as the `-x` option to the `functions`\nbuiltin."),
("where", "Equivalent to `whence -ca`."),
("which", "Equivalent to `whence -c`."),
("zcompile", "This builtin command can be used to compile functions or scripts,\nstoring the compiled form in a file, and to examine files containing\nthe compiled form. This allows faster autoloading of functions and\nsourcing of scripts by avoiding parsing of the text when the files\nare read.\n\nThe first form (without the `-c`, `-a` or `-t` options) creates a\ncompiled file. If only the _file_ argument is given, the\noutput file has the name `_file_`.zwc`' and will be placed in\nthe same directory as the _file_. The shell will load the compiled\nfile instead of the normal function file when the function\nis autoloaded; see _Autoloading Functions_ (zshmisc)\nfor a description of how autoloaded functions are searched. The\nextension `.zwc` stands for \"zsh word code\".\n\nvindex(fpath, with zcompile)\nIf there is at least one _name_ argument, all the named files\nare compiled into the output _file_ given as the first argument. If\n_file_ does not end in `.zwc`, this extension is automatically\nappended. Files containing multiple compiled functions are called \"digest\"\nfiles, and are intended to be used as elements of the `FPATH`/`fpath`\nspecial array.\n\nThe second form, with the `-c` or `-a` options, writes the compiled\ndefinitions for all the named functions into _file_. For `-c`, the\nnames must be functions currently defined in the shell, not those marked\nfor autoloading. Undefined functions that are marked for autoloading\nmay be written by using the `-a` option, in which case the `fpath`\nis searched and the contents of the definition files for those\nfunctions, if found, are compiled into _file_. If both `-c` and\n`-a` are given, names of both defined functions and functions marked\nfor autoloading may be given. In either case, the functions in files\nwritten with the `-c` or `-a` option will be autoloaded as if the\n`KSH_AUTOLOAD` option were unset.\n\nThe reason for handling loaded and not-yet-loaded functions with\ndifferent options is that some definition files for autoloading define\nmultiple functions, including the function with the same name as the\nfile, and, at the end, call that function. In such cases the output of\n\"zcompile -c\" does not include the additional functions defined in\nthe file, and any other initialization code in the file is lost. Using\n\"zcompile -a\" captures all this extra information.\n\nIf the `-m` option is combined with `-c` or `-a`,\nthe _name_s are used as patterns and all functions whose names\nmatch one of these patterns will be written. If no _name_ is given,\nthe definitions of all functions currently defined or marked as\nautoloaded will be written.\n\nNote the second form cannot be used for compiling functions that\ninclude redirections as part of the definition rather than within\nthe body of the function; for example\n\nexample(fn1() { { ... } >~/logfile })\n\ncan be compiled but\n\nexample(fn1() { ... } >~/logfile)\n\ncannot. It is possible to use the first form of `zcompile` to compile\nautoloadable functions that include the full function definition instead\nof just the body of the function.\n\nThe third form, with the `-t` option, examines an existing\ncompiled file. Without further arguments, the names of the original\nfiles compiled into it are listed. The first line of output shows\nthe version of the shell which compiled the file and how the file\nwill be used (i.e. by reading it directly or by mapping it into memory).\nWith arguments, nothing is output and the return status is set to zero if\ndefinitions for _all_ _name_s were found in the compiled\nfile, and non-zero if the definition for at least one _name_ was not\nfound.\n\nOther options:\n\n- **`-U`** âÂÂ\nAliases are not expanded when compiling the _name_d files.\n\n\n- **`-R`** â When the compiled file is read, its contents are copied into the\nshell's memory, rather than memory-mapped (see `-M`). This\nhappens automatically on systems that do not support memory mapping.\n\nWhen compiling scripts instead of autoloadable functions, it is\noften desirable to use this option; otherwise the whole file, including the\ncode to define functions which have already been defined, will\nremain mapped, consequently wasting memory.\n\n- **`-M`** âÂÂ\nThe compiled file is mapped into the shell's memory when read. This\nis done in such a way that multiple instances of the shell running\non the same host will share this mapped file. If neither `-R` nor\n`-M` is given, the `zcompile` builtin decides what to do based\non the size of the compiled file.\n\n- **`-k`**\n\n\n- **`-z`** â These options are used when the compiled file contains functions which\nare to be autoloaded. If `-z` is given, the\nfunction will be autoloaded as if the `KSH_AUTOLOAD` option is\n_not_ set, even if it is set at the time the compiled file is\nread, while if the `-k` is given, the function will be loaded as if\n`KSH_AUTOLOAD` _is_ set. These options also take precedence over\nany `-k` or `-z` options specified to the `autoload` builtin. If\nneither of these options is given, the function will be loaded as\ndetermined by the setting of the `KSH_AUTOLOAD` option at the time\nthe compiled file is read.\nifzman( )\nThese options may also appear as many times as necessary between the listed\n_name_s to specify the loading style of all following functions, up to\nthe next `-k` or `-z`.\n\nifnzman(\n)\nThe created file always contains two versions of the compiled\nformat, one for big-endian machines and one for small-endian\nmachines. The upshot of this is that the compiled file is machine\nindependent and if it is read or mapped, only one half of the file\nis actually used (and mapped).\nifzman()"),
("zmodload", "Performs operations relating to zsh's loadable modules.\nLoading of modules while the shell is running (\"dynamical loading\") is not\navailable on all operating systems, or on all installations on a particular\noperating system, although the `zmodload` command itself is always\navailable and can be used to manipulate modules built into versions of the\nshell executable without dynamical loading.\n\nWithout arguments the names of all currently loaded binary modules are\nprinted. The `-L` option causes this list to be in the form of a\nseries of `zmodload` commands. Forms with arguments are:\n\n- **`zmodload` [ `-is` ] _name_ ... **\n\n\n- **`zmodload` `-u` [ `-i` ] _name_ ...** â In the simplest case, `zmodload` loads a binary module. The module must\nbe in a file with a name consisting of the specified _name_ followed by\na standard suffix, usually \".so\" (\".sl\" on HPUX).\nIf the module to be loaded is already loaded the duplicate module is\nignored. If `zmodload` detects an inconsistency, such as an\ninvalid module name or circular dependency list, the current code block is\naborted. If it is available, the module is loaded if necessary, while if it\nis not available, non-zero status is silently returned. The option\n`-i` is accepted for compatibility but has no effect.\n\nThe _name_d module is searched for in the same way a command is, using\n`$module_path` instead of `$path`. However, the path search is\nperformed even when the module name contains a \"/\", which it usually does.\nThere is no way to prevent the path search.\n\nIf the module supports features (see below), `zmodload` tries to\nenable all features when loading a module. If the module was successfully\nloaded but not all features could be enabled, `zmodload` returns status 2.\n\nIf the option `-s` is given, no error is printed if the module was not\navailable (though other errors indicating a problem with the module are\nprinted). The return status indicates if the module was loaded. This\nis appropriate if the caller considers the module optional.\n\nWith `-u`, `zmodload` unloads modules. The same _name_\nmust be given that was given when the module was loaded, but it is not\nnecessary for the module to exist in the file system.\nThe `-i` option suppresses the error if the module is already\nunloaded (or was never loaded).\n\nEach module has a boot and a cleanup function. The module\nwill not be loaded if its boot function fails. Similarly a module\ncan only be unloaded if its cleanup function runs successfully.\n\n\n- **`zmodload -F` [ `-almLe` `-P` _param_ ] _module_ [ [`+-`]_feature_ ... ]** â `zmodload -F` allows more selective control over the features provided\nby modules. With no options apart from `-F`, the module named\n_module_ is loaded, if it was not already loaded, and the list of\n_feature_s is set to the required state. If no\n_feature_s are specified, the module is loaded, if it was not already\nloaded, but the state of features is unchanged. Each feature\nmay be preceded by a `+` to turn the feature on, or `-` to turn it\noff; the `+` is assumed if neither character is present.\nAny feature not explicitly mentioned is left in its current state;\nif the module was not previously loaded this means any such features will\nremain disabled. The return status is zero if all features were\nset, 1 if the module failed to load, and 2 if some features could\nnot be set (for example, a parameter couldn't be added because there\nwas a different parameter of the same name) but the module was loaded.\n\nThe standard features are builtins, conditions, parameters and math\nfunctions; these are indicated by the prefix \"b:\", \"c:\"\n(\"C:\" for an infix condition), \"p:\" and \"f:\", respectively,\nfollowed by the name that the corresponding feature would have in the\nshell. For example, \"b:strftime\" indicates a builtin named\n`strftime` and `p:EPOCHSECONDS` indicates a parameter named\n`EPOCHSECONDS`. The module may provide other (\"abstract\") features of\nits own as indicated by its documentation; these have no prefix.\n\nWith `-l` or `-L`, features provided by the module are listed. With\n`-l` alone, a list of features together with their states is shown, one\nfeature per line. With `-L` alone, a `zmodload -F` command that would\ncause enabled features of the module to be turned on is shown. With\n`-lL`, a `zmodload -F` command that would cause all the features to be\nset to their current state is shown. If one of these combinations is given\nwith the option `-P` _param_ then the parameter _param_ is set to an\narray of features, either features together with their state or (if\n`-L` alone is given) enabled features.\n\nWith the option `-L` the module name may be omitted; then a list\nof all enabled features for all modules providing features is printed\nin the form of `zmodload -F` commands. If `-l` is also given,\nthe state of both enabled and disabled features is output in that form.\n\nA set of features may be provided together with `-l` or `-L` and a\nmodule name; in that case only the state of those features is\nconsidered. Each feature may be preceded by `+` or `-` but the\ncharacter has no effect. If no set of features is provided, all\nfeatures are considered.\n\nWith `-e`, the command first tests that the module is loaded;\nif it is not, status 1 is returned. If the module is loaded,\nthe list of features given as an argument is examined. Any feature\ngiven with no prefix is simply tested to see if the module provides it;\nany feature given with a prefix `+` or `-` is tested to\nsee if is provided and in the given state. If the tests on all features\nin the list succeed, status 0 is returned, else status 1.\n\nWith `-m`, each entry in the given list of features is taken\nas a pattern to be matched against the list of features provided\nby the module. An initial `+` or `-` must be given explicitly.\nThis may not be combined with the `-a` option as autoloads must\nbe specified explicitly.\n\nWith `-a`, the given list of features is marked for autoload from\nthe specified module, which may not yet be loaded. An optional `+`\nmay appear before the feature name. If the feature is prefixed with\n`-`, any existing autoload is removed. The options `-l` and `-L`\nmay be used to list autoloads. Autoloading is specific to individual\nfeatures; when the module is loaded only the requested feature is\nenabled. Autoload requests are preserved if the module is\nsubsequently unloaded until an explicit ``zmodload -Fa` _module_\n`-\"_feature_\" is issued. It is not an error to request an autoload\nfor a feature of a module that is already loaded.\n\nWhen the module is loaded each autoload is checked against the features\nactually provided by the module; if the feature is not provided the\nautoload request is deleted. A warning message is output; if the\nmodule is being loaded to provide a different feature, and that autoload\nis successful, there is no effect on the status of the current command.\nIf the module is already loaded at the time when `zmodload -Fa` is\nrun, an error message is printed and status 1 returned.\n\n`zmodload -Fa` can be used with the `-l`, `-L`, `-e` and\n`-P` options for listing and testing the existence of autoloadable\nfeatures. In this case `-l` is ignored if `-L` is specified.\n`zmodload -FaL` with no module name lists autoloads for all modules.\n\nNote that only standard features as described above can be autoloaded;\nother features require the module to be loaded before enabling.\n\n- **`zmodload` `-d` [ `-L` ] [ _name_ ]**\n\n- **`zmodload` `-d` _name_ _dep_ ...**\n\n- **`zmodload` `-ud` _name_ [ _dep_ ... ]** âÂÂ\nThe `-d` option can be used to specify module dependencies. The modules\nnamed in the second and subsequent arguments will be loaded before the\nmodule named in the first argument.\n\nWith `-d` and one argument, all dependencies for that module are listed.\nWith `-d` and no arguments, all module dependencies are listed. This\nlisting is by default in a Makefile-like format. The `-L` option\nchanges this format to a list of `zmodload -d` commands.\n\nIf `-d` and `-u` are both used, dependencies are removed. If only one\nargument is given, all dependencies for that module are removed.\n\n- **`zmodload` `-ab` [ `-L` ]**\n\n- **`zmodload` `-ab` [ `-i` ] _name_ [ _builtin_ ... ]**\n\n\n- **`zmodload` `-ub` [ `-i` ] _builtin_ ...** â The `-ab` option defines autoloaded builtins. It defines the specified\n_builtin_s. When any of those builtins is called, the module specified\nin the first argument is loaded and all its features are enabled (for\nselective control of features use \"zmodload -F -a\" as described\nabove). If only the _name_ is given, one builtin is defined, with\nthe same name as the module. `-i` suppresses the error if the builtin\nis already defined or autoloaded, but not if another builtin of the\nsame name is already defined.\n\nWith `-ab` and no arguments, all autoloaded builtins are listed, with the\nmodule name (if different) shown in parentheses after the builtin name.\nThe `-L` option changes this format to a list of `zmodload -a`\ncommands.\n\nIf `-b` is used together with the `-u` option, it removes builtins\npreviously defined with `-ab`. This is only possible if the builtin is\nnot yet loaded. `-i` suppresses the error if the builtin is already\nremoved (or never existed).\n\nAutoload requests are retained if the module is subsequently unloaded\nuntil an explicit ``zmodload -ub\" _builtin_\" is issued.\n\n\n- **`zmodload` `-ac` [ `-IL` ]**\n\n- **`zmodload` `-ac` [ `-iI` ] _name_ [ _cond_ ... ]**\n\n\n- **`zmodload` `-uc` [ `-iI` ] _cond_ ...** â The `-ac` option is used to define autoloaded condition codes. The\n_cond_ strings give the names of the conditions defined by the\nmodule. The optional `-I` option is used to define infix condition\nnames. Without this option prefix condition names are defined.\n\nIf given no condition names, all defined names are listed (as a series of\n`zmodload` commands if the `-L` option is given).\n\nThe `-uc` option removes definitions for autoloaded conditions.\n\n\n- **`zmodload` `-ap` [ `-L` ]**\n\n- **`zmodload` `-ap` [ `-i` ] _name_ [ _parameter_ ... ]**\n\n- **`zmodload` `-up` [ `-i` ] _parameter_ ...** âÂÂ\nThe `-p` option is like the `-b` and `-c` options, but makes\n`zmodload` work on autoloaded parameters instead.\n\n- **`zmodload` `-af` [ `-L` ]**\n\n- **`zmodload` `-af` [ `-i` ] _name_ [ _function_ ... ]**\n\n- **`zmodload` `-uf` [ `-i` ] _function_ ...** âÂÂ\nThe `-f` option is like the `-b`, `-p`, and `-c` options, but\nmakes `zmodload` work on autoloaded math functions instead.\n\n- **`zmodload` `-a` [ `-L` ]**\n\n- **`zmodload` `-a` [ `-i` ] _name_ [ _builtin_ ... ]**\n\n- **`zmodload` `-ua` [ `-i` ] _builtin_ ...** âÂÂ\nEquivalent to `-ab` and `-ub`.\n\n- **`zmodload -e` [ `-A` ] [ _string_ ... ]** âÂÂ\nThe `-e` option without arguments lists all loaded modules; if the `-A`\noption is also given, module aliases corresponding to loaded modules are\nalso shown. If arguments are provided, nothing is printed;\nthe return status is set to zero if all _string_s given as arguments\nare names of loaded modules and to one if at least on _string_ is not\nthe name of a loaded module. This can be used to test for the\navailability of things implemented by modules. In this case, any\naliases are automatically resolved and the `-A` flag is not used.\n\n\n- **`zmodload` `-A` [ `-L` ] [ _modalias_[`=`_module_] ... ]** â For each argument, if both _modalias_ and _module_ are given,\ndefine _modalias_ to be an alias for the module _module_.\nIf the module _modalias_ is ever subsequently requested, either via a\ncall to `zmodload` or implicitly, the shell will attempt to load\n_module_ instead. If _module_ is not given, show the definition of\n_modalias_. If no arguments are given, list all defined module aliases.\nWhen listing, if the `-L` flag was also given, list the definition as a\n`zmodload` command to recreate the alias.\n\nThe existence of aliases for modules is completely independent of whether\nthe name resolved is actually loaded as a module: while the alias exists,\nloading and unloading the module under any alias has exactly the same\neffect as using the resolved name, and does not affect the connection\nbetween the alias and the resolved name which can be removed either by\n`zmodload -R` or by redefining the alias. Chains of aliases (i.e. where\nthe first resolved name is itself an alias) are valid so long as these are\nnot circular. As the aliases take the same format as module names, they\nmay include path separators: in this case, there is no requirement for any\npart of the path named to exist as the alias will be resolved first. For\nexample, \"any/old/alias\" is always a valid alias.\n\nDependencies added to aliased modules are actually added to the resolved\nmodule; these remain if the alias is removed. It is valid to create an\nalias whose name is one of the standard shell modules and which resolves to\na different module. However, if a module has dependencies, it\nwill not be possible to use the module name as an alias as the module will\nalready be marked as a loadable module in its own right.\n\nApart from the above, aliases can be used in the `zmodload` command\nanywhere module names are required. However, aliases will not be\nshown in lists of loaded modules with a bare \"zmodload\".\n\n\n- **`zmodload` `-R` _modalias_ ... ** âÂÂ\nFor each _modalias_ argument that was previously defined as a module\nalias via `zmodload -A`, delete the alias. If any was not defined, an\nerror is caused and the remainder of the line is ignored.\n\nNote that `zsh` makes no distinction between modules that were linked\ninto the shell and modules that are loaded dynamically. In both cases\nthis builtin command has to be used to make available the builtins and\nother things defined by modules (unless the module is autoloaded on\nthese definitions). This is true even for systems that don't support\ndynamic loading of modules."),
("bindkey", "`bindkey`'s options can be divided into three categories: keymap\nselection for the current command, operation selection, and others. The\nkeymap selection options are:\n\n- **`-e`** âÂÂ\nSelects keymap \"emacs\" for any operations by the current command,\nand also links \"emacs\" to \"main\" so that it is selected by\ndefault the next time the editor starts.\n\n- **`-v`** âÂÂ\nSelects keymap \"viins\" for any operations by the current command,\nand also links \"viins\" to \"main\" so that it is selected by default\nthe next time the editor starts.\n\n- **`-a`** âÂÂ\nSelects keymap \"vicmd\" for any operations by the current command.\n\n- **`-M` _keymap_** âÂÂ\nThe _keymap_ specifies a keymap name that is selected for any\noperations by the current command.\n\nIf a keymap selection is required and none of the options above are used, the\n\"main\" keymap is used. Some operations do not permit a keymap to be\nselected, namely:\n\n- **`-l`** âÂÂ\nList all existing keymap names; if any arguments are given, list just\nthose keymaps.\n\nIf the `-L` option is also used, list in the form of `bindkey`\ncommands to create or link the keymaps. ``bindkey -lL\nmain`' shows which keymap is linked to \"main\", if any, and hence if\nthe standard emacs or vi emulation is in effect. This option does\nnot show the `.safe` keymap because it cannot be created in that\nfashion; however, neither is \"bindkey -lL .safe\" reported as an\nerror, it simply outputs nothing.\n\n- **`-d`** âÂÂ\nDelete all existing keymaps and reset to the default state.\n\n- **`-D` _keymap_ ...** âÂÂ\nDelete the named _keymap_s.\n\n- **`-A` _old-keymap new-keymap_** âÂÂ\nMake the _new-keymap_ name an alias for _old-keymap_, so that\nboth names refer to the same keymap. The names have equal standing;\nif either is deleted, the other remains. If there is already a keymap\nwith the _new-keymap_ name, it is deleted.\n\n- **`-N` _new-keymap_ [ _old-keymap_ ]** âÂÂ\nCreate a new keymap, named _new-keymap_. If a keymap already has that\nname, it is deleted. If an _old-keymap_ name is given, the new keymap\nis initialized to be a duplicate of it, otherwise the new keymap will\nbe empty.\n\nTo use a newly created keymap, it should be linked to `main`. Hence\nthe sequence of commands to create and use a new keymap \"mymap\"\ninitialized from the `emacs` keymap (which remains unchanged) is:\n\n bindkey -N mymap emacs\nbindkey -A mymap main\n\nNote that while ``bindkey -A` _newmap_ `main`' will work when\n_newmap_ is `emacs` or `viins`, it will not work for `vicmd`, as\nswitching from vi insert to command mode becomes impossible.\n\nThe following operations act on the \"main\" keymap if no keymap\nselection option was given:\n\n- **`-m`** âÂÂ\nAdd the built-in set of meta-key bindings to the selected keymap.\nOnly keys that are unbound or bound to `self-insert` are affected.\n\n\n- **`-r` _in-string_ ...** â Unbind the specified _in-string_s in the selected keymap.\nThis is exactly equivalent to binding the strings to `undefined-key`.\n\nWhen `-R` is also used, interpret the _in-string_s as ranges.\n\nWhen `-p` is also used, the _in-string_s specify prefixes. Any\nbinding that has the given _in-string_ as a prefix, not including the\nbinding for the _in-string_ itself, if any, will be removed. For\nexample,\n\n bindkey -rpM viins '^['\n\nwill remove all bindings in the vi-insert keymap beginning with an escape\ncharacter (probably cursor keys), but leave the binding for the escape\ncharacter itself (probably `vi-cmd-mode`). This is incompatible with the\noption `-R`.\n\n\n- **`-s` _in-string out-string_ ...** âÂÂ\nBind each _in-string_ to each _out-string_.\nWhen _in-string_ is typed, _out-string_ will be\npushed back and treated as input to the line editor.\nWhen `-R` is also used, interpret the _in-string_s as ranges.\n\nNote that both _in-string_ and _out-string_ are subject to the same\nform of interpretation, as described below.\n\n- **_in-string command_ ...** âÂÂ\nBind each _in-string_ to each _command_.\nWhen `-R` is used, interpret the _in-string_s as ranges.\n\n\n- **[ _in-string_ ]** â List key bindings. If an _in-string_ is specified, the binding of\nthat string in the selected keymap is displayed. Otherwise, all key\nbindings in the selected keymap are displayed. (As a special case,\nif the `-e` or `-v` option is used alone, the keymap is _not_\ndisplayed - the implicit linking of keymaps is the only thing that\nhappens.)\n\nWhen the option `-p` is used, the _in-string_ must be present.\nThe listing shows all bindings which have the given key sequence as a\nprefix, not including any bindings for the key sequence itself.\n\nWhen the `-L` option is used, the list is in the form of `bindkey`\ncommands to create the key bindings.\n\n\nWhen the `-R` option is used as noted above, a valid range consists of\ntwo characters, with an optional \"-\" between them. All characters\nbetween the two specified, inclusive, are bound as specified.\n\nFor either _in-string_ or _out-string_, the following\nescape sequences are recognised:\n\n- `\\a` â bell character\n- `\\b` â backspace\n- `\\e`, `\\E` â escape\n- `\\f` â form feed\n\n- **`\\n`** â linefeed (newline)\n\n- `\\r` â carriage return\n- `\\t` â horizontal tab\n- `\\v` â vertical tab\n- `\\`_NNN_ â character code in octal\n- `\\x`_NN_ â character code in hexadecimal\n- `\\u`_NNNN_ â unicode character code in hexadecimal\n- `\\U`_NNNNNNNN_ â unicode character code in hexadecimal\n- `\\M`[`-`]_X_ â character with meta bit set\n- `\\C`[`-`]_X_ â control character\n- `^`_X_ â control character\n\nIn all other cases, \"\\\" escapes the following character. Delete is\nwritten as \"^?\". Note that \"\\M^?\" and \"^\\M?\" are not the same,\nand that (unlike emacs), the bindings ``\\M-\"_X_\" and ``\\e\"_X_\"\nare entirely distinct, although they are initialized to the same bindings\nby \"bindkey -m\"."),
("vared", "The value of the parameter _name_ is loaded into the edit\nbuffer, and the line editor is invoked. When the editor exits,\n_name_ is set to the string value returned by the editor.\nWhen the `-c\" flag is given, the parameter is created if it doesn\"t\nalready exist. The `-a` flag may be given with `-c` to create\nan array parameter, or the `-A` flag to create an associative array.\nIf the type of an existing parameter does not match the type to be\ncreated, the parameter is unset and recreated. The `-g` flag may\nbe given to suppress warnings from the `WARN_CREATE_GLOBAL`\nand `WARN_NESTED_VAR` options.\n\nIf an array or array slice is being edited, separator characters as defined\nin `$IFS` will be shown quoted with a backslash, as will backslashes\nthemselves. Conversely, when the edited text is split into an array, a\nbackslash quotes an immediately following separator character or backslash;\nno other special handling of backslashes, or any handling of quotes, is\nperformed.\n\nIndividual elements of existing array or associative array parameters\nmay be edited by using subscript syntax on _name_. New elements are\ncreated automatically, even without `-c`.\n\nIf the `-p` flag is given, the following string will be taken as\nthe prompt to display at the left. If the `-r` flag is given,\nthe following string gives the prompt to display at the right. If the\n`-h` flag is specified, the history can be accessed from ZLE. If the\n`-e` flag is given, typing `^D` (Control-D) in an empty buffer\ncauses `vared` to exit immediately with a non-zero return value.\n\nThe `-M` option gives a keymap to link to the `main` keymap during\nediting, and the `-m` option gives a keymap to link to the `vicmd`\nkeymap during editing. For vi-style editing, this allows a pair of keymaps\nto override `viins` and `vicmd`. For emacs-style editing, only `-M`\nis normally needed but the `-m` option may still be used. On exit, the\nprevious keymaps will be restored.\n\n`Vared` calls the usual \"zle-line-init\" and \"zle-line-finish\"\nhooks before and after it takes control. Using the `-i` and `-f`\noptions, it is possible to replace these with other custom widgets.\n\nIf ``-t\" _tty_\" is given, _tty_ is the name of a terminal device\nto be used instead of the default `/dev/tty`. If _tty_ does not\nrefer to a terminal an error is reported."),
("zle", "The `zle` builtin performs a number of different actions concerning\nZLE.\n\nWith no options and no arguments, only the return status will be\nset. It is zero if ZLE is currently active and widgets could be\ninvoked using this builtin command and non-zero otherwise.\nNote that even if non-zero status is returned, zle may still be active as\npart of the completion system; this does not allow direct calls to ZLE\nwidgets.\n\nOtherwise, which operation it performs depends on its options:\n\n- **`-l` [ `-L` | `-a` ] [ _string_ ]** âÂÂ\nList all existing user-defined widgets. If the `-L`\noption is used, list in the form of `zle`\ncommands to create the widgets.\n\nWhen combined with the `-a` option, all widget names are listed,\nincluding the builtin ones. In this case the `-L` option is ignored.\n\nIf at least one _string_ is given, and `-a` is present or `-L` is\nnot used, nothing will be printed. The return status will be zero if\nall _string_s are names of existing widgets and non-zero if at least one\n_string_ is not a name of a defined widget. If `-a` is also\npresent, all widget names are used for the comparison including builtin\nwidgets, else only user-defined widgets are used.\n\nIf at least one _string_ is present and the `-L` option is used,\nuser-defined widgets matching any _string_ are listed in the form of\n`zle` commands to create the widgets.\n\n- **`-D` _widget_ ...** âÂÂ\nDelete the named _widget_s.\n\n- **`-A` _old-widget_ _new-widget_** âÂÂ\nMake the _new-widget_ name an alias for _old-widget_, so that\nboth names refer to the same widget. The names have equal standing;\nif either is deleted, the other remains. If there is already a widget\nwith the _new-widget_ name, it is deleted.\n\n\n- **`-N` _widget_ [ _function_ ]** â Create a user-defined widget. If there is already a widget with the\nspecified name, it is overwritten. When the new\nwidget is invoked from within the editor, the specified shell _function_\nis called. If no function name is specified, it defaults to\nthe same name as the widget. For further information, see\n_Zle Widgets_ (below).\n\n\n- **`-f` _flag_ [ _flag_... ]** âÂÂ\nSet various flags on the running widget. Possible values for _flag_ are:\n\n`yank` for indicating that the widget has yanked text into the buffer.\nIf the widget is wrapping an existing internal widget, no further\naction is necessary, but if it has inserted the text manually, then it\nshould also take care to set `YANK_START` and `YANK_END` correctly.\n`yankbefore` does the same but is used when the yanked text appears\nafter the cursor.\n\n`kill` for indicating that text has been killed into the cutbuffer.\nWhen repeatedly invoking a kill widget, text is appended to the cutbuffer\ninstead of replacing it, but when wrapping such widgets, it is necessary\nto call \"zle -f kill\" to retain this effect.\n\n`vichange` for indicating that the widget represents a vi change that\ncan be repeated as a whole with \"vi-repeat-change\". The flag should be set\nearly in the function before inspecting the value of `NUMERIC` or invoking\nother widgets. This has no effect for a widget invoked from insert mode. If\ninsert mode is active when the widget finishes, the change extends until next\nreturning to command mode.\n\ncindex(completion widgets, creating)\n\n- **`-C` _widget_ _completion-widget_ _function_** â Create a user-defined completion widget named _widget_. The\ncompletion widget will behave like the built-in completion-widget\nwhose name is given as _completion-widget_. To generate the\ncompletions, the shell function _function_ will be called.\nFor further information, see nmref(Completion Widgets)(zshcompwid).\n\n\n- **`-R` [ `-c` ] [ _display-string_ ] [ _string_ ... ]** â Redisplay the command line. If a _display-string_ is\ngiven and not empty, this is shown in the status line (immediately\nbelow the line being edited).\n\nIf the optional _string_s are given they are listed below the\nprompt in the same way as completion lists are printed. If no\n_string_s are given but the `-c` option is used such a list is\ncleared.\n\nNote that immediately after returning from running widgets, the command line\nwill be redisplayed and the strings displayed will be erased. Therefore, this\noption is only useful for widgets that do not exit immediately after using it.\n\nThis command can safely be called outside user defined widgets; if zle is\nactive, the display will be refreshed, while if zle is not active, the\ncommand has no effect. In this case there will usually be no other\narguments.\n\nThe status is zero if zle was active, else one.\n\n\n- **`-M` _string_** â As with the `-R` option, the _string_ will be displayed below the\ncommand line; unlike the `-R` option, the string will not be put into\nthe status line but will instead be printed normally below the\nprompt. This means that the _string_ will still be displayed after\nthe widget returns (until it is overwritten by subsequent commands).\n\n\n- **`-U` _string_** âÂÂ\nThis pushes the characters in the _string_ onto the input stack of\nZLE. After the widget currently executed finishes ZLE will behave as\nif the characters in the _string_ were typed by the user.\n\nAs ZLE uses a stack, if this option is used repeatedly\nthe last string pushed onto the stack will be processed first. However,\nthe characters in each _string_ will be processed in the order in which\nthey appear in the string.\n\n\n- **`-K` _keymap_** â Selects the keymap named _keymap_. An error message will be displayed if\nthere is no such keymap.\n\nThis keymap selection affects the interpretation of following keystrokes\nwithin this invocation of ZLE. Any following invocation (e.g., the next\ncommand line) will start as usual with the \"main\" keymap selected.\n\n\n- **`-F` [ `-L` | `-w` ] [ _fd_ [ _handler_ ] ]** â Only available if your system supports one of the \"poll\" or \"select\" system\ncalls; most modern systems do.\n\nInstalls _handler_ (the name of a shell function) to handle input from\nfile descriptor _fd_. Installing a handler for an _fd_ which is\nalready handled causes the existing handler to be replaced. Any number of\nhandlers for any number of readable file descriptors may be installed.\nNote that zle makes no attempt to check whether this _fd_ is actually\nreadable when installing the handler. The user must make their own\narrangements for handling the file descriptor when zle is not active.\n\nWhen zle is attempting to read data, it will examine both the terminal and\nthe list of handled _fd_'s. If data becomes available on a handled\n_fd_, zle calls _handler_ with the fd which is ready for reading\nas the first argument. Under normal circumstances this is the only\nargument, but if an error was detected, a second argument provides\ndetails: \"hup\" for a disconnect, \"nval\" for a closed or otherwise\ninvalid descriptor, or \"err\" for any other condition. Systems that\nsupport only the \"select\" system call always use \"err\".\n\nIf the option `-w` is also given, the _handler_ is instead a line\neditor widget, typically a shell function made into a widget using\n\"zle -N\". In that case _handler_ can use all the facilities of zle\nto update the current editing line. Note, however, that as handling _fd_\ntakes place at a low level changes to the display will not automatically\nappear; the widget should call \"zle -R\" to force redisplay. As of this\nwriting, widget handlers only support a single argument and thus are never\npassed a string for error state, so widgets must be prepared to test the\ndescriptor themselves.\n\nIf either type of handler produces output to the terminal, it should call\n\"zle -I\" before doing so (see below). Handlers should not attempt to\nread from the terminal.\n\nIf no _handler_ is given, but an _fd_ is present, any handler for\nthat _fd_ is removed. If there is none, an error message is printed\nand status 1 is returned.\n\nIf no arguments are given, or the `-L` option is supplied, a list of\nhandlers is printed in a form which can be stored for later execution.\n\nAn _fd_ (but not a _handler_) may optionally be given with the `-L`\noption; in this case, the function will list the handler if any, else\nsilently return status 1.\n\nNote that this feature should be used with care. Activity on one of the\n_fd_'s which is not properly handled can cause the terminal to become\nunusable. Removing an _fd_ handler from within a signal trap may cause\nunpredictable behavior.\n\nHere is a simple example of using this feature. A connection to a remote\nTCP port is created using the ztcp command; see\n_The zsh/net/tcp Module_ (zshmodules). Then a handler is installed\nwhich simply prints out any data which arrives on this connection. Note\nthat \"select\" will indicate that the file descriptor needs handling\nif the remote side has closed the connection; we handle that by testing\nfor a failed read.\n\nexample(if ztcp pwspc 2811; then\n tcpfd=$REPLY\n handler+() {\n zle -I\n local line\n if ! read -r line <&$1; then\n # select marks this fd if we reach EOF,\n # so handle this specially.\n print \"[Read on fd $1 failed, removing.]\" >&2\n zle -F $1\n return 1\n fi\n print -r - $line\n }\n zle -F $tcpfd handler\nfi)\n\n\n- **`-I`** â Unusually, this option is most useful outside ordinary widget functions,\nthough it may be used within if normal output to the terminal is required.\nIt invalidates the current zle display in preparation for output; typically\nthis will be from a trap function. It has no effect if zle is not\nactive. When a trap exits, the shell checks to see if the display needs\nrestoring, hence the following will print output in such a way as not to\ndisturb the line being edited:\n\nexample(TRAPUSR1() {\n # Invalidate zle display\n [[ -o zle ]] && zle -I\n # Show output\n print Hello\n})\n\nIn general, the trap function may need to test whether zle is active before\nusing this method (as shown in the example), since the `zsh/zle` module\nmay not even be loaded; if it is not, the command can be skipped.\n\nIt is possible to call \"zle -I\" several times before control is\nreturned to the editor; the display will only be invalidated the first time\nto minimise disruption.\n\nNote that there are normally better ways of manipulating the display from\nwithin zle widgets; see, for example, \"zle -R\" above.\n\nThe returned status is zero if zle was invalidated, even though\nthis may have been by a previous call to \"zle -I\" or by a system\nnotification. To test if a zle widget may be called at this point, execute\n`zle` with no arguments and examine the return status.\n\n\n- **`-T`** â This is used to add, list or remove internal transformations on the\nprocessing performed by the line editor. It is typically used only for\ndebugging or testing and is therefore of little interest to the general\nuser.\n\n``zle -T\" _transformation_ _func_\" specifies that the\ngiven _transformation_ (see below) is effected by shell function\n_func_.\n\n``zle -Tr\" _transformation_\" removes the given _transformation_\nif it was present (it is not an error if none was).\n\n\"zle -TL\" can be used to list all transformations currently in\noperation.\n\nCurrently the only transformation is `tc`. This is used instead\nof outputting termcap codes to the terminal. When the transformation is\nin operation the shell function is passed the termcap code that would be\noutput as its first argument; if the operation required a numeric\nargument, that is passed as a second argument. The function should set\nthe shell variable `REPLY` to the transformed termcap code. Typically\nthis is used to produce some simply formatted version of the code and\noptional argument for debugging or testing. Note that this\ntransformation is not applied to other non-printing characters such as\ncarriage returns and newlines.\n\n\n- **_widget_ [ `-n` _num_ ] [ `-f` _flag_ ] [ `-Nw` ] [ `-K` _keymap_ ] _args_ ...** âÂÂ\nInvoke the specified _widget_. This can only be done when ZLE is\nactive; normally this will be within a user-defined widget.\n\nWith the options `-n` and `-N`, the current numeric argument will be\nsaved and then restored after the call to _widget_; ``-n\" _num_\"\nsets the numeric argument temporarily to _num_, while \"-N\" sets it\nto the default, i.e. as if there were none.\n\nWith the option `-K`, _keymap_ will be used as the current keymap\nduring the execution of the widget. The previous keymap will be\nrestored when the widget exits.\n\nNormally, calling a widget in this way does not set the special\nparameter `WIDGET` and related parameters, so that the environment\nappears as if the top-level widget called by the user were still\nactive. With the option `-w`, `WIDGET` and related parameters are set\nto reflect the widget being executed by the `zle` call.\n\nNormally, when _widget_ returns the special parameter `LASTWIDGET` will\npoint to it. This can be inhibited by passing the option `-f nolast`.\n\nAny further arguments will be passed to the widget; note that as\nstandard argument handling is performed, any general argument list\nshould be preceded by `-``-`. If it is a shell\nfunction, these are passed down as positional parameters; for builtin\nwidgets it is up to the widget in question what it does with them.\nCurrently arguments are only handled by the incremental-search commands,\nthe `history-search-forward` and `-backward` and the corresponding\nfunctions prefixed by `vi-`, and by `universal-argument`. No error is\nflagged if the command does not use the arguments, or only uses some of\nthem.\n\nThe return status reflects the success or failure of the operation carried\nout by the widget, or if it is a user-defined widget the return status of\nthe shell function.\n\nA non-zero return status causes the shell to beep when the widget exits,\nunless the `BEEP` options was unset or the widget was called via the\n`zle` command. Thus if a user defined widget requires an immediate beep,\nit should call the `beep` widget directly."),
("BUFFER", "The entire contents of the edit buffer. If it is written to, the\ncursor remains at the same offset, unless that would put it outside the\nbuffer."),
("BUFFERLINES", "The number of screen lines needed for the edit buffer currently\ndisplayed on screen (i.e. without any changes to the preceding\nparameters done after the last redisplay); read-only."),
("CONTEXT", "The context in which zle was called to read a line; read-only. One of\nthe values:\n\n\n- **`start`** â The start of a command line (at prompt `PS1`).\n\n\n- **`cont`** â A continuation to a command line (at prompt `PS2`).\n\n\n- **`select`** â In a `select` loop (at prompt `PS3`).\n\n\n- **`vared`** âÂÂ\nEditing a variable in `vared`."),
("CURSOR", "The offset of the cursor, within the edit buffer. This is in the range\n0 to `$#BUFFER`, and is by definition equal to `$#LBUFFER`.\nAttempts to move the cursor outside the buffer will result in the\ncursor being moved to the appropriate end of the buffer."),
("CUTBUFFER", "The last item cut using one of the \"kill-\" commands; the string\nwhich the next yank would insert in the line. Later entries in\nthe kill ring are in the array `killring`. Note that the\ncommand ``zle copy-region-as-kill\" _string_\" can be used to\nset the text of the cut buffer from a shell function and cycle the kill\nring in the same way as interactively killing text."),
("HISTNO", "The current history number. Setting this has the same effect as\nmoving up or down in the history to the corresponding history line.\nAn attempt to set it is ignored if the line is not stored in the\nhistory. Note this is not the same as the parameter `HISTCMD`,\nwhich always gives the number of the history line being added to the main\nshell's history. `HISTNO` refers to the line being retrieved within\nzle."),
("ISEARCHMATCH_END", "`ISEARCHMATCH_ACTIVE` indicates whether a part of the `BUFFER` is\ncurrently matched by an incremental search pattern. `ISEARCHMATCH_START`\nand `ISEARCHMATCH_END` give the location of the matched part and are\nin the same units as `CURSOR`. They are only valid for reading\nwhen `ISEARCHMATCH_ACTIVE` is non-zero.\n\nAll parameters are read-only."),
("KEYMAP", "The name of the currently selected keymap; read-only."),
("KEYS", "The keys typed to invoke this widget, as a literal string; read-only."),
("KEYS_QUEUED_COUNT", "The number of bytes pushed back to the input queue and therefore\navailable for reading immediately before any I/O is done; read-only.\nSee also `PENDING`; the two values are distinct."),
("killring", "The array of previously killed items, with the most recently killed first.\nThis gives the items that would be retrieved by a `yank-pop` in the\nsame order. Note, however, that the most recently killed item is in\n`$CUTBUFFER`; `$killring` shows the array of previous entries.\n\nThe default size for the kill ring is eight, however the length may be\nchanged by normal array operations. Any empty string in the kill ring is\nignored by the `yank-pop` command, hence the size of the array\neffectively sets the maximum length of the kill ring, while the number of\nnon-zero strings gives the current length, both as seen by the user at the\ncommand line."),
("LASTABORTEDSEARCH", "The last search string used by an interactive search that was\naborted by the user (status 3 returned by the search widget)."),
("LASTSEARCH", "The last search string used by an interactive search; read-only.\nThis is set even if the search failed (status 0, 1 or 2 returned\nby the search widget), but not if it was aborted by the user."),
("LASTWIDGET", "The name of the last widget that was executed; read-only."),
("LBUFFER", "The part of the buffer that lies to the left of the cursor position.\nIf it is assigned to, only that part of the buffer is replaced, and the\ncursor remains between the new `$LBUFFER` and the old `$RBUFFER`."),
("MARK", "Like `CURSOR`, but for the mark. With vi-mode operators that wait for\na movement command to select a region of text, setting `MARK` allows\nthe selection to extend in both directions from the initial cursor\nposition."),
("NUMERIC", "The numeric argument. If no numeric argument was given, this parameter\nis unset. When this is set inside a widget function, builtin widgets\ncalled with the `zle` builtin command will use the value\nassigned. If it is unset inside a widget function, builtin widgets\ncalled behave as if no numeric argument was given."),
("PENDING", "The number of bytes pending for input, i.e. the number of bytes which have\nalready been typed and can immediately be read. On systems where the shell\nis not able to get this information, this parameter will always have a\nvalue of zero. Read-only. See also `KEYS_QUEUED_COUNT`; the two\nvalues are distinct."),
("PREBUFFER", "In a multi-line input at the secondary prompt, this read-only parameter\ncontains the contents of the lines before the one the cursor is\ncurrently in."),
("PREDISPLAY", "Text to be displayed before the start of the editable text buffer. This\ndoes not have to be a complete line; to display a complete line, a newline\nmust be appended explicitly. The text is reset on each new invocation\n(but not recursive invocation) of zle."),
("POSTDISPLAY", "Text to be displayed after the end of the editable text buffer. This\ndoes not have to be a complete line; to display a complete line, a newline\nmust be prepended explicitly. The text is reset on each new invocation\n(but not recursive invocation) of zle."),
("RBUFFER", "The part of the buffer that lies to the right of the cursor position.\nIf it is assigned to, only that part of the buffer is replaced, and the\ncursor remains between the old `$LBUFFER` and the new `$RBUFFER`."),
("REGION_ACTIVE", "Indicates if the region is currently active. It can be assigned 0 or 1\nto deactivate and activate the region respectively. A value of 2\nactivates the region in line-wise mode with the highlighted text\nextending for whole lines only; see\n_Character Highlighting_ (below)."),
("region_highlight", "Each element of this array may be set to a string that describes\nhighlighting for an arbitrary region of the command line that will\ntake effect the next time the command line is redisplayed. Highlighting\nof the non-editable parts of the command line in `PREDISPLAY`\nand `POSTDISPLAY` are possible, but note that the `P` flag\nis needed for character indexing to include `PREDISPLAY`.\n\nEach string consists of the following whitespace-separated parts:\n\nstartitemize()\nitemiz(Optionally, a \"P\" to signify that the start and end offset that\nfollow include any string set by the `PREDISPLAY` special parameter;\nthis is needed if the predisplay string itself is to be highlighted.\nWhitespace between the \"P\" and the start offset is optional.)\nitemiz(A start offset in the same units as `CURSOR`.)\nitemiz(An end offset in the same units as `CURSOR`.)\nitemiz(A highlight specification in the same format as\nused for contexts in the parameter `zle_highlight`, see\n_Character Highlighting_ (below);\nfor example, `standout` or `fg=red,bold`.)\nitemiz(Optionally, a string of the form ``memo=\"_token_\".\nThe _token_ consists of everything between the \"=\" and the next\nwhitespace, comma, NUL, or the end of the string.\nThe _token_ is preserved verbatim but not parsed in any way.\n\nPlugins may use this to identify array elements they have added: for example,\na plugin might set _token_ to its (the plugin's) name and then use\n`tt(region_highlight=+( ${region_highlight:#*memo=)_token_`} +\")\"\nin order to remove array elements it added.\n\n(This example uses the ``${`_name_`:#`_pattern_`}`' array-grepping\nsyntax described in\n_Parameter Expansion_ (zshexpn).))\nenditemize()\n\nFor example,\n\nexample(region_highlight=(\"P0 20 bold memo=foobar\"))\n\nspecifies that the first twenty characters of the text including\nany predisplay string should be highlighted in bold.\n\nNote that the effect of `region_highlight` is not saved and disappears\nas soon as the line is accepted.\n\nNote that zsh 5.8 and older do not support the ``memo=\"_token_\" field\nand may misparse the third (highlight specification) field when a memo\nis given. COMMENT(The syntax \"0 20 bold, memo=foobar\" (with an auxiliary comma)\nhappens to work on both zsh <=5.8 and zsh 5.9, but that seems to be more of\nan accident of implementation than something we should make a first-class-citizen\nAPI promise. It's mentioned in the \"Incompatibilities\" section of README.)\n\nWhere a particular region is covered by multiple entries in\n`region_highlight`, their effects are merged. In the case of conflicts, later\nentries take precedence over earlier ones. This precedence ordering can be\noverridden by specifying layers.\n\nThe final highlighting on the command line depends on both `region_highlight`\nand `zle_highlight`; see\n_Character Highlighting_ (below) for details."),
("registers", "The contents of each of the vi register buffers. These are\ntypically set using `vi-set-buffer` followed by a delete, change or\nyank command."),
("SUFFIX_END", "`SUFFIX_ACTIVE` indicates whether an auto-removable completion suffix\nis currently active. `SUFFIX_START` and `SUFFIX_END` give the\nlocation of the suffix and are in the same units as `CURSOR`. They are\nonly valid for reading when `SUFFIX_ACTIVE` is non-zero.\n\nAll parameters are read-only."),
("UNDO_CHANGE_NO", "A number representing the state of the undo history. The only use\nof this is passing as an argument to the `undo` widget in order to\nundo back to the recorded point. Read-only."),
("UNDO_LIMIT_NO", "A number corresponding to an existing change in the undo history;\ncompare `UNDO_CHANGE_NO`. If this is set to a value greater\nthan zero, the `undo` command will not allow the line to\nbe undone beyond the given change number. It is still possible\nto use ``zle undo\" _change_\" in a widget to undo beyond\nthat point; in that case, it will not be possible to undo at\nall until `UNDO_LIMIT_NO` is reduced. Set to 0 to disable the limit.\n\nA typical use of this variable in a widget function is as follows (note\nthe additional function scope is required):\n\nexample(() {\n local UNDO_LIMIT_NO=$UNDO_CHANGE_NO\n # Perform some form of recursive edit.\n})"),
("WIDGET", "The name of the widget currently being executed; read-only."),
("WIDGETFUNC", "The name of the shell function that implements a widget defined with\neither `zle -N` or `zle -C`. In the former case, this is the second\nargument to the `zle -N` command that defined the widget, or\nthe first argument if there was no second argument. In the latter case\nthis is the third argument to the `zle -C` command that defined the\nwidget. Read-only."),
("WIDGETSTYLE", "Describes the implementation behind the completion widget currently being\nexecuted; the second argument that followed `zle -C` when the widget was\ndefined. This is the name of a builtin completion widget. For widgets\ndefined with `zle -N` this is set to the empty string. Read-only."),
("YANK_END", "`YANK_ACTIVE` indicates whether text has just been yanked (pasted)\ninto the buffer. `YANK_START` and `YANK_END` give the location of\nthe pasted text and are in the same units as `CURSOR`. They are only\nvalid for reading when `YANK_ACTIVE` is non-zero. They can also be\nassigned by widgets that insert text in a yank-like fashion, for example\nwrappers of `bracketed-paste`. See also `zle -f`.\n\n`YANK_ACTIVE` is read-only."),
("ZLE_RECURSIVE", "Usually zero, but incremented inside any instance of\n`recursive-edit`. Hence indicates the current recursion level.\n\n`ZLE_RECURSIVE` is read-only."),
("ZLE_STATE", "Contains a set of space-separated words that describe the current `zle`\nstate.\n\nCurrently, the states shown are the insert mode as set by the\n`overwrite-mode` or `vi-replace` widgets and whether history commands\nwill visit imported entries as controlled by the set-local-history widget.\nThe string contains \"insert\" if characters to be inserted on the\ncommand line move existing characters to the right or \"overwrite\"\nif characters to be inserted overwrite existing characters. It contains\n\"localhistory\" if only local history commands will be visited or\n\"globalhistory\" if imported history commands will also be visited.\n\nThe substrings are sorted in alphabetical order so that if you want to\ntest for two specific substrings in a future-proof way, you can do match\nby doing:\n\n if [[ $ZLE_STATE == *globalhistory*insert* ]]; then ...; fi"),
("zle", "Executed at the end of incremental search at the point where the isearch\nprompt is removed from the display. See `zle-isearch-update` for\nan example."),
("zle", "Executed within incremental search when the display is about to be\nredrawn. Additional output below the incremental search prompt can be\ngenerated by using \"zle -M\" within the widget. For example,\n\nexample(zle-isearch-update+() { zle -M \"Line $HISTNO\"; }\nzle -N zle-isearch-update)\n\nNote the line output by \"zle -M\" is not deleted on exit from\nincremental search. This can be done from a `zle-isearch-exit`\nwidget:\n\nexample(zle-isearch-exit+() { zle -M \"\"; }\nzle -N zle-isearch-exit)"),
("zle", "Executed whenever the input line is about to be redrawn, providing an\nopportunity to update the region_highlight array."),
("zle", "Executed every time the line editor is started to read a new line\nof input. The following example puts the line editor into vi command\nmode when it starts up.\n\nexample(zle-line-init+() { zle -K vicmd; }\nzle -N zle-line-init)\n\n(The command inside the function sets the keymap directly; it is\nequivalent to `zle vi-cmd-mode`.)"),
("zle", "This is similar to `zle-line-init` but is executed every time the\nline editor has finished reading a line of input."),
("zle", "Executed when the history line changes."),
("zle", "Executed every time the keymap changes, i.e. the special parameter\n`KEYMAP` is set to a different value, while the line editor is active.\nInitialising the keymap when the line editor starts does not cause the\nwidget to be called.\n\nThe value `$KEYMAP` within the function reflects the new keymap. The\nold keymap is passed as the sole argument.\n\nThis can be used for detecting switches between the vi command\n(`vicmd`) and insert (usually `main`) keymaps."),
("vi", "Move backward one word, where a word is defined as a series of\nnon-blank characters."),
("vi", "Move to the end of the previous word, where a word is defined as a\nseries of non-blank characters."),
("backward", "Move backward one character."),
("vi", "Move backward one character, without changing lines."),
("backward", "Move to the beginning of the previous word."),
("emacs", "Move to the beginning of the previous word."),
("vi", "Move to the beginning of the previous word, vi-style."),
("vi", "Move to the end of the previous word, vi-style."),
("beginning", "Move to the beginning of the line. If already at the beginning\nof the line, move to the beginning of the previous line, if any."),
("vi", "Move to the beginning of the line, without changing lines."),
("down", "Move down a line in the buffer."),
("end", "Move to the end of the line. If already at the end\nof the line, move to the end of the next line, if any."),
("vi", "Move to the end of the line.\nIf an argument is given to this command, the cursor will be moved to\nthe end of the line (argument - 1) lines down."),
("vi", "Move forward one word, where a word is defined as a series of\nnon-blank characters."),
("vi", "Move to the end of the current word, or, if at the end of the current word,\nto the end of the next word,\nwhere a word is defined as a series of non-blank characters."),
("forward", "Move forward one character."),
("vi", "Move forward one character."),
("vi", "Read a character from the keyboard, and move to\nthe next occurrence of it in the line."),
("vi", "Read a character from the keyboard, and move to\nthe position just before the next occurrence of it in the line."),
("vi", "Read a character from the keyboard, and move to\nthe previous occurrence of it in the line."),
("vi", "Read a character from the keyboard, and move to\nthe position just after the previous occurrence of it in the line."),
("vi", "Move to the first non-blank character in the line."),
("vi", "Move forward one word, vi-style."),
("forward", "Move to the beginning of the next word.\nThe editor's idea of a word is specified with the `WORDCHARS`\nparameter."),
("emacs", "Move to the end of the next word."),
("vi", "Move to the end of the next word."),
("vi", "Move to the column specified by the numeric argument."),
("vi", "Move to the specified mark."),
("vi", "Move to beginning of the line containing the specified mark."),
("vi", "Repeat the last `vi-find` command."),
("vi", "Repeat the last `vi-find` command in the opposite direction."),
("up", "Move up a line in the buffer."),
("beginning", "Move to the beginning of the buffer, or if already there,\nmove to the first event in the history list."),
("beginning", "Move to the beginning of the line. If already at the\nbeginning of the buffer, move to the previous history line."),
("beginning", "Move to the first event in the history list."),
("down", "Move down a line in the buffer, or if already at the bottom line,\nmove to the next event in the history list."),
("vi", "Move down a line in the buffer, or if already at the bottom line,\nmove to the next event in the history list.\nThen move to the first non-blank character on the line."),
("down", "Move down a line in the buffer, or if already at the bottom line,\nsearch forward in the history for a line beginning with the first\nword in the buffer.\n\nIf called from a function by the `zle` command with arguments, the first\nargument is taken as the string for which to search, rather than the\nfirst word in the buffer."),
("down", "Move to the next event in the history list."),
("history", "Search backward in the history for a line beginning with the current\nline up to the cursor.\nThis leaves the cursor in its original position."),
("end", "Move to the end of the buffer, or if already there,\nmove to the last event in the history list."),
("end", "Move to the end of the line. If already at the end of\nthe buffer, move to the next history line."),
("end", "Move to the last event in the history list."),
("vi", "Fetch the history line specified by the numeric argument.\nThis defaults to the current history line\n(i.e. the one that isn't history yet)."),
("history", "Search backward incrementally for a specified string. The search is\ncase-insensitive if the search string does not have uppercase letters and no\nnumeric argument was given. The string may begin with \"^\" to anchor the\nsearch to the beginning of the line. When called from a user-defined\nfunction returns the following statuses: 0, if the search succeeded;\n1, if the search failed; 2, if the search term was a bad pattern;\n3, if the search was aborted by the `send-break` command.\n\nA restricted set of editing functions\nis available in the mini-buffer. Keys are looked up in the special\n`isearch` keymap, and if not found there in the main keymap (note\nthat by default the `isearch` keymap is empty).\nAn interrupt signal, as defined by the stty\nsetting, will stop the search and go back to the original line. An undefined\nkey will have the same effect. Note that the following always\nperform the same task within incremental searches and cannot be\nreplaced by user defined widgets, nor can the set of functions\nbe extended. The supported functions are:\n\n- **`accept-and-hold`**\n\n- **`accept-and-infer-next-history`**\n\n- **`accept-line`**\n\n- **`accept-line-and-down-history`** âÂÂ\nPerform the usual function after exiting incremental search.\nThe command line displayed is executed.\n\n- **`backward-delete-char`**\n\n- **`vi-backward-delete-char`** âÂÂ\nBack up one place in the search history. If the search has been\nrepeated this does not immediately erase a character in the\nminibuffer.\n\n- **`accept-search`** âÂÂ\nExit incremental search, retaining the command line but performing no\nfurther action. Note that this function is not bound by default\nand has no effect outside incremental search.\n\n- **`backward-delete-word`**\n\n- **`backward-kill-word`**\n\n- **`vi-backward-kill-word`** âÂÂ\nBack up one character in the minibuffer; if multiple searches\nhave been performed since the character was inserted the search\nhistory is rewound to the point just before the character was\nentered. Hence this has the effect of repeating\n`backward-delete-char`.\n\n- **`clear-screen`** âÂÂ\nClear the screen, remaining in incremental search mode.\n\n- **`history-incremental-search-backward`** âÂÂ\nFind the next occurrence of the contents of the mini-buffer. If the\nmini-buffer is empty, the most recent previously used search string is\nreinstated.\n\n- **`history-incremental-search-forward`** âÂÂ\nInvert the sense of the search.\n\n- **`magic-space`** âÂÂ\nInserts a non-magical space.\n\n- **`quoted-insert`**\n\n- **`vi-quoted-insert`** âÂÂ\nQuote the character to insert into the minibuffer.\n\n- **`redisplay`** âÂÂ\nRedisplay the command line, remaining in incremental search mode.\n\n\n- **`vi-cmd-mode`** â Select the \"vicmd\" keymap;\nthe \"main\" keymap (insert mode) will be selected initially.\n\nIn addition, the modifications that were made while in vi insert mode are\nmerged to form a single undo event.\n\n\n- **`vi-repeat-search`**\n\n- **`vi-rev-repeat-search`** âÂÂ\nRepeat the search. The direction of the search is indicated in the\nmini-buffer.\n\nAny character that is not bound to one of the above functions, or\n`self-insert` or `self-insert-unmeta`, will cause the mode to be\nexited. The character is then looked up and executed in the keymap in\neffect at that point.\n\nWhen called from a widget function by the `zle` command, the incremental\nsearch commands can take a string argument. This will be treated as a\nstring of keys, as for arguments to the `bindkey` command, and used as\ninitial input for the command. Any characters in the string which are\nunused by the incremental search will be silently ignored. For example,\n\n zle history-incremental-search-backward forceps\n\nwill search backwards for `forceps`, leaving the minibuffer containing\nthe string \"forceps\"."),
("history", "Search forward incrementally for a specified string. The search is\ncase-insensitive if the search string does not have uppercase letters and no\nnumeric argument was given. The string may begin with \"^\" to anchor the\nsearch to the beginning of the line. The functions available in the\nmini-buffer are the same as for `history-incremental-search-backward`."),
("history", "These widgets behave similarly to the corresponding widgets with\nno `-pattern`, but the search string typed by the user is treated\nas a pattern, respecting the current settings of the various options\naffecting pattern matching. See _Filename Generation_ (zshexpn)\nfor a description of patterns.\nIf no numeric argument was given lowercase letters in the search\nstring may match uppercase letters in the history. The string may begin\nwith \"^\" to anchor the search to the beginning of the line.\n\nThe prompt changes to indicate an invalid pattern; this may simply\nindicate the pattern is not yet complete.\n\nNote that only non-overlapping matches are reported, so an expression\nwith wildcards may return fewer matches on a line than are visible\nby inspection."),
("history", "Search backward in the history for a line beginning with the first\nword in the buffer.\n\nIf called from a function by the `zle` command with arguments, the first\nargument is taken as the string for which to search, rather than the\nfirst word in the buffer."),
("vi", "Search backward in the history for a specified string.\nThe string may begin with \"^\" to anchor the search to the\nbeginning of the line.\n\nA restricted set of editing functions is available in\nthe mini-buffer. An interrupt signal, as defined by the stty setting, will\nstop the search.\nThe functions available in the mini-buffer are:\n`accept-line`,\n`backward-delete-char`,\n`vi-backward-delete-char`,\n`backward-kill-word`,\n`vi-backward-kill-word`,\n`clear-screen`,\n`redisplay`,\n`quoted-insert`\nand\n`vi-quoted-insert`.\n\n`vi-cmd-mode` is treated the same as accept-line, and\n`magic-space` is treated as a space.\nAny other character that is not bound to self-insert or\nself-insert-unmeta will beep and be ignored. If the function is called from vi\ncommand mode, the bindings of the current insert mode will be used.\n\nIf called from a function by the `zle` command with arguments, the first\nargument is taken as the string for which to search, rather than the\nfirst word in the buffer."),
("history", "Search forward in the history for a line beginning with the first\nword in the buffer.\n\nIf called from a function by the `zle` command with arguments, the first\nargument is taken as the string for which to search, rather than the\nfirst word in the buffer."),
("vi", "Search forward in the history for a specified string.\nThe string may begin with \"^\" to anchor the search to the\nbeginning of the line. The functions available in the mini-buffer are the same\nas for `vi-history-search-backward`. Argument handling is also the same\nas for that command."),
("infer", "Search in the history list for a line matching the current one and\nfetch the event following it."),
("insert", "Insert the last word from the previous history event at the\ncursor position. If a positive numeric argument is given,\ninsert that word from the end of the previous history event.\nIf the argument is zero or negative insert that word from the\nleft (zero inserts the previous command word). Repeating this command\nreplaces the word just inserted with the last word from the\nhistory event prior to the one just used; numeric arguments can be used in\nthe same way to pick a word from that event.\n\nWhen called from a shell function invoked from a user-defined widget, the\ncommand can take one to three arguments. The first argument specifies a\nhistory offset which applies to successive calls to this widget: if it is -1,\nthe default behaviour is used, while if it is 1, successive calls will move\nforwards through the history. The value 0 can be used to indicate that the\nhistory line examined by the previous execution of the command will be\nreexamined. Note that negative numbers should be preceded by a\n``-\"-\" argument to avoid confusing them with options.\n\nIf two arguments are given, the second specifies the word on the command\nline in normal array index notation (as a more natural alternative to the\nnumeric argument). Hence 1 is the first word, and -1 (the default) is the\nlast word.\n\nIf a third argument is given, its value is ignored, but it is used to\nsignify that the history offset is relative to the current history line,\nrather than the one remembered after the previous invocations of\n`insert-last-word`.\n\nFor example, the default behaviour of the command corresponds to\n\n zle insert-last-word -- -1 -1\n\nwhile the command\n\n zle insert-last-word -- -1 1 -\n\nalways copies the first word of the line in the history immediately before\nthe line being edited. This has the side effect that later invocations of\nthe widget will be relative to that line."),
("vi", "Repeat the last vi history search."),
("vi", "Repeat the last vi history search, but in reverse."),
("up", "Move up a line in the buffer, or if already at the top line,\nmove to the previous event in the history list."),
("vi", "Move up a line in the buffer, or if already at the top line,\nmove to the previous event in the history list.\nThen move to the first non-blank character on the line."),
("up", "Move up a line in the buffer, or if already at the top line,\nsearch backward in the history for a line beginning with the\nfirst word in the buffer.\n\nIf called from a function by the `zle` command with arguments, the first\nargument is taken as the string for which to search, rather than the\nfirst word in the buffer."),
("up", "Move to the previous event in the history list."),
("history", "Search forward in the history for a line beginning with the current\nline up to the cursor.\nThis leaves the cursor in its original position."),
("set", "By default, history movement commands visit the imported lines as well as\nthe local lines. This widget lets you toggle this on and off, or set it with\nthe numeric argument. Zero for both local and imported lines and nonzero for\nonly local lines."),
("vi", "Move to the end of the line and enter insert mode."),
("vi", "Enter insert mode after the current cursor position, without changing lines."),
("backward", "Delete the character behind the cursor."),
("vi", "Delete the character behind the cursor, without changing lines.\nIf in insert mode, this won't delete past the point where insert mode was\nlast entered."),
("backward", "Delete the word behind the cursor."),
("backward", "Kill from the beginning of the line to the cursor position."),
("backward", "Kill the word behind the cursor."),
("vi", "Kill the word behind the cursor, without going past the point where insert\nmode was last entered."),
("capitalize", "Capitalize the current word and move past it."),
("vi", "Read a movement command from the keyboard, and kill\nfrom the cursor position to the endpoint of the movement.\nThen enter insert mode.\nIf the command is `vi-change`, change the current line.\n\nFor compatibility with vi, if the command is `vi-forward-word`\nor `vi-forward-blank-word`, the whitespace after the word is not\nincluded. If you prefer the more consistent behaviour with the\nwhitespace included use the following key binding:\n\n bindkey -a -s cw dwi"),
("vi", "Kill to the end of the line and enter insert mode."),
("vi", "Kill the current line and enter insert mode."),
("copy", "Copy the area from the cursor to the mark to the kill buffer.\n\nIf called from a ZLE widget function in the form ``zle\ncopy-region-as-kill\" _string_\" then _string_ will be taken as the\ntext to copy to the kill buffer. The cursor, the mark and the text on the\ncommand line are not used in this case."),
("copy", "Duplicate the word to the left of the cursor."),
("copy", "Like `copy-prev-word`, but the word is found by using shell parsing,\nwhereas `copy-prev-word` looks for blanks. This makes a difference\nwhen the word is quoted and contains spaces."),
("vi", "Read a movement command from the keyboard, and kill\nfrom the cursor position to the endpoint of the movement.\nIf the command is `vi-delete`, kill the current line."),
("delete", "Delete the character under the cursor."),
("vi", "Delete the character under the cursor,\nwithout going past the end of the line."),
("delete", "Delete the current word."),
("down", "Convert the current word to all lowercase and move past it."),
("vi", "Read a movement command from the keyboard, and convert all characters\nfrom the cursor position to the endpoint of the movement to lowercase.\nIf the movement command is `vi-down-case`, swap the case of all\ncharacters on the current line."),
("kill", "Kill the current word."),
("gosmacs", "Exchange the two characters behind the cursor."),
("vi", "Indent a number of lines."),
("vi", "Enter insert mode."),
("vi", "Move to the first non-blank character on the line and enter insert mode."),
("vi", "Join the current line with the next one."),
("kill", "Kill from the cursor to the end of the line.\nIf already on the end of the line, kill the newline character."),
("vi", "Kill from the cursor back to wherever insert mode was last entered."),
("vi", "Kill from the cursor to the end of the line."),
("kill", "Kill from the cursor to the mark."),
("kill", "Kill the entire buffer."),
("kill", "Kill the current line."),
("vi", "Move to the bracket character (one of `{}`, tt(()) or `[]`) that\nmatches the one under the cursor.\nIf the cursor is not on a bracket character, move forward without going\npast the end of the line to find one, and then go to the matching bracket."),
("vi", "Open a line above the cursor and enter insert mode."),
("vi", "Open a line below the cursor and enter insert mode."),
("vi", "Read a movement command from the keyboard, and swap\nthe case of all characters\nfrom the cursor position to the endpoint of the movement.\nIf the movement command is `vi-oper-swap-case`,\nswap the case of all characters on the current line."),
("overwrite", "Toggle between overwrite mode and insert mode."),
("vi", "Insert the contents of the kill buffer before the cursor.\nIf the kill buffer contains a sequence of lines (as opposed to characters),\npaste it above the current line."),
("vi", "Insert the contents of the kill buffer after the cursor.\nIf the kill buffer contains a sequence of lines (as opposed to characters),\npaste it below the current line."),
("put", "Replace the contents of the current region or selection with the\ncontents of the kill buffer. If the kill buffer contains a sequence of\nlines (as opposed to characters), the current line will be split by the\npasted lines."),
("quoted", "Insert the next character typed into the buffer literally.\nAn interrupt character will not be inserted."),
("vi", "Display a \"^\" at the cursor position, and\ninsert the next character typed into the buffer literally.\nAn interrupt character will not be inserted."),
("quote", "Quote the current line; that is, put a ``'`' character at the\nbeginning and the end, and convert all ``'`' characters\nto ``'\\''`'."),
("quote", "Quote the region from the cursor to the mark."),
("vi", "Enter overwrite mode."),
("vi", "Repeat the last vi mode text modification.\nIf a count was used with the modification, it is remembered.\nIf a count is given to this command, it overrides the remembered count,\nand is remembered for future uses of this command.\nThe cut buffer specification is similarly remembered."),
("vi", "Replace the character under the cursor with a character\nread from the keyboard."),
("self", "Insert a character into the buffer at the cursor position."),
("self", "Insert a character into the buffer after stripping the meta bit\nand converting ^M to ^J."),
("vi", "Substitute the next characte+CHAR(r)(s)."),
("vi", "Swap the case of the character under the cursor and move past it."),
("transpose", "Exchange the two characters to the left of the\ncursor if at end of line, else exchange the\ncharacter under the cursor with the character\nto the left."),
("transpose", "Exchange the current word with the one before it.\n\nWith a positive numeric argument _N_, the word around the cursor, or\nfollowing it if the cursor is between words, is transposed with the\npreceding _N_ words. The cursor is put at the end of the resulting\ngroup of words.\n\nWith a negative numeric argument _-N_, the effect is the same as using\na positive argument _N_ except that the original cursor position is\nretained, regardless of how the words are rearranged."),
("vi", "Unindent a number of lines."),
("vi", "Read a movement command from the keyboard, and convert all characters\nfrom the cursor position to the endpoint of the movement to lowercase.\nIf the movement command is `vi-up-case`, swap the case of all\ncharacters on the current line."),
("up", "Convert the current word to all caps and move past it."),
("yank", "Insert the contents of the kill buffer at the cursor position."),
("yank", "Remove the text just yanked, rotate the kill-ring (the history of\npreviously killed text) and yank the new top. Only works following\n`yank`, `vi-put-before`, `vi-put-after` or `yank-pop`."),
("vi", "Read a movement command from the keyboard, and copy the region\nfrom the cursor position to the endpoint of the movement\ninto the kill buffer.\nIf the command is `vi-yank`, copy the current line."),
("vi", "Copy the current line into the kill buffer."),
("vi", "Copy the region from the cursor position to the end of the line\ninto the kill buffer.\nArguably, this is what Y should do in vi, but it isn't what it actually does."),
("digit", "Start a new numeric argument, or add to the current one.\nSee also `vi-digit-or-beginning-of-line`. This only works if bound to a\nkey sequence ending in a decimal digit.\n\nInside a widget function, a call to this function treats the last key of\nthe key sequence which called the widget as the digit."),
("neg", "Changes the sign of the following argument."),
("universal", "Multiply the argument of the next command by 4. Alternatively, if\nthis command is followed by an integer (positive or negative), use\nthat as the argument for the next command. Thus digits cannot be\nrepeated using this command. For example, if this command occurs\ntwice, followed immediately by `forward-char`, move forward sixteen\nspaces; if instead it is followed by `-2`, then `forward-char`,\nmove backward two spaces.\n\nInside a widget function, if passed an argument, i.e. ``zle\nuniversal-argument\" _num_\", the numeric argument will be set to\n_num_; this is equivalent to ``NUMERIC=\"_num_\"."),
("argument", "Use the existing numeric argument as a numeric base, which must be in the\nrange 2 to 36 inclusive. Subsequent use of `digit-argument` and\n`universal-argument` will input a new numeric argument in the given base.\nThe usual hexadecimal convention is used: the letter `a` or `A`\ncorresponds to 10, and so on. Arguments in bases requiring digits from 10\nupwards are more conveniently input with `universal-argument`, since\n`ESC-a` etc. are not usually bound to `digit-argument`.\n\nThe function can be used with a command argument inside a user-defined\nwidget. The following code sets the base to 16 and lets the user input a\nhexadecimal argument until a key out of the digit range is typed:\n\n zle argument-base 16\nzle universal-argument"),
("accept", "In a menu completion, insert the current completion into the buffer,\nand advance to the next possible completion."),
("complete", "Attempt completion on the current word."),
("delete", "Delete the character under the cursor. If the cursor\nis at the end of the line, list possible completions for the\ncurrent word."),
("expand", "Expand the current command to its full pathname."),
("expand", "Attempt shell expansion on the current word.\nIf that fails,\nattempt completion."),
("expand", "Attempt shell expansion on the current word up to cursor."),
("expand", "Perform history expansion on the edit buffer."),
("expand", "Attempt shell expansion on the current word."),
("list", "List possible completions for the current word."),
("list", "List the expansion of the current word."),
("magic", "Perform history expansion and insert a space into the\nbuffer. This is intended to be bound to space."),
("menu", "Like `complete-word`, except that menu completion is used.\nSee the `MENU_COMPLETE` option."),
("menu", "Like `expand-or-complete`, except that menu completion is used."),
("reverse", "Perform menu completion, like `menu-complete`, except that if\na menu completion is already in progress, move to the _previous_\ncompletion rather than the next."),
("end", "When a previous completion displayed a list below the prompt, this\nwidget can be used to move the prompt below the list."),
("accept", "Push the contents of the buffer on the buffer stack\nand execute it."),
("accept", "Execute the contents of the buffer.\nThen search the history list for a line matching the current one\nand push the event following onto the buffer stack."),
("accept", "Finish editing the buffer. Normally this causes the buffer to be\nexecuted as a shell command."),
("accept", "Execute the current line, and push the next history\nevent on the buffer stack."),
("auto", "If the previous action added a suffix (space, slash, etc.) to the word on\nthe command line, remove it. Otherwise do nothing. Removing the suffix\nends any active menu completion or menu selection.\n\nThis widget is intended to be called from user-defined widgets to enforce\na desired suffix-removal behavior."),
("auto", "If the previous action added a suffix (space, slash, etc.) to the word on\nthe command line, force it to be preserved. Otherwise do nothing.\nRetaining the suffix ends any active menu completion or menu selection.\n\nThis widget is intended to be called from user-defined widgets to enforce\na desired suffix-preservation behavior."),
("beep", "Beep, unless the `BEEP` option is unset."),
("bracketed", "This widget is invoked when text is pasted to the terminal emulator. It\nis not intended to be bound to actual keys but instead to the special\nsequence generated by the terminal emulator when text is pasted.\n\nWhen invoked interactively, the pasted text is inserted to the buffer\nand placed in the cutbuffer.\nIf a numeric argument is given, shell quoting will be applied to the\npasted text before it is inserted.\n\nWhen a named buffer is specified with `vi-set-buffer` (`\"x`),\nthe pasted text is stored in that named buffer but not inserted.\n\nWhen called from a widget function as ``bracketed-paste` _name_`, the\npasted text is assigned to the variable _name_ and no other processing is\ndone.\n\nSee also the `zle_bracketed_paste` parameter."),
("vi", "Enter command mode; that is, select the \"vicmd\" keymap.\nYes, this is bound by default in emacs mode."),
("vi", "Hang until any lowercase key is pressed.\nThis is for vi users without the mental capacity to keep\ntrack of their caps lock key (like the author)."),
("clear", "Clear the screen and redraw the prompt."),
("deactivate", "Make the current region inactive. This disables vim-style visual\nselection mode if it is active."),
("describe", "Reads a key sequence, then prints the function bound to that sequence."),
("exchange", "Exchange the cursor position (point) with the position of the mark.\nUnless a negative numeric argument is given, the region between\npoint and mark is activated so that it can be highlighted.\nIf a zero numeric argument is given, the region is activated but\npoint and mark are not swapped."),
("execute", "Read the name of an editor command and execute it. Aliasing this\nwidget with \"zle -A\" or replacing it with \"zle -N\" has no\neffect when interpreting key bindings, but \"zle execute-named-cmd\"\nwill invoke such an alias or replacement.\n\nA restricted set of editing functions is available in the\nmini-buffer. Keys are looked up in the special\n`command` keymap, and if not found there in the main keymap.\nAn interrupt signal, as defined by the stty setting, will\nabort the function. Note that the following always\nperform the same task within the `executed-named-cmd` environment and\ncannot be replaced by user defined widgets, nor can the set of functions\nbe extended. The allowed functions are:\n`backward-delete-char`,\n`vi-backward-delete-char`,\n`clear-screen`,\n`redisplay`,\n`quoted-insert`,\n`vi-quoted-insert`,\n`backward-kill-word`,\n`vi-backward-kill-word`,\n`kill-whole-line`,\n`vi-kill-line`,\n`backward-kill-line`,\n`list-choices`,\n`delete-char-or-list`,\n`complete-word`,\n`accept-line`,\n`expand-or-complete` and\n`expand-or-complete-prefix`.\n\n`kill-region` kills the last word,\nand vi-cmd-mode is treated the same as accept-line.\nThe space and tab characters, if not bound to one of\nthese functions, will complete the name and then list the\npossibilities if the `AUTO_LIST` option is set.\nAny other character that is not bound to `self-insert` or\n`self-insert-unmeta` will beep and be ignored.\nThe bindings of the current insert mode will be used.\n\nCurrently this command may not be redefined or called by name."),
("execute", "Redo the last function executed with `execute-named-cmd`.\n\nLike `execute-named-cmd`, this command may not be redefined,\nbut it may be called by name."),
("get", "Pop the top line off the buffer stack and insert it at the\ncursor position."),
("pound", "If there is no # character at the beginning of the buffer,\nadd one to the beginning of each line.\nIf there is one, remove a # from each line that has one.\nIn either case, accept the current line.\nThe `INTERACTIVE_COMMENTS` option must be set\nfor this to have any usefulness."),
("vi", "If there is no # character at the beginning of the current line,\nadd one. If there is one, remove it.\nThe `INTERACTIVE_COMMENTS` option must be set\nfor this to have any usefulness."),
("push", "Push the entire current multiline construct onto the buffer stack and\nreturn to the top-level (`PS1`) prompt.\nIf the current parser construct is only a single line, this is exactly\nlike `push-line`.\nNext time the editor starts up or is popped with `get-line`, the\nconstruct will be popped off the top of the buffer stack and loaded\ninto the editing buffer."),
("push", "Push the current buffer onto the buffer stack and clear\nthe buffer.\nNext time the editor starts up, the buffer will be popped\noff the top of the buffer stack and loaded into the editing\nbuffer."),
("push", "At the top-level (`PS1`) prompt, equivalent to `push-line`.\nAt a secondary (`PS2`) prompt, move the entire current multiline\nconstruct into the editor buffer.\nThe latter is equivalent to `push-input` followed by `get-line`."),
("read", "Only useful from a user-defined widget. A keystroke is read just as in\nnormal operation, but instead of the command being executed the name\nof the command that would be executed is stored in the shell parameter\n`REPLY`. This can be used as the argument of a future `zle`\ncommand. If the key sequence is not bound, status 1 is returned;\ntypically, however, `REPLY` is set to `undefined-key` to indicate\na useless key sequence."),
("recursive", "Only useful from a user-defined widget. At this point in the function,\nthe editor regains control until one of the standard widgets which would\nnormally cause zle to exit (typically an `accept-line` caused by\nhitting the return key) is executed. Instead, control returns to the\nuser-defined widget. The status returned is non-zero if the return was\ncaused by an error, but the function still continues executing and hence\nmay tidy up. This makes it safe for the user-defined widget to alter\nthe command line or key bindings temporarily.\n\nThe following widget, `caps-lock`, serves as an example.\n\nexample(self-insert-ucase+() {\n LBUFFER+=${(U)KEYS[-1]}\n}\n\ninteger stat\n\nzle -N self-insert self-insert-ucase\nzle -A caps-lock save-caps-lock\nzle -A accept-line caps-lock\n\nzle recursive-edit\nstat=$?\n\nzle -A .self-insert self-insert\nzle -A save-caps-lock caps-lock\nzle -D save-caps-lock\n\n(( stat )) && zle send-break\n\nreturn $stat)\n\nThis causes typed letters to be inserted capitalised until either\n`accept-line` (i.e. typically the return key) is typed or the\n`caps-lock` widget is invoked again; the later is handled by saving\nthe old definition of `caps-lock` as `save-caps-lock` and then\nrebinding it to invoke `accept-line`. Note that an error from the\nrecursive edit is detected as a non-zero return status and propagated by\nusing the `send-break` widget."),
("redisplay", "Redisplays the edit buffer."),
("reset", "Force the prompts on both the left and right of the screen to be\nre-expanded, then redisplay the edit buffer. This\nreflects changes both to the prompt variables themselves and changes\nin the expansion of the values (for example, changes in time or\ndirectory, or changes to the value of variables referred to by the\nprompt).\n\nOtherwise, the prompt is only expanded each time zle starts, and\nwhen the display has been interrupted by output from another part of the\nshell (such as a job notification) which causes the command line to be\nreprinted.\n\n`reset-prompt\" doesn\"t alter the special parameter `LASTWIDGET`."),
("send", "Abort the current editor function, e.g. `execute-named-command`, or the\neditor itself, e.g. if you are in `vared`. Otherwise abort the parsing of\nthe current line; in this case the aborted line is available in the shell\nvariable `ZLE_LINE_ABORTED`. If the editor is aborted from within\n`vared`, the variable `ZLE_VARED_ABORTED` is set."),
("run", "Push the buffer onto the buffer stack, and execute the\ncommand ``run-help\" _cmd_\", where _cmd_ is the current\ncommand. `run-help` is normally aliased to `man`."),
("vi", "Specify a buffer to be used in the following command.\nThere are 39 buffers that can be specified:\nthe 26 \"named\" buffers `\"a` to `\"z`, the \"yank\" buffer `\"0`,\nthe nine \"queued\" buffers `\"1` to `\"9`, the \"black hole\" buffer\n`\"_` and the system selection `\"*` and clipboard `\"+`.\nThe named buffers can also be specified as `\"A` to `\"Z`.\n\nWhen a buffer is specified for a cut, change or yank command, the text\nconcerned replaces the previous contents of the specified buffer. If\na named buffer is specified using a capital, the newly cut text is\nappended to the buffer instead of overwriting it. When using the `\"_`\nbuffer, nothing happens. This can be useful for deleting text without\naffecting any buffers.\n\nAccessing and updating the system clipboard relies on specific support from\nthe terminal.\n\nIf no buffer is specified for a cut or change command, `\"1` is used, and\nthe contents of `\"1` to `\"8` are each shifted along one buffer;\nthe contents of `\"9` is lost. If no buffer is specified for a yank\ncommand, `\"0` is used. Finally, a paste command without a specified\nbuffer will paste the text from the most recent command regardless of any\nbuffer that might have been used with that command.\n\nWhen called from a widget function by the `zle` command, the buffer\ncan optionally be specified with an argument. For example,\n\n zle vi-set-buffer A"),
("vi", "Set the specified mark at the cursor position."),
("set", "Set the mark at the cursor position. If called with a negative\nnumeric argument, do not set the mark but deactivate the region so that\nit is no longer highlighted (it is still usable for other purposes).\nOtherwise the region is marked as active."),
("spell", "Attempt spelling correction on the current word."),
("split", "Breaks the undo sequence at the current change. This is useful in vi mode as\nchanges made in insert mode are coalesced on entering command mode. Similarly,\n`undo` will normally revert as one all the changes made by a user-defined\nwidget."),
("undefined", "This command is executed when a key sequence that is not bound to any\ncommand is typed. By default it beeps."),
("undo", "Incrementally undo the last text modification. When called from a\nuser-defined widget, takes an optional argument indicating a previous state\nof the undo history as returned by the `UNDO_CHANGE_NO` variable;\nmodifications are undone until that state is reached, subject to\nany limit imposed by the `UNDO_LIMIT_NO` variable.\n\nNote that when invoked from vi command mode, the full prior change made in\ninsert mode is reverted, the changes having been merged when command mode was\nselected."),
("redo", "Incrementally redo undone text modifications."),
("vi", "Undo the last text modification.\nIf repeated, redo the modification."),
("visual", "Toggle vim-style visual selection mode. If line-wise visual mode is\ncurrently enabled then it is changed to being character-wise. If used\nfollowing an operator, it forces the subsequent movement command to be\ntreated as a character-wise movement."),
("visual", "Toggle vim-style line-wise visual selection mode. If character-wise\nvisual mode is currently enabled then it is changed to being line-wise. If used\nfollowing an operator, it forces the subsequent movement command to be\ntreated as a line-wise movement."),
("what", "Print the character under the cursor, its code as an octal, decimal and\nhexadecimal number, the current cursor position within the buffer and the\ncolumn of the cursor in the current line."),
("where", "Read the name of an editor command and print the listing of key\nsequences that invoke the specified command.\nA restricted set of editing functions is available in the\nmini-buffer. Keys are looked up in the special\n`command` keymap, and if not found there in the main keymap."),
("which", "Push the buffer onto the buffer stack, and execute the\ncommand ``which-command\" _cmd_\", where _cmd_ is the current\ncommand. `which-command` is normally aliased to `whence`."),
("vi", "If the last command executed was a digit as part of an argument,\ncontinue the argument. Otherwise, execute vi-beginning-of-line."),
("select", "Select a word including adjacent blanks, where a word is defined as a\nseries of non-blank characters. With a numeric argument, multiple words\nwill be selected."),
("select", "Select the current command argument applying the normal rules for\nquoting."),
("select", "Select a word including adjacent blanks, using the normal vi-style word\ndefinition. With a numeric argument, multiple words will be selected."),
("select", "Select a word, where a word is defined as a series of non-blank\ncharacters. With a numeric argument, multiple words will be selected."),
("select", "Select the current command argument applying the normal rules for\nquoting. If the argument begins and ends with matching quote characters,\nthese are not included in the selection."),
("select", "Select a word, using the normal vi-style word definition. With a numeric\nargument, multiple words will be selected."),
("bracketed", "Many terminal emulators have a feature that allows applications to identify\nwhen text is pasted into the terminal rather than being typed normally. For\nZLE, this means that special characters such as tabs and newlines can be\ninserted instead of invoking editor commands. Furthermore, pasted text forms a\nsingle undo event and if the region is active, pasted text will replace the\nregion."),
("cursor", "Support for changing the color of the cursor."),
("cursor", "Support for changing the shape of the cursor."),
("integration", "This provides the terminal with semantic information regarding where the output\nfrom commands start and finish. Some terminals use this information to make it\neasy to select just the output from a single command."),
("integration", "This informs the terminal when the shell displays a prompt. This enables a\nvariety of terminal features such as displaying markers, allowing you to jump\nto previous commands in the scroll-back buffer and ensuring that right prompts\nare handled correctly when the window is resized. The end of the prompt also\nprovides the terminal with a marker for the start of user input."),
("integration", "This advises the terminal of the shell's current directory which allows it\nto create new windows with the same current working directory."),
("query", "Query the terminal background color which is used for `.term.bg` and\n`.term.mode`."),
("query", "Query the cursor color. This facilitates restoring the cursor to its original\ncolor if it has been configured via `zle_cursorform`. The color is also\nassigned to `.term.cursor`."),
("query", "Query the terminal foreground color which is used for `.term.fg`."),
("query", "Query the terminal identification which is used for `.term.id` and\n`.term.version`."),
("query", "Support for the kitty keyboard handling protocol which enables reporting of a\nwider range of key combinations and resolves problems with ambiguous key\nsequences. Currently there is only support for detecting whether the terminal\nsupports this feature."),
("modkeys", "Support for the keyboard handling sequences associated with xterm's\n`modifyOtherKeys` X resource. This enables reporting of a wider range of key\ncombinations and resolves some problems with ambiguous key sequences."),
("query", "Support for 24-bit truecolor escape sequences. Auto-detection also tries\ntermcap and the `COLORTERM` environment variable."),
("default", "Any text within the command line not affected by any other highlighting.\nText outside the editable area of the command line is not affected."),
("isearch", "When one of the incremental history search widgets is active, the\narea of the command line matched by the search string or pattern."),
("region", "The currently selected text. In emacs terminology, this is referred to as\nthe region and is bounded by the cursor (point) and the mark. The region\nis only highlighted if it is active, which is the case after the mark\nis modified with `set-mark-command` or `exchange-point-and-mark`.\nNote that whether or not the region is active has no effect on its\nuse within emacs style widgets, it simply determines whether it is\nhighlighted. In vi mode, the region corresponds to selected text in\nvisual mode."),
("special", "Individual characters that have no direct printable\nrepresentation but are shown in a special manner by the line editor.\nThese characters are described below."),
("suffix", "This context is used in completion for characters that are\nmarked as suffixes that will be removed if the completion ends\nat that point, the most obvious example being a slash (`/`) after\na directory name. Note that suffix removal is configurable; the\ncircumstances under which the suffix will be removed may differ\nfor different completions."),
("paste", "Following a command to paste text, the characters that were inserted."),
("ellipsis", "Markers used to indicate where the text doesn't fit within the terminal."),
("fg_start_code", "The start of the escape sequence for the foreground colour.\nThis is followed by one to three ASCII digits representing the colour.\nOnly used for palette colors, i.e. not 24-bit colors specified via a\ncolor triplet."),
("fg_default_code", "The number to use instead of the colour to reset the default foreground\ncolour."),
("fg_end_code", "The end of the escape sequence for the foreground colour."),
("bg_start_code", "The start of the escape sequence for the background colour.\nSee `fg_start_code` above."),
("bg_default_code", "The number to use instead of the colour to reset the default\nbackground colour."),
("bg_end_code", "The end of the escape sequence for the background colour."),
("none", "No additional highlighting is applied to the given context. It is not\nuseful for this to appear with other types of highlighting; it is used to\noverride a default. Any inherited highlighting is retained so for example,\nwith `region:none`, highlighting associated with `default` is still used\nfor the region."),
("reset", "The terminal's default highlighting is applied to the given context.\nThis can be useful as a way to clear all inherited highlighting, so\nmay be used before naming other types of highlighting."),
("fg", "The foreground colour should be set to _colour_, a decimal integer,\nthe name of one of the eight most widely-supported colours or as a\n\"#\" followed by an RGB triplet in hexadecimal format.\n\nNot all terminals support this and, of those that do, not all provide\nfacilities to test the support, hence the user should decide based on the\nterminal type. Most terminals support the colours `black`, `red`,\n`green`, `yellow`, `blue`, `magenta`, `cyan` and `white`,\nwhich can be set by name. In addition. `default` may be used to\nset the terminal's default foreground colour. Abbreviations are allowed;\n`b` or `bl` selects black. Some terminals may generate additional\ncolours if the `bold` attribute is also present.\n\nOn recent terminals and on systems with an up-to-date terminal database the\nnumber of colours supported may be tested by the command ``echotc\nCo`'; if this succeeds, it indicates a limit on the number of colours which\nwill be enforced by the line editor. The number of colours is in any case\nlimited to 256 (i.e. the range 0 to 255).\n\nSome modern terminal emulators have support for 24-bit true colour (16\nmillion colours). In this case, the hex triplet format can be used. This\nconsists of a \"#\" followed by either a three or six digit hexadecimal\nnumber describing the red, green and blue components of the colour. Hex\ntriplets can also be used with 88 and 256 colour terminals via the\n`zsh/nearcolor` module (see nmref(The zsh/nearcolor Module)(zshmodules)).\n\nColour is also known as color."),
("bg", "The background colour should be set to _colour_.\nThis works similarly to the foreground colour, except the background is\nnot usually affected by the bold attribute."),
("bold", "The characters in the given context are shown with a bold font weight.\nNot all terminals distinguish bold fonts."),
("faint", "The characters in the given context are shown with a faint font weight.\nNot all terminals distinguish faint fonts."),
("standout", "The characters in the given context are shown in the terminal's standout\nmode. The actual effect is specific to the terminal; on many terminals it\nis inverse video. On some such terminals, where the cursor does not blink\nit appears with standout mode negated, making it less than clear where\nthe cursor actually is. On such terminals one of the other effects\nmay be preferable for highlighting the region and matched search string."),
("underline", "The characters in the given context are shown underlined. Some\nterminals show the foreground in a different colour instead; in this\ncase whitespace will not be highlighted."),
("italic", "The characters in the given context are shown in a italic font.\nNot all terminals support italic fonts."),
("hl", "Use the specified highlighting group. The _group_ is used as a key into\nthe associative array `.zle.hlgroups` to determine the actual highlighting."),
("layer", "The layer is used to determine precedence when multiple highlighting regions\noverlap. The _layer_ is a decimal integer, with higher numbers taking\nprecedence over lower numbers. This cannot be used with the `default` and\n`ellipsis` fields of `zle_highlight` because they treated as base layers.\nWith the other fields 30 applies by default for `special`, 20 for `region`\nand `isearch` and 15 for `paste`. Highlighting defined in\n`region_highlight` defaults to layer 10 and would take precedence over\nhighlighting for any fields of `zle_highlight` that are assigned to the same\nlayer."),
("opacity", "Instead of replacing colors in higher layers, the colors can be mixed. The\nopacity is specified as a percentage where `0%` is fully transparent and\n`100%` represents the default behavior of replacing the underlying colour.\nIf a single value is specified, it applies to both foreground and background."),
("command", "Used for vi normal mode."),
("edit", "The default form used in the line editor and for editing text in emacs\nmode."),
("insert", "Used for vi editing mode."),
("overwrite", "Used when editing text in overwrite mode or with the vi replace command."),
("pending", "Used where the line editor is waiting for a single key press such as the vi\noperator pending mode widget."),
("region", "Applied for both `regionstart` and `regionend` contexts."),
("regionstart", "Used when the region is active and the cursor is positioned at the start of the\nregion. The region includes the text under the cursor when it is positioned at\nthe start so it is best to configure the cursor so that it does not obscure\nthis fact."),
("regionend", "Used when the region is active and the cursor is positioned at the end of the\nregion. Note that when this is the case, the region does not include the cursor\nposition."),
("visual", "Used when vi visual mode is active. The visual selection always includes the\ncursor position so the same advice as for `regionstart` applies."),
("compdef", "The first form defines the _function_ to call for completion in the\ngiven contexts as described for the `#compdef` tag above.\n\nAlternatively, all the arguments may have the form\n`_cmd_`=\"_service_\". Here _service_ should already have been\ndefined by `_cmd1_`=\"_service_\" lines in `#compdef` files, as\ndescribed above. The argument for _cmd_ will be completed in the\nsame way as _service_.\n\nThe _function_ argument may alternatively be a string containing\nalmost any shell code. If the string contains an equal sign, the above\nwill take precedence. The option `-e` may be used to specify the first\nargument is to be evaluated as shell code even if it contains an equal\nsign. The string will be executed using the `eval` builtin command to\ngenerate completions. This provides a way of avoiding having to define\na new completion function. For example, to complete files ending in\n\".h\" as arguments to the command `foo`:\n\n compdef '_files -g \"*.h\"' foo\n\nThe option `-n` prevents any completions already defined for the\ncommand or context from being overwritten.\n\nThe option `-d` deletes any completion defined for the command or\ncontexts listed.\n\nThe _name_s may also contain `-p`, `-P` and `-N` options as\ndescribed for the `#compdef` tag. The effect on the argument list is\nidentical, switching between definitions of patterns tried initially,\npatterns tried finally, and normal commands and contexts.\n\nThe parameter `$_compskip` may be set by any function defined for a\npattern context. If it is set to a value containing the substring\n\"patterns\" none of the pattern-functions will be called; if it is\nset to a value containing the substring \"all\", no other function\nwill be called. Setting `$_compskip` in this manner is of particular\nutility when using the `-p` option, as otherwise the dispatcher will\nmove on to additional functions (likely the default one) after calling\nthe pattern-context one, which can mangle the display of completion\npossibilities if not handled properly.\n\nThe form with `-k` defines a widget with the same name as the _function_\nthat will be called for each of the _key-sequence_s; this is like the\n`#compdef -k` tag. The function should generate the completions needed\nand will otherwise behave like the builtin widget whose name is given as\nthe _style_ argument. The widgets usable for this are:\n`complete-word`, `delete-char-or-list`, `expand-or-complete`,\n`expand-or-complete-prefix`, `list-choices`, `menu-complete`,\n`menu-expand-or-complete`, and `reverse-menu-complete`, as well as\n`menu-select` if the `zsh/complist` module is loaded. The option `-n`\nprevents the key being bound if it is already to bound to something other\nthan `undefined-key`.\n\nThe form with `-K` is similar and defines multiple widgets based on the\nsame _function_, each of which requires the set of three arguments\n_name_, _style_ and _key-seq_uence, where the latter two are as\nfor `-k` and the first must be a unique widget name beginning with an\nunderscore.\n\nWherever applicable, the `-a` option makes the _function_\nautoloadable, equivalent to `autoload -U `_function_."),
("accounts", "used to look up the `users-hosts` style"),
("all", "used by the `_expand` completer when adding the single string containing\nall possible expansions"),
("all", "for the names of all files (as distinct from a particular subset, see the\n`globbed-files` tag)."),
("arguments", "for arguments to a command"),
("arrays", "for names of array parameters"),
("association", "for keys of associative arrays; used when completing inside a\nsubscript to a parameter of this type"),
("bookmarks", "when completing bookmarks (e.g. for URLs and the `zftp` function suite)"),
("builtins", "for names of builtin commands"),
("characters", "for single characters in arguments of commands such as `stty`. Also used\nwhen completing character classes after an opening bracket"),
("colormapids", "for X colormap ids"),
("colors", "for color names"),
("commands", "for names of external commands. Also used by complex commands such as\n`cvs` when completing names subcommands."),
("contexts", "for contexts in arguments to the `zstyle` builtin command"),
("corrections", "used by the `_approximate` and `_correct` completers for possible\ncorrections"),
("cursors", "for cursor names used by X programs"),
("default", "used in some contexts to provide a way of supplying a default when more\nspecific tags are also valid. Note that this tag is\nused when only the _function_ field of the context name is set"),
("descriptions", "used when looking up the value of the `format` style to generate\ndescriptions for types of matches"),
("devices", "for names of device special files"),
("directories", "for names of directories DASH()- `local-directories` is used instead\nwhen completing arguments of `cd` and related builtin commands when\nthe `cdpath` array is set"),
("directory", "for entries in the directory stack"),
("displays", "for X display names"),
("domains", "for network domains"),
("email", "for email addresses from the ``_email-\"_plugin_\" backend of `_email_addresses`"),
("expansions", "used by the `_expand` completer for individual words (as opposed to\nthe complete set of expansions) resulting from the expansion of a word\non the command line"),
("extensions", "for X server extensions"),
("file", "for numbers of open file descriptors"),
("files", "the generic file-matching tag used by functions completing filenames"),
("fonts", "for X font names"),
("fstypes", "for file system types (e.g. for the `mount` command)"),
("functions", "names of functions DASH()- normally shell functions, although certain\ncommands may understand other kinds of function"),
("globbed", "for filenames when the name has been generated by pattern matching"),
("groups", "for names of user groups"),
("history", "for words from the history"),
("hosts", "for hostnames"),
("indexes", "for array indexes"),
("interfaces", "for network interfaces"),
("jobs", "for jobs (as listed by the \"jobs\" builtin)"),
("keymaps", "for names of zsh keymaps"),
("keysyms", "for names of X keysyms"),
("libraries", "for names of system libraries"),
("limits", "for system limits"),
("local", "for names of directories that are subdirectories of the current working\ndirectory when completing arguments of `cd` and related builtin\ncommands (compare `path-directories`) DASH()- when the `cdpath`\narray is unset, `directories` is used instead"),
("mailboxes", "for e-mail folders"),
("manuals", "for names of manual pages"),
("maps", "for map names (e.g. NIS maps)"),
("messages", "used to look up the `format` style for messages"),
("modifiers", "for names of X modifiers"),
("modules", "for modules (e.g. `zsh` modules)"),
("my", "used to look up the `users-hosts` style"),
("named", "for named directories (you wouldn't have guessed that, would you?)"),
("names", "for all kinds of names"),
("newsgroups", "for USENET groups"),
("nicknames", "for nicknames of NIS maps"),
("options", "for command options"),
("original", "used by the `_approximate`, `_correct` and `_expand` completers when\noffering the original string as a match"),
("other", "used to look up the `users-hosts` style"),
("packages", "for packages (e.g. `rpm` or installed `Debian` packages)"),
("parameters", "for names of parameters"),
("path", "for names of directories found by searching the `cdpath` array when\ncompleting arguments of `cd` and related builtin commands (compare\n`local-directories`)"),
("paths", "used to look up the values of the `expand`, `ambiguous` and\n`special-dirs` styles"),
("pods", "for perl pods (documentation files)"),
("ports", "for communication ports"),
("prefixes", "for prefixes (like those of a URL)"),
("printers", "for print queue names"),
("processes", "for process identifiers"),
("processes", "used to look up the `command` style when generating the names of\nprocesses for `killall`"),
("sequences", "for sequences (e.g. `mh` sequences)"),
("sessions", "for sessions in the `zftp` function suite"),
("signals", "for signal names"),
("strings", "for strings (e.g. the replacement strings for the `cd` builtin\ncommand)"),
("styles", "for styles used by the zstyle builtin command"),
("suffixes", "for filename extensions"),
("tags", "for tags (e.g. `rpm` tags)"),
("targets", "for makefile targets"),
("time", "for time zones (e.g. when setting the `TZ` parameter)"),
("types", "for types of whatever (e.g. address types for the `xhost` command)"),
("urls", "used to look up the `urls` and `local` styles when completing URLs"),
("users", "for usernames"),
("values", "for one of a set of values in certain lists"),
("variant", "used by `_pick_variant` to look up the command to run when determining\nwhat program is installed for a particular command name."),
("visuals", "for X visuals"),
("warnings", "used to look up the `format` style for warnings"),
("widgets", "for zsh widget names"),
("windows", "for IDs of X windows"),
("zsh", "for shell options"),
("accept", "This is tested for the `default` tag in addition to the tags valid for\nthe current context. If it is set to \"true\" and any of the trial\nmatches is the same as the string on the command line, this match will\nimmediately be accepted (even if it would otherwise be considered\nambiguous).\n\nWhen completing pathnames (where the tag used is \"paths\")\nthis style accepts any number of patterns as the value in addition to\nthe boolean values. Pathnames matching one of these\npatterns will be accepted immediately even if the command line contains\nsome more partially typed pathname components and these match no file\nunder the directory accepted.\n\nThis style is also used by the `_expand` completer to decide if\nwords beginning with a tilde or parameter expansion should be\nexpanded. For example, if there are parameters\n`foo` and `foobar`, the string \"$foo\" will only be expanded if\n`accept-exact` is set to \"true\"; otherwise the completion system will\nbe allowed to complete `$foo` to `$foobar`. If the style is set to\n\"continue\", `_expand` will add the expansion as a match and the completion\nsystem will also be allowed to continue."),
("accept", "This is used by filename completion. Unlike `accept-exact` it is\na boolean. By default, filename completion examines all components\nof a path to see if there are completions of that component, even if\nthe component matches an existing directory. For example, when\ncompletion after `/usr/bin/`, the function examines possible\ncompletions to `/usr`.\n\nWhen this style is \"true\", any prefix of a path that matches an existing\ndirectory is accepted without any attempt to complete it further.\nHence, in the given example, the path `/usr/bin/` is accepted\nimmediately and completion tried in that directory.\n\nThis style is also useful when completing after directories that\nmagically appear when referenced, such as ZFS `.zfs` directories\nor NetApp `.snapshot` directories. When the style is set the\nshell does not check for the existence of the directory within the\nparent directory.\n\nIf you wish to inhibit this behaviour entirely, set the `path-completion`\nstyle (see below) to \"false\"."),
("add", "This style is used by the `_expand` completer. If it is \"true\" (the\ndefault), a space will be inserted after all words resulting from the\nexpansion, or a slash in the case of directory names. If the value\nis \"file\", the completer will only add a space\nto names of existing files. Either a boolean \"true\" or the value\n\"file\" may be combined with \"subst\", in which case the completer\nwill not add a space to words generated from the expansion of a\nsubstitution of the form `tt($()_..._`\")\" or ``${`_..._`}`'.\n\nThe `_prefix` completer uses this style as a simple boolean value\nto decide if a space should be inserted before the suffix."),
("ambiguous", "This applies when completing non-final components of filename paths, in\nother words those with a trailing slash. If it is set, the cursor is\nleft after the first ambiguous component, even if menu completion is in\nuse. The style is always tested with the `paths` tag."),
("assign", "When completing after an equals sign that is being treated as an\nassignment, the completion system normally completes only one filename.\nIn some cases the value may be a list of filenames separated by colons,\nas with `PATH` and similar parameters. This style can be set to a\nlist of patterns matching the names of such parameters.\n\nThe default is to complete lists when the word on the line already\ncontains a colon."),
("auto", "If set, this style's value will be used as the description for options that\nare not described by the completion functions, but that have exactly\none argument. The sequence \"%d\" in the value will be replaced by\nthe description for this argument. Depending on personal preferences,\nit may be useful to set this style to something like \"specify: %d\".\nNote that this may not work for some commands."),
("avoid", "This is used by the `_all_matches` completer to decide if the string\nconsisting of all matches should be added to the list currently being\ngenerated. Its value is a list of names of completers. If any of\nthese is the name of the completer that generated the matches in this\ncompletion, the string will not be added.\n\nThe default value for this style is ``_expand _old_list _correct\n_approximate`', i.e. it contains the completers for which a string\nwith all matches will almost never be wanted."),
("cache", "This style defines the path where any cache files containing dumped\ncompletion data are stored. It defaults to \"$ZDOTDIR/.zcompcache\", or\n\"$HOME/.zcompcache\" if `$ZDOTDIR` is not defined. The completion\ncache will not be used unless the `use-cache` style is set."),
("cache", "This style defines the function that will be used to determine whether\na cache needs rebuilding. See the section on the `_cache_invalid`\nfunction below."),
("call", "This style is used in the function for commands such as `make` and\n`ant` where calling the command directly to generate matches suffers\nproblems such as being slow or, as in the case of `make` can\npotentially cause actions in the makefile to be executed. If it is set\nto \"true\" the command is called to generate matches. The default value\nof this style is \"false\"."),
("command", "In many places, completion functions need to call external commands to\ngenerate the list of completions. This style can be used to override the\ncommand that is called in some such cases. The elements of the value are\njoined with spaces to form a command line to execute. The value can also\nstart with a hyphen, in which case the usual command will be added to the\nend; this is most useful for putting \"builtin\" or \"command\" in\nfront to make sure the appropriate version of a command is called, for\nexample to avoid calling a shell function with the same name as an external\ncommand.\n\nAs an example, the completion function for process IDs uses this\nstyle with the `processes` tag to generate the IDs to complete and\nthe list of processes to display (if the `verbose` style is \"true\").\nThe list produced by the command should look like the output of the\n`ps` command. The first line is not displayed, but is searched for\nthe string \"PID\" (or \"pid\") to find the position of the\nprocess IDs in the following lines. If the line does not contain\n\"PID\", the first numbers in each of the other lines are taken as the\nprocess IDs to complete.\n\nNote that the completion function generally has to call the specified\ncommand for each attempt to generate the completion list. Hence\ncare should be taken to specify only commands that take a short\ntime to run, and in particular to avoid any that may never terminate."),
("command", "This is a list of directories to search for commands to complete. The\ndefault for this style is the value of the special parameter `path`."),
("commands", "This is used by the function completing sub-commands for the system\ninitialisation scripts (residing in `/etc/init.d` or somewhere not\ntoo far away from that). Its values give the default commands to\ncomplete for those commands for which the completion function isn't\nable to find them out automatically. The default for this style are\nthe two strings \"start\" and \"stop\"."),
("complete", "This is used by the `_expand_alias` function when invoked as a\nbindable command. If set to \"true\" and the word on the command\nline is not the name of an alias, matching alias names will be\ncompleted."),
("complete", "This is used by the completer for `cd`, `chdir` and `pushd`.\nFor these commands a `-` is used to introduce a directory stack entry\nand completion of these is far more common than completing options.\nHence unless the value of this style is \"true\" options will not be\ncompleted, even after an initial `-`. If it is \"true\", options will\nbe completed after an initial `-` unless there is a preceding\n`-``-` on the command line."),
("completer", "The strings given as the value of this style provide the names of the\ncompleter functions to use. The available completer functions are\ndescribed in _Control Functions_ (below).\n\nEach string may be either the name of a completer function or a string\nof the form `_function_`:\"_name_\". In the first case the\n_completer_ field of the context will contain the name of the\ncompleter without the leading underscore and with all other\nunderscores replaced by hyphens. In the second case the\n_function_ is the name of the completer to call, but the context\nwill contain the user-defined _name_ in the _completer_ field of\nthe context. If the _name_ starts with a hyphen, the string for the\ncontext will be build from the name of the completer function as in\nthe first case with the _name_ appended to it. For example:\n\n zstyle ':completion:*' completer _complete _complete:-foo\n\nHere, completion will call the `_complete` completer twice, once\nusing \"complete\" and once using \"complete-foo\" in the\n_completer_ field of the context. Normally, using the same\ncompleter more than once only makes sense when used with the\n`_functions_`:\"_name_\" form, because otherwise the context\nname will be the same in all calls to the completer; possible\nexceptions to this rule are the `_ignored` and `_prefix`\ncompleters.\n\nThe default value for this style is \"_complete _ignored\":\nonly completion will be done, first using the `ignored-patterns` style\nand the `$fignore` array and then without ignoring matches."),
("condition", "This style is used by the `_list` completer function to decide if\ninsertion of matches should be delayed unconditionally. The default is\n\"true\"."),
("delimiters", "This style is used when adding a delimiter for use with history\nmodifiers or glob qualifiers that have delimited arguments. It is\nan array of preferred delimiters to add. Non-special characters are\npreferred as the completion system may otherwise become confused.\nThe default list is `:`, `+`, `/`, `-`, `%`. The list\nmay be empty to force a delimiter to be typed."),
("disabled", "If this is set to \"true\", the `_expand_alias` completer and bindable\ncommand will try to expand disabled aliases, too. The default is\n\"false\"."),
("domains", "A list of names of network domains for completion.\nIf this is not set, domain names will be taken from\nthe file `/etc/resolv.conf`."),
("environ", "The environ style is used when completing for \"sudo\". It is set to an\narray of `_VAR_`=\"_value_\" assignments to be exported into the\nlocal environment before the completion for the target command is invoked.\n\n zstyle ':completion:*:sudo::' environ \\\n PATH=\"/sbin:/usr/sbin:$PATH\" HOME=\"/root\""),
("expand", "This style is used when completing strings consisting of multiple\nparts, such as path names.\n\nIf one of its values is the string \"prefix\", the partially typed\nword from the line will be expanded as far as possible even if trailing\nparts cannot be completed.\n\nIf one of its values is the string \"suffix\", matching names for\ncomponents after the first ambiguous one will also be added. This means\nthat the resulting string is the longest unambiguous string possible.\nHowever, menu completion can be used to cycle through all matches."),
("extra", "If this style set to \"true\", the completion listing is still more verbose.\n\nCurrently, it is used for `commands` and `parameters` tags.\nIf it is \"true\" for the `commands` (or `parameters`) tag, short\ndescriptions of the commands (or the values of the parameters) are\ndisplayed along with the command (or parameter) names."),
("fake", "This style may be set for any completion context. It\nspecifies additional strings that will always be completed in that\ncontext. The form of each string is `_value_`:\"_description_\";\nthe colon and description may be omitted, but any literal colons in\n_value_ must be quoted with a backslash. Any _description_\nprovided is shown alongside the value in completion listings.\n\nIt is important to use a sufficiently restrictive context when specifying\nfake strings. Note that the styles `fake-files` and `fake-parameters`\nprovide additional features when completing files or parameters."),
("fake", "This works identically to the `fake` style except that\nthe `ignored-patterns` style is not applied to it. This makes it\npossible to override a set of matches completely by setting the\nignored patterns to \"*\".\n\nThe following shows a way of supplementing any tag with arbitrary data, but\nhaving it behave for display purposes like a separate tag. In this example\nwe use the features of the `tag-order` style to divide the\n`named-directories` tag into two when performing completion with\nthe standard completer `complete` for arguments of `cd`. The tag\n`named-directories-normal` behaves as normal, but the tag\n`named-directories-mine` contains a fixed set of directories.\nThis has the effect of adding the match group \"extra directories\" with\nthe given completions.\n\n zstyle ':completion::complete:cd:*' tag-order \\\n 'named-directories:-mine:extra\\ directories\n named-directories:-normal:named\\ directories *'\nzstyle ':completion::complete:cd:*:named-directories-mine' \\\n fake-always mydir1 mydir2\nzstyle ':completion::complete:cd:*:named-directories-mine' \\\n ignored-patterns '*'"),
("fake", "This style is used when completing files and looked up\nwithout a tag. Its values are of the form\n`_dir_`:\"_names..._\". This will add the _names_ (strings\nseparated by spaces) as\npossible matches when completing in the directory _dir_, even if no\nsuch files really exist. The dir may be a pattern; pattern characters\nor colons in _dir_ should be quoted with a backslash to be treated\nliterally.\n\nThis can be useful on systems that support special file systems whose\ntop-level pathnames can not be listed or generated with glob patterns\n(but see `accept-exact-dirs` for a more general way of dealing\nwith this problem). It can also be used for directories for which one\ndoes not have read permission.\n\nThe pattern form can be used to add a certain \"magic\" entry\nto all directories on a particular file system."),
("fake", "This is used by the completion function for parameter names.\nIts values are names of parameters that might not yet be\nset but should be completed nonetheless. Each name may also be\nfollowed by a colon and a string specifying the type of the parameter\n(like \"scalar\", \"array\" or \"integer\"). If the type is\ngiven, the name will only be completed if parameters of that type are\nrequired in the particular context. Names for which no type is\nspecified will always be completed."),
("file", "This style controls whether files completed using the standard builtin\nmechanism are to be listed with a long list similar to `ls -l`.\nNote that this feature uses the shell module\n`zsh/stat` for file information; this loads the builtin `stat`\nwhich will replace any external `stat` executable. To avoid\nthis the following code can be included in an initialization file:\n\n zmodload -i zsh/stat\ndisable stat\n\nThe style may either be set to a \"true\" value (or \"all\"), or\none of the values \"insert\" or \"list\", indicating that files\nare to be listed in long format in all circumstances, or when\nattempting to insert a file name, or when listing file names\nwithout attempting to insert one.\n\nMore generally, the value may be an array of any of the above values,\noptionally followed by `=`_num_. If _num_ is present it\ngives the maximum number of matches for which long listing style\nwill be used. For example,\n\n zstyle ':completion:*' file-list list=20 insert=10\n\nspecifies that long format will be used when listing up to 20 files\nor inserting a file with up to 10 matches (assuming a listing\nis to be shown at all, for example on an ambiguous completion), else short\nformat will be used.\n\nexample(zstyle -e ':completion:*' file-list \\\n '(( ${+NUMERIC} )) && reply=(true)')\n\nspecifies that long format will be used any time a numeric argument is\nsupplied, else short format."),
("file", "This is used by the standard function for completing filenames,\n`_files`. If the style is unset up to three tags are offered,\n\"globbed-files\",\"directories\" and \"all-files\", depending on\nthe types of files expected by the caller of `_files`. The first two\n(\"globbed-files\" and \"directories\") are normally offered\ntogether to make it easier to complete files in sub-directories.\n\nThe `file-patterns` style provides alternatives to the default tags,\nwhich are not used. Its value consists of elements of the form\n`_pattern_`:\"_tag_\"; each string may contain any number of\nsuch specifications separated by spaces.\n\nThe _pattern_ is a pattern that is to be used to generate filenames.\nAny occurrence of the sequence \"%p\" is replaced by any\npattern+(s+)\npassed by the function calling `_files`. Colons in the pattern must\nbe preceded by a backslash to make them distinguishable from the colon\nbefore the _tag_. If more than one pattern is needed, the patterns\ncan be given inside braces, separated by commas.\n\nThe _tag_s of all strings in the value will be offered by `_files`\nand used when looking up other styles. Any _tag_s in the same\nword will be offered at the same time and before later words.\nIf no ``:\"_tag_\" is given the \"files\" tag will be used.\n\nThe _tag_ may also be followed by an optional second colon and a\ndescription, which will be used for the \"%d\" in the value of\nthe `format` style (if that is set) instead of the default\ndescription supplied by the completion function. The inclusion\nof a description also gives precedence to associated options such as\nfor completion grouping so it can be used where files should be\nseparated.\n\nFor example, to make the `rm` command first complete only names of\nobject files and then the names of all files if there is no matching\nobject file:\n\n zstyle ':completion:*:*:rm:*:*' file-patterns \\\n '*.o:object-files' '%p:all-files'\n\nTo alter the default behaviour of file completion DASH()- offer files\nmatching a pattern and directories on the first attempt, then all files\nDASH()- to offer only matching files on the first attempt, then directories,\nand finally all files:\n\nexample(zstyle ':completion:*' file-patterns \\\n '%p:globbed-files' '*(-/):directories' '*:all-files')\n\nThis works even where there is no special pattern: `_files` matches\nall files using the pattern \"*\" at the first step and stops when it\nsees this pattern. Note also it will never try a pattern more than once\nfor a single completion attempt.\n\nTo separate directories into a separate group from the files but still\ncomplete them at the first attempt, a description needs to be given.\nNote that directories need to be explicitly excluded from the\nglobbed-files because \"*\" will match directories. For grouping, it\nis also necessary to set the `group-name` style.\n\nexample(zstyle ':completion:*' file-patterns \\\n '%p+(^-/):globbed-files *(-/):directories:location')\n\nDuring the execution of completion functions, the `EXTENDED_GLOB`\noption is in effect, so the characters \"#\", \"~\" and \"^\" have\nspecial meanings in the patterns."),
("file", "The standard filename completion function uses this style without a tag\nto determine in which order the names should be listed; menu completion\nwill cycle through them in the same order. The possible\nvalues are: \"size\" to sort by the size of the file;\n\"links\" to sort by the number of links to the file;\n\"modification\" (or \"time\" or \"date\") to sort by the last\nmodification time; \"access\" to sort by the last access time; and\n\"inode\" (or \"change\") to sort by the last inode change\ntime. If the style is set to any other value, or is unset, files will be\nsorted alphabetically by name. If the value contains the string\n\"reverse\", sorting is done in the opposite order. If the value\ncontains the string \"follow\", timestamps are associated with the\ntargets of symbolic links; the default is to use the timestamps\nof the links themselves."),
("file", "A set of characters that will cause _all_ file completions for\nthe given context to be split at the point where any of the characters\noccurs. A typical use is to set the style to `:`; then everything\nup to and including the last `:` in the string so far is ignored when\ncompleting files. As this is quite heavy-handed, it is usually\npreferable to update completion functions for contexts where this\nbehaviour is useful."),
("filter", "The `ldap` plugin of email address completion (see `_email_addresses`) uses\nthis style to specify\nthe attributes to match against when filtering entries. So for example, if\nthe style is set to \"sn\", matching is done against surnames. Standard\nLDAP filtering is used so normal completion matching is bypassed. If this\nstyle is not set, the LDAP plugin is skipped. You may also need to set the\n`command` style to specify how to connect to your LDAP server."),
("force", "This forces a list of completions to be shown at any point where listing is\ndone, even in cases where the list would usually be suppressed.\nFor example, normally the list is only shown if\nthere are at least two different matches. By setting this style to\n\"always\", the list will always be shown, even if there is only a\nsingle match that will immediately be accepted. The style may also\nbe set to a number. In this case the list will be shown if there are\nat least that many matches, even if they would all insert the same\nstring.\n\nThis style is tested for the default tag as well as for each tag valid\nfor the current completion. Hence the listing can be forced only for\ncertain types of match."),
("format", "If this is set for the `descriptions` tag, its value is used as a\nstring to display above matches in completion lists. The sequence\n\"%d\" in this string will be replaced with a short description of\nwhat these matches are. This string may also contain the output\nattribute sequences understood by `compadd -X`\n(see _Completion Builtin Commands_ (zshcompwid)).\n\nThe style is tested with each tag valid for the current completion\nbefore it is tested for the `descriptions` tag. Hence different format\nstrings can be defined for different types of match.\n\nNote also that some completer functions define additional\n\"%\"-sequences. These are described for the completer functions that\nmake use of them.\n\nSome completion functions display messages that may be customised by\nsetting this style for the `messages` tag. Here, the \"%d\" is\nreplaced with a message given by the completion function.\n\nFinally, the format string is looked up with the `warnings` tag,\nfor use when no matches could be generated at all. In this case the\n\"%d\" is replaced with the descriptions for the matches that were\nexpected separated by spaces. The sequence \"%D\" is replaced with\nthe same descriptions separated by newlines.\n\nIt is possible to use printf-style field width specifiers with \"%d\"\nand similar escape sequences. This is handled by the `zformat`\nbuiltin command from the `zsh/zutil` module, see\n_The zsh/zutil Module_ (zshmodules)."),
("gain", "If set to `true`, this style enables the use of commands like `sudo`\nor `doas` to gain extra privileges when retrieving information for\ncompletion. This is only done when a command such as `sudo` appears on\nthe command-line. To force the use of, e.g. `sudo` or to override any\nprefix that might be added due to `gain-privileges`, the `command`\nstyle can be used with a value that begins with a hyphen."),
("glob", "This is used by the `_expand` completer. If\nit is set to \"true\" (the default), globbing will be attempted on the\nwords resulting from a previous substitution (see the `substitute`\nstyle) or else the original string from the line."),
("global", "If this is set to \"true\" (the default), the `_expand_alias`\ncompleter and bindable command will try to expand global aliases."),
("group", "The completion system can group different types of matches, which appear\nin separate lists. This style can be used to give the names of groups\nfor particular tags. For example, in command position the completion\nsystem generates names of builtin and external commands, names of\naliases, shell functions and parameters and reserved words as possible\ncompletions. To have the external commands and shell functions listed\nseparately:\n\n zstyle ':completion:*:*:-command-:*:commands' \\\n group-name commands\nzstyle ':completion:*:*:-command-:*:functions' \\\n group-name functions\n\nAs a consequence, any match with the same tag will be displayed in the\nsame group.\n\nIf the name given is the empty string the name of the tag for\nthe matches will be used as the name of the group. So, to have all\ndifferent types of matches displayed separately, one can just set:\n\n zstyle ':completion:*' group-name ''\n\nAll matches for which no group name is defined will be put in a group\nnamed `-default-`.\n\nTo display the group name in the output, see the `format` style (q.v.)\nunder the `descriptions` tag."),
("group", "This style is additional to the `group-name` style to specify the\norder for display of the groups defined by that style (compare `tag-order`,\nwhich determines which completions appear at all). The groups named\nare shown in the given order; any other groups\nare shown in the order defined by the completion function.\n\nFor example, to have names of builtin commands, shell functions and\nexternal commands appear in that order when completing in command\nposition:\n\n zstyle ':completion:*:*:-command-:*:*' group-order \\\n builtins functions commands"),
("groups", "A list of names of UNIX groups. If this is not set,\ngroup names are taken from the YP database or the file \"/etc/group\"."),
("hidden", "If this is set to \"true\", matches for the given context\nwill not be listed, although\nany description for the matches set with the `format` style will be\nshown. If it is set to \"all\", not even the description will be\ndisplayed.\n\nNote that the matches will still be completed; they are just not shown\nin the list. To avoid having matches considered as possible\ncompletions at all, the `tag-order` style can be modified as described\nbelow."),
("hosts", "A list of names of hosts that should be completed. If this is not set,\nhostnames are taken from the file \"/etc/hosts\"."),
("hosts", "This style is used by commands that need or accept hostnames and\nnetwork ports. The strings in the value should be of the form\n`_host_`:\"_port_\". Valid ports are determined by the presence\nof hostnames; multiple ports for the same host may appear."),
("ignore", "This is tested for each tag valid for the current completion. If\nit is set to \"true\", none of the words that are already on the line\nwill be considered as possible completions. If it is set to\n\"current\", the word the cursor is on will not be considered as a\npossible completion. The value \"current-shown\" is similar but only\napplies if the list of completions is currently shown on the screen.\nFinally, if the style is set to \"other\", all words on the line except\nfor the current one will be excluded from the possible completions.\n\nThe values \"current\" and \"current-shown\" are a bit like the\nopposite of the `accept-exact` style: only strings with\nmissing characters will be completed.\n\nNote that you almost certainly don't want to set this to \"true\" or\n\"other\" for a general\ncontext such as \":completion:*\". This is because it would disallow\ncompletion of, for example, options multiple times even if the command\nin question accepts the option more than once."),
("ignore", "The style is tested without a tag by the function completing pathnames\nin order to determine whether to ignore\nthe names of directories already mentioned in the current word, or the\nname of the current working directory. The value must include one or both\nof the following strings:\n\n- **`parent`** âÂÂ\nThe name of any directory whose path is already contained in the word on\nthe line is ignored. For example, when completing after `foo/../`, the\ndirectory `foo` will not be considered a valid completion.\n\n- **`pwd`** âÂÂ\nThe name of the current working directory will not be completed; hence,\nfor example, completion after `../` will not use the name of the current\ndirectory.\n\nIn addition, the value may include one or both of:\n\n- **`..`** âÂÂ\nIgnore the specified directories only when the word on the line contains\nthe substring \"../\".\n\n- **`directory`** âÂÂ\nIgnore the specified directories only when names of directories are\ncompleted, not when completing names of files.\n\nExcluded values act in a similar fashion to values of the\n`ignored-patterns` style, so they can be restored to consideration by\nthe `_ignored` completer."),
("ignored", "A list of patterns; any trial completion matching one of the patterns\nwill be excluded from consideration. The\n`_ignored` completer can appear in the list of completers to\nrestore the ignored matches. This is a more configurable\nversion of the shell parameter `$fignore`.\n\nNote that the\n`EXTENDED_GLOB` option is set during the execution of completion\nfunctions, so the characters \"#\", \"~\" and \"^\" have special\nmeanings in the patterns."),
("insert", "This style is used by the `_all_matches` completer to decide whether to\ninsert the list of all matches unconditionally instead of adding the\nlist as another match."),
("insert", "When completing process IDs, for example as arguments to the `kill` and\n`wait` builtins the name of a\ncommand may be converted to the appropriate process ID. A problem\narises when the process name typed is not unique. By default (or if this\nstyle is set explicitly to \"menu\") the name will be converted\nimmediately to a set of possible IDs, and menu completion will be started\nto cycle through them.\n\nIf the value of the style is \"single\",\nthe shell will wait until the user has typed enough to make the command\nunique before converting the name to an ID; attempts at completion will\nbe unsuccessful until that point. If the value is any other\nstring, menu completion will be started when the string typed by the\nuser is longer than the common prefix to the corresponding IDs."),
("insert", "This style is used with tags of the form ``manuals.\"_X_\" when\ncompleting names of manual pages. If set and the _X_ in the tag name matches\nthe section number of the page being completed, the section number is inserted\nalong with the page name. For example, given\n\n zstyle ':completion:*:manuals.*' insert-sections true\n\n`man ssh_<TAB>` may be completed to `man 5 ssh_config`.\n\nThe value may also be set to one of \"prepend\", or \"suffix\".\n\"prepend\" behaves the same as \"true\" as in the above example, while\n\"suffix\" would complete `man ssh_<TAB>` as `man ssh_config.5`.\n\nThis is especially useful in conjunction with `separate-sections`, as\nit ensures that the page requested of `man` corresponds to the one\ndisplayed in the completion listing when there are multiple pages with the\nsame name (e.g., tt(printf+(1+)) and tt(printf+(3+))).\n\nThe default for this style is \"false\"."),
("insert", "If this is set to \"true\", the completion system will\ninsert a TAB character (assuming that was used to start completion) instead\nof performing completion when there is no non-blank character to the left\nof the cursor. If it is set to \"false\", completion will be done even there.\n\nThe value may also contain the substrings \"pending\" or\n``pending=\"_val_\". In this case, the typed character will be\ninserted instead of starting completion when there is unprocessed input\npending. If a _val_ is given, completion will not be done if there\nare at least that many characters of unprocessed input. This is often\nuseful when pasting characters into a terminal. Note\nhowever, that it relies on the `$PENDING` special parameter from the\n`zsh/zle` module being set properly which is not guaranteed on all\nplatforms.\n\nThe default value of this style is \"true\" except for completion within\n`vared` builtin command where it is \"false\"."),
("insert", "This is used by the `_match` and `_approximate` completers.\nThese completers are often used with menu completion since the word typed\nmay bear little resemblance to the final completion.\nHowever, if this style is \"true\", the completer will start menu\ncompletion only if it could find no unambiguous initial string at\nleast as long as the original string typed by the user.\n\nIn the case of the `_approximate` completer, the completer\nfield in the context will already have been set to one of\n`correct-`_num_ or `approximate-`_num_, where _num_ is the\nnumber of errors that were accepted.\n\nIn the case of the `_match` completer, the style may also be set to\nthe string \"pattern\". Then the pattern on the line is left\nunchanged if it does not match unambiguously."),
("keep", "This style is used by the `_expand` completer. If it is \"true\", the\ncompleter will try to keep a prefix containing a tilde or parameter\nexpansion. Hence, for example, the string \"~/f*\" would be expanded to\n\"~/foo\" instead of \"/home/user/foo\". If the style is set to\n\"changed\" (the default), the prefix will only be left unchanged if\nthere were other changes between the expanded words and the original\nword from the command line. Any other value forces the prefix to be\nexpanded unconditionally.\n\nThe behaviour of `_expand` when this style is \"true\" is to cause `_expand`\nto give up when a single expansion with the restored prefix is the same\nas the original; hence any remaining completers may be called."),
("known", "This style should contain a list of files to search for host names and\n(if the `use-ip` style is set) IP addresses in a format compatible with\nssh `known_hosts` files. If it is not set, the files\n`/etc/ssh/ssh_known_hosts` and `~/.ssh/known_hosts` are used."),
("last", "This is a more flexible form of the `ALWAYS_LAST_PROMPT` option.\nIf it is \"true\", the completion system will try to return the cursor to\nthe previous command line after displaying a completion list. It is\ntested for all tags valid for the current completion, then the\n`default` tag. The cursor will be moved back to the\nprevious line if this style is \"true\" for all types of match. Note\nthat unlike the `ALWAYS_LAST_PROMPT` option this is independent of the\nnumeric argument."),
("list", "This style is used by the `_history_complete_word` bindable command.\nIf it is set to \"true\" it has no effect. If it is set to \"false\"\nmatches will not be listed. This overrides the setting of the options\ncontrolling listing behaviour, in particular `AUTO_LIST`. The context\nalways starts with \":completion:history-words\"."),
("list", "If the `zsh/complist` module is loaded, this style can be used to set\ncolor specifications. This mechanism replaces the use of the\n`ZLS_COLORS` and `ZLS_COLOURS` parameters described in\n_The zsh/complist Module_ (zshmodules), but the syntax is the same.\n\nIf this style is set for the `default` tag, the strings in the value\nare taken as specifications that are to be used everywhere. If it is\nset for other tags, the specifications are used only for matches of\nthe type described by the tag. For this to work best, the `group-name`\nstyle must be set to an empty string.\n\nIn addition to setting styles for specific tags, it is also possible to\nuse group names specified explicitly by the `group-name` tag together\nwith the \"tt((group))\" syntax allowed by the `ZLS_COLORS` and\n`ZLS_COLOURS` parameters and simply using the `default` tag.\n\nIt is possible to use any color specifications already set up for the GNU\nversion of the `ls` command:\n\nexample(zstyle ':completion:*:default' list-colors \\\n ${(s.:.)LS_COLORS})\n\nThe default colors are the same as for the GNU `ls` command and can be\nobtained by setting the style to an empty string (i.e. `''`)."),
("list", "This is used by file completion and corresponds to a particular\nsetting of the `file-patterns` style.\nIf set, the default directories to be completed\nare listed separately from and before completion for other files."),
("list", "If this style is \"true\" (the default), the completion system will try to\nmake certain completion listings more compact by grouping matches.\nFor example, options for commands that have the same description (shown\nwhen the `verbose` style is set to \"true\") will appear as a single\nentry. However, menu selection can be used to cycle through all the\nmatches."),
("list", "This is tested for each tag valid in the current context as well as the\n`default` tag. If it is set to \"true\", the corresponding matches\nappear in listings as if the `LIST_PACKED` option were set. If it is\nset to \"false\", they are listed normally."),
("list", "If this style is set for the `default` tag,\ncompletion lists that don't fit on the screen can be scrolled (see\n_The zsh/complist Module_ (zshmodules)).\nThe value, if not the empty string, will be displayed after every\nscreenful and the shell will prompt for a key press; if the style is\nset to the empty string,\na default prompt will be used.\n\nThe value may contain the escape sequences:\n\"%l\" or \"%L\", which will be replaced by the number of the last line\ndisplayed and the total number of lines; \"%m\" or \"%M\",\nthe number of the last match shown and the total number of\nmatches; and \"%p\" and \"%P\", \"Top\"\nwhen at the beginning of the list, \"Bottom\" when at the end and the\nposition shown as a percentage of the total length otherwise. In each\ncase the form with the uppercase letter will be replaced by a string of fixed\nwidth, padded to the right with spaces, while the lowercase form will\nbe replaced by a variable width string. As in other prompt strings, the\nescape sequence ``%H`` along with \"%S\", \"%s\", \"%B\", \"%b\",\n\"%U\", \"%u\" for entering and leaving the display modes\nstandout, bold and underline, and \"%F\", \"%f\", \"%K\", \"%k\" for\nchanging the foreground background colour, are also available, as is the form\n``%{`...`%}`' for enclosing escape sequences which display with zero\n(or, with a numeric argument, some other) width.\n\nAfter deleting this prompt the variable `LISTPROMPT` should be unset for\nthe removal to take effect."),
("list", "This style is tested in the same way as the `list-packed` style and\ndetermines whether matches are to be listed in a rows-first fashion as\nif the `LIST_ROWS_FIRST` option were set."),
("list", "The value of this style is used in completion listing to separate the\nstring to complete from a description when possible (e.g. when\ncompleting options). It defaults to ``-\"-\" (two hyphens)."),
("list", "This style is used by the function that completes filenames. If it is\n\"true\", and completion is attempted on a string containing multiple partially\ntyped pathname components, all ambiguous components will be shown.\nOtherwise, completion stops at the first ambiguous component."),
("local", "This is for use with functions that complete URLs for which the\ncorresponding files are available directly from the file system.\nIts value should consist of three strings: a\nhostname, the path to the default web pages for the server, and the\ndirectory name used by a user placing web pages within their home\narea.\n\nFor example:\n\n zstyle ':completion:*' local toast \\\n /var/http/public/toast public_html\n\nCompletion after \"http://toast/stuff/\" will look for files in the\ndirectory `/var/http/public/toast/stuff`, while completion after\n\"http://toast/~yousir/\" will look for files in the directory\n`~yousir/public_html`."),
("mail", "If set, zsh will assume that mailbox files can be found in\nthe directory specified. It defaults to \"~/Mail\"."),
("match", "This is used by the `_match` completer. If it is set to\n`only`, `_match` will try to generate matches without inserting a\n\"*\" at the cursor position. If set to any other non-empty value,\nit will first try to generate matches without inserting the \"*\"\nand if that yields no matches, it will try again with the \"*\"\ninserted. If it is unset or set to the empty string, matching will\nonly be performed with the \"*\" inserted."),
("matcher", "This style is tested separately for each tag valid in the current\ncontext. Its value is placed before any match specifications given by the\n`matcher-list` style so can override them via the use of an `x:`\nspecification. The value should be in the form described in\n_Completion Matching Control_ (zshcompwid).\nFor examples of this, see the description of the `tag-order` style.\n\nFor notes comparing the use of this and the `matcher-list` style, see\nunder the description of the `tag-order` style."),
("matcher", "This style can be set to a list of match specifications that are to\nbe applied everywhere. Match specifications are described in\n_Completion Matching Control_ (zshcompwid).\nThe completion system will try them one after another for each completer\nselected. For example, to try first simple completion and, if that\ngenerates no matches, case-insensitive completion:\n\n zstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}'\n\nBy default each specification replaces the previous one; however, if a\nspecification is prefixed with `+`, it is added to the existing list.\nHence it is possible to create increasingly general specifications\nwithout repetition:\n\n zstyle ':completion:*' matcher-list \\\n '' '+m:{a-z}={A-Z}' '+m:{A-Z}={a-z}'\n\nIt is possible to create match specifications valid for particular\ncompleters by using the third field of the context. This applies only\nto completers that override the global matcher-list, which as of this\nwriting includes only `_prefix` and `_ignored`. For example, to\nuse the completers `_complete` and `_prefix` but allow\ncase-insensitive completion only with `_complete`:\n\n zstyle ':completion:*' completer _complete _prefix\nzstyle ':completion:*:complete:*:*:*' matcher-list \\\n '' 'm:{a-zA-Z}={A-Za-z}'\n\nUser-defined names, as explained for the `completer` style, are\navailable. This makes it possible to try the same completer more than\nonce with different match specifications each time. For example, to try\nnormal completion without a match specification, then normal completion\nwith case-insensitive matching, then correction, and finally\npartial-word completion:\n\n zstyle ':completion:*' completer \\\n _complete _correct _complete:foo\nzstyle ':completion:*:complete:*:*:*' matcher-list \\\n '' 'm:{a-zA-Z}={A-Za-z}'\nzstyle ':completion:*:foo:*:*:*' matcher-list \\\n 'm:{a-zA-Z}={A-Za-z} r:|[-_./]=* r:|=*'\n\nIf the style is unset in any context no match specification is applied.\nNote also that some completers such as `_correct` and `_approximate`\ndo not use the match specifications at all, though these completers will\nonly ever be called once even if the `matcher-list` contains more than\none element.\n\nWhere multiple specifications are useful, note that the _entire_\ncompletion is done for each element of `matcher-list`, which can\nquickly reduce the shell's performance. As a rough rule of thumb,\none to three strings will give acceptable performance. On the other\nhand, putting multiple space-separated values into the same string does\nnot have an appreciable impact on performance.\n\nIf there is no current matcher or it is empty, and the option\n`NO_CASE_GLOB` is in effect, the matching for files is performed\ncase-insensitively in any case. However, any matcher must\nexplicitly specify case-insensitive matching if that is required.\n\nFor notes comparing the use of this and the `matcher` style, see\nunder the description of the `tag-order` style."),
("max", "This is used by the `_approximate` and `_correct` completer functions\nto determine the maximum number of errors to allow. The completer will try\nto generate completions by first allowing one error, then two errors, and\nso on, until either a match or matches were found or the maximum number of\nerrors given by this style has been reached.\n\nIf the value for this style contains the string \"numeric\", the\ncompleter function will take any numeric argument as the\nmaximum number of errors allowed. For example, with\n\n zstyle ':completion:*:approximate:::' max-errors 2 numeric\n\ntwo errors are allowed if no numeric argument is given, but with\na numeric argument of six (as in \"ESC-6 TAB\"), up to six\nerrors are accepted. Hence with a value of \"0 numeric\", no correcting\ncompletion will be attempted unless a numeric argument is given.\n\nIf the value contains the string \"not-numeric\", the completer\nwill _not_ try to generate corrected\ncompletions when given a numeric argument, so in this case the number given\nshould be greater than zero. For example, \"2 not-numeric\" specifies that\ncorrecting completion with two errors will usually be performed, but if a\nnumeric argument is given, correcting completion will not be\nperformed.\n\nThe default value for this style is \"2 numeric\"."),
("max", "This style is used to determine the trade off between the width of the\ndisplay used for matches and the width used for their descriptions when\nthe `verbose` style is in effect. The value gives the number of\ndisplay columns to reserve for the matches. The default is half the\nwidth of the screen.\n\nThis has the most impact when several matches have the\nsame description and so will be grouped together. Increasing the style\nwill allow more matches to be grouped together; decreasing it will allow\nmore of the description to be visible."),
("menu", "If this is \"true\" in the context of any of the tags defined\nfor the current completion menu completion will be used. The value for\na specific tag will take precedence over that for the \"default\" tag.\n\nIf none of the values found in this way is \"true\" but at least\none is set to \"auto\", the shell behaves as if the `AUTO_MENU`\noption is set.\n\nIf one of the values is explicitly set to \"false\", menu\ncompletion will be explicitly turned off, overriding the\n`MENU_COMPLETE` option and other settings.\n\nIn the form ``yes=\"_num_\", where \"yes\" may be any of the\n\"true\" values (\"yes\", \"true\", \"on\" and \"1\"),\nmenu completion will be turned on if there are at least _num_ matches.\nIn the form \"yes=long\", menu completion will be turned on\nif the list does not fit on the screen. This does not activate menu\ncompletion if the widget normally only lists completions, but menu\ncompletion can be activated in that case with the value \"yes=long-list\"\n(Typically, the value \"select=long-list\" described later is more\nuseful as it provides control over scrolling.)\n\nSimilarly, with any of the \"false\" values (as in \"no=10\"), menu\ncompletion will _not_ be used if there are _num_ or more matches.\n\nThe value of this widget also controls menu selection, as implemented by\nthe `zsh/complist` module. The following values may appear either\nalongside or instead of the values above.\n\nIf the value contains the string \"select\", menu selection\nwill be started unconditionally.\n\nIn the form ``select=\"_num_\", menu selection will only be started if\nthere are at least _num_ matches. If the values for more than one\ntag provide a number, the smallest number is taken.\n\nMenu selection can be turned off explicitly by defining a value\ncontaining the string\"no-select\".\n\nIt is also possible to start menu selection only if the list of\nmatches does not fit on the screen by using the value\n\"select=long\". To start menu selection even if the current widget\nonly performs listing, use the value \"select=long-list\".\n\nTo turn on menu completion or menu selection when there are a certain\nnumber of matches _or_ the list of matches does not fit on the\nscreen, both of \"yes=\" and \"select=\" may be given twice, once\nwith a number and once with \"long\" or \"long-list\".\n\nFinally, it is possible to activate two special modes of menu selection.\nThe word \"interactive\" in the value causes interactive mode\nto be entered immediately when menu selection is started; see\n_The zsh/complist Module_ (zshmodules)\nfor a description of interactive mode. Including the string\n\"search\" does the same for incremental search mode. To select backward\nincremental search, include the string \"search-backward\"."),
("muttrc", "If set, gives the location of the mutt configuration file. It defaults\nto \"~/.muttrc\"."),
("numbers", "This is used with the `jobs` tag. If it is \"true\", the shell will\ncomplete job numbers instead of the shortest unambiguous prefix\nof the job command text. If the value is a number, job numbers will\nonly be used if that many words from the job descriptions are required to\nresolve ambiguities. For example, if the value is \"1\", strings will\nonly be used if all jobs differ in the first word on their command lines."),
("old", "This is used by the `_oldlist` completer. If it is set to \"always\",\nthen standard widgets which perform listing will retain the current list of\nmatches, however they were generated; this can be turned off explicitly\nwith the value \"never\", giving the behaviour without the `_oldlist`\ncompleter. If the style is unset, or any other value, then the existing\nlist of completions is displayed if it is not already; otherwise, the\nstandard completion list is generated; this is the default behaviour of\n`_oldlist`. However, if there is an old list and this style contains\nthe name of the completer function that generated the list, then the\nold list will be used even if it was generated by a widget which does\nnot do listing.\n\nFor example, suppose you type `^Xc` to use the `_correct_word`\nwidget, which generates a list of corrections for the word under the\ncursor. Usually, typing `^D` would generate a standard list of\ncompletions for the word on the command line, and show that. With\n`_oldlist`, it will instead show the list of corrections already\ngenerated.\n\nAs another example consider the `_match` completer: with the\n`insert-unambiguous` style set to \"true\" it inserts only a common prefix\nstring, if there is any. However, this may remove parts of the original\npattern, so that further completion could produce more matches than on the\nfirst attempt. By using the `_oldlist` completer and setting this style\nto `_match`, the list of matches generated on the first attempt will be\nused again."),
("old", "This is used by the `_all_matches` completer to decide if an old\nlist of matches should be used if one exists. This is selected by one of\nthe \"true\" values or by the string \"only\". If\nthe value is \"only\", `_all_matches` will only use an old list\nand won't have any effect on the list of matches currently being\ngenerated.\n\nIf this style is set it is generally unwise to call the `_all_matches`\ncompleter unconditionally. One possible use is for either this style or\nthe `completer` style to be defined with the `-e` option to\n`zstyle` to make the style conditional."),
("old", "This is used by the `_oldlist` completer. It controls how menu\ncompletion behaves when a completion has already been inserted and the\nuser types a standard completion key such as `TAB`. The default\nbehaviour of `_oldlist` is that menu completion always continues\nwith the existing list of completions. If this style is set to\n\"false\", however, a new completion is started if the old list was\ngenerated by a different completion command; this is the behaviour without\nthe `_oldlist` completer.\n\nFor example, suppose you type `^Xc` to generate a list of corrections,\nand menu completion is started in one of the usual ways. Usually, or with\nthis style set to \"false\", typing `TAB` at this point would start\ntrying to complete the line as it now appears. With `_oldlist`, it\ninstead continues to cycle through the list of corrections."),
("original", "This is used by the `_approximate` and `_correct`\ncompleters to decide if the original string should be added as\na possible completion. Normally, this is done only if there are\nat least two possible corrections, but if this style is set to \"true\", it\nis always added. Note that the style will be examined with the\ncompleter field in the context name set to `correct-`_num_ or\n`approximate-`_num_, where _num_ is the number of errors that\nwere accepted."),
("packageset", "This style is used when completing arguments of the Debian \"dpkg\"\nprogram. It contains an override for the default package set\nfor a given context. For example,\n\n zstyle ':completion:*:complete:dpkg:option--status-1:*' \\\n packageset avail\n\ncauses available packages, rather than only installed packages,\nto be completed for ``dpkg -\"-status\"."),
("path", "The function that completes color names uses this style with the\n`colors` tag. The value should be the pathname of a file\ncontaining color names in the format of an X11 `rgb.txt` file. If\nthe style is not set but this file is found in one of various standard\nlocations it will be used as the default."),
("path", "This is used by filename completion. By default, filename completion\nexamines all components of a path to see if there are completions of\nthat component. For example, `/u/b/z` can be completed to\n`/usr/bin/zsh`. Explicitly setting this style to \"false\" inhibits this\nbehaviour for path components up to the `/` before the cursor; this\noverrides the setting of `accept-exact-dirs`.\n\nEven with the style set to \"false\", it is still possible to complete\nmultiple paths by setting the option `COMPLETE_IN_WORD` and moving the\ncursor back to the first component in the path to be completed. For\nexample, `/u/b/z` can be completed to `/usr/bin/zsh` if the cursor is\nafter the `/u`."),
("pine", "If set, specifies the directory containing PINE mailbox files. There\nis no default, since recursively searching this directory is inconvenient\nfor anyone who doesn't use PINE."),
("ports", "A list of Internet service names (network ports) to complete. If this is\nnot set, service names are taken from the file \"/etc/services\"."),
("prefix", "This is used for certain completions which share a common prefix, for\nexample command options beginning with dashes. If it is \"true\", the\nprefix will not be shown in the list of matches.\n\nThe default value for this style is \"false\"."),
("prefix", "This style is also relevant for matches with a common prefix. If it is\nset to \"true\" this common prefix must be typed by the user to generate\nthe matches.\n\nThe style is applicable to the `options`, `signals`, `jobs`,\n`functions`, and `parameters` completion tags.\n\nFor command options, this means that the initial \"-\", \"+\", or\n``-\"-\" must be typed explicitly before option names will be\ncompleted.\n\nFor signals, an initial \"-\" is required before signal names will\nbe completed.\n\nFor jobs, an initial \"%\" is required before job names will be\ncompleted.\n\nFor function and parameter names, an initial \"_\" or \".\" is\nrequired before function or parameter names starting with those\ncharacters will be completed.\n\nThe default value for this style is \"false\" for `function` and\n`parameter` completions, and \"true\" otherwise."),
("preserve", "This style is used when completing path names. Its value should be a\npattern matching an initial prefix of the word to complete that should\nbe left unchanged under all circumstances. For example, on some Unices\nan initial \"//\" (double slash) has a special meaning; setting\nthis style to the string \"//\" will preserve it. As another example,\nsetting this style to \"?:/\" under Cygwin would allow completion\nafter \"a:/...\" and so on."),
("range", "This is used by the `_history` completer and the\n`_history_complete_word` bindable command to decide which words\nshould be completed.\n\nIf it is a single number, only the last _N_ words from the history\nwill be completed.\n\nIf it is a range of the form `_max_`:\"_slice_\",\nthe last _slice_ words will be completed; then if that\nyields no matches, the _slice_ words before those will be tried and\nso on. This process stops either when at least one match has been\nfound, or _max_ words have been tried.\n\nThe default is to complete all words from the history at once."),
("recursive", "If this style is set, its value is an array of patterns to be\ntested against \"$PWD/\": note the trailing slash, which allows\ndirectories in the pattern to be delimited unambiguously by including\nslashes on both sides. If an ordinary file completion fails\nand the word on the command line does not yet have a directory part to its\nname, the style is retrieved using the same tag as for the completion\njust attempted, then the elements tested against `$PWD/` in turn.\nIf one matches, then the shell reattempts completion by prepending the word\non the command line with each directory in the expansion of tt(**/*(/))\nin turn. Typically the elements of the style will be set to restrict\nthe number of directories beneath the current one to a manageable\nnumber, for example \"*/.git/*\".\n\nFor example,\n\n zstyle ':completion:*' recursive-files '*/zsh/*'\n\nIf the current directory is `/home/pws/zsh/Src`, then\n`zle_tr<TAB>` can be completed to `Zle/zle_tricky.c`."),
("regular", "This style is used by the `_expand_alias` completer and bindable\ncommand. If set to \"true\" (the default), regular aliases will be\nexpanded but only in command position. If it is set to \"false\",\nregular aliases will never be expanded. If it is set to \"always\",\nregular aliases will be expanded even if not in command position."),
("rehash", "If this is set when completing external commands, the internal\nlist (hash) of commands will be updated for each search by issuing\nthe `rehash` command. There is a speed penalty for this which\nis only likely to be noticeable when directories in the path have\nslow file access."),
("remote", "If set to \"false\", certain commands will be prevented from making\nInternet connections to retrieve remote information. This includes the\ncompletion for the `CVS` command.\n\nIt is not always possible to know if connections are in fact to a remote\nsite, so some may be prevented unnecessarily."),
("remove", "The `_history_complete_word` bindable command and the `_history`\ncompleter use this to decide if all duplicate matches should be\nremoved, rather than just consecutive duplicates."),
("select", "If this is set for the `default` tag, its\nvalue will be displayed during menu selection (see the `menu` style\nabove) when the completion list does not fit on the screen as a\nwhole. The same escapes as for the `list-prompt` style are\nunderstood, except that the numbers refer to the match or line the mark is\non. A default prompt is used when the value is the empty string."),
("select", "This style is tested for the `default` tag and determines how a\ncompletion list is scrolled during a menu selection (see the `menu`\nstyle above) when the completion list does not fit on the screen as a\nwhole. If the value is \"0\" (zero), the list is scrolled by\nhalf-screenfuls; if it is a positive integer, the list is scrolled by the\ngiven number of lines; if it is a negative number, the list is scrolled by a\nscreenful minus the absolute value of the given number of lines.\nThe default is to scroll by single lines."),
("separate", "This style is used with the `manuals` tag when completing names of\nmanual pages. If it is \"true\", entries for different sections are\nadded separately using tag names of the form ``manuals.\"_X_\",\nwhere _X_ is the section number. When the `group-name` style is\nalso in effect, pages from different sections will appear separately.\nThis style is also used similarly with the `words` style when\ncompleting words for the dict command. It allows words from different\ndictionary databases to be added separately. See also `insert-sections`.\n\nThe default for this style is \"false\"."),
("show", "If the `zsh/complist` module is loaded, this style can be used to\nhighlight the first ambiguous character in completion lists. The\nvalue is either a color indication such as those supported by the\n`list-colors` style or, with a value of \"true\", a default of\nunderlining is selected. The highlighting is only applied if the\ncompletion display strings correspond to the actual matches."),
("show", "Tested whenever a new completer is tried. If it is \"true\", the completion\nsystem outputs a progress message in the listing area showing what\ncompleter is being tried. The message will be overwritten by any output\nwhen completions are found and is removed after completion is finished."),
("single", "This is used by the `_ignored` completer when there is only one match.\nIf its value is \"show\", the single match will be\ndisplayed but not inserted. If the value is \"menu\", then the single\nmatch and the original string are both added as matches and menu completion\nis started, making it easy to select either of them."),
("sort", "This allows the standard ordering of matches to be overridden.\n\nIf its value is \"true\" or \"false\", sorting is enabled or disabled.\nAdditionally the values associated with the \"-o\" option to `compadd` can\nalso be listed: `match`, `nosort`, `numeric`, `reverse`. If it is not\nset for the context, the standard behaviour of the calling widget is used.\n\nThe style is tested first against the full context including the tag, and\nif that fails to produce a value against the context without the tag.\n\nIn many cases where a calling widget explicitly selects a particular ordering\nin lieu of the default, a value of \"true\" is not honoured. An example of\nwhere this is not the case is for command history where the default of sorting\nmatches chronologically may be overridden by setting the style to \"true\".\n\nIn the `_expand` completer, if it is set to\n\"true\", the expansions generated will always be sorted. If it is set\nto \"menu\", then the expansions are only sorted when they are offered\nas single strings but not in the string containing all possible\nexpansions."),
("special", "Normally, the completion code will not produce the directory names\n\".\" and \"..\" as possible completions. If this style is set to\n\"true\", it will add both \".\" and \"..\" as possible completions;\nif it is set to \"..\", only \"..\" will be added.\n\nThe following example sets `special-dirs` to \"..\" when the\ncurrent prefix is empty, is a single \".\", or consists only of a path\nbeginning with \"../\". Otherwise the value is \"false\".\n\nexample(zstyle -e ':completion:*' special-dirs \\\n '[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)')"),
("squeeze", "If set to \"true\", sequences of slashes in filename paths (for example in\n\"foo//bar\") will be treated as a single slash. This is the usual\nbehaviour of UNIX paths. However, by default the file completion\nfunction behaves as if there were a \"*\" between the slashes."),
("stop", "If set to \"true\", the `_history_complete_word` bindable\ncommand will stop once when reaching the beginning or end of the\nhistory. Invoking `_history_complete_word` will then wrap around to\nthe opposite end of the history. If this style is set to \"false\" (the\ndefault), `_history_complete_word` will loop immediately as in a\nmenu completion."),
("strip", "If set to \"true\", this style causes non-essential comment text to be\nremoved from completion matches. Currently it is only used when\ncompleting e-mail addresses where it removes any display name from the\naddresses, cutting them down to plain _user@host_ form."),
("subst", "This is used by the `_expand` completer. If it is set to \"true\",\nthe expansion will only be used if it resulted from globbing; hence,\nif expansions resulted from the use of the `substitute` style\ndescribed below, but these were not further changed by globbing, the\nexpansions will be rejected.\n\nThe default for this style is \"false\"."),
("substitute", "This boolean style controls whether the `_expand` completer will\nfirst try to expand all substitutions in the string (such as\n`tt($()_..._`\")\" and ``${`_..._`}`').\n\nThe default is \"true\"."),
("suffix", "This is used by the `_expand` completer if the word starts with a\ntilde or contains a parameter expansion. If it is set to \"true\", the\nword will only be expanded if it doesn't have a suffix, i.e. if it is\nsomething like \"~foo\" or \"$foo\" rather than \"~foo/\" or\n\"$foo/bar\", unless that suffix itself contains characters eligible\nfor expansion. The default for this style is \"true\"."),
("tag", "This provides a mechanism for sorting how the tags available in a\nparticular context will be used.\n\nThe values for the style are sets of space-separated lists of tags.\nThe tags in each value will be tried at the same time; if no match is\nfound, the next value is used. (See the `file-patterns` style for\nan exception to this behavior.)\n\nFor example:\n\n zstyle ':completion:*:complete:-command-:*:*' tag-order \\\n 'commands functions'\n\nspecifies that completion in command position first offers\nexternal commands and shell functions. Remaining tags will be tried if\nno completions are found.\n\nIn addition to tag names, each string in the value may take one of the\nfollowing forms:\n\n- **`-`** âÂÂ\nIf any value consists of only a hyphen,\nthen _only_ the tags specified in the other values are\ngenerated. Normally all tags not explicitly selected are tried last\nif the specified tags fail to generate any matches. This means\nthat a single value consisting only of a single hyphen\nturns off completion.\n\n- **`!` _tags_...** âÂÂ\nA string starting with an exclamation mark\nspecifies names of tags that are _not_ to be used. The effect is\nthe same as if all other possible tags for the context had been\nlisted.\n\n- **_tag_`:`_label_ ...** âÂÂ\nHere, _tag_ is one of the standard tags and _label_ is an\narbitrary name. Matches are generated as normal but the name _label_\nis used in contexts instead of _tag_. This is not useful in words\nstarting with `!`.\n\nIf the _label_ starts with a hyphen, the _tag_ is prepended to the\n_label_ to form the name used for lookup. This can be\nused to make the completion system try a certain tag more than once,\nsupplying different style settings for each attempt; see below for an\nexample.\n\n- **_tag_`:`_label_`:`_description_** âÂÂ\nAs before, but `description` will replace the \"%d\" in\nthe value of the `format` style instead of the default description\nsupplied by the completion function. Spaces in the description must\nbe quoted with a backslash. A \"%d\" appearing\nin _description_ is replaced with the description given by the\ncompletion function.\n\nIn any of the forms above the tag may be a pattern or several\npatterns in the form ``{`_pat1_`,`_pat2..._`}`'. In this\ncase all matching tags will be used except\nfor any given explicitly in the same string.\n\nOne use of these features is to try\none tag more than once, setting other styles differently on\neach attempt, but still to use all the other tags without having to\nrepeat them all. For example, to make completion of function names in\ncommand position ignore all the completion functions starting with an\nunderscore the first time completion is tried:\n\n zstyle ':completion:*:*:-command-:*:*' tag-order \\\n 'functions:-non-comp *' functions\nzstyle ':completion:*:functions-non-comp' \\\n ignored-patterns '_*'\n\nOn the first attempt, all tags will be offered but the `functions` tag\nwill be replaced by `functions-non-comp`. The `ignored-patterns` style\nis set for this tag to exclude functions starting with an underscore.\nIf there are no matches, the second value of the\n`tag-order` style is used which completes functions using the default\ntag, this time presumably including all function names.\n\nThe matches for one tag can be split into different groups. For example:\n\nexample(zstyle ':completion:*' tag-order \\\n 'options:-long:long\\ options\n options:-short:short\\ options\n options:-single-letter:single\\ letter\\ options'\nzstyle ':completion:*:options-long' \\\n ignored-patterns '[-+](|-|[^-]*)'\nzstyle ':completion:*:options-short' \\\n ignored-patterns '--*' '[-+]?'\nzstyle ':completion:*:options-single-letter' \\\n ignored-patterns '???*')\n\nWith the `group-names` style set, options beginning with\n``-\"-\", options beginning with a single \"-\" or \"+\" but\ncontaining multiple characters, and single-letter options will be\ndisplayed in separate groups with different descriptions.\n\nAnother use of patterns is to\ntry multiple match specifications one after another. The\n`matcher-list` style offers something similar, but it is tested very\nearly in the completion system and hence can't be set for single\ncommands nor for more specific contexts. Here is how to\ntry normal completion without any match specification and, if that\ngenerates no matches, try again with case-insensitive matching, restricting\nthe effect to arguments of the command `foo`:\n\n zstyle ':completion:*:*:foo:*:*' tag-order '*' '*:-case'\nzstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'\n\nFirst, all the tags offered when completing after `foo` are tried using\nthe normal tag name. If that generates no matches, the second value of\n`tag-order` is used, which tries all tags again except that this time\neach has `-case` appended to its name for lookup of styles. Hence this\ntime the value for the `matcher` style from the second call to `zstyle`\nin the example is used to make completion case-insensitive.\n\nIt is possible to use the `-e` option of the `zstyle` builtin\ncommand to specify conditions for the use of particular tags. For\nexample:\n\nexample(zstyle -e '*:-command-:*' tag-order '\n if [[ -n $PREFIX$SUFFIX ]]; then\n reply=( )\n else\n reply=( - )\n fi')\n\nCompletion in command position will be attempted only if the string\ntyped so far is not empty. This is tested using the `PREFIX`\nspecial parameter; see _Completion Special Parameters_ (zshcompwid)\nfor a description of parameters which are special inside completion widgets.\nSetting `reply` to an empty array provides the default\nbehaviour of trying all tags at once; setting it to an\narray containing only a hyphen disables the use of all tags and hence of\nall completions.\n\nIf no `tag-order` style has been defined for a context, the strings\n\"tt((|*-)argument-* (|*-)option-* values)\" and \"options\" plus all\ntags offered by the completion function will be used to provide a\nsensible default behavior that causes arguments (whether normal command\narguments or arguments of options) to be completed before option names for\nmost commands."),
("urls", "This is used together with the `urls` tag by\nfunctions completing URLs.\n\nIf the value consists of more than one string, or if the only string\ndoes not name a file or directory, the strings are used as the URLs to\ncomplete.\n\nIf the value contains only one string which is the name of a normal\nfile the URLs are taken from that file (where the URLs may be\nseparated by white space or newlines).\n\nFinally, if the only string in the value names a directory, the\ndirectory hierarchy rooted at this directory gives the completions. The\ntop level directory should be the file access method, such as\n\"http\", \"ftp\", \"bookmark\" and so on. In many cases the next\nlevel of directories will be a filename. The directory hierarchy can\ndescend as deep as necessary.\n\nFor example,\n\n zstyle ':completion:*' urls ~/.urls\nmkdir -p ~/.urls/ftp/ftp.zsh.org/pub\n\nallows completion of all the components of the URL\n`ftp://ftp.zsh.org/pub` after suitable commands such as\n\"netscape\" or \"lynx\". Note, however, that access methods and\nfiles are completed separately, so if the `hosts` style is set hosts\ncan be completed without reference to the `urls` style.\n\nSee the description in the function `_urls` itself\nfor more information (e.g. \"tt(more $^fpath/_urls+(N+))\")."),
("use", "If this is set, the completion caching layer is activated for any completions\nwhich use it (via the `_store_cache`, `_retrieve_cache`, and\n`_cache_invalid` functions). The directory containing the cache\nfiles can be changed with the `cache-path` style."),
("use", "If this style is set to a string _not_ equal to `false`, `0`,\n`no`, and `off`, the completion system may use any completion\nspecifications defined with the `compctl` builtin command. If the\nstyle is unset, this is done only if the `zsh/compctl` module\nis loaded. The string may also contain the substring \"first\" to\nuse completions defined with \"compctl -T\", and the substring\n\"default\" to use the completion defined with \"compctl -D\".\n\nNote that this is only intended to smooth the transition from\n`compctl` to the new completion system and may disappear in the\nfuture.\n\nNote also that the definitions from `compctl` will only be used if\nthere is no specific completion function for the command in question. For\nexample, if there is a function `_foo` to complete arguments to the\ncommand `foo`, `compctl` will never be invoked for `foo`.\nHowever, the `compctl` version will be tried if `foo` only uses\ndefault completion."),
("use", "By default, the function `_hosts` that completes host names strips\nIP addresses from entries read from host databases such as NIS and\nssh files. If this style is \"true\", the corresponding IP addresses\ncan be completed as well. This style is not use in any context\nwhere the `hosts` style is set; note also it must be set before\nthe cache of host names is generated (typically the first completion\nattempt)."),
("users", "This may be set to a list of usernames to be completed.\nIf it is not set all usernames will be completed.\nNote that if it is set only that list of users will be completed;\nthis is because on some systems querying all users can take\na prohibitive amount of time."),
("users", "The values of this style should be of the form\n`_user_`@\"_host_\" or `_user_`:\"_host_\". It is used for\ncommands that need pairs of\nuser- and hostnames. These commands will complete usernames from this\nstyle (only), and will restrict subsequent hostname completion to hosts\npaired with that user in one of the values of the style.\n\nIt is possible to group values for sets of commands which allow a remote\nlogin, such as `rlogin` and `ssh`, by using the `my-accounts` tag.\nSimilarly, values for sets of commands which usually refer to the\naccounts of other people, such as `talk` and `finger`, can be\ngrouped by using the `other-accounts` tag. More ambivalent commands\nmay use the `accounts` tag."),
("users", "Like `users-hosts` but used for commands like `telnet` and\ncontaining strings of the form `_user_`@`_host_`:\"_port_\"."),
("verbose", "If set, as it is by default, the completion listing is more verbose.\nIn particular many commands show descriptions for options if this\nstyle is \"true\"."),
("word", "This is used by the `_list` completer, which prevents the insertion of\ncompletions until a second completion attempt when the line has not\nchanged. The normal way of finding out if the line has changed is to\ncompare its entire contents between the two occasions. If this style is\n\"true\", the comparison is instead performed only on the current word.\nHence if completion is performed on another word with the same contents,\ncompletion will not be delayed."),
("_all_matches", "This completer can be used to add a string consisting of all other\nmatches. As it influences later completers it must appear as the first\ncompleter in the list. The list of all matches is affected by the\n`avoid-completer` and `old-matches` styles described above.\n\nIt may be useful to use the `_generic` function described below\nto bind `_all_matches` to its own keystroke, for example:\n\n zle -C all-matches complete-word _generic\nbindkey '^Xa' all-matches\nzstyle ':completion:all-matches:*' old-matches only\nzstyle ':completion:all-matches::::' completer _all_matches\n\nNote that this does not generate completions by itself: first use\nany of the standard ways of generating a list of completions,\nthen use `^Xa` to show all matches. It is possible instead to\nadd a standard completer to the list and request that the\nlist of all matches should be directly inserted:\n\n zstyle ':completion:all-matches::::' completer \\\n _all_matches _complete\nzstyle ':completion:all-matches:*' insert true\n\nIn this case the `old-matches` style should not be set."),
("_approximate", "This is similar to the basic `_complete` completer but allows the\ncompletions to undergo corrections. The maximum number of errors can be\nspecified by the `max-errors` style; see\n_Approximate Matching_ (zshexpn)\nfor how errors are counted. Normally this completer will only be tried\nafter the normal `_complete` completer:\n\n zstyle ':completion:*' completer _complete _approximate\n\nThis will give correcting completion if and only if\nnormal completion yields no possible completions. When\ncorrected completions are found, the completer will normally start\nmenu completion allowing you to cycle through these strings.\n\nThis completer uses the tags `corrections` and `original` when\ngenerating the possible corrections and the original string. The\n`format` style for the former may contain the additional sequences\n\"%e\" and \"%o\" which will be replaced by the number of errors\naccepted to generate the corrections and the original string,\nrespectively.\n\nThe completer progressively increases the number of errors allowed up to\nthe limit by the `max-errors` style, hence if a completion is found\nwith one error, no completions with two errors will be shown, and so on.\nIt modifies the completer name in the context to indicate the number of\nerrors being tried: on the first try the completer field contains\n\"approximate-1\", on the second try \"approximate-2\", and so on.\n\nWhen `_approximate` is called from another function, the number of\nerrors to accept may be passed with the `-a` option. The argument\nis in the same format as the `max-errors` style, all in one string.\n\nNote that this completer (and the `_correct` completer mentioned\nbelow) can be quite expensive to call, especially when a large number\nof errors are allowed. One way to avoid this is to set up the\n`completer` style using the `-e` option to zstyle so that some\ncompleters are only used when completion is attempted a second time on\nthe same string, e.g.:\n\nexample(zstyle -e ':completion:*' completer '\n if [[ $_last_try != \"$HISTNO$BUFFER$CURSOR\" ]]; then\n _last_try=\"$HISTNO$BUFFER$CURSOR\"\n reply=(_complete _match _prefix)\n else\n reply=(_ignored _correct _approximate)\n fi')\n\nThis uses the `HISTNO` parameter and the `BUFFER` and `CURSOR`\nspecial parameters that are available inside zle and completion\nwidgets to find out if the command line hasn't changed since the last\ntime completion was tried. Only then are the `_ignored`,\n`_correct` and `_approximate` completers called."),
("_canonical_paths", "This completion function completes all paths given to it, and also tries to\noffer completions which point to the same file as one of the paths given\n(relative path when an absolute path is given, and vice versa; when `..`'s\nare present in the word to be completed; and some paths got from symlinks).\n\n`-A`, if specified, takes the paths from the array variable specified. Paths can\nalso be specified on the command line as shown above. `-N`, if specified,\nprevents canonicalizing the paths given before using them for completion, in\ncase they are already so. The options `-M`, `-J`, `-V`, `-1`, `-2`,\n`-n`, `-F`, `-X` are passed to `compadd`.\n\nSee `_description` for a description of _tag_ and _descr_."),
("_cmdambivalent", "Completes the remaining positional arguments as an external command.\nThe external command and its arguments are completed as separate arguments\n(in a manner appropriate for completing `/usr/bin/env`)\nif there are two or more remaining positional arguments on the command line,\nand as a quoted command string (in the manner of tt(system+(...+))) otherwise.\nSee also `_cmdstring` and `_precommand`.\n\nThis function takes no arguments."),
("_cmdstring", "Completes an external command as a single argument, as for\ntt(system+(...+))."),
("_complete", "This completer generates all possible completions in a context-sensitive\nmanner, i.e. using the settings defined with the `compdef` function\nexplained above and the current settings of all special parameters.\nThis gives the normal completion behaviour.\n\nTo complete arguments of commands, `_complete` uses the utility function\n`_normal`, which is in turn responsible for finding the particular\nfunction; it is described below. Various contexts of the form\n`-`_context_`-` are handled specifically. These are all\nmentioned above as possible arguments to the `#compdef` tag.\n\nBefore trying to find a function for a specific context, `_complete`\nchecks if the parameter \"compcontext\" is set. Setting\n\"compcontext\" allows the usual completion dispatching to be\noverridden which is useful in places such as a function that uses\n`vared` for input. If it is set to an array, the elements are taken\nto be the possible matches which will be completed using the tag\n\"values\" and the description \"value\". If it is set to an\nassociative array, the keys are used as the possible completions and\nthe values (if non-empty) are used as descriptions for the matches. If\n\"compcontext\" is set to a string containing colons, it should be of\nthe form `_tag_`:`_descr_`:\"_action_\". In this case the\n_tag_ and _descr_ give the tag and description to use and the\n_action_ indicates what should be completed in one of the forms\naccepted by the `_arguments` utility function described below.\n\nFinally, if \"compcontext\" is set to a string without colons, the\nvalue is taken as the name of the context to use and the function\ndefined for that context will be called. For this purpose, there is a\nspecial context named `-command-line-` that completes whole command\nlines (commands and their arguments). This is not used by the completion\nsystem itself but is nonetheless handled when explicitly called."),
("_correct", "Generate corrections, but not completions, for the current word; this is\nsimilar to `_approximate` but will not allow any number of extra\ncharacters at the cursor as that completer does. The effect is\nsimilar to spell-checking. It is based on `_approximate`, but the\ncompleter field in the context name is `correct`.\n\nFor example, with:\n\n zstyle ':completion:::::' completer \\\n _complete _correct _approximate\nzstyle ':completion:*:correct:::' max-errors 2 not-numeric\nzstyle ':completion:*:approximate:::' max-errors 3 numeric\n\ncorrection will accept up to two errors. If a numeric argument is\ngiven, correction will not be performed, but correcting completion\nwill be, and will accept as many errors as given by the numeric\nargument. Without a numeric argument, first correction and then\ncorrecting completion will be tried, with the first one accepting two\nerrors and the second one accepting three errors.\n\nWhen `_correct` is called as a function, the number of errors to accept\nmay be given following the `-a` option. The argument is in the same\nform a values to the `accept` style, all in one string.\n\nThis completer function is intended to be used without the\n`_approximate` completer or, as in the example, just before\nit. Using it after the `_approximate` completer is useless since\n`_approximate` will at least generate the corrected strings\ngenerated by the `_correct` completer DASH()- and probably more."),
("_expand", "This completer function does not really perform completion, but instead\nchecks if the word on the command line is eligible for expansion and,\nif it is, gives detailed control over how this expansion is done. For\nthis to happen, the completion system needs to be invoked with\n`complete-word`, not `expand-or-complete` (the default binding for\n`TAB\"), as otherwise the string will be expanded by the shell\"s\ninternal mechanism before the completion system is started.\nNote also this completer should be called before the `_complete`\ncompleter function.\n\nThe tags used when generating expansions are `all-expansions` for the\nstring containing all possible expansions, `expansions` when adding\nthe possible expansions as single matches and `original` when adding\nthe original string from the line. The order in which these strings are\ngenerated, if at all, can be controlled by the `group-order` and\n`tag-order` styles, as usual.\n\nThe format string for `all-expansions` and for `expansions` may\ncontain the sequence \"%o\" which will be replaced by the original\nstring from the line.\n\nThe kind of expansion to be tried is controlled by the `substitute`,\n`glob` and `subst-globs-only` styles.\n\nIt is also possible to call `_expand` as a function, in which case the\ndifferent modes may be selected with options: `-s` for\n`substitute`, `-g` for `glob` and `-o` for `subst-globs-only`."),
("_expand_alias", "If the word the cursor is on is an alias, it is expanded and no other\ncompleters are called. The types of aliases which are to be expanded can\nbe controlled with the styles `regular`, `global` and `disabled`.\n\nThis function is also a bindable command, see\n_Bindable Commands_ (below)."),
("_extensions", "If the cursor follows the string \"*.\", filename extensions are\ncompleted. The extensions are taken from files in current directory or a\ndirectory specified at the beginning of the current word. For exact matches,\ncompletion continues to allow other completers such as `_expand` to\nexpand the pattern. The standard `add-space` and `prefix-hidden`\nstyles are observed."),
("_external_pwds", "Completes current directories of other zsh processes belonging to the\ncurrent user.\n\nThis is intended to be used via `_generic`, bound to a custom key\ncombination. Note that pattern matching is enabled so matching is\nperformed similar to how it works with the `_match` completer."),
("_history", "Complete words from the shell's command history. This completer\ncan be controlled by the `remove-all-dups`, and `sort` styles as for the\n`_history_complete_word` bindable command, see\n_Bindable Commands_ (below)\nand\n_Completion System Configuration_ (above)."),
("_ignored", "The `ignored-patterns` style can be set to a list of patterns which are\ncompared against possible completions; matching ones are removed.\nWith this completer those matches can be reinstated, as\nif no `ignored-patterns` style were set. The completer actually\ngenerates its own list of matches; which completers are invoked\nis determined in the same way as for the `_prefix` completer.\nThe `single-ignored` style is also available as described above."),
("_list", "This completer allows the insertion of matches to be delayed until\ncompletion is attempted a second time without the word on the line\nbeing changed. On the first attempt, only the list of matches will be\nshown. It is affected by the styles `condition` and `word`, see\n_Completion System Configuration_ (above)."),
("_match", "This completer is intended to be used after the `_complete`\ncompleter. It behaves similarly but the string on the command line may\nbe a pattern to match against trial completions. This gives the effect\nof the `GLOB_COMPLETE` option.\n\nNormally completion will be performed by taking the pattern from the line,\ninserting a \"*\" at the cursor position and comparing the resulting\npattern with the possible completions generated. This can be modified\nwith the `match-original` style described above.\n\nThe generated matches will be offered in a menu completion unless the\n`insert-unambiguous` style is set to \"true\"; see the description above\nfor other options for this style.\n\nNote that matcher specifications defined globally or used by the\ncompletion functions (the styles `matcher-list` and `matcher`) will\nnot be used."),
("_menu", "This completer was written as simple example function to show how menu\ncompletion can be enabled in shell code. However, it has the notable\neffect of disabling menu selection which can be useful with\n`_generic` based widgets. It should be used as the first completer in\nthe list. Note that this is independent of the setting of the\n`MENU_COMPLETE` option and does not work with the other menu\ncompletion widgets such as `reverse-menu-complete`, or\n`accept-and-menu-complete`."),
("_oldlist", "This completer controls how the standard completion widgets behave\nwhen there is an existing list of completions which may have been\ngenerated by a special completion (i.e. a separately-bound completion\ncommand). It allows the ordinary completion keys to continue to use the\nlist of completions thus generated, instead of producing a new list of\nordinary contextual completions.\nIt should appear in the list of completers before any of\nthe widgets which generate matches. It uses two styles: `old-list` and\n`old-menu`, see _Completion System Configuration_ (above)."),
("_precommand", "Complete an external command in word-separated arguments, as for\n`exec` and `/usr/bin/env`."),
("_prefix", "This completer can be used to try completion with the suffix (everything\nafter the cursor) ignored. In other words, the suffix will not be\nconsidered to be part of the word to complete. The effect is similar\nto the `expand-or-complete-prefix` command.\n\nThe `completer` style is used to decide which other completers are to\nbe called to generate matches. If this style is unset, the list of\ncompleters set for the current context is used DASH()- except, of course, the\n`_prefix` completer itself. Furthermore, if this completer appears\nmore than once in the list of completers only those completers not\nalready tried by the last invocation of `_prefix` will be called.\n\nFor example, consider this global `completer` style:\n\n zstyle ':completion:*' completer \\\n _complete _prefix _correct _prefix:foo\n\nHere, the `_prefix` completer tries normal completion but ignoring the\nsuffix. If that doesn't generate any matches, and neither does\nthe call to the `_correct` completer after it, `_prefix` will\nbe called a second time and, now only trying correction with the\nsuffix ignored. On the second invocation the completer part of the\ncontext appears as \"foo\".\n\nTo use `_prefix` as the last resort and try only normal completion\nwhen it is invoked:\n\n zstyle ':completion:*' completer _complete ... _prefix\nzstyle ':completion::prefix:*' completer _complete\n\nThe `add-space` style is also respected. If it is set to \"true\" then\n`_prefix` will insert a space between the matches generated (if any)\nand the suffix.\n\nNote that this completer is only useful if the\n`COMPLETE_IN_WORD` option is set; otherwise, the cursor will\nbe moved to the end of the current word before the completion code is\ncalled and hence there will be no suffix."),
("_user_expand", "This completer behaves similarly to the `_expand` completer but\ninstead performs expansions defined by users. The styles `add-space` and\n`sort` styles specific to the `_expand` completer are usable with\n`_user_expand` in addition to other styles handled more generally by\nthe completion system. The tag `all-expansions` is also available.\n\nThe expansion depends on the array style `user-expand` being defined\nfor the current context; remember that the context for completers is less\nspecific than that for contextual completion as the full context has not\nyet been determined. Elements of the array may have one of the following\nforms:\n\n- `$`_hash_ âÂÂ\n_hash_ is the name of an associative array. Note this is not a full\nparameter expression, merely a `$`, suitably quoted to prevent immediate\nexpansion, followed by the name of an associative array. If the trial\nexpansion word matches a key in _hash_, the resulting expansion is the\ncorresponding value.\n\n- __func_ âÂÂ\n__func_ is the name of a shell function whose name must begin with\n`_` but is not otherwise special to the completion system. The function\nis called with the trial word as an argument. If the word is to be\nexpanded, the function should set the array `reply` to a list of\nexpansions. Optionally, it can set `REPLY` to a word that will\nbe used as a description for the set of expansions.\nThe return status of the function is irrelevant."),
("_bash_completions", "This function is used by two widgets, `_bash_complete-word` and\n`_bash_list-choices`. It exists to provide compatibility with\ncompletion bindings in bash. The last character of the binding determines\nwhat is completed: \"!\", command names; \"$\", environment variables;\n\"@\", host names; \"/\", file names; \"~\" user names. In bash, the\nbinding preceded by \"\\e\" gives completion, and preceded by \"^X\"\nlists options. As some of these bindings clash with standard zsh\nbindings, only \"\\e~\" and \"^X~\" are bound by default. To add the\nrest, the following should be added to `.zshrc` after `compinit` has\nbeen run:\n\n for key in '!' '$' '@' '/' '~'; do\n bindkey \"\\e$key\" _bash_complete-word\n bindkey \"^X$key\" _bash_list-choices\ndone\n\nThis includes the bindings for \"~\" in case they were already bound to\nsomething else; the completion code does not override user bindings."),
("_correct_filename", "Correct the filename path at the cursor position. Allows up to six errors\nin the name. Can also be called with an argument to correct\na filename path, independently of zle; the correction is printed on\nstandard output."),
("_correct_word", "Performs correction of the current argument using the usual contextual\ncompletions as possible choices. This stores the string\n\"correct-word\" in the _function_ field of the context name and\nthen calls the `_correct` completer."),
("_expand_alias", "This function can be used as a completer and as a bindable command.\nIt expands the word the cursor is on if it is an alias. The types of\nalias expanded can be controlled with the styles `regular`, `global`\nand `disabled`.\n\nWhen used as a bindable command there is one additional feature that\ncan be selected by setting the `complete` style to \"true\". In this\ncase, if the word is not the name of an alias, `_expand_alias` tries\nto complete the word to a full alias name without expanding it. It\nleaves the cursor directly after the completed word so that invoking\n`_expand_alias` once more will expand the now-complete alias name."),
("_expand_word", "Performs expansion on the current word: equivalent to the standard\n`expand-word` command, but using the `_expand` completer. Before\ncalling it, the _function_ field of the context is set to\n\"expand-word\"."),
("_generic", "This function is not defined as a widget and not bound by\ndefault. However, it can be used to define a widget and will then\nstore the name of the widget in the _function_ field of the context\nand call the completion system. This allows custom completion widgets\nwith their own set of style settings to be defined easily. For example,\nto define a widget that performs normal completion and starts\nmenu selection:\n\n zle -C foo complete-word _generic\nbindkey '...' foo\nzstyle ':completion:foo:*' menu yes select=1\n\nNote in particular that the `completer` style may be set for the context\nin order to change the set of functions used to generate possible matches.\nIf `_generic` is called with arguments, those are passed through to\n`_main_complete` as the list of completers in place of those defined by\nthe `completer` style."),
("_history_complete_word", "Complete words from the shell's command history. This uses the\n`list`, `remove-all-dups`, `sort`, and `stop` styles."),
("_most_recent_file", "Complete the name of the most recently modified file matching the pattern\non the command line (which may be blank). If given a numeric argument\n_N_, complete the _N_th most recently modified file. Note the\ncompletion, if any, is always unique."),
("_next_tags", "This command alters the set of matches used to that for the next tag, or\nset of tags, either as given by the `tag-order` style or as set by\ndefault; these matches would otherwise not be available.\nSuccessive invocations of the command cycle through all possible sets of\ntags."),
("_read_comp", "Prompt the user for a string, and use that to perform completion on the\ncurrent word. There are two possibilities for the string. First, it can\nbe a set of words beginning \"_\", for example \"_files -/\", in which\ncase the function with any arguments will be called to generate the\ncompletions. Unambiguous parts of the function name will be completed\nautomatically (normal completion is not available at this point) until a\nspace is typed.\n\nSecond, any other string will be passed as a set of arguments to\n`compadd` and should hence be an expression specifying what should\nbe completed.\n\nA very restricted set of editing commands is available when reading the\nstring: \"DEL\" and \"^H\" delete the last character; \"^U\" deletes\nthe line, and \"^C\" and \"^G\" abort the function, while \"RET\"\naccepts the completion. Note the string is used verbatim as a command\nline, so arguments must be quoted in accordance with standard shell rules.\n\nOnce a string has been read, the next call to `_read_comp` will use the\nexisting string instead of reading a new one. To force a new string to be\nread, call `_read_comp` with a numeric argument."),
("_complete_debug", "This widget performs ordinary completion, but captures in a temporary file\na trace of the shell commands executed by the completion system. Each\ncompletion attempt gets its own file. A command to view each of these\nfiles is pushed onto the editor buffer stack."),
("_complete_help", "This widget displays information about the context names,\nthe tags, and the completion functions used\nwhen completing at the current cursor position. If given a numeric\nargument other than `1` (as in \"ESC-2 ^Xh\"), then the styles\nused and the contexts for which they are used will be shown, too.\n\nNote that the information about styles may be incomplete; it depends on the\ninformation available from the completion functions called, which in turn\nis determined by the user's own styles and other settings."),
("_complete_help_generic", "Unlike other commands listed here, this must be created as a normal ZLE\nwidget rather than a completion widget (i.e. with `zle -N`). It\nis used for generating help with a widget bound to the `_generic`\nwidget that is described above.\n\nIf this widget is created using the name of the function, as it is by\ndefault, then when executed it will read a key sequence. This is expected\nto be bound to a call to a completion function that uses the `_generic`\nwidget. That widget will be executed, and information provided in\nthe same format that the `_complete_help` widget displays for\ncontextual completion.\n\nIf the widget's name contains `debug`, for example if it is created\nas \"zle -N _complete_debug_generic _complete_help_generic\", it\nwill read and execute the keystring for a generic widget as before,\nbut then generate debugging information as done by `_complete_debug`\nfor contextual completion.\n\nIf the widget's name contains `noread`, it will not read a keystring\nbut instead arrange that the next use of a generic widget run in\nthe same shell will have the effect as described above.\n\nThe widget works by setting the shell parameter\n`ZSH_TRACE_GENERIC_WIDGET` which is read by `_generic`. Unsetting\nthe parameter cancels any pending effect of the `noread` form.\n\nFor example, after executing the following:\n\n zle -N _complete_debug_generic _complete_help_generic\nbindkey '^x:' _complete_debug_generic\n\ntyping \"C-x :\" followed by the key sequence for a generic widget\nwill cause trace output for that widget to be saved to a file."),
("_complete_tag", "This widget completes symbol tags created by the `etags` or `ctags`\nprogrammes (note there is no connection with the completion system's tags)\nstored in a file `TAGS`, in the format used by `etags`, or `tags`, in the\nformat created by `ctags`. It will look back up the path hierarchy for\nthe first occurrence of either file; if both exist, the file `TAGS` is\npreferred. You can specify the full path to a `TAGS` or `tags` file by\nsetting the parameter `$TAGSFILE` or `$tagsfile` respectively.\nThe corresponding completion tags used are `etags` and `vtags`, after\nemacs and vi respectively."),
("_absolute_command_paths", "This function completes external commands as absolute paths (unlike\n`_command_names -e` which completes their basenames). It takes no\narguments."),
("_all_labels", "This is a convenient interface to the `_next_label` function below,\nimplementing the loop shown in the `_next_label` example. The\n_command_ and its arguments are called to generate the matches. The\noptions stored in the parameter _name_ will automatically be inserted\ninto the _arg_s passed to the _command_. Normally, they are put\ndirectly after the _command_, but if one of the _arg_s is a single\nhyphen, they are inserted directly before that. If the hyphen is the last\nargument, it will be removed from the argument list before the\n_command_ is called. This allows `_all_labels` to be used in almost all\ncases where the matches can be generated by a single call to the\n`compadd` builtin command or by a call to one of the utility functions.\n\nFor example:\n\n local expl\n...\nif _requested foo; then\n ...\n _all_labels foo expl '...' compadd ... - $matches\nfi\n\nWill complete the strings from the `matches` parameter, using\n`compadd` with additional options which will take precedence over\nthose generated by `_all_labels`."),
("_alternative", "This function is useful in simple cases where multiple tags are available.\nEssentially it implements a loop like the one described for the `_tags`\nfunction below.\n\nThe tags to use and the action to perform if a tag is requested are\ndescribed using the _spec_s which are of the form:\n`_tag_`:`_descr_`:\"_action_\". The _tag_s are offered using\n`_tags` and if the tag is requested, the _action_ is executed with the\ngiven description _descr_. The _action_s are those accepted\nby the `_arguments` function (described below), with the following\nexceptions:\nstartitemize()\nitemiz(\\\nThe ``->\"_state_\" and ``=\"_..._\" forms are not supported.\n)\nitemiz(\\\nThe `tt(((a\\:bar b\\:baz)`\"))\" form does not need\nthe colon to be escaped, since the _spec_s have no colon-separated fields\nafter the _action_.\n)\nenditemize()\n\nFor example, the _action_ may be a simple function call:\n\n _alternative \\\n 'users:user:_users' \\\n 'hosts:host:_hosts'\n\noffers usernames and hostnames as possible matches,\ngenerated by the `_users` and `_hosts` functions respectively.\n\nLike `_arguments`, this function uses `_all_labels` to execute\nthe actions, which will loop over all sets of tags. Special handling is\nonly required if there is an additional valid tag, for example inside a\nfunction called from `_alternative`.\n\nThe option ``-O\" _name_\" is used in the same way as by the\n`_arguments` function. In other words, the elements of the _name_\narray will be passed to `compadd` when executing an action.\n\nLike `_tags` this function supports the `-C` option to give a\ndifferent name for the argument context field."),
("_arguments", "This function can be used to give a complete specification for completion\nfor a command whose arguments follow standard UNIX option and argument\nconventions.\n\n_Options Overview_\n\nOptions to `_arguments` itself must be in separate words, i.e. `-s -w`,\nnot `-sw`. The options are followed by _spec_s that describe options and\narguments of the analyzed command. To avoid ambiguity, all\noptions to `_arguments` itself may be separated from the _spec_ forms\nby a single colon.\n\nThe ``-\"-\"\nform is used to intuit _spec_ forms from the help output of the command\nbeing analyzed, and is described in detail below. The _opts_ for the\n``-\"-\" form are otherwise the same options as the first form. Note\nthat \"-s\" following ``-\"-\" has a distinct meaning from \"-s\"\npreceding ``-\"-\", and both may appear.\n\nThe option switches `-s`, `-S`, `-A`, `-w`, and `-W` affect how\n`_arguments\" parses the analyzed command line\"s options. These switches are\nuseful for commands with standard argument parsing.\n\nThe options of `_arguments` have the following meanings:\n\n- **`-n`** âÂÂ\nWith this option, `_arguments` sets the parameter `NORMARG`\nto the position of the first normal argument in the `$words` array,\ni.e. the position after the end of the options. If that argument\nhas not been reached, `NORMARG` is set to `-1`. The caller\nshould declare \"integer NORMARG\" if the `-n` option is passed;\notherwise the parameter is not used.\n\n\n- **`-s`** â Enable _option stacking_ for single-letter options, whereby multiple\nsingle-letter options may be combined into a single word. For example,\nthe two options \"-x\" and \"-y\" may be combined into\na single word \"-xy\". By default, every word corresponds to a single\noption name (\"-xy\" is a single option named \"xy\").\n\nOptions beginning with a single hyphen or plus sign are eligible for stacking;\nwords beginning with two hyphens are not.\n\nNote that `-s` after `-``-` has a different meaning, which is documented\nin the segment entitled \"Deriving _spec_ forms from the help output\".\n\n\n- **`-w`** â In combination with `-s`, allow option stacking\neven if one or more of the options take\narguments. For example, if `-x` takes an argument, with no\n`-s`, \"-xy\" is considered as a single (unhandled) option; with\n`-s`, `-xy` is an option with the argument \"y\"; with both `-s`\nand `-w`, `-xy` is the option `-x` and the option `-y` with\narguments to `-x` (and to `-y`, if it takes arguments) still to come\nin subsequent words.\n\n\n- **`-W`** âÂÂ\nThis option takes `-w` a stage further: it is possible to\ncomplete single-letter options even after an argument that occurs in the\nsame word. However, it depends on the action performed whether options\nwill really be completed at this point. For more control, use a\nutility function like `_guard` as part of the action.\n\n- **`-C`** âÂÂ\nModify the `curcontext` parameter for an action of the form ``->\"_state_\".\nThis is discussed in detail below.\n\n- **`-R`** âÂÂ\nReturn status 300 instead of zero when a `$state` is to\nbe handled, in the ``->\"_string_\" syntax.\n\n- **`-S`** âÂÂ\nDo not complete options after a ``-\"-\" appearing on the line,\nand ignore the ``-\"-\". For example, with `-S`, in the line\n\n foobar -x -- -y\n\nthe \"-x\" is considered an option, the \"-y\" is considered an\nargument, and the ``-\"-\" is considered to be neither.\n\n- **`-A` _pat_** âÂÂ\nDo not complete options after the first non-option\nargument on the line. _pat_ is a pattern matching\nall strings which are not to be taken as arguments. For example, to make\n`_arguments` stop completing options after the first normal argument, but\nignoring all strings starting with a hyphen even if they are not described\nby one of the _optspec_s, the form is \"-A \"-*\"\".\n\n- **`-O` _name_** âÂÂ\nPass the elements of the array _name_ as arguments to functions called to\nexecute _action_s.\nThis is discussed in detail below.\n\n- **`-M` _matchspec_** âÂÂ\nUse the match specification _matchspec_ for completing option names and values.\nThe default _matchspec_ allows partial word completion after \"_\" and\n\"-\", such as completing \"-f-b\" to \"-foo-bar\". The default\n_matchspec_ is:\n\n `r:|[_-]=* r:|=*`\n\n- **`-0`** âÂÂ\nWhen populating values of the \"opt_args\" associative array, don't\nbackslash-escape colons and backslashes and use NUL rather than colon for\njoining multiple values. This option is described in more detail below, under\nthe heading __spec_s: actions_.\n\n__spec_s: overview_\n\nEach of the following forms is a _spec_ describing individual sets of\noptions or arguments on the command line being analyzed.\n\n- **_n_`:`_message_`:`_action_**\n\n\n- **_n_`::`_message_`:\"_action_** â This describes the _n_\"th normal argument. The _message_ will be\nprinted above the matches generated and the _action_ indicates what can\nbe completed in this position (see below). If there are two colons\nbefore the _message_ the argument is optional. If the\n_message_ contains only white space, nothing will be printed above\nthe matches unless the action adds an explanation string itself.\n\n- **`:`_message_`:`_action_**\n\n- **`::`_message_`:`_action_** âÂÂ\nSimilar, but describes the _next_ argument, whatever number that\nhappens to be. If all arguments are specified in this form in the\ncorrect order the numbers are unnecessary.\n\n- **`*:`_message_`:`_action_**\n\n- **`*::`_message_`:`_action_**\n\n\n- **`*:::`_message_`:`_action_** â This describes how arguments (usually non-option arguments, those not\nbeginning with `-` or `+`) are to be completed when neither\nof the first two forms was provided. Any number of arguments can\nbe completed in this fashion.\n\nWith two colons before the _message_, the `words` special array and\nthe `CURRENT` special parameter are modified to refer only to the\nnormal arguments when the _action_ is executed or evaluated. With\nthree colons before the _message_ they are modified to refer only to\nthe normal arguments covered by this description.\n\n\n- **_optspec_**\n\n\n- **_optspec_`:`_..._** â This describes an option. The colon indicates handling for one or more\narguments to the option; if it is not present, the option is assumed to\ntake no arguments.\n\nThe following forms are available for the initial _optspec_, whether\nor not the option has arguments.\n\n- **`*`_optspec_** âÂÂ\nHere _optspec_ is one of the remaining forms below. This indicates\nthe following _optspec_ may be repeated. Otherwise if the\ncorresponding option is already present on the command line to the left\nof the cursor it will not be offered again.\n\n- **`-`_optname_**\n\n\n- **`+`_optname_** â In the simplest form the _optspec_ is just the option name beginning\nwith a minus or a plus sign, such as \"-foo\". The first argument for\nthe option (if any) must follow as a _separate_ word directly after the\noption.\n\nEither of ``-+\"_optname_\" and ``+-\"_optname_\" can be used to\nspecify that `-`_optname_ and `+`_optname_ are both valid.\n\nIn all the remaining forms, the leading \"-\" may be replaced by or\npaired with \"+\" in this way.\n\n\n- **`-`_optname_`-`** âÂÂ\nThe first argument of the option must come directly after the option name\n_in the same word_. For example, ``-foo-:\"_..._\" specifies that\nthe completed option and argument will look like ``-foo\"_arg_\".\n\n- **`-`_optname_`+`** âÂÂ\nThe first argument may appear immediately after _optname_ in the same\nword, or may appear as a separate word after the option. For example,\n``-foo+:\"_..._\" specifies that the completed option and argument\nwill look like either ``-foo\"_arg_\" or ``-foo\" _arg_\".\n\n- **`-`_optname_`=`** âÂÂ\nThe argument may appear as the next word, or in same word as the option\nname provided that it is separated from it by an equals sign, for\nexample ``-foo=\"_arg_\" or ``-foo\" _arg_\".\n\n- **`-`_optname_`=-`** âÂÂ\nThe argument to the option must appear after an equals sign in the same\nword, and may not be given in the next argument.\n\n- **_optspec_`[`_explanation_`]`** âÂÂ\nAn explanation string may be appended to any of the preceding forms of\n_optspec_ by enclosing it in brackets, as in \"-q[query operation]\".\n\nThe `verbose` style is used to decide whether the explanation strings\nare displayed with the option in a completion listing.\n\nIf no bracketed explanation string is given but the `auto-description`\nstyle is set and only one argument is described for this _optspec_, the\nvalue of the style is displayed, with any appearance of the sequence\n\"%d\" in it replaced by the _message_ of the first _optarg_\nthat follows the _optspec_; see below.\n\nIt is possible for options with a literal \"+\" or \"=\" to\nappear, but that character must be quoted, for example \"-\\+\".\n\nEach _optarg_ following an _optspec_ must take one of the\nfollowing forms:\n\n- **`:`_message_`:`_action_**\n\n- **`::`_message_`:`_action_** âÂÂ\nAn argument to the option; _message_ and _action_ are treated as\nfor ordinary arguments. In the first form, the argument is mandatory,\nand in the second form it is optional.\n\nThis group may be repeated for options which take multiple arguments.\nIn other words,\n`:`_message1_`:`_action1_`:`_message2_`:`_action2_\nspecifies that the option takes two arguments.\n\n- **`:*`_pattern_`:`_message_`:`_action_**\n\n- **`:*`_pattern_`::`_message_`:`_action_**\n\n\n- **`:*`_pattern_`:::`_message_`:`_action_** â This describes multiple arguments. Only the last _optarg_ for\nan option taking multiple arguments may be\ngiven in this form. If the _pattern_ is empty (i.e. `:*:`), all\nthe remaining words on the line are to be completed as described by the\n_action_; otherwise, all the words up to and including a word matching\nthe _pattern_ are to be completed using the _action_.\n\nMultiple colons are treated as for the ``*:\"_..._\" forms for\nordinary arguments: when the _message_ is preceded by two colons,\nthe `words` special array and the `CURRENT` special parameter are\nmodified during the execution or evaluation of the _action_ to refer\nonly to the words after the option. When preceded by three colons, they\nare modified to refer only to the words covered by this description.\n\n\nAny literal colon in an _optname_, _message_, or _action_\nmust be preceded by a backslash, \"\\:\".\n\nEach of the forms above may be preceded by a list in parentheses\nof option names and argument numbers. If the given option is on\nthe command line, the options and arguments indicated in parentheses\nwill not be offered. For example,\n\"tt((-two -three 1)-one:)_..._\" completes the option \"-one\"; if this\nappears on the command line, the options `-two` and `-three` and the\nfirst ordinary argument will not be completed after it.\n\"tt((-foo):)_..._\" specifies an ordinary argument completion;\n`-foo` will not be completed if that argument is already present.\n\nOther items may appear in the list of excluded options to indicate\nvarious other items that should not be applied when the current\nspecification is matched: a single star (`*`) for the rest arguments\n(i.e. a specification of the form ``*:\"_..._\"); a colon (`:`)\nfor all normal (non-option-) arguments; and a hyphen (`-`) for all\noptions. For example, if \"tt((*))\" appears before an option and the\noption appears on the command line, the list of remaining arguments\n(those shown in the above table beginning with \"*:\") will not be\ncompleted.\n\nTo aid in reuse of specifications, it is possible to precede any of the\nforms above with \"!\"; then the form will no longer be completed,\nalthough if the option or argument appears on the command line they will\nbe skipped as normal. The main use for this is when the arguments are\ngiven by an array, and `_arguments` is called repeatedly for more\nspecific contexts: on the first call \"_arguments $global_options\" is\nused, and on subsequent calls \"_arguments !$^global_options\".\n\n__spec_s: actions_\nCOMMENT(If you change this section title, change the references to it in running text.)\n\nIn each of the forms above the _action_ determines how\ncompletions should be generated. Except for the ``->\"_string_\"\nform below, the _action_ will be executed by calling the\n`_all_labels` function to process all tag labels. No special handling\nof tags is needed unless a function call introduces a new one.\n\nThe functions called to execute _action_s will be called with the\nelements of the array named by the ``-O\" _name_\" option as arguments.\nThis can be used, for example, to pass the same set of options for the\n`compadd` builtin to all _action_s.\n\nThe forms for _action_ are as follows.\n\ndef(SP)(0)(@ )\\\n\n- **`SP()`(single unquoted space)** â This is useful where an argument is required but it is not possible or\ndesirable to generate matches for it. The\n_message_ will be displayed but no completions listed. Note\nthat even in this case the colon at the end of the _message_ is\nneeded; it may only be omitted when neither a _message_\nnor an _action_ is given.\n\n\n- **`()_item1_ _item2_ _..._```** â One of a list of possible matches, for example:\n\nexample(tt(:foo:(foo bar baz)``))\n\n\n- **`((_item1_\\:_desc1_ _..._))`** â Similar to the above, but with descriptions for each possible match.\nNote the backslash before the colon. For example,\n\nexample(tt(:foo:((a\\:bar b\\:baz)``)))\n\nThe matches will be listed together with their descriptions if the\n`description` style is set with the `values` tag in the context.\n\n\n- **`->`_string_** â vindex(context, use of)\nvindex(line, use of)\nvindex(opt_args, use of)\nIn this form, `_arguments` processes the arguments and options and then\nreturns control to the calling function with parameters set to indicate the\nstate of processing; the calling function then makes its own arrangements\nfor generating completions. For example, functions that implement a state\nmachine can use this type of action.\n\nWhere `_arguments` encounters _action_ in the ``->\"_string_\"\nformat, it will strip all leading and trailing whitespace from _string_\nand set the array `state` to the set of all _string_s for which an\naction is to be performed. The elements of the array `state_descr` are\nassigned the corresponding _message_ field from each _optarg_\ncontaining such an _action_.\n\nBy default and in common with all other well behaved completion\nfunctions, _arguments returns status zero if it was able to add matches and\nnon-zero otherwise. However, if the `-R` option is given,\n`_arguments` will instead return a status of 300 to indicate that\n`$state` is to be handled.\n\nIn addition to `$state` and `$state_descr`, `_arguments` also\nsets the global\nparameters \"context\", \"line\" and \"opt_args\" as described\nbelow, and does not reset any changes made to the special parameters\nsuch as `PREFIX` and `words`. This gives the calling function the\nchoice of resetting these parameters or propagating changes in them.\n\nA function calling `_arguments` with at least\none action containing a ``->\"_string_\" must therefore declare\nappropriate local parameters:\n\n local context state state_descr line\ntypeset -A opt_args\n\nto prevent `_arguments` from altering the global environment.\n\n\n- **`{`_eval-string_`}`** â vindex(expl, use of)\nA string in braces is evaluated as shell code to generate matches. If the\n_eval-string_ itself does not begin with an opening parenthesis or\nbrace it is split into separate words before execution.\n\n\n- **`= `_action_** â If the _action_ starts with \"= \" (an equals sign followed by a\nspace), `_arguments` will insert the contents of the _argument_\nfield of the current context as the new first element in the `words`\nspecial array and increment the value of the `CURRENT` special\nparameter. This has the effect of inserting a dummy word onto the\ncompletion command line while not changing the point at which completion is\ntaking place.\n\nThis is most useful with one of the specifiers that restrict the words on\nthe command line on which the _action_ is to operate (the two- and\nthree-colon forms above). One particular use is when an _action_ itself\ncauses `_arguments` on a restricted range; it is necessary to use this\ntrick to insert an appropriate command name into the range for the second\ncall to `_arguments` to be able to parse the line.\n\n\n- **var(`SP()`word...)**\n\n\n- **_word..._** âÂÂ\nThis covers all forms other than those above. If the _action_\nstarts with a space, the remaining list of words will be invoked unchanged.\n\nOtherwise it will be invoked with some extra strings placed after the\nfirst word; these are to be passed down as options to the `compadd`\nbuiltin. They ensure that the state specified by `_arguments`, in\nparticular the descriptions of options and arguments, is correctly passed\nto the completion command. These additional arguments\nare taken from the array parameter \"expl\"; this will be set up\nbefore executing the _action_ and hence may be referred to inside it,\ntypically in an expansion of the form \"$expl[@]\" which preserves empty\nelements of the array.\n\nDuring the performance of the action the array \"line\" will be set to\nthe normal arguments from the command line, i.e. the words from the\ncommand line after the command name excluding all options and their\narguments. Options are stored in the associative array\n\"opt_args\" with option names as keys and their arguments as\nthe values. By default, all colons and backslashes in the value are escaped\nwith backslashes, and if an option has multiple arguments (for example, when\nusing an _optspec_ of the form ``*\"_optspec_\"), they are joined with\n(unescaped) colons. However, if the `-0` option was passed, no backslash\nescaping is performed, and multiple values are joined with NUL bytes. For\nexample, after \"zsh -o foo:foo -o bar:bar -o <TAB>\", the contents of\n\"opt_args\" would be\n\nexample(typeset -A opt_args=( [-o]='foo\\:foo:bar\\:bar:' ))\n\nby default, and\n\nexample(typeset -A opt_args=( [-o]=$'foo:foo\\x00bar:bar\\x00' ))\n\nif `_arguments` had been called with the `-0` option.\n\nThe parameter \"context\" is set when returning to the calling function\nto perform an action of the form ``->\"_string_\". It is set to an\narray of elements corresponding to the elements of `$state`. Each\nelement is a suitable name for the argument field of the context: either a\nstring of the form ``option`_-opt_\"-\"_n_\" for the _n_\"th\nargument of the option _-opt_, or a string of the form\n`\"argument-\"_n_\" for the _n_\"th argument. For \"rest\" arguments,\nthat is those in the list at the end not handled by position, _n_ is the\nstring \"rest\". For example, when completing the argument of the `-o`\noption, the name is \"option-o-1\", while for the second normal\n(non-option-) argument it is \"argument-2\".\n\nFurthermore, during the evaluation of the _action_ the context name in\nthe `curcontext` parameter is altered to append the same string that is\nstored in the `context` parameter.\n\nThe option `-C` tells `_arguments` to modify the `curcontext`\nparameter for an action of the form ``->\"_state_\". This is the\nstandard parameter used to keep track of the current context. Here it\n(and not the `context` array) should be made local to the calling\nfunction to avoid passing back the modified value and should be\ninitialised to the current value at the start of the function:\n\n local curcontext=\"$curcontext\"\n\nThis is useful where it is not possible for multiple states to be valid\ntogether.\n\n_Grouping Options_\n\nOptions can be grouped to simplify exclusion lists. A group is\nintroduced with \"+\" followed by a name for the group in the\nsubsequent word. Whole groups can then be referenced in an exclusion\nlist or a group name can be used to disambiguate between two forms of\nthe same option. For example:\n\nexample(_arguments \\\n '(group2--x)-a' \\\n + group1 \\\n -m \\\n '(group2)-n' \\\n + group2 \\\n -x -y)\n\nIf the name of a group is specified in the form\n`tt(()_name_`\")\" then only one value from that group\nwill ever be completed; more formally, all specifications are mutually\nexclusive to all other specifications in that group. This is useful for\ndefining options that are aliases for each other. For example:\n\nexample(_arguments \\\n -a -b \\\n + '(operation)' \\\n {-c,--compress}'[compress]' \\\n {-d,--decompress}'[decompress]' \\\n {-l,--list}'[list]')\n\nIf an option in a group appears on the command line, it is stored in the\nassociative array \"opt_args\" with '_group_`-\"_option_\"\nas a key. In the example above, a key \"operation--c\" is used if the option\n\"-c\" is present on the command line.\n\n_Specifying Multiple Sets of Arguments_\n\nIt is possible to specify multiple sets of options and arguments with\nthe sets separated by single hyphens. This differs from groups in that\nsets are considered to be mutually exclusive of each other.\n\nSpecifications before the first set and from any group are common to\nall sets. For example:\n\nexample(_arguments \\\n -a \\\n - set1 \\\n -c \\\n - set2 \\\n -d \\\n ':arg:(x2 y2)')\n\nThis defines two sets. When the command line contains the option\n\"-c\", the \"-d\" option and the argument will not be considered\npossible completions. When it contains \"-d\" or an argument, the\noption \"-c\" will not be considered. However, after \"-a\"\nboth sets will still be considered valid.\n\nAs for groups, the name of a set may appear in exclusion lists, either\nalone or preceding a normal option or argument specification.\n\nThe completion code has to parse the command line separately for each\nset. This can be slow so sets should only be used when necessary.\nA useful alternative is often an option specification with rest-arguments\n(as in \"-foo:*:...\"); here the option `-foo` swallows up all\nremaining arguments as described by the _optarg_ definitions.\n\n_Deriving _spec_ forms from the help output_\n\nThe option ``-\"-\" allows `_arguments` to work out the names of long\noptions that support the ``-\"-help\" option which is standard in many\nGNU commands. The command word is called with the argument\n``-\"-help\" and the output examined for option names. Clearly, it can\nbe dangerous to pass this to commands which may not support this option as\nthe behaviour of the command is unspecified.\n\nIn addition to options, ``_arguments -\"-\" will try to deduce the\ntypes of arguments available for options when the form\n``-``-`_opt_`=\"_val_\" is valid. It is also possible to provide\nhints by examining the help text of the command and adding _helpspec_ of\nthe form `_pattern_`:`_message_`:\"_action_\"; note that other\n`_arguments` _spec_ forms are not used. The _pattern_ is matched\nagainst the help text for an option, and if it matches the _message_ and\n_action_ are used as for other argument specifiers. The special case\nof \"*:\" means both _message_ and _action_ are empty, which has\nthe effect of causing options having no description in the help output to\nbe ordered in listings ahead of options that have a description.\n\nFor example:\n\nexample(_arguments -- '*\\*:toggle:(yes no)' \\\n '*=FILE*:file:_files' \\\n '*=DIR*:directory:_files -/' \\\n '*=PATH*:directory:_files -/')\n\nHere, \"yes\" and \"no\" will be completed as the argument of\noptions whose description ends in a star; file names will be completed for\noptions that contain the substring \"=FILE\" in the description; and\ndirectories will be completed for options whose description contains\n\"=DIR\" or \"=PATH\". The last three are in fact the default and so\nneed not be given explicitly, although it is possible to override the use\nof these patterns. A typical help text which uses this feature is:\n\n -C, --directory=DIR change to directory DIR\n\nso that the above specifications will cause directories to be completed\nafter ``-\"-directory\", though not after \"-C\".\n\nNote also that `_arguments` tries to find out automatically if the\nargument for an option is optional. This can be specified explicitly by\ndoubling the colon before the _message_.\n\nIf the _pattern_ ends in \"tt((-))\", this will be removed from the\npattern and the _action_ will be used only directly after the\n\"=\", not in the next word. This is the behaviour of a normal\nspecification defined with the form \"=-\".\n\nBy default, the command (with the option \"--help\") is run after\nresetting all the locale categories (except for `LC_CTYPE`) to \"C\".\nIf the localized help output is known to work, the option \"-l\" can\nbe specified after the ``_arguments -\"-\" so that the command is\nrun in the current locale.\n\nThe ``_arguments -\"-\" can be followed by the option ``-i`\n_patterns_' to give patterns for options which are not to be\ncompleted. The patterns can be given as the name of an array parameter\nor as a literal list in parentheses. For example,\n\nexample(_arguments -- -i \\\n \"(--(en|dis)able-FEATURE*)\")\n\nwill cause completion to ignore the options\n``-\"-enable-FEATURE\" and ``-\"-disable-FEATURE\" (this example is\nuseful with GNU `configure`).\n\nThe ``_arguments -\"-\" form can also be followed by the option ``-s`\n_pair_' to describe option aliases. The _pair_ consists of a list\nof alternating patterns and corresponding replacements, enclosed in parens\nand quoted so that it forms a single argument word in the `_arguments`\ncall.\n\nFor example, some `configure`-script help output describes options only\nas ``-\"-enable-foo\", but the script also accepts the negated form\n``-\"-disable-foo\". To allow completion of the second form:\n\nexample(_arguments -- -s \"((#s)--enable- --disable-)\")\n\n_Miscellaneous notes_\n\nFinally, note that `_arguments` generally expects to be the primary\nfunction handling any completion for which it is used. It may have side\neffects which change the treatment of any matches added by other functions\ncalled after it. To combine `_arguments` with other functions, those\nfunctions should be called either before `_arguments`, as an _action_\nwithin a _spec_, or in handlers for ``->\"_state_\" actions.\n\nHere is a more general example of the use of `_arguments`:\n\nexample(_arguments '-l+:left border:' \\\n '-format:paper size:(letter A4)' \\\n '*-copy:output file:_files::resolution:(300 600)' \\\n ':postscript file:_files -g \\*.\\(ps\\|eps\\)' \\\n '*:page number:')\n\nThis describes three options: \"-l\", \"-format\", and\n\"-copy\". The first takes one argument described as `_left\nborder_' for which no completion will be offered because of the empty\naction. Its argument may come directly after the \"-l\" or it may be\ngiven as the next word on the line.\n\nThe \"-format\" option takes one\nargument in the next word, described as \"_paper size_\" for which\nonly the strings \"letter\" and \"A4\" will be completed.\n\nThe \"-copy\" option may appear more than once on the command line and\ntakes two arguments. The first is mandatory and will be completed as a\nfilename. The second is optional (because of the second colon before\nthe description \"_resolution_\") and will be completed from the strings\n\"300\" and \"600\".\n\nThe last two descriptions say what should be completed as\narguments. The first describes the first argument as a\n\"_postscript file_\" and makes files ending in \"ps\" or \"eps\"\nbe completed. The last description gives all other arguments the\ndescription \"_page number_\" but does not offer completions."),
("_as_if", "This function is useful when one command should be completed as if it were\nanother command with particular arguments. For example to complete `foo` as\nif it were `bar --baz`, use\n\n compdef '_as_if bar --baz' foo"),
("_cache_invalid", "This function returns status zero if the completions cache corresponding to\nthe given cache identifier needs rebuilding. It determines this by\nlooking up the `cache-policy` style for the current context.\nThis should provide a function name which is run with the full path to the\nrelevant cache file as the only argument.\n\nExample:\n\nexample(_example_caching_policy () {\n # rebuild if cache is more than a week old\n local -a oldp\n oldp=( \"$1\"(Nm+7) )\n (( $#oldp ))\n})"),
("_call_function", "If a function _name_ exists, it is called with the arguments\n_arg_s. The _return_ argument gives the name of a parameter in which\nthe return status from the function _name_ should be stored; if _return_\nis empty or a single hyphen it is ignored.\n\nThe return status of `_call_function` itself is zero if the function\n_name_ exists and was called and non-zero otherwise."),
("_call_program", "This function provides a mechanism for the user to override the use of an\nexternal command. It looks up the `command` style with the supplied\n_tag_. If the style is set, its value is used as the command to\nexecute. The _string_s from the call to `_call_program`, or from the\nstyle if set, are concatenated with spaces between them and the resulting\nstring is evaluated. The return status is the return status of the command\ncalled.\n\nBy default, the command is run in an environment where all the locale\ncategories (except for `LC_CTYPE`) are reset to \"C\" by calling the\nutility function `_comp_locale` (see below). If the option \"-l\" is\ngiven, the command is run with the current locale.\n\nIf the option \"-p\" is supplied it indicates that the command\noutput is influenced by the permissions it is run with. If the\n`gain-privileges` style is set to true, `_call_program` will make\nuse of commands such as `sudo`, if present on the command-line, to\nmatch the permissions to whatever the final command is likely to run\nunder. When looking up the `gain-privileges` and `command` styles,\nthe command component of the zstyle context will end with a slash\n(\"/\") followed by the command that would be used to gain privileges."),
("_combination", "This function is used to complete combinations of values, for example\npairs of hostnames and usernames. The _style_ argument gives the style\nwhich defines the pairs; it is looked up in a context with the _tag_\nspecified.\n\nThe style name consists of field names separated by hyphens, for example\n\"users-hosts-ports\". For each field for a value is already known, a\n_spec_ of the form `_field_`=\"_pattern_\" is given. For example,\nif the command line so far specifies a user \"pws\", the argument\n\"users=pws\" should appear.\n\nThe next argument with no equals sign is taken as the name of the field\nfor which completions should be generated (presumably not one of the\n_field_s for which the value is known).\n\nThe matches generated will be taken from the value of the style. These\nshould contain the possible values for the combinations in the appropriate\norder (users, hosts, ports in the example above).\nThe values for the different fields are separated by colons. This\ncan be altered with the option `-s` to `_combination` which specifies a\npattern. Typically this is a character class, as for example\n\"-s \"[:@]\"\" in the case of the `users-hosts` style. Each\n`_field_`=\"_pattern_\" specification restricts the\ncompletions which apply to elements of the style with appropriately\nmatching fields.\n\nIf no style with the given name is defined for the given tag,\nor if none of the strings in style's value match, but a\nfunction name of the required field preceded by an\nunderscore is defined, that function will be called to generate the\nmatches. For example, if there is no \"users-hosts-ports\" or no\nmatching hostname when a host is required, the function \"_hosts\" will\nautomatically be called.\n\nIf the same name is used for more than one field, in both the\n`_field_`=\"_pattern_\" and the argument that gives the name of the\nfield to be completed, the number of the field (starting with one) may\nbe given after the fieldname, separated from it by a colon.\n\nAll arguments after the required field name are passed to\n`compadd` when generating matches from the style value, or to\nthe functions for the fields if they are called."),
("_command_names", "This function completes words that are valid at command position: names of\naliases, builtins, hashed commands, functions, and so on. If the `-e`\nflag is given, or if the list of precommands contains a non-builtin command\n(e.g. because `_normal -p` has been used previously), only hashed commands\nare completed. The `-` flag is ignored."),
("_comp_locale", "This function resets all the locale categories other than `LC_CTYPE` to\n\"C\" so that the output from external commands can be easily analyzed by\nthe completion system. `LC_CTYPE` retains the current value (taking\n`LC_ALL` and `LANG` into account), ensuring that non-ASCII characters\nin file names are still handled properly.\n\nThis function should normally be run only in a subshell, because the new\nlocale is exported to the environment. Typical usage would be\n`tt($(_comp_locale; )_command_ ...`\")\"."),
("_completers", "This function completes names of completers.\n\n\n- **`-p`** â Include the leading underscore (\"_\") in the matches.\n"),
("_default", "This function corresponds to the `-default-` special context which is\napplied where no completion is defined. It is useful to call it under\ncertain error conditions such as completion after an unrecognised\nsubcommand. This applies the concept of graceful degradation to the\ncompletion system, allowing it to fallback on basic completion of\ncommonly useful things like filenames."),
("_describe", "This function associates completions with descriptions.\nMultiple groups separated by `-``-` can be supplied, potentially with\ndifferent completion options _opt_s.\n\nThe _descr_ is taken as a string to display above the matches if the\n`format` style for the `descriptions` tag is set. This is followed by\none or two names of arrays followed by options to pass to `compadd`. The\narray _name1_ contains the possible completions with their descriptions in\nthe form `_completion_`:\"_description_\". Any literal colons in\n_completion_ must be quoted with a backslash. If a _name2_ is\ngiven, it should have the same number of elements as _name1_; in this\ncase the corresponding elements are added as possible completions instead\nof the _completion_ strings from _name1_. The completion list\nwill retain the descriptions from _name1_. Finally, a set of\ncompletion options can appear.\n\nIf the option \"-o\" appears before the first argument, the matches added\nwill be treated as names of command options (N.B. not shell options),\ntypically following a \"-\", ``-\"-\" or \"+\" on the command\nline. In this case `_describe` uses the `prefix-hidden`,\n`prefix-needed` and `verbose` styles to find out if the strings should\nbe added as completions and if the descriptions should be shown. Without\nthe \"-o\" option, only the `verbose` style is used to decide how\ndescriptions are shown. If \"-O\" is used instead of \"-o\", command\noptions are completed as above but `_describe` will not handle the\n`prefix-needed` style.\n\nWith the `-t` option a _tag_ can be specified. The default is\n\"values\" or, if the `-o` option is given, \"options\".\n\nThe options `-1`, `-2`, `-J`, `-V`, `-x` are passed to\n`_next_label`.\n\nIf selected by the `list-grouped` style, strings with the same\ndescription will appear together in the list.\n\n`_describe` uses the `_all_labels` function to generate the matches, so\nit does not need to appear inside a loop over tag labels."),
("_description", "This function is not to be confused with the previous one; it is used as\na helper function for creating options to `compadd`. It is buried\ninside many of the higher level completion functions and so often does\nnot need to be called directly.\n\nThe styles listed below are tested in the current context using the\ngiven _tag_. The resulting options for `compadd` are put into the\narray named _name_ (this is traditionally \"expl\", but this\nconvention is not enforced). The description for the corresponding set\nof matches is passed to the function in _descr_.\n\nThe styles tested are: `format`, `hidden`, `matcher`,\n`ignore-line`, `ignored-patterns`, `group-name` and `sort`.\nThe `format` style is first tested for the given _tag_ and then for\nthe `descriptions` tag if no value was found, while the remainder are\nonly tested for the tag given as the first argument. The function also\ncalls `_setup` which tests some more styles.\n\nThe string returned by the `format` style (if any) will be modified so\nthat the sequence \"%d\" is replaced by the _descr_ given as the third\nargument without any leading or trailing white space. If, after\nremoving the white space, the _descr_ is the empty string, the format\nstyle will not be used and the options put into the _name_ array will\nnot contain an explanation string to be displayed above the matches.\n\nIf `_description` is called with more than three arguments,\nthe additional _spec_s should be of the form `_char_`:\"_str_\".\nThese supply escape sequence replacements for the `format` style:\nevery appearance of ``%\"_char_\" will be replaced by _string_.\nIf no additional _spec_s are given but the description in _descr_\nconforms to a common form then further escape sequences are set for\nelements of that description. These elements correspond to a default\nvalue (\"%o\"), the units (\"%m\") range of acceptable values\n(\"%r\") and the remaining initial part of the description (\"%h\").\nThe form the description takes consists of specifying the units and\nrange in parentheses and the default value in square brackets, for\nexample:\n\nexample(_description times expl 'timeout (seconds) (0-60) [20]')\n\nIt is possible to use `zformat` conditional expressions when styling\nthese elements. So, for example, to add \"default:\" as a tag but only\nwhen there is a default value to show, the `format` style might\ninclude \"tt(%(o.default: %o.))\".\n\nIf the `-x` option is given, the description will be passed to\n`compadd` using the `-x` option instead of the default `-X`. This\nmeans that the description will be displayed even if there are no\ncorresponding matches.\n\nThe options placed in the array _name_ take account of the\n`group-name` style, so matches are placed in a separate group where\nnecessary. The group normally has its elements sorted (by passing the\noption `-J` to `compadd`), but if an option starting with \"-V\",\n\"-J\", \"-1\", or \"-2\" is passed to `_description`, that\noption will be included in the array. Hence it is possible for the\ncompletion group to be unsorted by giving the option \"-V\",\n\"-1V\", or \"-2V\".\n\nIn most cases, the function will be used like this:\n\n local expl\n_description files expl file\ncompadd \"$expl[@]\" - \"$files[@]\"\n\nNote the use of the parameter `expl`, the hyphen, and the list of\nmatches. Almost all calls to `compadd` within the completion system use\na similar format; this ensures that user-specified styles are correctly\npassed down to the builtins which implement the internals of completion."),
("_dir_list", "Complete a list of directory names separated by colons\n(the same format as `$PATH`).\n\n\n- **`-s` _sep_** â Use _sep_ as separator between items.\n_sep_ defaults to a colon (\":\").\n\n\n- **`-S`** â Add _sep_ instead of slash (\"/\") as an autoremoveable suffix.\n"),
("_dispatch", "This sets the current context to _context_ and looks for completion\nfunctions to handle this context by hunting through the list of command\nnames or special contexts (as described above for `compdef`)\ngiven as _string_s. The first completion function to be defined\nfor one of the contexts in the list is used to generate matches.\nTypically, the last _string_ is `-default-` to cause the function\nfor default completion to be used as a fallback.\n\nThe function sets the parameter\n`$service` to the _string_ being tried, and sets\nthe _context/command_ field (the fourth) of the `$curcontext`\nparameter to the _context_ given as the first argument."),
("_email_addresses", "Complete email addresses. Addresses are provided by plugins.\n\n- **`-c`** âÂÂ\nComplete bare `localhost@domain.tld` addresses, without a name part or\na comment.\nWithout this option, RFC822 `_Firstname Lastname_ `<`_address_`>`'\nstrings are completed.\n\n- **`-n` _plugin_** âÂÂ\nComplete aliases from _plugin_.\n\nCOMMENT(Intentionally leaving `-s` undocumented: new code should use\n`_sequence` instead.)\\\n\nThe following plugins are available by default:\n`_email-ldap` (see the `filter` style),\n`_email-local` (completes _user_`@`_hostname_ Unix addresses),\n`_email-mail` (completes aliases from `~/.mailrc`),\n`_email-mush`,\n`_email-mutt`,\nand\n`_email-pine`.\n\nAddresses from the `_email-`_foo_ plugin are added under the\ntag ``email-\"_foo_\".\n\n_Writing plugins_\n\nPlugins are written as separate functions with names starting with \"_email-\".\nThey are invoked with the `-c` option and `compadd` options.\nThey should either do their own completion or\nset the `$reply` array to a list of `_alias_`:\"_address_\" elements and return `300`.\nNew plugins will be picked up and run automatically."),
("_files", "The function `_files` is a wrapper around `_path_files`. It supports\nall of the same functionality, with some enhancements DASH()- notably, it\nrespects the `list-dirs-first` style, and it allows users to override\nthe behaviour of the `-g` and `-/` options with the `file-patterns`\nstyle. `_files` should therefore be preferred over `_path_files` in\nmost cases.\n\nThis function accepts the full set of options allowed by\n`_path_files`, described below."),
("_gnu_generic", "This function is a simple wrapper around the `_arguments` function\ndescribed above. It can be used to determine automatically the long\noptions understood by commands that produce a list when passed the\noption ``-\"-help\". It is intended to be used as a top-level\ncompletion function in its own right. For example, to enable option\ncompletion for the commands `foo` and `bar`, use\n\n compdef _gnu_generic foo bar\n\nafter the call to `compinit`.\n\nThe completion system as supplied is conservative in its use of this\nfunction, since it is important to be sure the command understands the\noption ``-\"-help\"."),
("_guard", "This function displays _descr_ if _pattern_ matches the string to\nbe completed. It is intended to be used in the _action_ for the\nspecifications passed to `_arguments` and similar functions.\n\nThe return status is zero if the message was displayed and the word to\ncomplete is not empty, and non-zero otherwise.\n\nThe _pattern_ may be preceded by any of the options understood by\n`compadd` that are passed down from `_description`, namely `-M`,\n`-J`, `-V`, `-1`, `-2`, `-n`, `-F` and `-X`. All of these\noptions will be ignored. This fits in conveniently with the\nargument-passing conventions of actions for `_arguments`.\n\nAs an example, consider a command taking the options `-n` and\n`-none`, where `-n` must be followed by a numeric value in the\nsame word. By using:\n\n _arguments '-n-: :_guard \"[0-9]#\" \"numeric value\"' '-none'\n\n`_arguments` can be made to both display the message ``numeric\nvalue`' and complete options after \"-n<TAB>\". If the \"-n\" is\nalready followed by one or more digits (the pattern passed to\n`_guard`) only the message will be displayed; if the \"-n\" is\nfollowed by another character, only options are completed."),
("_message", "The _descr_ is used in the same way as the third\nargument to the `_description` function, except that the resulting\nstring will always be shown whether or not matches were\ngenerated. This is useful for displaying a help message in places where\nno completions can be generated.\n\nThe `format` style is examined with the `messages` tag to find a\nmessage; the usual tag, `descriptions`, is used only if the style is\nnot set with the former.\n\nIf the `-r` option is given, no style is used; the _descr_ is\ntaken literally as the string to display. This is most useful\nwhen the _descr_ comes from a pre-processed argument list\nwhich already contains an expanded description. Note that this\noption does not disable the \"%\"-sequence parsing done by\n`compadd`.\n\nThe `-12VJ` options and the _group_ are passed to `compadd` and\nhence determine the group the message string is added to.\n\nThe second `-e` form gives a description for completions with the tag\n_tag_ to be shown even if there are no matches for that tag. This form\nis called by `_arguments` in the event that there is no action for an\noption specification. The tag can be omitted and if so the tag is taken\nfrom the parameter `$curtag`; this is maintained by the completion\nsystem and so is usually correct. Note that if there are no matches at\nthe time this function is called, `compstate[insert]` is cleared, so\nadditional matches generated later are not inserted on the command line."),
("_multi_parts", "The argument _sep_ is a separator character.\nThe _array_ may be either the\nname of an array parameter or a literal array in the form\n`tt((foo bar)`\")\", a parenthesised list of words separated\nby whitespace. The possible completions are the\nstrings from the array. However, each chunk delimited by _sep_ will be\ncompleted separately. For example, the `_tar` function uses\n``_multi_parts` `/\" _patharray_\" to complete partial file paths\nfrom the given array of complete file paths.\n\nThe `-i` option causes `_multi_parts` to insert a unique match even\nif that requires multiple separators to be inserted. This is not usually\nthe expected behaviour with filenames, but certain other types of\ncompletion, for example those with a fixed set of possibilities, may be\nmore suited to this form.\n\nLike other utility functions, this function accepts the \"-V\",\n\"-J\", \"-1\", \"-2\", \"-n\", \"-f\", \"-X\", \"-M\",\n\"-P\", \"-S\", \"-r\", \"-R\", and \"-q\" options and passes\nthem to the `compadd` builtin."),
("_next_label", "This function is used to implement the loop over different tag\nlabels for a particular tag as described above for the `tag-order`\nstyle. On each call it checks to see if there are any more tag labels; if\nthere is it returns status zero, otherwise non-zero.\nAs this function requires a current tag to be set, it must always follow\na call to `_tags` or `_requested`.\n\nThe `-x12VJ` options and the first three arguments are passed to the\n`_description` function. Where appropriate the _tag_ will be\nreplaced by a tag label in this call. Any description given in\nthe `tag-order` style is preferred to the _descr_ passed to\n`_next_label`.\n\nThe _option_s given after the _descr_\nare set in the parameter given by _name_, and hence are to be passed\nto `compadd` or whatever function is called to add the matches.\n\nHere is a typical use of this function for the tag `foo`. The call to\n`_requested` determines if tag `foo` is required at all; the loop\nover `_next_label` handles any labels defined for the tag in the\n`tag-order` style.\n\n local expl ret=1\n...\nif _requested foo; then\n ...\n while _next_label foo expl '...'; do\n compadd \"$expl[@]\" ... && ret=0\n done\n ...\nfi\nreturn ret"),
("_normal", "This is the standard function called to handle completion outside\nany special `-`_context_`-`. It is called both to complete the command\nword and also the arguments for a command. In the second case,\n`_normal` looks for a special completion for that command, and if\nthere is none it uses the completion for the `-default-` context.\n\nA second use is to reexamine the command line specified by the `$words`\narray and the `$CURRENT` parameter after those have been modified.\nFor example, the function `_precommand`, which\ncompletes after precommand specifiers such as `nohup`, removes the\nfirst word from the `words` array, decrements the `CURRENT` parameter,\nthen calls \"_normal -p $service\". The effect is that\n``nohup\" _cmd ..._\" is treated in the same way as \"_cmd ..._\".\n\n\n- **`-P`** â Reset the list of precommands. This option should be used if completing\na command line which allows internal commands (e.g. builtins and\nfunctions) regardless of prior precommands (e.g. \"zsh -c\").\n\n\n- **`-p` _precommand_** âÂÂ\nAppend _precommand_ to the list of precommands. This option should be\nused in nearly all cases in which `-P` is not applicable. An advantage\nof using this option is that it can automatically signal to\n`_command_names` that subsequent completion should be limited to hashed\ncommands, which is usually the desired behaviour following commands like\n`chroot` and `nohup`.\n\nIf the command name matches one of the patterns given by one of the\noptions `-p` or `-P` to `compdef`, the corresponding completion\nfunction is called and then the parameter `_compskip` is\nchecked. If it is set completion is terminated at that point even if\nno matches have been found. This is the same effect as in the\n`-first-` context."),
("_numbers", "This can be used where a number is followed by a suffix to indicate the units.\nThe unit suffixes are completed and can also be included in the description\nused when completion is invoked for the preceding number.\n\nIn addition to common `compadd` options, `_numbers` accepts the following\noptions:\n\n- **`-t` _tag_** âÂÂ\nSpecify a tag to use instead of the default of `numbers`.\n\n- **`-u` _units_** âÂÂ\nIndicate the default units for the number, e.g. `bytes`.\n\n- **`-l` _min_** âÂÂ\nSpecify the lowest possible value for the number.\n\n- **`-m` _max_** âÂÂ\nSpecify the highest possible value for the number.\n\n- **`-d` _default_** âÂÂ\nSpecify the default value.\n\n- **`-N`** âÂÂ\nAllow negative numbers. This is implied if the range includes a negative.\n\n- **`-f`** âÂÂ\nAllow decimal numbers.\n\nWhere a particular suffix represents the default units for a number, it\nshould be prefixed with a colon. Additionally, suffixes can be followed\nby a colon and a description. So for example, the following allows the\nage of something to be specified, either in seconds or with an optional\nsuffix with a longer unit of time:\n\n _numbers -u seconds age :s:seconds m:minutes h:hours d:days\n\nIt is typically helpful for units to be presented in order of magnitude\nwhen completed. To facilitate this, the order in which they are given\nis preserved.\n\nWhen the `format` style is looked up with the `descriptions` tag or\nthe tag specified with `-t`, the list of suffixes is available as a\n\"%x\" escape sequence. This is in addition to the usual sequences\ndocumented under the `format` style. The form this list takes can also\nbe configured. To this end, the `format` style is first looked up with\nthe tag `unit-suffixes`. The retrieved format is applied to each\nsuffix in turn and the results are then concatenated to form the\ncompleted list. For the `unit-suffixes` format, \"%x\" expands to\nthe individual suffix and \"%X\" to its description. `%d`' indicates\na default suffix and can be used in a condition. The index and reverse\nindex are set in \"%i\" and \"%r\" respectively and are useful for\ntext included only with the first and last suffixes in the list. So for\nexample, the following joins the suffixes together as a comma-separated\nlist:\n\nexample(zstyle ':completion:*:unit-suffixes' format '%x%(r::,)')"),
("_options", "This can be used to complete the names of shell options. It provides a\nmatcher specification that ignores a leading \"no\", ignores\nunderscores and allows upper-case letters to\nmatch their lower-case counterparts (for example, \"glob\",\n\"noglob\", \"NO_GLOB\" are all completed). Any arguments\nare propagated to the `compadd` builtin."),
("_options_set", "These functions complete only set or unset options, with the same\nmatching specification used in the `_options` function.\n\nNote that you need to uncomment a few lines in the `_main_complete`\nfunction for these functions to work properly. The lines in question\nare used to store the option settings in effect before the completion\nwidget locally sets the options it needs. Hence these functions are not\ngenerally used by the completion system."),
("_parameters", "This is used to complete the names of shell parameters.\n\nThe option ``-g\" _pattern_\" limits the completion to parameters\nwhose type matches the _pattern_. The type of a parameter is that\nshown by `tt(print ${(t))_param_`}`', hence judicious use of\n\"*\" in _pattern_ is probably necessary.\n\nAll other arguments are passed to the `compadd` builtin."),
("_path_files", "This function is used throughout the completion system\nto complete filenames. It allows completion of partial paths. For\nexample, the string \"/u/i/s/sig\" may be completed to\n\"/usr/include/sys/signal.h\".\n\nThe options accepted by both `_path_files` and `_files` are:\n\n- **`-f`** âÂÂ\nComplete all filenames. This is the default.\n\n- **`-/`** âÂÂ\nSpecifies that only directories should be completed.\n\n- **`-g` _pattern_** âÂÂ\nSpecifies that only files matching the _pattern_ should be completed.\n\n- **`-W` _paths_** âÂÂ\nSpecifies path prefixes that are to be prepended to the string from the\ncommand line to generate the filenames but that should not be inserted\nas completions nor shown in completion listings. Here, _paths_ may be\nthe name of an array parameter, a literal list of paths enclosed in\nparentheses or an absolute pathname.\n\n- **`-F` _ignored-files_** âÂÂ\nThis behaves as for the corresponding option to the `compadd` builtin.\nIt gives direct control over which\nfilenames should be ignored. If the option is not present, the\n`ignored-patterns` style is used.\n\nBoth `_path_files` and `_files` also accept the following options\nwhich are passed to `compadd`: \"-J\", \"-V\",\n\"-1\", \"-2\", \"-n\", \"-X\", \"-M\", \"-P\", \"-S\",\n\"-q\", \"-r\", and \"-R\".\n\nFinally, the `_path_files` function uses the styles `expand`,\n`ambiguous`, `special-dirs`, `list-suffixes` and `file-sort`\ndescribed above."),
("_pick_variant", "This function is used to resolve situations where a single command name\nrequires more than one type of handling, either because it\nhas more than one variant or because there is a name clash between two\ndifferent commands.\n\nThe command to run is taken from the first element of the array\n`words` unless this is overridden by the option `-c`. This command\nis run and its output is compared with a series of patterns. Arguments\nto be passed to the command can be specified at the end after all the\nother arguments. The patterns to try in order are given by the arguments\n_label_`=`_pattern_; if the output of `_command_ _arg_\n...' contains _pattern_, then _label_ is selected as the label\nfor the command variant. If none of the patterns match, the final\ncommand label is selected and status 1 is returned.\n\nIf the ``-b\" _builtin-label_\" is given, the command is tested to\nsee if it is provided as a shell builtin, possibly autoloaded; if so,\nthe label _builtin-label_ is selected as the label for the variant.\n\nIf the ``-r\" _name_\" is given, the _label_ picked is stored in\nthe parameter named _name_.\n\nThe results are also cached in the `_cmd_variant` associative array\nindexed by the name of the command run."),
("_regex_arguments", "This function generates a completion function _name_ which matches\nthe specifications _spec_s, a set of regular expressions as\ndescribed below. After running `_regex_arguments`, the function\n_name_ should be called as a normal completion function.\nThe pattern to be matched is given by the contents of\nthe `words` array up to the current cursor position joined together\nwith null characters; no quotation is applied.\n\nThe arguments are grouped as sets of alternatives separated by \"|\",\nwhich are tried one after the other until one matches. Each alternative\nconsists of a one or more specifications which are tried left to right,\nwith each pattern matched being stripped in turn from the command line\nbeing tested, until all of the group succeeds or until one fails; in the\nlatter case, the next alternative is tried. This structure can be\nrepeated to arbitrary depth by using parentheses; matching proceeds from\ninside to outside.\n\nCOMMENT(I think I've got this wrong, but I can't think what else it\ncould mean. Actually, it still doesn't mean very much.)\\\nA special procedure is applied if no test succeeds but the remaining\ncommand line string contains no null character (implying the remaining\nword is the one for which completions are to be generated). The\ncompletion target is restricted to the remaining word and any\n_action_s for the corresponding patterns are executed. In this case,\nnothing is stripped from the command line string. The order of\nevaluation of the _action_s can be determined by the `tag-order`\nstyle; the various formats supported by `_alternative` can be used\nin _action_. The _descr_ is used for setting up the array\nparameter `expl`.\n\nSpecification arguments take one of following forms, in which\nmetacharacters such as \"tt(()\", ``\")\", \"#\" and \"|\"\nshould be quoted.\n\n\n- **`/`_pattern_`/` [`%`_lookahead_`%`] [`-`_guard_] [`:`_tag_`:`_descr_`:`_action_]** â This is a single primitive component.\nThe function tests whether the combined pattern\n`tt((#b)((#B))_pattern_``)_lookahead_`*`' matches\nthe command line string. If so, \"_guard_\" is evaluated and\nits return status is examined to determine if the test has succeeded.\nThe _pattern_ string \"[]\" is guaranteed never to match.\nThe _lookahead_ is not stripped from the command line before the next\npattern is examined.\n\nThe argument starting with `:` is used in the same manner as an argument to\n`_alternative`.\n\nA component is used as follows: _pattern_ is tested to\nsee if the component already exists on the command line. If\nit does, any following specifications are examined to find something to\ncomplete. If a component is reached but no such pattern exists yet on the\ncommand line, the string containing the _action_ is used to generate\nmatches to insert at that point.\n\n- **`/`_pattern_`/+` [`%`_lookahead_`%`] [`-`_guard_] [`:`_tag_`:`_descr_`:`_action_]** â This is similar to ``/`_pattern_`/\" ...\" but the left part of the\ncommand line string (i.e. the part already matched by previous patterns)\nis also considered part of the completion target.\n\n\n- **`/`_pattern_`/-` [`%`_lookahead_`%`] [`-`_guard_] [`:`_tag_`:`_descr_`:`_action_]** âÂÂ\nThis is similar to ``/`_pattern_`/\" ...\" but the _action_s of the\ncurrent and previously matched patterns are ignored even if the\nfollowing \"_pattern_\" matches the empty string.\n\n\n- **`() _spec_ ```** â Parentheses may be used to groups _spec_s; note each parenthesis\nis a single argument to `_regex_arguments`.\n\n\n- **_spec_ `#`** âÂÂ\nThis allows any number of repetitions of _spec_.\n\n- **_spec_ _spec_** âÂÂ\nThe two _spec_s are to be matched one after the other as described\nabove.\n\n- **_spec_ `|` _spec_** âÂÂ\nEither of the two _spec_s can be matched.\n\nThe function `_regex_words` can be used as a helper function to\ngenerate matches for a set of alternative words possibly with\ntheir own arguments as a command line argument.\n\nExamples:\n\n _regex_arguments _tst /$'[^\\0]#\\0'/ \\\n /$'[^\\0]#\\0'/ :'compadd aaa'\n\nThis generates a function `_tst` that completes `aaa` as its only\nargument. The _tag_ and _description_ for the action have been\nomitted for brevity (this works but is not recommended in normal use).\nThe first component matches the command word, which is arbitrary; the\nsecond matches any argument. As the argument is also arbitrary, any\nfollowing component would not depend on `aaa` being present.\n\n _regex_arguments _tst /$'[^\\0]#\\0'/ \\\n /$'aaa\\0'/ :'compadd aaa'\n\nThis is a more typical use; it is similar, but any following patterns\nwould only match if `aaa` was present as the first argument.\n\nexample(_regex_arguments _tst /$'[^\\0]#\\0'/ \\( \\\n /$'aaa\\0'/ :'compadd aaa' \\\n /$'bbb\\0'/ :'compadd bbb' \\) \\#)\n\nIn this example, an indefinite number of command arguments may be\ncompleted. Odd arguments are completed as `aaa` and even arguments\nas `bbb`. Completion fails unless the set of `aaa` and `bbb`\narguments before the current one is matched correctly.\n\nexample(_regex_arguments _tst /$'[^\\0]#\\0'/ \\\n \\( /$'aaa\\0'/ :'compadd aaa' \\| \\\n /$'bbb\\0'/ :'compadd bbb' \\) \\#)\n\nThis is similar, but either `aaa` or `bbb` may be completed for\nany argument. In this case `_regex_words` could be used to generate\na suitable expression for the arguments."),
("_regex_words", "This function can be used to generate arguments for the\n`_regex_arguments` command which may be inserted at any point where\na set of rules is expected. The _tag_ and _description_ give a\nstandard tag and description pertaining to the current context. Each\n_spec_ contains two or three arguments separated by a colon: note\nthat there is no leading colon in this case.\n\nEach _spec_ gives one of a set of words that may be completed at\nthis point, together with arguments. It is thus roughly equivalent to\nthe `_arguments` function when used in normal (non-regex) completion.\n\nThe part of the _spec_ before the first colon is the word to be\ncompleted. This may contain a `*`; the entire word, before and after\nthe `*` is completed, but only the text before the `*` is required\nfor the context to be matched, so that further arguments may be\ncompleted after the abbreviated form.\n\nThe second part of _spec_ is a description for the word being\ncompleted.\n\nThe optional third part of the _spec_ describes how words following\nthe one being completed are themselves to be completed. It will be\nevaluated in order to avoid problems with quoting. This means that\ntypically it contains a reference to an array containing previously\ngenerated regex arguments.\n\nThe option `-t` _term_ specifies a terminator for the word\ninstead of the usual space. This is handled as an auto-removable suffix\nin the manner of the option `-s` _sep_ to `_values`.\n\nThe result of the processing by `_regex_words` is placed in the array\n`reply`, which should be made local to the calling function.\nIf the set of words and arguments may be matched repeatedly, a `#`\nshould be appended to the generated array at that point.\n\nFor example:\n\n local -a reply\n_regex_words mydb-commands 'mydb commands' \\\n 'add:add an entry to mydb:$mydb_add_cmds' \\\n 'show:show entries in mydb'\n_regex_arguments _mydb \"$reply[@]\"\n_mydb \"$@\"\n\nThis shows a completion function for a command `mydb` which takes\ntwo command arguments, `add` and `show`. `show` takes no arguments,\nwhile the arguments for `add` have already been prepared in an\narray `mydb_add_cmds`, quite possibly by a previous call to\n`_regex_words`."),
("_requested", "This function is called to decide whether a tag already registered by a\ncall to `_tags` (see below) has been requested by the user and hence\ncompletion should be performed for it. It returns status zero if the\ntag is requested and non-zero otherwise. The function is typically used\nas part of a loop over different tags as follows:\n\n _tags foo bar baz\nwhile _tags; do\n if _requested foo; then\n ... # perform completion for foo\n fi\n ... # test the tags bar and baz in the same way\n ... # exit loop if matches were generated\ndone\n\nNote that the test for whether matches were generated is not performed\nuntil the end of the `_tags` loop. This is so that the user can set\nthe `tag-order` style to specify a set of tags to be completed at the\nsame time.\n\nIf _name_ and _descr_ are given, `_requested` calls the\n`_description` function with these arguments together with the options\npassed to `_requested`.\n\nIf _command_ is given, the `_all_labels` function will be called\nimmediately with the same arguments. In simple cases this makes it\npossible to perform the test for the tag and the matching in one go.\nFor example:\n\nexample(local expl ret=1\n_tags foo bar baz\nwhile _tags; do\n _requested foo expl 'description' \\\n compadd foobar foobaz && ret=0\n ...\n (( ret )) || break\ndone)\n\nIf the _command_ is not `compadd`, it must nevertheless be prepared\nto handle the same options."),
("_retrieve_cache", "This function retrieves completion information from the file given by\n_cache_identifier_, stored in a directory specified by the\n`cache-path` style which defaults to `~/.zcompcache`. The return status\nis zero if retrieval was successful. It will only attempt retrieval\nif the `use-cache` style is set, so you can call this function\nwithout worrying about whether the user wanted to use the caching\nlayer.\n\nSee `_store_cache` below for more details."),
("_sep_parts", "This function is passed alternating arrays and separators as arguments.\nThe arrays specify completions for parts of strings to be separated by the\nseparators. The arrays may be the names of array parameters or\na quoted list of words in parentheses. For example, with the array\n\"tt(hosts=(ftp news))\" the call \"tt(_sep_parts \"(foo bar)' @ hosts)' will\ncomplete the string \"f\" to \"foo\" and the string \"b@n\" to\n\"bar@news\".\n\nThis function accepts the `compadd` options \"-V\", \"-J\",\n\"-1\", \"-2\", \"-n\", \"-X\", \"-M\", \"-P\", \"-S\",\n\"-r\", \"-R\", and \"-q\" and passes them on to the `compadd`\nbuiltin used to add the matches."),
("_sequence", "This function is a wrapper to other functions for completing items in a\nseparated list. The same function is used to complete each item in the\nlist. The separator is specified with the `-s` option. If `-s` is\nomitted it will use \",\". Duplicate values are not matched unless\n`-d` is specified. If there is a fixed or maximum number of items in\nthe list, this can be specified with the `-n` option.\n\nCommon `compadd` options are passed on to the function. It is possible\nto use `compadd` directly with `_sequence`, though `_values` may\nbe more appropriate in this situation."),
("_setup", "This function sets up the special\nparameters used by the completion system appropriately for the _tag_\ngiven as the first argument. It uses the styles `list-colors`,\n`list-packed`, `list-rows-first`, `last-prompt`, `accept-exact`,\n`menu` and `force-list`.\n\nThe optional _group_ supplies the name of the group in which the\nmatches will be placed. If it is not given, the _tag_ is used as\nthe group name.\n\nThis function is called automatically from `_description`\nand hence is not normally called explicitly."),
("_unshadow", "The `_shadow` function creates a copy of each of the shell functions\nin the _command_name_ arguments. The original functions can then\nbe replaced by new implementations. A later call to `_unshadow`\nremoves the new implementations, if any, and restores the originals.\n\nRecommended usage is to pair `_shadow` and `_unshadow` calls by\nuse of an \"always\" block:\n\n {\n _shadow fname\n function fname {\n # Do your new thing\n }\n # Invoke callers of fname\n} always {\n _unshadow\n}\n\nThe _suffix_, if supplied, is prepended by an \"@\" character and\nthen appended to each _command_name_ to create the copy. Thus\n\n _shadow -s XX foo\n\ncreates a function named \"foo@XX\". This provides a well-known\nname for the original implementation if the new implementation needs\nto call it as a wrapper. If a nested call to `_shadow` uses the\nsame _suffix_, _no new copy is made_. The presumption thus is\nthat suffixes and new implementations correspond one to one.\n\nIf _command_name_ is a builtin or external command, and there has been\nno preceding `_shadow` replacement made, the function so created calls\nthe shadowed name prefixed by the `builtin` or `command` keywords as\nappropriate.\nexample({\n _shadow -s wrap compadd\n compadd () {\n # compadd@wrap runs builtin compadd\n compadd@wrap -O tmparr \"$@\" }\n} always {\n _unshadow\n})\n\nWhen no _suffix_ argument is present, `_shadow` creates a unique\nsuffix to avoid name collisions.\n\nArguments of `_unshadow` are ignored. Every listed _command_name_\nfor the most recent call to `_shadow` is removed. This differs from\nan early implementation that required `_unshadow` to receive the\nsame _suffix_ and _command_name_ list as `_shadow`."),
("_store_cache", "This function, together with `_retrieve_cache` and\n`_cache_invalid`, implements a caching layer which can be used\nin any completion function. Data obtained by\ncostly operations are stored in parameters;\nthis function then dumps the values of those parameters to a file. The\ndata can then be retrieved quickly from that file via `_retrieve_cache`,\neven in different instances of the shell.\n\nThe _cache_identifier_ specifies the file which the data should be\ndumped to. The file is stored in a directory specified by the\n`cache-path` style which defaults to `~/.zcompcache`. The remaining\n_param_s arguments are the parameters to dump to the file.\n\nThe return status is zero if storage was successful. The function will\nonly attempt storage if the `use-cache` style is set, so you can\ncall this function without worrying about whether the user wanted to\nuse the caching layer.\n\nThe completion function may avoid calling `_retrieve_cache` when it\nalready has the completion data available as parameters.\nHowever, in that case it should\ncall `_cache_invalid` to check whether the data in the parameters and\nin the cache are still valid.\n\nSee the _perl_modules completion function for a simple example of\nthe usage of the caching layer."),
("_tags", "If called with arguments, these are taken to be the names of tags\nvalid for completions in the current context. These tags are stored\ninternally and sorted by using the `tag-order` style.\n\nNext, `_tags` is called repeatedly without arguments from the same\ncompletion function. This successively selects the first, second,\netc. set of tags requested by the user. The return status is zero if at\nleast one of the tags is requested and non-zero otherwise. To test if a\nparticular tag is to be tried, the `_requested` function should be\ncalled (see above).\n\nIf ``-C\" _name_\" is given, _name_ is temporarily stored in the\n_argument_ field (the fifth) of the context in the `curcontext` parameter\nduring the call to `_tags`; the field is restored on exit. This\nallows `_tags` to use a more\nspecific context without having to change and reset the\n`curcontext` parameter (which has the same effect)."),
("_tilde_files", "Like `_files`, but resolve leading tildes according to the rules of\nfilename expansion, so the suggested completions don't start with\na \"~\" even if the filename on the command-line does."),
("_values", "This is used to complete arbitrary keywords (values) and their arguments,\nor lists of such combinations.\n\nIf the first argument is the option ``-O\" _name_\", it will be used\nin the same way as by the `_arguments` function. In other words, the\nelements of the _name_ array will be passed to `compadd`\nwhen executing an action.\n\nIf the first argument (or the first argument after ``-O\" _name_\")\nis \"-s\", the next argument is used as the character that separates\nmultiple values. This character is automatically added after each value\nin an auto-removable fashion (see below); all values completed by\n\"_values -s\" appear in the same word on the command line, unlike\ncompletion using `_arguments`. If this option is not present, only a\nsingle value will be completed per word.\n\nNormally, `_values` will only use the current word to determine\nwhich values are already present on the command line and hence are not\nto be completed again. If the `-w` option is given, other arguments\nare examined as well.\n\nThe first non-option argument, _desc_, is used as a string to print as a\ndescription before listing the values.\n\nAll other arguments describe the possible values and their\narguments in the same format used for the description of options by\nthe `_arguments` function (see above). The only differences are that\nno minus or plus sign is required at the beginning,\nvalues can have only one argument, and the forms of action\nbeginning with an equal sign are not supported.\n\nThe character separating a value from its argument can be set using the\noption `-S` (like `-s`, followed by the character to use as the\nseparator in the next argument). By default the equals\nsign will be used as the separator between values and arguments.\n\nExample:\n\nexample(_values -s , 'description' \\\n '*foo[bar]' \\\n '(two)*one[number]:first count:' \\\n 'two[another number]::second count:(1 2 3)')\n\nThis describes three possible values: \"foo\", \"one\", and\n\"two\". The first is described as \"bar\", takes no argument\nand may appear more than once. The second is described as\n\"number\", may appear more than once, and takes one mandatory\nargument described as \"first count\"; no action is\nspecified, so it will not be completed. The\n\"tt((two))\" at the beginning says that if the value \"one\" is on\nthe line, the value \"two\" will no longer be considered a possible\ncompletion. Finally, the last value (\"two\") is described\nas \"another number\" and takes an optional argument described as\n\"second count\" for which the completions (to appear after an\n\"=\") are \"1\", \"2\", and \"3\". The `_values` function\nwill complete lists of these values separated by commas.\n\nLike `_arguments`, this function temporarily adds another context name\ncomponent to the arguments element (the fifth) of the current context\nwhile executing the _action_. Here this name is just the name of the\nvalue for which the argument is completed.\n\nThe style `verbose` is used to decide if the descriptions for the\nvalues (but not those for the arguments) should be printed.\n\nThe associative array `val_args` is used to report values and their\narguments; this works similarly to the `opt_args` associative array\nused by `_arguments`. Hence the function calling `_values` should\ndeclare the local parameters `state`, `state_descr`, `line`,\n`context` and `val_args`:\n\n local context state state_descr line\ntypeset -A val_args\n\nwhen using an action of the form ``->\"_string_\". With this\nfunction the `context` parameter will be set to the name of the\nvalue whose argument is to be completed. Note that for `_values`,\nthe `state` and `state_descr` are scalars rather than arrays.\nOnly a single matching state is returned.\n\nNote also that `_values` normally adds the character used as the\nseparator between values as an auto-removable suffix (similar to a\n\"/\" after a directory). However, this is not possible for a\n``->\"_string_\" action as the matches for the argument are\ngenerated by the calling function. To get the usual behaviour,\nthe calling function can add the separator _x_ as a suffix by\npassing the options ``-qS\" _x_\" either directly or indirectly to\n`compadd`.\n\nThe option `-C` is treated in the same way as it is by `_arguments`.\nIn that case the parameter `curcontext` should be made local instead\nof `context` (as described above)."),
("_wanted", "In many contexts, completion can only generate one particular set of\nmatches, usually corresponding to a single tag. However, it is\nstill necessary to decide whether the user requires matches of this type.\nThis function is useful in such a case.\n\nThe arguments to `_wanted` are the same as those to `_requested`,\ni.e. arguments to be passed to `_description`. However, in this case\nthe _command_ is not optional; all the processing of tags, including\nthe loop over both tags and tag labels and the generation of matches,\nis carried out automatically by `_wanted`.\n\nHence to offer only one tag and immediately add the corresponding\nmatches with the given description:\n\n local expl\n_wanted tag expl 'description' \\\n compadd -- _match1_ _match2_...\n\nNote that, as for `_requested`, the _command_ must be able to\naccept options to be passed down to `compadd`.\n\nLike `_tags` this function supports the `-C` option to give a\ndifferent name for the argument context field. The `-x` option has\nthe same meaning as for `_description`."),
("_widgets", "This function completes names of zle widgets (see\n_Zle Widgets_ (zshzle)).\nThe _pattern_, if present, is matched against values of the `$widgets`\nspecial parameter, documented in\n_The zsh/zleparameter Module_ (zshmodules)."),
("_comp_caller_options", "The completion system uses `setopt` to set a number of options. This\nallows functions to be written without concern for compatibility with\nevery possible combination of user options. However, sometimes completion\nneeds to know what the user's option preferences are. These are saved\nin the `_comp_caller_options` associative array. Option names, spelled\nin lowercase without underscores, are mapped to one or other of the\nstrings \"on\" and \"off\"."),
("_comp_priv_prefix", "Completion functions such as `_sudo` can set the `_comp_priv_prefix`\narray to a command prefix that may then be used by `_call_program` to\nmatch the privileges when calling programs to generate matches."),
("Base", "The core functions and special completion widgets automatically bound\nto keys. You will certainly need most of these, though will\nprobably not need to alter them. Many of these are documented above."),
("Zsh", "Functions for completing arguments of shell builtin commands and\nutility functions for this. Some of these are also used by functions from\nthe `Unix` directory."),
("Unix", "Functions for completing arguments of external commands and suites of\ncommands. They may need modifying for your system, although in many cases\nsome attempt is made to decide which version of a command is present. For\nexample, completion for the `mount` command tries to determine the system\nit is running on, while completion for many other utilities try to decide\nwhether the GNU version of the command is in use, and hence whether the\n`-``-help` option is supported."),
("X", "Completion and utility function for commands available only on some systems.\nThese are not arranged hierarchically, so, for example, both the\n`Linux` and `Debian` directories, as well as the `X` directory,\nmay be useful on your system."),
("CURRENT", "This is the number of the current word, i.e. the word the cursor is\ncurrently on in the `words` array. Note that this value is only\ncorrect if the `ksharrays` option is not set."),
("IPREFIX", "Initially this will be set to the empty string. This parameter functions\nlike `PREFIX`; it contains a string which precedes the one in `PREFIX`\nand is not considered part of the list of matches. Typically, a string is\ntransferred from the beginning of `PREFIX` to the end of `IPREFIX`, for\nexample:\n\n IPREFIX=${PREFIX%%\\=*}=\nPREFIX=${PREFIX#*=}\n\ncauses the part of the prefix up to and including the first equal sign not\nto be treated as part of a matched string. This can be done automatically\nby the `compset` builtin, see below."),
("ISUFFIX", "As `IPREFIX`, but for a suffix that should not be considered part\nof the matches; note that the `ISUFFIX` string follows the `SUFFIX`\nstring."),
("PREFIX", "Initially this will be set to the part of the current word from the\nbeginning of the word up to the position of the cursor; it may be altered\nto give a common prefix for all matches."),
("QIPREFIX", "This parameter is read-only and contains the quoted string up to the\nword being completed. E.g. when completing \"\"foo\", this parameter\ncontains the double quote. If the `-q` option of `compset` is used\n(see below), and the original string was \"\"foo bar\" with the\ncursor on the \"bar\", this parameter contains \"\"foo \"."),
("QISUFFIX", "Like `QIPREFIX`, but containing the suffix."),
("SUFFIX", "Initially this will be set to the part of the current word from the\ncursor position to the end; it may be altered to give a common suffix for\nall matches. It is most useful when the option `COMPLETE_IN_WORD` is\nset, as otherwise the whole word on the command line is treated as a\nprefix."),
("compstate", "This is an associative array with various keys and values that the\ncompletion code uses to exchange information with the completion widget.\nThe keys are:\n\nvindex(all_quotes, compstate)\n\n- **`all_quotes`** â The `-q` option of the `compset` builtin command (see below)\nallows a quoted string to be broken into separate words; if the cursor is\non one of those words, that word will be completed, possibly invoking\n\"compset -q\" recursively. With this key it is possible to test the\ntypes of quoted strings which are currently broken into parts in this\nfashion. Its value contains one character for each quoting level. The\ncharacters are a single quote or a double quote for strings quoted with\nthese characters, a dollars sign for strings quoted with\n\"$\"`_..._`'` and a backslash for strings not starting with a\nquote character. The first character in the value always corresponds to the\ninnermost quoting level.\n)\nvindex(context, compstate)\n\n- **`context`** â This will be set by the completion code to the overall context\nin which completion is attempted. Possible values are:\n\n- **`array_value`** âÂÂ\nwhen completing inside the value of an array parameter assignment; in\nthis case the `words` array contains the words inside the parentheses.\n\n\n- **`brace_parameter`** â when completing the name of a parameter in a parameter expansion beginning\nwith `${`. This context will also be set when completing parameter\nflags following tt(${(); the full command line argument is presented\nand the handler must test the value to be completed to ascertain that\nthis is the case.\n\n- **`assign_parameter`** âÂÂ\nwhen completing the name of a parameter in a parameter assignment.\n\n\n- **`command`** â when completing for a normal command (either in command position or for\nan argument of the command).\n\n\n- **`condition`** âÂÂ\nwhen completing inside a ``[[`...`]]`' conditional expression; in\nthis case the `words` array contains only the words inside the\nconditional expression.\n\n\n- **`math`** â when completing in a mathematical environment such as a\n`tt((()...`\"))\" construct.\n\n\n- **`parameter`** âÂÂ\nwhen completing the name of a parameter in a parameter expansion beginning\nwith `$` but not `${`.\n\n- **`redirect`** âÂÂ\nwhen completing after a redirection operator.\n\n- **`subscript`** âÂÂ\nwhen completing inside a parameter subscript.\n\n- **`value`** âÂÂ\nwhen completing the value of a parameter assignment.\n\nvindex(exact, compstate)\n\n- **`exact`** âÂÂ\nControls the behaviour when the `REC_EXACT` option is set. It will be\nset to `accept` if an exact match would be accepted, and will be unset\notherwise.\n\nIf it was set when at least one match equal to the string on the line\nwas generated, the match is accepted.\n\nvindex(exact_string, compstate)\n\n- **`exact_string`** âÂÂ\nThe string of an exact match if one was found, otherwise unset.\n\nvindex(ignored, compstate)\n\n- **`ignored`** âÂÂ\nThe number of completions that were ignored because they matched one of the\npatterns given with the `-F` option to the `compadd` builtin\ncommand.\n\nvindex(insert, compstate)\n\n- **`insert`** â This controls the manner in which a match is inserted into the command\nline. On entry to the widget function, if it is unset the command line is\nnot to be changed; if set to `unambiguous`, any prefix common to all\nmatches is to be inserted; if set to `automenu-unambiguous`, the\ncommon prefix is to be inserted and the next invocation of the\ncompletion code may start menu completion (due to the `AUTO_MENU`\noption being set); if set to `menu` or `automenu` menu completion\nwill be started for the matches currently generated (in the\nlatter case this will happen because the `AUTO_MENU` is set). The\nvalue may also contain the string \"tab\" when the completion code\nwould normally not really do completion, but only insert the TAB\ncharacter.\n\nOn exit it may be set to any of the values above (where setting it to\nthe empty string is the same as unsetting it), or to a number, in which\ncase the match whose number is given will be inserted into the command line.\nNegative numbers count backward from the last match (with \"-1\"\nselecting the last match) and out-of-range values are wrapped\naround, so that a value of zero selects the last match and a value\none more than the maximum selects the first. Unless the value of this\nkey ends in a space, the match is inserted as in a menu completion,\ni.e. without automatically appending a space.\n\nBoth `menu` and `automenu` may also specify the number of the\nmatch to insert, given after a colon. For example, \"menu:2\" says\nto start menu completion, beginning with the second match.\n\nNote that a value containing the substring \"tab\" makes the\nmatches generated be ignored and only the TAB be inserted.\n\nFinally, it may also be set to `all`, which makes all matches\ngenerated be inserted into the line.\n\nvindex(insert_positions, compstate)\n\n- **`insert_positions`** âÂÂ\nWhen the completion system inserts an unambiguous string into the\nline, there may be multiple places where characters are missing or\nwhere the character inserted differs from at least one match. The\nvalue of this key contains a colon separated list of all these\npositions, as indexes into the command line.\n\nvindex(last_prompt, compstate)\n\n- **`last_prompt`** âÂÂ\nIf this is set to a non-empty string for every match added, the\ncompletion code will move the cursor back to the previous prompt after\nthe list of completions has been displayed. Initially this is set or\nunset according to the `ALWAYS_LAST_PROMPT` option.\n\nvindex(list, compstate)\n\n- **`list`** â This controls whether or how the list of matches will be displayed. If it\nis unset or empty they will never be listed; if its value begins with\n`list`, they will always be listed; if it begins with `autolist`\nor `ambiguous`, they will be listed when the `AUTO_LIST` or\n`LIST_AMBIGUOUS` options respectively would normally cause them to\nbe.\n\nIf the substring `force` appears in the value, this makes the\nlist be shown even if there is only one match. Normally, the list\nwould be shown only if there are at least two matches.\n\nThe value contains the substring `packed` if the `LIST_PACKED`\noption is set. If this substring is given for all matches added to a\ngroup, this group will show the `LIST_PACKED` behavior. The same is\ndone for the `LIST_ROWS_FIRST` option with the substring `rows`.\n\nFinally, if the value contains the string `explanations`, only the\nexplanation strings, if any, will be listed and if it contains\n`messages`, only the messages (added with the `-x` option of\n`compadd`) will be listed. If it contains both `explanations` and\n`messages` both kinds of explanation strings will be listed. It\nwill be set appropriately on entry to a completion widget and may be\nchanged there.\n\nvindex(list_lines, compstate)\n\n- **`list_lines`** âÂÂ\nThis gives the number of lines that are needed to display the full\nlist of completions. Note that to calculate the total number of lines\nto display you need to add the number of lines needed for the command\nline to this value, this is available as the value of the `BUFFERLINES`\nspecial parameter.\n\nvindex(list_max, compstate)\n\n- **`list_max`** âÂÂ\nInitially this is set to the value of the `LISTMAX` parameter.\nIt may be set to any other value; when the widget exits this value\nwill be used in the same way as the value of `LISTMAX`.\n\nvindex(nmatches, compstate)\n\n- **`nmatches`** âÂÂ\nThe number of matches added by the completion code so far.\n\nvindex(old_insert, compstate)\n\n- **`old_insert`** âÂÂ\nOn entry to the widget this will be set to the number of the match of\nan old list of completions that is currently inserted into the command\nline. If no match has been inserted, this is unset.\n\nAs with `old_list`, the value of this key will only be used if it is the\nstring `keep`. If it was set to this value by the widget and there was an\nold match inserted into the command line, this match will be kept and if\nthe value of the `insert` key specifies that another match should be\ninserted, this will be inserted after the old one.\n\nvindex(old_list, compstate)\n\n- **`old_list`** âÂÂ\nThis is set to `yes` if there is still a valid list of completions\nfrom a previous completion at the time the widget is invoked. This will\nusually be the case if and only if the previous editing operation was a\ncompletion widget or one of the builtin completion functions. If there is a\nvalid list and it is also currently shown on the screen, the value of this\nkey is `shown`.\n\nAfter the widget has exited the value of this key is only used if it\nwas set to `keep`. In this case the completion code will continue\nto use this old list. If the widget generated new matches, they will\nnot be used.\n\nvindex(parameter, compstate)\n\n- **`parameter`** âÂÂ\nThe name of the parameter when completing in a subscript or in the\nvalue of a parameter assignment.\n\nvindex(pattern_insert, compstate)\n\n- **`pattern_insert`** â Normally this is set to `menu`, which specifies that menu completion will\nbe used whenever a set of matches was generated using `pattern_match`\n(see below). If\nit is set to any other non-empty string by the user and menu completion is\nnot selected by other option settings, the code will instead insert any\ncommon prefix for the generated matches as with normal completion.\n\nvindex(pattern_match, compstate)\n\n- **`pattern_match`** â Locally controls the behaviour given by the `GLOB_COMPLETE` option.\nInitially it is set to \"*\" if and only if the option is set.\nThe completion widget may set it to this value, to an empty string\n(which has the same effect as unsetting it), or to any\nother non-empty string. If it is non-empty, unquoted metacharacters on the\ncommand line will be treated as patterns; if it is \"*\", then\nadditionally a wildcard \"*\" is assumed at the cursor position; if\nit is empty or unset, metacharacters will be treated literally.\n\nNote that the match specifications given to the `compadd` builtin\ncommand are not used if this is set to a non-empty string.\n\nvindex(quote, compstate)\n\n- **`quote`** â When completing inside quotes, this contains the quotation character\n(i.e. either a single quote, a double quote, or a backtick). Otherwise it\nis unset.\n\nvindex(quoting, compstate)\n\n- **`quoting`** âÂÂ\nWhen completing inside single quotes, this is set to the string\n`single`; inside double quotes, the string\n`double`; inside backticks, the string `backtick`.\nOtherwise it is unset.\n\nvindex(redirect, compstate)\n\n- **`redirect`** âÂÂ\nThe redirection operator when completing in a redirection position,\ni.e. one of `<`, `>`, etc.\n\nvindex(restore, compstate)\n\n- **`restore`** â This is set to `auto` before a function is entered, which forces the\nspecial parameters mentioned above (`words`, `CURRENT`, `PREFIX`,\n`IPREFIX`, `SUFFIX`, and `ISUFFIX`) to be restored to their\nprevious values when the function exits. If a function unsets it or\nsets it to any other string, they will not be restored.\n\nvindex(to_end, compstate)\n\n- **`to_end`** â Specifies the occasions on which the cursor is moved to the end of a string\nwhen a match is inserted. On entry to a widget function, it may be\n`single` if this will happen when a single unambiguous match was inserted\nor `match` if it will happen any time a match is inserted (for example,\nby menu completion; this is likely to be the effect of the `ALWAYS_TO_END`\noption).\n\nOn exit, it may be set to `single` as above. It may also be set to\n`always`, or to the empty string or unset; in those cases the cursor will\nbe moved to the end of the string always or never respectively. Any\nother string is treated as `match`.\n\nvindex(unambiguous, compstate)\n\n- **`unambiguous`** â This key is read-only and will always be set to the common (unambiguous)\nprefix the completion code has generated for all matches added so far.\n\nvindex(unambiguous_cursor, compstate)\n\n- **`unambiguous_cursor`** âÂÂ\nThis gives the position the cursor would be placed at if the\ncommon prefix in the `unambiguous` key were inserted, relative to\nthe value of that key. The cursor would be placed before the character\nwhose index is given by this key.\n\nvindex(unambiguous_positions, compstate)\n\n- **`unambiguous_positions`** âÂÂ\nThis contains all positions where characters in the unambiguous string\nare missing or where the character inserted differs from at least one\nof the matches. The positions are given as indexes into the string\ngiven by the value of the `unambiguous` key.\n\nvindex(vared, compstate)\n\n- **`vared`** âÂÂ\nIf completion is called while editing a line using the `vared`\nbuiltin, the value of this key is set to the name of the parameter\ngiven as an argument to `vared`. This key is only set while a `vared`\ncommand is active."),
("words", "This array contains the words present on the command line currently being\nedited."),
("compadd", "This builtin command can be used to add matches directly and control\nall the information the completion code stores with each possible\ncompletion. The return status is zero if at least one match was added and\nnon-zero if no matches were added.\n\nThe completion code breaks each match into seven fields in the order:\n\n _<ipre><apre><hpre><body><hsuf><asuf><isuf>_\n\nThe first field\nis an ignored prefix taken from the command line, the contents of the\n`IPREFIX` parameter plus the string given with the `-i`\noption. With the `-U` option, only the string from the `-i`\noption is used. The field _<apre>_ is an optional prefix string\ngiven with the `-P` option. The _<hpre>_ field is a string\nthat is considered part of the match but that should not be shown when\nlisting completions, given with the `-p` option; for example,\nfunctions that do filename generation might specify\na common path prefix this way. _<body>_ is the part of the match that\nshould appear in the list of matches shown to the user.\nThe suffixes _<hsuf>_,\n_<asuf>_ and _<isuf>_ correspond to the prefixes _<hpre>_,\n_<apre>_ and _<ipre>_ and are given by the options `-s`, `-S` and\n`-I`, respectively.\n\nThe supported flags are:\n\n- **`-P` _prefix_** âÂÂ\nThis gives a string to be inserted before each match. The\nstring given is not considered as part of the match and any shell\nmetacharacters in it will not be quoted when the string is inserted.\n\n- **`-S` _suffix_** âÂÂ\nLike `-P`, but gives a string to be inserted after each match.\n\n- **`-p` _hidden-prefix_** âÂÂ\nThis gives a string that should be inserted before each\nmatch but that should not appear in the list of matches. Unless the\n`-U` option is given, this string must be matched as part of the string\non the command line.\n\n- **`-s` _hidden-suffix_** âÂÂ\nLike \"-p\", but gives a string to insert after each match.\n\n- **`-i` _ignored-prefix_** âÂÂ\nThis gives a string to insert just before any\nstring given with the \"-P\" option. Without \"-P\" the string is\ninserted before the string given with \"-p\" or directly before each\nmatch.\n\n- **`-I` _ignored-suffix_** âÂÂ\nLike `-i`, but gives an ignored suffix.\n\n- **`-a`** âÂÂ\nWith this flag the _completions_ are taken as names of arrays and the\nactual completions are their values. If only some elements of the\narrays are needed, the _completions_ may also contain subscripts, as in\n\"foo[2,-1]\".\n\n\n- **`-k`** â With this flag the _completions_ are taken as names of associative arrays\nand the actual completions are their keys. As for `-a`, the\n_words_ may also contain subscripts, as in \"tt(foo[(R)*bar*])\".\n\n\n- **`-d` _array_** âÂÂ\nThis adds per-completion display strings. The _array_ should contain one\nelement per _completion_ given. The completion code will then display the\nfirst element instead of the first _completion_, and so on. The\n_array_ may be given as the name of an array parameter or directly\nas a space-separated list of words in parentheses.\n\nIf there are fewer display strings than _completions_, the leftover\n_completions_ will be displayed unchanged and if there are more display\nstrings than _completions_, the leftover display strings will be silently\nignored.\n\n- **`-l`** âÂÂ\nThis option only has an effect if used together with the `-d`\noption. If it is given, the display strings are listed one per line,\nnot arrayed in columns.\n\n\n- **`-o` [ _order_ ]** â This controls the order in which matches are sorted. _order_ is a\ncomma-separated list comprising the following possible values. These values\ncan be abbreviated to their initial two or three characters. Note that the\norder forms part of the group name space so matches with different orderings\nwill not be in the same group; additionally, since ordering flags are not\nrespected on the default group, a group name must be given explicitly. See\n`-J` and `-V` below.\n\n\n- **`match`** â If given, the order of the output is determined by the match strings;\notherwise it is determined by the display strings (i.e. the strings given\nby the `-d` option). This is the default if \"-o\" is specified but\nthe _order_ argument is omitted.\n\n\n- **`nosort`** âÂÂ\nThis specifies that the _completions_\nare pre-sorted and their order should be\npreserved. This value only makes sense alone and cannot be combined with any\nothers.\n\n- **`numeric`** âÂÂ\nIf the matches include numbers, sort them numerically rather than\nlexicographically.\n\n- **`reverse`** âÂÂ\nArrange the matches backwards by reversing the sort ordering.\n\n\n- **`-J` _group-name_** âÂÂ\nGives the name of the group that the matches should be stored in.\n\n- **`-V` _group-name_** âÂÂ\nLike `-J` but naming an unsorted group. This option is identical to\nthe combination of `-J` and `-o nosort`.\n\n- **`-1`** âÂÂ\nIf given together with the `-V` option, makes\nonly consecutive duplicates in the group be removed. If combined with\nthe `-J` option, this has no visible effect. Note that groups\nwith and without this flag are in different name spaces.\n\n- **`-2`** âÂÂ\nIf given together with the `-J` or `-V` option, makes all\nduplicates be kept. Again, groups with and without this flag are in\ndifferent name spaces.\n\n\n- **`-X` _explanation_** â The _explanation_ string will be printed with the list of matches,\nabove the group currently selected.\n\nWithin the _explanation_, the following sequences may be used to\nspecify output attributes as described in\n_Expansion of Prompt Sequences_ (zshmisc):\n\"%B\", \"%S\", \"%U\", \"%F\", \"%K\" and their lower case\ncounterparts, as well as \"%H\" and ``%{`...`%}`'. \"%F\",\n\"%K\", \"%H\" and\n``%{`...`%}`' take arguments in the same form as prompt\nexpansion. (Note that the sequence \"%G\" is not available; an\nargument to \"%{\" should be used instead.) The sequence \"%%\"\nproduces a literal \"%\".\n\nThese sequences are most often employed by users when customising the\n`format` style (see subref(Standard Styles)(zshcompsys)),\nbut they must also be taken into account when writing completion\nfunctions, as passing descriptions with unescaped \"%\" characters\nto utility functions such as `_arguments` and `_message` may\nproduce unexpected results. If arbitrary text is to be passed in a\ndescription, it can be escaped using e.g. `${my_str//\\%/%%}`.\n\n\n- **`-x` _message_** âÂÂ\nLike `-X`, but the _message_ will be printed even if there are no\nmatches in the group.\n\n- **`-q`** âÂÂ\nThe suffix given with `-S` will be automatically removed if\nthe next character typed is a blank or does not insert anything, or if\nthe suffix consists of only one character and the next character typed\nis the same character.\n\n- **`-r` _remove-chars_** âÂÂ\nThis is a more versatile form of the `-q` option.\nThe suffix given with `-S` or the slash automatically added after\ncompleting directories will be automatically removed if\nthe next character typed inserts one of the characters given in the\n_remove-chars_. This string is parsed as a characters class and\nunderstands the backslash sequences used by the `print` command. For\nexample, \"-r \"a-z\\t\"\" removes the suffix if the next character typed\ninserts a lower case character or a TAB, and \"-r \"^0-9\"\" removes the\nsuffix if the next character typed inserts anything but a digit. One extra\nbackslash sequence is understood in this string: \"\\-\" stands for\nall characters that insert nothing. Thus \"-S \"=\" -q\" is the same\nas \"-S \"=\" -r \"= \\t\\n\\-\"\".\n\nThis option may also be used without the `-S` option; then any\nautomatically added space will be removed when one of the characters in the\nlist is typed.\n\n\n- **`-R` _remove-func_** â This is another form of the `-r` option. When a match\nhas been accepted and a suffix has been inserted, the function\n_remove-func_ will be called after the next character typed. It is\npassed the length of the suffix as an argument and can use the special\nparameters available in ordinary (non-completion) zle widgets (see\n_User-Defined Widgets_ (zshzle)\n) to analyse and modify the command line.\n\n\n- **`-f`** âÂÂ\nIf this flag is given, all of the matches built from the _completions_ are\nmarked as being the names of files. They are not required to be actual\nfilenames, but if they are, and the option `LIST_TYPES` is set, the\ncharacters describing the types of the files in the completion lists will\nbe shown. This also forces a slash to be added when the name of a\ndirectory is completed.\n\n- **`-e`** âÂÂ\nThis flag can be used to tell the completion code that the matches\nadded are parameter names for a parameter expansion. This will make\nthe `AUTO_PARAM_SLASH` and `AUTO_PARAM_KEYS` options be used for\nthe matches.\n\n- **`-W` _file-prefix_** âÂÂ\nThis string is a pathname that will be prepended to each match together\nwith any prefix specified by the `-p` option to form a complete filename\nfor testing. Hence it is only useful if combined with the `-f` flag, as\nthe tests will not otherwise be performed.\n\n\n- **`-F` _array_** â Specifies an array containing patterns. _completions_ that match one of\nthese patterns are ignored, that is, not considered to be matches.\n\nThe _array_ may be the name of an array parameter or a list of\nliteral patterns enclosed in parentheses and quoted, as in `tt(-F \"(*?.o\n*?.h)\")'. If the name of an array is given, the elements of the array are\ntaken as the patterns.\n)\n\n- **`-Q`** âÂÂ\nThis flag instructs the completion\ncode not to quote any metacharacters in the matches when inserting them\ninto the command line.\n\n\n- **`-M` _match-spec_** â This gives local match specifications as described below in\n(Completion Matching Control). This option may be given more than once.\nIn this case all _match-spec_s given are concatenated with spaces\nbetween them to form the specification string to use.\nNote that they will only be used if the `-U` option is not given.\n\n\n- **`-n`** âÂÂ\nSpecifies that matching _completions_ are to be added to the set of\nmatches, but are not to be listed to the user.\n\n- **`-U`** âÂÂ\nIf this flag is given, all _completions_ are added\nto the set of matches and no matching\nwill be done by the completion code. Normally this is used in\nfunctions that do the matching themselves.\n\n- **`-O` _array_** âÂÂ\nIf this option is given, the _completions_ are _not_ added to the set of\nmatches. Instead, matching is done as usual and all of the\n_completions_ that match\nwill be stored in the array parameter whose name is given as _array_.\n\n- **`-A` _array_** âÂÂ\nAs the `-O` option, except that instead of those of the _completions_\nwhich\nmatch being stored in _array_, the strings generated internally by the\ncompletion code are stored. For example,\nwith a match specification of \"-M \"L:|no=\"\", a current word of \"nof\"\nand _completions_ of \"foo\", this\noption stores the string \"nofoo\" in the array, whereas the `-O`\noption stores the \"foo\" originally given.\n\n- **`-D` _array_** âÂÂ\nAs with `-O`, the _completions_ are not added to the set of matches.\nInstead, whenever the _n_th _completion_ does not\nmatch, the _n_th element of the _array_ is removed. Elements\nfor which the corresponding _completion_ matches are retained.\nThis option can be used more than once to remove elements from multiple\narrays.\n\n- **`-C`** âÂÂ\nThis option adds a special match which expands to all other matches\nwhen inserted into the line, even those that are added after this\noption is used. Together with the `-d` option it is possible to\nspecify a string that should be displayed in the list for this special\nmatch. If no string is given, it will be shown as a string containing\nthe strings that would be inserted for the other matches, truncated to\nthe width of the screen.\n\n\n- **`-E` _number_** â This option adds _number_ empty matches after matching _completions_ have\nbeen added. An empty match takes up space in completion listings but\nwill never be inserted in the line and can't be selected with menu\ncompletion or menu selection. This makes empty matches only useful to\nformat completion lists and to make explanatory string be shown in\ncompletion lists (since empty matches can be given display strings\nwith the `-d` option). And because all but one empty string would\notherwise be removed, this option implies the `-V` and `-2`\noptions (even if an explicit `-J` option is given). This can be\nimportant to note as it affects the name space into which matches are\nadded.\n\n\n- **`-`**\n\n- **`-``-`** âÂÂ\nThis flag ends the list of flags and options. All arguments after it\nwill be taken as the _completions_ even if they begin with\nhyphens.\n\nExcept for the `-M` flag, if any of these flags is given more than\nonce, the first one (and its argument) will be used."),
("compset", "This command simplifies modification of the special parameters,\nwhile its return status allows tests on them to be carried out.\n\nThe options are:\n\n- **`-p` _number_** âÂÂ\nIf the value of the `PREFIX` parameter is at least _number_\ncharacters long, the first _number_ characters are removed from it and\nappended to the contents of the `IPREFIX` parameter.\n\n- **`-P` [ _number_ ] _pattern_** âÂÂ\nIf the value of the `PREFIX` parameter begins with anything that\nmatches the _pattern_, the matched portion is removed from\n`PREFIX` and appended to `IPREFIX`.\n\nWithout the optional _number_, the longest match is taken, but\nif _number_ is given, anything up to the _number_th match is\nmoved. If the _number_ is negative, the _number_th longest\nmatch is moved. For example, if `PREFIX` contains the string\n\"a=b=c\", then \"compset -P \"*\\='` will move the string \"a=b=\"\ninto the `IPREFIX\" parameter, but \"compset -P 1 \"*\\=\"` will move only\nthe string \"a=\".\n\n- **`-s` _number_** âÂÂ\nAs `-p`, but transfer the last _number_ characters from the\nvalue of `SUFFIX` to the front of the value of `ISUFFIX`.\n\n- **`-S` [ _number_ ] _pattern_** âÂÂ\nAs `-P`, but match the last portion of `SUFFIX` and transfer the\nmatched portion to the front of the value of `ISUFFIX`.\n\n- **`-n` _begin_ [ _end_ ]** âÂÂ\nIf the current word position as specified by the parameter `CURRENT`\nis greater than or equal to _begin_, anything up to the\n_begin_th word is removed from the `words` array and the value\nof the parameter `CURRENT` is decremented by _begin_.\n\nIf the optional _end_ is given, the modification is done only if\nthe current word position is also less than or equal to _end_. In\nthis case, the words from position _end_ onwards are also removed from\nthe `words` array.\n\nBoth _begin_ and _end_ may be negative to count backwards\nfrom the last element of the `words` array.\n\n\n- **`-N` _beg-pat_ [ _end-pat_ ]** â If one of the elements of the `words` array before the one at the\nindex given by the value of the parameter `CURRENT` matches the\npattern _beg-pat_, all elements up to and including the matching one are\nremoved from the `words` array and the value of `CURRENT` is changed to\npoint to the same word in the changed array.\n\nIf the optional pattern _end-pat_ is also given, and there is an\nelement in the `words` array matching this pattern, the parameters\nare modified only if the index of this word is higher than the one\ngiven by the `CURRENT` parameter (so that the matching word has\nto be after the cursor). In this case, the words starting with the one\nmatching `end-pat` are also removed from the `words`\narray. If `words` contains no word matching _end-pat_, the\ntesting and modification is performed as if it were not given.\n\n\n- **`-q`** âÂÂ\nThe word\ncurrently being completed is split on spaces into separate words,\nrespecting the usual shell quoting conventions. The\nresulting words are stored in the `words` array, and `CURRENT`,\n`PREFIX`, `SUFFIX`, `QIPREFIX`, and `QISUFFIX` are modified to\nreflect the word part that is completed.\n\nIn all the above cases the return status is zero if the test succeeded\nand the parameters were modified and non-zero otherwise. This allows\none to use this builtin in tests such as:\n\n if compset -P '*\\='; then ...\n\nThis forces anything up to and including the last equal sign to be\nignored by the completion code."),
("compcall", "This allows the use of completions defined with the `compctl` builtin\nfrom within completion widgets. The list of matches will be generated as\nif one of the non-widget completion functions (`complete-word`, etc.)\nhad been called, except that only `compctl`s given for specific commands\nare used. To force the code to try completions defined with the `-T`\noption of `compctl` and/or the default completion (whether defined by\n`compctl -D` or the builtin default) in the appropriate places, the\n`-T` and/or `-D` flags can be passed to `compcall`.\n\nThe return status can be used to test if a matching `compctl`\ndefinition was found. It is non-zero if a `compctl` was found and\nzero otherwise.\n\nNote that this builtin is defined by the `zsh/compctl` module."),
("M", "For each substring of the current word that matches _word-pat_, broaden the\ncorresponding part of the match pattern to additionally match _match-pat_.\n\n- **Examples:** âÂÂ\n\n`m:{[:lower:]}={[:upper:]}` lets any lower case character in the current word\nbe completed to itself or its uppercase counterpart. So, the completions\n\"foo\", \"FOO\" and \"Foo\" will are be considered matches for the word\n\"fo\".\n\n`M:_=` inserts every underscore from the current word into each match, in the\nsame relative position, determined by matching the substrings around it. So,\ngiven a completion \"foo\", the word \"f_o\" will be completed to the match\n\"f_oo\", even though the latter was not present as a completion."),
("E", "For each consecutive substring at the `b:`eginning or `e:`nd of the current\nword that matches _word-pat_, broaden the corresponding part of the match\npattern to additionally match _match-pat_.\n\n- **Examples:** âÂÂ\n\n\"b:-=+\" lets any number of minuses at the start of the current word be\ncompleted to a minus or a plus.\n\n\"B:0=\" adds all zeroes at the beginning of the current word to the\nbeginning of each match."),
("R", "If there is a substring at the `l:`eft or `r:`ight edge of the current word\nthat matches _word-pat_, then broaden the corresponding part of the match\npattern to additionally match _match-pat_.\n\nFor each `l:`, `L:`, `r:` and `R:` matcher (including the ones below),\nthe pattern _match-pat_ may also be a \"*\". This matches any number of\ncharacters in a completion.\n\n- **Examples:** âÂÂ\n\n\"r:|=*\" appends a \"*\" to the match pattern, even when\n`COMPLETE_IN_WORD` is set and the cursor is not at the end of the current\nword.\n\nIf the current word starts with a minus, then \"L:|-=\" will prepend it to\neach match."),
("R", "For each substring of the current word that matches _word-pat_ and has on\nits `l:`eft or `r:`ight another substring matching _anchor_, broaden the\ncorresponding part of the match pattern to additionally match _match-pat_.\n\nNote that these matchers (and the ones below) modify only what is matched by\n_word-pat_; they do not change the matching behavior of what is matched by\n_anchor_ (or _coanchor_; see the matchers below). Thus, unless its\ncorresponding part of the match pattern has been modified, the anchor in the\ncurrent word has to match literally in each completion, just like any other\nsubstring of the current word.\n\nIf a matcher includes at least one anchor (which includes the matchers with two\nanchors, below), then _match-pat_ may also be \"*\" or \"**\". \"*\"\ncan match any part of a completion that does not contain any substrings\nmatching _anchor_, whereas a \"**\" can match any part of a completion,\nperiod. (Note that this is different from the behavior of \"*\" in the\nanchorless forms of \"l:\" and \"r:\" and also different from \"*\"\nand \"**\" in glob expressions.)\n\n\n- **Examples:** â \"r:|.=*\" makes the completion \"comp.sources.unix\" a match for the word\n\"..u\" DASH()- but _not_ for the word \".u\".\n\nGiven a completion ``-\"-foo\", the matcher \"L:--|no-=\" will complete\nthe word ``-\"-no-\" to the match ``-\"-no-foo\".\n"),
("R", "For any two consecutive substrings of the current word that match _anchor_\nand _coanchor_, in the order given, insert the pattern _match-pat_\nbetween their corresponding parts in the match pattern.\n\nNote that, unlike _anchor_, the pattern _coanchor_ does not change what\n\"*\" can match.\n\n\n- **Examples:** â \"r:?||[[:upper:]]=*\" will complete the current word \"fB\" to\n\"fooBar\", but it will not complete it to \"fooHooBar\" (because \"*\"\nhere cannot match anything that includes a match for ``[[:upper:]]`), nor\nwill it complete \"B\" to \"fooBar\" (because there is no character in the\ncurrent word to match _coanchor_).\n\nGiven the current word \"pass.n\" and a completion \"pass.byname\", the\nmatcher \"L:.||[[:alpha:]]=by\" will produce the match \"pass.name\".\n"),
("x", "Ignore this matcher and all matchers to its right.\n\nThis matcher is used to mark the end of a match specification. In a single\nstandalone list of matchers, this has no use, but where match specifications\nare concatenated, as is often the case when using the\nifzman(completion system (see zmanref(zshcompsys)))\\\nifnzman((Completion System))\\\n, it can allow one match specification to override another."),
("zrecompile", "This tries to find `*.zwc` files and automatically re-compile them if at\nleast one of the original files is newer than the compiled file. This\nworks only if the names stored in the compiled files are full paths or are\nrelative to the directory that contains the `.zwc` file.\n\nIn the first form, each _name_ is the name of a compiled file or a\ndirectory containing `*.zwc` files that should be checked. If no\narguments are given, the directories and `*.zwc` files in `fpath` are\nused.\n\nWhen `-t` is given, no compilation is performed, but a return status of\nzero (true) is set if there are files that need to be re-compiled and\nnon-zero (false) otherwise. The `-q` option quiets the chatty output\nthat describes what `zrecompile` is doing.\n\nWithout the `-t` option, the return status is zero if all files that\nneeded re-compilation could be compiled and non-zero if compilation for at\nleast one of the files failed.\n\nIf the `-p` option is given, the _arg_s are interpreted as one\nor more sets of arguments for `zcompile`, separated by ``-\"-\".\nFor example:\n\n zrecompile -p \\\n -R ~/.zshrc -- \\\n -M ~/.zcompdump -- \\\n ~/zsh/comp.zwc ~/zsh/Completion/*/_*\n\nThis compiles `~/.zshrc` into `~/.zshrc.zwc\" if that doesn\"t exist or\nif it is older than `~/.zshrc`. The compiled file will be marked for\nreading instead of mapping. The same is done for `~/.zcompdump` and\n`~/.zcompdump.zwc`, but this compiled file is marked for mapping. The\nlast line re-creates the file `~/zsh/comp.zwc` if any of the files\nmatching the given pattern is newer than it.\n\nWithout the `-p` option, `zrecompile` does not create function digests\nthat do not already exist, nor does it add new functions to the digest."),
("reporter", "findex(reporter)\nPrint to standard output the indicated subset of the current shell state.\nThe _state_ arguments may be one or more of:\n\n- `all` â Output everything listed below.\n- `aliases` â Output alias definitions.\n- `bindings` â Output ZLE key maps and bindings.\n- `completion` â Output old-style `compctl` commands.\nNew completion is covered by `functions` and `zstyles`.\n- `functions` â Output autoloads and function definitions.\n- `limits` â Output `limit` commands.\n- `options` â Output `setopt` commands.\n- `styles` â Same as `zstyles`.\n- `variables` â Output shell parameter assignments, plus `export`\ncommands for any environment variables.\n- `zstyles` â Output `zstyle` commands.\n\nIf the _state_ is omitted, `all` is assumed."),
("add", "Several functions are special to the shell, as described in\n_Special Functions_ (zshmisc),\nin that they are automatically called at specific points during shell execution.\nEach has an associated array consisting of names of functions to be\ncalled at the same point; these are so-called \"hook functions\".\nThe shell function `add-zsh-hook` provides a simple way of adding or\nremoving functions from the array.\n\n_hook_ is one of `chpwd`, `periodic`, `precmd`, `preexec`,\n`zshaddhistory`, `zshexit`, or `zsh_directory_name`,\nthe special functions in question. Note that `zsh_directory_name`\nis called in a different way from the other functions, but may\nstill be manipulated as a hook.\n\n_function_ is name of an ordinary shell function. If no options\nare given this will be added to the array of functions to be executed\nin the given context.\nFunctions are invoked in the order they were added.\n\nIf the option `-L` is given, the current values for the hook arrays\nare listed with `typeset`.\n\nIf the option `-d` is given, the _function_ is removed from\nthe array of functions to be executed.\n\nIf the option `-D` is given, the _function_ is treated as a pattern\nand any matching names of functions are removed from the array of\nfunctions to be executed.\n\nThe options `-U`, `-z` and `-k` are passed as arguments to\n`autoload` for _function_. For functions contributed with zsh, the\noptions `-Uz` are appropriate."),
("add", "Several widget names are special to the line editor, as described in\nsubref(Special Widgets)(zshzle),\nin that they are automatically called at specific points during editing.\nUnlike function hooks, these do not use a predefined array of other names\nto call at the same point; the shell function `add-zle-hook-widget`\nmaintains a similar array and arranges for the special widget to invoke\nthose additional widgets.\n\n_hook_ is one of `isearch-exit`, `isearch-update`,\n`line-pre-redraw`, `line-init`, `line-finish`, `history-line-set`,\nor `keymap-select`, corresponding to each of the special widgets\n`zle-isearch-exit`, etc. The special widget names are also accepted\nas the _hook_ argument.\n\n_widgetname_ is the name of a ZLE widget. If no options are given this\nis added to the array of widgets to be invoked in the given hook context.\nWidgets are invoked in the order they were added, with\n\n `zle `_widgetname_` -Nw -f \"nolast\" -- \"$@\"`\n\nvindex(WIDGET, in hooks)\nNote that this means that the \"WIDGET\" special parameter tracks the\n_widgetname_ when the widget function is called, rather than tracking\nthe name of the corresponding special hook widget.\n\nIf the option `-d` is given, the _widgetname_ is removed from\nthe array of widgets to be executed.\n\nIf the option `-D` is given, the _widgetname_ is treated as a pattern\nand any matching names of widgets are removed from the array.\n\nIf _widgetname_ does not name an existing widget when added to the\narray, it is assumed that a shell function also named _widgetname_ is\nmeant to provide the implementation of the widget. This name is therefore\nmarked for autoloading, and the options `-U`, `-z` and `-k` are\npassed as arguments to `autoload` as with `add-zsh-hook`. The\nwidget is also created with ``zle -N \"_widgetname_\" to cause the\ncorresponding function to be loaded the first time the hook is called.\n\nThe arrays of _widgetname_ are currently maintained in `zstyle`\ncontexts, one for each _hook_ context, with a style of \"widgets\".\nIf the `-L` option is given, this set of styles is listed with\n\"zstyle -L\". This implementation may change, and the special widgets\nthat refer to the styles are created only if `add-zle-hook-widget` is\ncalled to add at least one widget, so if this function is used for any\nhooks, then all hooks should be managed only via this function."),
("recent", "If true, and the command is expecting a recent directory index, and\neither there is more than one argument or the argument is not an\ninteger, then fall through to \"cd\". This allows the lazy to use only\none command for directory changing. Completion recognises this, too;\nsee recent-dirs-insert for how to control completion when this option\nis in use."),
("recent", "The file where the list of directories is saved. The default\nis `${ZDOTDIR:-$HOME}/.chpwd-recent-dirs`, i.e. this is in your\nhome directory unless you have set the variable `ZDOTDIR` to point\nsomewhere else. Directory names are saved in \"$\"`_..._`'` quoted\nform, so each line in the file can be supplied directly to the shell as an\nargument.\n\nThe value of this style may be an array. In this case, the first\nfile in the list will always be used for saving directories while any\nother files are left untouched. When reading the recent directory\nlist, if there are fewer than the maximum number of entries in the\nfirst file, the contents of later files in the array will be appended\nwith duplicates removed from the list shown. The contents of the two\nfiles are not sorted together, i.e. all the entries in the first file\nare shown first. The special value `+` can appear in the list to\nindicate the default file should be read at that point. This allows\neffects like the following:\n\n zstyle ':chpwd:*' recent-dirs-file \\\n~/.chpwd-recent-dirs-${TTY##*/} +\n\nRecent directories are read from a file numbered according to\nthe terminal. If there are insufficient entries the list\nis supplemented from the default file.\n\nIt is possible to use `zstyle -e` to make the directory configurable\nat run time:\n\nexample(zstyle -e ':chpwd:*' recent-dirs-file pick-recent-dirs-file\npick-recent-dirs-file+() {\n if [[ $PWD = ~/text/writing+(|/*) ]]; then\n reply=(~/.chpwd-recent-dirs-writing)\n else\n reply=(+)\n fi\n})\n\nIn this example, if the current directory is `~/text/writing` or a\ndirectory under it, then use a special file for saving recent\ndirectories, else use the default."),
("recent", "Used by completion. If `recent-dirs-default` is true, then setting\nthis to `true` causes the actual directory, rather than its index, to\nbe inserted on the command line; this has the same effect as using\nthe corresponding index, but makes the history clearer and the line\neasier to edit. With this setting, if part of an argument was\nalready typed, normal directory completion rather than recent\ndirectory completion is done; this is because recent directory\ncompletion is expected to be done by cycling through entries menu\nfashion.\n\nIf the value of the style is `always`, then only recent directories will\nbe completed; in that case, use the `cd` command when you want to\ncomplete other directories.\n\nIf the value is `fallback`, recent directories will be tried first, then\nnormal directory completion is performed if recent directory completion\nfailed to find a match.\n\nFinally, if the value is `both` then both sets of completions are\npresented; the usual tag mechanism can be used to distinguish results, with\nrecent directories tagged as `recent-dirs`. Note that the recent\ndirectories inserted are abbreviated with directory names where appropriate."),
("recent", "The maximum number of directories to save to the file. If\nthis is zero or negative there is no maximum. The default is 20.\nNote this includes the current directory, which isn't offered,\nso the highest number of directories you will be offered\nis one less than the maximum."),
("recent", "This style is an array determining what directories should (or should\nnot) be added to the recent list. Elements of the array can include:\n\n\n- **`parent`** â Prune parents (more accurately, ancestors) from the recent list.\nIf present, changing directly down by any number of directories\ncauses the current directory to be overwritten. For example,\nchanging from ~pws to ~pws/some/other/dir causes ~pws not to be\nleft on the recent directory stack. This only applies to direct\nchanges to descendant directories; earlier directories on the\nlist are not pruned. For example, changing from ~pws/yet/another\nto ~pws/some/other/dir does not cause ~pws to be pruned.\n\n\n- **`pattern:`_pattern_** â Gives a zsh pattern for directories that should not be\nadded to the recent list (if not already there). This element\ncan be repeated to add different patterns. For example,\n`pattern:/tmp+(|/*)` stops `/tmp` or its descendants\nfrom being added. The `EXTENDED_GLOB` option is always turned on\nfor these patterns.\n"),
("recent", "If set to true, `cdr` will use `pushd` instead of `cd` to change the\ndirectory, so the directory is saved on the directory stack. As the\ndirectory stack is completely separate from the list of files saved\nby the mechanism used in this file there is no obvious reason to do\nthis."),
("g", "The top level directory for your git area. This first component\nhas to match, or the function will return indicating another\ndirectory name hook function should be tried."),
("p", "The name of a project within your git area."),
("s", "The source area within that project."),
("formats", "A list of formats, used when actionformats is not used\n(which is most of the time)."),
("actionformats", "A list of formats, used if there is a special\naction going on in your current repository; like an interactive rebase or\na merge conflict."),
("branchformat", "Some backends replace `%b` in the formats and\nactionformats styles above, not only by a branch name but also by a\nrevision number. This style lets you modify how that string should look."),
("nvcsformats", "These \"formats\" are set when we didn't detect a version control system\nfor the current directory or `vcs_info` was disabled. This is useful if\nyou want `vcs_info` to completely take over the generation of your\nprompt. You would do something like \"PS1=\"${vcs_info_msg_0_}'` to\naccomplish that."),
("hgrevformat", "`hg` uses both a hash and a revision number to reference a specific\nchangeset in a repository. With this style you can format the revision\nstring (see `branchformat\") to include either or both. It\"s only\nuseful when `get-revision` is true. Note, the full 40-character revision id\nis not available (except when using the `use-simple` option) because\nexecuting hg more than once per prompt is too slow; you may customize this\nbehavior using hooks."),
("max", "Defines the maximum number of\n`vcs_info_msg_*_` variables `vcs_info` will set."),
("enable", "A list of backends you want to use. Checked in the `-init-` context. If\nthis list contains an item called `NONE` no backend is used at all and\n`vcs_info` will do nothing. If this list contains `ALL`, `vcs_info`\nwill use all known backends. Only with `ALL` in `enable` will the\n`disable` style have any effect. `ALL` and `NONE` are case insensitive."),
("disable", "A list of VCSs you don't want `vcs_info` to test for\nrepositories (checked in the `-init-` context, too). Only used if\n`enable` contains `ALL`."),
("disable", "A list of patterns that are checked against `$PWD`. If a pattern\nmatches, `vcs_info` will be disabled. This style is checked in the\n`:vcs_info:-init-:*:-all-` context.\n\nSay, `~/.zsh` is a directory under version control, in which you do\nnot want `vcs_info` to be active, do:\nexample(zstyle ':vcs_info:*' disable-patterns \"${+(b+)HOME}/.zsh+(|/*+)\")"),
("use", "If enabled, the `quilt` support code is active in \"addon\" mode.\nSee ifzman(**Quilt Support**)ifnzman((vcs_info Quilt Support)) for details."),
("quilt", "If enabled, \"standalone\" mode detection is attempted if no VCS is active\nin a given directory. See ifzman(**Quilt Support**)ifnzman((vcs_info Quilt Support)) for details."),
("quilt", "Overwrite the value of the `$QUILT_PATCHES` environment variable. See\nifzman(**Quilt Support**)ifnzman((vcs_info Quilt Support)) for details."),
("quiltcommand", "When `quilt` itself is called in quilt support, the value of this style\nis used as the command name."),
("check", "If enabled, this style causes the `%c` and `%u` format escapes to show\nwhen the working directory has uncommitted changes. The strings displayed by\nthese escapes can be controlled via the `stagedstr` and `unstagedstr`\nstyles. The only backends that currently support this option are `git`,\n`hg`, and `bzr` (the latter two only support unstaged).\n\nFor this style to be evaluated with the `hg` backend, the `get-revision`\nstyle needs to be set and the `use-simple` style needs to be unset. The\nlatter is the default; the former is not.\n\nWith the `bzr` backend, _lightweight checkouts_ only honor this style if\nthe `use-server` style is set.\n\nNote, the actions taken if this style is enabled are potentially expensive\n(read: they may be slow, depending on how big the current repository is).\nTherefore, it is disabled by default."),
("check", "This style is like `check-for-changes`, but it never checks the worktree\nfiles, only the metadata in the `.${vcs}` dir. Therefore,\nthis style initializes only the `%c` escape (with `stagedstr`) but\nnot the `%u` escape. This style is faster than `check-for-changes`.\n\nIn the `git` backend, this style checks for changes in the index.\nOther backends do not currently implement this style.\n\nThis style is disabled by default."),
("stagedstr", "This string will be used in the `%c` escape if there are staged changes in\nthe repository."),
("unstagedstr", "This string will be used in the `%u` escape if there are unstaged changes\nin the repository."),
("command", "This style causes `vcs_info` to use the supplied string as the command\nto use as the VCS's binary. Note, that setting this in '`:vcs_info:*`' is\nnot a good idea.\n\nIf the value of this style is empty (which is the default), the used binary\nname is the name of the backend in use (e.g. `svn` is used in an `svn`\nrepository).\n\nThe `repo-root-name` part in the context is always the default `-all-`\nwhen this style is looked up.\n\nFor example, this style can be used to use binaries from non-default\ninstallation directories. Assume, `git` is installed in /usr/bin but\nyour sysadmin installed a newer version in /usr/local/bin. Instead of\nchanging the order of your `$PATH` parameter, you can do this:\n\n zstyle ':vcs_info:git:*:-all-' command /usr/local/bin/git"),
("use", "This is used by the Perforce backend (`p4`) to decide if it should\ncontact the Perforce server to find out if a directory is managed\nby Perforce. This is the only reliable way of doing this, but runs\nthe risk of a delay if the server name cannot be found. If the\nserver (more specifically, the _host_`:`_port_ pair describing the\nserver) cannot be contacted, its name is put into the associative array\n`vcs_info_p4_dead_servers` and is not contacted again during the session\nuntil it is removed by hand. If you do not set this style, the `p4`\nbackend is only usable if you have set the environment variable\n`P4CONFIG` to a file name and have corresponding files in the root\ndirectories of each Perforce client. See comments in the function\n`VCS_INFO_detect_p4` for more detail.\n\nThe Bazaar backend (`bzr`) uses this to permit contacting the server\nabout lightweight checkouts, see the `check-for-changes` style."),
("use", "If there are two different ways of gathering\ninformation, you can select the simpler one by setting this style to true;\nthe default is to use the not-that-simple code, which is potentially a lot\nslower but might be more accurate in all possible cases. This style is\nused by the `bzr`, `hg`, and `git` backends. In the case of `hg` it will invoke\nthe external hexdump program to parse the binary dirstate cache file; this\nmethod will not return the local revision number."),
("get", "If set to true, vcs_info goes the extra mile to figure out the revision of\na repository's work tree (currently for the `git` and `hg` backends,\nwhere this kind of information is not always vital). For `git`, the\nhash value of the currently checked out commit is available via the `%i`\nexpansion. With `hg`, the local revision number and the corresponding\nglobal hash are available via `%i`."),
("get", "If set to true, the `hg` backend will look for a Mercurial Queue (`mq`)\npatch directory. Information will be available via the \"%m\" replacement."),
("get", "If set to true, the `hg` backend will try to get a list of current\nbookmarks. They will be available via the \"%m\" replacement.\n\nThe default is to generate a comma-separated list of all bookmark names\nthat refer to the currently checked out revision. If a bookmark is active,\nits name is suffixed an asterisk and placed first in the list."),
("use", "Determines if we assume that the assembled\nstring from `vcs_info` includes prompt escapes. (Used by\n`vcs_info_lastmsg`.)"),
("debug", "Enable debugging output to track possible problems. Currently this style\nis only used by `vcs_info`'s hooks system."),
("hooks", "A list style that defines hook-function names. See ifzman(**Hooks in vcs_info**)\\\nifnzman((vcs_info Hooks))\nbelow for details."),
("nopatch", "This pair of styles format the patch information used by the `%m` expando in\nformats and actionformats for the `git` and `hg` backends. The value is\nsubject to certain `%`-expansions described below.\nThe expanded value is made available in the global `backend_misc` array as\n`${backend_misc[patches]}` (also if a `set-patch-format` hook is used)."),
("get", "This boolean style controls whether a backend should attempt to gather a list\nof unapplied patches (for example with Mercurial Queue patches).\n\nUsed by the `quilt`, `hg`, and `git` backends."),
("vcs_info", "The main function, that runs all backends and assembles all data into\n`${vcs_info_msg_*_}`. This is the function you want to call from\n`precmd` if you want to include up-to-date information in your prompt (see\nifzman(**Variable Description**)ifnzman((vcs_info Variables))\nbelow). If an argument is given, that string will be\nused instead of `default` in the _user-context_ field of the style\ncontext."),
("vcs_info_hookadd", "Statically registers a number of functions to a given hook. The hook needs\nto be given as the first argument; what follows is a list of hook-function\nnames to register to the hook. The \"+vi-\" prefix needs to be left out\nhere. See ifzman(**Hooks in vcs_info**)ifnzman((vcs_info Hooks))\nbelow for details."),
("vcs_info_hookdel", "Remove hook-functions from a given hook. The hook needs to be given as the\nfirst non-option argument; what follows is a list of hook-function\nnames to un-register from the hook. If \"-a\" is used as the first\nargument, `all` occurrences of the functions are unregistered. Otherwise\nonly the last occurrence is removed (if a function was registered to a hook\nmore than once). The \"+vi-\" prefix needs to be left out here.\nSee ifzman(**Hooks in vcs_info**)ifnzman((vcs_info Hooks))\nbelow for details."),
("vcs_info_lastmsg", "Outputs the current values of `${vcs_info_msg_*_}`.\nTakes into account the value of the `use-prompt-escapes` style in\n`':vcs_info:formats:command:-all-'`. It also only prints `max-exports`\nvalues."),
("vcs_info_printsys", "Prints a list of all\nsupported version control systems. Useful to find out possible contexts\n(and which of them are enabled) or values for the `disable` style."),
("vcs_info_setsys", "Initializes `vcs_info`'s internal list of\navailable backends. With this function, you can add support for new VCSs\nwithout restarting the shell."),
("ret", "The return value that the hooks system will return to the caller. The\ndefault is an integer \"zero\". If and how a changed `ret` value changes\nthe execution of the caller depends on the specific hook. See the hook\ndocumentation below for details."),
("hook_com", "An associated array which is used for bidirectional communication from\nthe caller to hook functions. The used keys depend on the specific hook."),
("context", "The active context of the hook. Functions that wish to change this\nvariable should make it local scope first."),
("vcs", "The current VCS after it was detected. The same values as in the\nenable/disable style are used. Available in all hooks except `start-up`."),
("start", "Called after starting `vcs_info` but before the VCS in this directory is\ndetermined. It can be used to deactivate `vcs_info` temporarily if\nnecessary. When `ret` is set to `1`, `vcs_info` aborts and does\nnothing; when set to `2`, `vcs_info` sets up everything as if no\nversion control were active and exits."),
("pre", "Same as `start-up` but after the VCS was detected."),
("gen", "Called in the Mercurial backend when a bookmark string is generated; the\n`get-revision` and `get-bookmarks` styles must be true.\n\nThis hook gets the names of the Mercurial bookmarks that\n`vcs_info` collected from \"hg\".\n\nIf a bookmark is active, the key `${hook_com[hg-active-bookmark]}` is\nset to its name. The key is otherwise unset.\n\nWhen setting `ret` to non-zero, the string in\n`${hook_com[hg-bookmark-string]}` will be used in the `%m` escape in\n`formats` and `actionformats` and will be available in the global\n`backend_misc` array as `${backend_misc[bookmarks]}`."),
("gen", "Called in the `git` (with `stgit` or during rebase or merge), and `hg`\n(with `mq`) backends and in `quilt` support when the `applied-string`\nis generated; the `use-quilt` zstyle must be true for `quilt` (the `mq`\nand `stgit` backends are active by default).\n\nThe arguments to this hook describe applied patches\nin the opposite order, which means that the first argument is the\ntop-most patch and so forth.\n\nWhen the patches' log messages can be extracted, those are embedded\nwithin each argument after a space, so each argument is of the form\n\"_patch-name_ _first line of the log message_\", where _patch-name_\ncontains no whitespace. The `mq` backend passes arguments of\nthe form \"_patch name_\", with possible embedded spaces, but without\nextracting the patch's log message.\n\nWhen setting `ret` to non-zero, the string in\n`${hook_com[applied-string]}` will be\navailable as `%p` in the `patch-format` and `nopatch-format` styles.\nThis hook is, in concert with `set-patch-format`, responsible for\n`%`-escaping that value for use in the prompt.\n(See ifzman(the **Oddities** subsection above)\\\nifnzman((vcs_info Oddities)).)\n\nCOMMENT(This paragraph is repeated above/below)\\\nThe `quilt` backend passes to this hook the inputs\n`${hook_com[quilt-patches-dir]}` and, if it has been\ndetermined, `${hook_com[quilt-pc-dir]}`."),
("gen", "Called in the `git` (with `stgit` or during rebase), and `hg` (with\n`mq`) backend and in `quilt` support when the `unapplied-string` is\ngenerated; the `get-unapplied` style must be true.\n\nThis hook gets the names of all unapplied patches which `vcs_info`\nin order, which means that the first argument is\nthe patch next-in-line to be applied and so forth.\n\nThe format of each argument is as for `gen-applied-string`, above.\n\nWhen setting `ret` to non-zero, the string in\n`${hook_com[unapplied-string]}` will be available as `%u` in the\n`patch-format` and `nopatch-format` styles.\nThis hook is, in concert with `set-patch-format`, responsible for\n`%`-escaping that value for use in the prompt.\n(See ifzman(the **Oddities** subsection above)\\\nifnzman((vcs_info Oddities)).)\n\nCOMMENT(This paragraph is repeated above/below)\\\nThe `quilt` backend passes to this hook the inputs\n`${hook_com[quilt-patches-dir]}` and, if it has been\ndetermined, `${hook_com[quilt-pc-dir]}`."),
("gen", "Called in the `hg` backend when `guards-string` is generated; the\n`get-mq` style must be true (default).\n\nThis hook gets the names of any active `mq` guards.\n\nWhen setting `ret` to non-zero, the string in\n`${hook_com[guards-string]}` will be used in the `%g` escape in the\n`patch-format` and `nopatch-format` styles."),
("no", "This hooks is called when no version control system was detected.\n\nThe \"hook_com\" parameter is not used."),
("post", "Called as soon as the backend has finished collecting information.\n\nThe \"hook_com\" keys available are as for the `set-message` hook."),
("post", "Called after the `quilt` support is done. The following information\nis passed as arguments to the hook: 1. the quilt-support mode (\"addon\" or\n\"standalone\"); 2. the directory that contains the patch series; 3. the\ndirectory that holds quilt's status information (the \".pc\" directory) or\nthe string `\"-nopc-\"\" if that directory wasn\"t found.\n\nThe \"hook_com\" parameter is not used."),
("set", "Called before \"branchformat\" is set. The only argument to the\nhook is the format that is configured at this point.\n\nThe \"hook_com\" keys considered are \"branch\" and \"revision\".\nThey are set to the values figured out so far by `vcs_info` and any\nchange will be used directly when the actual replacement is done.\n\nIf `ret` is set to non-zero, the string in\n`${hook_com[branch-replace]}` will be used unchanged as the\n\"%b\" replacement in the variables set by `vcs_info`."),
("set", "Called before a \"hgrevformat\" is set. The only argument to the\nhook is the format that is configured at this point.\n\nThe \"hook_com\" keys considered are \"hash\" and \"localrev\".\nThey are set to the values figured out so far by `vcs_info` and any\nchange will be used directly when the actual replacement is done.\n\nIf `ret` is set to non-zero, the string in\n`${hook_com[rev-replace]}` will be used unchanged as the\n\"%i\" replacement in the variables set by `vcs_info`."),
("pre", "This hook is used when `vcs_info`'s quilt functionality is active in \"addon\"\nmode (quilt used on top of a real version control system). It is activated\nright before any quilt specific action is taken.\n\nSetting the \"ret\" variable in this hook to a non-zero value avoids any\nquilt specific actions from being run at all."),
("set", "This hook is used to control some of the possible expansions in\n`patch-format` and `nopatch-format` styles with patch queue systems such as\nquilt, mqueue and the like.\n\nThis hook is used in the `git`, `hg` and `quilt` backends.\n\nThe hook allows the control of the `%p` (`${hook_com[applied]}`) and `%u`\n(`${hook_com[unapplied]}`) expansion in all backends that use the hook. With\nthe mercurial backend, the `%g` (`${hook_com[guards]}`) expansion is\ncontrollable in addition to that.\n\nIf `ret` is set to non-zero, the string in `${hook_com[patch-replace]}`\nwill be used unchanged instead of an expanded format from `patch-format` or\n`nopatch-format`.\n\nThis hook is, in concert with the `gen-applied-string` or\n`gen-unapplied-string` hooks if they are defined, responsible for\n`%`-escaping the final `patch-format` value for use in the prompt.\n(See ifzman(the **Oddities** subsection above)\\\nifnzman((vcs_info Oddities)).)\n\nCOMMENT(This paragraph is repeated above/below)\\\nThe `quilt` backend passes to this hook the inputs\n`${hook_com[quilt-patches-dir]}` and, if it has been\ndetermined, `${hook_com[quilt-pc-dir]}`."),
("set", "Called each time before a ``vcs_info_msg_`_N_`_`' message is set.\nIt takes two arguments; the first being the \"_N_\" in the message\nvariable name, the second is the currently configured `formats` or\n`actionformats`.\n\nThere are a number of \"hook_com\" keys, that are used here:\n\"action\", \"branch\", \"base\", \"base-name\", \"subdir\",\n\"staged\", \"unstaged\", \"revision\", \"misc\", \"vcs\"\nand one \"miscN\" entry for each backend-specific data field (`N`\nstarting at zero). They are set to the values figured out so far by\n`vcs_info` and any change will be used directly when the actual\nreplacement is done.\n\nSince this hook is triggered multiple times (once for each configured\n`formats` or `actionformats`), each of the \"hook_com\" keys mentioned\nabove (except for the `miscN` entries) has an \"_orig\" counterpart,\nso even if you changed a value to your liking you can still get the\noriginal value in the next run. Changing the \"_orig\" values is\nprobably not a good idea.\n\nIf `ret` is set to non-zero, the string in\n`${hook_com[message]}` will be used unchanged as the message by\n`vcs_info`."),
("prompt", "Set or examine the prompt theme. With no options and a _theme_\nargument, the theme with that name is set as the current theme. The\navailable themes are determined at run time; use the `-l` option to see\na list. The special _theme_ \"random\" selects at random one of the\navailable themes and sets your prompt to that.\n\nIn some cases the _theme_ may be modified by one or more arguments,\nwhich should be given after the theme name. See the help for each theme\nfor descriptions of these arguments.\n\nOptions are:\n\n- `-c` â Show the currently selected theme and its parameters, if any.\n- `-l` â List all available prompt themes.\n- `-p` â Preview the theme named by _theme_, or all themes if no\n_theme_ is given.\n- `-h` â Show help for the theme named by _theme_, or for the\n`prompt` function if no _theme_ is given.\n- `-s` â Set _theme_ as the current theme and save state."),
("prompt_", "Each available _theme_ has a setup function which is called by the\n`prompt` function to install that theme. This function may define\nother functions as necessary to maintain the prompt, including functions\nused to preview the prompt or provide help for its use. You should not\nnormally call a theme's setup function directly."),
("prompt", "The theme \"off\" sets all the prompt variables to minimal values with\nno special effects."),
("prompt", "The theme \"default\" sets all prompt variables to the same state as\nif an interactive zsh was started with no initialization files."),
("prompt", "The special theme \"restore\" erases all theme settings and sets prompt\nvariables to their state before the first time the \"prompt\" function\nwas run, provided each theme has properly defined its cleanup (see below).\n\nNote that you can undo \"prompt off\" and \"prompt default\" with\n\"prompt restore\", but a second restore does not undo the first."),
("select", "The first eight \"-match\" functions are drop-in replacements for the\nbuiltin widgets without the suffix. By default they behave in a similar\nway. However, by the use of styles and the function `select-word-style`,\nthe way words are matched can be altered. `select-word-match` is intended\nto be used as a text object in vi mode but with custom word styles. For\ncomparison, the widgets described in subref(Text Objects)(zshzle)\nuse fixed definitions of words, compatible\nwith the `vim` editor.\n\nThe simplest way of configuring the functions is to use\n`select-word-style`, which can either be called as a normal function with\nthe appropriate argument, or invoked as a user-defined widget that will\nprompt for the first character of the word style to be used. The first\ntime it is invoked, the first eight `-match` functions will automatically\nreplace the builtin versions, so they do not need to be loaded explicitly.\n\nThe word styles available are as follows. Only the first character\nis examined.\n\n- **`bash`** âÂÂ\nWord characters are alphanumeric characters only.\n\n- **`normal`** âÂÂ\nAs in normal shell operation: word characters are alphanumeric characters\nplus any characters present in the string given by the parameter\n`$WORDCHARS`.\n\n- **`shell`** âÂÂ\nWords are complete shell command arguments, possibly including complete\nquoted strings, or any tokens special to the shell.\n\n- **`whitespace`** âÂÂ\nWords are any set of characters delimited by whitespace.\n\n- **`default`** âÂÂ\nRestore the default settings; this is usually the same as \"normal\".\n\nAll but \"default\" can be input as an upper case character, which has\nthe same effect but with subword matching turned on. In this case, words\nwith upper case characters are treated specially: each separate run of\nupper case characters, or an upper case character followed by any number of\nother characters, is considered a word. The style `subword-range`\ncan supply an alternative character range to the default \"[:upper:]\";\nthe value of the style is treated as the contents of a ``[`_..._`]`'\npattern (note that the outer brackets should not be supplied, only\nthose surrounding named ranges).\n\nMore control can be obtained using the `zstyle` command, as described in\n_The zsh/zutil Module_ (zshmodules). Each style is looked up in the\ncontext `:zle:`_widget_ where _widget_ is the name of the\nuser-defined widget, not the name of the function implementing it, so in\nthe case of the definitions supplied by `select-word-style` the\nappropriate contexts are `:zle:forward-word`, and so on. The function\n`select-word-style` itself always defines styles for the context\n\":zle:*\" which can be overridden by more specific (longer) patterns as\nwell as explicit contexts.\n\nThe style `word-style` specifies the rules to use. This may have the\nfollowing values.\n\n- **`normal`** âÂÂ\nUse the standard shell rules, i.e. alphanumerics and `$WORDCHARS`, unless\noverridden by the styles `word-chars` or `word-class`.\n\n- **`specified`** âÂÂ\nSimilar to `normal`, but _only_ the specified characters, and not also\nalphanumerics, are considered word characters.\n\n- **`unspecified`** âÂÂ\nThe negation of specified. The given characters are those which will\n_not_ be considered part of a word.\n\n\n- **`shell`** â Words are obtained by using the syntactic rules for generating shell\ncommand arguments. In addition, special tokens which are never command\narguments such as \"tt(())\" are also treated as words.\n\n\n- **`whitespace`** âÂÂ\nWords are whitespace-delimited strings of characters.\n\nThe first three of those rules usually use `$WORDCHARS`, but the value\nin the parameter can be overridden by the style `word-chars`, which works\nin exactly the same way as `$WORDCHARS`. In addition, the style\n`word-class` uses character class syntax to group characters and takes\nprecedence over `word-chars` if both are set. The `word-class` style\ndoes not include the surrounding brackets of the character class; for\nexample, \"-:[:alnum:]\" is a valid `word-class` to include all\nalphanumerics plus the characters \"-\" and \":\". Be careful\nincluding \"]\", \"^\" and \"-\" as these are special inside\ncharacter classes.\n\n`word-style` may also have \"-subword\" appended to its value to\nturn on subword matching, as described above.\n\nThe style `skip-chars` is mostly useful for\n`transpose-words` and similar functions. If set, it gives a count of\ncharacters starting at the cursor position which will not be considered\npart of the word and are treated as space, regardless of what they actually\nare. For example, if\n\n zstyle ':zle:transpose-words' skip-chars 1\n\nhas been set, and `transpose-words-match` is called with the cursor on\nthe _X_ of `foo`_X_`bar`, where _X_ can be any character, then\nthe resulting expression is `bar`_X_`foo`.\n\nFiner grained control can be obtained by setting the style `word-context`\nto an array of pairs of entries. Each pair of entries consists of a\n_pattern_ and a _subcontext_. The shell argument the cursor is on is\nmatched against each _pattern_ in turn until one matches; if it does,\nthe context is extended by a colon and the corresponding _subcontext_.\nNote that the test is made against the original word on the line, with no\nstripping of quotes. Special handling is done between words: the current\ncontext is examined and if it contains the string `between` the word\nis set to a single space; else if it is contains the string `back`,\nthe word before the cursor is considered, else the word after cursor is\nconsidered. Some examples are given below.\n\nThe style `skip-whitespace-first` is only used with the\n`forward-word` widget. If it is set to true, then `forward-word`\nskips any non-word-characters, followed by any non-word-characters:\nthis is similar to the behaviour of other word-orientated widgets,\nand also that used by other editors, however it differs from the\nstandard zsh behaviour. When using `select-word-style` the widget\nis set in the context `:zle:*` to `true` if the word style is\n`bash` and `false` otherwise. It may be overridden by setting it in\nthe more specific context `:zle:forward-word*`.\n\nIt is possible to create widgets with specific behaviour by defining\na new widget implemented by the appropriate generic function, then\nsetting a style for the context of the specific widget. For example,\nthe following defines a widget `backward-kill-space-word` using\n`backward-kill-word-match`, the generic widget implementing\n`backward-kill-word` behaviour, and ensures that the new widget\nalways implements space-delimited behaviour.\n\n zle -N backward-kill-space-word backward-kill-word-match\nzstyle :zle:backward-kill-space-word word-style space\n\nThe widget `backward-kill-space-word` can now be bound to a key.\n\nHere are some further examples of use of the styles, actually taken from the\nsimplified interface in `select-word-style`:\n\n zstyle ':zle:*' word-style standard\nzstyle ':zle:*' word-chars ''\n\nImplements bash-style word handling for all widgets, i.e. only\nalphanumerics are word characters; equivalent to setting\nthe parameter `WORDCHARS` empty for the given context.\n\n style ':zle:*kill*' word-style space\n\nUses space-delimited words for widgets with the word \"kill\" in the name.\nNeither of the styles `word-chars` nor `word-class` is used in this case.\n\nHere are some examples of use of the `word-context` style to extend\nthe context.\n\n zstyle ':zle:*' word-context \\\n \"*/*\" filename \"[[:space:]]\" whitespace\nzstyle ':zle:transpose-words:whitespace' word-style shell\nzstyle ':zle:transpose-words:filename' word-style normal\nzstyle ':zle:transpose-words:filename' word-chars ''\n\nThis provides two different ways of using `transpose-words` depending on\nwhether the cursor is on whitespace between words or on a filename, here\nany word containing a `/`. On whitespace, complete arguments as defined\nby standard shell rules will be transposed. In a filename, only\nalphanumerics will be transposed. Elsewhere, words will be transposed\nusing the default style for `:zle:transpose-words`.\n\nThe word matching and all the handling of `zstyle` settings is actually\nimplemented by the function `match-words-by-style`. This can be used to\ncreate new user-defined widgets. The calling function should set the local\nparameter `curcontext` to `:zle:`_widget_, create the local\nparameter `matched_words` and call `match-words-by-style` with no\narguments. On return, `matched_words` will be set to an array with the\nelements: (1) the start of the line (2) the word before the cursor (3) any\nnon-word characters between that word and the cursor (4) any non-word\ncharacter at the cursor position plus any remaining non-word characters\nbefore the next word, including all characters specified by the\n`skip-chars` style, (5) the word at or following the cursor (6) any\nnon-word characters following that word (7) the remainder of the line. Any\nof the elements may be an empty string; the calling function should test\nfor this to decide whether it can perform its function.\n\nIf the variable `matched_words` is defined by the caller to\n`match-words-by-style` as an associative array (`local -A\nmatched_words`), then the seven values given above should be retrieved\nfrom it as elements named `start`, `word-before-cursor`,\n`ws-before-cursor`, `ws-after-cursor`, `word-after-cursor`,\n`ws-after-word`, and `end`. In addition the element\n`is-word-start` is 1 if the cursor is on the start of a word or\nsubword, or on white space before it (the cases can be distinguished by\ntesting the `ws-after-cursor` element) and 0 otherwise. This form is\nrecommended for future compatibility.\n\nIt is possible to pass options with arguments to `match-words-by-style`\nto override the use of styles. The options are:\n\n- `-w` â _word-style_\n- `-s` â _skip-chars_\n- `-c` â _word-class_\n- `-C` â _word-chars_\n- `-r` â _subword-range_\n\nFor example, `match-words-by-style -w shell -c 0` may be used to\nextract the command argument around the cursor.\n\nThe `word-context` style is implemented by the function\n`match-word-context`. This should not usually need to be called\ndirectly."),
("bracketed", "The `bracketed-paste` widget (see subref(Miscellaneous)(zshzle))\ninserts pasted text literally into the editor buffer rather than interpret\nit as keystrokes. This disables some common usages where the self-insert\nwidget is replaced in order to accomplish some extra processing. An\nexample is the contributed `url-quote-magic` widget described below.\n\nThe `bracketed-paste-magic` widget is meant to replace `bracketed-paste`\nwith a wrapper that re-enables these self-insert actions, and other\nactions as selected by zstyles. Therefore this widget is installed with\nifzman()\n\n autoload -Uz bracketed-paste-magic\nzle -N bracketed-paste bracketed-paste-magic\n\nOther than enabling some widget processing, `bracketed-paste-magic`\nattempts to replicate `bracketed-paste` as faithfully as possible.\n\nThe following zstyles may be set to control processing of pasted text.\nAll are looked up in the context \":bracketed-paste-magic\".\n\n\n- **`active-widgets`** â A list of patterns matching widget names that should be activated during\nthe paste. All other key sequences are processed as self-insert-unmeta.\nThe default is \"self-*\" so any user-defined widgets named with that\nprefix are active along with the builtin self-insert.\n\nIf this style is not set (explicitly deleted) or set to an empty value,\nno widgets are active and the pasted text is inserted literally. If the\nvalue includes \"undefined-key\", any unknown sequences are discarded\nfrom the pasted text.\n\n\n- **`inactive-keys`** âÂÂ\nThe inverse of `active-widgets`, a list of key sequences that always use\n`self-insert-unmeta` even when bound to an active widget. Note that\nthis is a list of literal key sequences, not patterns.\n\n\n- **`paste-init`** â A list of function names, called in widget context (but not as widgets).\nThe functions are called in order until one of them returns a non-zero\nstatus. The parameter \"PASTED\" contains the initial state of the\npasted text. All other ZLE parameters such as \"BUFFER\" have their\nnormal values and side-effects, and full history is available, so for\nexample `paste-init` functions may move words from `BUFFER` into\n`PASTED` to make those words visible to the `active-widgets`.\n\nA non-zero return from a `paste-init` function does _not_ prevent the\npaste itself from proceeding.\n\nLoading `bracketed-paste-magic` defines `backward-extend-paste`, a\nhelper function for use in `paste-init`.\n\n zstyle :bracketed-paste-magic paste-init \\\n backward-extend-paste\n\nWhen a paste would insert into the middle of a word or append text to a\nword already on the line, `backward-extend-paste` moves the prefix\nfrom `LBUFFER` into `PASTED` so that the `active-widgets` see the\nfull word so far. This may be useful with `url-quote-magic`.\n\n\n- **`paste-finish`** âÂÂ\nAnother list of function names called in order until one returns non-zero.\nThese functions are called _after_ the pasted text has been processed\nby the `active-widgets`, but _before_ it is inserted into \"BUFFER\".\nZLE parameters have their normal values and side-effects.\n\nA non-zero return from a `paste-finish` function does _not_ prevent\nthe paste itself from proceeding.\n\nLoading `bracketed-paste-magic` also defines `quote-paste`, a helper\nfunction for use in `paste-finish`.\n\n zstyle :bracketed-paste-magic paste-finish \\\n quote-paste\nzstyle :bracketed-paste-magic:finish quote-style \\\n qqq\n\nWhen the pasted text is inserted into `BUFFER`, it is quoted per the\n`quote-style` value. To forcibly turn off the built-in numeric prefix\nquoting of `bracketed-paste`, use:\n\n zstyle :bracketed-paste-magic:finish quote-style \\\n none\n\n_Important:_ During `active-widgets` processing of the paste (after\n`paste-init` and before `paste-finish`), `BUFFER` starts empty and\nhistory is restricted, so cursor motions, etc., may not pass outside of\nthe pasted content. Text assigned to `BUFFER` by the active widgets\nis copied back into `PASTED` before `paste-finish`."),
("bracketed", "This widget is a simpler version of using `bracketed-paste-magic`\nto enable `quote-url-magic`. Rather than re-interpreting everything as\nkeystrokes, it simply handles quoting of pasted urls itself, and all other\ntext is handled like the default bracketed-paste widget.\n\nIt limits the quoting to pastes that consist of a single url, but you\ncan also enable or disable quoting explicitly for a paste by setting\nNUMERIC to 1 or 2 respectively (ie, by pressing alt-1 or alt-2 before\npasting).\n\nIt is also possible to customize the list of schemas used to\ndecide if something is a url by setting the `schema` style in the\n`:bracketed-paste-url-magic` context, for example:\nifzman()\n\n zstyle :bracketed-paste-url-magic schema http:// myspecialschema:\n\nThe default list of schemas is `http:// https:// ftp:// ftps:// file:// \\\n ssh:// sftp:// magnet:`.\n\nThe widget itself is installed in a similar way as\n`bracketed-paste-magic` above, by\nifzman()\n\n autoload -Uz bracketed-paste-url-magic\nzle -N bracketed-paste bracketed-paste-url-magic"),
("copy", "This widget works like a combination of `insert-last-word` and\n`copy-prev-shell-word`. Repeated invocations of the widget retrieve\nearlier words on the relevant history line. With a numeric argument\n_N_, insert the _N_th word from the history line; _N_ may be\nnegative to count from the end of the line.\n\nIf `insert-last-word` has been used to retrieve the last word on a\nprevious history line, repeated invocations will replace that word with\nearlier words from the same line.\n\nOtherwise, the widget applies to words on the line currently being edited.\nThe `widget` style can be set to the name of another widget that should\nbe called to retrieve words. This widget must accept the same three\narguments as `insert-last-word`."),
("cycle", "After inserting an unambiguous string into the command line, the new\nfunction based completion system may know about multiple places in\nthis string where characters are missing or differ from at least one\nof the possible matches. It will then place the cursor on the\nposition it considers to be the most interesting one, i.e. the one\nwhere one can disambiguate between as many matches as possible with as\nlittle typing as possible.\n\nThis widget allows the cursor to be easily moved to the other interesting\nspots. It can be invoked repeatedly to cycle between all positions\nreported by the completion system."),
("delete", "This is another function which works like the `-match` functions\ndescribed immediately above, i.e. using styles to decide the word\nboundaries. However, it is not a replacement for any existing function.\n\nThe basic behaviour is to delete the word around the cursor. There is no\nnumeric argument handling; only the single word around the cursor is\nconsidered. If the widget contains the string `kill`, the removed text\nwill be placed in the cutbuffer for future yanking. This can be obtained\nby defining `kill-whole-word-match` as follows:\n\n zle -N kill-whole-word-match delete-whole-word-match\n\nand then binding the widget `kill-whole-word-match`."),
("up", "These widgets are similar to the builtin functions `up-line-or-search`\nand `down-line-or-search`: if in a multiline buffer they move up or\ndown within the buffer, otherwise they search for a history line matching\nthe start of the current line. In this case, however, they search for\na line which matches the current line up to the current cursor position, in\nthe manner of `history-beginning-search-backward` and `-forward`, rather\nthan the first word on the line."),
("edit", "Edit the command line using your visual editor, as in `ksh`.\n\n bindkey -M vicmd v edit-command-line\n\nThe editor to be used can also be specified using the `editor` style in\nthe context of the widget. It is specified as an array of command and\narguments:\n\n zstyle :zle:edit-command-line editor gvim -f"),
("expand", "Expand the file name under the cursor to an absolute path, resolving\nsymbolic links. Where possible, the initial path segment is turned\ninto a named directory or reference to a user's home directory."),
("history", "This function implements the widgets\n`history-beginning-search-backward-end` and\n`history-beginning-search-forward-end`. These commands work by first\ncalling the corresponding builtin widget (see\n_History Control_ (zshzle))\nand then moving the cursor to the end of the line. The original cursor\nposition is remembered and restored before calling the builtin widget a\nsecond time, so that the same search is repeated to look farther through\nthe history.\n\nAlthough you `autoload` only one function, the commands to use it are\nslightly different because it implements two widgets.\n\n zle -N history-beginning-search-backward-end \\\n history-search-end\nzle -N history-beginning-search-forward-end \\\n history-search-end\nbindkey '\\e^P' history-beginning-search-backward-end\nbindkey '\\e^N' history-beginning-search-forward-end"),
("history", "This function implements yet another form of history searching. The\ntext before the cursor is used to select lines from the history,\nas for `history-beginning-search-backward` except that all matches are\nshown in a numbered menu. Typing the appropriate digits inserts the\nfull history line. Note that leading zeroes must be typed (they are only\nshown when necessary for removing ambiguity). The entire history is\nsearched; there is no distinction between forwards and backwards.\n\nWith a numeric argument, the search is not anchored to the start of\nthe line; the string typed by the use may appear anywhere in the line\nin the history.\n\nIf the widget name contains \"-end\" the cursor is moved to the end of\nthe line inserted. If the widget name contains \"-space\" any space\nin the text typed is treated as a wildcard and can match anything (hence\na leading space is equivalent to giving a numeric argument). Both\nforms can be combined, for example:\n\n zle -N history-beginning-search-menu-space-end \\\n history-beginning-search-menu"),
("history", "The function `history-pattern-search` implements widgets which prompt\nfor a pattern with which to search the history backwards or forwards. The\npattern is in the usual zsh format, however the first character may be\n`^` to anchor the search to the start of the line, and the last character\nmay be `$` to anchor the search to the end of the line. If the\nsearch was not anchored to the end of the line the cursor is positioned\njust after the pattern found.\n\nThe commands to create bindable widgets are similar to those in the\nexample immediately above:\n\n autoload -U history-pattern-search\nzle -N history-pattern-search-backward history-pattern-search\nzle -N history-pattern-search-forward history-pattern-search"),
("incarg", "This widget allows you to increment integers on the current line. In addition\nto decimals, it can handle hexadecimals prefixed with `0x`, binaries with\n`0b`, and octals with `0o`.\n\nBy default, the target integer will be incremented by one. With a numeric\nargument, the integer is incremented by the amount of the argument. The shell\nparameter `incarg` may be set to change the default increment to something\nother than one.\n\nThe behavior of this widget changes depending on the widget name.\n\nWhen the widget is named `incarg`, the widget will increment an integer\nplaced under the cursor placed or just to the left of it. `decarg`, on the\nother hand, decrements the integer. When the name is prefixed with `vi`,\nthe cursor will jump to the nearest integer after the cursor before incrementing\nit. The `vi` prefix can also be combined with a `backward-` prefix to make\nthe widget search backwards for numbers.\n\nThere's also a `sync-` prefix that can be added to the widget name. This\nvariant is used for creating a sequence of numbers on split terminals with\nsynchronized key input. The first pane won't increment the integer at all, but\neach pane after that will have the integer incremented once more than the\nprevious pane. It currently supports tmux and iTerm2.\n\nThe prefixes `vi`, `backward-`, and `sync-` can be combined, for example,\ninto `vim-sync-` or `vim-backward-sync-`. The `vi` prefix needs to be\nat the very beginning.\n\n bindkey '^X+' incarg"),
("incremental", "This allows incremental completion of a word. After starting this\ncommand, a list of completion choices can be shown after every character\nyou type, which you can delete with `^H` or `DEL`. Pressing return\naccepts the completion so far and returns you to normal editing (that is,\nthe command line is _not_ immediately executed). You can hit `TAB` to\ndo normal completion, `^G` to abort back to the state when you started,\nand `^D` to list the matches.\n\nThis works only with the new function based completion system.\n\n bindkey '^Xi' incremental-complete-word"),
("insert", "This function allows you to compose characters that don't appear on the\nkeyboard to be inserted into the command line. The command is followed by\ntwo keys corresponding to ASCII characters (there is no prompt). For\naccented characters, the two keys are a base character followed by a code\nfor the accent, while for other special characters the two characters\ntogether form a mnemonic for the character to be inserted. The\ntwo-character codes are a subset of those given by RFC 1345 (see for\nexample uref(http://www.faqs.org/rfcs/rfc1345.html)).\n\nThe function may optionally be followed by up to two characters which\nreplace one or both of the characters read from the keyboard; if both\ncharacters are supplied, no input is read. For example,\n`insert-composed-char a:` can be used within a widget to insert an a with\numlaut into the command line. This has the advantages over use of a\nliteral character that it is more portable.\n\nFor best results zsh should have been built with support for multibyte\ncharacters (configured with `--enable-multibyte`); however, the function\nworks for the limited range of characters available in single-byte\ncharacter sets such as ISO-8859-1.\n\nThe character is converted into the local representation and\ninserted into the command line at the cursor position.\n(The conversion is done within the shell, using whatever facilities\nthe C library provides.) With a numeric argument, the character and its\ncode are previewed in the status line\n\nThe function may be run outside zle in which case it prints the character\n(together with a newline) to standard output. Input is still read from\nkeystrokes.\n\nSee `insert-unicode-char` for an alternative way of inserting Unicode\ncharacters using their hexadecimal character number.\n\nThe set of accented characters is reasonably complete up to Unicode\ncharacter U+0180, the set of special characters less so. However, it\nis very sporadic from that point. Adding new characters is easy,\nhowever; see the function `define-composed-chars`. Please send any\nadditions to `zsh-workers@zsh.org`.\n\nThe codes for the second character when used to accent the first are as\nfollows. Note that not every character can take every accent.\n\n- `!` â Grave.\n\n- **`'`** â Acute.\n\n- `>` â Circumflex.\n\n- **`?`** â Tilde. (This is not `~` as RFC 1345 does not assume that\ncharacter is present on the keyboard.)\n\n\n- **`-`** â Macron. (A horizontal bar over the base character.)\n\n\n- **`(`** — Breve. (A shallow dish shape over the base character.)\n\n- `.` â Dot above the base character, or in the case of `i` no dot,\nor in the case of `L` and `l` a centered dot.\n\n- **`:`** â Diaeresis (Umlaut).\n\n- `c` â Cedilla.\n- `_` â Underline, however there are currently no underlined characters.\n- `/` â Stroke through the base character.\n\n- **`\"`** â Double acute (only supported on a few letters).\n\n\n- **`;`** â Ogonek. (A little forward facing hook at the bottom right\nof the character.)\n\n\n- **`<`** â Caron. (A little v over the letter.)\n\n- `0` â Circle over the base character.\n- `2` â Hook over the base character.\n- `9` â Horn over the base character.\n\nThe most common characters from the Arabic, Cyrillic, Greek and Hebrew\nalphabets are available; consult RFC 1345 for the appropriate sequences.\nIn addition, a set of two letter codes not in RFC 1345 are available for\nthe double-width characters corresponding to ASCII characters from `!`\nto `~` (0x21 to 0x7e) by preceding the character with `^`, for\nexample `^A` for a double-width `A`.\n\nThe following other two-character sequences are understood.\n\n\n- **ASCII characters** â These are already present on most keyboards:\n\n\n- **`<()`(Left square bracket)\n\n- **`//`** — Backslash (solidus)\n\n\n- **``>**\n** â Right square bracket\n\n\n- **`(!)`(Left brace (curly bracket))\n\n- **`!!`** — Vertical bar (pipe symbol)\n\n\n- **`!`**\n** â Right brace (curly bracket)\n\n\n- **`'?`** â Tilde\n\n\n- **Special letters** â Characters found in various variants of the Latin alphabet:\n\n\n- **`ss`** â Eszett (scharfes S)\n\n- `D-`, `d-` â Eth\n- `TH`, `th` â Thorn\n- `kk` â Kra\n\n- **`'n`** â RQUOTE()n\n\n- `NG`, `ng` â Ng\n- `OI`, `oi` â Oi\n- `yr` â yr\n- `ED` â ezh\n\n\n- **Currency symbols** â - `Ct` â Cent\n\n- **`Pd`** â Pound sterling (also lira and others)\n\n- `Cu` â Currency\n- `Ye` â Yen\n\n- **`Eu`** â Euro (N.B. not in RFC 1345)\n\n\n- **Punctuation characters** â References to \"right\" quotes indicate the shape (like a 9 rather than 6)\nrather than their grammatical use. (For example, a \"right\" low double\nquote is used to open quotations in German.)\n\n- `!I` â Inverted exclamation mark\n- `BB` â Broken vertical bar\n- `SE` â Section\n- `Co` â Copyright\n- `-a` â Spanish feminine ordinal indicator\n- `<<` â Left guillemet\n- `-``-` â Soft hyphen\n- `Rg` â Registered trade mark\n\n- **`PI`** â Pilcrow (paragraph)\n\n- `-o` â Spanish masculine ordinal indicator\n- `>>` â Right guillemet\n- `?I` â Inverted question mark\n- `-1` â Hyphen\n- `-N` â En dash\n- `-M` â Em dash\n- `-3` â Horizontal bar\n- `:3` â Vertical ellipsis\n- `.3` â Horizontal midline ellipsis\n- `!2` â Double vertical line\n- `=2` â Double low line\n\n- **`'6`** â Left single quote\n\n\n- **`9)** â Right single quote\n\n- `.9` â \"Right\" low quote\n\n- **tt(9+`** â Reversed \"right\" quote\n\n- `\"6` â Left double quote\n- `\"9` â Right double quote\n- `:9` â \"Right\" low double quote\n- `9\"` â Reversed \"right\" double quote\n- `/-` â Dagger\n- `/=` â Double dagger\n\n\n- **Mathematical symbols** â - `DG` â Degree\n- `-2`, `+-`, `-+` â - sign, +/- sign, -/+ sign\n- `2S` â Superscript 2\n- `3S` â Superscript 3\n- `1S` â Superscript 1\n- `My` â Micro\n- `.M` â Middle dot\n- `14` â Quarter\n- `12` â Half\n- `34` â Three quarters\n- `*X` â Multiplication\n- `-:` â Division\n- `%0` â Per mille\n- `FA`, `TE`, `/0` â For all, there exists, empty set\n\n\n- **`dP`, `DE`, `NB`** â Partial derivative, delta (increment), del\n(nabla)\n\n\n- **`(-), `-``** â Element of, contains\n\n- `*P`, `+Z` â Product, sum\n- `*-`, `Ob`, `Sb` â Asterisk, ring, bullet\n\n- **`RT`, `0+(), `00``(Root sign, proportional to, infinity)**\n\n- **Other symbols** â - `cS`, `cH`, `cD`, `cC` â Card suits: spades, hearts, diamonds,\nclubs\n\n- **`Md`, `M8`, `M2`, `Mb`, `Mx`, `MX`** â Musical notation:\ncrotchet (quarter note), quaver (eighth note), semiquavers (sixteenth\nnotes), flag sign, natural sign, sharp sign\n\n- `Fm`, `Ml` â Female, male\n\n\n- **Accents on their own** â - **`'>`** â Circumflex (same as caret, `^`)\n\n\n- **`'!`** â Grave (same as backtick, ```)\n\n\n- **`',`** â Cedilla\n\n\n- **`':`** â Diaeresis (Umlaut)\n\n\n- **`'m`** â Macron\n\n\n- **``** â Acute\n"),
("insert", "This function allows you type a file pattern, and see the results of the\nexpansion at each step. When you hit return, all expansions are inserted\ninto the command line.\n\n bindkey '^Xf' insert-files"),
("insert", "When first executed, the user inputs a set of hexadecimal digits.\nThis is terminated with another call to `insert-unicode-char`.\nThe digits are then turned into the corresponding Unicode character.\nFor example, if the widget is bound to `^XU`, the character sequence\n\"^XU 4 c ^XU\" inserts `L` (Unicode U+004c).\n\nSee `insert-composed-char` for a way of inserting characters\nusing a two-character mnemonic."),
("narrow", "Narrow the editable portion of the buffer to the region between the cursor\nand the mark, which may be in either order. The region may not be empty.\n\n`narrow-to-region` may be used as a widget or called as a function from a\nuser-defined widget; by default, the text outside the editable area remains\nvisible. A `recursive-edit` is performed and the original widening\nstatus is then restored. Various options and arguments are available when\nit is called as a function.\n\nThe options `-p` _pretext_ and `-P` _posttext_ may be\nused to replace the text before and after the display for the duration of\nthe function; either or both may be an empty string.\n\nIf the option `-n` is also given, _pretext_ or _posttext_ will only\nbe inserted if there is text before or after the region respectively which\nwill be made invisible.\n\nTwo numeric arguments may be given which will be used instead of the cursor\nand mark positions.\n\nThe option `-S` _statepm_ is used to narrow according to the other\noptions while saving the original state in the parameter with name\n_statepm_, while the option `-R` _statepm_ is used to restore the\nstate from the parameter; note in both cases the _name_ of the parameter\nis required. In the second case, other options and arguments are\nirrelevant. When this method is used, no `recursive-edit` is performed;\nthe calling widget should call this function with the option `-S`,\nperform its own editing on the command line or pass control to the user\nvia \"zle recursive-edit\", then call this function with the option\n`-R`. The argument _statepm_ must be a suitable name for an ordinary\nparameter, except that parameters beginning with the prefix `_ntr_` are\nreserved for use within `narrow-to-region`. Typically the parameter will\nbe local to the calling function.\n\nThe options `-l` _lbufvar_ and `-r` _rbufvar_ may be used to\nspecify parameters where the widget will store the resulting text from\nthe operation. The parameter _lbufvar_ will contain `LBUFFER`\nand _rbufvar_ will contain `RBUFFER`. Neither of these two options\nmay be used with `-S` or `-R`.\n\n`narrow-to-region-invisible` is a simple widget which calls\n`narrow-to-region` with arguments which replace any text outside the\nregion with \"...\". It does not take any arguments.\n\nThe display is restored (and the widget returns) upon any zle command\nwhich would usually cause the line to be accepted or aborted. Hence an\nadditional such command is required to accept or abort the current line.\n\nThe return status of both widgets is zero if the line was accepted, else\nnon-zero.\n\nHere is a trivial example of a widget using this feature.\n\n local state\nnarrow-to-region -p $'Editing restricted region\\n' \\\n -P '' -S state\nzle recursive-edit\nnarrow-to-region -R state"),
("predict", "This set of functions implements predictive typing using history search.\nAfter `predict-on`, typing characters causes the editor to look backward\nin the history for the first line beginning with what you have typed so\nfar. After `predict-off`, editing returns to normal for the line found.\nIn fact, you often don't even need to use `predict-off`, because if the\nline doesn't match something in the history, adding a key performs\nstandard completion, and then inserts itself if no completions were found.\nHowever, editing in the middle of a line is liable to confuse prediction;\nsee the `toggle` style below.\n\nWith the function based completion system (which is needed for this), you\nshould be able to type `TAB` at almost any point to advance the cursor\nto the next \"interesting\" character position (usually the end of the\ncurrent word, but sometimes somewhere in the middle of the word). And of\ncourse as soon as the entire line is what you want, you can accept with\nreturn, without needing to move the cursor to the end first.\n\nThe first time `predict-on` is used, it creates several additional\nwidget functions:\n\n- `delete-backward-and-predict` â Replaces the `backward-delete-char`\nwidget. You do not need to bind this yourself.\n- `insert-and-predict` â Implements predictive typing by replacing the\n`self-insert` widget. You do not need to bind this yourself.\n- `predict-off` â Turns off predictive typing.\n\nAlthough you `autoload` only the `predict-on` function, it is\nnecessary to create a keybinding for `predict-off` as well.\n\n zle -N predict-on\nzle -N predict-off\nbindkey '^X^Z' predict-on\nbindkey '^Z' predict-off"),
("read", "This is most useful when called as a function from inside a widget, but will\nwork correctly as a widget in its own right. It prompts for a value\nbelow the current command line; a value may be input using all of the\nstandard zle operations (and not merely the restricted set available\nwhen executing, for example, `execute-named-cmd`). The value is then\nreturned to the calling function in the parameter `$REPLY` and the\nediting buffer restored to its previous state. If the read was aborted\nby a keyboard break (typically `^G`), the function returns status 1\nand `$REPLY` is not set.\n\nIf one argument is supplied to the function it is taken as a prompt,\notherwise \"? \" is used. If two arguments are supplied, they are the\nprompt and the initial value of `$LBUFFER`, and if a third argument is\ngiven it is the initial value of `$RBUFFER`. This provides a default\nvalue and starting cursor placement. Upon return the entire buffer is the\nvalue of `$REPLY`.\n\nOne option is available: ``-k\" _num_\" specifies that _num_\ncharacters are to be read instead of a whole line. The line editor is not\ninvoked recursively in this case, so depending on the terminal settings\nthe input may not be visible, and only the input keys are placed in\n`$REPLY`, not the entire buffer. Note that unlike the `read` builtin\n_num_ must be given; there is no default.\n\nThe name is a slight misnomer, as in fact the shell's own minibuffer is\nnot used. Hence it is still possible to call `executed-named-cmd` and\nsimilar functions while reading a value."),
("replace", "The function `replace-string` implements three widgets.\nIf defined under the same name as the function, it prompts for two\nstrings; the first (source) string will be replaced by the second\neverywhere it occurs in the line editing buffer.\n\nIf the widget name contains the word \"pattern\", for example by\ndefining the widget using the command ``zle -N replace-pattern\nreplace-string`', then the matching is performed using zsh patterns. All\nzsh extended globbing patterns can be used in the source string; note\nthat unlike filename generation the pattern does not need to match an\nentire word, nor do glob qualifiers have any effect. In addition, the\nreplacement string can contain parameter or command substitutions.\nFurthermore, a \"&\" in the replacement string will be replaced with\nthe matched source string, and a backquoted digit ``\\\"_N_\" will be\nreplaced by the _N_th parenthesised expression matched. The form\n``\\{`_N_`}`' may be used to protect the digit from following\ndigits.\n\nIf the widget instead contains the word \"regex\" (or \"regexp\"),\nthen the matching is performed using regular expressions, respecting\nthe setting of the option `RE_MATCH_PCRE` (see the description of the\nfunction `regexp-replace` below). The special replacement facilities\ndescribed above for pattern matching are available.\n\nBy default the previous source or replacement string will not be offered\nfor editing. However, this feature can be activated by setting the style\n`edit-previous` in the context `:zle:`_widget_ (for example,\n`:zle:replace-string`) to `true`. In addition, a positive\nnumeric argument forces the previous values to be offered, a negative or\nzero argument forces them not to be.\n\nThe function `replace-string-again` can be used to repeat the previous\nreplacement; no prompting is done. As with `replace-string`, if the name\nof the widget contains the word \"pattern\" or \"regex\", pattern or\nregular expression matching is performed, else a literal string\nreplacement. Note that the previous source and replacement text are the\nsame whether pattern, regular expression or string matching is used.\n\nIn addition, `replace-string` shows the previous replacement above\nthe prompt, so long as there was one during the current session; if the\nsource string is empty, that replacement will be repeated without\nthe widget prompting for a replacement string.\n\nFor example, starting from the line:\n\n print This line contains fan and fond\n\nand invoking `replace-pattern` with the source string\n\"tt(f+(?+)n)\" and\nthe replacement string \"c\\1r\" produces the not very useful line:\n\n print This line contains car and cord\n\nThe range of the replacement string can be limited by using the\n`narrow-to-region-invisible` widget. One limitation of the current\nversion is that `undo` will cycle through changes to the replacement\nand source strings before undoing the replacement itself."),
("send", "This is similar to read-from-minibuffer in that it may be called as a\nfunction from a widget or as a widget of its own, and interactively reads\ninput from the keyboard. However, the input being typed is concealed and\na string of asterisks (\"*\") is shown instead. The value is saved in\nthe parameter `$INVISIBLE` to which a reference is inserted into the\nediting buffer at the restored cursor position. If the read was aborted\nby a keyboard break (typically `^G`) or another escape from editing such\nas `push-line`, `$INVISIBLE` is set to empty and the original buffer\nis restored unchanged.\n\nIf one argument is supplied to the function it is taken as a prompt,\notherwise \"Non-echoed text: \" is used (as in emacs). If a second and\nthird argument are supplied they are used to begin and end the reference\nto `$INVISIBLE` that is inserted into the buffer. The default is to\nopen with `${`, then `INVISIBLE`, and close with `}`, but many\nother effects are possible."),
("smart", "This function may replace the `insert-last-word` widget, like so:\n\n zle -N insert-last-word smart-insert-last-word\n\nWith a numeric argument, or when passed command line arguments in a call\nfrom another widget, it behaves like `insert-last-word`, except that\nwords in comments are ignored when `INTERACTIVE_COMMENTS` is set.\n\nOtherwise, the rightmost \"interesting\" word from the previous command is\nfound and inserted. The default definition of \"interesting\" is that the\nword contains at least one alphabetic character, slash, or backslash.\nThis definition may be overridden by use of the `match` style. The\ncontext used to look up the style is the widget name, so usually the\ncontext is `:insert-last-word`. However, you can bind this function to\ndifferent widgets to use different patterns:\n\n zle -N insert-last-assignment smart-insert-last-word\nzstyle :insert-last-assignment match '[[:alpha:]][][[:alnum:]]#=*'\nbindkey '\\e=' insert-last-assignment\n\nIf no interesting word is found and the `auto-previous` style is set to\na true value, the search continues upward through the history. When\n`auto-previous` is unset or false (the default), the widget must be\ninvoked repeatedly in order to search earlier history lines."),
("transpose", "Only useful with a multi-line editing buffer; the lines here are\nlines within the current on-screen buffer, not history lines.\nThe effect is similar to the function of the same name in Emacs.\n\nTranspose the current line with the previous line and move the cursor\nto the start of the next line. Repeating this (which can be done by\nproviding a positive numeric argument) has the effect of moving\nthe line above the cursor down by a number of lines.\n\nWith a negative numeric argument, requires two lines above the\ncursor. These two lines are transposed and the cursor moved to the\nstart of the previous line. Using a numeric argument less than -1\nhas the effect of moving the line above the cursor up by minus that\nnumber of lines."),
("url", "This widget replaces the built-in `self-insert` to make it easier to\ntype URLs as command line arguments. As you type, the input character is\nanalyzed and, if it may need quoting, the current word is checked for a\nURI scheme. If one is found and the current word is not already in\nquotes, a backslash is inserted before the input character.\n\nStyles to control quoting behavior:\n\n\n- **`url-metas`** â This style is looked up in the context ``:url-quote-magic:\"_scheme_\"\n(where _scheme_ is that of the current URL, e.g. \"`ftp`\"). The value\nis a string listing the characters to be treated as globbing\nmetacharacters when appearing in a URL using that scheme. The default is\nto quote all zsh extended globbing characters, excluding '`<`' and\n'`>`' but including braces (as in brace expansion). See also\n`url-seps`.\n\n\n- **`url-seps`** âÂÂ\nLike `url-metas`, but lists characters that should be considered command\nseparators, redirections, history references, etc. The default is to\nquote the standard set of shell separators, excluding those that overlap\nwith the extended globbing characters, but including '`<`' and\n'`>`' and the first character of `$histchars`.\n\n\n- **`url-globbers`** â This style is looked up in the context \":url-quote-magic\". The values\nform a list of command names that are expected to do their own globbing\non the URL string. This implies that they are aliased to use the\n\"noglob\" modifier. When the first word on the line matches one of the\nvalues _and_ the URL refers to a local file (see `url-local-schema`),\nonly the `url-seps` characters are quoted; the `url-metas` are left\nalone, allowing them to affect command-line parsing, completion, etc. The\ndefault values are a literal \"noglob\" plus (when the `zsh/parameter`\nmodule is available) any commands aliased to the helper function\n\"urlglobber\" or its alias \"globurl\".\n\n\n- **`url-local-schema`** âÂÂ\nThis style is always looked up in the context \":urlglobber\", even\nthough it is used by both url-quote-magic and urlglobber. The values form\na list of URI schema that should be treated as referring to local files by\ntheir real local path names, as opposed to files which are specified\nrelative to a web-server-defined document root. The defaults are\n\"`ftp`\" and \"`file`\".\n\n- **`url-other-schema`** âÂÂ\nLike `url-local-schema`, but lists all other URI schema upon which\n`urlglobber` and `url-quote-magic` should act. If the URI on the\ncommand line does not have a scheme appearing either in this list or in\n`url-local-schema`, it is not magically quoted. The default values are\n\"`http`\", \"`https`\", and \"`ftp`\". When a scheme appears both here\nand in `url-local-schema`, it is quoted differently depending on whether\nthe command name appears in `url-globbers`.\n\nLoading `url-quote-magic` also defines a helper function \"urlglobber\"\nand aliases \"globurl\" to \"noglob urlglobber\". This function takes\na local URL apart, attempts to pattern-match the local file portion of the\nURL path, and then puts the results back into URL format again."),
("vi", "This function reads a movement command from the keyboard and then\nprompts for an external command. The part of the buffer covered by\nthe movement is piped to the external command and then replaced by\nthe command's output. If the movement command is bound to vi-pipe,\nthe current line is used.\n\nThe function serves as an example for reading a vi movement command\nfrom within a user-defined widget."),
("which", "This function is a drop-in replacement for the builtin widget\n`which-command`. It has enhanced behaviour, in that it correctly\ndetects whether or not the command word needs to be expanded as an\nalias; if so, it continues tracing the command word from the expanded\nalias until it reaches the command that will be executed.\n\nThe style `whence` is available in the context `:zle:$WIDGET`; this\nmay be set to an array to give the command and options that will be used to\ninvestigate the command word found. The default is `whence -c`."),
("zcalc", "This function is useful together with the `zcalc` function described in\n_Mathematical Functions_ (above).\nIt should be bound to a key representing a binary operator such\nas \"+\", \"-\", \"*\" or \"/\". When running in zcalc,\nif the key occurs at the start of the line or immediately following\nan open parenthesis, the text `\"ans \"` is inserted before the\nrepresentation of the key itself. This allows easy use of the\nanswer from the previous calculation in the current line. The\ntext to be inserted before the symbol typed can be modified by setting\nthe variable `ZCALC_AUTO_INSERT_PREFIX`.\n\nHence, for example, typing \"+12\" followed by return adds 12\nto the previous result.\n\nIf zcalc is in RPN mode (`-r` option) the effect of this binding is\nautomatically suppressed as operators alone on a line are meaningful.\n\nWhen not in zcalc, the key simply inserts the symbol itself."),
("split", "This function splits the line currently being edited into shell arguments\nand whitespace. The result is stored in the array `reply`. The array\ncontains all the parts of the line in order, starting with any whitespace\nbefore the first argument, and finishing with any whitespace after the last\nargument. Hence (so long as the option `KSH_ARRAYS` is not set)\nwhitespace is given by odd indices in the array and arguments by\neven indices. Note that no stripping of quotes is done; joining together\nall the elements of `reply` in order is guaranteed to produce the\noriginal line.\n\nThe parameter `REPLY` is set to the index of the word in `reply` which\ncontains the character after the cursor, where the first element has index\n1. The parameter `REPLY2` is set to the index of the character under the\ncursor in that word, where the first character has index 1.\n\nHence `reply`, `REPLY` and `REPLY2` should all be made local to\nthe enclosing function.\n\nSee the function `modify-current-argument`, described below, for\nan example of how to call this function."),
("modify", "This function provides a simple method of allowing user-defined widgets\nto modify the command line argument under the cursor (or immediately to the\nleft of the cursor if the cursor is between arguments).\n\nThe argument can be an expression which when evaluated operates on the shell\nparameter `ARG`, which will have been set to the command line argument\nunder the cursor. The expression should be suitably quoted to prevent\nit being evaluated too early.\n\nAlternatively, if the argument does not contain the string `ARG`, it\nis assumed to be a shell function, to which the current command line\nargument is passed as the only argument. The function should set the\nvariable `REPLY` to the new value for the command line argument.\nIf the function returns non-zero status, so does the calling function.\n\nFor example, a user-defined widget containing the following code\nconverts the characters in the argument under the cursor into all upper\ncase:\n\nexample(modify-current-argument '${(U)ARG}')\n\nThe following strips any quoting from the current word (whether backslashes\nor one of the styles of quotes), and replaces it with single quoting\nthroughout:\n\nexample(modify-current-argument '${(qq)${(Q)ARG}}')\n\nThe following performs directory expansion on the command line\nargument and replaces it by the absolute path:\n\nexample(expand-dir+() {\n REPLY=${~1}\n REPLY=${REPLY:a}\n}\nmodify-current-argument expand-dir)\n\nIn practice the function `expand-dir` would probably not be defined\nwithin the widget where `modify-current-argument` is called."),
("break", "This style is used by the `incremental-complete-word` widget. Its value\nshould be a pattern, and all keys matching this pattern will cause the\nwidget to stop incremental completion without the key having any further\neffect. Like all styles used directly by\n`incremental-complete-word`, this style is looked up using the\ncontext \":incremental\"."),
("completer", "The `incremental-complete-word` and `insert-and-predict` widgets set\nup their top-level context name before calling completion. This allows\none to define different sets of completer functions for normal completion\nand for these widgets. For example, to use completion, approximation and\ncorrection for normal completion, completion and correction for\nincremental completion and only completion for prediction one could use:\n\n zstyle ':completion:*' completer \\\n _complete _correct _approximate\nzstyle ':completion:incremental:*' completer \\\n _complete _correct\nzstyle ':completion:predict:*' completer \\\n _complete\n\nIt is a good idea to restrict the completers used in prediction, because\nthey may be automatically invoked as you type. The `_list` and\n`_menu` completers should never be used with prediction. The\n`_approximate`, `_correct`, `_expand`, and `_match` completers may\nbe used, but be aware that they may change characters anywhere in the word\nbehind the cursor, so you need to watch carefully that the result is what\nyou intended."),
("cursor", "The `insert-and-predict` widget uses this style, in the context\n\":predict\", to decide where to place the cursor after completion has\nbeen tried. Values are:\n\n- **`complete`** âÂÂ\nThe cursor is left where it was when completion finished, but only if\nit is after a character equal to the one just inserted by the user. If\nit is after another character, this value is the same as \"key\".\n\n- **`key`** âÂÂ\nThe cursor is left\nafter the _n_th occurrence of the character just inserted, where\n_n_ is the number of times that character appeared in the word\nbefore completion was attempted. In short, this has the effect of\nleaving the cursor after the character just typed even if the\ncompletion code found out that no other characters need to be inserted\nat that position.\n\nAny other value for this style unconditionally leaves the cursor at the\nposition where the completion code left it."),
("list", "When using the `incremental-complete-word` widget, this style says\nif the matches should be listed on every key press (if they fit on the\nscreen). Use the context prefix \":completion:incremental\".\n\nThe `insert-and-predict` widget uses this style to decide if the\ncompletion should be shown even if there is only one possible completion.\nThis is done if the value of this style is the string `always`. In this\ncase the context is \":predict\" (_not_ \":completion:predict\")."),
("match", "This style is used by `smart-insert-last-word` to provide a pattern\n(using full `EXTENDED_GLOB` syntax) that matches an interesting word.\nThe context is the name of the widget to which `smart-insert-last-word`\nis bound (see above). The default behavior of `smart-insert-last-word`\nis equivalent to:\n\n zstyle :insert-last-word match '*[[:alpha:]/\\\\]*'\n\nHowever, you might want to include words that contain spaces:\n\n zstyle :insert-last-word match '*[[:alpha:][:space:]/\\\\]*'\n\nOr include numbers as long as the word is at least two characters long:\n\nexample(zstyle :insert-last-word match '*([[:digit:]]?|[[:alpha:]/\\\\])*')\n\nThe above example causes redirections like \"2>\" to be included."),
("prompt", "The `incremental-complete-word` widget shows the value of this\nstyle in the status line during incremental completion. The string\nvalue may contain any of the following substrings in the manner of\nthe `PS1` and other prompt parameters:\n\n\n- **`%c`** â Replaced by the name of the completer function that generated the\nmatches (without the leading underscore).\n\n\n- **`%l`** âÂÂ\nWhen the `list` style is set,\nreplaced by \"...\" if the list of matches is too long to fit on the\nscreen and with an empty string otherwise. If the `list` style is\n\"false\" or not set, \"%l\" is always removed.\n\n- **`%n`** âÂÂ\nReplaced by the number of matches generated.\n\n- **`%s`** âÂÂ\nReplaced by \"-no match-\", \"-no prefix-\", or an empty string\nif there is no completion matching the word on the line, if the\nmatches have no common prefix different from the word on the line, or\nif there is such a common prefix, respectively.\n\n- **`%u`** âÂÂ\nReplaced by the unambiguous part of all matches, if there\nis any, and if it is different from the word on the line.\n\nLike \"break-keys\", this uses the \":incremental\" context."),
("stop", "This style is used by the `incremental-complete-word` widget. Its value\nis treated similarly to the one for the `break-keys` style (and uses\nthe same context: \":incremental\"). However, in\nthis case all keys matching the pattern given as its value will stop\nincremental completion and will then execute their usual function."),
("toggle", "This boolean style is used by `predict-on` and its related widgets in\nthe context \":predict\". If set to one of the standard \"true\" values,\npredictive typing is automatically toggled off in situations where it is\nunlikely to be useful, such as when editing a multi-line buffer or after\nmoving into the middle of a line and then deleting a character. The\ndefault is to leave prediction turned on until an explicit call to\n`predict-off`."),
("verbose", "This boolean style is used by `predict-on` and its related widgets in\nthe context \":predict\". If set to one of the standard \"true\" values,\nthese widgets display a message below the prompt when the predictive state\nis toggled. This is most useful in combination with the `toggle` style.\nThe default does not display these messages."),
("widget", "This style is similar to the `command` style: For widget functions that\nuse `zle` to call other widgets, this style can sometimes be used to\noverride the widget which is called. The context for this style is the\nname of the calling widget (_not_ the name of the calling function,\nbecause one function may be bound to multiple widget names).\n\n zstyle :copy-earlier-word widget smart-insert-last-word\n\nCheck the documentation for the calling widget or function to determine\nwhether the `widget` style is used."),
("throw", "The function `throw` throws the named _exception_. The name is\nan arbitrary string and is only used by the `throw` and `catch`\nfunctions. An exception is for the most part treated the same as a\nshell error, i.e. an unhandled exception will cause the shell to abort all\nprocessing in a function or script and to return to the top level in an\ninteractive shell."),
("catch", "The function `catch` returns status zero if an exception was thrown and\nthe pattern _exception-pattern_ matches its name. Otherwise it\nreturns status 1. _exception-pattern_ is a standard\nshell pattern, respecting the current setting of the `EXTENDED_GLOB`\noption. An alias `catch` is also defined to prevent the argument to the\nfunction from matching filenames, so patterns may be used unquoted. Note\nthat as exceptions are not fundamentally different from other shell errors\nit is possible to catch shell errors by using an empty string as the\nexception name. The shell variable `CAUGHT` is set by `catch` to the\nname of the exception caught. It is possible to rethrow an exception by\ncalling the `throw` function again once an exception has been caught.\nfindex(catch)"),
("zsh", "These two functions use the files `~/.mime.types` and `/etc/mime.types`,\nwhich associate types and extensions, as well as `~/.mailcap` and\n`/etc/mailcap` files, which associate types and the programs that\nhandle them. These are provided on many systems with the Multimedia\nInternet Mail Extensions.\n\nTo enable the system, the function `zsh-mime-setup` should be\nautoloaded and run. This allows files with extensions to be treated\nas executable; such files be completed by the function completion system.\nThe function `zsh-mime-handler` should not need to be called by the\nuser.\n\nThe system works by setting up suffix aliases with \"alias -s\".\nSuffix aliases already installed by the user will not be overwritten.\n\nFor suffixes defined in lower case, upper case variants will also\nautomatically be handled (e.g. `PDF` is automatically handled if\nhandling for the suffix `pdf` is defined), but not vice versa.\n\nRepeated calls to `zsh-mime-setup` do not override the existing\nmapping between suffixes and executable files unless the option `-f`\nis given. Note, however, that this does not override existing suffix\naliases assigned to handlers other than `zsh-mime-handler`.\n\nCalling `zsh-mime-setup` with the option `-l` lists the existing\nmappings without altering them. Suffixes to list (which may contain\npattern characters that should be quoted from immediate interpretation\non the command line) may be given as additional arguments, otherwise\nall suffixes are listed.\n\nCalling `zsh-mime-setup` with the option\n`-v` causes verbose output to be shown during the setup operation.\n\nThe system respects the `mailcap` flags `needsterminal` and\n`copiousoutput`; see manref(mailcap)(4) or manref(mailcap)(5)\n(the man page's name varies across platforms).\n\nThe functions use the following styles, which are defined with the\n`zstyle` builtin command (_The zsh/zutil Module_ (zshmodules)).\nThey should be defined\nbefore `zsh-mime-setup` is run. The contexts used all\nstart with `:mime:`, with additional components in some cases.\nIt is recommended that a trailing `*` (suitably quoted) be appended\nto style patterns in case the system is extended in future. Some\nexamples are given below.\n\nFor files that have multiple suffixes, e.g. `.pdf.gz`, where the\ncontext includes the suffix it will be looked up starting with the\nlongest possible suffix until a match for the style is found.\nFor example, if `.pdf.gz` produces a match for the handler, that\nwill be used; otherwise the handler for `.gz` will be used. Note\nthat, owing to the way suffix aliases work, it is always required that\nthere be a handler for the shortest possible suffix, so in this example\n`.pdf.gz` can only be handled if `.gz` is also handled (though\nnot necessarily in the same way). Alternatively, if no handling\nfor `.gz` on its own is needed, simply adding the command\n\n alias -s gz=zsh-mime-handler\n\nto the initialisation code is sufficient; `.gz` will not be handled\non its own, but may be in combination with other suffixes.\n\nkindex(current-shell, MIME style)\n\n- **`current-shell`** âÂÂ\nIf this boolean style is true, the mailcap handler for the context in\nquestion is run using the `eval` builtin instead of by starting a new\n`sh` process. This is more efficient, but may not work in the occasional\ncases where the mailcap handler uses strict POSIX syntax.\n\nkindex(disown, MIME style)\n\n- **`disown`** âÂÂ\nIf this boolean style is true, mailcap handlers started in the\nbackground will be disowned, i.e. not subject to job control within\nthe parent shell. Such handlers nearly always produce their own\nwindows, so the only likely harmful side effect of setting the style is\nthat it becomes harder to kill jobs from within the shell.\n\nkindex(execute-as-is, MIME style)\n\n- **`execute-as-is`** â This style gives a list of patterns to be matched against files\npassed for execution with a handler program. If the file matches\nthe pattern, the entire command line is executed in its current form,\nwith no handler. This is useful for files which might have suffixes\nbut nonetheless be executable in their own right. If the style\nis not set, the pattern tt(*+(*+) *+(/+)) is used;\nhence executable files are executed directly and not passed to a\nhandler, and the option `AUTO_CD` may be used to change to directories\nthat happen to have MIME suffixes.\n\nkindex(execute-never, MIME style)\n\n- **`execute-never`** â This style is useful in combination with `execute-as-is`. It is\nset to an array of patterns corresponding to full paths to files that\nshould never be treated as executable, even if the file passed to\nthe MIME handler matches `execute-as-is`. This is useful for file\nsystems that don't handle execute permission or that contain executables\nfrom another operating system. For example, if `/mnt/windows` is a\nWindows mount, then\n\n zstyle ':mime:*' execute-never '/mnt/windows/*'\n\nwill ensure that any files found in that area will be executed as MIME\ntypes even if they are executable. As this example shows, the complete\nfile name is matched against the pattern, regardless of how the file\nwas passed to the handler. The file is resolved to a full path using\nthe `:P` modifier described in subref(Modifiers)(zshexpn);\nthis means that symbolic links are resolved where possible, so that\nlinks into other file systems behave in the correct fashion.\nkindex(file-path, MIME style)\n\n- **`file-path`** âÂÂ\nUsed if the style `find-file-in-path` is true for the same context.\nSet to an array of directories that are used for searching for the\nfile to be handled; the default is the command path given by the\nspecial parameter `path`. The shell option `PATH_DIRS` is respected;\nif that is set, the appropriate path will be searched even if the\nname of the file to be handled as it appears on the command line contains\na \"/\".\nThe full context is `:mime:.`_suffix_`:`, as described for the style\n`handler`.\n\nkindex(find-file-in-path, MIME style)\n\n- **`find-file-in-path`** â If set, allows files whose names do not contain absolute paths\nto be searched for in the command path or the path specified by the\n`file-path` style. If the file is not found in the path, it is looked\nfor locally (whether or not the current directory is in the path); if it is\nnot found locally, the handler will abort unless the `handle-nonexistent`\nstyle is set. Files found in the path are tested as described for\nthe style `execute-as-is`.\nThe full context is `:mime:.`_suffix_`:`, as described for the style\n`handler`.\n\nkindex(flags, MIME style)\n\n- **`flags`** âÂÂ\nDefines flags to go with a handler; the context is as for the\n`handler` style, and the format is as for the flags in `mailcap`.\n\nkindex(handle-nonexistent, MIME style)\n\n- **`handle-nonexistent`** âÂÂ\nBy default, arguments that don't correspond to files are not passed\nto the MIME handler in order to prevent it from intercepting commands found\nin the path that happen to have suffixes. This style may be set to\nan array of extended glob patterns for arguments that will be passed to the\nhandler even if they don't exist. If it is not explicitly set it\ndefaults to `[[:alpha:]]#:/*` which allows URLs to be passed to the MIME\nhandler even though they don't exist in that format in the file system.\nThe full context is `:mime:.`_suffix_`:`, as described for the style\n`handler`.\n\nkindex(handler, MIME style)\n\n- **`handler`** â Specifies a handler for a suffix; the suffix is given by the context as\n`:mime:.`_suffix_`:`, and the format of the handler is exactly\nthat in `mailcap`. Note in particular the \".\" and trailing colon\nto distinguish this use of the context. This overrides any handler\nspecified by the `mailcap` files. If the handler requires a terminal,\nthe `flags` style should be set to include the word `needsterminal`,\nor if the output is to be displayed through a pager (but not if the\nhandler is itself a pager), it should include `copiousoutput`.\n\nkindex(mailcap, MIME style)\n\n- **`mailcap`** âÂÂ\nA list of files in the format of `~/.mailcap` and\n`/etc/mailcap` to be read during setup, replacing the default list\nwhich consists of those two files. The context is `:mime:`.\nA `+` in the list will be replaced by the default files.\n\nkindex(mailcap-priorities, MIME style)\n\n- **`mailcap-priorities`** â This style is used to resolve multiple mailcap entries for the same MIME\ntype. It consists of an array of the following elements, in descending\norder of priority; later entries will be used if earlier entries are\nunable to resolve the entries being compared. If none of the tests\nresolve the entries, the first entry encountered is retained.\n\n\n- **`files`** â The order of files (entries in the `mailcap` style) read. Earlier\nfiles are preferred. (Note this does not resolve entries in the same file.)\n\n\n- **`priority`** âÂÂ\nThe priority flag from the mailcap entry. The priority is an integer\nfrom 0 to 9 with the default value being 5.\n\n- **`flags`** âÂÂ\nThe test given by the `mailcap-prio-flags` option is used to resolve\nentries.\n\n- **`place`** âÂÂ\nLater entries are preferred; as the entries are strictly ordered, this\ntest always succeeds.\n\nNote that as this style is handled during initialisation, the context\nis always `:mime:`, with no discrimination by suffix.\n\nkindex(mailcap-prio-flags, MIME style)\n\n- **`mailcap-prio-flags`** â This style is used when the keyword `flags` is encountered in the\nlist of tests specified by the `mailcap-priorities` style.\nIt should be set to a list of patterns, each of which is tested against\nthe flags specified in the mailcap entry (in other words, the sets of\nassignments found with some entries in the mailcap file). Earlier\npatterns in the list are preferred to later ones, and matched patterns\nare preferred to unmatched ones.\n\nkindex(mime-types, MIME style)\n\n- **`mime-types`** âÂÂ\nA list of files in the format of `~/.mime.types` and\n`/etc/mime.types` to be read during setup, replacing the default list\nwhich consists of those two files. The context is `:mime:`.\nA `+` in the list will be replaced by the default files.\n\nkindex(never-background, MIME style)\n\n- **`never-background`** â If this boolean style is set, the handler for the given context is\nalways run in the foreground, even if the flags provided in the mailcap\nentry suggest it need not be (for example, it doesn't require a\nterminal).\nkindex(pager, MIME style)\n\n- **`pager`** âÂÂ\nIf set, will be used instead of `$PAGER` or `more` to handle\nsuffixes where the `copiousoutput` flag is set. The context is\nas for `handler`, i.e. `:mime:.`_suffix_`:` for handling\na file with the given _suffix_.\n\nExamples:\n\n zstyle ':mime:*' mailcap ~/.mailcap /usr/local/etc/mailcap\nzstyle ':mime:.txt:' handler less %s\nzstyle ':mime:.txt:' flags needsterminal\n\nWhen `zsh-mime-setup` is subsequently run, it will look for\n`mailcap` entries in the two files given. Files of suffix `.txt`\nwill be handled by running ``less\" _file.txt_\". The flag\n`needsterminal` is set to show that this program must run attached to a\nterminal.\n\nAs there are several steps to dispatching a command, the following\nshould be checked if attempting to execute a file by extension\n`.`_ext_ does not have the expected effect.\n\nThe command ``alias -s\" _ext_\" should show\n\"ps=zsh-mime-handler\". If it shows something else, another suffix\nalias was already installed and was not overwritten. If it shows\nnothing, no handler was installed: this is most likely because no\nhandler was found in the `.mime.types` and `mailcap` combination for\n`.ext` files. In that case, appropriate handling should be added to\n`~/.mime.types` and `mailcap`.\n\nIf the extension is handled by `zsh-mime-handler` but the file is\nnot opened correctly, either the handler defined for the type is\nincorrect, or the flags associated with it are in appropriate. Running\n`zsh-mime-setup -l` will show the handler and, if there are any, the\nflags. A `%s` in the handler is replaced by the file (suitably quoted\nif necessary). Check that the handler program listed lists and can\nbe run in the way shown. Also check that the flags `needsterminal` or\n`copiousoutput` are set if the handler needs to be run under a\nterminal; the second flag is used if the output should be sent to a pager.\nAn example of a suitable `mailcap` entry for such a program is:\n\n text/html; /usr/bin/lynx '%s'; needsterminal\n\nRunning ``zsh-mime-handler -l\" _command line_\" prints the command\nline that would be executed, simplified to remove the effect of any\nflags, and quoted so that the output can be run as a complete zsh\ncommand line. This is used by the completion system to decide how to\ncomplete after a file handled by `zsh-mime-setup`."),
("pick", "This function is separate from the two MIME functions described above\nand can be assigned directly to a suffix:\n\n autoload -U pick-web-browser\nalias -s html=pick-web-browser\n\nIt is provided as an intelligent front end to dispatch a web browser.\nIt may be run as either a function or a shell script. The status\n255 is returned if no browser could be started.\n\nVarious styles are available to customize the choice of browsers:\n\n- **`browser-style`** âÂÂ\nThe value of the style is an array giving preferences in decreasing order\nfor the type of browser to use. The values of elements may be\n\n- **`running`** âÂÂ\nUse a GUI browser that is already running when an X Window display is\navailable. The browsers listed in the `x-browsers` style are tried\nin order until one is found; if it is, the file will be displayed in\nthat browser, so the user may need to check whether it has appeared.\nIf no running browser is found, one is not started. Browsers other than\nFirefox, Opera and Konqueror are assumed to understand the Mozilla\nsyntax for opening a URL remotely.\n\n- **`x`** âÂÂ\nStart a new GUI browser when an X Window display is available. Search for\nthe availability of one of the browsers listed in the `x-browsers` style\nand start the first one that is found. No check is made for an already\nrunning browser.\n\n- **`tty`** âÂÂ\nStart a terminal-based browser. Search for the availability of one\nof the browsers listed in the `tty-browsers` style and start the\nfirst one that is found.\n\nIf the style is not set the default `running x tty` is used.\n\n\n- **`x-browsers`** â An array in decreasing order\nof preference of browsers to use when running under the X Window System.\nThe array consists of the command name under which to start the\nbrowser. They are looked up in the context `:mime:` (which may\nbe extended in future, so appending \"*\" is recommended). For\nexample,\n\n zstyle ':mime:*' x-browsers opera konqueror firefox\n\nspecifies that `pick-web-browser` should first look for a running\ninstance of Opera, Konqueror or Firefox, in that order, and if it\nfails to find any should attempt to start Opera. The default is\n`firefox mozilla netscape opera konqueror`.\n\n\n- **`tty-browsers`** âÂÂ\nAn array similar to `x-browsers`, except that it gives browsers to\nuse when no X Window display is available. The default is\n`elinks links lynx`.\n\n\n- **`command`** â If it is set this style is used to pick the command\nused to open a page for a browser. The context is\n`:mime:browser:new:$browser:` to start a new browser or\n`:mime:browser:running:$browser:` to open a URL in a browser already\nrunning on the current X display, where `$browser` is the value matched\nin the `x-browsers` or `tty-browsers` style. The escape sequence\n`%b\" in the style\"s value will be replaced by the browser, while `%u`\nwill be replaced by the URL. If the style is not set, the default for all\nnew instances is equivalent to `%b %u` and the defaults for using running\nbrowsers are equivalent to the values `kfmclient openURL %u` for\nKonqueror, `firefox -new-tab %u` for Firefox, `opera -newpage %u`\nfor Opera, and tt(%b -remote \"openUrl+(%u+)\") for all others.\n"),
("zcalc", "A reasonably powerful calculator based on zsh's arithmetic evaluation\nfacility. The syntax is similar to that of formulae in most programming\nlanguages; see\n_Arithmetic Evaluation_ (zshmisc) for details.\n\nNon-programmers should note that, as in many other programming\nlanguages, expressions involving only integers (whether constants\nwithout a \".\", variables containing such constants as strings, or\nvariables declared to be integers) are by default evaluated using\ninteger arithmetic, which is not how an ordinary desk calculator\noperates. To force floating point operation, pass the option `-f`;\nsee further notes below.\n\nIf the file `~/.zcalcrc` exists it will be sourced inside the function\nonce it is set up and about to process the command line. This\ncan be used, for example, to set shell options; `emulate -L zsh`\nand `setopt extendedglob` are in effect at this point. Any\nfailure to source the file if it exists is treated as fatal.\nAs with other initialisation files, the directory `$ZDOTDIR` is used\ninstead of `$HOME` if it is set.\n\nThe mathematical library `zsh/mathfunc` will be loaded if it is\navailable; see\n_The zsh/mathfunc Module_ (zshmodules). The mathematical functions\ncorrespond to the raw system libraries, so trigonometric functions are\nevaluated using radians, and so on.\n\nEach line typed is evaluated as an expression. The prompt shows a number,\nwhich corresponds to a positional parameter where the result of that\ncalculation is stored. For example, the result of the calculation on the\nline preceded by \"4> \" is available as `$4`. The last value\ncalculated is available as `ans`. Full command line editing, including\nthe history of previous calculations, is available; the history is saved in\nthe file `$ZCALC_HISTFILE`. If `$ZCALC_HISTFILE` is unset,\n`$ZDOTDIR/.zcalc_history` is used instead, which in turn falls backs to\n`$HOME/.zcalc_history` if `$ZDOTDIR` is unset. To exit, enter a blank\nline or type \":q\" on its own (\"q\" is allowed for historical\ncompatibility).\n\nA line ending with a single backslash is treated in the same fashion\nas it is in command line editing: the backslash is removed, the\nfunction prompts for more input (the prompt is preceded by \"...\"\nto indicate this), and the lines are combined into one to get the final\nresult. In addition, if the input so far contains more open than\nclose parentheses `zcalc` will prompt for more input.\n\nIf arguments are given to `zcalc` on start up, they are used to prime the\nfirst few positional parameters. A visual indication of this is given when\nthe calculator starts.\n\nThe constants `PI` (3.14159...) and `E` (2.71828...) are provided.\nParameter assignment is possible, but note that all parameters will be\nput into the global namespace unless the `:local` special command is\nused. The function creates local variables whose names start with\n`_`, so users should avoid doing so. The variables `ans` (the last\nanswer) and `stack` (the stack in RPN mode) may be referred to\ndirectly; `stack` is an array but elements of it are numeric. Various\nother special variables are used locally with their standard meaning,\nfor example `compcontext`, `match`, `mbegin`, `mend`, `psvar`.\n\nThe output base can be initialised by passing the option ``-#\"_base_\",\nfor example \"zcalc -#16\" (the \"#\" may have to be quoted, depending\non the globbing options set).\n\nIf the option \"-e\" is set, the function runs non-interactively:\nthe arguments are treated as expressions to be evaluated as if entered\ninteractively line by line.\n\nIf the option \"-f\" is set, all numbers are treated as floating\npoint, hence for example the expression \"3/4\" evaluates to 0.75\nrather than 0. Options must appear in separate words.\n\nIf the option \"-r\" is set, RPN (Reverse Polish Notation) mode is\nentered. This has various additional properties:\n\n- **Stack** âÂÂ\nEvaluated values are maintained in a stack; this is contained in\nan array named `stack` with the most recent value in `${stack[1]}`.\n\n\n- **Operators and functions** â If the line entered matches an operator (`+`, `-`, `*`,\n`/`, `**`, `^`, `|` or `&`) or a function supplied by the\n`zsh/mathfunc` library, the bottom element or elements of the stack\nare popped to use as the argument or arguments. The higher elements\nof stack (least recent) are used as earlier arguments. The result is\nthen pushed into `${stack[1]}`.\n\n\n- **Expressions** â Other expressions are evaluated normally, printed, and added to the\nstack as numeric values. The syntax within expressions on a single line\nis normal shell arithmetic (not RPN).\n\n\n- **Stack listing** âÂÂ\nIf an integer follows the option `-r` with no space, then\non every evaluation that many elements of the stack, where available,\nare printed instead of just the most recent result. Hence, for example,\n`zcalc -r4` shows `$stack[4]` to `$stack[1]` each time results\nare printed.\n\n- **Duplication: `=`** âÂÂ\nThe pseudo-operator `=` causes the most recent element of\nthe stack to be duplicated onto the stack.\n\n- **`pop`** âÂÂ\nThe pseudo-function `pop` causes the most recent element of\nthe stack to be popped. A \">\" on its own has the same effect.\n\n\n- **`>`_ident_** â The expression `>` followed (with no space) by a shell identifier\ncauses the most recent element of the stack to be popped and\nassigned to the variable with that name. The variable is\nlocal to the `zcalc` function.\n\n\n- **`<`_ident_** â The expression `<` followed (with no space) by a shell identifier\ncauses the value of the variable with that name to be pushed\nonto the stack. _ident_ may be an integer, in which\ncase the previous result with that number (as shown before\nthe `>` in the standard `zcalc` prompt) is put on the stack.\n\n\n- **Exchange: `xy`** âÂÂ\nThe pseudo-function `xy` causes the most recent two elements of\nthe stack to be exchanged. \"<>\" has the same effect.\n\nThe prompt is configurable via the parameter `ZCALCPROMPT`, which\nundergoes standard prompt expansion. The index of the current entry is\nstored locally in the first element of the array `psvar`, which can be\nreferred to in `ZCALCPROMPT` as \"%1v\". The default prompt is\n\"%1v> \".\n\nThe variable `ZCALC_ACTIVE` is set within the function and can\nbe tested by nested functions; it has the value `rpn` if RPN mode is\nactive, else 1.\n\nA few special commands are available; these are introduced by a colon.\nFor backward compatibility, the colon may be omitted for certain\ncommands. Completion is available if `compinit` has been run.\n\nThe output precision may be specified within zcalc by special commands\nfamiliar from many calculators.\n\n- **`:norm`** âÂÂ\nThe default output format. It corresponds to the printf `%g`\nspecification. Typically this shows six decimal digits.\n\n- **`:sci` _digits_** âÂÂ\nScientific notation, corresponding to the printf `%g` output format with\nthe precision given by _digits_. This produces either fixed point or\nexponential notation depending on the value output.\n\n- **`:fix` _digits_** âÂÂ\nFixed point notation, corresponding to the printf `%f` output format with\nthe precision given by _digits_.\n\n- **`:eng` _digits_** âÂÂ\nExponential notation, corresponding to the printf `%E` output format with\nthe precision given by _digits_.\n\n- **`:raw`** âÂÂ\nRaw output: this is the default form of the output from a math\nevaluation. This may show more precision than the number actually\npossesses.\n\nOther special commands:\n\n- **`:!`_line..._** âÂÂ\nExecute _line..._ as a normal shell command line. Note that it\nis executed in the context of the function, i.e. with local variables.\nSpace is optional after `:!`.\n\n- **`:local` _arg_ ...** âÂÂ\nDeclare variables local to the function. Other variables\nmay be used, too, but they will be taken from or put into the global\nscope.\n\n\n- **`:function` _name_ [ _body_ ]** â Define a mathematical function or (with no _body_) delete it.\n`:function` may be abbreviated to `:func` or simply `:f`.\nThe _name_ may contain the same characters as a shell function name.\nThe function is defined using `zmathfuncdef`, see below.\n\nNote that `zcalc` takes care of all quoting. Hence for example:\n\n :f cube $1 * $1 * $1\n\ndefines a function to cube the sole argument. Functions so defined, or\nindeed any functions defined directly or indirectly using `functions\n-M`, are available to execute by typing only the name on the line in RPN\nmode; this pops the appropriate number of arguments off the stack\nto pass to the function, i.e. 1 in the case of the example `cube`\nfunction. If there are optional arguments only the mandatory\narguments are supplied by this means.\n\n\n- **`[#`_base_`]`** âÂÂ\nThis is not a special command, rather part of normal arithmetic\nsyntax; however, when this form appears on a line by itself the default\noutput radix is set to _base_. Use, for example, \"[#16]\" to display\nhexadecimal output preceded by an indication of the base, or \"[##16]\"\njust to display the raw number in the given base. Bases themselves are\nalways specified in decimal. \"[#]\" restores the normal output format.\nNote that setting an output base suppresses floating point output; use\n\"[#]\" to return to normal operation.\n\n- **`$`_var_** âÂÂ\nPrint out the value of var literally; does not affect the calculation.\nTo use the value of var, omit the leading \"$\".\n\nSee the comments in the function for a few extra tips."),
("zmathfunc", "The function `zmathfunc` defines the three mathematical functions\n`min`, `max`, and `sum`. The functions `min` and `max` take\none or more arguments. The function `sum` takes zero or more arguments.\nArguments can be of different types (ints and floats).\n\nNot to be confused with the `zsh/mathfunc` module, described in\n_The zsh/mathfunc Module_ (zshmodules)."),
("zmathfuncdef", "A convenient front end to `functions -M`.\n\nWith two arguments, define a mathematical function named _mathfunc_\nwhich can be used in any form of arithmetic evaluation. _body_\nis a mathematical expression to implement the function. It may\ncontain references to position parameters `$1`, `$2`, ...\nto refer to mandatory parameters and `${1:-`_defvalue_`}` ...\nto refer to optional parameters. Note that the forms must be\nstrictly adhered to for the function to calculate the correct number\nof arguments. The implementation is held in a shell function named\n`zsh_math_func_`_mathfunc_; usually the user will not need\nto refer to the shell function directly. Any existing function\nof the same name is silently replaced.\n\nWith one argument, remove the mathematical function _mathfunc_\nas well as the shell function implementation.\n\nWith no arguments, list all _mathfunc_ functions in a form\nsuitable for restoring the definition.\nThe functions have not necessarily been defined by `zmathfuncdef`."),
("zsh", "The function presents the user with various options for customizing\ntheir initialization scripts. Currently only `~/.zshrc` is handled.\n`$ZDOTDIR/.zshrc` is used instead if the parameter `ZDOTDIR` is\nset; this provides a way for the user to configure a file without\naltering an existing `.zshrc`.\n\nBy default the function exits immediately if it finds any of the files\n`.zshenv`, `.zprofile`, `.zshrc`, or `.zlogin` in the appropriate\ndirectory. The option `-f` is required in order to force the function\nto continue. Note this may happen even if `.zshrc` itself does not\nexist.\n\nAs currently configured, the function will exit immediately if the\nuser has root privileges; this behaviour cannot be overridden.\n\nOnce activated, the function's behaviour is supposed to be\nself-explanatory. Menus are present allowing the user to alter\nthe value of options and parameters. Suggestions for improvements are\nalways welcome.\n\nWhen the script exits, the user is given the opportunity to save the new\nfile or not; changes are not irreversible until this point. However,\nthe script is careful to restrict changes to the file only to a group\nmarked by the lines \"# Lines configured by zsh-newuser-install\" and\n\"# End of lines configured by zsh-newuser-install\". In addition,\nthe old version of `.zshrc` is saved to a file with the suffix\n`.zni` appended.\n\nIf the function edits an existing `.zshrc`, it is up to the user\nto ensure that the changes made will take effect. For example, if\ncontrol usually returns early from the existing `.zshrc` the lines\nwill not be executed; or a later initialization file may override\noptions or parameters, and so on. The function itself does not attempt to\ndetect any such conflicts."),
("colors", "This function initializes several associative arrays to map color names to\n(and from) the ANSI standard eight-color terminal codes. These are used\nby the prompt theme system (see _Prompt Themes_ (above)).\nYou seldom should need to run\n`colors` more than once.\n\nThe eight base colors are: `black`, `red`, `green`, `yellow`,\n`blue`, `magenta`, `cyan`, and `white`. Each of these has codes for\nforeground and background. In addition there are seven intensity attributes:\n`bold`, `faint`, `italic`, `underline`, `blink`, `reverse`,\nand `conceal`. Finally, there are seven codes used to negate attributes:\n`none` (reset all attributes to the defaults), `normal`\n(neither bold nor faint), `no-italic`, `no-underline`, `no-blink`,\n`no-reverse`, and `no-conceal`.\n\nSome terminals do not support all combinations of colors and intensities.\nPrior to zsh `5.8.1` the intensity `standout` was provided. It has\nbeen replaced by the more specific `italic` and `reverse` to match\nthe specification, but some terminals may swap these or make one of them\nproduce blinking text even if the `blink` code is not usable.\n\nThe associative arrays are:\n\n- **`color`**\n\n- **`colour`** âÂÂ\nMap all the color names to their integer codes, and integer codes to the\ncolor names. The eight base names map to the foreground color codes, as\ndo names prefixed with \"fg-\", such as \"fg-red\". Names prefixed\nwith \"bg-\", such as \"bg-blue\", refer to the background codes. The\nreverse mapping from code to color yields base name for foreground codes\nand the `bg-` form for backgrounds.\n\nAlthough it is a misnomer to call them \"colors\", these arrays also map the\nother fourteen attributes from names to codes and codes to names.\n\n- **`fg`**\n\n- **`fg_bold`**\n\n- **`fg_no_bold`** âÂÂ\nMap the eight basic color names to ANSI terminal escape sequences that set\nthe corresponding foreground text properties. The `fg` sequences change\nthe color without changing the eight intensity attributes.\n\n- **`bg`**\n\n- **`bg_bold`**\n\n- **`bg_no_bold`** âÂÂ\nMap the eight basic color names to ANSI terminal escape sequences that set\nthe corresponding background properties. The `bg` sequences change the\ncolor without changing the eight intensity attributes.\n\nIn addition, the scalar parameters `reset_color` and `bold_color` are\nset to the ANSI terminal escapes that turn off all attributes and turn on\nbold intensity, respectively."),
("fned", "Same as `zed -f`. This function does not appear in the zsh\ndistribution, but can be created by linking `zed` to the name `fned`\nin some directory in your `fpath`."),
("histed", "Same as `zed -h`. This function does not appear in the zsh\ndistribution, but can be created by linking `zed` to the name `histed`\nin some directory in your `fpath`."),
("is", "Perform a greater-than-or-equal-to comparison of two strings having the\nformat of a zsh version number; that is, a string of numbers and text with\nsegments separated by dots or dashes. If the _present_ string is not\nprovided, `$ZSH_VERSION` is used. Segments are paired left-to-right in\nthe two strings with leading non-number parts ignored. If one string has\nfewer segments than the other, the missing segments are considered zero.\n\nThis is useful in startup files to set options and other state that are\nnot available in all versions of zsh.\n\n is-at-least 3.1.6-15 && setopt NO_GLOBAL_RCS\nis-at-least 3.1.0 && setopt HIST_REDUCE_BLANKS\nis-at-least 2.6-17 || print \"You can't use is-at-least here.\""),
("rmshadow", "These functions are an interface to the `_shadow` and `_unshadow`\ncompletion utilities to make them more easily accessible in other\ncontexts. Usage is exactly as for the completion utility:\n\n {\n mkshadow fname\n function fname {\n # Do your new thing\n }\n # Invoke callers of fname\n} always {\n rmshadow\n}\n\nUpon return, the value of `$REPLY` is the suffix used to create a\ncopy of the original _command_name_, so _command_name_`@$REPLY`\ninvokes that original."),
("nslookup", "This wrapper function for the `nslookup` command requires the\n`zsh/zpty` module (see _The zsh/zpty Module_ (zshmodules)).\nIt behaves exactly like the standard `nslookup`\nexcept that it provides customizable prompts (including a right-side\nprompt) and completion of nslookup commands, host names, etc. (if you use\nthe function-based completion system). Completion styles may be set with\nthe context prefix \":completion:nslookup\".\n\nSee also the `pager`, `prompt` and `rprompt` styles below."),
("regexp", "Use regular expressions to perform a global search and replace operation\non a variable. POSIX extended regular expressions (ERE) are used,\nunless the option `RE_MATCH_PCRE` has been set, in which case\nPerl-compatible regular expressions are used\n(this requires the shell to be linked against the `pcre`\nlibrary).\n\n_var_ is the name of the variable containing the string to be matched.\nThe variable will be modified directly by the function. The\nvariables `MATCH`, `MBEGIN`, `MEND`, `match`, `mbegin`, `mend`\nshould be avoided as these are used by the regular expression code.\n\n_regexp_ is the regular expression to match against the string.\n\n_replace_ is the replacement text. This can contain parameter, command\nand arithmetic expressions which will be replaced: in particular, a\nreference to `$MATCH` will be replaced by the text matched by the pattern.\n\nThe return status is 0 if at least one match was performed, else 1.\n\nNote that if using POSIX EREs, the `^` or word boundary operators\n(where available) may not work properly."),
("run", "This function is designed to be invoked by the `run-help` ZLE widget,\nin place of the default alias. See subref(Accessing On-Line Help)(above)\nfor setup instructions.\n\nIn the discussion which follows, if _cmd_ is a file system path, it is\nfirst reduced to its rightmost component (the file name).\n\nHelp is first sought by looking for a file named _cmd_ in the directory\nnamed by the `HELPDIR` parameter. If no file is found, an assistant\nfunction, alias, or command named `run-help-_cmd_` is sought. If\nfound, the assistant is executed with the rest of the current command line\n(everything after the command name _cmd_) as its arguments. When\nneither file nor assistant is found, the external command\n``man\" _cmd_\" is run.\n\nAn example assistant for the \"ssh\" command:\n\nexample(run-help-ssh+() {\n emulate -LR zsh\n local -a args\n # Delete the \"-l username\" option\n zparseopts -D -E -a args l:\n # Delete other options, leaving: host command\n args=(${@:#-*})\n if [[ ${#args} -lt 2 ]]; then\n man ssh\n else\n run-help $args[2]\n fi\n})\n\nSeveral of these assistants are provided in the `Functions/Misc`\ndirectory. These must be autoloaded, or placed as executable scripts in\nyour search path, in order to be found and used by `run-help`.\n\nfindex(run-help-btrfs)\nfindex(run-help-git)\nfindex(run-help-ip)\nfindex(run-help-openssl)\nfindex(run-help-p4)\nfindex(run-help-sudo)\nfindex(run-help-svk)\nfindex(run-help-svn)\n\n- **`run-help-btrfs`**\n\n- **`run-help-git`**\n\n- **`run-help-ip`**\n\n- **`run-help-openssl`**\n\n- **`run-help-p4`**\n\n- **`run-help-sudo`**\n\n- **`run-help-svk`**\n\n- **`run-help-svn`** âÂÂ\nAssistant functions for the\n`btrfs`,\n`git`,\n`ip`,\n`openssl`,\n`p4`,\n`sudo`,\n`svk`,\nand\n`svn`,\ncommands."),
("tetris", "Zsh was once accused of not being as complete as Emacs,\nbecause it lacked a Tetris game. This function was written to\nrefute this vicious slander.\n\nThis function must be used as a ZLE widget:\n\n autoload -U tetris\nzle -N tetris\nbindkey _keys_ tetris\n\nTo start a game, execute the widget by typing the _keys_. Whatever command\nline you were editing disappears temporarily, and your keymap is also\ntemporarily replaced by the Tetris control keys. The previous editor state\nis restored when you quit the game (by pressing \"q\") or when you lose.\n\nIf you quit in the middle of a game, the next invocation of the `tetris`\nwidget will continue where you left off. If you lost, it will start a new\ngame."),
("tetriscurses", "This is a port of the above to zcurses. The input handling is improved\na bit so that moving a block sideways doesn't automatically advance a\ntimestep, and the graphics use unicode block graphics.\n\nThis version does not save the game state between invocations, and is not\ninvoked as a widget, but rather as:\n\n autoload -U tetriscurses\ntetriscurses"),
("zargs", "This function has a similar purpose to GNU xargs. Instead of\nreading lines of arguments from the standard input, it takes them from\nthe command line. This is useful because zsh, especially with recursive\nglob operators, often can construct a command line for a shell function\nthat is longer than can be accepted by an external command.\n\nThe _option_ list represents options of the `zargs` command itself,\nwhich are the same as those of `xargs`. The _input_ list is the\ncollection of strings (often file names) that become the arguments of the\n`command`, analogous to the standard input of `xargs`. Finally, the\n_arg_ list consists of those arguments (usually options) that are\npassed to the _command_ each time it runs. The _arg_ list precedes\nthe elements from the `input` list in each run. If no _command_ is\nprovided, then no _arg_ list may be provided, and in that event the\ndefault command is \"print\" with arguments ``-r -\"-\".\n\nFor example, to get a long `ls` listing of all non-hidden plain files\nin the current directory or its subdirectories:\n\nexample(autoload -U zargs\nzargs -- **/*(.) -- ls -ld --)\n\nThe first and third occurrences of ``-\"-\" are used to mark the end\nof options for `zargs` and `ls` respectively to guard against\nfilenames starting with \"-\", while the second is used to separate the\nlist of files from the command to run (\"ls -ld --\").\n\nThe first ``-\"-\" would also be needed if there was a chance the\nlist might be empty as in:\n\nexample(zargs -r -- ./*.back+(#qN+) -- rm -f)\n\nIn the event that the string ``-\"-\" is or may be an _input_, the\n`-e` option may be used to change the end-of-inputs marker. Note that\nthis does _not_ change the end-of-options marker. For example, to use\n\"..\" as the marker:\n\nexample(zargs -e.. -- **/*(.) .. ls -ld --)\n\nThis is a good choice in that example because no plain file can be named\n\"..\", but the best end-marker depends on the circumstances.\n\nThe options `-i`, `-I`, `-l`, `-L`, and `-n` differ slightly\nfrom their usage in `xargs`. There are no input lines for `zargs` to\ncount, so `-l` and `-L` count through the _input_ list, and `-n`\ncounts the number of arguments passed to each execution of _command_,\n_including_ any _arg_ list. Also, any time `-i` or `-I` is used,\neach _input_ is processed separately as if by ``-L` `1`'.\n\nFor details of the other `zargs` options, see the manref(xargs)(1) man page (but note\nthe difference in function between `zargs` and `xargs`) or run\n`zargs` with the `-``-help` option."),
("zed", "This function uses the ZLE editor to edit a file or function.\n\nOnly one _name_ argument is allowed.\nIf the `-f` option is given, the name is taken to be that of\na function; if the function is marked for autoloading, `zed` searches\nfor it in the `fpath` and loads it. Note that functions edited this way\nare installed into the current shell, but _not_ written back to the\nautoload file. In this case the `-x` option specifies that leading\ntabs indenting the function according to syntax should be converted into\nthe given number of spaces; \"-x 2\" is consistent with the layout\nof functions distributed with the shell.\n\nWithout `-f`, _name_ is the path name of the file to edit, which need\nnot exist; it is created on write, if necessary. With `-h`, the file is\npresumed to contain history events.\n\nWhen no file name is provided for `-h` the current shell history is edited\nin place. The history is renumbered when zed exits successfully.\n\nWhen editing history, multi-line events must have a trailing backslash on\nevery line before the last.\n\nWhile editing, the function sets the main keymap to `zed` and the\nvi command keymap to `zed-vicmd`. These will be copied from the existing\n`main` and `vicmd` keymaps if they do not exist the first time `zed`\nis run. They can be used to provide special key bindings used only in zed.\n\nIf it creates the keymap, `zed` rebinds the return key to insert a line\nbreak and \"^X^W\" to accept the edit in the `zed` keymap, and binds\n\"ZZ\" to accept the edit in the `zed-vicmd` keymap.\n\nThe bindings alone can be installed by running \"zed -b\". This is\nsuitable for putting into a startup file. Note that, if rerun,\nthis will overwrite the existing `zed` and `zed-vicmd` keymaps.\n\nCompletion is available, and styles may be set with the context prefix\n\":completion:zed:\".\n\nfindex(zed-set-file-name)\nA zle widget `zed-set-file-name` is available. This can be called\nby name from within zed using \"\\ex zed-set-file-name\" or can be\nbound to a key in either of the `zed` or `zed-vicmd` keymaps after\n\"zed -b\" has been run. When the widget is called, it prompts for\na new name for the file being edited. When zed exits the file will be\nwritten under that name and the original file will be left alone. The\nwidget has no effect when invoked from \"zed -f\". The completion\ncontext is changed to \":completion:zed-set-file-name:\". When editing\nthe current history with \"zed -h\", the history is first updated and\nthen the file is written, but the global setting of `HISTFILE` is not\naltered.\n\nWhile `zed-set-file-name` is running, zed uses the keymap\n`zed-normal-keymap`, which is linked from the main keymap in effect\nat the time zed initialised its bindings. (This is to make the return key\noperate normally.) The result is that if the main keymap has been changed,\nthe widget won't notice. This is not a concern for most users."),
("zln", "Same as `zmv -C` and `zmv -L`, respectively. These functions do not\nappear in the zsh distribution, but can be created by linking `zmv` to\nthe names `zcp` and `zln` in some directory in your `fpath`."),
("zkbd", "See subref(Keyboard Definition)(above)."),
("zmv", "Move (usually, rename) files matching the pattern _srcpat_ to\ncorresponding files having names of the form given by _dest_, where\n_srcpat_ contains parentheses surrounding patterns which will be\nreplaced in turn by `$1`, `$2`, ... in _dest_. For example,\n\nexample(zmv '(*).lis' '$1.txt')\n\nrenames \"foo.lis\" to \"foo.txt\", \"my.old.stuff.lis\" to\n\"my.old.stuff.txt\", and so on.\n\nThe pattern is always treated as an `EXTENDED_GLOB` pattern. Any file\nwhose name is not changed by the substitution is simply ignored. Any\nerror (no files matched the _srcpat_, substitution resulted in an empty\nstring, two substitutions gave the same result, the destination was an\nexisting regular file and `-f` was not given) causes the entire function\nto abort without doing anything.\n\nIn addition to pattern replacement, the variable `$f` can be referred\nto in the second (replacement) argument. This makes it possible to\nuse variable substitution to alter the argument; see examples below.\n\nOptions:\n\n\n- **`-f`** â Force overwriting of destination files. Not currently\npassed down to the `mv`/`cp`/`ln` command due to vagaries of\nimplementations (but you can use `-o-f` to do that).\n\n- `-i` â Interactive: show each line to be executed and ask the user\nwhether to execute it. \"Y\" or \"y\" will execute it, anything else will\nskip it. Note that you just need to type one character.\n- `-n\" â No execution: print what would happen, but don\"t do it.\n- `-q` â Turn bare glob qualifiers off: now assumed by default, so\nthis has no effect.\n- `-Q\" â Force bare glob qualifiers on. Don\"t turn this on unless\nyou are actually using glob qualifiers in a pattern.\n- `-s` â Symbolic, passed down to `ln`; only works with `-L`.\n- `-v\" â Verbose: print each command as it\"s being executed.\n- `-w` â Pick out wildcard parts of the pattern, as described above,\nand implicitly add parentheses for referring to them.\n- `-W` â Just like `-w`, with the addition of turning wildcards in\nthe replacement pattern into sequential `${1}` .. `${N}` references.\n\n- **`-C`**\n\n\n- **`-L`**\n\n- `-M` â Force `cp`, `ln` or `mv`, respectively, regardless of\nthe name of the function.\n\n- **`-p` _program_** â Call _program_ instead of `cp`, `ln` or\n`mv`. Whatever it does, it should at least understand the form\nifzman(`_program_ `-``-\" _oldname_ _newname_\")\\\nifnzman(\n\n _program_ `-``-` _oldname_ _newname_\n\n)\nwhere _oldname_ and _newname_ are filenames generated by `zmv`.\n_program_ will be split into words, so might be e.g. the name\nof an archive tool plus a copy or rename subcommand.\n\n- `-P` _program_ â As `-p` _program_, except that\n_program_ does not accept a following `-``-` to indicate the\nend of options. In this case filenames must already be in a sane\nform for the program in question.\n- `-o` _optstring_ â The _optstring_ is split into words and\npassed down verbatim to the `cp`, `ln` or `mv` command called to\nperform the work. It should probably begin with a \"-\".\n\nFurther examples:\n\nexample(zmv -v '(* *)' '${1// /_}')\n\nFor any file in the current directory with at least one space in the name,\nreplace every space by an underscore and display the commands executed.\n\n zmv -v '* *' '${f// /_}'\n\nThis does exactly the same by referring to the file name stored in `$f`.\n\nFor more complete examples and other implementation details, see the\n`zmv` source file, usually located in one of the directories named in\nyour `fpath`, or in `Functions/Misc/zmv` in the zsh distribution."),
("zrecompile", "See subref(Recompiling Functions)(above)."),
("zstyle", "This makes defining styles a bit simpler by using a single \"+\" as a\nspecial token that allows you to append a context name to the previously\nused context name. Like this:\n\n zstyle+ ':foo:bar' _style1_ _value1_ \\\n + ':baz' _style2_ _value2_ \\\n + ':frob' _style3_ _value3_\n\nThis defines _style1_ with _value1_ for the context `:foo:bar` as usual,\nbut it also defines _style2_ with _value2_ for the context\n`:foo:bar:baz` and _style3_ with _value3_ for `:foo:bar:frob`. Any\n_subcontext_ may be the empty string to re-use the first context\nunchanged."),
("insert", "The `zed` function _sets_ this style in context \":completion:zed:*\"\nto turn off completion when `TAB` is typed at the beginning of a line.\nYou may override this by setting your own value for this context and style."),
("pager", "The `nslookup` function looks up this style in the context\n\":nslookup\" to determine the program used to display output that does\nnot fit on a single screen."),
("rprompt", "The `nslookup` function looks up this style in the context\n\":nslookup\" to set the prompt and the right-side prompt, respectively.\nThe usual expansions for the `PS1` and `RPS1` parameters may be used\n(see _Expansion of Prompt Sequences_ (zshmisc))."),
("zfparams", "Set or show the parameters for a future `zfopen` with no arguments. If\nno arguments are given, the current parameters are displayed (the password\nwill be shown as a line of asterisks). If a _host_ is given, and either the\n_user_ or _password_ is not, they will be prompted for; also, any\nparameter given as \"?\" will be prompted for, and if the \"?\" is\nfollowed by a string, that will be used as the prompt. As `zfopen` calls\n`zfparams` to store the parameters, this usually need not be called\ndirectly.\n\nA single argument \"-\" will delete the stored parameters. This will\nalso cause the memory of the last directory (and so on) on the other host\nto be deleted."),
("zfopen", "If _host_ is present, open a connection to that host under username\n_user_ with password _password_ (and, on the rare occasions when it\nis necessary, account _account_). If a necessary parameter is missing or\ngiven as \"?\" it will be prompted for. If _host_ is not present, use\na previously stored set of parameters.\n\nIf the command was successful, and the terminal is compatible with\n`xterm` or is `sun-cmd`, a summary will appear in the title bar,\ngiving the local `host:directory` and the remote `host:directory`;\nthis is handled by the function `zftp_chpwd`, described below.\n\nNormally, the _host_, _user_ and _password_ are internally\nrecorded for later re-opening, either by a `zfopen` with no arguments, or\nautomatically (see below). With the option \"-1\", no information is\nstored. Also, if an open command with arguments failed, the parameters\nwill not be retained (and any previous parameters will also be deleted).\nA `zfopen` on its own, or a `zfopen -1`, never alters the stored\nparameters.\n\nBoth `zfopen` and `zfanon` (but not `zfparams`) understand URLs of\nthe form `ftp://`_host_/_path..._ as meaning to connect to the\n_host_, then change directory to _path_ (which must be a directory,\nnot a file). The \"ftp://\" can be omitted; the trailing \"/\" is enough\nto trigger recognition of the _path_. Note prefixes other than\n\"ftp:\" are not recognized, and that all characters after the first\nslash beyond _host_ are significant in _path_."),
("zfanon", "Open a connection _host_ for anonymous FTP. The username used is\n\"anonymous\". The password (which will be reported the first time) is\ngenerated as _user_`@`_host_; this is then stored in the shell\nparameter `$EMAIL_ADDR` which can alternatively be set manually to a\nsuitable string."),
("zfcd", "Change the current directory on the remote server: this is implemented to\nhave many of the features of the shell builtin `cd`.\n\nIn the first form with _dir_ present, change to the directory _dir_.\nThe command \"zfcd ..\" is treated specially, so is guaranteed to work on\nnon-UNIX servers (note this is handled internally by `zftp`). If _dir_\nis omitted, has the effect of \"zfcd ~\".\n\nThe second form changes to the directory previously current.\n\nThe third form attempts to change the current directory by replacing the\nfirst occurrence of the string _old_ with the string _new_ in the\ncurrent directory.\n\nNote that in this command, and indeed anywhere a remote filename is\nexpected, the string which on the local host corresponds to \"~\" is\nconverted back to a \"~\" before being passed to the remote machine.\nThis is convenient because of the way expansion is performed on the command\nline before `zfcd` receives a string. For example, suppose the command\nis \"zfcd ~/foo\". The shell will expand this to a full path such as\n\"zfcd /home/user2/pws/foo\". At this stage, `zfcd` recognises the\ninitial path as corresponding to \"~\" and will send the directory to\nthe remote host as `~/foo`, so that the \"~\" will be expanded by the\nserver to the correct remote host directory. Other named directories of\nthe form \"~name\" are not treated in this fashion."),
("zfhere", "Change directory on the remote server to the one corresponding to the\ncurrent local directory, with special handling of \"~\" as in `zfcd`.\nFor example, if the current local directory is `~/foo/bar`, then\n`zfhere` performs the effect of \"zfcd ~/foo/bar\"."),
("zfdir", "Produce a long directory listing. The arguments _dir-options_ and\n_dir_ are passed directly to the server and their effect is\nimplementation dependent, but specifying a particular remote directory\n_dir_ is usually possible. The output is passed through a pager\ngiven by the environment variable `$PAGER`, or \"more\" if that is not\nset.\n\nThe directory is usually cached for re-use. In fact, two caches are\nmaintained. One is for use when there is no _dir-options_ or _dir_,\ni.e. a full listing of the current remote directory; it is flushed\nwhen the current remote directory changes. The other is\nkept for repeated use of `zfdir` with the same arguments; for example,\nrepeated use of \"zfdir /pub/gnu\" will only require the directory to be\nretrieved on the first call. Alternatively, this cache can be re-viewed with\nthe `-r` option. As relative directories will confuse\n`zfdir`, the `-f` option can be used to force the cache to be flushed\nbefore the directory is listed. The option `-d` will delete both\ncaches without showing a directory listing; it will also delete the cache\nof file names in the current remote directory, if any."),
("zfls", "List files on the remote server. With no arguments, this will produce a\nsimple list of file names for the current remote directory. Any arguments\nare passed directly to the server. No pager and no caching is used."),
("zftype", "With no arguments, show the type of data to be transferred, usually ASCII\nor binary. With an argument, change the type: the types \"A\" or\n\"ASCII\" for ASCII data and \"B\" or \"BINARY\", \"I\" or\n\"IMAGE\" for binary data are understood case-insensitively."),
("zfstat", "Show the status of the current or last connection, as well as the status of\nsome of `zftp`'s status variables. With the `-v` option, a more\nverbose listing is produced by querying the server for its version of\nevents, too."),
("zfget", "Retrieve all the listed files _file1_ ... one at a time from the remote\nserver. If a file contains a \"/\", the full name is passed to the\nremote server, but the file is stored locally under the name given by the\npart after the final \"/\". The option `-c` (cat) forces all files to\nbe sent as a single stream to standard output; in this case the `-t`\noption has no effect."),
("zfuget", "As `zfget`, but only retrieve files where the version on the remote\nserver is newer (has a later modification time), or where the local file\ndoes not exist. If the remote file is older but the files have different\nsizes, or if the sizes are the same but the remote file is newer, the user\nwill usually be queried. With the option `-s`, the command runs silently\nand will always retrieve the file in either of those two cases. With the\noption `-v`, the command prints more information about the files while it\nis working out whether or not to transfer them."),
("zfcget", "As `zfget`, but if any of the local files exists, and is shorter than\nthe corresponding remote file, the command assumes that it is the result of\na partially completed transfer and attempts to transfer the rest of the\nfile. This is useful on a poor connection which keeps failing.\n\nNote that this requires a commonly implemented, but non-standard, version\nof the FTP protocol, so is not guaranteed to work on all servers."),
("zfgcp", "This retrieves files from the remote server with arguments behaving\nsimilarly to the `cp` command.\n\nIn the first form, copy _remote-file_ from the server to the local file\n_local-file_.\n\nIn the second form, copy all the remote files _rfile1_ ... into the\nlocal directory _ldir_ retaining the same basenames. This assumes UNIX\ndirectory semantics."),
("zfput", "Send all the _file1_ ... given separately to the remote server. If a\nfilename contains a \"/\", the full filename is used locally to find the\nfile, but only the basename is used for the remote file name.\n\nWith the option `-r`, if any of the _files_ are directories they are\nsent recursively with all their subdirectories, including files beginning\nwith \".\". This requires that the remote machine understand UNIX file\nsemantics, since \"/\" is used as a directory separator."),
("zfuput", "As `zfput`, but only send files which are newer than their remote\nequivalents, or if the remote file does not exist. The logic is the same\nas for `zfuget`, but reversed between local and remote files."),
("zfcput", "As `zfput`, but if any remote file already exists and is shorter than the\nlocal equivalent, assume it is the result of an incomplete transfer and\nsend the rest of the file to append to the existing part. As the FTP\nappend command is part of the standard set, this is in principle more\nlikely to work than `zfcget`."),
("zfpcp", "This sends files to the remote server with arguments behaving similarly to\nthe `cp` command.\n\nWith two arguments, copy _local-file_ to the server as\n_remote-file_.\n\nWith more than two arguments, copy all the local files _lfile1_ ... into\nthe existing remote directory _rdir_ retaining the same basenames. This\nassumes UNIX directory semantics.\n\nA problem arises if you attempt to use `zfpcp` _lfile1_ _rdir_,\ni.e. the second form of copying but with two arguments, as the command has\nno simple way of knowing if _rdir_ corresponds to a directory or a\nfilename. It attempts to resolve this in various ways. First, if the\n_rdir_ argument is \".\" or \"..\" or ends in a slash, it is assumed\nto be a directory. Secondly, if the operation of copying to a remote file\nin the first form failed, and the remote server sends back the expected\nfailure code 553 and a reply including the string \"Is a directory\",\nthen `zfpcp` will retry using the second form."),
("zfclose", "Close the connection."),
("zfsession", "Allows you to manage multiple FTP sessions at once. By default,\nconnections take place in a session called \"default\"; by giving the\ncommand ``zfsession\" _sessname_\" you can change to a new or existing\nsession with a name of your choice. The new session remembers its own\nconnection, as well as associated shell parameters, and also the host/user\nparameters set by `zfparams`. Hence you can have different sessions set\nup to connect to different hosts, each remembering the appropriate host,\nuser and password.\n\nWith no arguments, `zfsession` prints the name of the current session;\nwith the option `-l` it lists all sessions which currently exist, and\nwith the option `-v` it gives a verbose list showing the host and\ndirectory for each session, where the current session is marked with an\nasterisk. With `-o`, it will switch to the most recent previous session.\n\nWith `-d`, the given session (or else the current one) is removed;\neverything to do with it is completely forgotten. If it was the only\nsession, a new session called \"default\" is created and made current.\nIt is safest not to delete sessions while background commands using\n`zftp` are active."),
("zftransfer", "Transfer files between two sessions; no local copy is made. The file\nis read from the session _sess1_ as _file1_ and written to session\n_sess2_ as file _file2_; _file1_ and _file2_ may be relative to\nthe current directories of the session. Either _sess1_ or _sess2_\nmay be omitted (though the colon should be retained if there is a\npossibility of a colon appearing in the file name) and defaults to the\ncurrent session; _file2_ may be omitted or may end with a slash, in\nwhich case the basename of _file1_ will be added. The sessions\n_sess1_ and _sess2_ must be distinct.\n\nThe operation is performed using pipes, so it is required that the\nconnections still be valid in a subshell, which is not the case under\nversions of some operating systems, presumably due to a system bug."),
("zfmark", "If given an argument, mark the current host, user and directory under the\nname _bookmark_ for later use by `zfgoto`. If there is no connection\nopen, use the values for the last connection immediately before it was\nclosed; it is an error if there was none. Any existing bookmark\nunder the same name will be silently replaced.\n\nIf not given an argument, list the existing bookmarks and the points to\nwhich they refer in the form _user_`@`_host_`:`_directory_;\nthis is the format in which they are stored, and the file may be edited\ndirectly."),
("zfgoto", "Return to the location given by _bookmark_, as previously set by\n`zfmark`. If the location has user \"ftp\" or \"anonymous\", open\nthe connection with `zfanon`, so that no password is required. If the\nuser and host parameters match those stored for the current session, if\nany, those will be used, and again no password is required. Otherwise a\npassword will be prompted for.\n\nWith the option `-n`, the bookmark is taken to be a nickname stored by\nthe `ncftp` program in its bookmark file, which is assumed to be\n`~/.ncftp/bookmarks`. The function works identically in other ways.\nNote that there is no mechanism for adding or modifying `ncftp` bookmarks\nfrom the zftp functions."),
("zfinit", "As described above, this is used to initialize the zftp function system.\nThe `-n` option should be used if the zftp command is already built into\nthe shell."),
("zfautocheck", "This function is called to implement automatic reopening behaviour, as\ndescribed in more detail below. The options must appear in the first\nargument; `-n` prevents the command from changing to the old directory,\nwhile `-d` prevents it from setting the variable `do_close`, which it\notherwise does as a flag for automatically closing the connection after a\ntransfer. The host and directory for the last session are stored in the\nvariable `$zflastsession`, but the internal host/user/password parameters\nmust also be correctly set."),
("zfcd_match", "This performs matching for completion of remote directory names. If the\nremote server is UNIX, it will attempt to persuade the server to list the\nremote directory with subdirectories marked, which usually works but is not\nguaranteed. On other hosts it simply calls `zfget_match` and hence\ncompletes all files, not just directories. On some systems, directories\nmay not even look like filenames."),
("zfget_match", "This performs matching for completion of remote filenames. It caches files\nfor the current directory (only) in the shell parameter `$zftp_fcache`.\nIt is in the form to be called by the `-K` option of `compctl`, but\nalso works when called from a widget-style completion function with\n_prefix_ and _suffix_ set appropriately."),
("zfrglob", "Perform remote globbing, as describes in more detail below. _varname_\nis the name of a variable containing the pattern to be expanded; if there\nwere any matches, the same variable will be set to the expanded set of\nfilenames on return."),
("zfrtime", "Set the local file _lfile_ to have the same modification time as the\nremote file _rfile_, or the explicit time _time_ in FTP format\n`CCYYMMDDhhmmSS\" for the GMT timezone. This uses the shell\"s\n`zsh/datetime` module to perform the conversion from\nGMT to local time."),
("zftp_chpwd", "This function is called every time a connection is opened, or closed, or\nthe remote directory changes. This version alters the title bar of an\n`xterm`-compatible or `sun-cmd` terminal emulator to reflect the\nlocal and remote hostnames and current directories. It works best when\ncombined with the function `chpwd`. In particular, a function of\nthe form\n\nexample(chpwd+() {\n if [[ -n $ZFTP_USER ]]; then\n zftp_chpwd\n else\n # usual chpwd e.g put host:directory in title bar\n fi\n})\n\nfits in well."),
("zftp_progress", "This function shows the status of the transfer. It will not write anything\nunless the output is going to a terminal; however, if you transfer files in\nthe background, you should turn off progress reports by hand using\n\"\"zstyle \":zftp:*\" progress none`'. Note also that if you alter it, any\noutput _must_ be to standard error, as standard output may be a file\nbeing received. The form of the progress meter, or whether it is used at\nall, can be configured without altering the function, as described in the\nnext section."),
("zffcache", "This is used to implement caching of files in the current directory for\neach session separately. It is used by `zfget_match` and `zfrglob`."),
("progress", "Controls the way that `zftp_progress` reports on the progress of a\ntransfer. If empty, unset, or \"none\", no progress report is made; if\n\"bar\" a growing bar of inverse video is shown; if \"percent\" (or any\nother string, though this may change in future), the percentage of the file\ntransferred is shown. The bar meter requires that the width of the\nterminal be available via the `$COLUMNS` parameter (normally this is set\nautomatically). If the size of the file being transferred is not\navailable, `bar` and `percent` meters will simply show the number of\nbytes transferred so far.\n\nWhen `zfinit` is run, if this style is not defined for the context\n`:zftp:*`, it will be set to \"bar\"."),
("update", "Specifies the minimum time interval between updates of the progress meter\nin seconds. No update is made unless new data has been received, so the\nactual time interval is limited only by `$ZFTP_TIMEOUT`.\n\nAs described for `progress`, `zfinit` will force this to default to 1."),
("remote", "If set to \"1\", \"yes\" or \"true\", filename generation (globbing) is\nperformed on the remote machine instead of by zsh itself; see below."),
("titlebar", "If set to \"1\", \"yes\" or \"true\", `zftp_chpwd` will put the remote host and\nremote directory into the titlebar of terminal emulators such as xterm or\nsun-cmd that allow this.\n\nAs described for `progress`, `zfinit` will force this to default to 1."),
("chpwd", "If set to \"1\" \"yes\" or \"true\", `zftp_chpwd` will call the function\n`chpwd` when a connection is closed. This is useful if the remote host\ndetails were put into the terminal title bar by `zftp_chpwd` and your\nusual `chpwd` also modifies the title bar.\n\nWhen `zfinit` is run, it will determine whether `chpwd` exists and if\nso it will set the default value for the style to 1 if none exists\nalready."),
("calendar", "Show events in the calendar.\n\nWith no arguments, show events from the start of today until the end of\nthe next working day after today. In other words, if today is Friday,\nSaturday, or Sunday, show up to the end of the following Monday, otherwise\nshow today and tomorrow.\n\nIf _end_ is given, show events from the start of today up to the time\nand date given, which is in the format described in the previous section.\nNote that if this is a date the time is assumed to be midnight at the\nstart of the date, so that effectively this shows all events before\nthe given date.\n\n_end_ may start with a `+`, in which case the remainder of the\nspecification is a relative time format as described in the previous\nsection indicating the range of time from the start time that is to\nbe included.\n\nIf _start_ is also given, show events starting from that time and date.\nThe word `now` can be used to indicate the current time.\n\nTo implement an alert when events are due, include `calendar -s` in your\n`~/.zshrc` file.\n\nOptions:\n\n- **`-a`** âÂÂ\nShow all items in the calendar, regardless of the `start` and\n`end`.\n\n\n- **`-b\"** â Brief: don\"t display continuation lines (i.e. indented lines following\nthe line with the date/time), just the first line.\n)\n\n- **`-B` _lines_** âÂÂ\nBrief: display at most the first _lines_ lines of the calendar\nentry. \"-B 1\" is equivalent to \"-b\".\n\n- **`-C` _calfile_** âÂÂ\nExplicitly specify a calendar file instead of the value of\nthe `calendar-file` style or the default `~/calendar`.\n\n- **`-d`** âÂÂ\nMove any events that have passed from the calendar file to the\n\"done\" file, as given by the `done-file` style or the default\nwhich is the calendar file with `.done` appended. This option\nis implied by the `-s` option.\n\n- **`-D`** âÂÂ\nTurns off the option `-d`, even if the `-s` option is also present.\n\n- **`-n` _num_, `-`_num_** âÂÂ\nShow at least _num_ events, if present in the calendar file, regardless\nof the `start` and `end`.\n\n- **`-r`** âÂÂ\nShow all the remaining options in the calendar, ignoring the given _end_\ntime. The _start_ time is respected; any argument given is treated\nas a _start_ time.\n\n\n- **`-s\"** â Use the shell\"s `sched` command to schedule a timed event that\nwill warn the user when an event is due. Note that the `sched` command\nonly runs if the shell is at an interactive prompt; a foreground task\nblocks the scheduled task from running until it is finished.\n\nThe timed event usually runs the programme `calendar_show` to show\nthe event, as described in _Utility Functions_ (below).\n\nBy default, a warning of the event is shown five minutes before it is due.\nThe warning period can be configured by the style `warn-time` or\nfor a single calendar entry by including `WARN` _reltime_ in the first\nline of the entry, where _reltime_ is one of the usual relative time\nformats.\n\nA repeated event may be indicated by including `RPT` _reldate_ in the\nfirst line of the entry. After the scheduled event has been displayed\nit will be re-entered into the calendar file at a time _reldate_\nafter the existing event. Note that this is currently the only use\nmade of the repeat count, so that it is not possible to query the schedule\nfor a recurrence of an event in the calendar until the previous event\nhas passed.\n\nIf `RPT` is used, it is also possible to specify that certain\nrecurrences of an event are rescheduled or cancelled. This is\ndone with the `OCCURRENCE` keyword, followed by whitespace and the\ndate and time of the occurrence in the regular sequence, followed by\nwhitespace and either the date and time of the rescheduled event or\nthe exact string `CANCELLED`. In this case the date and time must\nbe in exactly the \"date with local time\" format used by the\n`text/calendar` MIME type (RFC 2445),\n_<YYYY><MM><DD>_`T`_<hh><mm><ss>_ (note the presence of the literal\ncharacter `T`). The first word (the regular recurrence) may be\nsomething other than a proper date/time to indicate that the event\nis additional to the normal sequence; a convention that retains\nthe formatting appearance is `XXXXXXXXTXXXXXX`.\n\nFurthermore, it is useful to record the next regular recurrence\n(as then the displayed date may be for a rescheduled event so cannot\nbe used for calculating the regular sequence). This is specified by\n`RECURRENCE` and a time or date in the same format. `calendar_add`\nadds such an indication when it encounters a recurring event that does not\ninclude one, based on the headline date/time.\n\nIf `calendar_add` is used to update occurrences the `UID` keyword\ndescribed there should be present in both the existing entry and the added\noccurrence in order to identify recurring event sequences.\n\nFor example,\n\n Thu May 6, 2010 11:00 Informal chat RPT 1 week\n # RECURRENCE 20100506T110000\n # OCCURRENCE 20100513T110000 20100513T120000\n # OCCURRENCE 20100520T110000 CANCELLED\n\nThe event that occurs at 11:00 on 13th May 2010 is rescheduled an hour\nlater. The event that occurs a week later is cancelled. The occurrences\nare given on a continuation line starting with a `#` character so will\nnot usually be displayed as part of the event. As elsewhere, no account of\ntime zones is taken with the times. After the next event occurs the headline\ndate/time will be \"Thu May 13, 2010 12:00\" while the `RECURRENCE`\ndate/time will be \"20100513T110000\" (note that cancelled and\nmoved events are not taken account of in the `RECURRENCE`, which\nrecords what the next regular recurrence is, but they are accounted for in\nthe headline date/time).\n\nIt is safe to run `calendar -s` to reschedule an existing event\n(if the calendar file has changed, for example), and also to have it\nrunning in multiples instances of the shell since the calendar file\nis locked when in use.\n\nBy default, expired events are moved to the \"done\" file; see the `-d`\noption. Use `-D` to prevent this.\n\n\n- **`-S` _showprog_** âÂÂ\nExplicitly specify a programme to be used for showing events instead\nof the value of the `show-prog` style or the default `calendar_show`.\n\n- **`-v`** âÂÂ\nVerbose: show more information about stages of processing. This\nis useful for confirming that the function has successfully parsed\nthe dates in the calendar file."),
("calendar_add", "Adds a single event to the calendar in the appropriate location.\nThe event can contain multiple lines, as described in\n_File and Date Formats_ (above).\nUsing this function ensures that the calendar file is sorted in date\nand time order. It also makes special arrangements for locking\nthe file while it is altered. The old calendar is left in a file\nwith the suffix `.old`.\n\nThe option `-B` indicates that backing up the calendar file will be\nhandled by the caller and should not be performed by `calendar_add`. The\noption `-L` indicates that `calendar_add` does not need to lock the\ncalendar file as it is already locked. These options will not usually be\nneeded by users.\n\nIf the style `reformat-date` is true, the date and time of the\nnew entry will be rewritten into the standard date format: see\nthe descriptions of this style and the style `date-format`.\n\nThe function can use a unique identifier stored with each event to ensure\nthat updates to existing events are treated correctly. The entry\nshould contain the word `UID`, followed by whitespace, followed by\na word consisting entirely of hexadecimal digits of arbitrary length\n(all digits are significant, including leading zeroes). As the UID\nis not directly useful to the user, it is convenient to hide it on\nan indented continuation line starting with a `#`, for example:\n\n Aug 31, 2007 09:30 Celebrate the end of the holidays\n # UID 045B78A0\n\nThe second line will not be shown by the `calendar` function.\n\nIt is possible to specify the `RPT` keyword followed by `CANCELLED`\ninstead of a relative time. This causes any matched event or series\nof events to be cancelled (the original event does not have to be marked\nas recurring in order to be cancelled by this method). A `UID` is\nrequired in order to match an existing event in the calendar.\n\n`calendar_add` will attempt to manage recurrences and occurrences of\nrepeating events as described for event scheduling by `calendar -s`\nabove. To reschedule or cancel a single event `calendar_add` should be\ncalled with an entry that includes the correct `UID` but does _not_\ninclude the `RPT` keyword as this is taken to mean the entry applies to a\nseries of repeating events and hence replaces all existing information.\nEach rescheduled or cancelled occurrence must have an `OCCURRENCE`\nkeyword in the entry passed to `calendar_add` which will be merged into\nthe calendar file. Any existing reference to the occurrence is replaced.\nAn occurrence that does not refer to a valid existing event is added as a\none-off occurrence to the same calendar entry."),
("calendar_edit", "This calls the user's editor to edit the calendar file. If\nthere are arguments, they are taken as the editor to use (the file name\nis appended to the commands); otherwise, the editor is given by the\nvariable `VISUAL`, if set, else the variable `EDITOR`.\n\nIf the calendar scheduler was running, then after editing the file\n`calendar -s` is called to update it.\n\nThis function locks out the calendar system during the edit.\nHence it should be used to edit the calendar file if there is any\npossibility of a calendar event occurring meanwhile. Note this\ncan lead to another shell with calendar functions enabled hanging waiting\nfor a lock, so it is necessary to quit the editor as soon as possible."),
("calendar_parse", "This is the internal function that analyses the parts of a calendar\nentry, which is passed as the only argument. The function returns\nstatus 1 if the argument could not be parsed as a calendar entry\nand status 2 if the wrong number of arguments were passed; it also sets the\nparameter `reply` to an empty associative array. Otherwise,\nit returns status 0 and sets elements of the associative\narray `reply` as follows:\n\n- `time` â The time as a string of digits in the same units as\n`$EPOCHSECONDS`\n- `schedtime` â The regularly scheduled time. This may differ from\nthe actual event time `time` if this is a recurring event and the next\noccurrence has been rescheduled. Then `time` gives the actual time\nand `schedtime` the time of the regular recurrence before modification.\n- `text1` â The text from the line not including the date and time of the\nevent, but including any `WARN` or `RPT` keywords and values.\n\n- **`warntime`** â Any warning time given by the `WARN` keyword as a string\nof digits containing the time at which to warn in the same units as\n`$EPOCHSECONDS`. (Note this is an absolute time, not the relative time\npassed down.) Not set no `WARN` keyword and value were\nmatched.\n\n- `warnstr` â The raw string matched after the `WARN` keyword, else unset.\n\n- **`rpttime`** â Any recurrence time given by the `RPT` keyword as a string\nof digits containing the time of the recurrence in the same units\nas `$EPOCHSECONDS`. (Note this is an absolute time.) Not set if\nno `RPT` keyword and value were matched.\n\n- `schedrpttime` â The next regularly scheduled occurrence of a recurring\nevent before modification. This may differ from `rpttime`, which is the\nactual time of the event that may have been rescheduled from the regular\ntime.\n- `rptstr` â The raw string matched after the `RPT` keyword, else unset.\n- `text2` â The text from the line after removal of the date and any\nkeywords and values."),
("calendar_showdate", "The given _date-spec_ is interpreted and the corresponding date and\ntime printed. If the initial _date-spec_ begins with a `+` or\n`-` it is treated as relative to the current time; _date-spec_s after\nthe first are treated as relative to the date calculated so far and\na leading `+` is optional in that case. This allows one to\nuse the system as a date calculator. For example, \"calendar_showdate \"+1\nmonth, 1st Friday'` shows the date of the first Friday of next month.\n\nWith the option `-r` nothing is printed but the value of the date and\ntime in seconds since the epoch is stored in the parameter `REPLY`.\n\nWith the option `-f` _fmt_ the given date/time conversion format\nis passed to `strftime`; see notes on the `date-format` style below.\n\nIn order to avoid ambiguity with negative relative date specifications,\noptions must occur in separate words; in other words, `-r` and `-f`\nshould not be combined in the same word."),
("calendar_sort", "Sorts the calendar file into date and time order. The old calendar is\nleft in a file with the suffix `.old`."),
("age", "findex(age)\nThe function `age` can be autoloaded and use separately from\nthe calendar system, although it uses the function `calendar_scandate`\nfor date formatting. It requires the `zsh/stat` builtin, but uses\nonly the builtin `zstat`.\n\n`age` selects files having a given modification time for use\nas a glob qualifier. The format of the date is the same as that\nunderstood by the calendar system, described in\n_File and Date Formats_ (above).\n\nThe function can take one or two arguments, which can be supplied either\ndirectly as command or arguments, or separately as shell parameters.\n\nexample(print *+(e:age 2006/10/04 2006/10/09:+))\n\nThe example above matches all files modified between the start of those\ndates. The second argument may alternatively be a relative time\nintroduced by a `+`:\n\nexample(print *+(e:age 2006/10/04 +5d:+))\n\nThe example above is equivalent to the previous example.\n\nIn addition to the special use of days of the week, `today` and\n`yesterday`, times with no date may be specified; these apply to today.\nObviously such uses become problematic around midnight.\n\nexample(print *+(e-age 12:00 13:30-+))\n\nThe example above shows files modified between 12:00 and 13:00 today.\n\nexample(print *+(e:age 2006/10/04:+))\n\nThe example above matches all files modified on that date. If the second\nargument is omitted it is taken to be exactly 24 hours after the first\nargument (even if the first argument contains a time).\n\nexample(print *+(e-age 2006/10/04:10:15 2006/10/04:10:45-))\n\nThe example above supplies times. Note that whitespace within the time and\ndate specification must be quoted to ensure `age` receives the correct\narguments, hence the use of the additional colon to separate the date and\ntime.\n\nexample(AGEREF=2006/10/04:10:15\nAGEREF2=2006/10/04:10:45\nprint *+(+age+))\n\nThis shows the same example before using another form of argument\npassing. The dates and times in the parameters `AGEREF` and `AGEREF2`\nstay in effect until unset, but will be overridden if any argument is\npassed as an explicit argument to age. Any explicit argument\ncauses both parameters to be ignored.\n\nInstead of an explicit date and time, it's possible to use the\nmodification time of a file as the date and time for either argument\nby introducing the file name with a colon:\n\nexample(print *+(e-age :file1-+))\n\nmatches all files created on the same day (24 hours starting from\nmidnight) as `file1`.\n\nexample(print *+(e-age :file1 :file2-+))\n\nmatches all files modified no earlier than `file1` and\nno later than `file2`; precision here is to the nearest second."),
("before", "findex(after)\nfindex(before)\nThe functions `after` and `before` are simpler versions of `age`\nthat take just one argument. The argument is parsed similarly to an\nargument of `age`; if it is not given the variable `AGEREF` is\nconsulted. As the names of the functions suggest, a file matches if its\nmodification time is after or before the time and date specified. If\na time only is given the date is today.\n\nThe two following examples are therefore equivalent:\nexample(print *+(e-after 12:00-)\nprint *+(e-after today:12:00-))"),
("calendar", "The location of the main calendar. The default is `~/calendar`."),
("date", "A `strftime` format string (see manref(strftime)(3)) with the zsh\nextensions providing various numbers with no leading zero or space\nif the number is a single digit as described for the\n`%D{`_string_`}` prompt format in\n_Simple Prompt Escapes_ (zshmisc).\n\nThis is used for outputting dates in `calendar`, both to support\nthe `-v` option and when adding recurring events back to the calendar\nfile, and in `calendar_showdate` as the final output format.\n\nIf the style is not set, the default used is similar the standard system\nformat as output by the `date` command (also known as \"ctime format\"):\n\"%a %b %d %H:%M:%S %Z %Y\"."),
("done", "The location of the file to which events which have passed are appended.\nThe default is the calendar file location with the suffix `.done`.\nThe style may be set to an empty string in which case a \"done\" file\nwill not be maintained."),
("reformat", "Boolean, used by `calendar_add`. If it is true, the date and time\nof new entries added to the calendar will be reformatted to the format\ngiven by the style `date-format` or its default. Only the date and\ntime of the event itself is reformatted; any subsidiary dates and times\nsuch as those associated with repeat and warning times are left alone."),
("show", "The programme run by `calendar` for showing events. It will\nbe passed the start time and stop time of the events requested in seconds\nsince the epoch followed by the event text. Note that `calendar -s` uses\na start time and stop time equal to one another to indicate alerts\nfor specific events.\n\nThe default is the function `calendar_show`."),
("warn", "The time before an event at which a warning will be displayed, if the\nfirst line of the event does not include the text `EVENT` _reltime_.\nThe default is 5 minutes."),
("calendar_lockfiles", "Attempt to lock the files given in the argument. To prevent\nproblems with network file locking this is done in an ad hoc fashion\nby attempting to create a symbolic link to the file with the name\n_file_`.lockfile`. No other system level functions are used\nfor locking, i.e. the file can be accessed and modified by any\nutility that does not use this mechanism. In particular, the user is not\nprevented from editing the calendar file at the same time unless\n`calendar_edit` is used.\n\nThree attempts are made to lock the file before giving up. If the module\n`zsh/zselect` is available, the times of the attempts are jittered so that\nmultiple instances of the calling function are unlikely to retry at the\nsame time.\n\nThe files locked are appended to the array `lockfiles`, which should\nbe local to the caller.\n\nIf all files were successfully locked, status zero is returned, else status one.\n\nThis function may be used as a general file locking function, although\nthis will only work if only this mechanism is used to lock files."),
("calendar_read", "This is a backend used by various other functions to parse the\ncalendar file, which is passed as the only argument. The array\n`calendar_entries` is set to the list of events in the file; no\npruning is done except that ampersands are removed from the start of\nthe line. Each entry may contain multiple lines."),
("calendar_scandate", "This is a generic function to parse dates and times that may be\nused separately from the calendar system. The argument is a date\nor time specification as described in _File and Date Formats_ (above).\nThe parameter `REPLY`\nis set to the number of seconds since the epoch corresponding to that date\nor time. By default, the date and time may occur anywhere within the given\nargument.\n\nReturns status zero if the date and time were successfully parsed,\nelse one.\n\nOptions:\n\n- **`-a`** âÂÂ\nThe date and time are anchored to the start of the argument; they\nwill not be matched if there is preceding text.\n\n- **`-A`** âÂÂ\nThe date and time are anchored to both the start and end of the argument;\nthey will not be matched if the is any other text in the argument.\n\n- **`-d`** âÂÂ\nEnable additional debugging output.\n\n- **`-m`** âÂÂ\nMinus. When `-R` _anchor_time_ is also given the relative time is\ncalculated backwards from _anchor_time_.\n\n- **`-r`** âÂÂ\nThe argument passed is to be parsed as a relative time.\n\n- **`-R` _anchor_time_** âÂÂ\nThe argument passed is to be parsed as a relative time. The time is\nrelative to _anchor_time_, a time in seconds since the epoch,\nand the returned value is the absolute time corresponding to advancing\n_anchor_time_ by the relative time given.\nThis allows lengths of months to be correctly taken into account. If\nthe final day does not exist in the given month, the last day of the\nfinal month is given. For example, if the anchor time is during 31st\nJanuary 2007 and the relative time is 1 month, the final time is the\nsame time of day during 28th February 2007.\n\n- **`-s`** âÂÂ\nIn addition to setting `REPLY`, set `REPLY2` to the remainder of\nthe argument after the date and time have been stripped. This is\nempty if the option `-A` was given.\n\n- **`-t`** âÂÂ\nAllow a time with no date specification. The date is assumed to be\ntoday. The behaviour is unspecified if the iron tongue of midnight\nis tolling twelve."),
("calendar_show", "The function used by default to display events. It accepts a start time\nand end time for events, both in epoch seconds, and an event description.\n\nThe event is always printed to standard output. If the command line editor\nis active (which will usually be the case) the command line will be\nredisplayed after the output.\n\nIf the parameter `DISPLAY` is set and the start and end times are\nthe same (indicating a scheduled event), the function uses the\ncommand `xmessage` to display a window with the event details."),
("tcp_open", "Open a new session. In the first and simplest form, open a TCP connection\nto host _host_ at port _port_; numeric and symbolic forms are\nunderstood for both.\n\nIf _sess_ is given, this becomes the name of the session which can be\nused to refer to multiple different TCP connections. If _sess_ is\nnot given, the function will invent a numeric name value (note this is\n_not_ the same as the file descriptor to which the session is attached).\nIt is recommended that session names not include \"funny\" characters, where\nfunny characters are not well-defined but certainly do not include\nalphanumerics or underscores, and certainly do include whitespace.\n\nIn the second case, one or more sessions to be opened are given by name.\nA single session name is given after `-s` and a comma-separated list\nafter `-l`; both options may be repeated as many times as necessary.\nA failure to open any session causes `tcp_open` to abort.\nThe host and port are read from the file `.ztcp_sessions` in the same\ndirectory as the user's zsh initialisation files, i.e. usually the home\ndirectory, but `$ZDOTDIR` if that is set. The file consists of lines\neach giving a session name and the corresponding host and port, in that\norder (note the session name comes first, not last), separated by\nwhitespace.\n\nThe third form allows passive and fake TCP connections. If the option\n`-a` is used, its argument is a file descriptor open for listening for\nconnections. No function front-end is provided to open such a file\ndescriptor, but a call to ``ztcp -l\" _port_\" will create one with the\nfile descriptor stored in the parameter `$REPLY`. The listening port can\nbe closed with ``ztcp -c\" _fd_\". A call to ``tcp_open -a\" _fd_\"\nwill block until a remote TCP connection is made to _port_ on the local\nmachine. At this point, a session is created in the usual way and is\nlargely indistinguishable from an active connection created with one of the\nfirst two forms.\n\nIf the option `-f` is used, its argument is a file descriptor which is\nused directly as if it were a TCP session. How well the remainder of the\nTCP function system copes with this depends on what actually underlies this\nfile descriptor. A regular file is likely to be unusable; a FIFO (pipe) of\nsome sort will work better, but note that it is not a good idea for two\ndifferent sessions to attempt to read from the same FIFO at once.\n\nIf the option `-q` is given with any of the three forms, `tcp_open`\nwill not print informational messages, although it will in any case exit\nwith an appropriate status.\n\nIf the line editor (zle) is in use, which is typically the case if the\nshell is interactive, `tcp_open` installs a handler inside zle which\nwill check for new data at the same time as it checks for keyboard input.\nThis is convenient as the shell consumes no CPU time while waiting; the\ntest is performed by the operating system. Giving the option `-z` to\nany of the forms of `tcp_open` prevents the handler from being\ninstalled, so data must be read explicitly. Note, however, this is not\nnecessary for executing complete sets of send and read commands from a\nfunction, as zle is not active at this point. Generally speaking, the\nhandler is only active when the shell is waiting for input at a command\nprompt or in the `vared` builtin. The option has no effect if zle is not\nactive; \"[[ -o zle]]\" will test for this.\n\nThe first session to be opened becomes the current session and subsequent\ncalls to `tcp_open` do not change it. The current session is stored\nin the parameter `$TCP_SESS`; see below for more detail about the\nparameters used by the system.\n\nThe function `tcp_on_open`, if defined, is called when a session\nis opened. See the description below."),
("tcp_close", "Close the named sessions, or the current session if none is given,\nor all open sessions if `-a` is given. The options `-l` and `-s` are\nboth handled for consistency with `tcp_open`, although the latter is\nredundant.\n\nIf the session being closed is the current one, `$TCP_SESS` is unset,\nleaving no current session, even if there are other sessions still open.\n\nIf the session was opened with `tcp_open -f`, the file descriptor is\nclosed so long as it is in the range 0 to 9 accessible directly from the\ncommand line. If the option `-n` is given, no attempt will be made to\nclose file descriptors in this case. The `-n` option is not used for\ngenuine `ztcp` session; the file descriptors are always closed with the\nsession.\n\nIf the option `-q` is given, no informational messages will be printed."),
("tcp_read", "Perform a read operation on the current session, or on a list of\nsessions if any are given with `-u`, `-l` or `-s`, or all open\nsessions if the option `-a` is given. Any of the `-u`, `-l` or\n`-s` options may be repeated or mixed together. The `-u` option\nspecifies a file descriptor directly (only those managed by this system\nare useful), the other two specify sessions as described for\n`tcp_open` above.\n\nThe function checks for new data available on all the sessions listed.\nUnless the `-b` option is given, it will not block waiting for new data.\nAny one line of data from any of the available sessions will be read,\nstored in the parameter `$TCP_LINE`, and displayed to standard output\nunless `$TCP_SILENT` contains a non-empty string. When printed to\nstandard output the string `$TCP_PROMPT` will be shown at the start of\nthe line; the default form for this includes the name of the session being\nread. See below for more information on these parameters. In this mode,\n`tcp_read` can be called repeatedly until it returns status 2 which\nindicates all pending input from all specified sessions has been handled.\n\nWith the option `-b`, equivalent to an infinite timeout, the function\nwill block until a line is available to read from one of the specified\nsessions. However, only a single line is returned.\n\nThe option `-d` indicates that all pending input should be drained. In\nthis case `tcp_read` may process multiple lines in the manner given\nabove; only the last is stored in `$TCP_LINE`, but the complete set is\nstored in the array `$tcp_lines`. This is cleared at the start of each\ncall to `tcp_read`.\n\nThe options `-t` and `-T` specify a timeout in seconds, which may be a\nfloating point number for increased accuracy. With `-t` the timeout is\napplied before each line read. With `-T`, the timeout applies to the\noverall operation, possibly including multiple read operations if the\noption `-d` is present; without this option, there is no distinction\nbetween `-t` and `-T`.\n\nThe function does not print informational messages, but if the option\n`-q` is given, no error message is printed for a non-existent session.\n\nA return status of 2 indicates a timeout or no data to read. Any other\nnon-zero return status indicates some error condition.\n\nSee `tcp_log` for how to control where data is sent by `tcp_read`."),
("tcp_send", "Send the supplied data strings to all the specified sessions in turn. The\nunderlying operation differs little from a \"print -r\" to the session's\nfile descriptor, although it attempts to prevent the shell from dying owing\nto a `SIGPIPE` caused by an attempt to write to a defunct session.\n\nThe option `-c` causes `tcp_send` to behave like `cat`. It reads\nlines from standard input until end of input and sends them in turn to the\nspecified session+(s+) exactly as if they were given as _data_\narguments to individual `tcp_send` commands.\n\nThe option `-n` prevents `tcp_send` from putting a newline at the end\nof the data strings.\n\nThe remaining options all behave as for `tcp_read`.\n\nThe data arguments are not further processed once they have been passed to\n`tcp_send`; they are simply passed down to `print -r`.\n\nIf the parameter `$TCP_OUTPUT` is a non-empty string and logging is\nenabled then the data sent to each session will be echoed to the log\nfile+(s+) with `$TCP_OUTPUT` in front where appropriate, much\nin the manner of `$TCP_PROMPT`."),
("tcp_alias", "This function is not particularly well tested.\n\nThe first form creates an alias for a session name; _alias_ can then be\nused to refer to the existing session _sess_. As many aliases may be\nlisted as required.\n\nThe second form lists any aliases specified, or all aliases if none.\n\nThe third form deletes all the aliases listed. The underlying sessions are\nnot affected.\n\nThe option `-q` suppresses an inconsistently chosen subset of error\nmessages."),
("tcp_log", "With an argument _logfile_, all future input from `tcp_read` will be\nlogged to the named file. Unless `-a` (append) is given, this file will\nfirst be truncated or created empty. With no arguments, show the current\nstatus of logging.\n\nWith the option `-s`, per-session logging is enabled. Input from\n`tcp_read` is output to the file _logfile_`.`_sess_. As the\nsession is automatically discriminated by the filename, the contents are\nraw (no `$TCP_PROMPT`). The option `-a` applies as above.\nPer-session logging and logging of all data in one file are not mutually\nexclusive.\n\nThe option `-c` closes all logging, both complete and per-session logs.\n\nThe options `-n` and `-N` respectively turn off or restore output of\ndata read by `tcp_read` to standard output; hence \"tcp_log -cn\" turns\noff all output by `tcp_read`.\n\nThe function is purely a convenient front end to setting the parameters\n`$TCP_LOG`, `$TCP_LOG_SESS`, `$TCP_SILENT`, which are described below."),
("tcp_rename", "Rename session _old_ to session _new_. The old name becomes invalid."),
("tcp_sess", "With no arguments, list all the open sessions and associated file\ndescriptors. The current session is marked with a star. For use in\nfunctions, direct access to the parameters `$tcp_by_name`, `$tcp_by_fd`\nand `$TCP_SESS` is probably more convenient; see below.\n\nWith a _sess_ argument, set the current session to _sess_.\nThis is equivalent to changing `$TCP_SESS` directly.\n\nWith additional arguments, temporarily set the current session while\nexecuting \"_command_ _arg_ ...\". _command_ is re-evaluated\nso as to expand aliases etc., but the remaining _arg_s are passed\nthrough as that appear to `tcp_sess`. The original session is restored\nwhen `tcp_sess` exits."),
("tcp_command", "This is a convenient front-end to `tcp_send`. All arguments are passed\nto `tcp_send`, then the function pauses waiting for data. While data is\narriving at least every `$TCP_TIMEOUT` (default 0.3) seconds, data is\nhandled and printed out according to the current settings. Status 0 is\nalways returned.\n\nThis is generally only useful for interactive use, to prevent the display\nbecoming fragmented by output returned from the connection. Within a\nprogramme or function it is generally better to handle reading data by a\nmore explicit method."),
("tcp_expect", "Wait for input matching any of the given _pattern_s from any of the\nspecified sessions. Input is ignored until an input line matches one of\nthe given patterns; at this point status zero is returned, the matching\nline is stored in `$TCP_LINE`, and the full set of lines read during the\ncall to `tcp_expect` is stored in the array `$tcp_expect_lines`.\n\nSessions are specified in the same way as `tcp_read`: the default is to\nuse the current session, otherwise the sessions specified by `-a`,\n`-s`, or `-l` are used.\n\nEach _pattern_ is a standard zsh extended-globbing pattern; note that it\nneeds to be quoted to avoid it being expanded immediately by filename\ngeneration. It must match the full line, so to match a substring there\nmust be a \"*\" at the start and end. The line matched against includes\nthe `$TCP_PROMPT` added by `tcp_read`. It is possible to include the\nglobbing flags \"#b\" or \"#m\" in the patterns to make backreferences\navailable in the parameters `$MATCH`, `$match`, etc., as described in\nthe base zsh documentation on pattern matching.\n\nUnlike `tcp_read`, the default behaviour of `tcp_expect` is to block\nindefinitely until the required input is found. This can be modified by\nspecifying a timeout with `-t` or `-T`; these function as in\n`tcp_read`, specifying a per-read or overall timeout, respectively, in\nseconds, as an integer or floating-point number. As `tcp_read`, the\nfunction returns status 2 if a timeout occurs.\n\nThe function returns as soon as any one of the patterns given match. If\nthe caller needs to know which of the patterns matched, the option `-p`\n_var_ can be used; on return, `$var` is set to the number of the\npattern using ordinary zsh indexing, i.e. the first is 1, and so on. Note\nthe absence of a \"$\" in front of _var_. To avoid clashes, the\nparameter cannot begin with \"_expect\". The index -1 is used if\nthere is a timeout and 0 if there is no match.\n\nThe option `-P` _var_ works similarly to `-p`, but instead of\nnumerical indexes the regular arguments must begin with a prefix\nfollowed by a colon: that prefix is then used as a tag to which _var_\nis set when the argument matches. The tag `timeout` is used if there\nis a timeout and the empty string if there is no match. Note it is\nacceptable for different arguments to start with the same prefix if the\nmatches do not need to be distinguished.\n\nThe option `-q` is passed directly down to `tcp_read`.\n\nAs all input is done via `tcp_read`, all the usual rules about output of\nlines read apply. One exception is that the parameter `$tcp_lines` will\nonly reflect the line actually matched by `tcp_expect`; use\n`$tcp_expect_lines` for the full set of lines read during the function\ncall."),
("tcp_proxy", "This is a simple-minded function to accept a TCP connection and execute a\ncommand with I/O redirected to the connection. Extreme caution should be\ntaken as there is no security whatsoever and this can leave your computer\nopen to the world. Ideally, it should only be used behind a firewall.\n\nThe first argument is a TCP port on which the function will listen.\n\nThe remaining arguments give a command and its arguments to execute with\nstandard input, standard output and standard error redirected to the\nfile descriptor on which the TCP session has been accepted.\nIf no command is given, a new zsh is started. This gives everyone on\nyour network direct access to your account, which in many cases will be a\nbad thing.\n\nThe command is run in the background, so `tcp_proxy` can then accept new\nconnections. It continues to accept new connections until interrupted."),
("tcp_spam", "Execute \"_cmd_ [ _arg_ ... ]\" for each session in turn. Note this executes\nthe command and arguments; it does not send the command line as data\nunless the `-t` (transmit) option is given.\n\nThe sessions may be selected explicitly with the standard `-a`, `-s` or\n`-l` options, or may be chosen implicitly. If none of the three options\nis given the rules are: first, if the array `$tcp_spam_list` is set, this\nis taken as the list of sessions, otherwise all sessions are taken.\nSecond, any sessions given in the array `$tcp_no_spam_list` are removed\nfrom the list of sessions.\n\nNormally, any sessions added by the \"-a\" flag or when all sessions are\nchosen implicitly are spammed in alphabetic order; sessions given by the\n`$tcp_spam_list` array or on the command line are spammed in the order\ngiven. The `-r` flag reverses the order however it was arrived it.\n\nThe `-v` flag specifies that a `$TCP_PROMPT` will be output before each\nsession. This is output after any modification to `TCP_SESS` by the\nuser-defined `tcp_on_spam` function described below. (Obviously that\nfunction is able to generate its own output.)\n\nIf the option `-e` is present, the line given as \"_cmd_ [ _arg_ ... ]\" is executed\nusing `eval`, otherwise it is executed without any further processing."),
("tcp_talk", "This is a fairly simple-minded attempt to force input to the line editor to\ngo straight to the default `TCP_SESS`.\n\nAn escape string, `$TCP_TALK_ESCAPE`, default \":\", is used to allow\naccess to normal shell operation. If it is on its own at the start of the\nline, or followed only by whitespace, the line editor returns to normal\noperation. Otherwise, the string and any following whitespace are skipped\nand the remainder of the line executed as shell input without any change of\nthe line editor's operating mode.\n\nThe current implementation is somewhat deficient in terms of use of the\ncommand history. For this reason, many users will prefer to use some form\nof alternative approach for sending data easily to the current session.\nOne simple approach is to alias some special character (such as \"%\") to\n``tcp_command -\"-\"."),
("tcp_wait", "The sole argument is an integer or floating point number which gives the\nseconds to delay. The shell will do nothing for that period except wait\nfor input on all TCP sessions by calling `tcp_read -a`. This is similar\nto the interactive behaviour at the command prompt when zle handlers are\ninstalled."),
("tcp_shoot", "This pair of functions provide a simple way to transfer a file between\ntwo hosts within the shell. Note, however, that bulk data transfer is\ncurrently done using `cat`. `tcp_point` reads any data arriving at\n_port_ and sends it to standard output; `tcp_shoot` connects to\n_port_ on _host_ and sends its standard input. Any unused _port_\nmay be used; the standard mechanism for picking a port is to think of a\nrandom four-digit number above 1024 until one works.\n\nTo transfer a file from host `woodcock` to host `springes`, on\n`springes`:\n\n tcp_point 8091 >output_file\n\nand on `woodcock`:\n\n tcp_shoot springes 8091 <input_file\n\nAs these two functions do not require `tcp_open` to set up a TCP\nconnection first, they may need to be autoloaded separately."),
("tcp_on_alias", "When an alias is defined, this function will be called with two arguments:\nthe name of the alias, and the file descriptor of the corresponding session."),
("tcp_on_awol", "If the function `tcp_fd_handler` is handling input from the line\neditor and detects that the file descriptor is no longer reusable,\nby default it removes it from the list of file descriptors handled\nby this method and prints a message. If the function `tcp_on_awol`\nis defined it is called immediately before this point. It may\nreturn status 100, which indicates that the normal handling should\nstill be performed; any other return status indicates that no further\naction should be taken and the `tcp_fd_handler` should return\nimmediately with the given status. Typically the action of `tcp_on_awol`\nwill be to close the session.\n\nThe variable `TCP_INVALIDATE_ZLE` will be a non-empty string if it is\nnecessary to invalidate the line editor display using \"zle -I\" before\nprinting output from the function.\n\n(\"AWOL\" is military jargon for \"absent without leave\" or some\nvariation. It has no pre-existing technical meaning known to the author.)"),
("tcp_on_close", "This is called with the name of a session being closed and the file\ndescriptor which corresponded to that session. Both will be invalid by\nthe time the function is called."),
("tcp_on_open", "This is called after a new session has been defined with the session name\nand file descriptor as arguments. If it returns a non-zero status,\nopening the session is assumed to fail and the session is closed\nagain; however, `tcp_open` will continue to attempt to open any\nremaining sessions given on the command line."),
("tcp_on_rename", "This is called after a session has been renamed with the three arguments\nold session name, file descriptor, new session name."),
("tcp_on_spam", "This is called once for each session spammed, just _before_ a command is\nexecuted for a session by `tcp_spam`. The arguments are the session name\nfollowed by the command list to be executed. If `tcp_spam` was called\nwith the option `-t`, the first command will be `tcp_send`.\n\nThis function is called after `$TCP_SESS` is set to reflect the session\nto be spammed, but before any use of it is made. Hence it is possible to\nalter the value of `$TCP_SESS` within this function. For example, the\nsession arguments to `tcp_spam` could include extra information to be\nstripped off and processed in `tcp_on_spam`.\n\nIf the function sets the parameter `$REPLY` to \"done\", the command\nline is not executed; in addition, no prompt is printed for the `-v`\noption to `tcp_spam`."),
("tcp_on_unalias", "This is called with the name of an alias and the corresponding session's\nfile descriptor after an alias has been deleted."),
("tcp_fd_handler", "This is the function installed by `tcp_open` for handling input from\nwithin the line editor, if that is required. It is in the format\ndocumented for the builtin \"zle -F\" in _Zle Builtins_ (zshzle).\n\nWhile active, the function sets the parameter `TCP_HANDLER_ACTIVE` to 1.\nThis allows shell code called internally (for example, by setting\n`tcp_on_read`) to tell if is being called when the shell is otherwise\nidle at the editor prompt."),
("tcp_output", "This function is used for both logging and handling output to standard\noutput, from within `tcp_read` and (if `$TCP_OUTPUT` is set)\n`tcp_send`.\n\nThe _prompt_ to use is specified by `-P`; the default is the empty\nstring. It can contain:\n\n\n- **`%c`** â Expands to 1 if the session is the current session, otherwise 0. Used\nwith ternary expressions such as \"tt(%(c.-.+))\" to\noutput \"+\" for the current session and \"-\" otherwise.\n\n\n- **`%f`** âÂÂ\nReplaced by the session's file descriptor.\n\n- **`%s`** âÂÂ\nReplaced by the session name.\n\n- **`%%`** âÂÂ\nReplaced by a single \"%\".\n\nThe option `-q` suppresses output to standard output, but not to any log\nfiles which are configured.\n\nThe `-S` and `-F` options are used to pass in the session name and file\ndescriptor for possible replacement in the prompt."),
("tcp_expect_lines", "Array. The set of lines read during the last call to `tcp_expect`,\nincluding the last (`$TCP_LINE`)."),
("tcp_filter", "Array. May be set directly. A set of extended globbing patterns which,\nif matched in `tcp_output`, will cause the line not to be printed to\nstandard output. The patterns should be defined as described for the\narguments to `tcp_expect`. Output of line to log files is not affected."),
("TCP_HANDLER_ACTIVE", "Scalar. Set to 1 within `tcp_fd_handler` to indicate to functions\ncalled recursively that they have been called during an editor session.\nOtherwise unset."),
("TCP_LINE", "The last line read by `tcp_read`, and hence also `tcp_expect`."),
("TCP_LINE_FD", "The file descriptor from which `$TCP_LINE` was read.\n`${tcp_by_fd[$TCP_LINE_FD]}` will give the corresponding session name."),
("tcp_lines", "Array. The set of lines read during the last call to `tcp_read`,\nincluding the last (`$TCP_LINE`)."),
("TCP_LOG", "May be set directly, although it is also controlled by `tcp_log`.\nThe name of a file to which output from all sessions will be sent.\nThe output is proceeded by the usual `$TCP_PROMPT`. If it is not an\nabsolute path name, it will follow the user's current directory."),
("TCP_LOG_SESS", "May be set directly, although it is also controlled by `tcp_log`.\nThe prefix for a set of files to which output from each session separately\nwill be sent; the full filename is `${TCP_LOG_SESS}.`_sess_.\nOutput to each file is raw; no prompt is added. If it is not an absolute\npath name, it will follow the user's current directory."),
("tcp_no_spam_list", "Array. May be set directly. See `tcp_spam` for how this is used."),
("TCP_OUTPUT", "May be set directly. If a non-empty string, any data sent to a session by\n`tcp_send` will be logged. This parameter gives the prompt to be used\nin a file specified by `$TCP_LOG` but not in a file generated from\n`$TCP_LOG_SESS`. The prompt string has the same format as\n`TCP_PROMPT` and the same rules for its use apply."),
("TCP_PROMPT", "May be set directly. Used as the prefix for data read by `tcp_read`\nwhich is printed to standard output or to the log file given by\n`$TCP_LOG`, if any. Any \"%s\", \"%f\" or \"%%\" occurring in the\nstring will be replaced by the name of the session, the session's\nunderlying file descriptor, or a single \"%\", respectively. The\nexpression \"%c\" expands to 1 if the session being read is the current\nsession, else 0; this is most useful in ternary expressions such as\n\"tt(%(c.-.+))\" which outputs \"+\" if the session is\nthe current one, else \"-\".\n\nIf the prompt starts with `%P`, this is stripped and the complete\nresult of the previous stage is passed through standard prompt `%`-style\nformatting before being output."),
("TCP_READ_DEBUG", "May be set directly. If this has non-zero length, `tcp_read` will give\nsome limited diagnostics about data being read."),
("TCP_SECONDS_START", "This value is created and initialised to zero by tcp_open.\n\nThe functions `tcp_read` and `tcp_expect\" use the shell\"s\n`SECONDS` parameter for their own timing purposes. If that parameter\nis not of floating point type on entry to one of the functions, it will\ncreate a local parameter `SECONDS` which is floating point and set the\nparameter `TCP_SECONDS_START` to the previous value of `$SECONDS`.\nIf the parameter is already floating point, it is used without a local\ncopy being created and `TCP_SECONDS_START` is not set. As the global\nvalue is zero, the shell elapsed time is guaranteed to be the sum of\n`$SECONDS` and `$TCP_SECONDS_START`.\n\nThis can be avoided by setting `SECONDS` globally to a floating point\nvalue using \"typeset -F SECONDS\"; then the TCP functions will never\nmake a local copy and never set `TCP_SECONDS_START` to a non-zero value."),
("TCP_SESS", "May be set directly. The current session; must refer to one of the\nsessions established by `tcp_open`."),
("TCP_SILENT", "May be set directly, although it is also controlled by `tcp_log`.\nIf of non-zero length, data read by `tcp_read` will not be written to\nstandard output, though may still be written to a log file."),
("tcp_spam_list", "Array. May be set directly. See the description of the function\n`tcp_spam` for how this is used."),
("TCP_TALK_ESCAPE", "May be set directly. See the description of the function `tcp_talk` for\nhow this is used."),
("TCP_TIMEOUT", "May be set directly. Currently this is only used by the function\n`tcp_command`, see above."),
("tcp_on_read", "This should be an associative array; if it is not, the behaviour is\nundefined. Each key is the name of a shell function or other command,\nand the corresponding value is a shell pattern (using `EXTENDED_GLOB`).\nEvery line read from a TCP session directly or indirectly using\n`tcp_read` (which includes lines read by `tcp_expect`) is compared\nagainst the pattern. If the line matches, the command given in the key is\ncalled with two arguments: the name of the session from which the line was\nread, and the line itself.\n\nIf any function called to handle a line returns a non-zero status, the\nline is not output. Thus a `tcp_on_read` handler containing only\nthe instruction \"return 1\" can be used to suppress output of\nparticular lines (see, however, `tcp_filter` above). However, the line\nis still stored in `TCP_LINE` and `tcp_lines`; this occurs after all\n`tcp_on_read` processing."),
("tcp_aliases", "Associative array. The keys are the names of sessions established with\n`tcp_open`; each value is a space-separated list of aliases which refer\nto that session."),
("tcp_by_fd", "Associative array. The keys are session file descriptors; each\nvalue is the name of that session."),
("tcp_by_name", "Associative array. The keys are the names of sessions; each value is the\nfile descriptor associated with that session."),
("zgetattr", "Get the extended attribute _attribute_ from the specified\n_filename_. If the optional argument _parameter_ is given, the\nattribute is set on that parameter instead of being printed to stdout."),
("zsetattr", "Set the extended attribute _attribute_ on the specified\n_filename_ to _value_."),
("zdelattr", "Remove the extended attribute _attribute_ from the specified\n_filename_."),
("zlistattr", "List the extended attributes currently set on the specified\n_filename_. If the optional argument _parameter_ is given, the\nlist of attributes is set on that parameter instead of being printed to stdout."),
("cap", "Change the shell's process capability sets to the specified _capabilities_,\notherwise display the shell's current capabilities."),
("getcap", "This is a built-in implementation of the POSIX standard utility. It displays\nthe capability sets on each specified _filename_."),
("setcap", "This is a built-in implementation of the POSIX standard utility. It sets\nthe capability sets on each specified _filename_ to the specified\n_capabilities_."),
("clone", "Creates a forked instance of the current shell, attached to the specified\n_tty_. In the new shell, the `PID`, `PPID` and `TTY` special\nparameters are changed appropriately. `$!` is set to zero in the new\nshell, and to the new shell's PID in the original shell.\n\nThe return status of the builtin is zero in both shells if successful,\nand non-zero on error.\n\nThe target of `clone` should be an unused terminal, such as an unused virtual\nconsole or a virtual terminal created by\n\n xterm -e sh -c 'trap : INT QUIT TSTP; tty;\n while :; do sleep 100000000; done'\n\nSome words of explanation are warranted about this long xterm command\nline: when doing clone on a pseudo-terminal, some other session\n(\"session\" meant as a unix session group, or SID) is already owning\nthe terminal. Hence the cloned zsh cannot acquire the pseudo-terminal\nas a controlling tty. That means two things:\n\nstartitemize()\nitemiz(the job control signals will go to the sh-started-by-xterm process\ngroup (that's why we disable INT QUIT and TSTP with trap; otherwise\nthe while loop could get suspended or killed))\nitemiz(the cloned shell will have job control disabled, and the job\ncontrol keys (control-C, control-\\ and control-Z) will not work.)\nenditemize()\n\nThis does not apply when cloning to an _unused_ vc.\n\nCloning to a used (and unprepared) terminal will result in two\nprocesses reading simultaneously from the same terminal, with\ninput bytes going randomly to either process.\n\n`clone` is mostly useful as a shell built-in replacement for\nopenvt."),
("no", "for normal text (i.e. when displaying something other than a matched file)"),
("fi", "for regular files"),
("di", "for directories"),
("ln", "for symbolic links. If this has the special value `target`,\nsymbolic links are dereferenced and the target file used to\ndetermine the display format."),
("pi", "for named pipes (FIFOs)"),
("so", "for sockets"),
("bd", "for block devices"),
("cd", "for character devices"),
("or", "for a symlink to nonexistent file (default is the value defined for `ln`)"),
("mi", "for a non-existent file (default is the value defined for `fi`); this code\nis currently not used"),
("su", "for files with setuid bit set"),
("sg", "for files with setgid bit set"),
("tw", "for world writable directories with sticky bit set"),
("ow", "for world writable directories without sticky bit set"),
("sa", "for files with an associated suffix alias; this is only tested\nafter specific suffixes, as described below"),
("st", "for directories with sticky bit set but not world writable"),
("ex", "for executable files"),
("lc", "for the left code (see below)"),
("rc", "for the right code"),
("tc", "for the character indicating the file type printed after filenames if\nthe `LIST_TYPES` option is set"),
("sp", "for the spaces printed after matches to align the next column"),
("ec", "for the end code"),
("send", "stops listing discarding the key pressed"),
("down", "scrolls forward one line"),
("expand", "scrolls forward one screenful"),
("accept", "stop listing but take no other action"),
("accept", "accept the current match and leave menu selection (but do\nnot cause the command line to be accepted)"),
("send", "leaves menu selection and restores the previous contents of the\ncommand line"),
("redisplay", "execute their normal function without leaving menu selection"),
("accept", "accept the currently inserted match and continue selection allowing to\nselect the next match to insert into the line"),
("accept", "accepts the current match and then tries completion with\nmenu selection again; in the case of files this allows one to select\na directory and immediately attempt to complete files in it; if there\nare no matches, a message is shown and one can use `undo` to go back\nto completion on the previous level, every other key leaves menu\nselection (including the other zle functions which are otherwise\nspecial during menu selection)"),
("undo", "removes matches inserted during the menu selection by one of the three\nfunctions before"),
("vi", "moves the mark one line down"),
("vi", "moves the mark one line up"),
("forward", "moves the mark one column right"),
("backward", "moves the mark one column left"),
("vi", "moves the mark one screenful down"),
("backward", "moves the mark one screenful up"),
("vi", "moves the mark to the first line of the next group of matches"),
("vi", "moves the mark to the last line of the previous group of matches"),
("beginning", "moves the mark to the first line"),
("end", "moves the mark to the last line"),
("beginning", "moves the mark to the leftmost column"),
("end", "moves the mark to the rightmost column"),
("expand", "moves the mark to the next match"),
("reverse", "moves the mark to the previous match"),
("vi", "this toggles between normal and interactive mode; in interactive mode\nthe keys bound to `self-insert` and `self-insert-unmeta` insert\ninto the command line as in normal editing mode but without leaving\nmenu selection; after each character completion is tried again and the\nlist changes to contain only the new matches; the completion widgets\nmake the longest unambiguous string be inserted in the command line\nand `undo` and `backward-delete-char` go back to the previous set\nof matches"),
("history", "this starts incremental searches in the list of completions displayed;\nin this mode, `accept-line` only leaves incremental search, going\nback to the normal menu selection mode"),
("comparguments", "This is used by the `_arguments` function to do the argument and\ncommand line parsing. Like `compdescribe` it has an option `-i` to\ndo the parsing and initialize some internal state and various options\nto access the state information to decide what should be completed."),
("compdescribe", "This is used by the `_describe` function to build the displays for\nthe matches and to get the strings to add as matches with their\noptions. On the first call one of the options `-i` or `-I` should be\nsupplied as the first argument. In the first case, display strings without\nthe descriptions will be generated, in the second case, the string used to\nseparate the matches from their descriptions must be given as the\nsecond argument and the descriptions (if any) will be shown. All other\narguments are like the definition arguments to `_describe` itself.\n\nOnce `compdescribe` has been called with either the `-i` or the\n`-I` option, it can be repeatedly called with the `-g` option and\nthe names of four parameters as its arguments. This will step through\nthe different sets of matches and store the value of `compstate[list]`\nin the first scalar, the options for `compadd` in the second array,\nthe matches in the third array, and the strings to be displayed in the\ncompletion listing in the fourth array. The arrays may then be directly\ngiven to `compadd` to register the matches with the completion code."),
("compfiles", "Used by the `_path_files` function to optimize complex recursive\nfilename generation (globbing). It does three things. With the\n`-p` and `-P` options it builds the glob patterns to use,\nincluding the paths already handled and trying to optimize the\npatterns with respect to the prefix and suffix from the line and the\nmatch specification currently used. The `-i` option does the\ndirectory tests for the `ignore-parents` style and the `-r` option\ntests if a component for some of the matches are equal to the string\non the line and removes all other matches if that is true."),
("compgroups", "Used by the `_tags` function to implement the internals of the\n`group-order` style. This only takes its arguments as names of\ncompletion groups and creates the groups for it (all six types: sorted\nand unsorted, both without removing duplicates, with removing all\nduplicates and with removing consecutive duplicates)."),
("compquote", "There may be reasons to write completion functions that have to add\nthe matches using the `-Q` option to `compadd` and perform quoting\nthemselves. Instead of interpreting the first character of the\n`all_quotes` key of the `compstate` special association and using\nthe `q` flag for parameter expansions, one can use this builtin\ncommand. The arguments are the names of scalar or array parameters\nand the values of these parameters are quoted as needed for the\ninnermost quoting level. If the `-p` option is given, quoting is\ndone as if there is some prefix before the values of the parameters,\nso that a leading equal sign will not be quoted.\n\nThe return status is non-zero in case of an error and zero otherwise."),
("comptry", "These implement the internals of the tags mechanism."),
("compvalues", "Like `comparguments`, but for the `_values` function."),
("zcurses", "Manipulate curses windows. All uses of this command should be\nbracketed by \"zcurses init\" to initialise use of curses, and\n\"zcurses end\" to end it; omitting \"zcurses end\" can cause\nthe terminal to be in an unwanted state.\n\nThe subcommand `addwin` creates a window with _nlines_ lines and\n_ncols_ columns. Its upper left corner will be placed at row\n_begin_y_ and column\n_begin_x_ of the screen. _targetwin_ is a string and refers\nto the name of a window that is not currently assigned. Note\nin particular the curses convention that vertical values appear\nbefore horizontal values.\n\nIf `addwin` is given an existing window as the final argument, the new\nwindow is created as a subwindow of _parentwin_. This differs from an\nordinary new window in that the memory of the window contents is shared\nwith the parent's memory. Subwindows must be deleted before their parent.\nNote that the coordinates of subwindows are relative to the screen, not\nthe parent, as with other windows.\n\nUse the subcommand `delwin` to delete a window created with\n`addwin`. Note that `end` does _not_ implicitly delete windows,\nand that `delwin` does not erase the screen image of the window.\n\nThe window corresponding to the full visible screen is called\n`stdscr`; it always exists after \"zcurses init\" and cannot\nbe delete with `delwin`.\n\nThe subcommand `refresh` will refresh window _targetwin_; this is\nnecessary to make any pending changes (such as characters you have\nprepared for output with `char`) visible on the screen. `refresh`\nwithout an argument causes the screen to be cleared and redrawn.\nIf multiple windows are given, the screen is updated once at the end.\n\nThe subcommand `touch` marks the _targetwin_s listed as changed.\nThis is necessary before `refresh`ing windows if a window that\nwas in front of another window (which may be `stdscr`) is deleted.\n\nThe subcommand `move` moves the cursor position in _targetwin_ to\nnew coordinates _new_y_ and _new_x_. Note that the\nsubcommand `string` (but not the subcommand `char`) advances the\ncursor position over the characters added.\n\nThe subcommand `clear` erases the contents of _targetwin_. One\n(and no more than one) of three options may be specified. With the\noption `redraw`, in addition the next `refresh` of _targetwin_\nwill cause the screen to be cleared and repainted. With the option\n`eol`, _targetwin_ is only cleared to the end of the current cursor\nline. With the option\n`bot`, _targetwin_ is cleared to the end of the window, i.e\neverything to the right and below the cursor is cleared.\n\nThe subcommand `position` writes various positions associated with\n_targetwin_ into the array named _array_.\nThese are, in order:\n\n- - â The y and x coordinates of the cursor relative to the top left\nof _targetwin_\n- - â The y and x coordinates of the top left of _targetwin_ on the\nscreen\n- - â The size of _targetwin_ in y and x dimensions.\n\nOutputting characters and strings are achieved by `char` and `string`\nrespectively.\n\nTo draw a border around window _targetwin_, use `border`. Note\nthat the border is not subsequently handled specially: in other words,\nthe border is simply a set of characters output at the edge of the\nwindow. Hence it can be overwritten, can scroll off the window, etc.\n\nThe subcommand `attr\" will set _targetwin_\"s attributes or\nforeground/background color pair for any successive character output.\nEach _attribute_ given on the line may be prepended by a `+` to set\nor a `-` to unset that attribute; `+` is assumed if absent. The\nattributes supported are `blink`, `bold`, `dim`, `reverse`,\n`standout`, and `underline`.\n\nEach _fg_col_`/`_bg_col_ attribute (to be read as\n\"_fg_col_ on _bg_col_\") sets the foreground and background color\nfor character output. The color `default` is sometimes available\n(in particular if the library is ncurses), specifying the foreground\nor background color with which the terminal started. The color pair\n`default/default` is always available. To use more than the 8 named\ncolors (red, green, etc.) construct the _fg_col_`/`_bg_col_\npairs where _fg_col_ and _bg_col_ are decimal integers, e.g\n`128/200`. The maximum color value is 254 if the terminal supports\n256 colors.\n\n`bg` overrides the color and other attributes of all characters in the\nwindow. Its usual use is to set the background initially, but it will\noverwrite the attributes of any characters at the time when it is called.\nIn addition to the arguments allowed with `attr`, an argument `@`_char_\nspecifies a character to be shown in otherwise blank areas of the window.\nOwing to limitations of curses this cannot be a multibyte character\n(use of ASCII characters only is recommended). As the specified set\nof attributes override the existing background, turning attributes\noff in the arguments is not useful, though this does not cause an error.\n\nThe subcommand `scroll` can be used with `on` or `off` to enabled\nor disable scrolling of a window when the cursor would otherwise move\nbelow the window due to typing or output. It can also be used with a\npositive or negative integer to scroll the window up or down the given\nnumber of lines without changing the current cursor position (which\ntherefore appears to move in the opposite direction relative to the\nwindow). In the second case, if scrolling is `off` it is temporarily\nturned `on` to allow the window to be scrolled.\n\nThe subcommand `input` reads a single character from the window\nwithout echoing it back. If _param_ is supplied the character is\nassigned to the parameter _param_, else it is assigned to the\nparameter `REPLY`.\n\nIf both _param_ and _kparam_ are supplied, the key is read in\n\"keypad\" mode. In this mode special keys such as function keys and\narrow keys return the name of the key in the parameter _kparam_. The\nkey names are the macros defined in the `curses.h` or `ncurses.h`\nwith the prefix \"KEY_\" removed; see also the description of the\nparameter `zcurses_keycodes` below. Other keys cause a value to be\nset in _param_ as before. On a successful return only one of\n_param_ or _kparam_ contains a non-empty string; the other is set\nto an empty string.\n\nIf _mparam_ is also supplied, `input` attempts to handle mouse\ninput. This is only available with the ncurses library; mouse handling\ncan be detected by checking for the exit status of \"zcurses mouse\" with\nno arguments. If a mouse\nbutton is clicked (or double- or triple-clicked, or pressed or released with\na configurable delay from being clicked) then _kparam_ is set to the string\n`MOUSE`, and _mparam_ is set to an array consisting of the\nfollowing elements:\n\n- - â An identifier to discriminate different input devices; this\nis only rarely useful.\n\n- **-** â The x, y and z coordinates of the mouse click relative to\nthe full screen, as three elements in that order (i.e. the y coordinate\nis, unusually, after the x coordinate). The z coordinate is only\navailable for a few unusual input devices and is otherwise set to zero.\n\n\n- **-** â Any events that occurred as separate items; usually\nthere will be just one. An event consists of `PRESSED`, `RELEASED`,\n`CLICKED`, `DOUBLE_CLICKED` or `TRIPLE_CLICKED` followed\nimmediately (in the same element) by the number of the button.\n\n- - â If the shift key was pressed, the string `SHIFT`.\n- - â If the control key was pressed, the string `CTRL`.\n- - â If the alt key was pressed, the string `ALT`.\n\nNot all mouse events may be passed through to the terminal window;\nmost terminal emulators handle some mouse events themselves. Note\nthat the ncurses manual implies that using input both with and\nwithout mouse handling may cause the mouse cursor to appear and\ndisappear.\n\nThe subcommand `mouse` can be used to configure the use of the mouse.\nThere is no window argument; mouse options are global.\n\"zcurses mouse\" with no arguments returns status 0 if mouse handling\nis possible, else status 1. Otherwise, the possible arguments (which\nmay be combined on the same command line) are as follows.\n`delay` _num_ sets the maximum delay in milliseconds between press and\nrelease events to be considered as a click; the value 0 disables click\nresolution, and the default is one sixth of a second. `motion` proceeded\nby an optional \"+\" (the default) or `-` turns on or off\nreporting of mouse motion in addition to clicks, presses and releases,\nwhich are always reported. However, it appears reports for mouse\nmotion are not currently implemented.\n\nThe subcommand `timeout` specifies a timeout value for input from\n_targetwin_. If _intval_ is negative, \"zcurses input\" waits\nindefinitely for a character to be typed; this is the default. If\n_intval_ is zero, \"zcurses input\" returns immediately; if there\nis typeahead it is returned, else no input is done and status 1 is\nreturned. If _intval_ is positive, \"zcurses input\" waits\n_intval_ milliseconds for input and if there is none at the end of\nthat period returns status 1.\n\nThe subcommand `querychar` queries the character at the current cursor\nposition. The return values are stored in the array named _param_ if\nsupplied, else in the array `reply`. The first value is the character\n(which may be a multibyte character if the system supports them); the\nsecond is the color pair in the usual _fg_col_`/`_bg_col_\nnotation, or `0` if color is not supported. Any attributes other than\ncolor that apply to the character, as set with the subcommand `attr`,\nappear as additional elements.\n\nThe subcommand `resize` resizes `stdscr` and all windows to given\ndimensions (windows that stick out from the new dimensions are resized\ndown). The underlying curses extension (`resize_term call`) can be\nunavailable. To verify, zeroes can be used for _height_ and\n_width_. If the result of the subcommand is `0`, resize_term is\navailable (`2` otherwise). Tests show that resizing can be normally\naccomplished by calling `zcurses end` and `zcurses refresh`. The\n`resize` subcommand is provided for versatility. Multiple system\nconfigurations have been checked and `zcurses end` and `zcurses\nrefresh` are still needed for correct terminal state after resize. To\ninvoke them with `resize`, use _endwin_ argument. Using\n_nosave_ argument will cause new terminal state to not be saved\ninternally by `zcurses`. This is also provided for versatility and\nshould normally be not needed."),
("ZCURSES_COLORS", "Readonly integer. The maximum number of colors the terminal\nsupports. This value is initialised by the curses library and is not\navailable until the first time `zcurses init` is run."),
("ZCURSES_COLOR_PAIRS", "Readonly integer. The maximum number of color pairs\n_fg_col_`/`_bg_col_ that may be defined in \"zcurses attr\"\ncommands; note this limit applies to all color pairs that have been\nused whether or not they are currently active. This value is initialised\nby the curses library and is not available until the first time `zcurses\ninit` is run."),
("zcurses_attrs", "Readonly array. The attributes supported by `zsh/curses`; available\nas soon as the module is loaded."),
("zcurses_colors", "Readonly array. The colors supported by `zsh/curses`; available\nas soon as the module is loaded."),
("zcurses_keycodes", "Readonly array. The values that may be returned in the second\nparameter supplied to \"zcurses input\" in the order in which they\nare defined internally by curses. Not all function keys\nare listed, only `F0`; curses reserves space for `F0` up to `F63`."),
("zcurses_windows", "Readonly array. The current list of windows, i.e. all windows that\nhave been created with \"zcurses addwin\" and not removed with\n\"zcurses delwin\"."),
("strftime", "Output the date in the _format_ specified. With no _epochtime_, the\ncurrent system date/time is used; optionally, _epochtime_ may be used to\nspecify the number of seconds since the epoch, and _nanoseconds_ may\nadditionally be used to specify the number of nanoseconds past the second\n(otherwise that number is assumed to be 0).\nSee manref(strftime)(3) for details. The zsh extensions described\nunder `%D{`_string_`}` prompt eqcape in\n_Simple Prompt Escapes_ (zshmisc) are also available.\n\n- **`-n`** âÂÂ\nSuppress printing a newline after the formatted string.\n\n- **`-q`** âÂÂ\nRun quietly; suppress printing of all error messages described below.\nErrors for invalid _epochtime_ values are always printed.\n\n\n- **`-r`** â With the option `-r` (reverse), use _format_ to parse the input\nstring _timestring_ and output the number of seconds since the epoch at\nwhich the time occurred. The parsing is implemented by the system\nfunction `strptime`; see manref(strptime)(3). This means that zsh\nformat extensions are not available, but for reverse lookup they are not\nrequired.\n\nIn most implementations of `strptime` any timezone in the\n_timestring_ is ignored and the local timezone declared by the `TZ`\nenvironment variable is used; other parameters are set to zero if not\npresent.\n\nIf _timestring_ does not match _format_ the command returns status 1\nand prints an error message. If _timestring_ matches _format_ but\nnot all characters in _timestring_ were used, the conversion succeeds\nbut also prints an error message.\n\nIf either of the system functions `strptime` or `mktime` is not\navailable, status 2 is returned and an error message is printed.\n\n\n- **`-s` _scalar_** â Assign the date string (or epoch time in seconds if `-r` is given) to\n_scalar_ instead of printing it.\n\n\nNote that depending on the system's declared integral time type,\n`strftime` may produce incorrect results for epoch times greater than\n2147483647 which corresponds to 2038-01-19 03:14:07 +0000."),
("EPOCHREALTIME", "A floating point value representing the number of seconds since\nthe epoch. The notional accuracy is to nanoseconds if the\n`clock_gettime` call is available and to microseconds otherwise,\nbut in practice the range of double precision floating point and\nshell scheduling latencies may be significant effects."),
("EPOCHSECONDS", "An integer value representing the number of seconds since the\nepoch."),
("epochtime", "An array value containing the number of seconds since the epoch\nin the first element and the remainder of the time since the epoch\nin nanoseconds in the second element. To ensure the two elements\nare consistent the array should be copied or otherwise referenced\nas a single substitution before the values are used. The following\nidiom may be used:\n\n for secs nsecs in $epochtime; do\n ...\ndone"),
("ztie", "Open the GDBM database identified by _filename_ and, if successful,\ncreate the associative array _arrayname_ linked to the file. To create\na local tied array, the parameter must first be declared, so commands\nsimilar to the following would be executed inside a function scope:\n\n local -A sampledb\nztie -d db/gdbm -f sample.gdbm sampledb\n\nThe `-r` option opens the database file for reading only, creating a\nparameter with the readonly attribute. Without this option, using\n\"ztie\" on a file for which the user does not have write permission is\nan error. If writable, the database is opened synchronously so fields\nchanged in _arrayname_ are immediately written to _filename_.\n\nChanges to the file modes _filename_ after it has been opened do not\nalter the state of _arrayname_, but ``typeset -r\" _arrayname_\"\nworks as expected."),
("zuntie", "Close the GDBM database associated with each _arrayname_ and then\nunset the parameter. The `-u` option forces an unset of parameters\nmade readonly with \"ztie -r\".\n\nThis happens automatically if the parameter is explicitly unset or its\nlocal scope (function) ends. Note that a readonly parameter may not be\nexplicitly unset, so the only way to unset a global parameter created with\n\"ztie -r\" is to use \"zuntie -u\"."),
("zgdbmpath", "Put path to database file assigned to _parametername_ into `REPLY`\nscalar."),
("zgdbm_tied", "Array holding names of all tied parameters."),
("delete", "Read a character from the keyboard, and\ndelete from the cursor position up to and including the next\n(or, with repeat count _n_, the _n_th) instance of that character.\nNegative repeat counts mean delete backwards."),
("zap", "This behaves like `delete-to-char`, except that the final occurrence of\nthe character itself is not deleted."),
("example", "Displays the flags and arguments it is invoked with."),
("chgrp", "Changes group of files specified. This is equivalent to `chown` with\na _user-spec_ argument of ``:\"_group_\"."),
("chmod", "Changes mode of files specified.\n\nThe specified _mode_ must be in octal.\n\nThe `-R` option causes `chmod` to recursively descend into directories,\nchanging the mode of all files in the directory after\nchanging the mode of the directory itself.\n\nThe `-s` option is a zsh extension to `chmod` functionality. It enables\nparanoid behaviour, intended to avoid security problems involving\na `chmod` being tricked into affecting files other than the ones\nintended. It will refuse to follow symbolic links, so that (for example)\n\"\"chmod 600 /tmp/foo/passwd\"\" can't accidentally chmod `/etc/passwd`\nif `/tmp/foo` happens to be a link to `/etc`. It will also check\nwhere it is after leaving directories, so that a recursive chmod of\na deep directory tree can't end up recursively chmoding `/usr` as\na result of directories being moved up the tree."),
("chown", "Changes ownership and group of files specified.\n\nThe _user-spec_ can be in four forms:\n\n- _user_ â change owner to _user_; do not change group\n- _user_`::` â change owner to _user_; do not change group\n- _user_`:\" â change owner to _user_; change group to _user_\"s primary group\n- _user_`:`_group_ â change owner to _user_; change group to _group_\n- `:`_group_ â do not change owner; change group to _group_\n\nIn each case, the \":\" may instead be a \".\". The rule is that\nif there is a \":\" then the separator is \":\", otherwise\nif there is a \".\" then the separator is \".\", otherwise\nthere is no separator.\n\nEach of _user_ and _group_ may be either a username (or group name, as\nappropriate) or a decimal user ID (group ID). Interpretation as a name\ntakes precedence, if there is an all-numeric username (or group name).\n\nIf the target is a symbolic link, the `-h` option causes `chown` to set\nthe ownership of the link instead of its target.\n\nThe `-R` option causes `chown` to recursively descend into directories,\nchanging the ownership of all files in the directory after\nchanging the ownership of the directory itself.\n\nThe `-s` option is a zsh extension to `chown` functionality. It enables\nparanoid behaviour, intended to avoid security problems involving\na `chown` being tricked into affecting files other than the ones\nintended. It will refuse to follow symbolic links, so that (for example)\n\"\"chown luser /tmp/foo/passwd\"\" can't accidentally chown `/etc/passwd`\nif `/tmp/foo` happens to be a link to `/etc`. It will also check\nwhere it is after leaving directories, so that a recursive chown of\na deep directory tree can't end up recursively chowning `/usr` as\na result of directories being moved up the tree."),
("ln", "Creates hard (or, with `-s`, symbolic) links. In the first form, the\nspecified _dest_ination is created, as a link to the specified\n_filename_. In the second form, each of the _filename_s is\ntaken in turn, and linked to a pathname in the specified _dir_ectory\nthat has the same last pathname component.\n\nNormally, `ln` will not attempt to create hard links to\ndirectories. This check can be overridden using the `-d` option.\nTypically only the super-user can actually succeed in creating\nhard links to directories.\nThis does not apply to symbolic links in any case.\n\nBy default, existing files cannot be replaced by links.\nThe `-i` option causes the user to be queried about replacing\nexisting files. The `-f` option causes existing files to be\nsilently deleted, without querying. `-f` takes precedence.\n\nThe `-h` and `-n` options are identical and both exist for\ncompatibility; either one indicates that if the target is a symlink\nthen it should not be dereferenced.\nTypically this is used in combination with `-sf` so that if an\nexisting link points to a directory then it will be removed,\ninstead of followed.\nIf this option is used with multiple filenames and the target\nis a symbolic link pointing to a directory then the result is\nan error."),
("mkdir", "Creates directories. With the `-p` option, non-existing parent\ndirectories are first created if necessary, and there will be\nno complaint if the directory already exists.\nThe `-m` option can be used to specify (in octal) a set of file permissions\nfor the created directories, otherwise mode 777 modified by the current\n`umask` (see manref(umask)(2)) is used."),
("mv", "Moves files. In the first form, the specified _filename_ is moved\nto the specified _dest_ination. In the second form, each of the\n_filename_s is\ntaken in turn, and moved to a pathname in the specified _dir_ectory\nthat has the same last pathname component.\n\nBy default, the user will be queried before replacing any file\nthat the user cannot write to, but writable files will be silently\nremoved.\nThe `-i` option causes the user to be queried about replacing\nany existing files. The `-f` option causes any existing files to be\nsilently deleted, without querying. `-f` takes precedence.\n\nNote that this `mv` will not move files across devices.\nHistorical versions of `mv`, when actual renaming is impossible,\nfall back on copying and removing files; if this behaviour is desired,\nuse `cp` and `rm` manually. This may change in a future version."),
("rm", "Removes files and directories specified.\n\nNormally, `rm` will not remove directories (except with the `-R` or `-r`\noptions). The `-d` option causes `rm` to try removing directories\nwith `unlink` (see manref(unlink)(2)), the same method used for files.\nTypically only the super-user can actually succeed in unlinking\ndirectories in this way.\n`-d` takes precedence over `-R` and `-r`.\n\nBy default, the user will be queried before removing any file\nthat the user cannot write to, but writable files will be silently\nremoved.\nThe `-i` option causes the user to be queried about removing\nany files. The `-f` option causes files to be\nsilently deleted, without querying, and suppresses all error indications.\n`-f` takes precedence.\n\nThe `-R` and `-r` options cause `rm` to recursively descend into\ndirectories, deleting all files in the directory before removing the directory\nwith the `rmdir` system call (see manref(rmdir)(2)).\n\nThe `-s` option is a zsh extension to `rm` functionality. It enables\nparanoid behaviour, intended to avoid common security problems involving\na root-run `rm` being tricked into removing files other than the ones\nintended. It will refuse to follow symbolic links, so that (for example)\n\"\"rm /tmp/foo/passwd\"\" can't accidentally remove `/etc/passwd`\nif `/tmp/foo` happens to be a link to `/etc`. It will also check\nwhere it is after leaving directories, so that a recursive removal of\na deep directory tree can't end up recursively removing `/usr` as\na result of directories being moved up the tree."),
("rmdir", "Removes empty directories specified."),
("sync", "Calls the system call of the same name (see manref(sync)(2)), which\nflushes dirty buffers to disk. It might return before the I/O has\nactually been completed."),
("nameref", "Equivalent to `typeset -n `_pname_`=`_rname_\n\nHowever, `nameref` is a builtin command rather than a reserved word,\nso when _rname_ uses subscript syntax it must be quoted against\nglobbing. Subscripts in referenced parameters are not supported in\nksh93, so this is not a significant compatibility issue."),
("namespace", "This reserved word executes the current shell compound command\n`{ `_list_` }`, with the special behavior that all functions\nand parameters \"_name_\" declared within _list_ are implicitly\nprefixed to become ``.`_ident_`.\"_name_\", and similarly any\nreference to a function or parameter \"_name_\" is searched for as\n``.`_ident_`.\"_name_\" before falling back to \"_name_\".\n\n_THIS FEATURE IS NOT YET IMPLEMENTED._"),
("var", "A shell function having this name, if defined, is invoked whenever the\nparameter `${`_name_`}` is referenced, including by commands\nsuch as \"typeset -p\". If the special variable \".sh.value\" is\nassigned by the function, that value is substituted instead of the\ntrue value of _name_. This does not change the value of _name_,\nbut there is no way to access the actual value without first removing\nthe function.\n\nAdditionally, an explicit reference to `${`_name_`.get}`\ncalls the function _name_`.get` even if there is no parameter\n\"_name_\" and substitutes the standard output of the function.\n\n_THIS FEATURE IS NOT YET IMPLEMENTED._"),
("var", "Shell functions having these names are invoked when the parameter\n_name_ is assigned or (for array types) has a new field appended.\nThe function may change the result of the operation by assigning to\nthe \".sh.value\" special parameter, or block the change by\nunsetting \".sh.value\".\n\nExplicit reference to `${`_name_`.set}` or `${`_name_`.append}`\nsubstitutes the standard output of the function.\n\n_THIS FEATURE IS NOT YET IMPLEMENTED._"),
("var", "When a function of this name is defined, it is called whenever the\nparameter _name_ would be unset. The function must explicitly\n``unset \"_name_\", otherwise the variable remains set.\n\n_THIS FEATURE IS NOT YET IMPLEMENTED._"),
("typeset", "Creates a _compound variable_.\n\n_THIS FEATURE IS NOT YET IMPLEMENTED, and the syntax of _values_\nis unlikely to be fully ksh compatible._"),
("builtin", "Installs a new shell builtin command dynamically linked from _file_,\nwhere _file_ is found by a path search and the base name of the file\nis the name of the builtin to be added.\n\nSimilar to ``zmodload -F zsh/`_file_` +b:\"_file_\".\n\n_THIS FEATURE IS UNLIKELY EVER TO BE IMPLEMENTED._"),
("typeset", "Used for _host-name file mapping_ on some operating systems.\n\n_THIS FEATURE IS UNLIKELY EVER TO BE IMPLEMENTED._"),
("typeset", "Declares a character translation _mapname_ for values assigned to _name_."),
("typeset", "Used to define _typed variables_ and properties of their _sub-variables_.\nThe `-T` and `-h` options conflict with existing zsh usage."),
("typeset", "Declares a floating-point variable displayed in hexadecimal format."),
("typeset", "Declares a parameter stored in _base64_ format."),
("typeset", "_Moves_ _oldname_ to _newname_. Conflicts with native zsh usage."),
("langinfo", "An associative array that maps langinfo elements to\ntheir values.\n\nYour implementation may support a number of the following keys:\n\n`CODESET`,\n`D_T_FMT`,\n`D_FMT`,\n`T_FMT`,\n`RADIXCHAR`,\n`THOUSEP`,\n`YESEXPR`,\n`NOEXPR`,\n`CRNCYSTR`,\n`ABDAY_{1..7}`,\n`DAY_{1..7}`,\n`ABMON_{1..12}`,\n`MON_{1..12}`,\n`T_FMT_AMPM`,\n`AM_STR`,\n`PM_STR`,\n`ERA`,\n`ERA_D_FMT`,\n`ERA_D_T_FMT`,\n`ERA_T_FMT`,\n`ALT_DIGITS`"),
("mapfile", "This associative array takes as keys the names of files; the resulting\nvalue is the content of the file. The value is treated identically to any\nother text coming from a parameter. The value may also be assigned to, in\nwhich case the file in question is written (whether or not it originally\nexisted); or an element may be unset, which will delete the file in\nquestion. For example, \"\"vared \"mapfile[myfile]\"`' works as expected,\nediting the file \"myfile\".\n\nWhen the array is accessed as a whole, the keys are the names of files in\nthe current directory, and the values are empty (to save a huge overhead in\nmemory). Thus tt(${(k)mapfile}) has the same effect as the glob operator\ntt(*(D)), since files beginning with a dot are not special. Care must be\ntaken with expressions such as tt(rm ${(k)mapfile}), which will delete\nevery file in the current directory without the usual \"rm *\" test.\n\nThe parameter `mapfile` may be made read-only; in that case, files\nreferenced may not be written or deleted.\n\nA file may conveniently be read into an array as one line per element\nwith the form\n`_array_tt(=(\"${(f@)mapfile[)_filename_`]}\"\")\".\nThe double quotes and the \"@\" are necessary to prevent empty lines\nfrom being removed. Note that if the file ends with a newline,\nthe shell will split on the final newline, generating an additional\nempty field; this can be suppressed by using\n\"_array_tt(=(\"${(f@)${mapfile[)_filename_\"]%$\"\\n\"}}\"\")\"."),
("options", "The keys for this associative array are the names of the options that\ncan be set and unset using the `setopt` and `unsetopt`\nbuiltins. The value of each key is either the string `on` if the\noption is currently set, or the string `off` if the option is unset.\nSetting a key to one of these strings is like setting or unsetting\nthe option, respectively. Unsetting a key in this array is like\nsetting it to the value `off`."),
("commands", "This array gives access to the command hash table. The keys are the\nnames of external commands, the values are the pathnames of the files\nthat would be executed when the command would be invoked. Setting a\nkey in this array defines a new entry in this table in the same way as\nwith the `hash` builtin. Unsetting a key as in ``unset\n\"commands[foo]\"`' removes the entry for the given key from the command\nhash table."),
("functions", "This associative array maps names of enabled functions to their\ndefinitions. Setting a key in it is like defining a function with the\nname given by the key and the body given by the value. Unsetting a key\nremoves the definition for the function named by the key."),
("dis_functions", "Like `functions` but for disabled functions."),
("functions_source", "This readonly associative array maps names of enabled functions to the\nname of the file containing the source of the function.\n\nFor an autoloaded function that has already been loaded, or marked for\nautoload with an absolute path, or that has had its path resolved with\n\"functions -r\", this is the file found for autoloading, resolved\nto an absolute path.\n\nFor a function defined within the body of a script or sourced file,\nthis is the name of that file. In this case, this is the exact path\noriginally used to that file, which may be a relative path.\n\nFor any other function, including any defined at an interactive prompt or\nan autoload function whose path has not yet been resolved, this is\nthe empty string. However, the hash element is reported as defined\njust so long as the function is present: the keys to this hash are\nthe same as those to `$functions`."),
("dis_functions_source", "Like `functions_source` but for disabled functions."),
("builtins", "This associative array gives information about the builtin commands\ncurrently enabled. The keys are the names of the builtin commands and\nthe values are either \"undefined\" for builtin commands that will\nautomatically be loaded from a module if invoked or \"defined\" for\nbuiltin commands that are already loaded."),
("dis_builtins", "Like `builtins` but for disabled builtin commands."),
("reswords", "This array contains the enabled reserved words."),
("dis_reswords", "Like `reswords` but for disabled reserved words."),
("patchars", "This array contains the enabled pattern characters."),
("dis_patchars", "Like `patchars` but for disabled pattern characters."),
("aliases", "This maps the names of the regular aliases currently enabled to their\nexpansions."),
("dis_aliases", "Like `aliases` but for disabled regular aliases."),
("galiases", "Like `aliases`, but for global aliases."),
("dis_galiases", "Like `galiases` but for disabled global aliases."),
("saliases", "Like `raliases`, but for suffix aliases."),
("dis_saliases", "Like `saliases` but for disabled suffix aliases."),
("parameters", "The keys in this associative array are the names of the parameters\ncurrently defined. The values are strings describing the type of the\nparameter, in the same format used by the `t` parameter flag, see\nsubref(Parameter Expansion Flags)(zshexpn).\nThe value may also be \"undefined\" indicating a parameter that\nmay be autoloaded from a module but has not yet been referenced.\nWhen the key is the name of a named reference, the value is\n\"nameref-\" prepended to the type of the referenced parameter,\nfor example\nifzman()\n\n `% typeset -n parms=parameters`\n`% print -r ${parameters[parms]}`\n`nameref-association-readonly-hide-hideval-special`\n\nSetting or unsetting keys in this array is not possible."),
("modules", "An associative array giving information about modules. The keys are the names\nof the modules loaded, registered to be autoloaded, or aliased. The\nvalue says which state the named module is in and is one of the\nstrings \"loaded\", \"autoloaded\", or ``alias:\"_name_\",\nwhere _name_ is the name the module is aliased to.\n\nSetting or unsetting keys in this array is not possible."),
("dirstack", "A normal array holding the elements of the directory stack. Note that\nthe output of the `dirs` builtin command includes one more\ndirectory, the current working directory."),
("history", "This associative array maps history event numbers to the full history lines.\nAlthough it is presented as an associative array, the array of all values\n(`${history[@]}`) is guaranteed to be returned in order from most recent\nto oldest history event, that is, by decreasing history event number."),
("historywords", "A special array containing the words stored in the history. These also\nappear in most to least recent order."),
("jobdirs", "This associative array maps job numbers to the directories from which the\njob was started (which may not be the current directory of the job).\n\nThe keys of the associative arrays are usually valid job numbers,\nand these are the values output with, for example, tt(${(k)jobdirs}).\nNon-numeric job references may be used when looking up a value;\nfor example, `${jobdirs[%+]}` refers to the current job.\n\nSee the `jobs` builtin for how job information is provided in a subshell."),
("jobtexts", "This associative array maps job numbers to the texts of the command lines\nthat were used to start the jobs.\n\nHandling of the keys of the associative array is as described for\n`jobdirs` above.\n\nSee the `jobs` builtin for how job information is provided in a subshell."),
("jobstates", "This associative array gives information about the states of the jobs\ncurrently known. The keys are the job numbers and the values are\nstrings of the form\n`_job-state_`:`_mark_`:`_pid_`=\"_state_...\". The\n_job-state_ gives the state the whole job is currently in, one of\n\"running\", \"suspended\", or \"done\". The _mark_ is\n\"+\" for the current job, \"-\" for the previous job and empty\notherwise. This is followed by one ``:`_pid_`=\"_state_\" for every\nprocess in the job. The _pid_s are, of course, the process IDs and\nthe _state_ describes the state of that process.\n\nHandling of the keys of the associative array is as described for\n`jobdirs` above.\n\nSee the `jobs` builtin for how job information is provided in a subshell."),
("nameddirs", "This associative array maps the names of named directories to the pathnames\nthey stand for."),
("userdirs", "This associative array maps user names to the pathnames of their home\ndirectories."),
("usergroups", "This associative array maps names of system groups of which the current\nuser is a member to the corresponding group identifiers. The contents\nare the same as the groups output by the `id` command."),
("funcfiletrace", "This array contains the absolute line numbers and corresponding file\nnames for the point where the current function, sourced file, or (if\n`EVAL_LINENO` is set) `eval` command was\ncalled. The array is of the same length as `funcsourcetrace` and\n`functrace`, but differs from `funcsourcetrace` in that the line and\nfile are the point of call, not the point of definition, and differs\nfrom `functrace` in that all values are absolute line numbers in\nfiles, rather than relative to the start of a function, if any."),
("funcsourcetrace", "This array contains the file names and line numbers of the\npoints where the functions, sourced files, and (if `EVAL_LINENO` is set)\n`eval` commands currently being executed were\ndefined. The line number is the line where the ``function\" _name_\"\nor \"_name_ tt(())\" started. In the case of an autoloaded\nfunction the line number is reported as zero.\nThe format of each element is _filename_`:`_lineno_.\n\nFor functions autoloaded from a file in native zsh format, where only the\nbody of the function occurs in the file, or for files that have been\nexecuted by the `source` or \".\" builtins, the trace information is\nshown as _filename_`:`_0_, since the entire file is the\ndefinition. The source file name is resolved to an absolute path when\nthe function is loaded or the path to it otherwise resolved.\n\nMost users will be interested in the information in the\n`funcfiletrace` array instead."),
("funcstack", "This array contains the names of the functions, sourced files,\nand (if `EVAL_LINENO` is set) `eval` commands. currently being\nexecuted. The first element is the name of the function using the\nparameter.\n\nThe standard shell array `zsh_eval_context` can be used to\ndetermine the type of shell construct being executed at each depth:\nnote, however, that is in the opposite order, with the most recent\nitem last, and it is more detailed, for example including an\nentry for `toplevel`, the main shell code being executed\neither interactively or from a script, which is not present\nin `$funcstack`."),
("functrace", "This array contains the names and line numbers of the callers\ncorresponding to the functions currently being executed.\nThe format of each element is _name_`:`_lineno_.\nCallers are also shown for sourced files; the caller is the point\nwhere the `source` or \".\" command was executed."),
("pcre_compile", "Compiles a perl-compatible regular expression.\n\nOption `-a` will force the pattern to be anchored.\nOption `-i` will compile a case-insensitive pattern.\nOption `-m` will compile a multi-line pattern; that is,\n`^` and `$` will match newlines within the pattern.\nOption `-x` will compile an extended pattern, wherein\nwhitespace and `#` comments are ignored.\nOption `-s` makes the dot metacharacter match all characters,\nincluding those that indicate newline."),
("pcre_study", "Requests JIT compilation for the previously-compiled PCRE which\nmay result in faster matching."),
("pcre_match", "Returns successfully if `string` matches the previously-compiled\nPCRE.\n\nUpon successful match,\nif the expression captures substrings within parentheses,\n`pcre_match` will set the array `match` to those\nsubstrings, unless the `-a` option is given, in which\ncase it will set the array _arr_. Similarly, the variable\n`MATCH` will be set to the entire matched portion of the\nstring, unless the `-v` option is given, in which case the variable\n_var_ will be set. Furthermore, any named captures will\nbe stored in the associative array `.pcre.match` unless an\nalternative is given with `-A`.\nNo variables are altered if there is no successful match.\nA `-n` option starts searching for a match from the\nbyte _offset_ position in _string_. If the `-b` option is given,\nthe variable `ZPCRE_OP` will be set to an offset pair string,\nrepresenting the byte offset positions of the entire matched portion\nwithin the _string_. For example, a `ZPCRE_OP` set to \"32 45\" indicates\nthat the matched portion began on byte offset 32 and ended on byte offset 44.\nHere, byte offset position 45 is the position directly after the matched\nportion. Keep in mind that the byte position isn't necessarily the same\nas the character position when UTF-8 characters are involved.\nConsequently, the byte offset positions are only to be relied on in the\ncontext of using them for subsequent searches on _string_, using an offset\nposition as an argument to the `-n` option. This is mostly\nused to implement the \"find all non-overlapping matches\" functionality.\n\nA simple example of \"find all non-overlapping matches\":\n\nexample(string=\"The following zip codes: 78884 90210 99513\"\npcre_compile -m \"\\d{5}\"\naccum=()\npcre_match -b -- $string\nwhile [[ $? -eq 0 ]] do\n b=($=ZPCRE_OP)\n accum+=$MATCH\n pcre_match -b -n $b[2] -- $string\ndone\nprint -l $accum)"),
("pcre-match", "Matches a string against a perl-compatible regular expression.\n\nFor example,\n\n [[ \"$text\" -pcre-match ^d+$ ]] &&\nprint text variable contains only \"d's\".\n\npindex(REMATCH_PCRE)\npindex(NO_CASE_MATCH)\nIf the `REMATCH_PCRE` option is set, the `=~` operator is equivalent to\n`-pcre-match`, and the `NO_CASE_MATCH` option may be used. Note that\n`NO_CASE_MATCH` never applies to the `pcre_match` builtin, instead use\nthe `-i` switch of `pcre_compile`."),
("private", "The `private` builtin accepts all the same options and arguments as `local`\n(nmref(Shell Builtin Commands)(zshbuiltins)) except\nfor the ``-\"T\" option. Tied parameters may not be made private.\n\nThe ``-\"p\" option is presently disabled because the state of\nprivate parameters cannot reliably be reloaded. When ``typeset -\"p\"\noutputs a private parameter, it is treated as a local with the\n``-\"h\" (hide) option enabled.\n\nIf used at the top level (outside a function scope), `private` creates a\nnormal parameter in the same manner as `declare` or `typeset`. A\nwarning about this is printed if `WARN_CREATE_GLOBAL` is set\n(nmref(Options)(zshoptions)). Used inside a\nfunction scope, `private` creates a local parameter similar to one\ndeclared with `local`, except having special properties noted below.\n\nSpecial parameters which expose or manipulate internal shell state, such\nas `ARGC`, `argv`, `COLUMNS`, `LINES`, `UID`, `EUID`, `IFS`,\n`PROMPT`, `RANDOM`, `SECONDS`, etc., cannot be made private unless\nthe ``-\"h\" option is used to hide the special meaning of the\nparameter. This may change in the future."),
("SRANDOM", "A random positive 32-bit integer between 0 and 4,294,967,295. This parameter\nis read-only. The name was chosen for compatibility with Bash and to\ndistinguish it from `RANDOM` which has a documented repeatable behavior."),
("zrand_float", "Returns a random floating point number between 0 and 1 inclusive."),
("zrand_int", "Returns a random integer between `lower` and `upper`. All parameters are\noptional. If none are specified it is equivalent to\n`SRANDOM`.\n\n`upper` is the upper bound on the resultant number and defaults to\n4,294,967,295.\n\n`lower` is the lower bound and defaults to 0.\n\nThe defaults of these two arguments are also the maximum and minimum to which\neither can be set.\n\n`inclusive` is a flag that controls whether the result is ever equal to\n`upper`. By default it is not. If this argument is set to a non-zero value\nthen it may be.\n\nThis is to facilitate a construct like tt($a[zrand_int+($#a+)+1]) rather\nthan tt($a[zrand_int+($#a-1+)+1]).\nFor example, if $#a is 16, you would use tt(zrand_int+(16)) which has\n16 possible return values 0-15. Because the function can return zero, in order\nto use it as an array index from 1-16 you need to add one. It would\nbe an array index range error for it to also potentially return 16 ($#a). You\ncould, however, use the construct tt(zrand_int+(16,1,1+)) instead of\nadding 1 to achieve the same result, but it is more verbose.\n\nMost statistics algorithms seem to also expect 0 to `upper`-1, so this was\ndeemed the most commonly desired case and chosen as the default."),
("regex-match", "Matches a string against a POSIX extended regular expression.\nOn successful match,\nmatched portion of the string will normally be placed in the `MATCH`\nvariable. If there are any capturing parentheses within the regex, then\nthe `match` array variable will contain those.\nIf the match is not successful, then the variables will not be altered.\n\nFor example,\n\nexample([[ alphabetical -regex-match ^a+([^a]++)a+([^a]+++)a ]] &&\nprint -l $MATCH X $match)\n\nIf the option `REMATCH_PCRE` is not set, then the `=~` operator will\nautomatically load this module as needed and will invoke the\n`-regex-match` operator.\n\nIf `BASH_REMATCH` is set, then the array `BASH_REMATCH` will be set\ninstead of `MATCH` and `match`.\n\nNote that the `zsh/regex` module logic relies on the host system. The\nsame _expr_ and _regex_ pair could produce different results on different\nplatforms if a _regex_ with non-standard syntax is given.\n\nFor example, no syntax for matching a word boundary is defined in the POSIX\nextended regular expression standard. GNU `libc` and BSD `libc` both provide\nsuch syntaxes as extensions (`\\b` and `[[:<:]]`/`[[:>:]]` respectively),\nbut neither of these syntaxes is supported by both of these implementations.\n\nRefer to the manref(regcomp)(3) and manref(re_format)(7) manual pages on your\nsystem for locally-supported syntax."),
("sched", "Make an entry in the scheduled list of commands to execute.\nThe time may be specified in either absolute or relative time,\nand either as hours, minutes and (optionally) seconds separated by a\ncolon, or seconds alone.\nAn absolute number of seconds indicates the time since the epoch\n(1970/01/01 00:00); this is useful in combination with the features in\nthe `zsh/datetime` module, see\n_The zsh/datetime Module_ (zshmodules).\n\nWith no arguments, prints the list of scheduled commands. If the\nscheduled command has the `-o` flag set, this is shown at the\nstart of the command.\n\nWith the argument ``-\"_item_\", removes the given item\nfrom the list. The numbering of the list is continuous and entries are\nin time order, so the numbering can change when entries are added or\ndeleted.\n\nCommands are executed either immediately before a prompt, or while\nthe shell's line editor is waiting for input. In the latter case\nit is useful to be able to produce output that does not interfere\nwith the line being edited. Providing the option `-o` causes\nthe shell to clear the command line before the event and redraw it\nafterwards. This should be used with any scheduled event that produces\nvisible output to the terminal; it is not needed, for example, with\noutput that updates a terminal emulator's title bar.\n\nTo effect changes to the editor buffer when an event executes, use the\n\"zle\" command with no arguments to test whether the editor is active,\nand if it is, then use ``zle \"_widget_\" to access the editor via\nthe named _widget_.\n\nThe `sched` builtin is not made available by default when the shell\nstarts in a mode emulating another shell. It can be made available\nwith the command \"zmodload -F zsh/sched b:sched\"."),
("zsh_scheduled_events", "A readonly array corresponding to the events scheduled by the\n`sched` builtin. The indices of the array correspond to the numbers\nshown when `sched` is run with no arguments (provided that the\n`KSH_ARRAYS` option is not set). The value of the array\nconsists of the scheduled time in seconds since the epoch\n(see _The zsh/datetime Module_ (zshmodules) for facilities for\nusing this number), followed by a colon, followed by any options\n(which may be empty but will be preceded by a \"-\" otherwise),\nfollowed by a colon, followed by the command to be executed.\n\nThe `sched` builtin should be used for manipulating the events. Note\nthat this will have an immediate effect on the contents of the array,\nso that indices may become invalid."),
("zsocket", "`zsocket` is implemented as a builtin to allow full use of shell\ncommand line editing, file I/O, and job control mechanisms."),
("zsocket", "Open a new Unix domain connection to _filename_.\nThe shell parameter `REPLY` will be set to the file descriptor\nassociated with that connection. Currently, only stream connections\nare supported.\n\nIf `-d` is specified, its argument\nwill be taken as the target file descriptor for the\nconnection.\n\nIn order to elicit more verbose output, use `-v`.\n\nFile descriptors can be closed with normal shell syntax when no longer\nneeded, for example:\n\n exec {REPLY}>&-"),
("zsocket", "`zsocket -l` will open a socket listening on _filename_.\nThe shell parameter `REPLY` will be set to the file descriptor\nassociated with that listener. The file descriptor remains open in subshells\nand forked external executables.\n\nIf `-d` is specified, its argument\nwill be taken as the target file descriptor for\nthe connection.\n\nIn order to elicit more verbose output, use `-v`."),
("zsocket", "`zsocket -a` will accept an incoming connection\nto the socket associated with _listenfd_.\nThe shell parameter `REPLY` will\nbe set to the file descriptor associated with\nthe inbound connection. The file descriptor remains open in subshells\nand forked external executables.\n\nIf `-d` is specified, its argument\nwill be taken as the target file descriptor for the\nconnection.\n\nIf `-t` is specified, `zsocket` will return\nif no incoming connection is pending. Otherwise\nit will wait for one.\n\nIn order to elicit more verbose output, use `-v`."),
("stat", "The command acts as a front end to the `stat` system call (see\nmanref(stat)(2)). The same command is provided with two names; as\nthe name `stat` is often used by an external command it is recommended\nthat only the `zstat` form of the command is used. This can be\narranged by loading the module with the command ``zmodload -F zsh/stat\nb:zstat`'.\n\nIf the `stat` call fails, the appropriate system error message\nprinted and status 1 is returned.\nThe fields of `struct stat` give information about\nthe files provided as arguments to the command. In addition to those\navailable from the `stat` call, an extra element \"link\" is provided.\nThese elements are:\n\n- **`device`** âÂÂ\nThe number of the device on which the file resides.\n\n\n- **`inode`** â The unique number of the file on this device (\"_inode_\" number).\n\n\n- **`mode`** âÂÂ\nThe mode of the file; that is, the file's type and access permissions.\nWith the `-s` option, this will\nbe returned as a string corresponding to the first column in the\ndisplay of the `ls -l` command.\n\n- **`nlink`** âÂÂ\nThe number of hard links to the file.\n\n- **`uid`** âÂÂ\nThe user ID of the owner of the file. With the `-s`\noption, this is displayed as a user name.\n\n- **`gid`** âÂÂ\nThe group ID of the file. With the `-s` option, this\nis displayed as a group name.\n\n- **`rdev`** âÂÂ\nThe raw device number. This is only useful for special devices.\n\n- **`size`** âÂÂ\nThe size of the file in bytes.\n\n- **`atime`**\n\n- **`mtime`**\n\n- **`ctime`** âÂÂ\nThe last access, modification and inode change times\nof the file, respectively, as the number of seconds since\nmidnight GMT on 1st January, 1970. With the `-s` option,\nthese are printed as strings for the local time zone; the format\ncan be altered with the `-F` option, and with the `-g`\noption the times are in GMT.\n\n- **`blksize`** âÂÂ\nThe number of bytes in one allocation block on the\ndevice on which the file resides.\n\n- **`block`** âÂÂ\nThe number of disk blocks used by the file.\n\n\n- **`link`** â If the file is a link and the `-L` option is in\neffect, this contains the name of the file linked to, otherwise\nit is empty. Note that if this element is selected (\"\"zstat +link\"\")\nthen the `-L` option is automatically used.\n\n\nA particular element may be selected by including its name\npreceded by a \"+\" in the option list; only one element is allowed.\nThe element may be shortened to any unique set of leading\ncharacters. Otherwise, all elements will be shown for all files.\n\nOptions:\n\n- **`-A` _array_** âÂÂ\nInstead of displaying the results on standard\noutput, assign them to an _array_, one `struct stat` element per array\nelement for each file in order. In this case neither the name\nof the element nor the name of the files appears in _array_ unless the\n`-t` or `-n` options were given, respectively. If `-t` is given,\nthe element name appears as a prefix to the\nappropriate array element; if `-n` is given, the file name\nappears as a separate array element preceding all the others.\nOther formatting options are respected.\n\n- **`-H` _hash_** âÂÂ\nSimilar to `-A`, but instead assign the values to _hash_. The keys\nare the elements listed above. If the `-n` option is provided then the\nname of the file is included in the hash with key `name`.\n\n- **`-f` _fd_** âÂÂ\nUse the file on file descriptor _fd_ instead of\nnamed files; no list of file names is allowed in this case.\n\n\n- **`-F` _fmt_** â Supplies a `strftime` (see manref(strftime)(3)) string for the\nformatting of the time elements. The format string supports all of the\nzsh extensions (see the description of `%D{`_string_`}`\nprompt escape in _Simple Prompt Escapes_ (zshmisc)).\nIn particular, `-F %s.%N` can be used to show timestamps with nanosecond\nprecision if supported by the system.\nThe `-s` option is implied.\n\n\n- **`-g`** âÂÂ\nShow the time elements in the GMT time zone. The\n`-s` option is implied.\n\n\n- **`-l`** â List the names of the type elements (to standard\noutput or an array as appropriate) and return immediately;\narguments, and options other than `-A`, are ignored.\n\n\n- **`-L`** â Perform an `lstat` (see manref(lstat)(2)) rather than a `stat`\nsystem call. In this case, if the file is a link, information\nabout the link itself rather than the target file is returned.\nThis option is required to make the `link` element useful.\nIt's important to note that this is the exact opposite from manref(ls)(1),\netc.\n\n- **`-n`** âÂÂ\nAlways show the names of files. Usually these are\nonly shown when output is to standard output and there is more\nthan one file in the list.\n\n- **`-N`** âÂÂ\nNever show the names of files.\n\n- **`-o`** âÂÂ\nIf a raw file mode is printed, show it in octal, which is more useful for\nhuman consumption than the default of decimal. A leading zero will be\nprinted in this case. Note that this does not affect whether a raw or\nformatted file mode is shown, which is controlled by the `-r` and `-s`\noptions, nor whether a mode is shown at all.\n\n\n- **`-r`** â Print raw data (the default format) alongside string\ndata (the `-s` format); the string data appears in parentheses\nafter the raw data.\n\n\n- **`-s`** âÂÂ\nPrint `mode`, `uid`, `gid` and the three time\nelements as strings instead of numbers. In each case the format\nis like that of `ls -l`.\n\n- **`-t`** âÂÂ\nAlways show the type names for the elements of\n`struct stat`. Usually these are only shown when output is to\nstandard output and no individual element has been selected.\n\n- **`-T`** âÂÂ\nNever show the type names of the `struct stat` elements."),
("syserror", "This command prints out the error message associated with _errno_, a\nsystem error number, followed by a newline to standard error.\n\nInstead of the error number, a name _errname_, for example\n`ENOENT`, may be used. The set of names is the same as the contents\nof the array `errnos`, see below.\n\nIf the string _prefix_ is given, it is printed in front of the error\nmessage, with no intervening space.\n\nIf _errvar_ is supplied, the entire message, without a newline, is\nassigned to the parameter names _errvar_ and nothing is output.\n\nA return status of 0 indicates the message was successfully printed\n(although it may not be useful if the error number was out of the\nsystem's range), a return status of 1 indicates an error in the\nparameters, and a return status of 2 indicates the error name was\nnot recognised (no message is printed for this)."),
("sysopen", "This command opens a file. The `-r`, `-w` and `-a` flags indicate\nwhether the file should be opened for reading, writing and appending,\nrespectively. The `-m` option allows the initial permissions to use when\ncreating a file to be specified in octal form. The file descriptor is\nspecified with `-u`. Either an explicit file descriptor in the range 0 to 9 can\nbe specified or a variable name can be given to which the file descriptor\nnumber will be assigned.\n\nThe `-o` option allows various system specific options to be\nspecified as a comma-separated list. The following is a list of possible\noptions. Note that, depending on the system, some may not be available.\n\n\n- **`cloexec`** â mark file to be closed when other programs are executed (else\nthe file descriptor remains open in subshells and forked external\nexecutables)\n\n\n- **`create`**\n\n- **`creat`** âÂÂ\ncreate file if it does not exist\n\n- **`excl`** âÂÂ\ncreate file, error if it already exists\n\n- **`noatime`** âÂÂ\nsuppress updating of the file atime\n\n- **`nofollow`** âÂÂ\nfail if _file_ is a symbolic link\n\n- **`nonblock`** âÂÂ\nthe file is opened in nonblocking mode\n\n- **`sync`** âÂÂ\nrequest that writes wait until data has been physically written\n\n- **`truncate`**\n\n- **`trunc`** âÂÂ\ntruncate file to size 0\n\nA return status of 0 indicates the descriptor was successfully opened,\notherwise an error message is printed, and 1 is returned for an error\nin the parameters to the command, or 2 is returned for a system error.\nThe parameter `ERRNO` is nonzero for system errors.\n\nTo close the file, use one of the following:\n\n `exec {`_fd_`}<&-`\n`exec {`_fd_`}>&-`"),
("sysread", "Perform a single system read from file descriptor _infd_, or zero if\nthat is not given. The result of the read is stored in _param_ or\n`REPLY` if that is not given. If _countvar_ is given, the number\nof bytes read is assigned to the parameter named by _countvar_.\n\nThe maximum number of bytes read is _bufsize_ or 8192 if that is not\ngiven, however the command returns as soon as any number of bytes was\nsuccessfully read.\n\nIf _timeout_ is given, it specifies a timeout in seconds, which may\nbe zero to poll the file descriptor. This is handled by the `poll`\nsystem call if available, otherwise the `select` system call if\navailable.\n\nIf _outfd_ is given, an attempt is made to write all the bytes just\nread to the file descriptor _outfd_. If this fails, because of a\nsystem error other than `EINTR` or because of an internal zsh error\nduring an interrupt, the bytes read but not written are stored in the\nparameter named by _param_ if supplied (no default is used in this\ncase), and the number of bytes read but not written is stored in the\nparameter named by _countvar_ if that is supplied. If it was\nsuccessful, _countvar_ contains the full number of bytes transferred,\nas usual, and _param_ is not set.\n\nThe error `EINTR` (interrupted system call) is handled internally so\nthat shell interrupts are transparent to the caller. Any other error\ncauses a return.\n\nThe possible return statuses are\n\n- **0** âÂÂ\nAt least one byte of data was successfully read and, if appropriate,\nwritten.\n\n- **1** âÂÂ\nThere was an error in the parameters to the command. This is the only\nerror for which a message is printed to standard error.\n\n- **2** âÂÂ\nThere was an error on the read, or on polling the input file descriptor\nfor a timeout. The parameter `ERRNO` identifies the error.\n\n- **3** âÂÂ\nData were successfully read, but there was an error writing them\nto _outfd_. The parameter `ERRNO` identifies the error.\n\n- **4** âÂÂ\nThe attempt to read timed out. Note this does not set `ERRNO` as this\nis not a system error.\n\n- **5** âÂÂ\nNo system error occurred, but zero bytes were read. This usually\nindicates end of file. The parameters are set according to the\nusual rules; no write to _outfd_ is attempted."),
("sysseek", "The current file position at which future reads and writes will take place is\nadjusted to the specified byte offset. The _offset_ is evaluated as a math\nexpression. The `-u` option allows the file descriptor to be specified. By\ndefault the offset is specified relative to the start or the file but, with the\n`-w` option, it is possible to specify that the offset should be relative to\nthe current position or the end of the file.\n\nThe return status may be 0 for success, 1 for an error in the parameters\nto the command, or 2 for an error on the seek; no error message is\nprinted in the last case, but the parameter `ERRNO` reflects\nthe error that occurred."),
("syswrite", "The data (a single string of bytes) are written to the file descriptor\n_outfd_, or 1 if that is not given, using the `write` system call.\nMultiple write operations may be used if the first does not write all\nthe data.\n\nIf _countvar_ is given, the number of byte written is stored in the\nparameter named by _countvar_; this may not be the full length of\n_data_ if an error occurred.\n\nThe error `EINTR` (interrupted system call) is handled internally by\nretrying; otherwise an error causes the command to return. For example,\nif the file descriptor is set to non-blocking output, an error\n`EAGAIN` (on some systems, `EWOULDBLOCK`) may result in the command\nreturning early.\n\nThe return status may be 0 for success, 1 for an error in the parameters\nto the command, or 2 for an error on the write; no error message is\nprinted in the last case, but the parameter `ERRNO` reflects\nthe error that occurred."),
("zsystem", "The builtin `zsystem`'s subcommand `flock` performs advisory file\nlocking (via the manref(fcntl)(2) system call) over the entire contents\nof the given file. This form of locking requires the processes\naccessing the file to cooperate; its most obvious use is between two\ninstances of the shell itself.\n\nIn the first form the named _file_, which must already exist, is\nlocked by opening a file descriptor to the file and applying a lock to\nthe file descriptor. The lock terminates when the shell process that\ncreated the lock exits; it is therefore often convenient to create file\nlocks within subshells, since the lock is automatically released when\nthe subshell exits. Note that use of the `print` builtin with the\n`-u` option will, as a side effect, release the lock, as will redirection\nto the file in the shell holding the lock. To work around this use a\nsubshell, e.g. \"tt((print message) >> )_file_\". Status 0 is\nreturned if the lock succeeds, else status 1.\n\nIn the second form the file descriptor given by the arithmetic\nexpression _fd_expr_ is closed, releasing a lock. The file descriptor\ncan be queried by using the ``-f\" _var_\" form during the lock;\non a successful lock, the shell variable _var_ is set to the file\ndescriptor used for locking. The lock will be released if the\nfile descriptor is closed by any other means, for example using\n``exec {`_var_`}>&-`'; however, the form described here performs\na safety check that the file descriptor is in use for file locking.\n\nBy default the shell waits indefinitely for the lock to succeed.\nThe option `-t` _timeout_ specifies a timeout for the lock in\nseconds; fractional seconds are allowed. During this period, the\nshell will attempt to lock the file every _interval_ seconds\nif the `-i` _interval_ option is given, otherwise once a second.\n(This _interval_ is shortened before the last attempt if needed,\nso that the shell waits only until the _timeout_ and not longer.)\nIf the attempt times out, status 2 is returned.\n\n(Note: _timeout_ is limited to 2^30-1 seconds (about 34 years), and\n_interval_ to 0.999 * LONG_MAX microseconds (only about 35 minutes\non 32-bit systems).)\n\nIf the option `-e` is given, the file descriptor for the lock is\npreserved when the shell uses `exec` to start a new process;\notherwise it is closed at that point and the lock released.\n\nIf the option `-r` is given, the lock is only for reading, otherwise\nit is for reading and writing. The file descriptor is opened\naccordingly."),
("zsystem", "The builtin `zsystem`'s subcommand `supports` tests whether a\ngiven subcommand is supported. It returns status 0 if so, else\nstatus 1. It operates silently unless there was a syntax error\n(i.e. the wrong number of arguments), in which case status 255\nis returned. Status 1 can indicate one of two things: _subcommand_\nis known but not supported by the current operating system, or\n_subcommand_ is not known (possibly because this is an older\nversion of the shell before it was implemented)."),
("systell", "The systell math function returns the current file position for the file\ndescriptor passed as an argument."),
("errnos", "A readonly array of the names of errors defined on the system. These\nare typically macros defined in C by including the system header file\n`errno.h`. The index of each name (assuming the option `KSH_ARRAYS`\nis unset) corresponds to the error number. Error numbers _num_\nbefore the last known error which have no name are given the name\n`E`_num_ in the array.\n\nNote that aliases for errors are not handled; only the canonical name is\nused."),
("sysparams", "A readonly associative array. The keys are:\n\n\n- **`pid`** â vindex(pid, sysparams)\nReturns the process ID of the current process, even in subshells. Compare\n`$$`, which returns the process ID of the main shell process.\n\n\n- **`ppid`** â vindex(ppid, sysparams)\nReturns the current process ID of the parent of the current process, even\nin subshells. Compare `$PPID`, which returns the process ID of the\ninitial parent of the main shell process.\n\n\n- **`procsubstpid`** â Returns the process ID of the last process started for process\nsubstitution, i.e. the tt(<()_..._``) and\ntt(>()_..._``) expansions.\n"),
("ztcp", "`ztcp` is implemented as a builtin to allow full use of shell\ncommand line editing, file I/O, and job control mechanisms.\n\nIf `ztcp` is run with no options, it will output\nthe contents of its session table.\n\nIf it is run with only the option `-L`, it will output the contents of\nthe session table in a format suitable for automatic parsing. The option\nis ignored if given with a command to open or close a session. The output\nconsists of a set of lines, one per session, each containing the following\nelements separated by spaces:\n\n\n- **File descriptor** â The file descriptor in use for the connection. For normal inbound (`I`)\nand outbound (`O`) connections this may be read and written by the usual\nshell mechanisms. However, it should only be close with \"ztcp -c\".\n\n\n- **Connection type** âÂÂ\nA letter indicating how the session was created:\n\n- **`Z`** âÂÂ\nA session created with the `zftp` command.\n\n- **`L`** âÂÂ\nA connection opened for listening with \"ztcp -l\".\n\n- **`I`** âÂÂ\nAn inbound connection accepted with \"ztcp -a\".\n\n- **`O`** âÂÂ\nAn outbound connection created with ``ztcp\" _host_ _..._\".\n\n- **The local host** âÂÂ\nThis is usually set to an all-zero IP address as the address of the\nlocalhost is irrelevant.\n\n- **The local port** âÂÂ\nThis is likely to be zero unless the connection is for listening.\n\n- **The remote host** âÂÂ\nThis is the fully qualified domain name of the peer, if available, else an\nIP address. It is an all-zero IP address for a session opened for\nlistening.\n\n- **The remote port** âÂÂ\nThis is zero for a connection opened for listening."),
("ztcp", "Open a new TCP connection to _host_. If the _port_ is\nomitted, it will default to port 23. The connection will\nbe added to the session table and the shell parameter\n`REPLY` will be set to the file descriptor associated\nwith that connection.\n\nIf `-d` is specified, its argument will be taken as the target file\ndescriptor for the connection.\n\nIn order to elicit more verbose output, use `-v`."),
("ztcp", "`ztcp -l` will open a socket listening on TCP\n_port_. The socket will be added to the\nsession table and the shell parameter `REPLY`\nwill be set to the file descriptor associated\nwith that listener.\n\nIf `-d` is specified, its argument will be taken as the target file\ndescriptor for the connection.\n\nIn order to elicit more verbose output, use `-v`."),
("ztcp", "`ztcp -a` will accept an incoming connection\nto the port associated with _listenfd_.\nThe connection will be added to the session\ntable and the shell parameter `REPLY` will\nbe set to the file descriptor associated with\nthe inbound connection.\n\nIf `-d` is specified, its argument\nwill be taken as the target file descriptor for the\nconnection.\n\nIf `-t` is specified, `ztcp` will return\nif no incoming connection is pending. Otherwise\nit will wait for one.\n\nIn order to elicit more verbose output, use `-v`."),
("ztcp", "`ztcp -c` will close the socket associated\nwith _fd_. The socket will be removed from the\nsession table. If _fd_ is not specified,\n`ztcp` will close everything in the session table.\n\nNormally, sockets registered by zftp (see\n_The zsh/zftp Module_ (zshmodules))\ncannot be closed this way. In order\nto force such a socket closed, use `-f`.\n\nIn order to elicit more verbose output, use `-v`."),
("echotc", "Output the termcap value corresponding to the capability\n_cap_, with optional arguments."),
("termcap", "An associative array that maps termcap capability codes to\ntheir values."),
("echoti", "Output the terminfo value corresponding to the capability\n_cap_, instantiated with _arg_ if applicable."),
("terminfo", "An associative array that maps terminfo capability names to\ntheir values."),
("LOGCHECK", "The interval in seconds between checks for login/logout activity\nusing the `watch` parameter."),
("watch", "An array (colon-separated list) of login/logout events to report.\n\nIf it contains the single word \"all\", then all login/logout events\nare reported. If it contains the single word \"notme\", then all\nevents are reported as with \"all\" except `$USERNAME`.\n\nAn entry in this list may consist of a username,\nan \"@\" followed by a remote hostname,\nand a \"%\" followed by a line (tty). Any of these may\nbe a pattern (be sure to quote this during the assignment to\n`watch` so that it does not immediately perform file generation);\nthe setting of the `EXTENDED_GLOB` option is respected.\nAny or all of these components may be present in an entry;\nif a login/logout event matches all of them,\nit is reported.\n\nFor example, with the `EXTENDED_GLOB` option set, the following:\n\nexample(watch=('^(pws|barts)'))\n\ncauses reports for activity associated with any user other than `pws`\nor `barts`."),
("WATCHFMT", "The format of login/logout reports if the `watch` parameter is set.\nDefault is \"%n has %a %l from %m\".\nRecognizes the following escape sequences:\n\n- **`%n`** âÂÂ\nThe name of the user that logged in/out.\n\n- **`%a`** âÂÂ\nThe observed action, i.e. \"logged on\" or \"logged off\".\n\n\n- **`%l`** â The line (tty) the user is logged in on.\n\n\n- **`%M`** âÂÂ\nThe full hostname of the remote host.\n\n- **`%m`** âÂÂ\nThe hostname up to the first \".\". If only the\nIP address is available or the utmp field contains\nthe name of an X-windows display, the whole name is printed.\n\n_NOTE:_\nThe \"%m\" and \"%M\" escapes will work only if there is a host name\nfield in the utmp on your machine. Otherwise they are\ntreated as ordinary strings.\n\n\n- **`%F{`_color_`}` (`%f`)** â Start (stop) using a different foreground color.\n\n\n- **`%K{`_color_`}` (`%k`)** â Start (stop) using a different background color.\n\n\n- **`%S` (`%s`)** â Start (stop) standout mode.\n\n\n- **`%U` (`%u`)** â Start (stop) underline mode.\n\n\n- **`%B` (`%b`)** â Start (stop) boldface mode.\n\n\n- **`%t`**\n\n- **`%@`** âÂÂ\nThe time, in 12-hour, am/pm format.\n\n- **`%T`** âÂÂ\nThe time, in 24-hour format.\n\n- **`%w`** âÂÂ\nThe date in `_day_`-\"_dd_\" format.\n\n- **`%W`** âÂÂ\nThe date in `_mm_`/`_dd_`/\"_yy_\" format.\n\n- **`%D`** âÂÂ\nThe date in `_yy_`-`_mm_`-\"_dd_\" format.\n\n\n- **`%D{`_string_`}`** â The date formatted as _string_ using the `strftime` function, with\nzsh extensions as described for `%D{`_string_`}` escape sequence in\n_Simple Prompt Escapes_ (zshmisc).\n\n\n- **`%()_x_`:`_true-text_`:`_false-text_```** â Specifies a ternary expression.\nThe character following the _x_ is\narbitrary; the same character is used to separate the text\nfor the \"true\" result from that for the \"false\" result.\nBoth the separator and the right parenthesis may be escaped\nwith a backslash.\nTernary expressions may be nested.\n\nThe test character _x_ may be any one of \"l\", \"n\", \"m\"\nor \"M\", which indicate a \"true\" result if the corresponding\nescape sequence would return a non-empty value; or it may be \"a\",\nwhich indicates a \"true\" result if the watched user has logged in,\nor \"false\" if he has logged out.\nOther characters evaluate to neither true nor false; the entire\nexpression is omitted in this case.\n\nIf the result is \"true\", then the _true-text_\nis formatted according to the rules above and printed,\nand the _false-text_ is skipped.\nIf \"false\", the _true-text_ is skipped and the _false-text_\nis formatted and printed.\nEither or both of the branches may be empty, but\nboth separators must be present in any case.\n"),
("log", "List all users currently logged in who are affected by\nthe current setting of the `watch` parameter."),
("zftp", "The `zsh/zftp` module is a client for FTP (file transfer protocol). It\nis implemented as a builtin to allow full use of shell command line\nediting, file I/O, and job control mechanisms. Often, users will\naccess it via shell functions providing a more powerful interface; a set is\nprovided with the `zsh` distribution and is described in\nnmref(Zftp Function System)(zshzftpsys).\nHowever, the `zftp` command is entirely usable in its\nown right.\n\nAll commands consist of the command name `zftp` followed by the name\nof a subcommand. These are listed below. The return status of each\nsubcommand is supposed to reflect the success or failure of the remote\noperation. See a description of the variable `ZFTP_VERBOSE` for\nmore information on how responses from the server may be printed."),
("open", "Open a new FTP session to _host_, which may be the name of a TCP/IP\nconnected host or an IP number in the standard dot notation. If the\nargument is in the form _host_`:`_port_, open a connection to\nTCP port _port_ instead of the standard FTP port 21. This may be\nthe name of a TCP service or a number: see the description of\n`ZFTP_PORT` below for more information.\n\nIf IPv6 addresses in colon format are used, the _host_ should be\nsurrounded by quoted square brackets to distinguish it from the _port_,\nfor example `'[fe80::203:baff:fe02:8b56]'`. For consistency this is\nallowed with all forms of _host_.\n\nRemaining arguments are passed to the `login` subcommand. Note that\nif no arguments beyond _host_ are supplied, `open` will _not_\nautomatically call `login`. If no arguments at all are supplied,\n`open` will use the parameters set by the `params` subcommand.\n\nAfter a successful open, the shell variables `ZFTP_HOST`, `ZFTP_PORT`,\n`ZFTP_IP` and `ZFTP_SYSTEM` are available; see \"Variables\"\nbelow."),
("user", "Login the user _name_ with parameters _password_ and _account_.\nAny of the parameters can be omitted, and will be read from standard\ninput if needed (_name_ is always needed). If\nstandard input is a terminal, a prompt for each one will be printed on\nstandard error and _password_ will not be echoed. If any of the\nparameters are not used, a warning message is printed.\n\nAfter a successful login, the shell variables `ZFTP_USER`,\n`ZFTP_ACCOUNT` and `ZFTP_PWD` are available; see \"Variables\"\nbelow.\n\nThis command may be re-issued when a user is already logged in, and\nthe server will first be reinitialized for a new user."),
("params", "Store the given parameters for a later `open` command with no\narguments. Only those given on the command line will be remembered.\nIf no arguments are given, the parameters currently set are printed,\nalthough the password will appear as a line of stars; the return status is\none if no parameters were set, zero otherwise.\n\nAny of the parameters may be specified as a \"?\", which\nmay need to be quoted to protect it from shell expansion. In this case,\nthe appropriate parameter will be read from stdin as with the\n`login` subcommand, including special handling of _password_. If the\n\"?\" is followed by a string, that is used as the prompt for reading the\nparameter instead of the default message (any necessary punctuation and\nwhitespace should be included at the end of the prompt). The first letter\nof the parameter (only) may be quoted with a \"\\\"; hence an argument\n`\"\\\\$word\"` guarantees that the string from the shell parameter `$word`\nwill be treated literally, whether or not it begins with a \"?\".\n\nIf instead a single \"-\" is given, the existing parameters, if any,\nare deleted. In that case, calling `open` with no arguments will\ncause an error.\n\nThe list of parameters is not deleted after a `close`, however it\nwill be deleted if the `zsh/zftp` module is unloaded.\n\nFor example,\n\n zftp params ftp.elsewhere.xx juser '?Password for juser: '\n\nwill store the host `ftp.elsewhere.xx` and the user `juser` and\nthen prompt the user for the corresponding password with the given prompt."),
("test", "Test the connection; if the server has reported\nthat it has closed the connection (maybe due to a timeout), return\nstatus 2; if no connection was open anyway, return status 1; else\nreturn status 0. The `test` subcommand is\nsilent, apart from messages printed by the `$ZFTP_VERBOSE`\nmechanism, or error messages if the connection closes. There is no\nnetwork overhead for this test.\n\nThe test is only supported on systems with either the\ntt(select+(2+)) or\ntt(poll+(2+)) system calls; otherwise the message ``not\nsupported on this system`' is printed instead.\n\nThe `test` subcommand will automatically be called at the start of any\nother subcommand for the current session when a connection is open."),
("cd", "Change the remote directory to _directory_. Also alters the shell\nvariable `ZFTP_PWD`."),
("cdup", "Change the remote directory to the one higher in the directory tree.\nNote that `cd ..` will also work correctly on non-UNIX systems."),
("dir", "Give a (verbose) listing of the remote directory. The _arg_s are\npassed directly to the server. The command's behaviour is implementation\ndependent, but a UNIX server will typically interpret _arg_s as\narguments to the `ls` command and with no arguments return the\nresult of \"ls -l\". The directory is listed to standard output."),
("ls", "Give a (short) listing of the remote directory. With no _arg_,\nproduces a raw list of the files in the directory, one per line.\nOtherwise, up to vagaries of the server implementation, behaves\nsimilar to `dir`."),
("type", "Change the type for the transfer to _type_, or print the current type\nif _type_ is absent. The allowed values are \"A\" (ASCII),\n\"I\" (Image, i.e. binary), or \"B\" (a synonym for \"I\").\n\nThe FTP default for a transfer is ASCII. However, if `zftp` finds\nthat the remote host is a UNIX machine with 8-bit byes, it will\nautomatically switch to using binary for file transfers upon\n`open`. This can subsequently be overridden.\n\nThe transfer type is only passed to the remote host when a data\nconnection is established; this command involves no network overhead."),
("ascii", "The same as `type A`."),
("binary", "The same as `type I`."),
("mode", "Set the mode type to stream (`S`) or block (`B`). Stream mode is\nthe default; block mode is not widely supported."),
("local", "Print the size and last modification time of the remote or local\nfiles. If there is more than one item on the list, the name of the\nfile is printed first. The first number is the file size, the second\nis the last modification time of the file in the format\n`CCYYMMDDhhmmSS` consisting of year, month, date, hour, minutes and\nseconds in GMT. Note that this format, including the length, is\nguaranteed, so that time strings can be directly compared via the\n`[[\" builtin\"s `<` and `>` operators, even if they are too long\nto be represented as integers.\n\nNot all servers support the commands for retrieving this information.\nIn that case, the `remote` command will print nothing and return\nstatus 2, compared with status 1 for a file not found.\n\nThe `local` command (but not `remote`) may be used with no\narguments, in which case the information comes from examining file\ndescriptor zero. This is the same file as seen by a `put` command\nwith no further redirection."),
("get", "Retrieve all _file_s from the server, concatenating them\nand sending them to standard output."),
("put", "For each _file_, read a file from standard input and send that to\nthe remote host with the given name."),
("append", "As `put`, but if the remote _file_ already exists, data is\nappended to it instead of overwriting it."),
("appendat", "Versions of `get`, `put` and `append` which will start the\ntransfer at the given _point_ in the remote _file_. This is\nuseful for appending to an incomplete local file. However, note that\nthis ability is not universally supported by servers (and is not quite\nthe behaviour specified by the standard)."),
("delete", "Delete the list of files on the server."),
("mkdir", "Create a new directory _directory_ on the server."),
("rmdir", "Delete the directory _directory_ on the server."),
("rename", "Rename file _old-name_ to _new-name_ on the server."),
("site", "Send a host-specific command to the server. You will probably\nonly need this if instructed by the server to use it."),
("quote", "Send the raw FTP command sequence to the server. You should be\nfamiliar with the FTP command set as defined in RFC959 before doing\nthis. Useful commands may include `STAT` and `HELP`. Note also\nthe mechanism for returning messages as described for the variable\n`ZFTP_VERBOSE` below, in particular that all messages from the\ncontrol connection are sent to standard error."),
("quit", "Close the current data connection. This unsets the shell parameters\n`ZFTP_HOST`, `ZFTP_PORT`, `ZFTP_IP`, `ZFTP_SYSTEM`, `ZFTP_USER`,\n`ZFTP_ACCOUNT`, `ZFTP_PWD`, `ZFTP_TYPE` and `ZFTP_MODE`."),
("session", "Allows multiple FTP sessions to be used at once. The name of the session\nis an arbitrary string of characters; the default session is called\n\"default\". If this command is called without an argument, it will list\nall the current sessions; with an argument, it will either switch to the\nexisting session called _sessname_, or create a new session of that name.\n\nEach session remembers the status of the connection, the set of\nconnection-specific shell parameters (the same set as are unset when a\nconnection closes, as given in the description of `close`), and any user\nparameters specified with the `params` subcommand. Changing to a\nprevious session restores those values; changing to a new session\ninitialises them in the same way as if `zftp` had just been loaded. The\nname of the current session is given by the parameter `ZFTP_SESSION`."),
("rmsession", "Delete a session; if a name is not given, the current session is deleted.\nIf the current session is deleted, the earliest existing session becomes\nthe new current session, otherwise the current session is not changed.\nIf the session being deleted is the only one, a new session called\n\"default\" is created and becomes the current session; note that this is\na new session even if the session being deleted is also called\n\"default\". It is recommended that sessions not be deleted while\nbackground commands which use `zftp` are still active."),
("ZFTP_TMOUT", "Integer. The time in seconds to wait for a network operation to\ncomplete before returning an error. If this is not set when the\nmodule is loaded, it will be given the default value 60. A value of\nzero turns off timeouts. If a timeout occurs on the control\nconnection it will be closed. Use a larger value if this occurs too\nfrequently."),
("ZFTP_IP", "Readonly. The IP address of the current connection in dot notation."),
("ZFTP_HOST", "Readonly. The hostname of the current remote server. If the host was\nopened as an IP number, `ZFTP_HOST` contains that instead; this\nsaves the overhead for a name lookup, as IP numbers are most commonly\nused when a nameserver is unavailable."),
("ZFTP_PORT", "Readonly. The number of the remote TCP port to which the connection is\nopen (even if the port was originally specified as a named service).\nUsually this is the standard FTP port, 21.\n\nIn the unlikely event that your system does not have the appropriate\nconversion functions, this appears in network byte order. If your\nsystem is little-endian, the port then consists of two swapped bytes and the\nstandard port will be reported as 5376. In that case, numeric ports passed\nto `zftp open` will also need to be in this format."),
("ZFTP_SYSTEM", "Readonly. The system type string returned by the server in response\nto an FTP `SYST` request. The most interesting case is a string\nbeginning `\"UNIX Type: L8\"`, which ensures maximum compatibility\nwith a local UNIX host."),
("ZFTP_TYPE", "Readonly. The type to be used for data transfers , either \"A\" or\n\"I\". Use the `type` subcommand to change this."),
("ZFTP_USER", "Readonly. The username currently logged in, if any."),
("ZFTP_ACCOUNT", "Readonly. The account name of the current user, if any. Most servers\ndo not require an account name."),
("ZFTP_PWD", "Readonly. The current directory on the server."),
("ZFTP_CODE", "Readonly. The three digit code of the last FTP reply from the server\nas a string. This can still be read after the connection is closed, and\nis not changed when the current session changes."),
("ZFTP_REPLY", "Readonly. The last line of the last reply sent by the server. This\ncan still be read after the connection is closed, and is not changed when\nthe current session changes."),
("ZFTP_SESSION", "Readonly. The name of the current FTP session; see the description of the\n`session` subcommand."),
("ZFTP_PREFS", "A string of preferences for altering aspects of `zftp`'s behaviour.\nEach preference is a single character. The following are defined:\n\n- **`P`** âÂÂ\nPassive: attempt to make the remote server initiate data transfers.\nThis is slightly more efficient than sendport mode. If the letter\n`S` occurs later in the string, `zftp` will use sendport mode if\npassive mode is not available.\n\n- **`S`** âÂÂ\nSendport: initiate transfers by the FTP `PORT` command. If this\noccurs before any `P` in the string, passive mode will never be\nattempted.\n\n\n- **`D`** â Dumb: use only the bare minimum of FTP commands. This prevents\nthe variables `ZFTP_SYSTEM` and `ZFTP_PWD` from being set, and\nwill mean all connections default to ASCII type. It may prevent\n`ZFTP_SIZE` from being set during a transfer if the server\ndoes not send it anyway (many servers do).\n\n\nIf `ZFTP_PREFS` is not set when `zftp` is loaded, it will be set to a\ndefault of \"PS\", i.e. use passive mode if available, otherwise\nfall back to sendport mode."),
("ZFTP_VERBOSE", "A string of digits between 0 and 5 inclusive, specifying which\nresponses from the server should be printed. All responses go to\nstandard error. If any of the numbers 1 to 5 appear in the string,\nraw responses from the server with reply codes beginning with that\ndigit will be printed to standard error. The first digit of the three\ndigit reply code is defined by RFC959 to correspond to:\n\n- **1.** âÂÂ\nA positive preliminary reply.\n\n- **2.** âÂÂ\nA positive completion reply.\n\n- **3.** âÂÂ\nA positive intermediate reply.\n\n- **4.** âÂÂ\nA transient negative completion reply.\n\n- **5.** âÂÂ\nA permanent negative completion reply.\n\nIt should be noted that, for unknown reasons, the reply `Service not\navailable', which forces termination of a connection, is classified as\n421, i.e. \"transient negative\", an interesting interpretation of the word\n\"transient\".\n\nThe code 0 is special: it indicates that all but the last line of\nmultiline replies read from the server will be printed to standard\nerror in a processed format. By convention, servers use this\nmechanism for sending information for the user to read. The\nappropriate reply code, if it matches the same response, takes\npriority.\n\nIf `ZFTP_VERBOSE` is not set when `zftp` is loaded, it will be\nset to the default value `450`, i.e., messages destined for the user\nand all errors will be printed. A null string is valid and\nspecifies that no messages should be printed."),
("zftp_chpwd", "If this function is set by the user, it is called every time the\ndirectory changes on the server, including when a user is logged\nin, or when a connection is closed. In the last case, `$ZFTP_PWD`\nwill be unset; otherwise it will reflect the new directory."),
("zftp_progress", "If this function is set by the user, it will be called during\na `get`, `put` or `append` operation each time sufficient data\nhas been received from the host. During a `get`, the data is sent\nto standard output, so it is vital that this function should write\nto standard error or directly to the terminal, _not_ to standard\noutput.\n\nWhen it is called with a transfer in progress, the following\nadditional shell parameters are set:\n\nvindex(ZFTP_FILE)\n\n- **`ZFTP_FILE`** âÂÂ\nThe name of the remote file being transferred from or to.\n\nvindex(ZFTP_TRANSFER)\n\n- **`ZFTP_TRANSFER`** âÂÂ\nA `G` for a `get` operation and a `P` for a `put` operation.\n\nvindex(ZFTP_SIZE)\n\n- **`ZFTP_SIZE`** âÂÂ\nThe total size of the complete file being transferred:\nthe same as the first value provided by the\n`remote` and `local` subcommands for a particular file.\nIf the server cannot supply this value for a remote file being\nretrieved, it will not be set. If input is from a pipe the value may\nbe incorrect and correspond simply to a full pipe buffer.\n\nvindex(ZFTP_COUNT)\n\n- **`ZFTP_COUNT`** âÂÂ\nThe amount of data so far transferred; a number between zero and\n`$ZFTP_SIZE`, if that is set. This number is always available.\n\nThe function is initially called with `ZFTP_TRANSFER` set\nappropriately and `ZFTP_COUNT` set to zero. After the transfer is\nfinished, the function will be called one more time with\n`ZFTP_TRANSFER` set to `GF` or `PF`, in case it wishes to tidy\nup. It is otherwise never called twice with the same value of\n`ZFTP_COUNT`.\n\nSometimes the progress meter may cause disruption. It is up to the\nuser to decide whether the function should be defined and to use\n`unfunction` when necessary."),
("keymaps", "This array contains the names of the keymaps currently defined."),
("widgets", "This associative array contains one entry per widget. The name\nof the widget is the key and the value gives information about the\nwidget. It is either\n the string \"builtin\" for builtin widgets,\n a string of the form ``user:\"_name_\" for user-defined widgets,\n where _name_ is the name of the shell function implementing the widget,\n a string of the form ``completion:`_type_`:\"_name_\"\n for completion widgets,\n or a null value if the widget is not yet fully defined.\nIn the penultimate case, _type_ is the name of the builtin widget the\ncompletion widget imitates in its behavior and _name_ is the name\nof the shell function implementing the completion widget."),
("zprof", "Without the `-c` option, `zprof` lists profiling results to\nstandard output. The format is comparable to that of commands like\n`gprof`.\n\nAt the top there is a summary listing all functions that were called\nat least once. This summary is sorted in decreasing order of the\namount of time spent in each. The lines contain\nthe number of the function in order, which is used in\nother parts of the list in suffixes of the form\n``[`_num_`]`', then the number of calls made to the function.\nThe next three columns list the time in\nmilliseconds spent in the function and its descendants, the average\ntime in milliseconds spent in the function and its descendants per\ncall and the percentage of time spent in all shell functions used in\nthis function and its descendants. The following three columns give\nthe same information, but counting only the time spent in the function\nitself. The final column shows the name of the function.\n\nAfter the summary, detailed information about every function that was\ninvoked is listed, sorted in decreasing order of the amount of time spent\nin each function and its descendants. Each of these entries consists of\ndescriptions for the functions that called the function described, the\nfunction itself, and the functions that were called from it. The\ndescription for the function itself has the same format as in the summary\n(and shows the same information). The other lines don't show the number of\nthe function at the beginning and have their function named indented to\nmake it easier to distinguish the line showing the function described in\nthe section from the surrounding lines.\n\nThe information shown in this case is almost the same as in the summary,\nbut only refers to the call hierarchy being displayed. For example, for a\ncalling function the column showing the total running time lists the time\nspent in the described function and its descendants only for the times when\nit was called from that particular calling function. Likewise, for a\ncalled function, this columns lists the total time spent in the called\nfunction and its descendants only for the times when it was called from the\nfunction described.\n\nAlso in this case, the column showing the number of calls to a function\nalso shows a slash and then the total number of invocations made to the\ncalled function.\n\nAs long as the `zsh/zprof` module is loaded, profiling will be done and\nmultiple invocations of the `zprof` builtin command will show the\ntimes and numbers of calls since the module was loaded. With the\n`-c` option, the `zprof` builtin command will reset its internal\ncounters and will not show the listing."),
("zpty", "The arguments following _name_ are concatenated with spaces between,\nthen executed as a command, as if passed to the `eval` builtin. The\ncommand runs under a newly assigned pseudo-terminal; this is useful for\nrunning commands non-interactively which expect an interactive\nenvironment. The _name_ is not part of the command, but is used to\nrefer to this command in later calls to `zpty`.\n\nWith the `-e` option, the pseudo-terminal is set up so that input\ncharacters are echoed.\n\nWith the `-b` option, input to and output from the pseudo-terminal are\nmade non-blocking.\n\nThe shell parameter `REPLY` is set to the file descriptor assigned to\nthe master side of the pseudo-terminal. This allows the terminal to be\nmonitored with ZLE descriptor handlers (see the description of option\n`-F` for `zle` builtin in _Zle Builtins_ (zshzle))\nor manipulated with `sysread` and `syswrite` builtins\n(see _The zsh/system Module_ (zshmodules)).\n_Warning_: Use of `sysread`\nand `syswrite` is _not_ recommended; use `zpty -r` and `zpty -w`\nunless you know exactly what you are doing."),
("zpty", "The second form, with the `-d` option, is used to delete commands\npreviously started, by supplying a list of their _name_s. If no\n_name_ is given, all commands are deleted. Deleting a command causes\nthe HUP signal to be sent to the corresponding process."),
("zpty", "The `-w` option can be used to send the to command _name_ the given\n_string_s as input (separated by spaces). If the `-n` option is\n_not_ given, a newline is added at the end.\n\nIf no _string_ is provided, the standard input is copied to the\npseudo-terminal; this may stop before copying the full input if the\npseudo-terminal is non-blocking. The exact input is always copied:\nthe `-n` option is not applied.\n\nNote that the command under the pseudo-terminal sees this input as if it\nwere typed, so beware when sending special tty driver characters such as\nword-erase, line-kill, and end-of-file."),
("zpty", "The `-r` option can be used to read the output of the command _name_.\nWith only a _name_ argument, the output read is copied to the standard\noutput. Unless the pseudo-terminal is non-blocking, copying continues\nuntil the command under the pseudo-terminal exits; when non-blocking, only\nas much output as is immediately available is copied. The return status is\nzero if any output is copied.\n\nWhen also given a _param_ argument, at most one line is read and stored\nin the parameter named _param_. Less than a full line may be read if\nthe pseudo-terminal is non-blocking. The return status is zero if at least\none character is stored in _param_.\n\nIf a _pattern_ is given as well, output is read until the whole string\nread matches the _pattern_, even in the non-blocking case. The return\nstatus is zero if the string read matches the pattern, or if the command\nhas exited but at least one character could still be read. If the option\n`-m` is present, the return status is zero only if the pattern matches.\nAs of this writing, a maximum of one megabyte of output can be consumed\nthis way; if a full megabyte is read without matching the pattern, the\nreturn status is non-zero.\n\nIn all cases, the return status is non-zero if nothing could be read, and\nis `2` if this is because the command has finished.\n\nIf the `-r` option is combined with the `-t` option, `zpty` tests\nwhether output is available before trying to read. If no output is\navailable, `zpty` immediately returns the status `1`. When used\nwith a _pattern_, the behaviour on a failed poll is similar to\nwhen the command has exited: the return value is zero if at least\none character could still be read even if the pattern failed to match."),
("zpty", "The `-t` option without the `-r` option can be used to test\nwhether the command _name_ is still running. It returns a zero\nstatus if the command is running and a non-zero value otherwise."),
("zpty", "The last form, without any arguments, is used to list the commands\ncurrently defined. If the `-L` option is given, this is done in the\nform of calls to the `zpty` builtin."),
("zselect", "The `zselect` builtin is a front-end to the \"select\" system call, which\nblocks until a file descriptor is ready for reading or writing, or has an\nerror condition, with an optional timeout. If this is not available on\nyour system, the command prints an error message and returns status 2\n(normal errors return status 1). For more information, see your system's\ndocumentation for manref(select)(2). Note there is no connection with the\nshell builtin of the same name.\n\nArguments and options may be intermingled in any order. Non-option\narguments are file descriptors, which must be decimal integers. By\ndefault, file descriptors are to be tested for reading, i.e. `zselect`\nwill return when data is available to be read from the file descriptor, or\nmore precisely, when a read operation from the file descriptor will not\nblock. After a `-r`, `-w` and `-e`, the given file descriptors are\nto be tested for reading, writing, or error conditions. These options and\nan arbitrary list of file descriptors may be given in any order.\n\n(The presence of an \"error condition\" is not well defined in the\ndocumentation for many implementations of the select system call.\nAccording to recent versions of the POSIX specification, it is really an\n_exception_ condition, of which the only standard example is out-of-band\ndata received on a socket. So zsh users are unlikely to find the `-e`\noption useful.)\n\nThe option ``-t\" _timeout_\" specifies a timeout in hundredths of a\nsecond. This may be zero, in which case the file descriptors will simply\nbe polled and `zselect` will return immediately. It is possible to call\nzselect with no file descriptors and a non-zero timeout for use as a\nfiner-grained replacement for \"sleep\"; note, however, the return status is\nalways 1 for a timeout.\n\nThe option ``-a\" _array_\" indicates that _array_ should be set to\nindicate the file descriptor+(s+) which are ready. If the option\nis not\ngiven, the array `reply` will be used for this purpose. The array will\ncontain a string similar to the arguments for `zselect`. For example,\n\n zselect -t 0 -r 0 -w 1\n\nmight return immediately with status 0 and `$reply` containing ``-r 0 -w\n1`' to show that both file descriptors are ready for the requested\noperations.\n\nThe option ``-A\" _assoc_\" indicates that the associative array\n_assoc_ should be set to indicate the file descriptor+(s+)\nwhich are ready. This option overrides the option `-a`, nor will\n`reply` be modified. The keys of `assoc` are the file descriptors, and\nthe corresponding values are any of the characters \"rwe\" to indicate\nthe condition.\n\nThe command returns status 0 if some file descriptors are ready for\nreading. If the operation timed out, or a timeout of 0 was given and no\nfile descriptors were ready, or there was an error, it returns status 1 and\nthe array will not be set (nor modified in any way). If there was an error\nin the select operation the appropriate error message is printed."),
("zstyle", "This builtin command is used to define and lookup styles. Styles are\npairs of names and values, where the values consist of any number of\nstrings. They are stored together with patterns and lookup is done by\ngiving a string, called the \"_context_\", which is matched against the\npatterns. The definition stored for the most specific pattern that matches\nwill be returned.\n\nA pattern is considered to be more specific\nthan another if it contains more components (substrings separated by\ncolons) or if the patterns for the components are more specific, where\nsimple strings are considered to be more specific than patterns and\ncomplex patterns are considered to be more specific than the pattern\n\"*\". A \"*\" in the pattern will match zero or more characters\nin the context; colons are not treated specially in this regard.\nIf two patterns are equally specific, the tie is broken in favour of\nthe pattern that was defined first.\n\n_Example_\nkindex(preferred-precipitation, example style)\nfindex(weather, example function)\n\nFor example, a fictional \"weather\" plugin might state in its documentation\nthat it looks up the `preferred-precipitation` style under the\n``:weather:`_continent_`:`_day-of-the-week_`:\"_phase-of-the-moon_\" context.\nAccording to this, you might set the following in your `zshrc`:\n\n zstyle ':weather:europe:*' preferred-precipitation rain\nzstyle ':weather:*:Sunday:*' preferred-precipitation snow\n\nThen the plugin would run under the hood a command such as\n\n zstyle -s \\\n \":weather:${continent}:${day_of_week}:${moon_phase}\" \\\n preferred-precipitation REPLY\n\nin order to retrieve your preference into the scalar variable `$REPLY`.\nOn Sundays `$REPLY` would be set to \"snow\"; in Europe it would be set\nto \"rain\"; and on Sundays in Europe it would be set to \"snow\" again,\nbecause the patterns \":weather:europe:*\" and \":weather:*:Sunday:*\" both\nmatch the _context_ argument to `zstyle -s`, are equally specific, and the\nlatter is more specific (because it has more colon-separated components).\n\n_Usage_\n\nThe forms that operate on patterns are the following.\n\n\n- **`zstyle` [ `-L` [ _metapattern_ [ _style_ ] ] ]** â Without arguments, lists style definitions. Styles\nare shown in alphabetic order and patterns are shown in the order\n`zstyle` will test them.\n\nIf the `-L` option is given, listing is done in the form of calls to\n`zstyle`. The optional first argument, _metapattern_, is a pattern which\nwill be matched against the string supplied as _pattern_ when the style was\ndefined. Note:\nthis means, for example, \"zstyle -L \":completion:*\"\" will\nmatch any supplied pattern beginning \":completion:\", not\njust `\":completion:*\"`: use `':completion:\\*'` to match that.\nThe optional second argument limits the output to a specific _style_ (not a\npattern). `-L` is not compatible with any other options.\n\n\n- **`zstyle` [ `-` | `-``-` | `-e` ] _pattern_ _style_ _string_ ...** â vindex(reply, use of)\nDefines the given _style_ for the _pattern_ with the _string_s as\nthe value. If the `-e` option is given, the _string_s will be\nconcatenated (separated by spaces) and the resulting string will be\nevaluated (in the same way as it is done by the `eval` builtin\ncommand) when the style is looked up. In this case the parameter\n\"reply\" must be assigned to set the strings returned after the\nevaluation. Before evaluating the value, `reply` is unset, and\nif it is still unset after the evaluation, the style is treated as if\nit were not set.\n\n\n- **`zstyle -d` [ _pattern_ [ _style_ ... ] ]** âÂÂ\nDelete style definitions. Without arguments all definitions are deleted,\nwith a _pattern_ all definitions for that pattern are deleted and if\nany _style_s are given, then only those styles are deleted for the\n_pattern_.\n\n- **`zstyle -g` _name_ [ _pattern_ [ _style_ ] ]** âÂÂ\nRetrieve a style definition. The _name_ is\nused as the name of an array in which the results are stored. Without\nany further arguments, all patterns defined are returned. With a\n_pattern_ the styles defined for that pattern are returned and with\nboth a _pattern_ and a _style_, the value strings of that\ncombination is returned.\n\nThe other forms can be used to look up or test styles for a given context.\n\n- **`zstyle -q` _context_ _style_** âÂÂ\nReturn `0` if _style_ is defined in _context_. This does not\nevaluate expressions defined by `zstyle -e` and does not examine any\nvalues set by _style_. The expected use is to test whether a style\nhas been defined for _context_ before asserting a new style.\n\n\n- **`zstyle -s` _context_ _style_ _name_ [ _sep_ ]** â The parameter _name_ is set to the value of the style interpreted as a\nstring. If the value contains several strings they are concatenated with\nspaces (or with the _sep_ string if that is given) between them.\n\nReturn `0` if the style is set, `1` otherwise.\n\n\n- **`zstyle -b` _context_ _style_ _name_** âÂÂ\nThe value is stored in _name_ as a boolean, i.e. as the string\n\"yes\" if the value has only one string and that string is equal to one\nof \"yes\", \"true\", \"on\", or \"1\". If the value is any other\nstring or has more than one string, the parameter is set to \"no\".\n\nReturn `0` if _name_ is set to \"yes\", `1` otherwise.\n\n- **`zstyle -a` _context_ _style_ _name_** âÂÂ\nThe value is stored in _name_ as an array. If _name_ is declared\nas an associative array, the first, third, etc. strings are used as the\nkeys and the other strings are used as the values.\n\nReturn `0` if the style is set, `1` otherwise.\n\n- **`zstyle -t` _context_ _style_ [ _string_ ... ]**\n\n\n- **`zstyle -T` _context_ _style_ [ _string_ ... ]** â Test the value of a style, i.e. the `-t` option only returns a status\n(sets `$?`). Without any _string_ the return status is zero if the\nstyle is defined for at least one matching pattern, has only one string in\nits value, and that is equal to one of \"true\", \"yes\", \"on\" or\n\"1\". If any _string_s are given the status is zero if and only if\nat least one of the _string_s is equal to at least one of the strings\nin the value. If the style is defined but doesn't match, the return status\nis `1`. If the style is not defined, the status is `2`.\n\nThe `-T` option tests the values of the style like `-t`, but it\nreturns status zero (rather than `2`) if the style is not defined for any\nmatching pattern.\n\n- **`zstyle -m` _context_ _style_ _pattern_** âÂÂ\nMatch a value. Returns status zero if the\n_pattern_ matches at least one of the strings in the value."),
("zformat", "This builtin provides different forms of formatting. The first form\nis selected with the `-f` option. In this case the _format_\nstring will be modified by replacing sequences starting with a percent\nsign in it with strings from the _spec_s. Each _spec_ should be\nof the form `_char_`:\"_string_\" which will cause every\nappearance of the sequence ``%\"_char_\" in _format_ to be replaced\nby the _string_. The \"%\" sequence may also contain optional\nminimum and maximum field width specifications between the \"%\" and\nthe \"_char_\" in the form ``%`_min_`.`_max_`c`',\ni.e. the minimum field width is given first and if the maximum field\nwidth is used, it has to be preceded by a dot. Specifying a minimum field\nwidth makes the result be padded with spaces to the right if the\n_string_ is shorter than the requested width. Padding to the left\ncan be achieved by giving a negative minimum field width. If a maximum\nfield width is specified, the _string_ will be truncated after that\nmany characters. After all \"%\" sequences for the given _spec_s\nhave been processed, the resulting string is stored in the parameter\n_param_.\n\nThe `%`-escapes also understand ternary expressions in the form used by\nprompts. The `%` is followed by a \"tt(()\" and then an ordinary\nformat specifier character as described above. There may be a set of\ndigits either before or after the \"tt(()\"; these specify a test\nnumber, which defaults to zero. Negative numbers are also allowed. An\narbitrary delimiter character follows the format specifier, which is\nfollowed by a piece of \"true\" text, the delimiter character again, a piece\nof \"false\" text, and a closing parenthesis. The complete expression\n(without the digits) thus looks like\n`tt(%()_X_`.`_text1_`.`_text2_`\")\", except that\nthe \".\" character is arbitrary. The value given for the format\nspecifier in the _char_`:`_string_ expressions is evaluated as a\nmathematical expression, and compared with the test number. If they are\nthe same, _text1_ is output, else _text2_ is output. A parenthesis\nmay be escaped in _text2_ as `%`). Either of _text1_ or\n_text2_ may contain nested `%`-escapes.\n\nFor example:\n\nexample(zformat -f REPLY \"The answer is '%3(c.yes.no)'.\" c:3)\n\noutputs \"The answer is 'yes'.\" to `REPLY` since the value for the format\nspecifier `c` is 3, agreeing with the digit argument to the ternary\nexpression.\n\nWith `-F` instead of `-f`, ternary expressions choose between the\n\"true\" or \"false\" text on the basis of whether the format specifier is\npresent and non-empty. A test number indicates a minimum width for the\nvalue given in the format specifier. Negative numbers reverse this,\nso the test is for whether the value exceeds a maximum width.\n\nThe form, using the `-a` option, can be used for aligning\nstrings. Here, the _spec_s are of the form\n`_left_`:\"_right_\" where \"_left_\" and \"_right_\" are\narbitrary strings. These strings are modified by replacing the colons\nby the _sep_ string and padding the _left_ strings with spaces\nto the right so that the _sep_ strings in the result (and hence the\n_right_ strings after them) are all aligned if the strings are\nprinted below each other. All strings without a colon are left\nunchanged and all strings with an empty _right_ string have the\ntrailing colon removed. In both cases the lengths of the strings\nare not used to determine how the other strings are to be aligned.\nA colon in the _left_ string can be escaped with a backslash.\nThe resulting strings are stored in the _array_."),
("zregexparse", "This implements some internals of the `_regex_arguments` function."),
("zparseopts", "This builtin simplifies the parsing of options in positional parameters,\ni.e. the set of arguments given by `$*`. Each _spec_ describes one\noption and must be of the form `_opt_[`=\"_array_]\". If an option\ndescribed by _opt_ is found in the positional parameters it is copied\ninto the _array_ specified with the `-a` option; if the optional\n``=\"_array_\" is given, it is instead copied into that array, which\nshould be declared as a normal array and never as an associative array.\n\nNote that it is an error to give any _spec_ without an\n``=\"_array_\" unless one of the `-a` or `-A` options is used.\n\nUnless the `-E` option is given, parsing stops at the first string\nthat isn't described by one of the _spec_s. Even with `-E`,\nparsing always stops at a positional parameter equal to ``-\"-\" or\n(without `-G`) \"-\". See also `-F`.\n\nThe _opt_ description must be one of the following. Any of the special\ncharacters can appear in the option name provided it is preceded by a\nbackslash.\n\n- **_name_**\n\n\n- **_name_`+`** â The _name_ is the name of the option without the leading \"-\". To\nspecify a GNU-style long option, one of the usual two leading \"-\" must\nbe included in _name_; for example, a ``-\"-file\" option is\nrepresented by a _name_ of \"-file\".\n\nIf a \"+\" appears after _name_, the option is appended to _array_\neach time it is found in the positional parameters; without the \"+\"\nonly the _last_ occurrence of the option is preserved.\n\nIf one of these forms is used, the option takes no argument, so parsing\nstops if the next positional parameter does not also begin with \"-\"\n(unless the `-E` option is used).\n\n\n- **_name_`:`**\n\n- **_name_`:-`**\n\n\n- **_name_`::`** â If one or two colons are given, the option takes an argument; with one\ncolon, the argument is mandatory and with two colons it is optional. The\nargument is appended to the _array_ after the option itself.\n\nAn optional argument is put into the same array element as the option name\n(note that this makes empty strings as arguments indistinguishable). A\nmandatory argument is added as a separate element unless the \":-\" form\nis used, in which case the argument is put into the same element.\n\nA \"+\" as described above may appear between the _name_ and the\nfirst colon.\n\n\nBy default, option-arguments may appear either immediately following the\noption in the same positional parameter or in the next one. Even an optional\nargument may appear in the next parameter, unless it begins with a \"-\".\nAdditionally, there is no special consideration given to an \"=\"\nbetween an option and its argument. To make parsing use the more common\nGNU-style conventions, use the `-G` option.\n\nWhen the names of two options that take no arguments overlap, the longest one\nwins, so that parsing for the _spec_s \"-foo -foobar\" (for example) is\nunambiguous. However, due to the aforementioned handling of option-arguments,\nambiguities may arise when at least one overlapping _spec_ takes an\nargument, as in \"-foo: -foobar\". In that case, the last matching\n_spec_ wins. (This is not an issue with GNU-style parsing.)\n\nThe options of `zparseopts` itself cannot be stacked because, for\nexample, the stack \"-DEK\" is indistinguishable from a _spec_ for\nthe GNU-style long option ``-\"-DEK\". The options of `zparseopts`\nitself are:\n\n- **`-a` _array_** âÂÂ\nAs described above, this names the default array in which to store the\nrecognised options.\n\n\n- **`-A` _assoc_** â If this is given, the options and their values are also put into an\nassociative array with the option names as keys and the arguments (if any)\nas the values.\n\n\n- **`-D`** â If this option is given, all options found are removed from the positional\nparameters of the calling shell or shell function, up to but not including\nany not described by the _spec_s. If the first such parameter is\n``-\"-\" or (without `-G`) \"-\", it is removed as well. This is\nsimilar to using the `shift` builtin.\n\n\n- **`-E`** â This changes the parsing rules to _not_ stop at the first string\nthat isn't described by one of the _spec_s. It can be used to test\nfor or (if used together with `-D`) extract options and their\narguments, ignoring all other options and arguments that may be in the\npositional parameters. As indicated above, parsing still stops at the\nfirst \"-\" or ``-\"-\" not described by a _spec_, but it is not\nremoved when used with `-D`.\n)\n\n- **`-F`** â If this option is given, `zparseopts` immediately stops at the first\noption-like parameter not described by one of the _spec_s, prints an\nerror message, and returns status 1. Removal (`-D`) and extraction\n(`-E`) are not performed, and option arrays are not updated. This\nprovides basic validation for the given options.\n\nNote that the appearance in the positional parameters of an option without\nits required argument always aborts parsing and returns an error as described\nabove regardless of whether this option is used.\n\n\n- **`-G`** â This option specifies that options are parsed in the GNU style,\nsimilar to tt(getopt_long+(3+)). In particular:\n\nGiven the _spec_ \"-foo:\", the positional parameter\n``-\"-foo=bar\" is interpreted as option ``-\"-foo\" with\nargument \"bar\", rather than argument \"=bar\" as is the default,\nwhilst the positional parameter ``-\"-foobar\" is considered an\nunknown option (unless another _spec_ describes it). This applies\nto both singly and doubly hyphenated long options.\n\nAn empty option-argument can be given to its long option in the same\nparameter using a trailing \"=\".\n\nAn optional argument to a long option must be given with the\nequals syntax, and an optional argument to a short option must\nfollow it immediately in the same parameter; in both cases the\nfollowing parameter is considered unrelated.\n\nWhenever a long option and its argument are stored in the same array\nelement, an \"=\" is used to separate them.\n\nA mandatory option-argument given in a separate parameter from its\noption (as in ``-``-foo` `bar`'\n, or any option-argument given to\na short option in the same parameter, is always treated the same\nregardless of whether this option is in effect.\n\nLastly, when this option is active, only ``-\"-\" is treated as an\nexplicit option-parsing terminator in the parsed arguments; a single\n\"-\" is considered a normal operand.\n\nNote: Unlike most tt(getopt_long+(3+)) implementations,\n`zparseopts` does not support abbreviating long options.\n)\n\n- **`-K`** âÂÂ\nWith this option, the arrays specified with the `-a` option and with the\n``=\"_array_\" forms are kept unchanged when none of the _spec_s for\nthem is used. Otherwise the entire array is replaced when any of the\n_spec_s is used. Individual elements of associative arrays specified\nwith the `-A` option are preserved by `-K`. This allows assignment of\ndefault values to arrays before calling `zparseopts`.\n\n- **`-M`** âÂÂ\nThis changes the assignment rules to implement a map among equivalent\noption names. If any _spec_ uses the ``=\"_array_\" form, the\nstring _array_ is interpreted as the name of another _spec_,\nwhich is used to choose where to store the values. If no other _spec_\nis found, the values are stored as usual. This changes only the way the\nvalues are stored, not the way `$*` is parsed, so results may be\nunpredictable if the `_name_`+`' specifier is used inconsistently.\n\n- **`-v` _argv_** âÂÂ\nWith this option, the elements of the named array _argv_ are used as the\npositional parameters to parse, rather than those given by `$*`. The\narray may be modified according to the `-D` option.\n\nFor example,\n\n set -- -a -bx -c y -cz baz -cend\nzparseopts a=foo b:=bar c+:=bar\n\nwill have the effect of\n\nexample(foo=(-a)\nbar=(-b x -c y -c z))\n\nThe arguments from \"baz\" on will not be used.\n\nAs an example for the `-E` option, consider:\n\n set -- -a x -b y -c z arg1 arg2\nzparseopts -E -D b:=bar\n\nwill have the effect of\n\nexample(bar=(-b y)\nset -- -a x -c z arg1 arg2)\n\nI.e., the option `-b` and its arguments are taken from the\npositional parameters and put into the array `bar`.\n\nThe `-M` option can be used like this:\n\n set -- -a -bx -c y -cz baz -cend\nzparseopts -A bar -M a=foo b+: c:=b\n\nto have the effect of\n\nexample(foo=(-a)\nbar=(-a '' -b xyz))"),
];
/// Alias → canonical mapping. One entry per surface name
/// that should resolve to the same documentation body.
pub const BUILTIN_ALIASES: &[(&str, &str)] = &[
("ARG1", "ARG1"),
(".", "."),
("NOTRANS(:", "NOTRANS(:"),
("alias", "alias"),
("autoload", "autoload"),
("bg", "bg"),
("break", "break"),
("builtin", "builtin"),
("cd", "cd"),
("command", "command"),
("continue", "continue"),
("dirs", "dirs"),
("disable", "disable"),
("disown", "disown"),
("echo", "echo"),
("emulate", "emulate"),
("enable", "enable"),
("eval", "eval"),
("exec", "exec"),
("exit", "exit"),
("export", "export"),
("false", "false"),
("fc", "fc"),
("fg", "fg"),
("float", "float"),
("functions", "functions"),
("getln", "getln"),
("getopts", "getopts"),
("hash", "hash"),
("integer", "integer"),
("jobs", "jobs"),
("kill", "kill"),
("let", "let"),
("limit", "limit"),
("local", "local"),
("logout", "logout"),
("popd", "popd"),
("print", "print"),
("printf", "printf"),
("pushd", "pushd"),
("pushln", "pushln"),
("pwd", "pwd"),
("read", "read"),
("readonly", "readonly"),
("return", "return"),
("set", "set"),
("setopt", "setopt"),
("shift", "shift"),
("source", "source"),
("suspend", "suspend"),
("test", "test"),
("times", "times"),
("trap", "trap"),
("true", "true"),
("ttyctl", "ttyctl"),
("type", "type"),
("typeset", "typeset"),
("ulimit", "ulimit"),
("umask", "umask"),
("unalias", "unalias"),
("unhash", "unhash"),
("unlimit", "unlimit"),
("unset", "unset"),
("unsetopt", "unsetopt"),
("wait", "wait"),
("whence", "whence"),
("where", "where"),
("which", "which"),
("zcompile", "zcompile"),
("zmodload", "zmodload"),
("bindkey", "bindkey"),
("vared", "vared"),
("zle", "zle"),
("BUFFER", "BUFFER"),
("BUFFERLINES", "BUFFERLINES"),
("CONTEXT", "CONTEXT"),
("CURSOR", "CURSOR"),
("CUTBUFFER", "CUTBUFFER"),
("HISTNO", "HISTNO"),
("ISEARCHMATCH_END", "ISEARCHMATCH_END"),
("KEYMAP", "KEYMAP"),
("KEYS", "KEYS"),
("KEYS_QUEUED_COUNT", "KEYS_QUEUED_COUNT"),
("killring", "killring"),
("LASTABORTEDSEARCH", "LASTABORTEDSEARCH"),
("LASTSEARCH", "LASTSEARCH"),
("LASTWIDGET", "LASTWIDGET"),
("LBUFFER", "LBUFFER"),
("MARK", "MARK"),
("NUMERIC", "NUMERIC"),
("PENDING", "PENDING"),
("PREBUFFER", "PREBUFFER"),
("PREDISPLAY", "PREDISPLAY"),
("POSTDISPLAY", "POSTDISPLAY"),
("RBUFFER", "RBUFFER"),
("REGION_ACTIVE", "REGION_ACTIVE"),
("region_highlight", "region_highlight"),
("registers", "registers"),
("SUFFIX_END", "SUFFIX_END"),
("UNDO_CHANGE_NO", "UNDO_CHANGE_NO"),
("UNDO_LIMIT_NO", "UNDO_LIMIT_NO"),
("WIDGET", "WIDGET"),
("WIDGETFUNC", "WIDGETFUNC"),
("WIDGETSTYLE", "WIDGETSTYLE"),
("YANK_END", "YANK_END"),
("ZLE_RECURSIVE", "ZLE_RECURSIVE"),
("ZLE_STATE", "ZLE_STATE"),
("vi", "vi"),
("backward", "backward"),
("emacs", "emacs"),
("beginning", "beginning"),
("down", "down"),
("end", "end"),
("forward", "forward"),
("up", "up"),
("history", "history"),
("infer", "infer"),
("insert", "insert"),
("capitalize", "capitalize"),
("copy", "copy"),
("delete", "delete"),
("gosmacs", "gosmacs"),
("overwrite", "overwrite"),
("put", "put"),
("quoted", "quoted"),
("quote", "quote"),
("self", "self"),
("transpose", "transpose"),
("yank", "yank"),
("digit", "digit"),
("neg", "neg"),
("universal", "universal"),
("argument", "argument"),
("accept", "accept"),
("complete", "complete"),
("expand", "expand"),
("list", "list"),
("magic", "magic"),
("menu", "menu"),
("reverse", "reverse"),
("auto", "auto"),
("beep", "beep"),
("bracketed", "bracketed"),
("clear", "clear"),
("deactivate", "deactivate"),
("describe", "describe"),
("exchange", "exchange"),
("execute", "execute"),
("get", "get"),
("pound", "pound"),
("push", "push"),
("recursive", "recursive"),
("redisplay", "redisplay"),
("reset", "reset"),
("send", "send"),
("run", "run"),
("spell", "spell"),
("split", "split"),
("undefined", "undefined"),
("undo", "undo"),
("redo", "redo"),
("visual", "visual"),
("what", "what"),
("select", "select"),
("cursor", "cursor"),
("integration", "integration"),
("query", "query"),
("modkeys", "modkeys"),
("default", "default"),
("isearch", "isearch"),
("region", "region"),
("special", "special"),
("suffix", "suffix"),
("paste", "paste"),
("ellipsis", "ellipsis"),
("fg_start_code", "fg_start_code"),
("fg_default_code", "fg_default_code"),
("fg_end_code", "fg_end_code"),
("bg_start_code", "bg_start_code"),
("bg_default_code", "bg_default_code"),
("bg_end_code", "bg_end_code"),
("none", "none"),
("bold", "bold"),
("faint", "faint"),
("standout", "standout"),
("underline", "underline"),
("italic", "italic"),
("hl", "hl"),
("layer", "layer"),
("opacity", "opacity"),
("edit", "edit"),
("pending", "pending"),
("regionstart", "regionstart"),
("regionend", "regionend"),
("compdef", "compdef"),
("accounts", "accounts"),
("all", "all"),
("arguments", "arguments"),
("arrays", "arrays"),
("association", "association"),
("bookmarks", "bookmarks"),
("builtins", "builtins"),
("characters", "characters"),
("colormapids", "colormapids"),
("colors", "colors"),
("commands", "commands"),
("contexts", "contexts"),
("corrections", "corrections"),
("cursors", "cursors"),
("descriptions", "descriptions"),
("devices", "devices"),
("directories", "directories"),
("directory", "directory"),
("displays", "displays"),
("domains", "domains"),
("email", "email"),
("expansions", "expansions"),
("extensions", "extensions"),
("file", "file"),
("files", "files"),
("fonts", "fonts"),
("fstypes", "fstypes"),
("globbed", "globbed"),
("groups", "groups"),
("hosts", "hosts"),
("indexes", "indexes"),
("interfaces", "interfaces"),
("keymaps", "keymaps"),
("keysyms", "keysyms"),
("libraries", "libraries"),
("limits", "limits"),
("mailboxes", "mailboxes"),
("manuals", "manuals"),
("maps", "maps"),
("messages", "messages"),
("modifiers", "modifiers"),
("modules", "modules"),
("my", "my"),
("named", "named"),
("names", "names"),
("newsgroups", "newsgroups"),
("nicknames", "nicknames"),
("options", "options"),
("original", "original"),
("other", "other"),
("packages", "packages"),
("parameters", "parameters"),
("path", "path"),
("paths", "paths"),
("pods", "pods"),
("ports", "ports"),
("prefixes", "prefixes"),
("printers", "printers"),
("processes", "processes"),
("sequences", "sequences"),
("sessions", "sessions"),
("signals", "signals"),
("strings", "strings"),
("styles", "styles"),
("suffixes", "suffixes"),
("tags", "tags"),
("targets", "targets"),
("time", "time"),
("types", "types"),
("urls", "urls"),
("users", "users"),
("values", "values"),
("variant", "variant"),
("visuals", "visuals"),
("warnings", "warnings"),
("widgets", "widgets"),
("windows", "windows"),
("zsh", "zsh"),
("add", "add"),
("ambiguous", "ambiguous"),
("assign", "assign"),
("avoid", "avoid"),
("cache", "cache"),
("call", "call"),
("completer", "completer"),
("condition", "condition"),
("delimiters", "delimiters"),
("disabled", "disabled"),
("environ", "environ"),
("extra", "extra"),
("fake", "fake"),
("filter", "filter"),
("force", "force"),
("format", "format"),
("gain", "gain"),
("glob", "glob"),
("global", "global"),
("group", "group"),
("hidden", "hidden"),
("ignore", "ignore"),
("ignored", "ignored"),
("keep", "keep"),
("known", "known"),
("last", "last"),
("mail", "mail"),
("match", "match"),
("matcher", "matcher"),
("max", "max"),
("muttrc", "muttrc"),
("numbers", "numbers"),
("old", "old"),
("packageset", "packageset"),
("pine", "pine"),
("prefix", "prefix"),
("preserve", "preserve"),
("range", "range"),
("regular", "regular"),
("rehash", "rehash"),
("remote", "remote"),
("remove", "remove"),
("separate", "separate"),
("show", "show"),
("single", "single"),
("sort", "sort"),
("squeeze", "squeeze"),
("stop", "stop"),
("strip", "strip"),
("subst", "subst"),
("substitute", "substitute"),
("tag", "tag"),
("use", "use"),
("verbose", "verbose"),
("word", "word"),
("_all_matches", "_all_matches"),
("_approximate", "_approximate"),
("_canonical_paths", "_canonical_paths"),
("_cmdambivalent", "_cmdambivalent"),
("_cmdstring", "_cmdstring"),
("_complete", "_complete"),
("_correct", "_correct"),
("_expand", "_expand"),
("_expand_alias", "_expand_alias"),
("_extensions", "_extensions"),
("_external_pwds", "_external_pwds"),
("_history", "_history"),
("_ignored", "_ignored"),
("_list", "_list"),
("_match", "_match"),
("_menu", "_menu"),
("_oldlist", "_oldlist"),
("_precommand", "_precommand"),
("_prefix", "_prefix"),
("_user_expand", "_user_expand"),
("_bash_completions", "_bash_completions"),
("_correct_filename", "_correct_filename"),
("_correct_filename (^XC", "_correct_filename"),
("_correct_word", "_correct_word"),
("_expand_alias (^Xa", "_expand_alias"),
("_expand_word", "_expand_word"),
("_expand_word (^Xe", "_expand_word"),
("_generic", "_generic"),
("_history_complete_word", "_history_complete_word"),
("_history_complete_word (\\e/", "_history_complete_word"),
("_most_recent_file", "_most_recent_file"),
("_most_recent_file (^Xm", "_most_recent_file"),
("_next_tags", "_next_tags"),
("_next_tags (^Xn", "_next_tags"),
("_read_comp", "_read_comp"),
("_read_comp (^X^R", "_read_comp"),
("_complete_debug", "_complete_debug"),
("_complete_debug (^X?", "_complete_debug"),
("_complete_help", "_complete_help"),
("_complete_help (^Xh", "_complete_help"),
("_complete_help_generic", "_complete_help_generic"),
("_complete_tag", "_complete_tag"),
("_complete_tag (^Xt", "_complete_tag"),
("_absolute_command_paths", "_absolute_command_paths"),
("_all_labels", "_all_labels"),
("_alternative", "_alternative"),
("_arguments", "_arguments"),
("_as_if", "_as_if"),
("_cache_invalid", "_cache_invalid"),
("_call_function", "_call_function"),
("_call_program", "_call_program"),
("_combination", "_combination"),
("_command_names", "_command_names"),
("_comp_locale", "_comp_locale"),
("_completers", "_completers"),
("_default", "_default"),
("_describe", "_describe"),
("_description", "_description"),
("_dir_list", "_dir_list"),
("_dispatch", "_dispatch"),
("_email_addresses", "_email_addresses"),
("_files", "_files"),
("_gnu_generic", "_gnu_generic"),
("_guard", "_guard"),
("_message", "_message"),
("_multi_parts", "_multi_parts"),
("_next_label", "_next_label"),
("_normal", "_normal"),
("_numbers", "_numbers"),
("_options", "_options"),
("_options_set", "_options_set"),
("_options_unset", "_options_set"),
("_parameters", "_parameters"),
("_path_files", "_path_files"),
("_pick_variant", "_pick_variant"),
("_regex_arguments", "_regex_arguments"),
("_regex_words", "_regex_words"),
("_regex_words [ tt(-t", "_regex_words"),
("_requested", "_requested"),
("_retrieve_cache", "_retrieve_cache"),
("_sep_parts", "_sep_parts"),
("_sequence", "_sequence"),
("_setup", "_setup"),
("_unshadow", "_unshadow"),
("_shadow", "_unshadow"),
("_store_cache", "_store_cache"),
("_tags", "_tags"),
("_tilde_files", "_tilde_files"),
("_values", "_values"),
("_wanted", "_wanted"),
("_widgets", "_widgets"),
("_comp_caller_options", "_comp_caller_options"),
("_comp_priv_prefix", "_comp_priv_prefix"),
("Base", "Base"),
("Zsh", "Zsh"),
("Unix", "Unix"),
("X", "X"),
("CURRENT", "CURRENT"),
("IPREFIX", "IPREFIX"),
("ISUFFIX", "ISUFFIX"),
("PREFIX", "PREFIX"),
("QIPREFIX", "QIPREFIX"),
("QISUFFIX", "QISUFFIX"),
("SUFFIX", "SUFFIX"),
("compstate", "compstate"),
("words", "words"),
("compadd", "compadd"),
("compset", "compset"),
("compcall", "compcall"),
("M", "M"),
("E", "E"),
("R", "R"),
("x", "x"),
("zrecompile", "zrecompile"),
("reporter", "reporter"),
("add-zsh-hook", "add"),
("add-zle-hook-widget", "add"),
("recent", "recent"),
("g", "g"),
("p", "p"),
("s", "s"),
("formats", "formats"),
("actionformats", "actionformats"),
("branchformat", "branchformat"),
("nvcsformats", "nvcsformats"),
("hgrevformat", "hgrevformat"),
("quilt", "quilt"),
("quiltcommand", "quiltcommand"),
("check", "check"),
("stagedstr", "stagedstr"),
("unstagedstr", "unstagedstr"),
("debug", "debug"),
("hooks", "hooks"),
("nopatch", "nopatch"),
("vcs_info", "vcs_info"),
("vcs_info_hookadd", "vcs_info_hookadd"),
("vcs_info_hookdel", "vcs_info_hookdel"),
("vcs_info_lastmsg", "vcs_info_lastmsg"),
("vcs_info_printsys", "vcs_info_printsys"),
("vcs_info_setsys", "vcs_info_setsys"),
("ret", "ret"),
("hook_com", "hook_com"),
("context", "context"),
("vcs", "vcs"),
("start", "start"),
("pre", "pre"),
("gen", "gen"),
("no", "no"),
("post", "post"),
("prompt", "prompt"),
("prompt_", "prompt_"),
("cycle", "cycle"),
("incarg", "incarg"),
("incremental", "incremental"),
("narrow", "narrow"),
("predict", "predict"),
("replace", "replace"),
("smart", "smart"),
("url", "url"),
("zcalc", "zcalc"),
("modify", "modify"),
("toggle", "toggle"),
("widget", "widget"),
("throw", "throw"),
("catch", "catch"),
("zsh-mime-setup", "zsh"),
("zsh-mime-handler", "zsh"),
("pick", "pick"),
("pick-web-browser", "pick"),
("zmathfunc", "zmathfunc"),
("min", "zmathfunc"),
("sum", "zmathfunc"),
("zmathfuncdef", "zmathfuncdef"),
("fned", "fned"),
("histed", "histed"),
("is", "is"),
("is-at-least", "is"),
("rmshadow", "rmshadow"),
("mkshadow", "rmshadow"),
("nslookup", "nslookup"),
("regexp", "regexp"),
("regexp-replace", "regexp"),
("run-help", "run"),
("tetris", "tetris"),
("tetriscurses", "tetriscurses"),
("zargs", "zargs"),
("zed", "zed"),
("zln", "zln"),
("zcp", "zln"),
("zkbd", "zkbd"),
("zmv", "zmv"),
("zstyle", "zstyle"),
("zstyle+", "zstyle"),
("pager", "pager"),
("rprompt", "rprompt"),
("zfparams", "zfparams"),
("zfopen", "zfopen"),
("zfanon", "zfanon"),
("zfcd", "zfcd"),
("zfhere", "zfhere"),
("zfdir", "zfdir"),
("zfls", "zfls"),
("zftype", "zftype"),
("zfstat", "zfstat"),
("zfget", "zfget"),
("zfuget", "zfuget"),
("zfcget", "zfcget"),
("zfgcp", "zfgcp"),
("zfput", "zfput"),
("zfuput", "zfuput"),
("zfcput", "zfcput"),
("zfpcp", "zfpcp"),
("zfclose", "zfclose"),
("zfsession", "zfsession"),
("zftransfer", "zftransfer"),
("zfmark", "zfmark"),
("zfgoto", "zfgoto"),
("zfinit", "zfinit"),
("zfautocheck", "zfautocheck"),
("zfcd_match", "zfcd_match"),
("zfget_match", "zfget_match"),
("zfrglob", "zfrglob"),
("zfrtime", "zfrtime"),
("zftp_chpwd", "zftp_chpwd"),
("zftp_progress", "zftp_progress"),
("zffcache", "zffcache"),
("progress", "progress"),
("update", "update"),
("titlebar", "titlebar"),
("chpwd", "chpwd"),
("calendar", "calendar"),
("calendar_add", "calendar_add"),
("calendar_edit", "calendar_edit"),
("calendar_parse", "calendar_parse"),
("calendar_showdate", "calendar_showdate"),
("calendar_sort", "calendar_sort"),
("age", "age"),
("before", "before"),
("date", "date"),
("done", "done"),
("reformat", "reformat"),
("warn", "warn"),
("calendar_lockfiles", "calendar_lockfiles"),
("calendar_read", "calendar_read"),
("calendar_scandate", "calendar_scandate"),
("calendar_show", "calendar_show"),
("tcp_open", "tcp_open"),
("tcp_close", "tcp_close"),
("tcp_read", "tcp_read"),
("tcp_send", "tcp_send"),
("tcp_alias", "tcp_alias"),
("tcp_log", "tcp_log"),
("tcp_rename", "tcp_rename"),
("tcp_sess", "tcp_sess"),
("tcp_command", "tcp_command"),
("tcp_expect", "tcp_expect"),
("tcp_proxy", "tcp_proxy"),
("tcp_spam", "tcp_spam"),
("tcp_talk", "tcp_talk"),
("tcp_wait", "tcp_wait"),
("tcp_shoot", "tcp_shoot"),
("tcp_on_alias", "tcp_on_alias"),
("tcp_on_awol", "tcp_on_awol"),
("tcp_on_close", "tcp_on_close"),
("tcp_on_open", "tcp_on_open"),
("tcp_on_rename", "tcp_on_rename"),
("tcp_on_spam", "tcp_on_spam"),
("tcp_on_unalias", "tcp_on_unalias"),
("tcp_fd_handler", "tcp_fd_handler"),
("tcp_output", "tcp_output"),
("tcp_expect_lines", "tcp_expect_lines"),
("tcp_filter", "tcp_filter"),
("TCP_HANDLER_ACTIVE", "TCP_HANDLER_ACTIVE"),
("TCP_LINE", "TCP_LINE"),
("TCP_LINE_FD", "TCP_LINE_FD"),
("tcp_lines", "tcp_lines"),
("TCP_LOG", "TCP_LOG"),
("TCP_LOG_SESS", "TCP_LOG_SESS"),
("tcp_no_spam_list", "tcp_no_spam_list"),
("TCP_OUTPUT", "TCP_OUTPUT"),
("TCP_PROMPT", "TCP_PROMPT"),
("TCP_READ_DEBUG", "TCP_READ_DEBUG"),
("TCP_SECONDS_START", "TCP_SECONDS_START"),
("TCP_SESS", "TCP_SESS"),
("TCP_SILENT", "TCP_SILENT"),
("tcp_spam_list", "tcp_spam_list"),
("TCP_TALK_ESCAPE", "TCP_TALK_ESCAPE"),
("TCP_TIMEOUT", "TCP_TIMEOUT"),
("tcp_on_read", "tcp_on_read"),
("tcp_aliases", "tcp_aliases"),
("tcp_by_fd", "tcp_by_fd"),
("tcp_by_name", "tcp_by_name"),
("zgetattr", "zgetattr"),
("zsetattr", "zsetattr"),
("zdelattr", "zdelattr"),
("zlistattr", "zlistattr"),
("cap", "cap"),
("getcap", "getcap"),
("setcap", "setcap"),
("clone", "clone"),
("fi", "fi"),
("di", "di"),
("ln", "ln"),
("pi", "pi"),
("so", "so"),
("bd", "bd"),
("or", "or"),
("mi", "mi"),
("su", "su"),
("sg", "sg"),
("tw", "tw"),
("ow", "ow"),
("sa", "sa"),
("st", "st"),
("ex", "ex"),
("lc", "lc"),
("rc", "rc"),
("tc", "tc"),
("sp", "sp"),
("ec", "ec"),
("comparguments", "comparguments"),
("compdescribe", "compdescribe"),
("compfiles", "compfiles"),
("compgroups", "compgroups"),
("compquote", "compquote"),
("comptry", "comptry"),
("comptags", "comptry"),
("compvalues", "compvalues"),
("zcurses", "zcurses"),
("ZCURSES_COLORS", "ZCURSES_COLORS"),
("ZCURSES_COLOR_PAIRS", "ZCURSES_COLOR_PAIRS"),
("zcurses_attrs", "zcurses_attrs"),
("zcurses_colors", "zcurses_colors"),
("zcurses_keycodes", "zcurses_keycodes"),
("zcurses_windows", "zcurses_windows"),
("strftime", "strftime"),
("EPOCHREALTIME", "EPOCHREALTIME"),
("EPOCHSECONDS", "EPOCHSECONDS"),
("epochtime", "epochtime"),
("ztie", "ztie"),
("zuntie", "zuntie"),
("zgdbmpath", "zgdbmpath"),
("zgdbm_tied", "zgdbm_tied"),
("zap", "zap"),
("example", "example"),
("chgrp", "chgrp"),
("chmod", "chmod"),
("chown", "chown"),
("mkdir", "mkdir"),
("mv", "mv"),
("rm", "rm"),
("rmdir", "rmdir"),
("sync", "sync"),
("nameref", "nameref"),
("namespace", "namespace"),
("var", "var"),
("langinfo", "langinfo"),
("mapfile", "mapfile"),
("dis_functions", "dis_functions"),
("functions_source", "functions_source"),
("dis_functions_source", "dis_functions_source"),
("dis_builtins", "dis_builtins"),
("reswords", "reswords"),
("dis_reswords", "dis_reswords"),
("patchars", "patchars"),
("dis_patchars", "dis_patchars"),
("aliases", "aliases"),
("dis_aliases", "dis_aliases"),
("galiases", "galiases"),
("dis_galiases", "dis_galiases"),
("saliases", "saliases"),
("dis_saliases", "dis_saliases"),
("dirstack", "dirstack"),
("historywords", "historywords"),
("jobdirs", "jobdirs"),
("jobtexts", "jobtexts"),
("jobstates", "jobstates"),
("nameddirs", "nameddirs"),
("userdirs", "userdirs"),
("usergroups", "usergroups"),
("funcfiletrace", "funcfiletrace"),
("funcsourcetrace", "funcsourcetrace"),
("funcstack", "funcstack"),
("functrace", "functrace"),
("pcre_compile", "pcre_compile"),
("pcre_study", "pcre_study"),
("pcre_match", "pcre_match"),
("pcre-match", "pcre-match"),
("private", "private"),
("SRANDOM", "SRANDOM"),
("zrand_float", "zrand_float"),
("zrand_int", "zrand_int"),
("regex-match", "regex-match"),
("sched", "sched"),
("zsh_scheduled_events", "zsh_scheduled_events"),
("zsocket", "zsocket"),
("stat", "stat"),
("zstat", "stat"),
("syserror", "syserror"),
("sysopen", "sysopen"),
("sysread", "sysread"),
("sysseek", "sysseek"),
("syswrite", "syswrite"),
("zsystem", "zsystem"),
("systell", "systell"),
("errnos", "errnos"),
("sysparams", "sysparams"),
("ztcp", "ztcp"),
("echotc", "echotc"),
("termcap", "termcap"),
("echoti", "echoti"),
("terminfo", "terminfo"),
("LOGCHECK", "LOGCHECK"),
("watch", "watch"),
("WATCHFMT", "WATCHFMT"),
("log", "log"),
("zftp", "zftp"),
("open", "open"),
("user", "user"),
("params", "params"),
("cdup", "cdup"),
("dir", "dir"),
("ls", "ls"),
("ascii", "ascii"),
("binary", "binary"),
("mode", "mode"),
("append", "append"),
("appendat", "appendat"),
("rename", "rename"),
("site", "site"),
("quit", "quit"),
("session", "session"),
("rmsession", "rmsession"),
("ZFTP_TMOUT", "ZFTP_TMOUT"),
("ZFTP_IP", "ZFTP_IP"),
("ZFTP_HOST", "ZFTP_HOST"),
("ZFTP_PORT", "ZFTP_PORT"),
("ZFTP_SYSTEM", "ZFTP_SYSTEM"),
("ZFTP_TYPE", "ZFTP_TYPE"),
("ZFTP_USER", "ZFTP_USER"),
("ZFTP_ACCOUNT", "ZFTP_ACCOUNT"),
("ZFTP_PWD", "ZFTP_PWD"),
("ZFTP_CODE", "ZFTP_CODE"),
("ZFTP_REPLY", "ZFTP_REPLY"),
("ZFTP_SESSION", "ZFTP_SESSION"),
("ZFTP_PREFS", "ZFTP_PREFS"),
("ZFTP_VERBOSE", "ZFTP_VERBOSE"),
("zprof", "zprof"),
("zpty", "zpty"),
("zselect", "zselect"),
("zformat", "zformat"),
("zregexparse", "zregexparse"),
("zparseopts", "zparseopts"),
];
/// Resolve a builtin name (case-insensitive, alias-aware)
/// to its canonical name + markdown body.
pub fn lookup_builtin_doc(name: &str) -> Option<(&'static str, &'static str)> {
let key = name.to_string();
let canon = BUILTIN_ALIASES
.iter()
.find(|(a, _)| *a == key.as_str())
.map(|(_, c)| *c)?;
BUILTIN_DOCS.iter().find(|(n, _)| *n == canon).map(|&(n, d)| (n, d))
}