164 lines
11 KiB
Org Mode
164 lines
11 KiB
Org Mode
* 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]].
|
|
*** main utility functions for overall completion
|
|
| _arguments | Used to specify how to complete individual command line options for a command with unix style options. Often used. |
|
|
| _regex_arguments | Creates a function for matching commandline arguments with regular expressions, and then performing actions/completions. |
|
|
| _gnu_generic | Can be used to complete options for commands that understand the `--help' option. |
|
|
| _alternative | Loop over tag labels and perform actions based on matching tag label. |
|
|
| _describe | Used for creating simple completions consisting of single words with descriptions (but no actions). Easier to use than _arguments |
|
|
*** functions for performing complex 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 ETC) | List of possible matches |
|
|
| ((ITEM1\:DESC1 ITEM2\:DESC2 ETC\:BLAH)) | List of possible matches, with descriptions. |
|
|
| ->STRING | Set $state to STRING and continue ($state can be checked in a case statement after the utility function call) |
|
|
| {EVAL-STRING} | Evaluate string as shell code to generate matches. |
|
|
| =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.
|
|
**** Examples
|
|
Here the non-option argument
|
|
#+BEGIN_SRC sh
|
|
_arguments '--help[show help]' '-?[show help]' '1:First arg:_files'
|
|
#+END_SRC
|
|
** Writing completion functions using _arguments
|
|
The _arguments function makes it easy to create completion functions.
|
|
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]].
|
|
|
|
|
|
** Patterns
|
|
** Writing completion functions using _values
|
|
The _values function
|
|
** Functions for completing specific types of objects
|
|
| _files | completes files & directories |
|
|
| _net_interfaces | completes network interface names |
|
|
| _values | for completing comma se |
|
|
* Utility functions with example code
|
|
** compadd
|
|
** _gnu_generic
|
|
** _arguments
|
|
** _regex_arguments
|
|
** _regex_words
|
|
** _values
|
|
** _comma_separated
|
|
** _files
|
|
** _net_interfaces
|
|
* testing & debugging
|
|
To reload a completion function:
|
|
#+BEGIN_SRC sh
|
|
> unfunction _func
|
|
> autoload -U _func
|
|
#+END_SRC
|
|
|
|
* gotchas
|
|
* 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.
|