* 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]]).

** Defining completion functions
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 on the command line 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.
* 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.