{ "content": [ { "type": "text", "text": "# zshcompsys (man)\n\n## NAME\n\nzshcompsys - zsh completion system\n\n## DESCRIPTION\n\nThis describes the shell code for the `new' completion system, referred to as compsys. It is\nwritten in shell functions based on the features described in zshcompwid(1).\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **INITIALIZATION** (18 subsections)\n- **COMPLETION SYSTEM CONFIGURATION** (158 subsections)\n- **CONTROL FUNCTIONS** (16 subsections)\n- **BINDABLE COMMANDS** (3 subsections)\n- **UTILITY FUNCTIONS** (9 subsections)\n- **COMPLETION SYSTEM VARIABLES** (2 subsections)\n- **COMPLETION DIRECTORIES**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "zshcompsys", "section": "", "mode": "man", "summary": "zshcompsys - zsh completion system", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 54, "subsections": [] }, { "name": "INITIALIZATION", "lines": 24, "subsections": [ { "name": "Use of compinit", "lines": 60 }, { "name": "Autoloaded files", "lines": 82 }, { "name": "-array-value-", "lines": 2 }, { "name": "-assign-parameter-", "lines": 2 }, { "name": "-brace-parameter-", "lines": 2 }, { "name": "-command-", "lines": 2 }, { "name": "-condition-", "lines": 2 }, { "name": "-default-", "lines": 2 }, { "name": "-equal-", "lines": 2 }, { "name": "-first-", "lines": 6 }, { "name": "-math-", "lines": 1 }, { "name": "-parameter-", "lines": 2 }, { "name": "-redirect-", "lines": 2 }, { "name": "-subscript-", "lines": 2 }, { "name": "-tilde-", "lines": 2 }, { "name": "-value-", "lines": 3 }, { "name": "-_ -", "lines": 42 }, { "name": "Functions", "lines": 67 } ] }, { "name": "COMPLETION SYSTEM CONFIGURATION", "lines": 3, "subsections": [ { "name": "Overview", "lines": 149 }, { "name": "Standard Tags", "lines": 3 }, { "name": "accounts", "lines": 2 }, { "name": "all-expansions", "lines": 3 }, { "name": "all-files", "lines": 3 }, { "name": "arguments", "lines": 4 }, { "name": "association-keys", "lines": 3 }, { "name": "bookmarks", "lines": 2 }, { "name": "builtins", "lines": 2 }, { "name": "characters", "lines": 3 }, { "name": "colormapids", "lines": 4 }, { "name": "commands", "lines": 3 }, { "name": "contexts", "lines": 2 }, { "name": "corrections", "lines": 2 }, { "name": "cursors", "lines": 2 }, { "name": "default", "lines": 4 }, { "name": "descriptions", "lines": 3 }, { "name": "devices", "lines": 2 }, { "name": "directories", "lines": 3 }, { "name": "directory-stack", "lines": 2 }, { "name": "displays", "lines": 2 }, { "name": "domains", "lines": 5 }, { "name": "expansions", "lines": 3 }, { "name": "extensions", "lines": 2 }, { "name": "file-descriptors", "lines": 6 }, { "name": "fstypes", "lines": 2 }, { "name": "functions", "lines": 3 }, { "name": "globbed-files", "lines": 4 }, { "name": "history-words", "lines": 4 }, { "name": "indexes", "lines": 2 }, { "name": "interfaces", "lines": 4 }, { "name": "keymaps", "lines": 2 }, { "name": "keysyms", "lines": 2 }, { "name": "libraries", "lines": 4 }, { "name": "local-directories", "lines": 4 }, { "name": "mailboxes", "lines": 2 }, { "name": "manuals", "lines": 4 }, { "name": "messages", "lines": 2 }, { "name": "modifiers", "lines": 2 }, { "name": "modules", "lines": 2 }, { "name": "my-accounts", "lines": 2 }, { "name": "named-directories", "lines": 4 }, { "name": "newsgroups", "lines": 2 }, { "name": "nicknames", "lines": 2 }, { "name": "options", "lines": 2 }, { "name": "original", "lines": 3 }, { "name": "other-accounts", "lines": 2 }, { "name": "packages", "lines": 2 }, { "name": "parameters", "lines": 2 }, { "name": "path-directories", "lines": 9 }, { "name": "prefixes", "lines": 2 }, { "name": "printers", "lines": 2 }, { "name": "processes", "lines": 2 }, { "name": "processes-names", "lines": 2 }, { "name": "sequences", "lines": 2 }, { "name": "sessions", "lines": 2 }, { "name": "signals", "lines": 2 }, { "name": "strings", "lines": 4 }, { "name": "suffixes", "lines": 4 }, { "name": "targets", "lines": 2 }, { "name": "time-zones", "lines": 10 }, { "name": "variant", "lines": 3 }, { "name": "visuals", "lines": 2 }, { "name": "warnings", "lines": 2 }, { "name": "widgets", "lines": 2 }, { "name": "windows", "lines": 2 }, { "name": "zsh-options", "lines": 2 }, { "name": "Standard Styles", "lines": 14 }, { "name": "accept-exact", "lines": 18 }, { "name": "accept-exact-dirs", "lines": 18 }, { "name": "add-space", "lines": 10 }, { "name": "ambiguous", "lines": 5 }, { "name": "assign-list", "lines": 7 }, { "name": "auto-description", "lines": 6 }, { "name": "avoid-completer", "lines": 9 }, { "name": "cache-path", "lines": 5 }, { "name": "cache-policy", "lines": 3 }, { "name": "call-command", "lines": 6 }, { "name": "command", "lines": 21 }, { "name": "command-path", "lines": 3 }, { "name": "commands", "lines": 6 }, { "name": "complete", "lines": 4 }, { "name": "complete-options", "lines": 6 }, { "name": "completer", "lines": 25 }, { "name": "condition", "lines": 3 }, { "name": "delimiters", "lines": 6 }, { "name": "disabled", "lines": 3 }, { "name": "domains", "lines": 3 }, { "name": "environ", "lines": 17 }, { "name": "extra-verbose", "lines": 13 }, { "name": "fake-always", "lines": 20 }, { "name": "fake-files", "lines": 14 }, { "name": "fake-parameters", "lines": 7 }, { "name": "file-list", "lines": 30 }, { "name": "file-patterns", "lines": 54 }, { "name": "file-sort", "lines": 11 }, { "name": "file-split-chars", "lines": 13 }, { "name": "force-list", "lines": 36 }, { "name": "gain-privileges", "lines": 13 }, { "name": "group-name", "lines": 25 }, { "name": "group-order", "lines": 25 }, { "name": "hosts-ports", "lines": 4 }, { "name": "ignore-line", "lines": 16 }, { "name": "ignore-parents", "lines": 24 }, { "name": "ignored-patterns", "lines": 11 }, { "name": "insert-ids", "lines": 12 }, { "name": "insert-sections", "lines": 18 }, { "name": "insert-tab", "lines": 16 }, { "name": "insert-unambiguous", "lines": 14 }, { "name": "keep-prefix", "lines": 11 }, { "name": "known-hosts-files", "lines": 4 }, { "name": "last-prompt", "lines": 12 }, { "name": "list-colors", "lines": 23 }, { "name": "list-dirs-first", "lines": 4 }, { "name": "list-grouped", "lines": 6 }, { "name": "list-packed", "lines": 4 }, { "name": "list-prompt", "lines": 22 }, { "name": "list-rows-first", "lines": 4 }, { "name": "list-separator", "lines": 4 }, { "name": "list-suffixes", "lines": 19 }, { "name": "mail-directory", "lines": 3 }, { "name": "match-original", "lines": 6 }, { "name": "matcher", "lines": 9 }, { "name": "matcher-list", "lines": 56 }, { "name": "max-errors", "lines": 22 }, { "name": "max-matches-width", "lines": 62 }, { "name": "numbers", "lines": 6 }, { "name": "old-list", "lines": 22 }, { "name": "old-matches", "lines": 9 }, { "name": "old-menu", "lines": 12 }, { "name": "original", "lines": 7 }, { "name": "packageset", "lines": 14 }, { "name": "path-completion", "lines": 11 }, { "name": "pine-directory", "lines": 7 }, { "name": "prefix-hidden", "lines": 6 }, { "name": "prefix-needed", "lines": 19 }, { "name": "preserve-prefix", "lines": 19 }, { "name": "recursive-files", "lines": 18 }, { "name": "regular", "lines": 10 }, { "name": "remote-access", "lines": 6 }, { "name": "remove-all-dups", "lines": 4 }, { "name": "select-prompt", "lines": 6 }, { "name": "select-scroll", "lines": 8 }, { "name": "separate-sections", "lines": 10 }, { "name": "show-ambiguity", "lines": 6 }, { "name": "show-completer", "lines": 5 }, { "name": "single-ignored", "lines": 24 }, { "name": "special-dirs", "lines": 11 }, { "name": "squeeze-slashes", "lines": 10 }, { "name": "strip-comments", "lines": 5 }, { "name": "subst-globs-only", "lines": 7 }, { "name": "substitute", "lines": 11 }, { "name": "tag-order", "lines": 148 }, { "name": "use-cache", "lines": 4 }, { "name": "use-compctl", "lines": 25 }, { "name": "users-hosts", "lines": 11 }, { "name": "users-hosts-ports", "lines": 3 }, { "name": "verbose", "lines": 10 } ] }, { "name": "CONTROL FUNCTIONS", "lines": 24, "subsections": [ { "name": "_all_matches", "lines": 24 }, { "name": "_approximate", "lines": 58 }, { "name": "_cmdambivalent", "lines": 8 }, { "name": "_cmdstring", "lines": 2 }, { "name": "_complete", "lines": 27 }, { "name": "_correct", "lines": 27 }, { "name": "_expand", "lines": 24 }, { "name": "_expand_alias", "lines": 6 }, { "name": "_extensions", "lines": 6 }, { "name": "_external_pwds", "lines": 6 }, { "name": "_history", "lines": 5 }, { "name": "_ignored", "lines": 35 }, { "name": "_oldlist", "lines": 8 }, { "name": "_precommand", "lines": 3 }, { "name": "_prefix", "lines": 33 }, { "name": "_user_expand", "lines": 24 } ] }, { "name": "BINDABLE COMMANDS", "lines": 4, "subsections": [ { "name": "_bash_completions", "lines": 43 }, { "name": "_generic", "lines": 66 }, { "name": "_complete_help_generic", "lines": 39 } ] }, { "name": "UTILITY FUNCTIONS", "lines": 6, "subsections": [ { "name": "_absolute_command_paths", "lines": 694 }, { "name": "_comp_locale", "lines": 13 }, { "name": "_default", "lines": 152 }, { "name": "_gnu_generic", "lines": 182 }, { "name": "_options", "lines": 14 }, { "name": "_parameters", "lines": 8 }, { "name": "_path_files", "lines": 247 }, { "name": "_sep_parts", "lines": 69 }, { "name": "_tilde_files", "lines": 114 } ] }, { "name": "COMPLETION SYSTEM VARIABLES", "lines": 5, "subsections": [ { "name": "_comp_caller_options", "lines": 7 }, { "name": "_comp_priv_prefix", "lines": 9 } ] }, { "name": "COMPLETION DIRECTORIES", "lines": 26, "subsections": [] } ], "sections": { "NAME": { "content": "zshcompsys - zsh completion system\n", "subsections": [] }, "DESCRIPTION": { "content": "This describes the shell code for the `new' completion system, referred to as compsys. It is\nwritten in shell functions based on the features described in zshcompwid(1).\n\nThe features are contextual, sensitive to the point at which completion is started. Many\ncompletions are already provided. For this reason, a user can perform a great many tasks\nwithout knowing any details beyond how to initialize the system, which is described below in\nINITIALIZATION.\n\nThe context that decides what completion is to be performed may be\n• an argument or option position: these describe the position on the command line at\nwhich completion is requested. For example `first argument to rmdir, the word being\ncompleted names a directory';\n\n\n• a special context, denoting an element in the shell's syntax. For example `a word in\ncommand position' or `an array subscript'.\n\n\nA full context specification contains other elements, as we shall describe.\n\nBesides commands names and contexts, the system employs two more concepts, styles and tags.\nThese provide ways for the user to configure the system's behaviour.\n\nTags play a dual role. They serve as a classification system for the matches, typically in‐\ndicating a class of object that the user may need to distinguish. For example, when complet‐\ning arguments of the ls command the user may prefer to try files before directories, so both\nof these are tags. They also appear as the rightmost element in a context specification.\n\nStyles modify various operations of the completion system, such as output formatting, but\nalso what kinds of completers are used (and in what order), or which tags are examined.\nStyles may accept arguments and are manipulated using the zstyle command described in zshmod‐\nules(1).\n\nIn summary, tags describe what the completion objects are, and style how they are to be com‐\npleted. At various points of execution, the completion system checks what styles and/or tags\nare defined for the current context, and uses that to modify its behavior. The full descrip‐\ntion of context handling, which determines how tags and other elements of the context influ‐\nence the behaviour of styles, is described below in COMPLETION SYSTEM CONFIGURATION.\n\nWhen a completion is requested, a dispatcher function is called; see the description of\nmaincomplete in the list of control functions below. This dispatcher decides which function\nshould be called to produce the completions, and calls it. The result is passed to one or\nmore completers, functions that implement individual completion strategies: simple comple‐\ntion, error correction, completion with error correction, menu selection, etc.\n\nMore generally, the shell functions contained in the completion system are of two types:\n• those beginning `comp' are to be called directly; there are only a few of these;\n\n\n• those beginning `' are called by the completion code. The shell functions of this\nset, which implement completion behaviour and may be bound to keystrokes, are referred\nto as `widgets'. These proliferate as new completions are required.\n\n", "subsections": [] }, "INITIALIZATION": { "content": "If the system was installed completely, it should be enough to call the shell function\ncompinit from your initialization file; see the next section. However, the function compin‐\nstall can be run by a user to configure various aspects of the completion system.\n\nUsually, compinstall will insert code into .zshrc, although if that is not writable it will\nsave it in another file and tell you that file's location. Note that it is up to you to make\nsure that the lines added to .zshrc are actually run; you may, for example, need to move them\nto an earlier place in the file if .zshrc usually returns early. So long as you keep them\nall together (including the comment lines at the start and finish), you can rerun compinstall\nand it will correctly locate and modify these lines. Note, however, that any code you add to\nthis section by hand is likely to be lost if you rerun compinstall, although lines using the\ncommand `zstyle' should be gracefully handled.\n\nThe new code will take effect next time you start the shell, or run .zshrc by hand; there is\nalso an option to make them take effect immediately. However, if compinstall has removed de‐\nfinitions, you will need to restart the shell to see the changes.\n\nTo run compinstall you will need to make sure it is in a directory mentioned in your fpath\nparameter, which should already be the case if zsh was properly configured as long as your\nstartup files do not remove the appropriate directories from fpath. Then it must be au‐\ntoloaded (`autoload -U compinstall' is recommended). You can abort the installation any time\nyou are being prompted for information, and your .zshrc will not be altered at all; changes\nonly take place right at the end, where you are specifically asked for confirmation.\n", "subsections": [ { "name": "Use of compinit", "content": "This section describes the use of compinit to initialize completion for the current session\nwhen called directly; if you have run compinstall it will be called automatically from your\n.zshrc.\n\nTo initialize the system, the function compinit should be in a directory mentioned in the\nfpath parameter, and should be autoloaded (`autoload -U compinit' is recommended), and then\nrun simply as `compinit'. This will define a few utility functions, arrange for all the nec‐\nessary shell functions to be autoloaded, and will then re-define all widgets that do comple‐\ntion to use the new system. If you use the menu-select widget, which is part of the zsh/com‐\nplist module, you should make sure that that module is loaded before the call to compinit so\nthat that widget is also re-defined. If completion styles (see below) are set up to perform\nexpansion as well as completion by default, and the TAB key is bound to expand-or-complete,\ncompinit will rebind it to complete-word; this is necessary to use the correct form of expan‐\nsion.\n\nShould you need to use the original completion commands, you can still bind keys to the old\nwidgets by putting a `.' in front of the widget name, e.g. `.expand-or-complete'.\n\nTo speed up the running of compinit, it can be made to produce a dumped configuration that\nwill be read in on future invocations; this is the default, but can be turned off by calling\ncompinit with the option -D. The dumped file is .zcompdump in the same directory as the\nstartup files (i.e. $ZDOTDIR or $HOME); alternatively, an explicit file name can be given by\n`compinit -d dumpfile'. The next invocation of compinit will read the dumped file instead of\nperforming a full initialization.\n\nIf the number of completion files changes, compinit will recognise this and produce a new\ndump file. However, if the name of a function or the arguments in the first line of a #com‐\npdef function (as described below) change, it is easiest to delete the dump file by hand so\nthat compinit will re-create it the next time it is run. The check performed to see if there\nare new functions can be omitted by giving the option -C. In this case the dump file will\nonly be created if there isn't one already.\n\nThe dumping is actually done by another function, compdump, but you will only need to run\nthis yourself if you change the configuration (e.g. using compdef) and then want to dump the\nnew one. The name of the old dumped file will be remembered for this purpose.\n\nIf the parameter compdir is set, compinit uses it as a directory where completion functions\ncan be found; this is only necessary if they are not already in the function search path.\n\nFor security reasons compinit also checks if the completion system would use files not owned\nby root or by the current user, or files in directories that are world- or group-writable or\nthat are not owned by root or by the current user. If such files or directories are found,\ncompinit will ask if the completion system should really be used. To avoid these tests and\nmake all files found be used without asking, use the option -u, and to make compinit silently\nignore all insecure files and directories use the option -i. This security check is skipped\nentirely when the -C option is given, provided the dumpfile exists.\n\nThe security check can be retried at any time by running the function compaudit. This is the\nsame check used by compinit, but when it is executed directly any changes to fpath are made\nlocal to the function so they do not persist. The directories to be checked may be passed as\narguments; if none are given, compaudit uses fpath and compdir to find completion system di‐\nrectories, adding missing ones to fpath as necessary. To force a check of exactly the direc‐\ntories currently named in fpath, set compdir to an empty string before calling compaudit or\ncompinit.\n\nThe function bashcompinit provides compatibility with bash's programmable completion system.\nWhen run it will define the functions, compgen and complete which correspond to the bash\nbuiltins with the same names. It will then be possible to use completion specifications and\nfunctions written for bash.\n" }, { "name": "Autoloaded files", "content": "The convention for autoloaded functions used in completion is that they start with an under‐\nscore; as already mentioned, the fpath/FPATH parameter must contain the directory in which\nthey are stored. If zsh was properly installed on your system, then fpath/FPATH automati‐\ncally contains the required directories for the standard functions.\n\nFor incomplete installations, if compinit does not find enough files beginning with an under‐\nscore (fewer than twenty) in the search path, it will try to find more by adding the direc‐\ntory compdir to the search path. If that directory has a subdirectory named Base, all sub‐\ndirectories will be added to the path. Furthermore, if the subdirectory Base has a subdirec‐\ntory named Core, compinit will add all subdirectories of the subdirectories to the path: this\nallows the functions to be in the same format as in the zsh source distribution.\n\nWhen compinit is run, it searches all such files accessible via fpath/FPATH and reads the\nfirst line of each of them. This line should contain one of the tags described below. Files\nwhose first line does not start with one of these tags are not considered to be part of the\ncompletion system and will not be treated specially.\n\nThe tags are:\n\n#compdef name ... [ -{p|P} pattern ... [ -N name ... ] ]\nThe file will be made autoloadable and the function defined in it will be called when\ncompleting names, each of which is either the name of a command whose arguments are to\nbe completed or one of a number of special contexts in the form -context- described\nbelow.\n\nEach name may also be of the form `cmd=service'. When completing the command cmd, the\nfunction typically behaves as if the command (or special context) service was being\ncompleted instead. This provides a way of altering the behaviour of functions that\ncan perform many different completions. It is implemented by setting the parameter\n$service when calling the function; the function may choose to interpret this how it\nwishes, and simpler functions will probably ignore it.\n\nIf the #compdef line contains one of the options -p or -P, the words following are\ntaken to be patterns. The function will be called when completion is attempted for a\ncommand or context that matches one of the patterns. The options -p and -P are used\nto specify patterns to be tried before or after other completions respectively. Hence\n-P may be used to specify default actions.\n\nThe option -N is used after a list following -p or -P; it specifies that remaining\nwords no longer define patterns. It is possible to toggle between the three options\nas many times as necessary.\n\n#compdef -k style key-sequence ...\nThis option creates a widget behaving like the builtin widget style and binds it to\nthe given key-sequences, if any. The style must be one of the builtin widgets that\nperform completion, namely complete-word, delete-char-or-list, expand-or-complete, ex‐\npand-or-complete-prefix, list-choices, menu-complete, menu-expand-or-complete, or re‐\nverse-menu-complete. If the zsh/complist module is loaded (see zshmodules(1)) the\nwidget menu-select is also available.\n\nWhen one of the key-sequences is typed, the function in the file will be invoked to\ngenerate the matches. Note that a key will not be re-bound if it already was (that\nis, was bound to something other than undefined-key). The widget created has the same\nname as the file and can be bound to any other keys using bindkey as usual.\n\n#compdef -K widget-name style key-sequence [ name style seq ... ]\nThis is similar to -k except that only one key-sequence argument may be given for each\nwidget-name style pair. However, the entire set of three arguments may be repeated\nwith a different set of arguments. Note in particular that the widget-name must be\ndistinct in each set. If it does not begin with `' this will be added. The wid‐\nget-name should not clash with the name of any existing widget: names based on the\nname of the function are most useful. For example,\n\n#compdef -K foocomplete complete-word \"^X^C\" \\\nfoolist list-choices \"^X^D\"\n\n(all on one line) defines a widget foocomplete for completion, bound to `^X^C', and\na widget foolist for listing, bound to `^X^D'.\n\n#autoload [ options ]\nFunctions with the #autoload tag are marked for autoloading but are not otherwise\ntreated specially. Typically they are to be called from within one of the completion\nfunctions. Any options supplied will be passed to the autoload builtin; a typical use\nis +X to force the function to be loaded immediately. Note that the -U and -z flags\nare always added implicitly.\n\nThe # is part of the tag name and no white space is allowed after it. The #compdef tags use\nthe compdef function described below; the main difference is that the name of the function is\nsupplied implicitly.\n\nThe special contexts for which completion functions can be defined are:\n" }, { "name": "-array-value-", "content": "The right hand side of an array-assignment (`name=(...)')\n" }, { "name": "-assign-parameter-", "content": "The name of a parameter in an assignment, i.e. on the left hand side of an `='\n" }, { "name": "-brace-parameter-", "content": "The name of a parameter expansion within braces (`${...}')\n" }, { "name": "-command-", "content": "A word in command position\n" }, { "name": "-condition-", "content": "A word inside a condition (`[[...]]')\n" }, { "name": "-default-", "content": "Any word for which no other completion is defined\n" }, { "name": "-equal-", "content": "A word beginning with an equals sign\n" }, { "name": "-first-", "content": "This is tried before any other completion function. The function called may set the\ncompskip parameter to one of various values: all: no further completion is attempted;\na string containing the substring patterns: no pattern completion functions will be\ncalled; a string containing default: the function for the `-default-' context will not\nbe called, but functions defined for commands will be.\n" }, { "name": "-math-", "content": "" }, { "name": "-parameter-", "content": "The name of a parameter expansion (`$...')\n" }, { "name": "-redirect-", "content": "The word after a redirection operator.\n" }, { "name": "-subscript-", "content": "The contents of a parameter subscript.\n" }, { "name": "-tilde-", "content": "After an initial tilde (`~'), but before the first slash in the word.\n" }, { "name": "-value-", "content": "On the right hand side of an assignment.\n\nDefault implementations are supplied for each of these contexts. In most cases the context" }, { "name": "-_ -", "content": "`-tilde-' and the function `tilde').\n\nThe contexts -redirect- and -value- allow extra context-specific information. (Internally,\nthis is handled by the functions for each context calling the function dispatch.) The extra\ninformation is added separated by commas.\n\nFor the -redirect- context, the extra information is in the form `-redirect-,op,command',\nwhere op is the redirection operator and command is the name of the command on the line. If\nthere is no command on the line yet, the command field will be empty.\n\nFor the -value- context, the form is `-value-,name,command', where name is the name of the\nparameter on the left hand side of the assignment. In the case of elements of an associative\narray, for example `assoc=(key ', name is expanded to `name-key'. In certain special\ncontexts, such as completing after `make CFLAGS=', the command part gives the name of the\ncommand, here make; otherwise it is empty.\n\nIt is not necessary to define fully specific completions as the functions provided will try\nto generate completions by progressively replacing the elements with `-default-'. For exam‐\nple, when completing after `foo=', value will try the names `-value-,foo,' (note the\nempty command part), `-value-,foo,-default-' and`-value-,-default-,-default-', in that order,\nuntil it finds a function to handle the context.\n\nAs an example:\n\ncompdef 'files -g \"*.log\"' '-redirect-,2>,-default-'\n\ncompletes files matching `*.log' after `2> ' for any command with no more specific han‐\ndler defined.\n\nAlso:\n\ncompdef foo -value-,-default-,-default-\n\nspecifies that foo provides completions for the values of parameters for which no special\nfunction has been defined. This is usually handled by the function value itself.\n\nThe same lookup rules are used when looking up styles (as described below); for example\n\nzstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log'\n\nis another way to make completion after `2> ' complete files matching `*.log'.\n" }, { "name": "Functions", "content": "The following function is defined by compinit and may be called directly.\n\ncompdef [ -ane ] function name ... [ -{p|P} pattern ... [ -N name ...]]\ncompdef -d name ...\ncompdef -k [ -an ] function style key-sequence [ key-sequence ... ]\ncompdef -K [ -an ] function name style key-seq [ name style seq ... ]\nThe first form defines the function to call for completion in the given contexts as\ndescribed for the #compdef tag above.\n\nAlternatively, all the arguments may have the form `cmd=service'. Here service should\nalready have been defined by `cmd1=service' lines in #compdef files, as described\nabove. The argument for cmd will be completed in the same way as service.\n\nThe function argument may alternatively be a string containing almost any shell code.\nIf the string contains an equal sign, the above will take precedence. The option -e\nmay be used to specify the first argument is to be evaluated as shell code even if it\ncontains an equal sign. The string will be executed using the eval builtin command to\ngenerate completions. This provides a way of avoiding having to define a new comple‐\ntion function. For example, to complete files ending in `.h' as arguments to the com‐\nmand foo:\n\ncompdef 'files -g \"*.h\"' foo\n\nThe option -n prevents any completions already defined for the command or context from\nbeing overwritten.\n\nThe option -d deletes any completion defined for the command or contexts listed.\n\nThe names may also contain -p, -P and -N options as described for the #compdef tag.\nThe effect on the argument list is identical, switching between definitions of pat‐\nterns tried initially, patterns tried finally, and normal commands and contexts.\n\nThe parameter $compskip may be set by any function defined for a pattern context. If\nit is set to a value containing the substring `patterns' none of the pattern-functions\nwill be called; if it is set to a value containing the substring `all', no other func‐\ntion will be called. Setting $compskip in this manner is of particular utility when\nusing the -p option, as otherwise the dispatcher will move on to additional functions\n(likely the default one) after calling the pattern-context one, which can mangle the\ndisplay of completion possibilities if not handled properly.\n\nThe form with -k defines a widget with the same name as the function that will be\ncalled for each of the key-sequences; this is like the #compdef -k tag. The function\nshould generate the completions needed and will otherwise behave like the builtin wid‐\nget whose name is given as the style argument. The widgets usable for this are: com‐\nplete-word, delete-char-or-list, expand-or-complete, expand-or-complete-prefix,\nlist-choices, menu-complete, menu-expand-or-complete, and reverse-menu-complete, as\nwell as menu-select if the zsh/complist module is loaded. The option -n prevents the\nkey being bound if it is already to bound to something other than undefined-key.\n\nThe form with -K is similar and defines multiple widgets based on the same function,\neach of which requires the set of three arguments name, style and key-sequence, where\nthe latter two are as for -k and the first must be a unique widget name beginning with\nan underscore.\n\nWherever applicable, the -a option makes the function autoloadable, equivalent to au‐\ntoload -U function.\n\nThe function compdef can be used to associate existing completion functions with new com‐\nmands. For example,\n\ncompdef pids foo\n\nuses the function pids to complete process IDs for the command foo.\n\nNote also the gnugeneric function described below, which can be used to complete options\nfor commands that understand the `--help' option.\n" } ] }, "COMPLETION SYSTEM CONFIGURATION": { "content": "This section gives a short overview of how the completion system works, and then more detail\non how users can configure how and when matches are generated.\n", "subsections": [ { "name": "Overview", "content": "When completion is attempted somewhere on the command line the completion system begins\nbuilding the context. The context represents everything that the shell knows about the mean‐\ning of the command line and the significance of the cursor position. This takes account of a\nnumber of things including the command word (such as `grep' or `zsh') and options to which\nthe current word may be an argument (such as the `-o' option to zsh which takes a shell op‐\ntion as an argument).\n\nThe context starts out very generic (\"we are beginning a completion\") and becomes more spe‐\ncific as more is learned (\"the current word is in a position that is usually a command name\"\nor \"the current word might be a variable name\" and so on). Therefore the context will vary\nduring the same call to the completion system.\n\nThis context information is condensed into a string consisting of multiple fields separated\nby colons, referred to simply as `the context' in the remainder of the documentation. Note\nthat a user of the completion system rarely needs to compose a context string, unless for ex‐\nample a new function is being written to perform completion for a new command. What a user\nmay need to do is compose a style pattern, which is matched against a context when needed to\nlook up context-sensitive options that configure the completion system.\n\nThe next few paragraphs explain how a context is composed within the completion function\nsuite. Following that is discussion of how styles are defined. Styles determine such things\nas how the matches are generated, similarly to shell options but with much more control.\nThey are defined with the zstyle builtin command (see zshmodules(1)).\n\nThe context string always consists of a fixed set of fields, separated by colons and with a\nleading colon before the first. Fields which are not yet known are left empty, but the sur‐\nrounding colons appear anyway. The fields are always in the order :completion:function:com‐\npleter:command:argument:tag. These have the following meaning:\n\n• The literal string completion, saying that this style is used by the completion sys‐\ntem. This distinguishes the context from those used by, for example, zle widgets and\nZFTP functions.\n\n\n• The function, if completion is called from a named widget rather than through the nor‐\nmal completion system. Typically this is blank, but it is set by special widgets such\nas predict-on and the various functions in the Widget directory of the distribution to\nthe name of that function, often in an abbreviated form.\n\n\n• The completer currently active, the name of the function without the leading under‐\nscore and with other underscores converted to hyphens. A `completer' is in overall\ncontrol of how completion is to be performed; `complete' is the simplest, but other\ncompleters exist to perform related tasks such as correction, or to modify the behav‐\niour of a later completer. See the section `Control Functions' below for more infor‐\nmation.\n\n\n• The command or a special -context-, just at it appears following the #compdef tag or\nthe compdef function. Completion functions for commands that have sub-commands usu‐\nally modify this field to contain the name of the command followed by a minus sign and\nthe sub-command. For example, the completion function for the cvs command sets this\nfield to cvs-add when completing arguments to the add subcommand.\n\n\n• The argument; this indicates which command line or option argument we are completing.\nFor command arguments this generally takes the form argument-n, where n is the number\nof the argument, and for arguments to options the form option-opt-n where n is the\nnumber of the argument to option opt. However, this is only the case if the command\nline is parsed with standard UNIX-style options and arguments, so many completions do\nnot set this.\n\n\n• The tag. As described previously, tags are used to discriminate between the types of\nmatches a completion function can generate in a certain context. Any completion func‐\ntion may use any tag name it likes, but a list of the more common ones is given below.\n\n\nThe context is gradually put together as the functions are executed, starting with the main\nentry point, which adds :completion: and the function element if necessary. The completer\nthen adds the completer element. The contextual completion adds the command and argument op‐\ntions. Finally, the tag is added when the types of completion are known. For example, the\ncontext name\n\n:completion::complete:dvips:option-o-1:files\n\nsays that normal completion was attempted as the first argument to the option -o of the com‐\nmand dvips:\n\ndvips -o ...\n\nand the completion function will generate filenames.\n\nUsually completion will be tried for all possible tags in an order given by the completion\nfunction. However, this can be altered by using the tag-order style. Completion is then re‐\nstricted to the list of given tags in the given order.\n\nThe completehelp bindable command shows all the contexts and tags available for completion\nat a particular point. This provides an easy way of finding information for tag-order and\nother styles. It is described in the section `Bindable Commands' below.\n\nWhen looking up styles the completion system uses full context names, including the tag.\nLooking up the value of a style therefore consists of two things: the context, which is\nmatched to the most specific (best fitting) pattern, and the name of the style itself, which\nmust be matched exactly. The following examples demonstrate that patterns may be loosely de‐\nfined for styles that apply broadly, or as tightly defined as desired for styles that apply\nin narrower circumstances.\n\nFor example, many completion functions can generate matches in a simple and a verbose form\nand use the verbose style to decide which form should be used. To make all such functions\nuse the verbose form, put\n\nzstyle ':completion:*' verbose yes\n\nin a startup file (probably .zshrc). This gives the verbose style the value yes in every\ncontext inside the completion system, unless that context has a more specific definition. It\nis best to avoid giving the pattern as `*' in case the style has some meaning outside the\ncompletion system.\n\nMany such general purpose styles can be configured simply by using the compinstall function.\n\nA more specific example of the use of the verbose style is by the completion for the kill\nbuiltin. If the style is set, the builtin lists full job texts and process command lines;\notherwise it shows the bare job numbers and PIDs. To turn the style off for this use only:\n\nzstyle ':completion:*:*:kill:*:*' verbose no\n\nFor even more control, the style can use one of the tags `jobs' or `processes'. To turn off\nverbose display only for jobs:\n\nzstyle ':completion:*:*:kill:*:jobs' verbose no\n\nThe -e option to zstyle even allows completion function code to appear as the argument to a\nstyle; this requires some understanding of the internals of completion functions (see see\nzshcompwid(1))). For example,\n\nzstyle -e ':completion:*' hosts 'reply=($myhosts)'\n\nThis forces the value of the hosts style to be read from the variable myhosts each time a\nhost name is needed; this is useful if the value of myhosts can change dynamically. For an‐\nother useful example, see the example in the description of the file-list style below. This\nform can be slow and should be avoided for commonly examined styles such as menu and\nlist-rows-first.\n\nNote that the order in which styles are defined does not matter; the style mechanism uses the\nmost specific possible match for a particular style to determine the set of values. Strings\nare preferred over patterns (for example, `:completion::complete:::foo' is more specific than\n`:completion::complete:::*'), and longer patterns are preferred over the pattern `*'. See\nzmodules(1) for details.\n\nContext patterns that use something other than a wildcard (*) to match the middle parts of\nthe context -- the completer, command, and argument in :completion:function:completer:com‐\nmand:argument:tag -- should include all six colons (:) explicitly. Without this, a pattern\nsuch as :completion:*:foo:* could match foo against a component other than the intended one\n(for example, against completer when a match against command was intended).\n\nStyle names like those of tags are arbitrary and depend on the completion function. However,\nthe following two sections list some of the most common tags and styles.\n" }, { "name": "Standard Tags", "content": "Some of the following are only used when looking up particular styles and do not refer to a\ntype of match.\n" }, { "name": "accounts", "content": "used to look up the users-hosts style\n" }, { "name": "all-expansions", "content": "used by the expand completer when adding the single string containing all possible\nexpansions\n" }, { "name": "all-files", "content": "for the names of all files (as distinct from a particular subset, see the\nglobbed-files tag).\n" }, { "name": "arguments", "content": "for arguments to a command\n\narrays for names of array parameters\n" }, { "name": "association-keys", "content": "for keys of associative arrays; used when completing inside a subscript to a parameter\nof this type\n" }, { "name": "bookmarks", "content": "when completing bookmarks (e.g. for URLs and the zftp function suite)\n" }, { "name": "builtins", "content": "for names of builtin commands\n" }, { "name": "characters", "content": "for single characters in arguments of commands such as stty. Also used when complet‐\ning character classes after an opening bracket\n" }, { "name": "colormapids", "content": "for X colormap ids\n\ncolors for color names\n" }, { "name": "commands", "content": "for names of external commands. Also used by complex commands such as cvs when com‐\npleting names subcommands.\n" }, { "name": "contexts", "content": "for contexts in arguments to the zstyle builtin command\n" }, { "name": "corrections", "content": "used by the approximate and correct completers for possible corrections\n" }, { "name": "cursors", "content": "for cursor names used by X programs\n" }, { "name": "default", "content": "used in some contexts to provide a way of supplying a default when more specific tags\nare also valid. Note that this tag is used when only the function field of the con‐\ntext name is set\n" }, { "name": "descriptions", "content": "used when looking up the value of the format style to generate descriptions for types\nof matches\n" }, { "name": "devices", "content": "for names of device special files\n" }, { "name": "directories", "content": "for names of directories -- local-directories is used instead when completing argu‐\nments of cd and related builtin commands when the cdpath array is set\n" }, { "name": "directory-stack", "content": "for entries in the directory stack\n" }, { "name": "displays", "content": "for X display names\n" }, { "name": "domains", "content": "for network domains\n\nemail-plugin\nfor email addresses from the `email-plugin' backend of emailaddresses\n" }, { "name": "expansions", "content": "used by the expand completer for individual words (as opposed to the complete set of\nexpansions) resulting from the expansion of a word on the command line\n" }, { "name": "extensions", "content": "for X server extensions\n" }, { "name": "file-descriptors", "content": "for numbers of open file descriptors\n\nfiles the generic file-matching tag used by functions completing filenames\n\nfonts for X font names\n" }, { "name": "fstypes", "content": "for file system types (e.g. for the mount command)\n" }, { "name": "functions", "content": "names of functions -- normally shell functions, although certain commands may under‐\nstand other kinds of function\n" }, { "name": "globbed-files", "content": "for filenames when the name has been generated by pattern matching\n\ngroups for names of user groups\n" }, { "name": "history-words", "content": "for words from the history\n\nhosts for hostnames\n" }, { "name": "indexes", "content": "for array indexes\n" }, { "name": "interfaces", "content": "for network interfaces\n\njobs for jobs (as listed by the `jobs' builtin)\n" }, { "name": "keymaps", "content": "for names of zsh keymaps\n" }, { "name": "keysyms", "content": "for names of X keysyms\n" }, { "name": "libraries", "content": "for names of system libraries\n\nlimits for system limits\n" }, { "name": "local-directories", "content": "for names of directories that are subdirectories of the current working directory when\ncompleting arguments of cd and related builtin commands (compare path-directories) --\nwhen the cdpath array is unset, directories is used instead\n" }, { "name": "mailboxes", "content": "for e-mail folders\n" }, { "name": "manuals", "content": "for names of manual pages\n\nmaps for map names (e.g. NIS maps)\n" }, { "name": "messages", "content": "used to look up the format style for messages\n" }, { "name": "modifiers", "content": "for names of X modifiers\n" }, { "name": "modules", "content": "for modules (e.g. zsh modules)\n" }, { "name": "my-accounts", "content": "used to look up the users-hosts style\n" }, { "name": "named-directories", "content": "for named directories (you wouldn't have guessed that, would you?)\n\nnames for all kinds of names\n" }, { "name": "newsgroups", "content": "for USENET groups\n" }, { "name": "nicknames", "content": "for nicknames of NIS maps\n" }, { "name": "options", "content": "for command options\n" }, { "name": "original", "content": "used by the approximate, correct and expand completers when offering the original\nstring as a match\n" }, { "name": "other-accounts", "content": "used to look up the users-hosts style\n" }, { "name": "packages", "content": "for packages (e.g. rpm or installed Debian packages)\n" }, { "name": "parameters", "content": "for names of parameters\n" }, { "name": "path-directories", "content": "for names of directories found by searching the cdpath array when completing arguments\nof cd and related builtin commands (compare local-directories)\n\npaths used to look up the values of the expand, ambiguous and special-dirs styles\n\npods for perl pods (documentation files)\n\nports for communication ports\n" }, { "name": "prefixes", "content": "for prefixes (like those of a URL)\n" }, { "name": "printers", "content": "for print queue names\n" }, { "name": "processes", "content": "for process identifiers\n" }, { "name": "processes-names", "content": "used to look up the command style when generating the names of processes for killall\n" }, { "name": "sequences", "content": "for sequences (e.g. mh sequences)\n" }, { "name": "sessions", "content": "for sessions in the zftp function suite\n" }, { "name": "signals", "content": "for signal names\n" }, { "name": "strings", "content": "for strings (e.g. the replacement strings for the cd builtin command)\n\nstyles for styles used by the zstyle builtin command\n" }, { "name": "suffixes", "content": "for filename extensions\n\ntags for tags (e.g. rpm tags)\n" }, { "name": "targets", "content": "for makefile targets\n" }, { "name": "time-zones", "content": "for time zones (e.g. when setting the TZ parameter)\n\ntypes for types of whatever (e.g. address types for the xhost command)\n\nurls used to look up the urls and local styles when completing URLs\n\nusers for usernames\n\nvalues for one of a set of values in certain lists\n" }, { "name": "variant", "content": "used by pickvariant to look up the command to run when determining what program is\ninstalled for a particular command name.\n" }, { "name": "visuals", "content": "for X visuals\n" }, { "name": "warnings", "content": "used to look up the format style for warnings\n" }, { "name": "widgets", "content": "for zsh widget names\n" }, { "name": "windows", "content": "for IDs of X windows\n" }, { "name": "zsh-options", "content": "for shell options\n" }, { "name": "Standard Styles", "content": "Note that the values of several of these styles represent boolean values. Any of the strings\n`true', `on', `yes', and `1' can be used for the value `true' and any of the strings `false',\n`off', `no', and `0' for the value `false'. The behavior for any other value is undefined\nexcept where explicitly mentioned. The default value may be either `true' or `false' if the\nstyle is not set.\n\nSome of these styles are tested first for every possible tag corresponding to a type of\nmatch, and if no style was found, for the default tag. The most notable styles of this type\nare menu, list-colors and styles controlling completion listing such as list-packed and\nlast-prompt. When tested for the default tag, only the function field of the context will be\nset so that a style using the default tag will normally be defined along the lines of:\n\nzstyle ':completion:*:default' menu ...\n" }, { "name": "accept-exact", "content": "This is tested for the default tag in addition to the tags valid for the current con‐\ntext. If it is set to `true' and any of the trial matches is the same as the string\non the command line, this match will immediately be accepted (even if it would other‐\nwise be considered ambiguous).\n\nWhen completing pathnames (where the tag used is `paths') this style accepts any num‐\nber of patterns as the value in addition to the boolean values. Pathnames matching\none of these patterns will be accepted immediately even if the command line contains\nsome more partially typed pathname components and these match no file under the direc‐\ntory accepted.\n\nThis style is also used by the expand completer to decide if words beginning with a\ntilde or parameter expansion should be expanded. For example, if there are parameters\nfoo and foobar, the string `$foo' will only be expanded if accept-exact is set to\n`true'; otherwise the completion system will be allowed to complete $foo to $foobar.\nIf the style is set to `continue', expand will add the expansion as a match and the\ncompletion system will also be allowed to continue.\n" }, { "name": "accept-exact-dirs", "content": "This is used by filename completion. Unlike accept-exact it is a boolean. By de‐\nfault, filename completion examines all components of a path to see if there are com‐\npletions of that component, even if the component matches an existing directory. For\nexample, when completion after /usr/bin/, the function examines possible completions\nto /usr.\n\nWhen this style is `true', any prefix of a path that matches an existing directory is\naccepted without any attempt to complete it further. Hence, in the given example, the\npath /usr/bin/ is accepted immediately and completion tried in that directory.\n\nThis style is also useful when completing after directories that magically appear when\nreferenced, such as ZFS .zfs directories or NetApp .snapshot directories. When the\nstyle is set the shell does not check for the existence of the directory within the\nparent directory.\n\nIf you wish to inhibit this behaviour entirely, set the path-completion style (see be‐\nlow) to `false'.\n" }, { "name": "add-space", "content": "This style is used by the expand completer. If it is `true' (the default), a space\nwill be inserted after all words resulting from the expansion, or a slash in the case\nof directory names. If the value is `file', the completer will only add a space to\nnames of existing files. Either a boolean `true' or the value `file' may be combined\nwith `subst', in which case the completer will not add a space to words generated from\nthe expansion of a substitution of the form `$(...)' or `${...}'.\n\nThe prefix completer uses this style as a simple boolean value to decide if a space\nshould be inserted before the suffix.\n" }, { "name": "ambiguous", "content": "This applies when completing non-final components of filename paths, in other words\nthose with a trailing slash. If it is set, the cursor is left after the first ambigu‐\nous component, even if menu completion is in use. The style is always tested with the\npaths tag.\n" }, { "name": "assign-list", "content": "When completing after an equals sign that is being treated as an assignment, the com‐\npletion system normally completes only one filename. In some cases the value may be\na list of filenames separated by colons, as with PATH and similar parameters. This\nstyle can be set to a list of patterns matching the names of such parameters.\n\nThe default is to complete lists when the word on the line already contains a colon.\n" }, { "name": "auto-description", "content": "If set, this style's value will be used as the description for options that are not\ndescribed by the completion functions, but that have exactly one argument. The se‐\nquence `%d' in the value will be replaced by the description for this argument. De‐\npending on personal preferences, it may be useful to set this style to something like\n`specify: %d'. Note that this may not work for some commands.\n" }, { "name": "avoid-completer", "content": "This is used by the allmatches completer to decide if the string consisting of all\nmatches should be added to the list currently being generated. Its value is a list of\nnames of completers. If any of these is the name of the completer that generated the\nmatches in this completion, the string will not be added.\n\nThe default value for this style is `expand oldlist correct approximate', i.e. it\ncontains the completers for which a string with all matches will almost never be\nwanted.\n" }, { "name": "cache-path", "content": "This style defines the path where any cache files containing dumped completion data\nare stored. It defaults to `$ZDOTDIR/.zcompcache', or `$HOME/.zcompcache' if $ZDOTDIR\nis not defined. The completion cache will not be used unless the use-cache style is\nset.\n" }, { "name": "cache-policy", "content": "This style defines the function that will be used to determine whether a cache needs\nrebuilding. See the section on the cacheinvalid function below.\n" }, { "name": "call-command", "content": "This style is used in the function for commands such as make and ant where calling the\ncommand directly to generate matches suffers problems such as being slow or, as in the\ncase of make can potentially cause actions in the makefile to be executed. If it is\nset to `true' the command is called to generate matches. The default value of this\nstyle is `false'.\n" }, { "name": "command", "content": "In many places, completion functions need to call external commands to generate the\nlist of completions. This style can be used to override the command that is called in\nsome such cases. The elements of the value are joined with spaces to form a command\nline to execute. The value can also start with a hyphen, in which case the usual com‐\nmand will be added to the end; this is most useful for putting `builtin' or `command'\nin front to make sure the appropriate version of a command is called, for example to\navoid calling a shell function with the same name as an external command.\n\nAs an example, the completion function for process IDs uses this style with the\nprocesses tag to generate the IDs to complete and the list of processes to display (if\nthe verbose style is `true'). The list produced by the command should look like the\noutput of the ps command. The first line is not displayed, but is searched for the\nstring `PID' (or `pid') to find the position of the process IDs in the following\nlines. If the line does not contain `PID', the first numbers in each of the other\nlines are taken as the process IDs to complete.\n\nNote that the completion function generally has to call the specified command for each\nattempt to generate the completion list. Hence care should be taken to specify only\ncommands that take a short time to run, and in particular to avoid any that may never\nterminate.\n" }, { "name": "command-path", "content": "This is a list of directories to search for commands to complete. The default for\nthis style is the value of the special parameter path.\n" }, { "name": "commands", "content": "This is used by the function completing sub-commands for the system initialisation\nscripts (residing in /etc/init.d or somewhere not too far away from that). Its values\ngive the default commands to complete for those commands for which the completion\nfunction isn't able to find them out automatically. The default for this style are\nthe two strings `start' and `stop'.\n" }, { "name": "complete", "content": "This is used by the expandalias function when invoked as a bindable command. If set\nto `true' and the word on the command line is not the name of an alias, matching alias\nnames will be completed.\n" }, { "name": "complete-options", "content": "This is used by the completer for cd, chdir and pushd. For these commands a - is used\nto introduce a directory stack entry and completion of these is far more common than\ncompleting options. Hence unless the value of this style is `true' options will not\nbe completed, even after an initial -. If it is `true', options will be completed af‐\nter an initial - unless there is a preceding -- on the command line.\n" }, { "name": "completer", "content": "The strings given as the value of this style provide the names of the completer func‐\ntions to use. The available completer functions are described in the section `Control\nFunctions' below.\n\nEach string may be either the name of a completer function or a string of the form\n`function:name'. In the first case the completer field of the context will contain\nthe name of the completer without the leading underscore and with all other under‐\nscores replaced by hyphens. In the second case the function is the name of the com‐\npleter to call, but the context will contain the user-defined name in the completer\nfield of the context. If the name starts with a hyphen, the string for the context\nwill be build from the name of the completer function as in the first case with the\nname appended to it. For example:\n\nzstyle ':completion:*' completer complete complete:-foo\n\nHere, completion will call the complete completer twice, once using `complete' and\nonce using `complete-foo' in the completer field of the context. Normally, using the\nsame completer more than once only makes sense when used with the `functions:name'\nform, because otherwise the context name will be the same in all calls to the com‐\npleter; possible exceptions to this rule are the ignored and prefix completers.\n\nThe default value for this style is `complete ignored': only completion will be\ndone, first using the ignored-patterns style and the $fignore array and then without\nignoring matches.\n" }, { "name": "condition", "content": "This style is used by the list completer function to decide if insertion of matches\nshould be delayed unconditionally. The default is `true'.\n" }, { "name": "delimiters", "content": "This style is used when adding a delimiter for use with history modifiers or glob\nqualifiers that have delimited arguments. It is an array of preferred delimiters to\nadd. Non-special characters are preferred as the completion system may otherwise be‐\ncome confused. The default list is :, +, /, -, %. The list may be empty to force a\ndelimiter to be typed.\n" }, { "name": "disabled", "content": "If this is set to `true', the expandalias completer and bindable command will try to\nexpand disabled aliases, too. The default is `false'.\n" }, { "name": "domains", "content": "A list of names of network domains for completion. If this is not set, domain names\nwill be taken from the file /etc/resolv.conf.\n" }, { "name": "environ", "content": "The environ style is used when completing for `sudo'. It is set to an array of\n`VAR=value' assignments to be exported into the local environment before the comple‐\ntion for the target command is invoked.\nzstyle ':completion:*:sudo::' environ \\\nPATH=\"/sbin:/usr/sbin:$PATH\" HOME=\"/root\"\n\nexpand This style is used when completing strings consisting of multiple parts, such as path\nnames.\n\nIf one of its values is the string `prefix', the partially typed word from the line\nwill be expanded as far as possible even if trailing parts cannot be completed.\n\nIf one of its values is the string `suffix', matching names for components after the\nfirst ambiguous one will also be added. This means that the resulting string is the\nlongest unambiguous string possible. However, menu completion can be used to cycle\nthrough all matches.\n" }, { "name": "extra-verbose", "content": "If set, the completion listing is more verbose at the cost of a probable decrease in\ncompletion speed. Completion performance will suffer if this style is set to `true'.\n\nfake This style may be set for any completion context. It specifies additional strings\nthat will always be completed in that context. The form of each string is `value:de‐\nscription'; the colon and description may be omitted, but any literal colons in value\nmust be quoted with a backslash. Any description provided is shown alongside the\nvalue in completion listings.\n\nIt is important to use a sufficiently restrictive context when specifying fake\nstrings. Note that the styles fake-files and fake-parameters provide additional fea‐\ntures when completing files or parameters.\n" }, { "name": "fake-always", "content": "This works identically to the fake style except that the ignored-patterns style is not\napplied to it. This makes it possible to override a set of matches completely by set‐\nting the ignored patterns to `*'.\n\nThe following shows a way of supplementing any tag with arbitrary data, but having it\nbehave for display purposes like a separate tag. In this example we use the features\nof the tag-order style to divide the named-directories tag into two when performing\ncompletion with the standard completer complete for arguments of cd. The tag\nnamed-directories-normal behaves as normal, but the tag named-directories-mine con‐\ntains a fixed set of directories. This has the effect of adding the match group `ex‐\ntra directories' with the given completions.\n\nzstyle ':completion::complete:cd:*' tag-order \\\n'named-directories:-mine:extra\\ directories\nnamed-directories:-normal:named\\ directories *'\nzstyle ':completion::complete:cd:*:named-directories-mine' \\\nfake-always mydir1 mydir2\nzstyle ':completion::complete:cd:*:named-directories-mine' \\\nignored-patterns '*'\n" }, { "name": "fake-files", "content": "This style is used when completing files and looked up without a tag. Its values are\nof the form `dir:names...'. This will add the names (strings separated by spaces) as\npossible matches when completing in the directory dir, even if no such files really\nexist. The dir may be a pattern; pattern characters or colons in dir should be quoted\nwith a backslash to be treated literally.\n\nThis can be useful on systems that support special file systems whose top-level path‐\nnames can not be listed or generated with glob patterns (but see accept-exact-dirs for\na more general way of dealing with this problem). It can also be used for directories\nfor which one does not have read permission.\n\nThe pattern form can be used to add a certain `magic' entry to all directories on a\nparticular file system.\n" }, { "name": "fake-parameters", "content": "This is used by the completion function for parameter names. Its values are names of\nparameters that might not yet be set but should be completed nonetheless. Each name\nmay also be followed by a colon and a string specifying the type of the parameter\n(like `scalar', `array' or `integer'). If the type is given, the name will only be\ncompleted if parameters of that type are required in the particular context. Names\nfor which no type is specified will always be completed.\n" }, { "name": "file-list", "content": "This style controls whether files completed using the standard builtin mechanism are\nto be listed with a long list similar to ls -l. Note that this feature uses the shell\nmodule zsh/stat for file information; this loads the builtin stat which will replace\nany external stat executable. To avoid this the following code can be included in an\ninitialization file:\n\nzmodload -i zsh/stat\ndisable stat\n\nThe style may either be set to a `true' value (or `all'), or one of the values `in‐\nsert' or `list', indicating that files are to be listed in long format in all circum‐\nstances, or when attempting to insert a file name, or when listing file names without\nattempting to insert one.\n\nMore generally, the value may be an array of any of the above values, optionally fol‐\nlowed by =num. If num is present it gives the maximum number of matches for which\nlong listing style will be used. For example,\n\nzstyle ':completion:*' file-list list=20 insert=10\n\nspecifies that long format will be used when listing up to 20 files or inserting a\nfile with up to 10 matches (assuming a listing is to be shown at all, for example on\nan ambiguous completion), else short format will be used.\n\nzstyle -e ':completion:*' file-list \\\n'(( ${+NUMERIC} )) && reply=(true)'\n\nspecifies that long format will be used any time a numeric argument is supplied, else\nshort format.\n" }, { "name": "file-patterns", "content": "This is used by the standard function for completing filenames, files. If the style\nis unset up to three tags are offered, `globbed-files',`directories' and `all-files',\ndepending on the types of files expected by the caller of files. The first two\n(`globbed-files' and `directories') are normally offered together to make it easier to\ncomplete files in sub-directories.\n\nThe file-patterns style provides alternatives to the default tags, which are not used.\nIts value consists of elements of the form `pattern:tag'; each string may contain any\nnumber of such specifications separated by spaces.\n\nThe pattern is a pattern that is to be used to generate filenames. Any occurrence of\nthe sequence `%p' is replaced by any pattern(s) passed by the function calling files.\nColons in the pattern must be preceded by a backslash to make them distinguishable\nfrom the colon before the tag. If more than one pattern is needed, the patterns can\nbe given inside braces, separated by commas.\n\nThe tags of all strings in the value will be offered by files and used when looking\nup other styles. Any tags in the same word will be offered at the same time and be‐\nfore later words. If no `:tag' is given the `files' tag will be used.\n\nThe tag may also be followed by an optional second colon and a description, which will\nbe used for the `%d' in the value of the format style (if that is set) instead of the\ndefault description supplied by the completion function. The inclusion of a descrip‐\ntion also gives precedence to associated options such as for completion grouping so it\ncan be used where files should be separated.\n\nFor example, to make the rm command first complete only names of object files and then\nthe names of all files if there is no matching object file:\n\nzstyle ':completion:*:*:rm:*:*' file-patterns \\\n'*.o:object-files' '%p:all-files'\n\nTo alter the default behaviour of file completion -- offer files matching a pattern\nand directories on the first attempt, then all files -- to offer only matching files\non the first attempt, then directories, and finally all files:\n\nzstyle ':completion:*' file-patterns \\\n'%p:globbed-files' '*(-/):directories' '*:all-files'\n\nThis works even where there is no special pattern: files matches all files using the\npattern `*' at the first step and stops when it sees this pattern. Note also it will\nnever try a pattern more than once for a single completion attempt.\n\nTo separate directories into a separate group from the files but still complete them\nat the first attempt, a description needs to be given. Note that directories need to\nbe explicitly excluded from the globbed-files because `*' will match directories. For\ngrouping, it is also necessary to set the group-name style.\n\nzstyle ':completion:*' file-patterns \\\n'%p(^-/):globbed-files *(-/):directories:location'\n\nDuring the execution of completion functions, the EXTENDEDGLOB option is in effect,\nso the characters `#', `~' and `^' have special meanings in the patterns.\n" }, { "name": "file-sort", "content": "The standard filename completion function uses this style without a tag to determine\nin which order the names should be listed; menu completion will cycle through them in\nthe same order. The possible values are: `size' to sort by the size of the file;\n`links' to sort by the number of links to the file; `modification' (or `time' or\n`date') to sort by the last modification time; `access' to sort by the last access\ntime; and `inode' (or `change') to sort by the last inode change time. If the style\nis set to any other value, or is unset, files will be sorted alphabetically by name.\nIf the value contains the string `reverse', sorting is done in the opposite order. If\nthe value contains the string `follow', timestamps are associated with the targets of\nsymbolic links; the default is to use the timestamps of the links themselves.\n" }, { "name": "file-split-chars", "content": "A set of characters that will cause all file completions for the given context to be\nsplit at the point where any of the characters occurs. A typical use is to set the\nstyle to :; then everything up to and including the last : in the string so far is ig‐\nnored when completing files. As this is quite heavy-handed, it is usually preferable\nto update completion functions for contexts where this behaviour is useful.\n\nfilter The ldap plugin of email address completion (see emailaddresses) uses this style to\nspecify the attributes to match against when filtering entries. So for example, if\nthe style is set to `sn', matching is done against surnames. Standard LDAP filtering\nis used so normal completion matching is bypassed. If this style is not set, the LDAP\nplugin is skipped. You may also need to set the command style to specify how to con‐\nnect to your LDAP server.\n" }, { "name": "force-list", "content": "This forces a list of completions to be shown at any point where listing is done, even\nin cases where the list would usually be suppressed. For example, normally the list\nis only shown if there are at least two different matches. By setting this style to\n`always', the list will always be shown, even if there is only a single match that\nwill immediately be accepted. The style may also be set to a number. In this case\nthe list will be shown if there are at least that many matches, even if they would all\ninsert the same string.\n\nThis style is tested for the default tag as well as for each tag valid for the current\ncompletion. Hence the listing can be forced only for certain types of match.\n\nformat If this is set for the descriptions tag, its value is used as a string to display\nabove matches in completion lists. The sequence `%d' in this string will be replaced\nwith a short description of what these matches are. This string may also contain the\noutput attribute sequences understood by compadd -X (see zshcompwid(1)).\n\nThe style is tested with each tag valid for the current completion before it is tested\nfor the descriptions tag. Hence different format strings can be defined for different\ntypes of match.\n\nNote also that some completer functions define additional `%'-sequences. These are\ndescribed for the completer functions that make use of them.\n\nSome completion functions display messages that may be customised by setting this\nstyle for the messages tag. Here, the `%d' is replaced with a message given by the\ncompletion function.\n\nFinally, the format string is looked up with the warnings tag, for use when no matches\ncould be generated at all. In this case the `%d' is replaced with the descriptions\nfor the matches that were expected separated by spaces. The sequence `%D' is replaced\nwith the same descriptions separated by newlines.\n\nIt is possible to use printf-style field width specifiers with `%d' and similar escape\nsequences. This is handled by the zformat builtin command from the zsh/zutil module,\nsee zshmodules(1).\n" }, { "name": "gain-privileges", "content": "If set to true, this style enables the use of commands like sudo or doas to gain extra\nprivileges when retrieving information for completion. This is only done when a com‐\nmand such as sudo appears on the command-line. To force the use of, e.g. sudo or to\noverride any prefix that might be added due to gain-privileges, the command style can\nbe used with a value that begins with a hyphen.\n\nglob This is used by the expand completer. If it is set to `true' (the default), globbing\nwill be attempted on the words resulting from a previous substitution (see the substi‐\ntute style) or else the original string from the line.\n\nglobal If this is set to `true' (the default), the expandalias completer and bindable com‐\nmand will try to expand global aliases.\n" }, { "name": "group-name", "content": "The completion system can group different types of matches, which appear in separate\nlists. This style can be used to give the names of groups for particular tags. For\nexample, in command position the completion system generates names of builtin and ex‐\nternal commands, names of aliases, shell functions and parameters and reserved words\nas possible completions. To have the external commands and shell functions listed\nseparately:\n\nzstyle ':completion:*:*:-command-:*:commands' \\\ngroup-name commands\nzstyle ':completion:*:*:-command-:*:functions' \\\ngroup-name functions\n\nAs a consequence, any match with the same tag will be displayed in the same group.\n\nIf the name given is the empty string the name of the tag for the matches will be used\nas the name of the group. So, to have all different types of matches displayed sepa‐\nrately, one can just set:\n\nzstyle ':completion:*' group-name ''\n\nAll matches for which no group name is defined will be put in a group named -default-.\n\nTo display the group name in the output, see the format style (q.v.) under the de‐\nscriptions tag.\n" }, { "name": "group-order", "content": "This style is additional to the group-name style to specify the order for display of\nthe groups defined by that style (compare tag-order, which determines which comple‐\ntions appear at all). The groups named are shown in the given order; any other groups\nare shown in the order defined by the completion function.\n\nFor example, to have names of builtin commands, shell functions and external commands\nappear in that order when completing in command position:\n\nzstyle ':completion:*:*:-command-:*:*' group-order \\\nbuiltins functions commands\n\ngroups A list of names of UNIX groups. If this is not set, group names are taken from the YP\ndatabase or the file `/etc/group'.\n\nhidden If this is set to `true', matches for the given context will not be listed, although\nany description for the matches set with the format style will be shown. If it is set\nto `all', not even the description will be displayed.\n\nNote that the matches will still be completed; they are just not shown in the list.\nTo avoid having matches considered as possible completions at all, the tag-order style\ncan be modified as described below.\n\nhosts A list of names of hosts that should be completed. If this is not set, hostnames are\ntaken from the file `/etc/hosts'.\n" }, { "name": "hosts-ports", "content": "This style is used by commands that need or accept hostnames and network ports. The\nstrings in the value should be of the form `host:port'. Valid ports are determined by\nthe presence of hostnames; multiple ports for the same host may appear.\n" }, { "name": "ignore-line", "content": "This is tested for each tag valid for the current completion. If it is set to `true',\nnone of the words that are already on the line will be considered as possible comple‐\ntions. If it is set to `current', the word the cursor is on will not be considered as\na possible completion. The value `current-shown' is similar but only applies if the\nlist of completions is currently shown on the screen. Finally, if the style is set to\n`other', all words on the line except for the current one will be excluded from the\npossible completions.\n\nThe values `current' and `current-shown' are a bit like the opposite of the accept-ex‐\nact style: only strings with missing characters will be completed.\n\nNote that you almost certainly don't want to set this to `true' or `other' for a gen‐\neral context such as `:completion:*'. This is because it would disallow completion\nof, for example, options multiple times even if the command in question accepts the\noption more than once.\n" }, { "name": "ignore-parents", "content": "The style is tested without a tag by the function completing pathnames in order to de‐\ntermine whether to ignore the names of directories already mentioned in the current\nword, or the name of the current working directory. The value must include one or\nboth of the following strings:\n\nparent The name of any directory whose path is already contained in the word on the\nline is ignored. For example, when completing after foo/../, the directory foo\nwill not be considered a valid completion.\n\npwd The name of the current working directory will not be completed; hence, for ex‐\nample, completion after ../ will not use the name of the current directory.\n\nIn addition, the value may include one or both of:\n\n.. Ignore the specified directories only when the word on the line contains the\nsubstring `../'.\n\ndirectory\nIgnore the specified directories only when names of directories are completed,\nnot when completing names of files.\n\nExcluded values act in a similar fashion to values of the ignored-patterns style, so\nthey can be restored to consideration by the ignored completer.\n" }, { "name": "ignored-patterns", "content": "A list of patterns; any trial completion matching one of the patterns will be excluded\nfrom consideration. The ignored completer can appear in the list of completers to\nrestore the ignored matches. This is a more configurable version of the shell parame‐\nter $fignore.\n\nNote that the EXTENDEDGLOB option is set during the execution of completion func‐\ntions, so the characters `#', `~' and `^' have special meanings in the patterns.\n\ninsert This style is used by the allmatches completer to decide whether to insert the list\nof all matches unconditionally instead of adding the list as another match.\n" }, { "name": "insert-ids", "content": "When completing process IDs, for example as arguments to the kill and wait builtins\nthe name of a command may be converted to the appropriate process ID. A problem\narises when the process name typed is not unique. By default (or if this style is set\nexplicitly to `menu') the name will be converted immediately to a set of possible IDs,\nand menu completion will be started to cycle through them.\n\nIf the value of the style is `single', the shell will wait until the user has typed\nenough to make the command unique before converting the name to an ID; attempts at\ncompletion will be unsuccessful until that point. If the value is any other string,\nmenu completion will be started when the string typed by the user is longer than the\ncommon prefix to the corresponding IDs.\n" }, { "name": "insert-sections", "content": "This style is used with tags of the form `manuals.X' when completing names of manual\npages. If set and the X in the tag name matches the section number of the page being\ncompleted, the section number is inserted along with the page name. For example, given\n\nzstyle ':completion:*:manuals.*' insert-sections true\n\nman ssh may be completed to man 5 sshconfig.\n\nThe value may also be set to one of `prepend', or `suffix'. `prepend' behaves the\nsame as `true' as in the above example, while `suffix' would complete man ssh as\nman sshconfig.5.\n\nThis is especially useful in conjunction with separate-sections, as it ensures that\nthe page requested of man corresponds to the one displayed in the completion listing\nwhen there are multiple pages with the same name (e.g., printf(1) and printf(3)).\n\nThe default for this style is `false'.\n" }, { "name": "insert-tab", "content": "If this is set to `true', the completion system will insert a TAB character (assuming\nthat was used to start completion) instead of performing completion when there is no\nnon-blank character to the left of the cursor. If it is set to `false', completion\nwill be done even there.\n\nThe value may also contain the substrings `pending' or `pending=val'. In this case,\nthe typed character will be inserted instead of starting completion when there is un‐\nprocessed input pending. If a val is given, completion will not be done if there are\nat least that many characters of unprocessed input. This is often useful when pasting\ncharacters into a terminal. Note however, that it relies on the $PENDING special pa‐\nrameter from the zsh/zle module being set properly which is not guaranteed on all\nplatforms.\n\nThe default value of this style is `true' except for completion within vared builtin\ncommand where it is `false'.\n" }, { "name": "insert-unambiguous", "content": "This is used by the match and approximate completers. These completers are often\nused with menu completion since the word typed may bear little resemblance to the fi‐\nnal completion. However, if this style is `true', the completer will start menu com‐\npletion only if it could find no unambiguous initial string at least as long as the\noriginal string typed by the user.\n\nIn the case of the approximate completer, the completer field in the context will al‐\nready have been set to one of correct-num or approximate-num, where num is the number\nof errors that were accepted.\n\nIn the case of the match completer, the style may also be set to the string `pat‐\ntern'. Then the pattern on the line is left unchanged if it does not match unambigu‐\nously.\n" }, { "name": "keep-prefix", "content": "This style is used by the expand completer. If it is `true', the completer will try\nto keep a prefix containing a tilde or parameter expansion. Hence, for example, the\nstring `~/f*' would be expanded to `~/foo' instead of `/home/user/foo'. If the style\nis set to `changed' (the default), the prefix will only be left unchanged if there\nwere other changes between the expanded words and the original word from the command\nline. Any other value forces the prefix to be expanded unconditionally.\n\nThe behaviour of expand when this style is `true' is to cause expand to give up when\na single expansion with the restored prefix is the same as the original; hence any re‐\nmaining completers may be called.\n" }, { "name": "known-hosts-files", "content": "This style should contain a list of files to search for host names and (if the use-ip\nstyle is set) IP addresses in a format compatible with ssh knownhosts files. If it\nis not set, the files /etc/ssh/sshknownhosts and ~/.ssh/knownhosts are used.\n" }, { "name": "last-prompt", "content": "This is a more flexible form of the ALWAYSLASTPROMPT option. If it is `true', the\ncompletion system will try to return the cursor to the previous command line after\ndisplaying a completion list. It is tested for all tags valid for the current comple‐\ntion, then the default tag. The cursor will be moved back to the previous line if\nthis style is `true' for all types of match. Note that unlike the ALWAYSLASTPROMPT\noption this is independent of the numeric argument.\n\nlist This style is used by the historycompleteword bindable command. If it is set to\n`true' it has no effect. If it is set to `false' matches will not be listed. This\noverrides the setting of the options controlling listing behaviour, in particular\nAUTOLIST. The context always starts with `:completion:history-words'.\n" }, { "name": "list-colors", "content": "If the zsh/complist module is loaded, this style can be used to set color specifica‐\ntions. This mechanism replaces the use of the ZLSCOLORS and ZLSCOLOURS parameters\ndescribed in the section `The zsh/complist Module' in zshmodules(1), but the syntax is\nthe same.\n\nIf this style is set for the default tag, the strings in the value are taken as speci‐\nfications that are to be used everywhere. If it is set for other tags, the specifica‐\ntions are used only for matches of the type described by the tag. For this to work\nbest, the group-name style must be set to an empty string.\n\nIn addition to setting styles for specific tags, it is also possible to use group\nnames specified explicitly by the group-name tag together with the `(group)' syntax\nallowed by the ZLSCOLORS and ZLSCOLOURS parameters and simply using the default tag.\n\nIt is possible to use any color specifications already set up for the GNU version of\nthe ls command:\n\nzstyle ':completion:*:default' list-colors \\\n${(s.:.)LSCOLORS}\n\nThe default colors are the same as for the GNU ls command and can be obtained by set‐\nting the style to an empty string (i.e. '').\n" }, { "name": "list-dirs-first", "content": "This is used by file completion and corresponds to a particular setting of the\nfile-patterns style. If set, the default directories to be completed are listed sepa‐\nrately from and before completion for other files.\n" }, { "name": "list-grouped", "content": "If this style is `true' (the default), the completion system will try to make certain\ncompletion listings more compact by grouping matches. For example, options for com‐\nmands that have the same description (shown when the verbose style is set to `true')\nwill appear as a single entry. However, menu selection can be used to cycle through\nall the matches.\n" }, { "name": "list-packed", "content": "This is tested for each tag valid in the current context as well as the default tag.\nIf it is set to `true', the corresponding matches appear in listings as if the\nLISTPACKED option were set. If it is set to `false', they are listed normally.\n" }, { "name": "list-prompt", "content": "If this style is set for the default tag, completion lists that don't fit on the\nscreen can be scrolled (see the description of the zsh/complist module in zshmod‐\nules(1)). The value, if not the empty string, will be displayed after every screenful\nand the shell will prompt for a key press; if the style is set to the empty string, a\ndefault prompt will be used.\n\nThe value may contain the escape sequences: `%l' or `%L', which will be replaced by\nthe number of the last line displayed and the total number of lines; `%m' or `%M', the\nnumber of the last match shown and the total number of matches; and `%p' and `%P',\n`Top' when at the beginning of the list, `Bottom' when at the end and the position\nshown as a percentage of the total length otherwise. In each case the form with the\nuppercase letter will be replaced by a string of fixed width, padded to the right\nwith spaces, while the lowercase form will be replaced by a variable width string. As\nin other prompt strings, the escape sequences `%S', `%s', `%B', `%b', `%U', `%u' for\nentering and leaving the display modes standout, bold and underline, and `%F', `%f',\n`%K', `%k' for changing the foreground background colour, are also available, as is\nthe form `%{...%}' for enclosing escape sequences which display with zero (or, with a\nnumeric argument, some other) width.\n\nAfter deleting this prompt the variable LISTPROMPT should be unset for the removal to\ntake effect.\n" }, { "name": "list-rows-first", "content": "This style is tested in the same way as the list-packed style and determines whether\nmatches are to be listed in a rows-first fashion as if the LISTROWSFIRST option were\nset.\n" }, { "name": "list-separator", "content": "The value of this style is used in completion listing to separate the string to com‐\nplete from a description when possible (e.g. when completing options). It defaults to\n`--' (two hyphens).\n" }, { "name": "list-suffixes", "content": "This style is used by the function that completes filenames. If it is `true', and\ncompletion is attempted on a string containing multiple partially typed pathname com‐\nponents, all ambiguous components will be shown. Otherwise, completion stops at the\nfirst ambiguous component.\n\nlocal This is for use with functions that complete URLs for which the corresponding files\nare available directly from the file system. Its value should consist of three\nstrings: a hostname, the path to the default web pages for the server, and the direc‐\ntory name used by a user placing web pages within their home area.\n\nFor example:\n\nzstyle ':completion:*' local toast \\\n/var/http/public/toast publichtml\n\nCompletion after `http://toast/stuff/' will look for files in the directory\n/var/http/public/toast/stuff, while completion after `http://toast/~yousir/' will\nlook for files in the directory ~yousir/publichtml.\n" }, { "name": "mail-directory", "content": "If set, zsh will assume that mailbox files can be found in the directory specified.\nIt defaults to `~/Mail'.\n" }, { "name": "match-original", "content": "This is used by the match completer. If it is set to only, match will try to gener‐\nate matches without inserting a `*' at the cursor position. If set to any other\nnon-empty value, it will first try to generate matches without inserting the `*' and\nif that yields no matches, it will try again with the `*' inserted. If it is unset or\nset to the empty string, matching will only be performed with the `*' inserted.\n" }, { "name": "matcher", "content": "This style is tested separately for each tag valid in the current context. Its value\nis placed before any match specifications given by the matcher-list style so can over‐\nride them via the use of an x: specification. The value should be in the form de‐\nscribed in the section `Completion Matching Control' in zshcompwid(1). For examples\nof this, see the description of the tag-order style.\n\nFor notes comparing the use of this and the matcher-list style, see under the descrip‐\ntion of the tag-order style.\n" }, { "name": "matcher-list", "content": "This style can be set to a list of match specifications that are to be applied every‐\nwhere. Match specifications are described in the section `Completion Matching Control'\nin zshcompwid(1). The completion system will try them one after another for each com‐\npleter selected. For example, to try first simple completion and, if that generates\nno matches, case-insensitive completion:\n\nzstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}'\n\nBy default each specification replaces the previous one; however, if a specification\nis prefixed with +, it is added to the existing list. Hence it is possible to create\nincreasingly general specifications without repetition:\n\nzstyle ':completion:*' matcher-list \\\n'' '+m:{a-z}={A-Z}' '+m:{A-Z}={a-z}'\n\nIt is possible to create match specifications valid for particular completers by using\nthe third field of the context. This applies only to completers that override the\nglobal matcher-list, which as of this writing includes only prefix and ignored. For\nexample, to use the completers complete and prefix but allow case-insensitive com‐\npletion only with complete:\n\nzstyle ':completion:*' completer complete prefix\nzstyle ':completion:*:complete:*:*:*' matcher-list \\\n'' 'm:{a-zA-Z}={A-Za-z}'\n\nUser-defined names, as explained for the completer style, are available. This makes\nit possible to try the same completer more than once with different match specifica‐\ntions each time. For example, to try normal completion without a match specification,\nthen normal completion with case-insensitive matching, then correction, and finally\npartial-word completion:\n\nzstyle ':completion:*' completer \\\ncomplete correct complete:foo\nzstyle ':completion:*:complete:*:*:*' matcher-list \\\n'' 'm:{a-zA-Z}={A-Za-z}'\nzstyle ':completion:*:foo:*:*:*' matcher-list \\\n'm:{a-zA-Z}={A-Za-z} r:|[-./]=* r:|=*'\n\nIf the style is unset in any context no match specification is applied. Note also\nthat some completers such as correct and approximate do not use the match specifica‐\ntions at all, though these completers will only ever be called once even if the\nmatcher-list contains more than one element.\n\nWhere multiple specifications are useful, note that the entire completion is done for\neach element of matcher-list, which can quickly reduce the shell's performance. As a\nrough rule of thumb, one to three strings will give acceptable performance. On the\nother hand, putting multiple space-separated values into the same string does not have\nan appreciable impact on performance.\n\nIf there is no current matcher or it is empty, and the option NOCASEGLOB is in ef‐\nfect, the matching for files is performed case-insensitively in any case. However,\nany matcher must explicitly specify case-insensitive matching if that is required.\n\nFor notes comparing the use of this and the matcher style, see under the description\nof the tag-order style.\n" }, { "name": "max-errors", "content": "This is used by the approximate and correct completer functions to determine the\nmaximum number of errors to allow. The completer will try to generate completions by\nfirst allowing one error, then two errors, and so on, until either a match or matches\nwere found or the maximum number of errors given by this style has been reached.\n\nIf the value for this style contains the string `numeric', the completer function will\ntake any numeric argument as the maximum number of errors allowed. For example, with\n\nzstyle ':completion:*:approximate:::' max-errors 2 numeric\n\ntwo errors are allowed if no numeric argument is given, but with a numeric argument of\nsix (as in `ESC-6 TAB'), up to six errors are accepted. Hence with a value of `0 nu‐\nmeric', no correcting completion will be attempted unless a numeric argument is given.\n\nIf the value contains the string `not-numeric', the completer will not try to generate\ncorrected completions when given a numeric argument, so in this case the number given\nshould be greater than zero. For example, `2 not-numeric' specifies that correcting\ncompletion with two errors will usually be performed, but if a numeric argument is\ngiven, correcting completion will not be performed.\n\nThe default value for this style is `2 numeric'.\n" }, { "name": "max-matches-width", "content": "This style is used to determine the trade off between the width of the display used\nfor matches and the width used for their descriptions when the verbose style is in ef‐\nfect. The value gives the number of display columns to reserve for the matches. The\ndefault is half the width of the screen.\n\nThis has the most impact when several matches have the same description and so will be\ngrouped together. Increasing the style will allow more matches to be grouped to‐\ngether; decreasing it will allow more of the description to be visible.\n\nmenu If this is `true' in the context of any of the tags defined for the current completion\nmenu completion will be used. The value for a specific tag will take precedence over\nthat for the `default' tag.\n\nIf none of the values found in this way is `true' but at least one is set to `auto',\nthe shell behaves as if the AUTOMENU option is set.\n\nIf one of the values is explicitly set to `false', menu completion will be explicitly\nturned off, overriding the MENUCOMPLETE option and other settings.\n\nIn the form `yes=num', where `yes' may be any of the `true' values (`yes', `true',\n`on' and `1'), menu completion will be turned on if there are at least num matches.\nIn the form `yes=long', menu completion will be turned on if the list does not fit on\nthe screen. This does not activate menu completion if the widget normally only lists\ncompletions, but menu completion can be activated in that case with the value\n`yes=long-list' (Typically, the value `select=long-list' described later is more use‐\nful as it provides control over scrolling.)\n\nSimilarly, with any of the `false' values (as in `no=10'), menu completion will not be\nused if there are num or more matches.\n\nThe value of this widget also controls menu selection, as implemented by the zsh/com‐\nplist module. The following values may appear either alongside or instead of the val‐\nues above.\n\nIf the value contains the string `select', menu selection will be started uncondition‐\nally.\n\nIn the form `select=num', menu selection will only be started if there are at least\nnum matches. If the values for more than one tag provide a number, the smallest num‐\nber is taken.\n\nMenu selection can be turned off explicitly by defining a value containing the\nstring`no-select'.\n\nIt is also possible to start menu selection only if the list of matches does not fit\non the screen by using the value `select=long'. To start menu selection even if the\ncurrent widget only performs listing, use the value `select=long-list'.\n\nTo turn on menu completion or menu selection when there are a certain number of\nmatches or the list of matches does not fit on the screen, both of `yes=' and `se‐\nlect=' may be given twice, once with a number and once with `long' or `long-list'.\n\nFinally, it is possible to activate two special modes of menu selection. The word\n`interactive' in the value causes interactive mode to be entered immediately when menu\nselection is started; see the description of the zsh/complist module in zshmodules(1)\nfor a description of interactive mode. Including the string `search' does the same\nfor incremental search mode. To select backward incremental search, include the\nstring `search-backward'.\n\nmuttrc If set, gives the location of the mutt configuration file. It defaults to `~/.mut‐\ntrc'.\n" }, { "name": "numbers", "content": "This is used with the jobs tag. If it is `true', the shell will complete job numbers\ninstead of the shortest unambiguous prefix of the job command text. If the value is a\nnumber, job numbers will only be used if that many words from the job descriptions are\nrequired to resolve ambiguities. For example, if the value is `1', strings will only\nbe used if all jobs differ in the first word on their command lines.\n" }, { "name": "old-list", "content": "This is used by the oldlist completer. If it is set to `always', then standard wid‐\ngets which perform listing will retain the current list of matches, however they were\ngenerated; this can be turned off explicitly with the value `never', giving the behav‐\niour without the oldlist completer. If the style is unset, or any other value, then\nthe existing list of completions is displayed if it is not already; otherwise, the\nstandard completion list is generated; this is the default behaviour of oldlist.\nHowever, if there is an old list and this style contains the name of the completer\nfunction that generated the list, then the old list will be used even if it was gener‐\nated by a widget which does not do listing.\n\nFor example, suppose you type ^Xc to use the correctword widget, which generates a\nlist of corrections for the word under the cursor. Usually, typing ^D would generate\na standard list of completions for the word on the command line, and show that. With\noldlist, it will instead show the list of corrections already generated.\n\nAs another example consider the match completer: with the insert-unambiguous style\nset to `true' it inserts only a common prefix string, if there is any. However, this\nmay remove parts of the original pattern, so that further completion could produce\nmore matches than on the first attempt. By using the oldlist completer and setting\nthis style to match, the list of matches generated on the first attempt will be used\nagain.\n" }, { "name": "old-matches", "content": "This is used by the allmatches completer to decide if an old list of matches should\nbe used if one exists. This is selected by one of the `true' values or by the string\n`only'. If the value is `only', allmatches will only use an old list and won't have\nany effect on the list of matches currently being generated.\n\nIf this style is set it is generally unwise to call the allmatches completer uncon‐\nditionally. One possible use is for either this style or the completer style to be\ndefined with the -e option to zstyle to make the style conditional.\n" }, { "name": "old-menu", "content": "This is used by the oldlist completer. It controls how menu completion behaves when\na completion has already been inserted and the user types a standard completion key\nsuch as TAB. The default behaviour of oldlist is that menu completion always contin‐\nues with the existing list of completions. If this style is set to `false', however,\na new completion is started if the old list was generated by a different completion\ncommand; this is the behaviour without the oldlist completer.\n\nFor example, suppose you type ^Xc to generate a list of corrections, and menu comple‐\ntion is started in one of the usual ways. Usually, or with this style set to `false',\ntyping TAB at this point would start trying to complete the line as it now appears.\nWith oldlist, it instead continues to cycle through the list of corrections.\n" }, { "name": "original", "content": "This is used by the approximate and correct completers to decide if the original\nstring should be added as a possible completion. Normally, this is done only if there\nare at least two possible corrections, but if this style is set to `true', it is al‐\nways added. Note that the style will be examined with the completer field in the con‐\ntext name set to correct-num or approximate-num, where num is the number of errors\nthat were accepted.\n" }, { "name": "packageset", "content": "This style is used when completing arguments of the Debian `dpkg' program. It con‐\ntains an override for the default package set for a given context. For example,\n\nzstyle ':completion:*:complete:dpkg:option--status-1:*' \\\npackageset avail\n\ncauses available packages, rather than only installed packages, to be completed for\n`dpkg --status'.\n\npath The function that completes color names uses this style with the colors tag. The\nvalue should be the pathname of a file containing color names in the format of an X11\nrgb.txt file. If the style is not set but this file is found in one of various stan‐\ndard locations it will be used as the default.\n" }, { "name": "path-completion", "content": "This is used by filename completion. By default, filename completion examines all\ncomponents of a path to see if there are completions of that component. For example,\n/u/b/z can be completed to /usr/bin/zsh. Explicitly setting this style to `false' in‐\nhibits this behaviour for path components up to the / before the cursor; this over‐\nrides the setting of accept-exact-dirs.\n\nEven with the style set to `false', it is still possible to complete multiple paths by\nsetting the option COMPLETEINWORD and moving the cursor back to the first component\nin the path to be completed. For example, /u/b/z can be completed to /usr/bin/zsh if\nthe cursor is after the /u.\n" }, { "name": "pine-directory", "content": "If set, specifies the directory containing PINE mailbox files. There is no default,\nsince recursively searching this directory is inconvenient for anyone who doesn't use\nPINE.\n\nports A list of Internet service names (network ports) to complete. If this is not set,\nservice names are taken from the file `/etc/services'.\n" }, { "name": "prefix-hidden", "content": "This is used for certain completions which share a common prefix, for example command\noptions beginning with dashes. If it is `true', the prefix will not be shown in the\nlist of matches.\n\nThe default value for this style is `false'.\n" }, { "name": "prefix-needed", "content": "This style is also relevant for matches with a common prefix. If it is set to `true'\nthis common prefix must be typed by the user to generate the matches.\n\nThe style is applicable to the options, signals, jobs, functions, and parameters com‐\npletion tags.\n\nFor command options, this means that the initial `-', `+', or `--' must be typed ex‐\nplicitly before option names will be completed.\n\nFor signals, an initial `-' is required before signal names will be completed.\n\nFor jobs, an initial `%' is required before job names will be completed.\n\nFor function and parameter names, an initial `' or `.' is required before function or\nparameter names starting with those characters will be completed.\n\nThe default value for this style is `false' for function and parameter completions,\nand `true' otherwise.\n" }, { "name": "preserve-prefix", "content": "This style is used when completing path names. Its value should be a pattern matching\nan initial prefix of the word to complete that should be left unchanged under all cir‐\ncumstances. For example, on some Unices an initial `//' (double slash) has a special\nmeaning; setting this style to the string `//' will preserve it. As another example,\nsetting this style to `?:/' under Cygwin would allow completion after `a:/...' and so\non.\n\nrange This is used by the history completer and the historycompleteword bindable command\nto decide which words should be completed.\n\nIf it is a single number, only the last N words from the history will be completed.\n\nIf it is a range of the form `max:slice', the last slice words will be completed; then\nif that yields no matches, the slice words before those will be tried and so on. This\nprocess stops either when at least one match has been found, or max words have been\ntried.\n\nThe default is to complete all words from the history at once.\n" }, { "name": "recursive-files", "content": "If this style is set, its value is an array of patterns to be tested against `$PWD/':\nnote the trailing slash, which allows directories in the pattern to be delimited unam‐\nbiguously by including slashes on both sides. If an ordinary file completion fails\nand the word on the command line does not yet have a directory part to its name, the\nstyle is retrieved using the same tag as for the completion just attempted, then the\nelements tested against $PWD/ in turn. If one matches, then the shell reattempts com‐\npletion by prepending the word on the command line with each directory in the expan‐\nsion of /*(/) in turn. Typically the elements of the style will be set to restrict\nthe number of directories beneath the current one to a manageable number, for example\n`*/.git/*'.\n\nFor example,\n\nzstyle ':completion:*' recursive-files '*/zsh/*'\n\nIf the current directory is /home/pws/zsh/Src, then zletr can be completed to\nZle/zletricky.c.\n" }, { "name": "regular", "content": "This style is used by the expandalias completer and bindable command. If set to\n`true' (the default), regular aliases will be expanded but only in command position.\nIf it is set to `false', regular aliases will never be expanded. If it is set to\n`always', regular aliases will be expanded even if not in command position.\n\nrehash If this is set when completing external commands, the internal list (hash) of commands\nwill be updated for each search by issuing the rehash command. There is a speed\npenalty for this which is only likely to be noticeable when directories in the path\nhave slow file access.\n" }, { "name": "remote-access", "content": "If set to `false', certain commands will be prevented from making Internet connections\nto retrieve remote information. This includes the completion for the CVS command.\n\nIt is not always possible to know if connections are in fact to a remote site, so some\nmay be prevented unnecessarily.\n" }, { "name": "remove-all-dups", "content": "The historycompleteword bindable command and the history completer use this to de‐\ncide if all duplicate matches should be removed, rather than just consecutive dupli‐\ncates.\n" }, { "name": "select-prompt", "content": "If this is set for the default tag, its value will be displayed during menu selection\n(see the menu style above) when the completion list does not fit on the screen as a\nwhole. The same escapes as for the list-prompt style are understood, except that the\nnumbers refer to the match or line the mark is on. A default prompt is used when the\nvalue is the empty string.\n" }, { "name": "select-scroll", "content": "This style is tested for the default tag and determines how a completion list is\nscrolled during a menu selection (see the menu style above) when the completion list\ndoes not fit on the screen as a whole. If the value is `0' (zero), the list is\nscrolled by half-screenfuls; if it is a positive integer, the list is scrolled by the\ngiven number of lines; if it is a negative number, the list is scrolled by a screenful\nminus the absolute value of the given number of lines. The default is to scroll by\nsingle lines.\n" }, { "name": "separate-sections", "content": "This style is used with the manuals tag when completing names of manual pages. If it\nis `true', entries for different sections are added separately using tag names of the\nform `manuals.X', where X is the section number. When the group-name style is also in\neffect, pages from different sections will appear separately. This style is also used\nsimilarly with the words style when completing words for the dict command. It allows\nwords from different dictionary databases to be added separately. See also insert-sec‐\ntions.\n\nThe default for this style is `false'.\n" }, { "name": "show-ambiguity", "content": "If the zsh/complist module is loaded, this style can be used to highlight the first\nambiguous character in completion lists. The value is either a color indication such\nas those supported by the list-colors style or, with a value of `true', a default of\nunderlining is selected. The highlighting is only applied if the completion display\nstrings correspond to the actual matches.\n" }, { "name": "show-completer", "content": "Tested whenever a new completer is tried. If it is `true', the completion system out‐\nputs a progress message in the listing area showing what completer is being tried.\nThe message will be overwritten by any output when completions are found and is re‐\nmoved after completion is finished.\n" }, { "name": "single-ignored", "content": "This is used by the ignored completer when there is only one match. If its value is\n`show', the single match will be displayed but not inserted. If the value is `menu',\nthen the single match and the original string are both added as matches and menu com‐\npletion is started, making it easy to select either of them.\n\nsort This allows the standard ordering of matches to be overridden.\n\nIf its value is `true' or `false', sorting is enabled or disabled. Additionally the\nvalues associated with the `-o' option to compadd can also be listed: match, nosort,\nnumeric, reverse. If it is not set for the context, the standard behaviour of the\ncalling widget is used.\n\nThe style is tested first against the full context including the tag, and if that\nfails to produce a value against the context without the tag.\n\nIn many cases where a calling widget explicitly selects a particular ordering in lieu\nof the default, a value of `true' is not honoured. An example of where this is not\nthe case is for command history where the default of sorting matches chronologically\nmay be overridden by setting the style to `true'.\n\nIn the expand completer, if it is set to `true', the expansions generated will always\nbe sorted. If it is set to `menu', then the expansions are only sorted when they are\noffered as single strings but not in the string containing all possible expansions.\n" }, { "name": "special-dirs", "content": "Normally, the completion code will not produce the directory names `.' and `..' as\npossible completions. If this style is set to `true', it will add both `.' and `..'\nas possible completions; if it is set to `..', only `..' will be added.\n\nThe following example sets special-dirs to `..' when the current prefix is empty, is a\nsingle `.', or consists only of a path beginning with `../'. Otherwise the value is\n`false'.\n\nzstyle -e ':completion:*' special-dirs \\\n'[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)'\n" }, { "name": "squeeze-slashes", "content": "If set to `true', sequences of slashes in filename paths (for example in `foo//bar')\nwill be treated as a single slash. This is the usual behaviour of UNIX paths. How‐\never, by default the file completion function behaves as if there were a `*' between\nthe slashes.\n\nstop If set to `true', the historycompleteword bindable command will stop once when\nreaching the beginning or end of the history. Invoking historycompleteword will\nthen wrap around to the opposite end of the history. If this style is set to `false'\n(the default), historycompleteword will loop immediately as in a menu completion.\n" }, { "name": "strip-comments", "content": "If set to `true', this style causes non-essential comment text to be removed from com‐\npletion matches. Currently it is only used when completing e-mail addresses where it\nremoves any display name from the addresses, cutting them down to plain user@host\nform.\n" }, { "name": "subst-globs-only", "content": "This is used by the expand completer. If it is set to `true', the expansion will\nonly be used if it resulted from globbing; hence, if expansions resulted from the use\nof the substitute style described below, but these were not further changed by glob‐\nbing, the expansions will be rejected.\n\nThe default for this style is `false'.\n" }, { "name": "substitute", "content": "This boolean style controls whether the expand completer will first try to expand all\nsubstitutions in the string (such as `$(...)' and `${...}').\n\nThe default is `true'.\n\nsuffix This is used by the expand completer if the word starts with a tilde or contains a\nparameter expansion. If it is set to `true', the word will only be expanded if it\ndoesn't have a suffix, i.e. if it is something like `~foo' or `$foo' rather than\n`~foo/' or `$foo/bar', unless that suffix itself contains characters eligible for ex‐\npansion. The default for this style is `true'.\n" }, { "name": "tag-order", "content": "This provides a mechanism for sorting how the tags available in a particular context\nwill be used.\n\nThe values for the style are sets of space-separated lists of tags. The tags in each\nvalue will be tried at the same time; if no match is found, the next value is used.\n(See the file-patterns style for an exception to this behavior.)\n\nFor example:\n\nzstyle ':completion:*:complete:-command-:*:*' tag-order \\\n'commands functions'\n\nspecifies that completion in command position first offers external commands and shell\nfunctions. Remaining tags will be tried if no completions are found.\n\nIn addition to tag names, each string in the value may take one of the following\nforms:\n\n- If any value consists of only a hyphen, then only the tags specified in the\nother values are generated. Normally all tags not explicitly selected are\ntried last if the specified tags fail to generate any matches. This means that\na single value consisting only of a single hyphen turns off completion.\n\n! tags...\nA string starting with an exclamation mark specifies names of tags that are not\nto be used. The effect is the same as if all other possible tags for the con‐\ntext had been listed.\n\ntag:label ...\nHere, tag is one of the standard tags and label is an arbitrary name. Matches\nare generated as normal but the name label is used in contexts instead of tag.\nThis is not useful in words starting with !.\n\nIf the label starts with a hyphen, the tag is prepended to the label to form\nthe name used for lookup. This can be used to make the completion system try a\ncertain tag more than once, supplying different style settings for each at‐\ntempt; see below for an example.\n\ntag:label:description\nAs before, but description will replace the `%d' in the value of the format\nstyle instead of the default description supplied by the completion function.\nSpaces in the description must be quoted with a backslash. A `%d' appearing in\ndescription is replaced with the description given by the completion function.\n\nIn any of the forms above the tag may be a pattern or several patterns in the form\n`{pat1,pat2...}'. In this case all matching tags will be used except for any given\nexplicitly in the same string.\n\nOne use of these features is to try one tag more than once, setting other styles dif‐\nferently on each attempt, but still to use all the other tags without having to repeat\nthem all. For example, to make completion of function names in command position ig‐\nnore all the completion functions starting with an underscore the first time comple‐\ntion is tried:\n\nzstyle ':completion:*:*:-command-:*:*' tag-order \\\n'functions:-non-comp *' functions\nzstyle ':completion:*:functions-non-comp' \\\nignored-patterns '*'\n\nOn the first attempt, all tags will be offered but the functions tag will be replaced\nby functions-non-comp. The ignored-patterns style is set for this tag to exclude\nfunctions starting with an underscore. If there are no matches, the second value of\nthe tag-order style is used which completes functions using the default tag, this time\npresumably including all function names.\n\nThe matches for one tag can be split into different groups. For example:\n\nzstyle ':completion:*' tag-order \\\n'options:-long:long\\ options\noptions:-short:short\\ options\noptions:-single-letter:single\\ letter\\ options'\nzstyle ':completion:*:options-long' \\\nignored-patterns '[-+](|-|[^-]*)'\nzstyle ':completion:*:options-short' \\\nignored-patterns '--*' '[-+]?'\nzstyle ':completion:*:options-single-letter' \\\nignored-patterns '???*'\n\nWith the group-names style set, options beginning with `--', options beginning with a\nsingle `-' or `+' but containing multiple characters, and single-letter options will\nbe displayed in separate groups with different descriptions.\n\nAnother use of patterns is to try multiple match specifications one after another.\nThe matcher-list style offers something similar, but it is tested very early in the\ncompletion system and hence can't be set for single commands nor for more specific\ncontexts. Here is how to try normal completion without any match specification and,\nif that generates no matches, try again with case-insensitive matching, restricting\nthe effect to arguments of the command foo:\n\nzstyle ':completion:*:*:foo:*:*' tag-order '*' '*:-case'\nzstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'\n\nFirst, all the tags offered when completing after foo are tried using the normal tag\nname. If that generates no matches, the second value of tag-order is used, which\ntries all tags again except that this time each has -case appended to its name for\nlookup of styles. Hence this time the value for the matcher style from the second\ncall to zstyle in the example is used to make completion case-insensitive.\n\nIt is possible to use the -e option of the zstyle builtin command to specify condi‐\ntions for the use of particular tags. For example:\n\nzstyle -e '*:-command-:*' tag-order '\nif [[ -n $PREFIX$SUFFIX ]]; then\nreply=( )\nelse\nreply=( - )\nfi'\n\nCompletion in command position will be attempted only if the string typed so far is\nnot empty. This is tested using the PREFIX special parameter; see zshcompwid for a\ndescription of parameters which are special inside completion widgets. Setting reply\nto an empty array provides the default behaviour of trying all tags at once; setting\nit to an array containing only a hyphen disables the use of all tags and hence of all\ncompletions.\n\nIf no tag-order style has been defined for a context, the strings `(|*-)argument-*\n(|*-)option-* values' and `options' plus all tags offered by the completion function\nwill be used to provide a sensible default behavior that causes arguments (whether\nnormal command arguments or arguments of options) to be completed before option names\nfor most commands.\n\nurls This is used together with the urls tag by functions completing URLs.\n\nIf the value consists of more than one string, or if the only string does not name a\nfile or directory, the strings are used as the URLs to complete.\n\nIf the value contains only one string which is the name of a normal file the URLs are\ntaken from that file (where the URLs may be separated by white space or newlines).\n\nFinally, if the only string in the value names a directory, the directory hierarchy\nrooted at this directory gives the completions. The top level directory should be the\nfile access method, such as `http', `ftp', `bookmark' and so on. In many cases the\nnext level of directories will be a filename. The directory hierarchy can descend as\ndeep as necessary.\n\nFor example,\n\nzstyle ':completion:*' urls ~/.urls\nmkdir -p ~/.urls/ftp/ftp.zsh.org/pub\n\nallows completion of all the components of the URL ftp://ftp.zsh.org/pub after suit‐\nable commands such as `netscape' or `lynx'. Note, however, that access methods and\nfiles are completed separately, so if the hosts style is set hosts can be completed\nwithout reference to the urls style.\n\nSee the description in the function urls itself for more information (e.g. `more\n$^fpath/urls(N)').\n" }, { "name": "use-cache", "content": "If this is set, the completion caching layer is activated for any completions which\nuse it (via the storecache, retrievecache, and cacheinvalid functions). The di‐\nrectory containing the cache files can be changed with the cache-path style.\n" }, { "name": "use-compctl", "content": "If this style is set to a string not equal to false, 0, no, and off, the completion\nsystem may use any completion specifications defined with the compctl builtin command.\nIf the style is unset, this is done only if the zsh/compctl module is loaded. The\nstring may also contain the substring `first' to use completions defined with `compctl\n-T', and the substring `default' to use the completion defined with `compctl -D'.\n\nNote that this is only intended to smooth the transition from compctl to the new com‐\npletion system and may disappear in the future.\n\nNote also that the definitions from compctl will only be used if there is no specific\ncompletion function for the command in question. For example, if there is a function\nfoo to complete arguments to the command foo, compctl will never be invoked for foo.\nHowever, the compctl version will be tried if foo only uses default completion.\n\nuse-ip By default, the function hosts that completes host names strips IP addresses from en‐\ntries read from host databases such as NIS and ssh files. If this style is `true',\nthe corresponding IP addresses can be completed as well. This style is not use in any\ncontext where the hosts style is set; note also it must be set before the cache of\nhost names is generated (typically the first completion attempt).\n\nusers This may be set to a list of usernames to be completed. If it is not set all user‐\nnames will be completed. Note that if it is set only that list of users will be com‐\npleted; this is because on some systems querying all users can take a prohibitive\namount of time.\n" }, { "name": "users-hosts", "content": "The values of this style should be of the form `user@host' or `user:host'. It is used\nfor commands that need pairs of user- and hostnames. These commands will complete\nusernames from this style (only), and will restrict subsequent hostname completion to\nhosts paired with that user in one of the values of the style.\n\nIt is possible to group values for sets of commands which allow a remote login, such\nas rlogin and ssh, by using the my-accounts tag. Similarly, values for sets of com‐\nmands which usually refer to the accounts of other people, such as talk and finger,\ncan be grouped by using the other-accounts tag. More ambivalent commands may use the\naccounts tag.\n" }, { "name": "users-hosts-ports", "content": "Like users-hosts but used for commands like telnet and containing strings of the form\n`user@host:port'.\n" }, { "name": "verbose", "content": "If set, as it is by default, the completion listing is more verbose. In particular\nmany commands show descriptions for options if this style is `true'.\n\nword This is used by the list completer, which prevents the insertion of completions until\na second completion attempt when the line has not changed. The normal way of finding\nout if the line has changed is to compare its entire contents between the two occa‐\nsions. If this style is `true', the comparison is instead performed only on the cur‐\nrent word. Hence if completion is performed on another word with the same contents,\ncompletion will not be delayed.\n" } ] }, "CONTROL FUNCTIONS": { "content": "The initialization script compinit redefines all the widgets which perform completion to call\nthe supplied widget function maincomplete. This function acts as a wrapper calling the\nso-called `completer' functions that generate matches. If maincomplete is called with ar‐\nguments, these are taken as the names of completer functions to be called in the order given.\nIf no arguments are given, the set of functions to try is taken from the completer style.\nFor example, to use normal completion and correction if that doesn't generate any matches:\n\nzstyle ':completion:*' completer complete correct\n\nafter calling compinit. The default value for this style is `complete ignored', i.e. nor‐\nmally only ordinary completion is tried, first with the effect of the ignored-patterns style\nand then without it. The maincomplete function uses the return status of the completer\nfunctions to decide if other completers should be called. If the return status is zero, no\nother completers are tried and the maincomplete function returns.\n\nIf the first argument to maincomplete is a single hyphen, the arguments will not be taken\nas names of completers. Instead, the second argument gives a name to use in the completer\nfield of the context and the other arguments give a command name and arguments to call to\ngenerate the matches.\n\nThe following completer functions are contained in the distribution, although users may write\ntheir own. Note that in contexts the leading underscore is stripped, for example basic com‐\npletion is performed in the context `:completion::complete:...'.\n", "subsections": [ { "name": "_all_matches", "content": "This completer can be used to add a string consisting of all other matches. As it in‐\nfluences later completers it must appear as the first completer in the list. The list\nof all matches is affected by the avoid-completer and old-matches styles described\nabove.\n\nIt may be useful to use the generic function described below to bind allmatches to\nits own keystroke, for example:\n\nzle -C all-matches complete-word generic\nbindkey '^Xa' all-matches\nzstyle ':completion:all-matches:*' old-matches only\nzstyle ':completion:all-matches::::' completer allmatches\n\nNote that this does not generate completions by itself: first use any of the standard\nways of generating a list of completions, then use ^Xa to show all matches. It is\npossible instead to add a standard completer to the list and request that the list of\nall matches should be directly inserted:\n\nzstyle ':completion:all-matches::::' completer \\\nallmatches complete\nzstyle ':completion:all-matches:*' insert true\n\nIn this case the old-matches style should not be set.\n" }, { "name": "_approximate", "content": "This is similar to the basic complete completer but allows the completions to undergo\ncorrections. The maximum number of errors can be specified by the max-errors style;\nsee the description of approximate matching in zshexpn(1) for how errors are counted.\nNormally this completer will only be tried after the normal complete completer:\n\nzstyle ':completion:*' completer complete approximate\n\nThis will give correcting completion if and only if normal completion yields no possi‐\nble completions. When corrected completions are found, the completer will normally\nstart menu completion allowing you to cycle through these strings.\n\nThis completer uses the tags corrections and original when generating the possible\ncorrections and the original string. The format style for the former may contain the\nadditional sequences `%e' and `%o' which will be replaced by the number of errors ac‐\ncepted to generate the corrections and the original string, respectively.\n\nThe completer progressively increases the number of errors allowed up to the limit by\nthe max-errors style, hence if a completion is found with one error, no completions\nwith two errors will be shown, and so on. It modifies the completer name in the con‐\ntext to indicate the number of errors being tried: on the first try the completer\nfield contains `approximate-1', on the second try `approximate-2', and so on.\n\nWhen approximate is called from another function, the number of errors to accept may\nbe passed with the -a option. The argument is in the same format as the max-errors\nstyle, all in one string.\n\nNote that this completer (and the correct completer mentioned below) can be quite ex‐\npensive to call, especially when a large number of errors are allowed. One way to\navoid this is to set up the completer style using the -e option to zstyle so that some\ncompleters are only used when completion is attempted a second time on the same\nstring, e.g.:\n\nzstyle -e ':completion:*' completer '\nif [[ $lasttry != \"$HISTNO$BUFFER$CURSOR\" ]]; then\nlasttry=\"$HISTNO$BUFFER$CURSOR\"\nreply=(complete match prefix)\nelse\nreply=(ignored correct approximate)\nfi'\n\nThis uses the HISTNO parameter and the BUFFER and CURSOR special parameters that are\navailable inside zle and completion widgets to find out if the command line hasn't\nchanged since the last time completion was tried. Only then are the ignored, cor‐\nrect and approximate completers called.\n\ncanonicalpaths [ -A var ] [ -N ] [ -MJV12nfX ] tag descr [ paths ... ]\nThis completion function completes all paths given to it, and also tries to offer com‐\npletions which point to the same file as one of the paths given (relative path when an\nabsolute path is given, and vice versa; when ..'s are present in the word to be com‐\npleted; and some paths got from symlinks).\n\n-A, if specified, takes the paths from the array variable specified. Paths can also be\nspecified on the command line as shown above. -N, if specified, prevents canonicaliz‐\ning the paths given before using them for completion, in case they are already so. The\noptions -M, -J, -V, -1, -2, -n, -F, -X are passed to compadd.\n\nSee description for a description of tag and descr.\n" }, { "name": "_cmdambivalent", "content": "Completes the remaining positional arguments as an external command. The external\ncommand and its arguments are completed as separate arguments (in a manner appropriate\nfor completing /usr/bin/env) if there are two or more remaining positional arguments\non the command line, and as a quoted command string (in the manner of system(...))\notherwise. See also cmdstring and precommand.\n\nThis function takes no arguments.\n" }, { "name": "_cmdstring", "content": "Completes an external command as a single argument, as for system(...).\n" }, { "name": "_complete", "content": "This completer generates all possible completions in a context-sensitive manner, i.e.\nusing the settings defined with the compdef function explained above and the current\nsettings of all special parameters. This gives the normal completion behaviour.\n\nTo complete arguments of commands, complete uses the utility function normal, which\nis in turn responsible for finding the particular function; it is described below.\nVarious contexts of the form -context- are handled specifically. These are all men‐\ntioned above as possible arguments to the #compdef tag.\n\nBefore trying to find a function for a specific context, complete checks if the para‐\nmeter `compcontext' is set. Setting `compcontext' allows the usual completion dis‐\npatching to be overridden which is useful in places such as a function that uses vared\nfor input. If it is set to an array, the elements are taken to be the possible matches\nwhich will be completed using the tag `values' and the description `value'. If it is\nset to an associative array, the keys are used as the possible completions and the\nvalues (if non-empty) are used as descriptions for the matches. If `compcontext' is\nset to a string containing colons, it should be of the form `tag:descr:action'. In\nthis case the tag and descr give the tag and description to use and the action indi‐\ncates what should be completed in one of the forms accepted by the arguments utility\nfunction described below.\n\nFinally, if `compcontext' is set to a string without colons, the value is taken as the\nname of the context to use and the function defined for that context will be called.\nFor this purpose, there is a special context named -command-line- that completes whole\ncommand lines (commands and their arguments). This is not used by the completion sys‐\ntem itself but is nonetheless handled when explicitly called.\n" }, { "name": "_correct", "content": "Generate corrections, but not completions, for the current word; this is similar to\napproximate but will not allow any number of extra characters at the cursor as that\ncompleter does. The effect is similar to spell-checking. It is based on approxi‐\nmate, but the completer field in the context name is correct.\n\nFor example, with:\n\nzstyle ':completion:::::' completer \\\ncomplete correct approximate\nzstyle ':completion:*:correct:::' max-errors 2 not-numeric\nzstyle ':completion:*:approximate:::' max-errors 3 numeric\n\ncorrection will accept up to two errors. If a numeric argument is given, correction\nwill not be performed, but correcting completion will be, and will accept as many er‐\nrors as given by the numeric argument. Without a numeric argument, first correction\nand then correcting completion will be tried, with the first one accepting two errors\nand the second one accepting three errors.\n\nWhen correct is called as a function, the number of errors to accept may be given\nfollowing the -a option. The argument is in the same form a values to the accept\nstyle, all in one string.\n\nThis completer function is intended to be used without the approximate completer or,\nas in the example, just before it. Using it after the approximate completer is use‐\nless since approximate will at least generate the corrected strings generated by the\ncorrect completer -- and probably more.\n" }, { "name": "_expand", "content": "This completer function does not really perform completion, but instead checks if the\nword on the command line is eligible for expansion and, if it is, gives detailed con‐\ntrol over how this expansion is done. For this to happen, the completion system needs\nto be invoked with complete-word, not expand-or-complete (the default binding for\nTAB), as otherwise the string will be expanded by the shell's internal mechanism be‐\nfore the completion system is started. Note also this completer should be called be‐\nfore the complete completer function.\n\nThe tags used when generating expansions are all-expansions for the string containing\nall possible expansions, expansions when adding the possible expansions as single\nmatches and original when adding the original string from the line. The order in\nwhich these strings are generated, if at all, can be controlled by the group-order and\ntag-order styles, as usual.\n\nThe format string for all-expansions and for expansions may contain the sequence `%o'\nwhich will be replaced by the original string from the line.\n\nThe kind of expansion to be tried is controlled by the substitute, glob and\nsubst-globs-only styles.\n\nIt is also possible to call expand as a function, in which case the different modes\nmay be selected with options: -s for substitute, -g for glob and -o for\nsubst-globs-only.\n" }, { "name": "_expand_alias", "content": "If the word the cursor is on is an alias, it is expanded and no other completers are\ncalled. The types of aliases which are to be expanded can be controlled with the\nstyles regular, global and disabled.\n\nThis function is also a bindable command, see the section `Bindable Commands' below.\n" }, { "name": "_extensions", "content": "If the cursor follows the string `*.', filename extensions are completed. The exten‐\nsions are taken from files in current directory or a directory specified at the begin‐\nning of the current word. For exact matches, completion continues to allow other com‐\npleters such as expand to expand the pattern. The standard add-space and prefix-hid‐\nden styles are observed.\n" }, { "name": "_external_pwds", "content": "Completes current directories of other zsh processes belonging to the current user.\n\nThis is intended to be used via generic, bound to a custom key combination. Note that\npattern matching is enabled so matching is performed similar to how it works with the\nmatch completer.\n" }, { "name": "_history", "content": "Complete words from the shell's command history. This completer can be controlled by\nthe remove-all-dups, and sort styles as for the historycompleteword bindable com‐\nmand, see the section `Bindable Commands' below and the section `Completion System\nConfiguration' above.\n" }, { "name": "_ignored", "content": "The ignored-patterns style can be set to a list of patterns which are compared against\npossible completions; matching ones are removed. With this completer those matches\ncan be reinstated, as if no ignored-patterns style were set. The completer actually\ngenerates its own list of matches; which completers are invoked is determined in the\nsame way as for the prefix completer. The single-ignored style is also available as\ndescribed above.\n\nlist This completer allows the insertion of matches to be delayed until completion is at‐\ntempted a second time without the word on the line being changed. On the first at‐\ntempt, only the list of matches will be shown. It is affected by the styles condition\nand word, see the section `Completion System Configuration' above.\n\nmatch This completer is intended to be used after the complete completer. It behaves simi‐\nlarly but the string on the command line may be a pattern to match against trial com‐\npletions. This gives the effect of the GLOBCOMPLETE option.\n\nNormally completion will be performed by taking the pattern from the line, inserting a\n`*' at the cursor position and comparing the resulting pattern with the possible com‐\npletions generated. This can be modified with the match-original style described\nabove.\n\nThe generated matches will be offered in a menu completion unless the insert-unambigu‐\nous style is set to `true'; see the description above for other options for this\nstyle.\n\nNote that matcher specifications defined globally or used by the completion functions\n(the styles matcher-list and matcher) will not be used.\n\nmenu This completer was written as simple example function to show how menu completion can\nbe enabled in shell code. However, it has the notable effect of disabling menu selec‐\ntion which can be useful with generic based widgets. It should be used as the first\ncompleter in the list. Note that this is independent of the setting of the MENUCOM‐\nPLETE option and does not work with the other menu completion widgets such as re‐\nverse-menu-complete, or accept-and-menu-complete.\n" }, { "name": "_oldlist", "content": "This completer controls how the standard completion widgets behave when there is an\nexisting list of completions which may have been generated by a special completion\n(i.e. a separately-bound completion command). It allows the ordinary completion keys\nto continue to use the list of completions thus generated, instead of producing a new\nlist of ordinary contextual completions. It should appear in the list of completers\nbefore any of the widgets which generate matches. It uses two styles: old-list and\nold-menu, see the section `Completion System Configuration' above.\n" }, { "name": "_precommand", "content": "Complete an external command in word-separated arguments, as for exec and\n/usr/bin/env.\n" }, { "name": "_prefix", "content": "This completer can be used to try completion with the suffix (everything after the\ncursor) ignored. In other words, the suffix will not be considered to be part of the\nword to complete. The effect is similar to the expand-or-complete-prefix command.\n\nThe completer style is used to decide which other completers are to be called to gen‐\nerate matches. If this style is unset, the list of completers set for the current\ncontext is used -- except, of course, the prefix completer itself. Furthermore, if\nthis completer appears more than once in the list of completers only those completers\nnot already tried by the last invocation of prefix will be called.\n\nFor example, consider this global completer style:\n\nzstyle ':completion:*' completer \\\ncomplete prefix correct prefix:foo\n\nHere, the prefix completer tries normal completion but ignoring the suffix. If that\ndoesn't generate any matches, and neither does the call to the correct completer af‐\nter it, prefix will be called a second time and, now only trying correction with the\nsuffix ignored. On the second invocation the completer part of the context appears as\n`foo'.\n\nTo use prefix as the last resort and try only normal completion when it is invoked:\n\nzstyle ':completion:*' completer complete ... prefix\nzstyle ':completion::prefix:*' completer complete\n\nThe add-space style is also respected. If it is set to `true' then prefix will in‐\nsert a space between the matches generated (if any) and the suffix.\n\nNote that this completer is only useful if the COMPLETEINWORD option is set; other‐\nwise, the cursor will be moved to the end of the current word before the completion\ncode is called and hence there will be no suffix.\n" }, { "name": "_user_expand", "content": "This completer behaves similarly to the expand completer but instead performs expan‐\nsions defined by users. The styles add-space and sort styles specific to the expand\ncompleter are usable with userexpand in addition to other styles handled more gener‐\nally by the completion system. The tag all-expansions is also available.\n\nThe expansion depends on the array style user-expand being defined for the current\ncontext; remember that the context for completers is less specific than that for con‐\ntextual completion as the full context has not yet been determined. Elements of the\narray may have one of the following forms:\n\n$hash\n\nhash is the name of an associative array. Note this is not a full parameter\nexpression, merely a $, suitably quoted to prevent immediate expansion, fol‐\nlowed by the name of an associative array. If the trial expansion word matches\na key in hash, the resulting expansion is the corresponding value.\nfunc\n\nfunc is the name of a shell function whose name must begin with but is not\notherwise special to the completion system. The function is called with the\ntrial word as an argument. If the word is to be expanded, the function should\nset the array reply to a list of expansions. Optionally, it can set REPLY to a\nword that will be used as a description for the set of expansions. The return\nstatus of the function is irrelevant." } ] }, "BINDABLE COMMANDS": { "content": "In addition to the context-dependent completions provided, which are expected to work in an\nintuitively obvious way, there are a few widgets implementing special behaviour which can be\nbound separately to keys. The following is a list of these and their default bindings.\n", "subsections": [ { "name": "_bash_completions", "content": "This function is used by two widgets, bashcomplete-word and bashlist-choices. It\nexists to provide compatibility with completion bindings in bash. The last character\nof the binding determines what is completed: `!', command names; `$', environment\nvariables; `@', host names; `/', file names; `~' user names. In bash, the binding\npreceded by `\\e' gives completion, and preceded by `^X' lists options. As some of\nthese bindings clash with standard zsh bindings, only `\\e~' and `^X~' are bound by de‐\nfault. To add the rest, the following should be added to .zshrc after compinit has\nbeen run:\n\nfor key in '!' '$' '@' '/' '~'; do\nbindkey \"\\e$key\" bashcomplete-word\nbindkey \"^X$key\" bashlist-choices\ndone\n\nThis includes the bindings for `~' in case they were already bound to something else;\nthe completion code does not override user bindings.\n\ncorrectfilename (^XC)\nCorrect the filename path at the cursor position. Allows up to six errors in the\nname. Can also be called with an argument to correct a filename path, independently\nof zle; the correction is printed on standard output.\n\ncorrectword (^Xc)\nPerforms correction of the current argument using the usual contextual completions as\npossible choices. This stores the string `correct-word' in the function field of the\ncontext name and then calls the correct completer.\n\nexpandalias (^Xa)\nThis function can be used as a completer and as a bindable command. It expands the\nword the cursor is on if it is an alias. The types of alias expanded can be con‐\ntrolled with the styles regular, global and disabled.\n\nWhen used as a bindable command there is one additional feature that can be selected\nby setting the complete style to `true'. In this case, if the word is not the name of\nan alias, expandalias tries to complete the word to a full alias name without ex‐\npanding it. It leaves the cursor directly after the completed word so that invoking\nexpandalias once more will expand the now-complete alias name.\n\nexpandword (^Xe)\nPerforms expansion on the current word: equivalent to the standard expand-word com‐\nmand, but using the expand completer. Before calling it, the function field of the\ncontext is set to `expand-word'.\n" }, { "name": "_generic", "content": "This function is not defined as a widget and not bound by default. However, it can be\nused to define a widget and will then store the name of the widget in the function\nfield of the context and call the completion system. This allows custom completion\nwidgets with their own set of style settings to be defined easily. For example, to\ndefine a widget that performs normal completion and starts menu selection:\n\nzle -C foo complete-word generic\nbindkey '...' foo\nzstyle ':completion:foo:*' menu yes select=1\n\nNote in particular that the completer style may be set for the context in order to\nchange the set of functions used to generate possible matches. If generic is called\nwith arguments, those are passed through to maincomplete as the list of completers\nin place of those defined by the completer style.\n\nhistorycompleteword (\\e/)\nComplete words from the shell's command history. This uses the list, remove-all-dups,\nsort, and stop styles.\n\nmostrecentfile (^Xm)\nComplete the name of the most recently modified file matching the pattern on the com‐\nmand line (which may be blank). If given a numeric argument N, complete the Nth most\nrecently modified file. Note the completion, if any, is always unique.\n\nnexttags (^Xn)\nThis command alters the set of matches used to that for the next tag, or set of tags,\neither as given by the tag-order style or as set by default; these matches would oth‐\nerwise not be available. Successive invocations of the command cycle through all pos‐\nsible sets of tags.\n\nreadcomp (^X^R)\nPrompt the user for a string, and use that to perform completion on the current word.\nThere are two possibilities for the string. First, it can be a set of words beginning\n`', for example `files -/', in which case the function with any arguments will be\ncalled to generate the completions. Unambiguous parts of the function name will be\ncompleted automatically (normal completion is not available at this point) until a\nspace is typed.\n\nSecond, any other string will be passed as a set of arguments to compadd and should\nhence be an expression specifying what should be completed.\n\nA very restricted set of editing commands is available when reading the string: `DEL'\nand `^H' delete the last character; `^U' deletes the line, and `^C' and `^G' abort the\nfunction, while `RET' accepts the completion. Note the string is used verbatim as a\ncommand line, so arguments must be quoted in accordance with standard shell rules.\n\nOnce a string has been read, the next call to readcomp will use the existing string\ninstead of reading a new one. To force a new string to be read, call readcomp with\na numeric argument.\n\ncompletedebug (^X?)\nThis widget performs ordinary completion, but captures in a temporary file a trace of\nthe shell commands executed by the completion system. Each completion attempt gets\nits own file. A command to view each of these files is pushed onto the editor buffer\nstack.\n\ncompletehelp (^Xh)\nThis widget displays information about the context names, the tags, and the completion\nfunctions used when completing at the current cursor position. If given a numeric ar‐\ngument other than 1 (as in `ESC-2 ^Xh'), then the styles used and the contexts for\nwhich they are used will be shown, too.\n\nNote that the information about styles may be incomplete; it depends on the informa‐\ntion available from the completion functions called, which in turn is determined by\nthe user's own styles and other settings.\n" }, { "name": "_complete_help_generic", "content": "Unlike other commands listed here, this must be created as a normal ZLE widget rather\nthan a completion widget (i.e. with zle -N). It is used for generating help with a\nwidget bound to the generic widget that is described above.\n\nIf this widget is created using the name of the function, as it is by default, then\nwhen executed it will read a key sequence. This is expected to be bound to a call to\na completion function that uses the generic widget. That widget will be executed,\nand information provided in the same format that the completehelp widget displays\nfor contextual completion.\n\nIf the widget's name contains debug, for example if it is created as `zle -N com‐\npletedebuggeneric completehelpgeneric', it will read and execute the keystring\nfor a generic widget as before, but then generate debugging information as done by\ncompletedebug for contextual completion.\n\nIf the widget's name contains noread, it will not read a keystring but instead arrange\nthat the next use of a generic widget run in the same shell will have the effect as\ndescribed above.\n\nThe widget works by setting the shell parameter ZSHTRACEGENERICWIDGET which is read\nby generic. Unsetting the parameter cancels any pending effect of the noread form.\n\nFor example, after executing the following:\n\nzle -N completedebuggeneric completehelpgeneric\nbindkey '^x:' completedebuggeneric\n\ntyping `C-x :' followed by the key sequence for a generic widget will cause trace out‐\nput for that widget to be saved to a file.\n\ncompletetag (^Xt)\nThis widget completes symbol tags created by the etags or ctags programmes (note there\nis no connection with the completion system's tags) stored in a file TAGS, in the for‐\nmat used by etags, or tags, in the format created by ctags. It will look back up the\npath hierarchy for the first occurrence of either file; if both exist, the file TAGS\nis preferred. You can specify the full path to a TAGS or tags file by setting the pa‐\nrameter $TAGSFILE or $tagsfile respectively. The corresponding completion tags used\nare etags and vtags, after emacs and vi respectively.\n" } ] }, "UTILITY FUNCTIONS": { "content": "Descriptions follow for utility functions that may be useful when writing completion func‐\ntions. If functions are installed in subdirectories, most of these reside in the Base subdi‐\nrectory. Like the example functions for commands in the distribution, the utility functions\ngenerating matches all follow the convention of returning status zero if they generated com‐\npletions and non-zero if no matching completions could be added.\n", "subsections": [ { "name": "_absolute_command_paths", "content": "This function completes external commands as absolute paths (unlike commandnames -e\nwhich completes their basenames). It takes no arguments.\n\nalllabels [ -x ] [ -12VJ ] tag name descr [ command arg ... ]\nThis is a convenient interface to the nextlabel function below, implementing the\nloop shown in the nextlabel example. The command and its arguments are called to\ngenerate the matches. The options stored in the parameter name will automatically be\ninserted into the args passed to the command. Normally, they are put directly after\nthe command, but if one of the args is a single hyphen, they are inserted directly be‐\nfore that. If the hyphen is the last argument, it will be removed from the argument\nlist before the command is called. This allows alllabels to be used in almost all\ncases where the matches can be generated by a single call to the compadd builtin com‐\nmand or by a call to one of the utility functions.\n\nFor example:\n\nlocal expl\n...\nif requested foo; then\n...\nalllabels foo expl '...' compadd ... - $matches\nfi\n\nWill complete the strings from the matches parameter, using compadd with additional\noptions which will take precedence over those generated by alllabels.\n\nalternative [ -O name ] [ -C name ] spec ...\nThis function is useful in simple cases where multiple tags are available. Essen‐\ntially it implements a loop like the one described for the tags function below.\n\nThe tags to use and the action to perform if a tag is requested are described using\nthe specs which are of the form: `tag:descr:action'. The tags are offered using tags\nand if the tag is requested, the action is executed with the given description descr.\nThe actions are those accepted by the arguments function (described below), with the\nfollowing exceptions:\n• The `->state' and `=...' forms are not supported.\n\n\n• The `((a\\:bar b\\:baz))' form does not need the colon to be escaped, since the\nspecs have no colon-separated fields after the action.\n\n\nFor example, the action may be a simple function call:\n\nalternative \\\n'users:user:users' \\\n'hosts:host:hosts'\n\noffers usernames and hostnames as possible matches, generated by the users and hosts\nfunctions respectively.\n\nLike arguments, this function uses alllabels to execute the actions, which will\nloop over all sets of tags. Special handling is only required if there is an addi‐\ntional valid tag, for example inside a function called from alternative.\n\nThe option `-O name' is used in the same way as by the arguments function. In other\nwords, the elements of the name array will be passed to compadd when executing an ac‐\ntion.\n\nLike tags this function supports the -C option to give a different name for the argu‐\nment context field.\n\n\narguments [ -nswWCRS ] [ -A pat ] [ -O name ] [ -M matchspec ]\n[ : ] spec ...\narguments [ opt ... ] -- [ -l ] [ -i pats ] [ -s pair ]\n[ helpspec ...]\nThis function can be used to give a complete specification for completion for a com‐\nmand whose arguments follow standard UNIX option and argument conventions.\n\nOptions Overview\n\nOptions to arguments itself must be in separate words, i.e. -s -w, not -sw. The op‐\ntions are followed by specs that describe options and arguments of the analyzed com‐\nmand. To avoid ambiguity, all options to arguments itself may be separated from the\nspec forms by a single colon.\n\nThe `--' form is used to intuit spec forms from the help output of the command being\nanalyzed, and is described in detail below. The opts for the `--' form are otherwise\nthe same options as the first form. Note that `-s' following `--' has a distinct\nmeaning from `-s' preceding `--', and both may appear.\n\nThe option switches -s, -S, -A, -w, and -W affect how arguments parses the analyzed\ncommand line's options. These switches are useful for commands with standard argument\nparsing.\n\nThe options of arguments have the following meanings:\n\n-n With this option, arguments sets the parameter NORMARG to the position of the\nfirst normal argument in the $words array, i.e. the position after the end of\nthe options. If that argument has not been reached, NORMARG is set to -1. The\ncaller should declare `integer NORMARG' if the -n option is passed; otherwise\nthe parameter is not used.\n\n-s Enable option stacking for single-letter options, whereby multiple single-let‐\nter options may be combined into a single word. For example, the two options\n`-x' and `-y' may be combined into a single word `-xy'. By default, every word\ncorresponds to a single option 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 in the seg‐\nment entitled `Deriving spec forms from the help output'.\n\n-w In combination with -s, allow option stacking even if one or more of the op‐\ntions take arguments. For example, if -x takes an argument, with no -s, `-xy'\nis considered as a single (unhandled) option; with -s, -xy is an option with\nthe argument `y'; with both -s and -w, -xy is the option -x and the option -y\nwith arguments to -x (and to -y, if it takes arguments) still to come in subse‐\nquent words.\n\n-W This option takes -w a stage further: it is possible to complete single-letter\noptions even after an argument that occurs in the same word. However, it de‐\npends on the action performed whether options will really be completed at this\npoint. For more control, use a utility function like guard as part of the ac‐\ntion.\n\n-C Modify the curcontext parameter for an action of the form `->state'. This is\ndiscussed in detail below.\n\n-R Return status 300 instead of zero when a $state is to be handled, in the\n`->string' syntax.\n\n-S Do not complete options after a `--' appearing on the line, and ignore the\n`--'. For example, with -S, in the line\n\nfoobar -x -- -y\n\nthe `-x' is considered an option, the `-y' is considered an argument, and the\n`--' is considered to be neither.\n\n-A pat Do not complete options after the first non-option argument on the line. pat\nis a pattern matching all strings which are not to be taken as arguments. For\nexample, to make arguments stop completing options after the first normal ar‐\ngument, but ignoring all strings starting with a hyphen even if they are not\ndescribed by one of the optspecs, the form is `-A \"-*\"'.\n\n-O name\nPass the elements of the array name as arguments to functions called to execute\nactions. This 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 `-', such as\ncompleting `-f-b' to `-foo-bar'. The default matchspec is:\nr:|[-]=* r:|=*\n\n-0 When populating values of the `optargs' associative array, don't backslash-es‐\ncape colons and backslashes and use NUL rather than colon for joining multiple\nvalues. This option is described in more detail below, under the heading specs:\nactions.\n\nspecs: overview\n\nEach of the following forms is a spec describing individual sets of options or argu‐\nments on the command line being analyzed.\n\nn:message:action\nn::message:action\nThis describes the n'th normal argument. The message will be printed above the\nmatches generated and the action indicates what can be completed in this posi‐\ntion (see below). If there are two colons before the message the argument is\noptional. If the message contains only white space, nothing will be printed\nabove the matches unless the action adds an explanation string itself.\n\n:message:action\n::message:action\nSimilar, but describes the next argument, whatever number that happens to be.\nIf all arguments are specified in this form in the correct order the numbers\nare unnecessary.\n\n*:message:action\n*::message:action\n*:::message:action\nThis describes how arguments (usually non-option arguments, those not beginning\nwith - or +) are to be completed when neither of the first two forms was pro‐\nvided. Any number of arguments can be completed in this fashion.\n\nWith two colons before the message, the words special array and the CURRENT\nspecial parameter are modified to refer only to the normal arguments when the\naction is executed or evaluated. With three colons before the message they are\nmodified to refer only to the normal arguments covered by this description.\n\noptspec\noptspec:...\nThis describes an option. The colon indicates handling for one or more argu‐\nments to the option; if it is not present, the option is assumed to take no ar‐\nguments.\n\nThe following forms are available for the initial optspec, whether or not the\noption has arguments.\n\n*optspec\nHere optspec is one of the remaining forms below. This indicates the\nfollowing optspec may be repeated. Otherwise if the corresponding op‐\ntion is already present on the command line to the left of the cursor it\nwill not be offered again.\n\n-optname\n+optname\nIn the simplest form the optspec is just the option name beginning with\na minus or a plus sign, such as `-foo'. The first argument for the op‐\ntion (if any) must follow as a separate word directly after the option.\n\nEither of `-+optname' and `+-optname' can be used to specify that -opt‐\nname and +optname are both valid.\n\nIn all the remaining forms, the leading `-' may be replaced by or paired\nwith `+' in this way.\n\n-optname-\nThe first argument of the option must come directly after the option\nname in the same word. For example, `-foo-:...' specifies that the com‐\npleted option and argument will look like `-fooarg'.\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 will look\nlike either `-fooarg' 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 exam‐\nple `-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\noptspec[explanation]\nAn explanation string may be appended to any of the preceding forms of\noptspec by enclosing it in brackets, as in `-q[query operation]'.\n\nThe verbose style is used to decide whether the explanation strings are\ndisplayed 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 that follows the\noptspec; see below.\n\nIt is possible for options with a literal `+' or `=' to appear, but that char‐\nacter must be quoted, for example `-\\+'.\n\nEach optarg following an optspec must take one of the following forms:\n\n:message:action\n::message:action\nAn argument to the option; message and action are treated as for ordi‐\nnary arguments. In the first form, the argument is mandatory, and in\nthe second form it is optional.\n\nThis group may be repeated for options which take multiple arguments.\nIn other words, :message1:action1:message2:action2 specifies that the\noption takes two arguments.\n\n:*pattern:message:action\n:*pattern::message:action\n:*pattern:::message:action\nThis describes multiple arguments. Only the last optarg for an option\ntaking multiple arguments may be given in this form. If the pattern is\nempty (i.e. :*:), all the remaining words on the line are to be com‐\npleted as described by the action; otherwise, all the words up to and\nincluding a word matching the pattern are to be completed using the ac‐\ntion.\n\nMultiple colons are treated as for the `*:...' forms for ordinary argu‐\nments: when the message is preceded by two colons, the words special\narray and the CURRENT special parameter are modified during the execu‐\ntion or evaluation of the action to refer only to the words after the\noption. When preceded by three colons, they are modified to refer only\nto the words covered by this description.\n\nAny literal colon in an optname, message, or action must be preceded by a backslash,\n`\\:'.\n\nEach of the forms above may be preceded by a list in parentheses of option names and\nargument numbers. If the given option is on the command line, the options and argu‐\nments indicated in parentheses will not be offered. For example, `(-two -three\n1)-one:...' completes the option `-one'; if this appears on the command line, the op‐\ntions -two and -three and the first ordinary argument will not be completed after it.\n`(-foo):...' specifies an ordinary argument completion; -foo will not be completed if\nthat argument is already present.\n\nOther items may appear in the list of excluded options to indicate various other items\nthat should not be applied when the current specification is matched: a single star\n(*) for the rest arguments (i.e. a specification of the form `*:...'); a colon (:) for\nall normal (non-option-) arguments; and a hyphen (-) for all options. For example, if\n`(*)' appears before an option and the option appears on the command line, the list of\nremaining arguments (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 forms above\nwith `!'; then the form will no longer be completed, although if the option or argu‐\nment appears on the command line they will be skipped as normal. The main use for\nthis is when the arguments are given by an array, and arguments is called repeatedly\nfor more specific contexts: on the first call `arguments $globaloptions' is used,\nand on subsequent calls `arguments !$^globaloptions'.\n\nspecs: actions\n\n\nIn each of the forms above the action determines how completions should be generated.\nExcept for the `->string' form below, the action will be executed by calling the\nalllabels function to process all tag labels. No special handling of tags is needed\nunless a function call introduces a new one.\n\nThe functions called to execute actions will be called with the elements of the array\nnamed by the `-O name' option as arguments. This can be used, for example, to pass\nthe same set of options for the compadd builtin to all actions.\n\nThe forms for action are as follows.\n\n(single unquoted space)\nThis is useful where an argument is required but it is not possible or desir‐\nable to generate matches for it. The message will be displayed but no comple‐\ntions listed. Note that even in this case the colon at the end of the message\nis needed; it may only be omitted when neither a message nor an action is\ngiven.\n\n(item1 item2 ...)\nOne of a list of possible matches, for example:\n\n:foo:(foo bar baz)\n\n((item1\\:desc1 ...))\nSimilar to the above, but with descriptions for each possible match. Note the\nbackslash before the colon. For example,\n\n:foo:((a\\:bar b\\:baz))\n\nThe matches will be listed together with their descriptions if the description\nstyle is set with the values tag in the context.\n\n->string\nIn this form, arguments processes the arguments and options and then returns\ncontrol to the calling function with parameters set to indicate the state of\nprocessing; the calling function then makes its own arrangements for generating\ncompletions. For example, functions that implement a state machine can use\nthis type of action.\n\nWhere arguments encounters action in the `->string' format, it will strip all\nleading and trailing whitespace from string and set the array state to the set\nof all strings for which an action is to be performed. The elements of the ar‐\nray statedescr are assigned the corresponding message field from each optarg\ncontaining such an action.\n\nBy default and in common with all other well behaved completion functions, ar‐\nguments returns status zero if it was able to add matches and non-zero other‐\nwise. However, if the -R option is given, arguments will instead return a sta‐\ntus of 300 to indicate that $state is to be handled.\n\nIn addition to $state and $statedescr, arguments also sets the global parame‐\nters `context', `line' and `optargs' as described below, and does not reset\nany changes made to the special parameters such as PREFIX and words. This\ngives the calling function the choice of resetting these parameters or propa‐\ngating changes in them.\n\nA function calling arguments with at least one action containing a `->string'\nmust therefore declare appropriate local parameters:\n\nlocal context state statedescr line\ntypeset -A optargs\n\nto prevent arguments from altering the global environment.\n\n{eval-string}\nA string in braces is evaluated as shell code to generate matches. If the\neval-string itself does not begin with an opening parenthesis or brace it is\nsplit into separate words before execution.\n\n= action\nIf the action starts with `= ' (an equals sign followed by a space), arguments\nwill insert the contents of the argument field of the current context as the\nnew first element in the words special array and increment the value of the\nCURRENT special parameter. This has the effect of inserting a dummy word onto\nthe completion 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 the\ncommand line on which the action is to operate (the two- and three-colon forms\nabove). One particular use is when an action itself causes arguments on a re‐\nstricted range; it is necessary to use this trick to insert an appropriate com‐\nmand name into the range for the second call to arguments to be able to parse\nthe line.\n\nword...\nword...\nThis covers all forms other than those above. If the action starts with a\nspace, the remaining list of words will be invoked unchanged.\n\nOtherwise it will be invoked with some extra strings placed after the first\nword; these are to be passed down as options to the compadd builtin. They en‐\nsure that the state specified by arguments, in particular the descriptions of\noptions and arguments, is correctly passed to the completion command. These\nadditional arguments are taken from the array parameter `expl'; this will be\nset up before executing the action and hence may be referred to inside it, typ‐\nically in an expansion of the form `$expl[@]' which preserves empty elements of\nthe array.\n\nDuring the performance of the action the array `line' will be set to the normal argu‐\nments from the command line, i.e. the words from the command line after the command\nname excluding all options and their arguments. Options are stored in the associative\narray `optargs' with option names as keys and their arguments as the values. By de‐\nfault, all colons and backslashes in the value are escaped with backslashes, and if an\noption has multiple arguments (for example, when using an optspec of the form `*opt‐\nspec'), they are joined with (unescaped) colons. However, if the -0 option was\npassed, no backslash escaping is performed, and multiple values are joined with NUL\nbytes. For example, after `zsh -o foo:foo -o bar:bar -o ', the contents of\n`optargs' would be\n\ntypeset -A optargs=( [-o]='foo\\:foo:bar\\:bar:' )\n\nby default, and\n\ntypeset -A optargs=( [-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 to perform an\naction of the form `->string'. It is set to an array of elements corresponding to the\nelements of $state. Each element is a suitable name for the argument field of the\ncontext: either a string of the form `option-opt-n' for the n'th argument of the op‐\ntion -opt, or a string of the form `argument-n' for the n'th argument. For `rest' ar‐\nguments, that is those in the list at the end not handled by position, n is the string\n`rest'. For example, when completing the argument of the -o option, the name is `op‐\ntion-o-1', while for the second normal (non-option-) argument it is `argument-2'.\n\nFurthermore, during the evaluation of the action the context name in the curcontext\nparameter is altered to append the same string that is stored in the context parame‐\nter.\n\nThe option -C tells arguments to modify the curcontext parameter for an action of the\nform `->state'. This is the standard parameter used to keep track of the current con‐\ntext. Here it (and not the context array) should be made local to the calling func‐\ntion to avoid passing back the modified value and should be initialised to the current\nvalue at the start of the function:\n\nlocal curcontext=\"$curcontext\"\n\nThis is useful where it is not possible for multiple states to be valid together.\n\nGrouping Options\n\nOptions can be grouped to simplify exclusion lists. A group is introduced with `+'\nfollowed by a name for the group in the subsequent word. Whole groups can then be ref‐\nerenced in an exclusion list or a group name can be used to disambiguate between two\nforms of the same option. For example:\n\narguments \\\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 `(name)' then only one value from that\ngroup will ever be completed; more formally, all specifications are mutually exclusive\nto all other specifications in that group. This is useful for defining options that\nare aliases for each other. For example:\n\narguments \\\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 associative\narray `optargs' with 'group-option' as a key. In the example above, a key `opera‐\ntion--c' is used if the option `-c' is present on the command line.\n\nSpecifying Multiple Sets of Arguments\n\nIt is possible to specify multiple sets of options and arguments with the sets sepa‐\nrated by single hyphens. This differs from groups in that sets are considered to be\nmutually exclusive of each other.\n\nSpecifications before the first set and from any group are common to all sets. For ex‐\nample:\n\narguments \\\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 `-c', the `-d' op‐\ntion and the argument will not be considered possible completions. When it contains\n`-d' or an argument, the option `-c' will not be considered. However, after `-a' both\nsets will still be considered valid.\n\nAs for groups, the name of a set may appear in exclusion lists, either alone or pre‐\nceding a normal option or argument specification.\n\nThe completion code has to parse the command line separately for each set. This can be\nslow so sets should only be used when necessary. A useful alternative is often an op‐\ntion specification with rest-arguments (as in `-foo:*:...'); here the option -foo\nswallows up all remaining arguments as described by the optarg definitions.\n\nDeriving spec forms from the help output\n\nThe option `--' allows arguments to work out the names of long options that support\nthe `--help' option which is standard in many GNU commands. The command word is\ncalled with the argument `--help' and the output examined for option names. Clearly,\nit can be dangerous to pass this to commands which may not support this option as the\nbehaviour of the command is unspecified.\n\nIn addition to options, `arguments --' will try to deduce the types of arguments\navailable for options when the form `--opt=val' is valid. It is also possible to pro‐\nvide hints by examining the help text of the command and adding helpspec of the form\n`pattern:message:action'; note that other arguments spec forms are not used. The\npattern is matched against the help text for an option, and if it matches the message\nand action are used as for other argument specifiers. The special case of `*:' means\nboth message and action are empty, which has the effect of causing options having no\ndescription in the help output to be ordered in listings ahead of options that have a\ndescription.\n\nFor example:\n\narguments -- '*\\*: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 options whose description\nends in a star; file names will be completed for options that contain the substring\n`=FILE' in the description; and directories will be completed for options whose de‐\nscription contains `=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 of these\npatterns. 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 after `--di‐\nrectory', though not after `-C'.\n\nNote also that arguments tries to find out automatically if the argument for an op‐\ntion is optional. This can be specified explicitly by doubling the colon before the\nmessage.\n\nIf the pattern ends in `(-)', this will be removed from the pattern and the action\nwill be used only directly after the `=', not in the next word. This is the behaviour\nof a normal specification defined with the form `=-'.\n\nBy default, the command (with the option `--help') is run after resetting all the lo‐\ncale categories (except for LCCTYPE) to `C'. If the localized help output is known\nto work, the option `-l' can be specified after the `arguments --' so that the com‐\nmand is run in the current locale.\n\nThe `arguments --' can be followed by the option `-i patterns' to give patterns for\noptions which are not to be completed. The patterns can be given as the name of an\narray parameter or as a literal list in parentheses. For example,\n\narguments -- -i \\\n\"(--(en|dis)able-FEATURE*)\"\n\nwill cause completion to ignore the options `--enable-FEATURE' and `--disable-FEATURE'\n(this example is useful with GNU configure).\n\nThe `arguments --' form can also be followed by the option `-s pair' to describe op‐\ntion aliases. The pair consists of a list of alternating patterns and corresponding\nreplacements, enclosed in parens and quoted so that it forms a single argument word in\nthe arguments call.\n\nFor example, some configure-script help output describes options only as `--en‐\nable-foo', but the script also accepts the negated form `--disable-foo'. To allow\ncompletion of the second form:\n\narguments -- -s \"((#s)--enable- --disable-)\"\n\nMiscellaneous notes\n\nFinally, note that arguments generally expects to be the primary function handling\nany completion for which it is used. It may have side effects which change the treat‐\nment of any matches added by other functions called after it. To combine arguments\nwith other functions, those functions should be called either before arguments, as an\naction within a spec, or in handlers for `->state' actions.\n\nHere is a more general example of the use of arguments:\n\narguments '-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 `-copy'. The first takes one argu‐\nment described as `left border' for which no completion will be offered because of the\nempty action. Its argument may come directly after the `-l' or it may be given as the\nnext word on the line.\n\nThe `-format' option takes one argument in the next word, described as `paper size'\nfor which only the strings `letter' and `A4' will be completed.\n\nThe `-copy' option may appear more than once on the command line and takes two argu‐\nments. The first is mandatory and will be completed as a filename. The second is op‐\ntional (because of the second colon before the description `resolution') and will be\ncompleted from the strings `300' and `600'.\n\nThe last two descriptions say what should be completed as arguments. The first de‐\nscribes the first argument as a `postscript file' and makes files ending in `ps' or\n`eps' be completed. The last description gives all other arguments the description\n`page number' but does not offer completions.\n\ncacheinvalid cacheidentifier\nThis function returns status zero if the completions cache corresponding to the given\ncache identifier needs rebuilding. It determines this by looking up the cache-policy\nstyle for the current context. This should provide a function name which is run with\nthe full path to the relevant cache file as the only argument.\n\nExample:\n\nexamplecachingpolicy () {\n# rebuild if cache is more than a week old\nlocal -a oldp\noldp=( \"$1\"(Nm+7) )\n(( $#oldp ))\n}\n\ncallfunction return name [ arg ... ]\nIf a function name exists, it is called with the arguments args. The return argument\ngives the name of a parameter in which the return status from the function name should\nbe stored; if return is empty or a single hyphen it is ignored.\n\nThe return status of callfunction itself is zero if the function name exists and was\ncalled and non-zero otherwise.\n\ncallprogram [ -l ] [ -p ] tag string ...\nThis function provides a mechanism for the user to override the use of an external\ncommand. It looks up the command style with the supplied tag. If the style is set,\nits value is used as the command to execute. The strings from the call to callpro‐\ngram, or from the style if set, are concatenated with spaces between them and the re‐\nsulting string 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 categories (ex‐\ncept for LCCTYPE) are reset to `C' by calling the utility function complocale (see\nbelow). If the option `-l' is given, the command is run with the current locale.\n\nIf the option `-p' is supplied it indicates that the command output is influenced by\nthe permissions it is run with. If the gain-privileges style is set to true,\ncallprogram will make use of commands such as sudo, if present on the command-line,\nto match the permissions to whatever the final command is likely to run under. When\nlooking up the gain-privileges and command styles, the command component of the zstyle\ncontext will end with a slash (`/') followed by the command that would be used to gain\nprivileges.\n\ncombination [ -s pattern ] tag style spec ... field opts ...\nThis function is used to complete combinations of values, for example pairs of host‐\nnames and usernames. The style argument gives the style which defines the pairs; it\nis looked up in a context with the tag specified.\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 spec of the form\n`field=pattern' is given. For example, if the command line so far specifies a user\n`pws', the argument `users=pws' should appear.\n\nThe next argument with no equals sign is taken as the name of the field for which com‐\npletions should be generated (presumably not one of the fields for which the value is\nknown).\n\nThe matches generated will be taken from the value of the style. These should contain\nthe possible values for the combinations in the appropriate order (users, hosts, ports\nin the example above). The values for the different fields are separated by colons.\nThis can be altered with the option -s to combination which specifies a pattern.\nTypically this is a character class, as for example `-s \"[:@]\"' in the case of the\nusers-hosts style. Each `field=pattern' specification restricts the completions\nwhich apply to elements of the style with appropriately matching fields.\n\nIf no style with the given name is defined for the given tag, or if none of the\nstrings in style's value match, but a function name of the required field preceded by\nan underscore is defined, that function will be called to generate the matches. For\nexample, if there is no `users-hosts-ports' or no matching hostname when a host is re‐\nquired, the function `hosts' will automatically be called.\n\nIf the same name is used for more than one field, in both the `field=pattern' and the\nargument that gives the name of the field to be completed, the number of the field\n(starting with one) may be given after the fieldname, separated from it by a colon.\n\nAll arguments after the required field name are passed to compadd when generating\nmatches from the style value, or to the functions for the fields if they are called.\n\ncommandnames [ -e | - ]\nThis function completes words that are valid at command position: names of aliases,\nbuiltins, hashed commands, functions, and so on. With the -e flag, only hashed com‐\nmands are completed. The - flag is ignored.\n" }, { "name": "_comp_locale", "content": "This function resets all the locale categories other than LCCTYPE to `C' so that the\noutput from external commands can be easily analyzed by the completion system.\nLCCTYPE retains the current value (taking LCALL and LANG into account), ensuring\nthat non-ASCII characters in file names are still handled properly.\n\nThis function should normally be run only in a subshell, because the new locale is ex‐\nported to the environment. Typical usage would be `$(complocale; command ...)'.\n\ncompleters [ -p ]\nThis function completes names of completers.\n\n-p Include the leading underscore (`') in the matches.\n" }, { "name": "_default", "content": "This function corresponds to the -default- special context which is applied where no\ncompletion is defined. It is useful to call it under certain error conditions such as\ncompletion after an unrecognised subcommand. This applies the concept of graceful\ndegradation to the completion system, allowing it to fallback on basic completion of\ncommonly useful things like filenames.\n\n\ndescribe [-12JVx] [ -oO | -t tag ] descr name1 [ name2 ] [ opt ... ]\n[ -- name1 [ name2 ] [ opt ... ] ... ]\nThis function associates completions with descriptions. Multiple groups separated by\n-- can be supplied, potentially with different completion options opts.\n\nThe descr is taken as a string to display above the matches if the format style for\nthe descriptions tag is set. This is followed by one or two names of arrays followed\nby options to pass to compadd. The array name1 contains the possible completions with\ntheir descriptions in the form `completion:description'. Any literal colons in com‐\npletion must be quoted with a backslash. If a name2 is given, it should have the same\nnumber of elements as name1; in this case the corresponding elements are added as pos‐\nsible completions instead of the completion strings from name1. The completion list\nwill retain the descriptions from name1. Finally, a set of completion options can ap‐\npear.\n\nIf the option `-o' appears before the first argument, the matches added will be\ntreated as names of command options (N.B. not shell options), typically following a\n`-', `--' or `+' on the command line. In this case describe uses the prefix-hidden,\nprefix-needed and verbose styles to find out if the strings should be added as comple‐\ntions and if the descriptions should be shown. Without the `-o' option, only the ver‐\nbose style is used to decide how descriptions are shown. If `-O' is used instead of\n`-o', command options are completed as above but describe will not handle the pre‐\nfix-needed style.\n\nWith the -t option a tag can be specified. The default is `values' or, if the -o op‐\ntion is given, `options'.\n\nThe options -1, -2, -J, -V, -x are passed to nextlabel.\n\nIf selected by the list-grouped style, strings with the same description will appear\ntogether in the list.\n\ndescribe uses the alllabels function to generate the matches, so it does not need\nto appear inside a loop over tag labels.\n\ndescription [ -x ] [ -12VJ ] tag name descr [ spec ... ]\nThis function is not to be confused with the previous one; it is used as a helper\nfunction for creating options to compadd. It is buried inside many of the higher\nlevel completion functions and so often does not need to be called directly.\n\nThe styles listed below are tested in the current context using the given tag. The\nresulting options for compadd are put into the array named name (this is traditionally\n`expl', but this convention is not enforced). The description for the corresponding\nset of matches is passed to the function in descr.\n\nThe styles tested are: format, hidden, matcher, ignore-line, ignored-patterns,\ngroup-name and sort. The format style is first tested for the given tag and then for\nthe descriptions tag if no value was found, while the remainder are only tested for\nthe tag given as the first argument. The function also calls setup which tests some\nmore styles.\n\nThe string returned by the format style (if any) will be modified so that the sequence\n`%d' is replaced by the descr given as the third argument without any leading or\ntrailing white space. If, after removing the white space, the descr is the empty\nstring, the format style 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, the additional specs should\nbe of the form `char:str'. These supply escape sequence replacements for the format\nstyle: every appearance of `%char' will be replaced by string. If no additional specs\nare given but the description in descr conforms to a common form then further escape\nsequences are set for elements of that description. These elements correspond to a\ndefault value (`%o'), the units (`%m') range of acceptable values (`%r') and the re‐\nmaining initial part of the description (`%h'). The form the description takes con‐\nsists of specifying the units and range in parentheses and the default value in square\nbrackets, for example:\n\ndescription times expl 'timeout (seconds) (0-60) [20]'\n\nIt is possible to use zformat conditional expressions when styling these elements. So,\nfor example, to add `default:' as a tag but only when there is a default value to\nshow, the format style might include `%(o.default: %o.)'.\n\nIf the -x option is given, the description will be passed to compadd using the -x op‐\ntion instead of the default -X. This means that the description will be displayed\neven if there are no corresponding matches.\n\nThe options placed in the array name take account of the group-name style, so matches\nare placed in a separate group where necessary. The group normally has its elements\nsorted (by passing the option -J to compadd), but if an option starting with `-V',\n`-J', `-1', or `-2' is passed to description, that option will be included in the ar‐\nray. Hence it is possible for the completion group to be unsorted by giving the op‐\ntion `-V', `-1V', or `-2V'.\n\nIn most cases, the function will be used like this:\n\nlocal expl\ndescription files expl file\ncompadd \"$expl[@]\" - \"$files[@]\"\n\nNote the use of the parameter expl, the hyphen, and the list of matches. Almost all\ncalls to compadd within the completion system use a similar format; this ensures that\nuser-specified styles are correctly passed down to the builtins which implement the\ninternals of completion.\n\ndirlist [ -s sep ] [ -S ]\nComplete a list of directory names separated by colons (the same format as $PATH).\n\n-s sep Use sep as separator between items. sep defaults to a colon (`:').\n\n-S Add sep instead of slash (`/') as an autoremoveable suffix.\n\ndispatch context string ...\nThis sets the current context to context and looks for completion functions to handle\nthis context by hunting through the list of command names or special contexts (as de‐\nscribed above for compdef) given as strings. The first completion function to be de‐\nfined for one of the contexts in the list is used to generate matches. Typically, the\nlast string is -default- to cause the function for default completion to be used as a\nfallback.\n\nThe function sets the parameter $service to the string being tried, and sets the con‐\ntext/command field (the fourth) of the $curcontext parameter to the context given as\nthe first argument.\n\nemailaddresses [ -c ] [ -n plugin ]\nComplete email addresses. Addresses are provided by plugins.\n\n-c Complete bare localhost@domain.tld addresses, without a name part or a comment.\nWithout this option, RFC822 `Firstname Lastname
' strings are com‐\npleted.\n\n-n plugin\nComplete aliases from plugin.\n\nThe following plugins are available by default: email-ldap (see the filter style),\nemail-local (completes user@hostname Unix addresses), email-mail (completes aliases\nfrom ~/.mailrc), email-mush, email-mutt, and email-pine.\n\nAddresses from the email-foo plugin are added under the tag `email-foo'.\n\nWriting plugins\n\nPlugins are written as separate functions with names starting with `email-'. They\nare invoked with the -c option and compadd options. They should either do their own\ncompletion or set the $reply array to a list of `alias:address' elements and return\n300. New plugins will be picked up and run automatically.\n\nfiles The function files is a wrapper around pathfiles. It supports all of the same func‐\ntionality, with some enhancements -- notably, it respects the list-dirs-first style,\nand it allows users to override the behaviour of the -g and -/ options with the\nfile-patterns style. files should therefore be preferred over pathfiles in most\ncases.\n\nThis function accepts the full set of options allowed by pathfiles, described below.\n" }, { "name": "_gnu_generic", "content": "This function is a simple wrapper around the arguments function described above. It\ncan be used to determine automatically the long options understood by commands that\nproduce a list when passed the option `--help'. It is intended to be used as a\ntop-level completion function in its own right. For example, to enable option comple‐\ntion for the commands foo and bar, use\n\ncompdef gnugeneric foo bar\n\nafter the call to compinit.\n\nThe completion system as supplied is conservative in its use of this function, since\nit is important to be sure the command understands the option `--help'.\n\nguard [ options ] pattern descr\nThis function displays descr if pattern matches the string to be completed. It is in‐\ntended to be used in the action for the specifications passed to arguments and simi‐\nlar functions.\n\nThe return status is zero if the message was displayed and the word to complete is not\nempty, and non-zero otherwise.\n\nThe pattern may be preceded by any of the options understood by compadd that are\npassed down from description, namely -M, -J, -V, -1, -2, -n, -F and -X. All of these\noptions will be ignored. This fits in conveniently with the argument-passing conven‐\ntions of actions for arguments.\n\nAs an example, consider a command taking the options -n and -none, where -n must be\nfollowed by a numeric value in the same word. By using:\n\narguments '-n-: :guard \"[0-9]#\" \"numeric value\"' '-none'\n\narguments can be made to both display the message `numeric value' and complete op‐\ntions after `-n'. If the `-n' is already followed by one or more digits (the\npattern passed to guard) only the message will be displayed; if the `-n' is followed\nby another character, only options are completed.\n\nmessage [ -r12 ] [ -VJ group ] descr\nmessage -e [ tag ] descr\nThe descr is used in the same way as the third argument to the description function,\nexcept that the resulting string will always be shown whether or not matches were gen‐\nerated. This is useful for displaying a help message in places where no completions\ncan be generated.\n\nThe format style is examined with the messages tag to find a message; the usual tag,\ndescriptions, is used only if the style is not set with the former.\n\nIf the -r option is given, no style is used; the descr is taken literally as the\nstring to display. This is most useful when the descr comes from a pre-processed ar‐\ngument list which already contains an expanded description. Note that this option\ndoes not disable the `%'-sequence parsing done by compadd.\n\nThe -12VJ options and the group are passed to compadd and hence determine the group\nthe message string is added to.\n\nThe second -e form gives a description for completions with the tag tag to be shown\neven if there are no matches for that tag. This form is called by arguments in the\nevent that there is no action for an option specification. The tag can be omitted and\nif so the tag is taken from the parameter $curtag; this is maintained by the comple‐\ntion system and so is usually correct. Note that if there are no matches at the time\nthis function is called, compstate[insert] is cleared, so additional matches generated\nlater are not inserted on the command line.\n\nmultiparts [ -i ] sep array\nThe argument sep is a separator character. The array may be either the name of an ar‐\nray parameter or a literal array in the form `(foo bar)', a parenthesised list of\nwords separated by whitespace. The possible completions are the strings from the ar‐\nray. However, each chunk delimited by sep will be completed separately. For example,\nthe tar function uses `multiparts / patharray' to complete partial file paths from\nthe given array of complete file paths.\n\nThe -i option causes multiparts to insert a unique match even if that requires mul‐\ntiple separators to be inserted. This is not usually the expected behaviour with\nfilenames, but certain other types of completion, for example those with a fixed set\nof possibilities, may be more suited to this form.\n\nLike other utility functions, this function accepts the `-V', `-J', `-1', `-2', `-n',\n`-f', `-X', `-M', `-P', `-S', `-r', `-R', and `-q' options and passes them to the com‐\npadd builtin.\n\nnextlabel [ -x ] [ -12VJ ] tag name descr [ option ... ]\nThis function is used to implement the loop over different tag labels for a particular\ntag as described above for the tag-order style. On each call it checks to see if\nthere are any more tag labels; if there is it returns status zero, otherwise non-zero.\nAs this function requires a current tag to be set, it must always follow a call to\ntags or requested.\n\nThe -x12VJ options and the first three arguments are passed to the description func‐\ntion. Where appropriate the tag will be replaced by a tag label in this call. Any\ndescription given in the tag-order style is preferred to the descr passed to nextla‐\nbel.\n\nThe options given after the descr are set in the parameter given by name, and hence\nare to be passed to 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 requested deter‐\nmines if tag foo is required at all; the loop over nextlabel handles any labels de‐\nfined for the tag in the tag-order style.\n\nlocal expl ret=1\n...\nif requested foo; then\n...\nwhile nextlabel foo expl '...'; do\ncompadd \"$expl[@]\" ... && ret=0\ndone\n...\nfi\nreturn ret\n\nnormal [ -P | -p precommand ]\nThis is the standard function called to handle completion outside any special -con‐\ntext-. It is called both to complete the command word and also the arguments for a\ncommand. In the second case, normal looks for a special completion for that command,\nand if there is none it uses the completion for the -default- context.\n\nA second use is to reexamine the command line specified by the $words array and the\n$CURRENT parameter after those have been modified. For example, the function precom‐\nmand, which completes after precommand specifiers such as nohup, removes the first\nword from the words array, decrements the CURRENT parameter, then calls `normal -p\n$service'. The effect is that `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 a com‐\nmand line which allows internal commands (e.g. builtins and functions) regard‐\nless of prior precommands (e.g. `zsh -c').\n\n-p precommand\nAppend precommand to the list of precommands. This option should be used in\nnearly all cases in which -P is not applicable.\n\nIf the command name matches one of the patterns given by one of the options -p or -P\nto compdef, the corresponding completion function is called and then the parameter\ncompskip is checked. If it is set completion is terminated at that point even if no\nmatches have been found. This is the same effect as in the -first- context.\n\nnumbers [ option ... ] [ description ] [ suffix ... ]\nThis can be used where a number is followed by a suffix to indicate the units. The\nunit suffixes are completed and can also be included in the description used when com‐\npletion is invoked for the preceding number.\n\nIn addition to common compadd options, numbers accepts the following options:\n\n-t tag Specify 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 Specify the lowest possible value for the number.\n\n-m max Specify the highest possible value for the number.\n\n-d default\nSpecify the default value.\n\n-N Allow negative numbers. This is implied if the range includes a negative.\n\n-f Allow decimal numbers.\n\nWhere a particular suffix represents the default units for a number, it should be pre‐\nfixed with a colon. Additionally, suffixes can be followed by a colon and a descrip‐\ntion. So for example, the following allows the age of something to be specified, ei‐\nther in seconds or with an optional suffix with a longer unit of time:\n\nnumbers -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 when com‐\npleted. To facilitate this, the order in which they are given is preserved.\n\nWhen the format style is looked up with the descriptions tag or the tag specified with\n-t, the list of suffixes is available as a `%x' escape sequence. This is in addition\nto the usual sequences documented under the format style. The form this list takes can\nalso be configured. To this end, the format style is first looked up with the tag\nunit-suffixes. The retrieved format is applied to each suffix in turn and the results\nare then concatenated to form the completed list. For the unit-suffixes format, `%x'\nexpands to the individual suffix and `%X' to its description. %d' indicates a default\nsuffix and can be used in a condition. The index and reverse index are set in `%i' and\n`%r' respectively and are useful for text included only with the first and last suf‐\nfixes in the list. So for example, the following joins the suffixes together as a\ncomma-separated list:\n\nzstyle ':completion:*:unit-suffixes' format '%x%(r::,)'\n" }, { "name": "_options", "content": "This can be used to complete the names of shell options. It provides a matcher speci‐\nfication that ignores a leading `no', ignores underscores and allows upper-case let‐\nters to match their lower-case counterparts (for example, `glob', `noglob', `NOGLOB'\nare all completed). Any arguments are propagated to the compadd builtin.\n\noptionsset and optionsunset\nThese functions complete only set or unset options, with the same matching specifica‐\ntion used in the options function.\n\nNote that you need to uncomment a few lines in the maincomplete function for these\nfunctions to work properly. The lines in question are used to store the option set‐\ntings in effect before the completion widget locally sets the options it needs. Hence\nthese functions are not generally used by the completion system.\n" }, { "name": "_parameters", "content": "This is used to complete the names of shell parameters.\n\nThe option `-g pattern' limits the completion to parameters whose type matches the\npattern. The type of a parameter is that shown by `print ${(t)param}', hence judi‐\ncious use of `*' in pattern is probably necessary.\n\nAll other arguments are passed to the compadd builtin.\n" }, { "name": "_path_files", "content": "This function is used throughout the completion system to complete filenames. It al‐\nlows completion of partial paths. For example, the string `/u/i/s/sig' may be com‐\npleted to `/usr/include/sys/signal.h'.\n\nThe options accepted by both pathfiles and files are:\n\n-f Complete all filenames. This is the default.\n\n-/ Specifies 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 command\nline to generate the filenames but that should not be inserted as completions\nnor shown in completion listings. Here, paths may be the name of an array pa‐\nrameter, a literal list of paths enclosed in parentheses or an absolute path‐\nname.\n\n-F ignored-files\nThis behaves as for the corresponding option to the compadd builtin. It gives\ndirect control over which filenames should be ignored. If the option is not\npresent, the ignored-patterns style is used.\n\nBoth pathfiles and files also accept the following options which are passed to com‐\npadd: `-J', `-V', `-1', `-2', `-n', `-X', `-M', `-P', `-S', `-q', `-r', and `-R'.\n\nFinally, the pathfiles function uses the styles expand, ambiguous, special-dirs,\nlist-suffixes and file-sort described above.\n\n\npickvariant [ -b builtin-label ] [ -c command ] [ -r name ]\nlabel=pattern ... label [ arg ... ]\nThis function is used to resolve situations where a single command name requires more\nthan one type of handling, either because it has more than one variant or because\nthere is a name clash between two different commands.\n\nThe command to run is taken from the first element of the array words unless this is\noverridden by the option -c. This command is run and its output is compared with a\nseries of patterns. Arguments to be passed to the command can be specified at the end\nafter all the other arguments. The patterns to try in order are given by the argu‐\nments label=pattern; if the output of `command arg ...' contains pattern, then label\nis selected as the label for the command variant. If none of the patterns match, the\nfinal command label is selected and status 1 is returned.\n\nIf the `-b builtin-label' is given, the command is tested to see if it is provided as\na shell builtin, possibly autoloaded; if so, the label builtin-label is selected as\nthe label for the variant.\n\nIf the `-r name' is given, the label picked is stored in the parameter named name.\n\nThe results are also cached in the cmdvariant associative array indexed by the name\nof the command run.\n\nregexarguments name spec ...\nThis function generates a completion function name which matches the specifications\nspecs, a set of regular expressions as described below. After running regexargu‐\nments, the function name should be called as a normal completion function. The pat‐\ntern to be matched is given by the contents of the words array up to the current cur‐\nsor position joined together with null characters; no quotation is applied.\n\nThe arguments are grouped as sets of alternatives separated by `|', which are tried\none after the other until one matches. Each alternative consists of a one or more\nspecifications which are tried left to right, with each pattern matched being stripped\nin turn from the command line being tested, until all of the group succeeds or until\none fails; in the latter case, the next alternative is tried. This structure can be\nrepeated to arbitrary depth by using parentheses; matching proceeds from inside to\noutside.\n\nA special procedure is applied if no test succeeds but the remaining command line\nstring contains no null character (implying the remaining word is the one for which\ncompletions are to be generated). The completion target is restricted to the remain‐\ning word and any actions for the corresponding patterns are executed. In this case,\nnothing is stripped from the command line string. The order of evaluation of the ac‐\ntions can be determined by the tag-order style; the various formats supported by al‐\nternative can be used in action. The descr is used for setting up the array parameter\nexpl.\n\nSpecification arguments take one of following forms, in which metacharacters such as\n`(', `)', `#' and `|' should be quoted.\n\n/pattern/ [%lookahead%] [-guard] [:tag:descr:action]\nThis is a single primitive component. The function tests whether the combined\npattern `(#b)((#B)pattern)lookahead*' matches the command line string. If so,\n`guard' is evaluated and its return status is examined to determine if the test\nhas succeeded. The pattern string `[]' is guaranteed never to match. The\nlookahead is not stripped from the command line before the next pattern is ex‐\namined.\n\nThe argument starting with : is used in the same manner as an argument to al‐\nternative.\n\nA component is used as follows: pattern is tested to see if the component al‐\nready exists on the command line. If it does, any following specifications are\nexamined to find something to complete. If a component is reached but no such\npattern exists yet on the command line, the string containing the action is\nused to generate matches to insert at that point.\n\n/pattern/+ [%lookahead%] [-guard] [:tag:descr:action]\nThis is similar to `/pattern/ ...' but the left part of the command line string\n(i.e. the part already matched by previous patterns) is also considered part of\nthe completion target.\n\n/pattern/- [%lookahead%] [-guard] [:tag:descr:action]\nThis is similar to `/pattern/ ...' but the actions of the current and previ‐\nously matched patterns are ignored even if the following `pattern' matches the\nempty string.\n\n( spec )\nParentheses may be used to groups specs; note each parenthesis is a single ar‐\ngument to regexarguments.\n\nspec # This allows any number of repetitions of spec.\n\nspec spec\nThe two specs are to be matched one after the other as described above.\n\nspec | spec\nEither of the two specs can be matched.\n\nThe function regexwords can be used as a helper function to generate matches for a\nset of alternative words possibly with their own arguments as a command line argument.\n\nExamples:\n\nregexarguments tst /$'[^\\0]#\\0'/ \\\n/$'[^\\0]#\\0'/ :'compadd aaa'\n\nThis generates a function tst that completes aaa as its only argument. The tag and\ndescription for the action have been omitted for brevity (this works but is not recom‐\nmended in normal use). The first component matches the command word, which is arbi‐\ntrary; the second matches any argument. As the argument is also arbitrary, any fol‐\nlowing component would not depend on aaa being present.\n\nregexarguments tst /$'[^\\0]#\\0'/ \\\n/$'aaa\\0'/ :'compadd aaa'\n\nThis is a more typical use; it is similar, but any following patterns would only match\nif aaa was present as the first argument.\n\nregexarguments 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 completed. Odd ar‐\nguments are completed as aaa and even arguments as bbb. Completion fails unless the\nset of aaa and bbb arguments before the current one is matched correctly.\n\nregexarguments 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 any argument. In this\ncase regexwords could be used to generate a suitable expression for the arguments.\n\nregexwords tag description spec ...\nThis function can be used to generate arguments for the regexarguments command which\nmay be inserted at any point where a set of rules is expected. The tag and descrip‐\ntion give a standard tag and description pertaining to the current context. Each spec\ncontains two or three arguments separated by a colon: note that there is no leading\ncolon in this case.\n\nEach spec gives one of a set of words that may be completed at this point, together\nwith arguments. It is thus roughly equivalent to the arguments function when used in\nnormal (non-regex) completion.\n\nThe part of the spec before the first colon is the word to be completed. This may\ncontain a *; the entire word, before and after the * is completed, but only the text\nbefore the * is required for the context to be matched, so that further arguments may\nbe completed after the abbreviated form.\n\nThe second part of spec is a description for the word being completed.\n\nThe optional third part of the spec describes how words following the one being com‐\npleted are themselves to be completed. It will be evaluated in order to avoid prob‐\nlems with quoting. This means that typically it contains a reference to an array con‐\ntaining previously generated regex arguments.\n\nThe option -t term specifies a terminator for the word instead of the usual space.\nThis is handled as an auto-removable suffix in the manner of the option -s sep to\nvalues.\n\nThe result of the processing by regexwords is placed in the array reply, which\nshould be made local to the calling function. If the set of words and arguments may\nbe matched repeatedly, a # should be appended to the generated array at that point.\n\nFor example:\n\nlocal -a reply\nregexwords mydb-commands 'mydb commands' \\\n'add:add an entry to mydb:$mydbaddcmds' \\\n'show:show entries in mydb'\nregexarguments mydb \"$reply[@]\"\nmydb \"$@\"\n\nThis shows a completion function for a command mydb which takes two command arguments,\nadd and show. show takes no arguments, while the arguments for add have already been\nprepared in an array mydbaddcmds, quite possibly by a previous call to regexwords.\n\nrequested [ -x ] [ -12VJ ] tag [ name descr [ command [ arg ... ] ]\nThis function is called to decide whether a tag already registered by a call to tags\n(see below) has been requested by the user and hence completion should be performed\nfor it. It returns status zero if the tag is requested and non-zero otherwise. The\nfunction is typically used as part of a loop over different tags as follows:\n\ntags foo bar baz\nwhile tags; do\nif requested foo; then\n... # perform completion for foo\nfi\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 until the end\nof the tags loop. This is so that the user can set the tag-order style to specify a\nset of tags to be completed at the same time.\n\nIf name and descr are given, requested calls the description function with these ar‐\nguments together with the options passed to requested.\n\nIf command is given, the alllabels function will be called immediately with the same\narguments. In simple cases this makes it possible to perform the test for the tag and\nthe matching in one go. For example:\n\nlocal expl ret=1\ntags foo bar baz\nwhile tags; do\nrequested foo expl 'description' \\\ncompadd foobar foobaz && ret=0\n...\n(( ret )) || break\ndone\n\nIf the command is not compadd, it must nevertheless be prepared to handle the same op‐\ntions.\n\nretrievecache cacheidentifier\nThis function retrieves completion information from the file given by cacheidenti‐\nfier, stored in a directory specified by the cache-path style which defaults to\n~/.zcompcache. The return status is zero if retrieval was successful. It will only\nattempt retrieval if the use-cache style is set, so you can call this function without\nworrying about whether the user wanted to use the caching layer.\n\nSee storecache below for more details.\n" }, { "name": "_sep_parts", "content": "This function is passed alternating arrays and separators as arguments. The arrays\nspecify completions for parts of strings to be separated by the separators. The ar‐\nrays may be the names of array parameters or a quoted list of words in parentheses.\nFor example, with the array `hosts=(ftp news)' the call `sepparts '(foo bar)' @\nhosts' will complete the string `f' to `foo' and the string `b@n' to `bar@news'.\n\nThis function accepts the compadd options `-V', `-J', `-1', `-2', `-n', `-X', `-M',\n`-P', `-S', `-r', `-R', and `-q' and passes them on to the compadd builtin used to add\nthe matches.\n\nsequence [ -s sep ] [ -n max ] [ -d ] function [ - ] ...\nThis function is a wrapper to other functions for completing items in a separated\nlist. The same function is used to complete each item in the list. The separator is\nspecified with the -s option. If -s is omitted it will use `,'. Duplicate values are\nnot matched unless -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 to use compadd\ndirectly with sequence, though values may be more appropriate in this situation.\n\nsetup tag [ group ]\nThis function sets up the special parameters used by the completion system appropri‐\nately for the tag given as the first argument. It uses the styles list-colors,\nlist-packed, list-rows-first, last-prompt, accept-exact, menu and force-list.\n\nThe optional group supplies the name of the group in which the matches will be placed.\nIf it is not given, the tag is used as the group name.\n\nThis function is called automatically from description and hence is not normally\ncalled explicitly.\n\nstorecache cacheidentifier param ...\nThis function, together with retrievecache and cacheinvalid, implements a caching\nlayer which can be used in any completion function. Data obtained by costly opera‐\ntions are stored in parameters; this function then dumps the values of those parame‐\nters to a file. The data can then be retrieved quickly from that file via re‐\ntrievecache, even in different instances of the shell.\n\nThe cacheidentifier specifies the file which the data should be dumped to. The file\nis stored in a directory specified by the cache-path style which defaults to ~/.zcomp‐\ncache. The remaining params arguments are the parameters to dump to the file.\n\nThe return status is zero if storage was successful. The function will only attempt\nstorage if the use-cache style is set, so you can call this function without worrying\nabout whether the user wanted to use the caching layer.\n\nThe completion function may avoid calling retrievecache when it already has the com‐\npletion data available as parameters. However, in that case it should call cachein‐\nvalid to check whether the data in the parameters and in the cache are still valid.\n\nSee the perlmodules completion function for a simple example of the usage of the\ncaching layer.\n\ntags [ [ -C name ] tag ... ]\nIf called with arguments, these are taken to be the names of tags valid for comple‐\ntions in the current context. These tags are stored internally and sorted by using\nthe tag-order style.\n\nNext, tags is called repeatedly without arguments from the same completion function.\nThis successively selects the first, second, etc. set of tags requested by the user.\nThe return status is zero if at least one of the tags is requested and non-zero other‐\nwise. To test if a particular 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 argument field (the fifth) of\nthe context in the curcontext parameter during the call to tags; the field is re‐\nstored on exit. This allows tags to use a more specific context without having to\nchange and reset the curcontext parameter (which has the same effect).\n" }, { "name": "_tilde_files", "content": "Like files, but resolve leading tildes according to the rules of filename expansion,\nso the suggested completions don't start with a `~' even if the filename on the com‐\nmand-line does.\n\nvalues [ -O name ] [ -s sep ] [ -S sep ] [ -wC ] desc spec ...\nThis is used to complete arbitrary keywords (values) and their arguments, or lists of\nsuch combinations.\n\nIf the first argument is the option `-O name', it will be used in the same way as by\nthe arguments function. In other words, the elements of the name array will be\npassed to compadd when executing an action.\n\nIf the first argument (or the first argument after `-O name') is `-s', the next argu‐\nment is used as the character that separates multiple values. This character is auto‐\nmatically added after each value in an auto-removable fashion (see below); all values\ncompleted by `values -s' appear in the same word on the command line, unlike comple‐\ntion using arguments. If this option is not present, only a single value will be\ncompleted per word.\n\nNormally, values will only use the current word to determine which values are already\npresent on the command line and hence are not to be completed again. If the -w option\nis given, other arguments are examined as well.\n\nThe first non-option argument, desc, is used as a string to print as a description be‐\nfore listing the values.\n\nAll other arguments describe the possible values and their arguments in the same for‐\nmat used for the description of options by the arguments function (see above). The\nonly differences are that no minus or plus sign is required at the beginning, values\ncan have only one argument, and the forms of action beginning with an equal sign are\nnot supported.\n\nThe character separating a value from its argument can be set using the option -S\n(like -s, followed by the character to use as the separator in the next argument). By\ndefault the equals sign will be used as the separator between values and arguments.\n\nExample:\n\nvalues -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 `two'. The first is described\nas `bar', takes no argument and may appear more than once. The second is described as\n`number', may appear more than once, and takes one mandatory argument described as\n`first count'; no action is specified, so it will not be completed. The `(two)' at\nthe beginning says that if the value `one' is on the line, the value `two' will no\nlonger be considered a possible completion. Finally, the last value (`two') is de‐\nscribed as `another number' and takes an optional argument described as `second count'\nfor which the completions (to appear after an `=') are `1', `2', and `3'. The values\nfunction will complete lists of these values separated by commas.\n\nLike arguments, this function temporarily adds another context name component to the\narguments element (the fifth) of the current context while executing the action. Here\nthis name is just the name of the value for which the argument is completed.\n\nThe style verbose is used to decide if the descriptions for the values (but not those\nfor the arguments) should be printed.\n\nThe associative array valargs is used to report values and their arguments; this\nworks similarly to the optargs associative array used by arguments. Hence the func‐\ntion calling values should declare the local parameters state, statedescr, line,\ncontext and valargs:\n\nlocal context state statedescr line\ntypeset -A valargs\n\nwhen using an action of the form `->string'. With this function the context parameter\nwill be set to the name of the value whose argument is to be completed. Note that for\nvalues, the state and statedescr are scalars rather than arrays. Only a single\nmatching state is returned.\n\nNote also that values normally adds the character used as the separator between val‐\nues as an auto-removable suffix (similar to a `/' after a directory). However, this\nis not possible for a `->string' action as the matches for the argument are generated\nby the calling function. To get the usual behaviour, the calling function can add the\nseparator x as a suffix by passing the options `-qS x' either directly or indirectly\nto compadd.\n\nThe option -C is treated in the same way as it is by arguments. In that case the pa‐\nrameter curcontext should be made local instead of context (as described above).\n\nwanted [ -x ] [ -C name ] [ -12VJ ] tag name descr command [ arg ...]\nIn many contexts, completion can only generate one particular set of matches, usually\ncorresponding to a single tag. However, it is still necessary to decide whether the\nuser requires matches of this type. This function is useful in such a case.\n\nThe arguments to wanted are the same as those to requested, i.e. arguments to be\npassed to description. However, in this case the command is not optional; all the\nprocessing of tags, including the loop over both tags and tag labels and the genera‐\ntion of matches, is carried out automatically by wanted.\n\nHence to offer only one tag and immediately add the corresponding matches with the\ngiven description:\n\nlocal expl\nwanted tag expl 'description' \\\ncompadd -- match1 match2...\n\nSee also the use of wanted in the example function in the subsection `Dynamic named\ndirectories' in zshexpn(1).\n\nNote that, as for requested, the command must be able to accept options to be passed\ndown to compadd.\n\nLike tags this function supports the -C option to give a different name for the argu‐\nment context field. The -x option has the same meaning as for description.\n\nwidgets [ -g pattern ]\nThis function completes names of zle widgets (see the section `Widgets' in zshzle(1)).\nThe pattern, if present, is matched against values of the $widgets special parameter,\ndocumented in the section `The zsh/zleparameter Module' in zshmodules(1).\n" } ] }, "COMPLETION SYSTEM VARIABLES": { "content": "There are some standard variables, initialised by the maincomplete function and then used\nfrom other functions.\n\nThe standard variables are:\n", "subsections": [ { "name": "_comp_caller_options", "content": "The completion system uses setopt to set a number of options. This allows functions to\nbe written without concern for compatibility with every possible combination of user\noptions. However, sometimes completion needs to know what the user's option prefer‐\nences are. These are saved in the compcalleroptions associative array. Option\nnames, spelled in lowercase without underscores, are mapped to one or other of the\nstrings `on' and `off'.\n" }, { "name": "_comp_priv_prefix", "content": "Completion functions such as sudo can set the compprivprefix array to a command\nprefix that may then be used by callprogram to match the privileges when calling\nprograms to generate matches.\n\nTwo more features are offered by the maincomplete function. The arrays compprefuncs and\ncomppostfuncs may contain names of functions that are to be called immediately before or af‐\nter completion has been tried. A function will only be called once unless it explicitly\nreinserts itself into the array.\n" } ] }, "COMPLETION DIRECTORIES": { "content": "In the source distribution, the files are contained in various subdirectories of the Comple‐\ntion directory. They may have been installed in the same structure, or into one single func‐\ntion directory. The following is a description of the files found in the original directory\nstructure. If you wish to alter an installed file, you will need to copy it to some direc‐\ntory which appears earlier in your fpath than the standard directory where it appears.\n\nBase The core functions and special completion widgets automatically bound to keys. You\nwill certainly need most of these, though will probably not need to alter them. Many\nof these are documented above.\n\nZsh Functions for completing arguments of shell builtin commands and utility functions for\nthis. Some of these are also used by functions from the Unix directory.\n\nUnix Functions for completing arguments of external commands and suites of commands. They\nmay need modifying for your system, although in many cases some attempt is made to de‐\ncide which version of a command is present. For example, completion for the mount\ncommand tries to determine the system it is running on, while completion for many\nother utilities try to decide whether the GNU version of the command is in use, and\nhence whether the --help option is supported.\n\nX, AIX, BSD, ...\nCompletion and utility function for commands available only on some systems. These\nare not arranged hierarchically, so, for example, both the Linux and Debian directo‐\nries, as well as the X directory, may be useful on your system.\n\nzsh 5.9 May 14, 2022 ZSHCOMPSYS(1)", "subsections": [] } } } }