70 lines
3.7 KiB
Org Mode
70 lines
3.7 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 two other tutorials on the web, however both of those tutorials only
|
|
explain a small portion of the capabilities of the completion system. This document aims to give more complete and easy to
|
|
understand explanation for creating zsh 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 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
|
|
** Copying completions from another command
|
|
If you want a command, say cmd1, to have the same completions as another, say cmd2, 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. This is a utility function that makes
|
|
it easy to write simple completion functions.
|
|
* Utility functions with example code
|
|
** compadd
|
|
** _gnu_generic
|
|
** _arguments
|
|
** _regex_arguments
|
|
** _regex_words
|
|
** _values
|
|
** _comma_separated
|
|
** _files
|
|
** _net_interfaces
|
|
* 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.
|