xinb
/
zsh-completions
mirror of https://github.com/zsh-users/zsh-completions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

review the howto guide

This commit is contained in:
Oliver Kiddle 2017-10-27 23:13:35 +02:00
parent 831d89694d
commit 29ce259ea5
1 changed files with 38 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
zsh-completions-howto.org
View File

@ -6,7 +6,7 @@ with examples, so that you can learn how to write more advanced completion funct
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 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]]. [[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]]). Please make any scripts that you create publicly available for others (e.g. by forking this repo and making a [[id:64bcd501-b0f0-48c7-b8e2-07af708b95ec][pull request]]).
Also if you have any more information to add or improvements to make to this tutorial, please do. Also if you have any more information to add or improvements to make to this tutorial, please do.
* Getting started * Getting started
** Telling zsh which function to use for completing a command ** Telling zsh which function to use for completing a command
@ -78,7 +78,7 @@ Examples of how to use these functions are given in the next section.
*** main utility functions for overall completion *** main utility functions for overall completion
| _alternative | Can be used to generate completion candidates from other utility functions or shell code. | | _alternative | Can be used to generate completion candidates from other utility functions or shell code. |
| _arguments | Used to specify how to complete individual options & arguments for a command with unix style options. | | _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 | | _describe | Used for creating simple completions consisting of 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. | | _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. | | _regex_arguments | Creates a function for matching commandline arguments with regular expressions, and then performing actions/completions. |
*** functions for performing complex completions of single words *** functions for performing complex completions of single words
@ -86,6 +86,7 @@ Examples of how to use these functions are given in the next section.
| _combination | Used to complete combinations of values, for example pairs of hostnames and usernames. | | _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 | | _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. | | _sep_parts | Like _multi_parts but allows different separators at different parts of the completion. |
| _sequence | Used as a wrapper around another completion function to complete a delimited list of matches generated by that other function.
*** functions for completing specific types of objects *** functions for completing specific types of objects
| _path_files | Used to complete filepaths. Take several options to control behaviour. | | _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. | | _files | Calls _path_files with all options except -g and -/. These options depend on file-patterns style setting. |
@ -119,72 +120,76 @@ _regex_arguments or _alternative functions.
** Writing simple completion functions using _describe ** 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 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 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 parameter name as an argument to _describe. The following example creates completion candidates c and d, with
the descriptions (note this should be put in a file called _cmd in some directory listed in $fpath). the descriptions (note this should be put in a file called _cmd in some directory listed in $fpath).
#+BEGIN_SRC sh #+BEGIN_SRC sh
#compdef cmd #compdef cmd
local -a options local -a subcmds
options=('-c:description for -c opt' '-d:description for -d opt') subcmds=('c:description for c command' 'd:description for d command')
_describe 'values' options _describe 'command' subcmds
#+END_SRC #+END_SRC
You can use several different lists separated by a double hyphen e.g. like this: You can use several different lists separated by a double hyphen as follows but note that this mixes the matches under and single heading and is not intended to be used with different types of completion candidates:
#+BEGIN_SRC sh #+BEGIN_SRC sh
local -a options arguments local -a subcmds topics
options=('-c:description for -c opt' '-d:description for -d opt') subcmds=('c:description for c command' 'd:description for d command')
arguments=('e:description for e arg' 'f:description for f arg') topics=('e:description for e help topic' 'f:description for f help topic')
_describe 'values' options -- arguments _describe 'command' subcmds -- topics
#+END_SRC #+END_SRC
If two candidates have the same description, _describe collects them together on the same rowand ensures that descriptions are aligned in neatedly in columns.
The _describe function can be used in an ACTION as part of a specification for _alternative, _arguments or _regex_arguments. 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}' 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 ** Writing completion functions using _alternative
Like _describe, this function performs simple completions where the order and position of options/arguments is not important. 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. However, unlike _describe, instead of fixed matches further functions may be called to generate the completion candidates. Furthermore, _alternative allows a mix of different types of completion candidates to be mixed.
As arguments it takes a list of specifications each in the form 'TAG:DESCRIPTION:ACTION' where TAG is a tag name, As arguments it takes a list of specifications each in the form 'TAG:DESCRIPTION:ACTION' where TAG is a special tag that identifies the type of completion matches,
DESCRIPTION is a description, and ACTION is one of the action types listed previously (apart from the ->STRING and =ACTION forms). DESCRIPTION is used as a heading to describe the group of completion candidates collectively, and ACTION is one of the action types listed previously (apart from the ->STRING and =ACTION forms).
For example: For example:
#+BEGIN_SRC sh #+BEGIN_SRC sh
_alternative 'args:custom args:(a b c)' 'files:filenames:_files' _alternative 'arguments:custom arg:(a b c)' 'files:filename:_files'
#+END_SRC #+END_SRC
The first specification adds completion candidates a, b & c, and the second specification calls the _files function The first specification adds completion candidates a, b & c, and the second specification calls the _files function for completing filepaths.
for completing filepaths.
We could split the specifications over several lines with \ and add descriptions to each of the custom args like this: We could split the specifications over several lines with \ and add descriptions to each of the custom args like this:
#+BEGIN_SRC sh #+BEGIN_SRC sh
_alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"description c"))'\ _alternative \
'files:filenames:_files' 'args:custom arg:((a\:"description a" b\:"description b" c\:"description c"))' \
'files:filename:_files'
#+END_SRC #+END_SRC
If we want to call _files with arguments we can put it in braces, like this: If we want to pass arguments to _files they can simply be included, like this:
#+BEGIN_SRC sh #+BEGIN_SRC sh
_alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"description c"))'\ _alternative \
'files:filenames:{_files -/}' 'args:custom arg:((a\:"description a" b\:"description b" c\:"description c"))'\
'files:filename:_files -/'
#+END_SRC #+END_SRC
To use parameter expansion to create our list of completions we must use double quotes to quote the specifications, To use parameter expansion to create our list of completions we must use double quotes to quote the specifications,
e.g: e.g:
#+BEGIN_SRC sh #+BEGIN_SRC sh
_alternative "dirs:user directories:($userdirs)"\ _alternative \
"pids:process IDs:($(ps -A o pid=))" "dirs:user directory:($userdirs)" \
"pids:process ID:($(ps -A o pid=))"
#+END_SRC #+END_SRC
In this case the first specification adds the words stored in the $userdirs variable, and the second specification 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. evaluates 'ps -A o pid=' to get a list of pids to use as completion candidates. In practice, we would make used of the existing _pids function for this.
We can use other utility functions such as _values in the ACTION to perform more complex completions, e.g: We can use other utility functions such as _values in the ACTION to perform more complex completions, e.g:
#+BEGIN_SRC sh #+BEGIN_SRC sh
_alternative "dirs:user directories:($userdirs)"\ _alternative \
'opts:comma separated opts:{_values -s , a b c}' "directories:user directory:($userdirs)" \
'options:comma-separated opt: _values -s , letter a b c'
#+END_SRC #+END_SRC
this will complete the items in $userdirs, aswell as a comma separated list containing a, b &/or c. this will complete the items in $userdirs, as well as a comma separated list containing a, b &/or c. Note the use of the initial space before _values. This is needed because _values doesn't understand standard compadd options for descriptions.
As with _describe, the _alternative function can itself be used in an ACTION as part of a specification for _arguments As with _describe, the _alternative function can itself be used in an ACTION as part of a specification for _arguments
or _regex_arguments. or _regex_arguments.
** Writing completion functions using _arguments ** Writing completion functions using _arguments
With the _arguments function you can create more sophisticated completion functions. With a single call to the _arguments function you can create fairly sophisticated completion functions. It is intended to handle typical commands that take a variety of options along with some normal arguments.
Like the _alternative function, _arguments takes a list of specification strings as arguments. 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), These specification strings specify options and any corresponding option arguments (e.g. -f filename),
or command arguments. or command arguments.
Basic option specifications take the form '-OPT[DESCRIPTION]', e.g. like this: Basic option specifications take the form '-OPT[DESCRIPTION]', e.g. like this:
@ -227,11 +232,11 @@ In this case paths to music files are completed stepwise descending down directo
and the flags are completed as a comma separated list using the _values function. and the flags are completed as a comma separated list using the _values function.
I have just given you the basics of _arguments specifications here, you can also specify mutually exclusive options, I have just given you the basics of _arguments specifications here, you can also specify mutually exclusive options,
repeated options & arguments, options beginning with + insead of -, etc. For more details see the [[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-System][official documentation]]. repeated options & arguments, options beginning with + instead of -, etc. For more details see the [[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-System][official documentation]].
Also have a look at the tutorials mentioned at the end of this document, and the completion functions in the [[https://github.com/vapniks/zsh-completions/tree/master/src][src directory]]. Also have a look at the tutorials mentioned at the end of this document, and the completion functions in the [[https://github.com/vapniks/zsh-completions/tree/master/src][src directory]].
** Writing completion functions using _regex_arguments and _regex_words ** Writing completion functions using _regex_arguments and _regex_words
If you have a complex command line specification with several different possible argument sequences then If you have a complex command line specification with several different possible argument sequences then
the _regex_arguments function may be what you need. the _regex_arguments function may be what you need. It typically works well where you have a series of keywords followed by a variable number of arguments.
_regex_arguments creates a completion function whose name is given by the first argument. _regex_arguments creates a completion function whose name is given by the first argument.
Hence you need to first call _regex_arguments to create the completion function, and then call that function, Hence you need to first call _regex_arguments to create the completion function, and then call that function,
@ -251,7 +256,7 @@ For example:
_regex_arguments _cmd SEQ1 '|' SEQ2 \( SEQ2a '|' SEQ2b \) _regex_arguments _cmd SEQ1 '|' SEQ2 \( SEQ2a '|' SEQ2b \)
_cmd "$@" _cmd "$@"
#+END_SRC #+END_SRC
this specifies a command line matching either SEQ1, or SEQ2 followed by SEQ2a or SEQ2b. This specifies a command line matching either SEQ1, or SEQ2 followed by SEQ2a or SEQ2b. You are describing the form arguments to the command take in the form of a regular expression grammar.
Each specification in a sequence must contain a / PATTERN/ part at the start followed by an optional ':TAG:DESCRIPTION:ACTION' Each specification in a sequence must contain a / PATTERN/ part at the start followed by an optional ':TAG:DESCRIPTION:ACTION'
part. part.