From 815c0a73ffaa6463908e32577d41139dab2be2d1 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Mon, 24 Mar 2014 22:20:53 +0000 Subject: [PATCH] update --- zsh-completions-howto.org | 72 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 67 insertions(+), 5 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 5147bd3..d24aff3 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -1,9 +1,10 @@ * 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]]. +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 @@ -64,7 +65,30 @@ This is a utility function that makes it easy to write simple completion functio 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 _values which are easier to use. +and _regex_arguments 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]]. +| _alternative | Loop over tag labels and perform actions based on matching tag label. | +| _arguments | Used to specify how to complete individual command line options for a command with unix style options. Often used. | +| _combination | Used to complete combinations of values, for example pairs of hostnames and usernames. | +| _gnu_generic | Wrapper around the _arguments function. Can be used to complete options for commands that understand the `--help' option. | +| _guard | Can be used in the ACTION of specifications for _arguments and similar functions to check the word being completed. | +| _message | Used for displaying help messages in places where no completions can be generated. | +| _multi_parts | Used for completing multiple parts of word separately where each part is seperated by some char, e.g. for completing partial filepaths: /u/i/sy -> /usr/include/sys | +| _options | Can be used to complete the names of shell options. | +| _parameters | Used to complete the names of shell parameters/variables (can restrict to those matching a pattern). | +| _pick_variant | Used for resolving situations where there are several different commands with the same name each having different completion strategies. | +| _regex_arguments | Creates a function for matching commandline arguments with regular expressions, and then performing actions/completions. | +| _regex_words | Can be used to generate arguments for the _regex_arguments command. This should be easier than writing the arguments manually. | +| _sep_parts | Given a list of alternating arrays and separators, use the arrays to complete corresponding parts of string containing separators (see also _multi_parts) | +| _values | Used for completing arbitrary keywords (values) and their arguments, or comma separated lists of such combinations. Can be an ACTION in an _arguments/_regex_arguments spec. | +| _path_files | Used to complete filepaths. Can complete partial paths, e.g. /u/i/sy -> /usr/include/sys | +| _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 | | +| _groups | | ** 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, @@ -76,7 +100,38 @@ This example completes the options --help & -? when trying to complete a hyphen, with the same description in this case. The first non-option argument is completed using the _files function which completes file/directories. +The +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]]. +** 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 + + + +** 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 @@ -87,6 +142,13 @@ completes file/directories. ** _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