svxf/dotfiles
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

update prezto

Browse Source
This commit is contained in:
svxf
2018-11-18 23:37:19 +04:00
parent a17ecf9f57
commit 2808949f26
352 changed files with 15169 additions and 25328 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
.zprezto/modules/completion/external/zsh-completions-howto.org vendored
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
[[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.
* Getting started
** 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
| _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. |
| _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. |
| _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
@@ -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. |
| _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. |
| _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
| _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. |
@@ -119,72 +120,76 @@ _regex_arguments or _alternative functions.
** 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
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).
#+BEGIN_SRC sh
#compdef cmd
local -a options
options=('-c:description for -c opt' '-d:description for -d opt')
_describe 'values' options
local -a subcmds
subcmds=('c:description for c command' 'd:description for d command')
_describe 'command' subcmds
#+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
local -a options arguments
options=('-c:description for -c opt' '-d:description for -d opt')
arguments=('e:description for e arg' 'f:description for f arg')
_describe 'values' options -- arguments
local -a subcmds topics
subcmds=('c:description for c command' 'd:description for d command')
topics=('e:description for e help topic' 'f:description for f help topic')
_describe 'command' subcmds -- topics
#+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.
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
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,
DESCRIPTION is a description, and ACTION is one of the action types listed previously (apart from the ->STRING and =ACTION forms).
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 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:
#+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
The first specification adds completion candidates a, b & c, and the second specification calls the _files function
for completing filepaths.
The first specification adds completion candidates a, b & c, and the second specification calls the _files function for completing filepaths.
We could split the specifications over several lines with \ and add descriptions to each of the custom args like this:
#+BEGIN_SRC sh
_alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"description c"))'\
'files:filenames:_files'
_alternative \
'args:custom arg:((a\:"description a" b\:"description b" c\:"description c"))' \
'files:filename:_files'
#+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
_alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"description c"))'\
'files:filenames:{_files -/}'
_alternative \
'args:custom arg:((a\:"description a" b\:"description b" c\:"description c"))'\
'files:filename:_files -/'
#+END_SRC
To use parameter expansion to create our list of completions we must use double quotes to quote the specifications,
e.g:
#+BEGIN_SRC sh
_alternative "dirs:user directories:($userdirs)"\
"pids:process IDs:($(ps -A o pid=))"
_alternative \
"dirs:user directory:($userdirs)" \
"pids:process ID:($(ps -A o pid=))"
#+END_SRC
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:
#+BEGIN_SRC sh
_alternative "dirs:user directories:($userdirs)"\
'opts:comma separated opts:{_values -s , a b c}'
_alternative \
"directories:user directory:($userdirs)" \
'options:comma-separated opt: _values -s , letter a b c'
#+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
or _regex_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.
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.
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.
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]].
** Writing completion functions using _regex_arguments and _regex_words
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.
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 \)
_cmd "$@"
#+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'
part.
@@ -266,7 +271,7 @@ except that it has an extra : at the start, and now all of the possible ACTION f
Here is an example:
#+BEGIN_SRC sh
_regex_arguments _hello /$'[^\0]##\0'/ \( /$'word1(a|b|c)\0'/ ':word:first word:(word1a word1b word1c)' '|'\
_regex_arguments _cmd /$'[^\0]##\0'/ \( /$'word1(a|b|c)\0'/ ':word:first word:(word1a word1b word1c)' '|'\
/$'word11(a|b|c)\0'/ ':word:first word:(word11a word11b word11c)' \( /$'word2(a|b|c)\0'/ ':word:second word:(word2a word2b word2c)'\
'|' /$'word22(a|b|c)\0'/ ':word:second word:(word22a word22b word22c)' \) \)
_cmd "$@"
@@ -435,6 +440,6 @@ you can add another empty option (i.e. \:) to the ACTION like this ':TAG:DESCRIP
Note this only applies to utility functions that use ACTIONs in their specification arguments (_arguments, _regex_arguments, etc.)
* 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,
[[https://wikimatze.de/writing-zsh-completion-for-padrino/][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.