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

update

This commit is contained in:
Joe Bloggs 2014-03-27 13:40:25 +00:00
parent 3b777e258a
commit b69f5b9d96
1 changed files with 15 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
zsh-completions-howto.org
View File

@ -127,7 +127,6 @@ _describe 'values' options
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 e.g. like this:
#+BEGIN_SRC sh #+BEGIN_SRC sh
#compdef cmd
local -a options arguments local -a options arguments
options=('-c:description for -c opt' '-d:description for -d opt') options=('-c:description for -c opt' '-d:description for -d opt')
arguments=('e:description for e arg' 'f:description for f arg') arguments=('e:description for e arg' 'f:description for f arg')
@ -144,7 +143,6 @@ As arguments it takes a list of specifications each in the form 'TAG:DESCRIPTION
DESCRIPTION is a description, and ACTION is one of the action types listed previously (apart from the ->STRING and =ACTION forms). DESCRIPTION is a description, 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
#compdef cmd
_alternative 'args:custom args:(a b c)' 'files:filenames:_files' _alternative 'args:custom args:(a b c)' 'files:filenames:_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
@ -152,14 +150,12 @@ 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
#compdef cmd
_alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"description c"))'\ _alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"description c"))'\
'files:filenames:_files' 'files:filenames:_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 call _files with arguments we can put it in braces, like this:
#+BEGIN_SRC sh #+BEGIN_SRC sh
#compdef cmd
_alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"description c"))'\ _alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"description c"))'\
'files:filenames:{_files -/}' 'files:filenames:{_files -/}'
#+END_SRC #+END_SRC
@ -167,7 +163,6 @@ _alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"descr
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
#compdef cmd
_alternative "dirs:user directories:($userdirs)"\ _alternative "dirs:user directories:($userdirs)"\
"pids:process IDs:($(ps -A o pid=))" "pids:process IDs:($(ps -A o pid=))"
#+END_SRC #+END_SRC
@ -176,7 +171,6 @@ evaluates 'ps -A o pid=' to get a list of pids to use as completion candidates.
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
#compdef cmd
_alternative "dirs:user directories:($userdirs)"\ _alternative "dirs:user directories:($userdirs)"\
'opts:comma separated opts:{_values -s , a b c}' 'opts:comma separated opts:{_values -s , a b c}'
#+END_SRC #+END_SRC
@ -192,14 +186,12 @@ 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:
#+BEGIN_SRC sh #+BEGIN_SRC sh
#compdef cmd
_arguments '-s[sort output]' '--l[long output]' '-l[long output]' _arguments '-s[sort output]' '--l[long output]' '-l[long output]'
#+END_SRC #+END_SRC
Arguments for the option can be specified after the option description in this form '-OPT[DESCRIPTION]:MESSAGE:ACTION', Arguments for the option can be specified after the option description in this form '-OPT[DESCRIPTION]:MESSAGE:ACTION',
where MESSAGE is a message to display and ACTION can be any of the forms mentioned in the ACTIONS section above. where MESSAGE is a message to display and ACTION can be any of the forms mentioned in the ACTIONS section above.
For example: For example:
#+BEGIN_SRC sh #+BEGIN_SRC sh
#compdef cmd
_arguments '-f[input file]:filename:_files' _arguments '-f[input file]:filename:_files'
#+END_SRC #+END_SRC
@ -208,7 +200,6 @@ and MESSAGE & ACTION are as before. If the N is omitted then it just means the n
already been specified). If a double colon is used at the start (after N) then the argument is optional. already been specified). If a double colon is used at the start (after N) then the argument is optional.
For example: For example:
#+BEGIN_SRC sh #+BEGIN_SRC sh
#compdef cmd
_arguments '-s[sort output]' '1:first arg:_net_interfaces' '::optional arg:_files' ':next arg:(a b c)' _arguments '-s[sort output]' '1:first arg:_net_interfaces' '::optional arg:_files' ':next arg:(a b c)'
#+END_SRC #+END_SRC
here the first arg is a network interface, the next optional arg is a file name, the last arg can be either a, b or c, here the first arg is a network interface, the next optional arg is a file name, the last arg can be either a, b or c,
@ -217,7 +208,6 @@ and the -s option may be completed at any position.
The _arguments function allows the full set of ACTION forms listed in the ACTION section above. The _arguments function allows the full set of ACTION forms listed in the ACTION section above.
This means that you can use actions for selecting case statement branches like this: This means that you can use actions for selecting case statement branches like this:
#+BEGIN_SRC sh #+BEGIN_SRC sh
#compdef cmd
_arguments '-m[music file]:filename:->files' '-f[flags]:flag:->flags' _arguments '-m[music file]:filename:->files' '-f[flags]:flag:->flags'
case "$state" in case "$state" in
files) files)
@ -244,7 +234,6 @@ _regex_arguments creates a completion function whose name is given by the first
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,
e.g. like this: e.g. like this:
#+BEGIN_SRC sh #+BEGIN_SRC sh
#compdef cmd
_regex_arguments _cmd OTHER_ARGS.. _regex_arguments _cmd OTHER_ARGS..
_cmd "$@" _cmd "$@"
#+END_SRC #+END_SRC
@ -254,7 +243,6 @@ These sequences can be separated by '|' to represent alternative sequences of wo
You can use bracketing to arbitrary depth to specify alternate subsequences. You can use bracketing to arbitrary depth to specify alternate subsequences.
For example: For example:
#+BEGIN_SRC sh #+BEGIN_SRC sh
#compdef cmd
_regex_arguments _cmd SEQ1 '|' SEQ2 \( SEQ2a '|' SEQ2b \) _regex_arguments _cmd SEQ1 '|' SEQ2 \( SEQ2a '|' SEQ2b \)
_cmd "$@" _cmd "$@"
#+END_SRC #+END_SRC
@ -267,19 +255,25 @@ for that word. Note that there needs to be a pattern to match the initial comman
Note that the ':TAG:DESCRIPTION:ACTION' part is interpreted in the same way as for the _alternative function specifications, Note that the ':TAG:DESCRIPTION:ACTION' part is interpreted in the same way as for the _alternative function specifications,
except that it has an extra : at the start, and now all of the possible ACTION formats listed previously are allowed. except that it has an extra : at the start, and now all of the possible ACTION formats listed previously are allowed.
Here is an example Here is an example:
#+BEGIN_SRC sh #+BEGIN_SRC sh
#compdef cmd _regex_arguments _hello /$'[^\0]##\0'/ \( /$'word1(a|b|c)\0'/ ':word:first word:(word1a word1b word1c)' '|'\
_regex_arguments _cmd /$'[^\0]##\0'/ /$'[^\0]##\0'/ 'file:filename:_files' '|' /$'word2\0'/ 'file:filename:_files' \ /$'word11(a|b|c)\0'/ ':word:first word:(word11a word11b word11c)' \( /$'word2(a|b|c)\0'/ ':word:second word:(word2a word2b word2c)'\
\( /$'word1\0'/ 'file:filename:_files' '|' /$'word1\0'/ 'file:filename:_files' \) '|' /$'word22(a|b|c)\0'/ ':word:second word:(word22a word22b word22c)' \) \)
_cmd "$@" _cmd "$@"
#+END_SRC #+END_SRC
in this case the first word can be word1 or word11 followed by an a, b or c, and if the first word contains 11 then a second
word is allowed which can be word2 followed by and a, b, or c, or a filename.
If this sounds too complicated a simpler alternative is to use the _regex_words function for creating If this sounds too complicated a much simpler alternative is to use the _regex_words function for creating
specifications for _regex_arguments. specifications for _regex_arguments.
*** _regex_words
*** Patterns *** Patterns
Note Note * = wildcard, # = wildcard
* Testing & debugging * Testing & debugging
To reload a completion function: To reload a completion function:
#+BEGIN_SRC sh #+BEGIN_SRC sh
@ -295,6 +289,8 @@ If the default keybindings don't work you can try pressing Alt+x and then enter
| _complete_help | Alt+2 Ctrl+x h | as above but displays even more information | | _complete_help | Alt+2 Ctrl+x h | as above but displays even more information |
| _complete_debug | Ctrl+x ? | performs ordinary completion, but captures in a temporary file a trace of the shell commands executed by the completion system | | _complete_debug | Ctrl+x ? | performs ordinary completion, but captures in a temporary file a trace of the shell commands executed by the completion system |
* Gotchas (things to watch out for) * Gotchas (things to watch out for)
Remember to include a #compdef line at the beginning of the file containing the completion function.
Take care to use the correct type of quoting for specifications to _arguments or _regex_arguments: Take care to use the correct type of quoting for specifications to _arguments or _regex_arguments:
use double quotes if there is a parameter that needs to be expanded in the specification, single quotes otherwise, use double quotes if there is a parameter that needs to be expanded in the specification, single quotes otherwise,
and make sure to use different quotes around item descriptions. and make sure to use different quotes around item descriptions.