* Intro The official documentation for writing zsh completion functions is difficult to understand, and doesn't give many examples. At the time of writing this document I was able to find a few other tutorials on the web, however those tutorials only explain a small portion of the capabilities of the completion system. This document aims to cover areas not explained elsewhere, with examples, so that you can learn how to write more advanced completion functions. I do not go into all the details, but will give enough information and examples to get you up and running. If you need more details you can look it up for yourself in the [[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-System][official documentation]]. Please make any scripts that you create publically available for others (e.g. by forking this repo and making a [[id:64bcd501-b0f0-48c7-b8e2-07af708b95ec][pull request]]). * Getting started ** Telling zsh which function to use for completing a command Completion functions for commands are stored in files with names beginning with an underscore _, and these files should be placed in a directory listed in the $fpath variable. You can add a directory to $fpath by adding a line like this to your ~/.zshrc file: #+BEGIN_SRC sh fpath=(~/newdir $fpath) #+END_SRC The first line of a completion function file can look something like this: #+BEGIN_SRC sh #compdef foobar #+END_SRC This tells zsh that the file contains code for completing the foobar command. This is the format that you will use most often for the first line, but you can also use the same file for completing several different functions if you want. See [[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Autoloaded-files][here]] for more details. You can also use the compdef command directly (e.g. in your ~/.zshrc file) to tell zsh which function to use for completing a command like this: #+BEGIN_SRC sh > compdef _function foobar #+END_SRC or to use the same completions for several commands: #+BEGIN_SRC sh > compdef _function foobar goocar hoodar #+END_SRC or if you want to supply arguments: #+BEGIN_SRC sh > compdef '_function arg1 arg2' foobar #+END_SRC See [[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Functions-4][here]] for more details. ** Completing generic gnu commands Many [[http://www.gnu.org/][gnu]] commands have a standardized way of listing option descriptions (when the --help option is used). For these commands you can use the _gnu_generic function for automatically creating completions, like this: #+BEGIN_SRC sh > compdef _gnu_generic foobar #+END_SRC or to use _gnu_generic with several different commands: #+BEGIN_SRC sh > compdef _gnu_generic foobar goocar hoodar #+END_SRC This line can be placed in your ~/.zshrc file. ** Copying completions from another command If you want a command, say cmd1, to have the same completions as another, say cmd2, which has already had completions defined for it, you can do this: #+BEGIN_SRC sh > compdef cmd1=cmd2 #+END_SRC This can be useful for example if you have created an alias for a command to help you remember it. * Writing your own completion functions A good way to get started is to look at some already defined completion functions. On my linux installation these are found in /usr/share/zsh/functions/Completion/Unix and /usr/share/zsh/functions/Completion/Linux and a few other subdirs. You will notice that the _arguments function is used a lot in these files. This is a utility function that makes it easy to write simple completion functions. The _arguments function is a wrapper around the compadd builtin function. The compadd builtin is the core function used to add completion words to the command line, and control its behaviour. However, most of the time you will not need to use compadd, since there are many utility functions such as _arguments and _describe which are easier to use. ** Utility functions Here is a list of some of the utility functions that may be of use. The full list of utility functions, with full explanations, is available [[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-Functions][here]]. Examples of how to use these functions are given in the next section. *** main utility functions for overall completion | _alternative | Loop over tag labels and perform actions based on matching tag label. | | _arguments | Used to specify how to complete individual options & arguments for a command with unix style options. | | _describe | Used for creating simple completions consisting of single words with descriptions (but no actions). Easier to use than _arguments | | _gnu_generic | Can be used to complete options for commands that understand the `--help' option. | | _regex_arguments | Creates a function for matching commandline arguments with regular expressions, and then performing actions/completions. | *** functions for performing complex individual completions | _values | Used for completing arbitrary keywords (values) and their arguments, or comma separated lists of such combinations. | | _combination | Used to complete combinations of values, for example pairs of hostnames and usernames. | | _multi_parts | Used for completing multiple parts of words separately where each part is separated by some char, e.g. for completing partial filepaths: /u/i/sy -> /usr/include/sys | | _sep_parts | Like _multi_parts but allows different separators at different parts of the completion. | *** functions for completing specific types of objects | _path_files | Used to complete filepaths. Take several options to control behaviour. | | _files | Calls _path_files with all options except -g and -/. These options depend on file-patterns style setting. | | _net_interfaces | Used for completing network interface names | | _users | Used for completing user names | | _groups | Used for completing group names | | _options | Used for completing the names of shell options. | | _parameters | Used for completing the names of shell parameters/variables (can restrict to those matching a pattern). | *** functions for handling cached completions If you have a very large number of completions you can save them in a cache file so that the completions load quickly. | _cache_invalid | indicates whether the completions cache corresponding to a given cache identifier needs rebuilding | | _retrieve_cache | retrieves completion information from a cache file | | _store_cache | store completions corresponding to a given cache identifier in a cache file | *** other functions | _message | Used for displaying help messages in places where no completions can be generated. | | _regex_words | Can be used to generate arguments for the _regex_arguments command. This is easier than writing the arguments manually. | | _guard | Can be used in the ACTION of specifications for _arguments and similar functions to check the word being completed. | *** Actions Many of the utility functions such as _arguments, _regex_arguments, _alternative and _values may include an action at the end of an option/argument specification. This action indicates how to complete the corresponding argument. The actions can take one of the following forms: | ( ) | Argument is required but no matches are generated for it. | | (ITEM1 ITEM2) | List of possible matches | | ((ITEM1\:'DESC1' ITEM2\:'DESC2')) | List of possible matches, with descriptions. Make sure to use different quotes than those around the whole specification. | | ->STRING | Set $state to STRING and continue ($state can be checked in a case statement after the utility function call) | | FUNCTION | Name of a function to call for generating matches or performing some other action, e.g. _files or _message | | {EVAL-STRING} | Evaluate string as shell code to generate matches. This can be used to call a utility function with arguments, e.g. _values or _describe | | =ACTION | Inserts a dummy word into completion command line without changing the point at which completion takes place. | Not all action types are available for all utility functions that use them. For example the ->STRING type is not available in the _regex_arguments or _alternative functions. ** Writing simple completion functions using _describe The _describe function can be used for simple completions where the order and position of the options/arguments is not important. You just need to create an array parameter to hold the options & their descriptions, and then pass the parameter name as an argument to _describe. The following example creates completion candidates -c and -d, with the descriptions. #+BEGIN_SRC sh local -a options options=('-c:description for -c opt' '-d:description for -d opt') _describe 'values' options #+END_SRC You can use several different lists separated by a double hyphen e.g. like this: #+BEGIN_SRC sh local -a options arguments options=('-c:description for -c opt' '-d:description for -d opt') arguments=('e:description for e arg' 'f:description for f arg') _describe 'values' options -- arguments #+END_SRC The _describe function can be used in an ACTION as part of a specification for _alternative, _arguments or _regex_arguments. In this case you will have to put it in braces with its arguments, e.g. 'TAG:DESCRIPTION:{_describe 'values' options}' ** Writing completion functions using _alternative Like _describe, this function performs simple completions where the order and position of options/arguments is not important. However, unlike _describe, you can call execute shell code or call functions to obtain the completion candidates. As arguments it takes a list of specifications each in the form `TAG:DESCRIPTION:ACTION' where TAG is a tag name, DESCRIPTION is a description, and ACTION is one of the action types listed previously (apart from the ->STRING and =ACTION forms). For example: #+BEGIN_SRC sh _alternative 'args:custom args:(a b c)' 'files:filenames:_files' #+END_SRC The first specification adds completion candidates a, b & c, and the second specification calls the _files function for completing filepaths. We could split the specifications over several lines with \ and add descriptions to each of the custom args like this: #+BEGIN_SRC sh _alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"description c"))'\ 'files:filenames:_files' #+END_SRC If we want to call _files with arguments we can put it in braces, like this: #+BEGIN_SRC sh _alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"description c"))'\ 'files:filenames:{_files -/}' #+END_SRC To use parameter expansion to create our list of completions we must use double quotes to quote the specifications, e.g: #+BEGIN_SRC sh _alternative "dirs:user directories:($userdirs)"\ "pids:process IDs:($(ps -A o pid=))" #+END_SRC In this case the first specification adds the words stored in the $userdirs variable, and the second specification evaluates 'ps -A o pid=' to get a list of pids to use as completion candidates. We can use other utility functions such as _values in the ACTION to perform more complex completions, e.g: #+BEGIN_SRC sh _alternative "dirs:user directories:($userdirs)"\ 'opts:comma separated opts:{_values -s , a b c}' #+END_SRC this will complete the items in $userdirs, aswell as a comma separated list containing a, b &/or c. As with _describe, the _alternative function can itself be used in an ACTION as part of a specification for _arguments or _regex_arguments. ** Writing completion functions using _arguments With the _arguments function you can create much more sophisticated completion functions. Like the _alternative function, _arguments takes a list of specification strings as arguments. These specification strings can be for specifying options and any corresponding option arguments (e.g. -f filename), or command arguments. Basic option specifications take the form '-OPT[DESCRIPTION]', e.g. like this: #+BEGIN_SRC sh _arguments '-s[sort output]' '--l[long output]' '-l[long output]' #+END_SRC Arguments for the option can be specified after the option description in this form '-OPT[DESCRIPTION]:MESSAGE:ACTION', where MESSAGE is a message to display and ACTION can be any of the forms mentioned in the ACTIONS section above. For example: #+BEGIN_SRC sh _arguments '-f[input file]:filename:_files' #+END_SRC As arguments it takes special strings specifying the options & arguments to the function being completed, e.g. like this: #+BEGIN_SRC sh _arguments '--help[show help]' '-?[show help]' '1:First arg:_files' #+END_SRC This example completes the options --help & -? when trying to complete a hyphen, which will both be listed together with the same description in this case. The first non-option argument is completed using the _files function which completes file/directories. There are a couple of tutorials on how to use _arguments [[http://www.linux-mag.com/id/1106/][here]] and [[http://wikimatze.de/writing-zsh-completion-for-padrino.html][here]], so I won't cover any more here. Also have a look at the many completion functions listed [[https://github.com/vapniks/zsh-completions/tree/master/src][here]] many of which use _arguments. The full documentation for _arguments is available [[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-Functions][here]]. ** Writing completion functions using _regex_arguments and _regex_words *** Patterns * Testing & debugging To reload a completion function: #+BEGIN_SRC sh > unfunction _func > autoload -U _func #+END_SRC The following functions can be called to obtain useful information. If the default keybindings don't work you can try pressing Alt+x and then enter the command name. | Function | Default keybinding | Description | |-----------------+--------------------+--------------------------------------------------------------------------------------------------------------------------------| | _complete_help | Ctrl+x h | displays information about context names, tags, and completion functions used when completing at the current cursor position | | _complete_help | Alt+2 Ctrl+x h | as above but displays even more information | | _complete_debug | Ctrl+x ? | performs ordinary completion, but captures in a temporary file a trace of the shell commands executed by the completion system | * Gotchas (things to watch out for) Take care to use the correct type of quoting for specifications to _arguments or _regex_arguments: use double quotes if there is a parameter that needs to be expanded in the specification, single quotes otherwise, and make sure to use different quotes around item descriptions. * Putting it all together * Other resources [[http://wikimatze.de/writing-zsh-completion-for-padrino.html][Here]] is a nicely formatted short tutorial showing basic usage of the _arguments function, and [[http://www.linux-mag.com/id/1106/][here]] is a slightly more advanced tutorial using the _arguments function. [[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-System][Here]] is the zshcompsys man page.