From a0ea8a932eb758c123d864abe5c88137653ec13e Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Fri, 14 Mar 2014 21:48:06 +0000 Subject: [PATCH 01/73] Completion for ps command --- src/_ps | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 src/_ps diff --git a/src/_ps b/src/_ps new file mode 100644 index 0000000..61010c6 --- /dev/null +++ b/src/_ps @@ -0,0 +1,128 @@ +#compdef ps + +local context state state_descr line +typeset -A opt_args +local filterexcl="(-A -a -C -d -e -g -G --group --Group -p --pid --ppid -s --sid -t --tty -u -U --user --User)" + +_arguments -s \ + "$filterexcl-A[all processes]"\ + "$filterexcl-a[all w/ tty except session leaders]"\ + "--cumulative[include some dead child process data (as a sum with the parent)]"\ + "(-f -F --format -l -o -O)--context[display security context format (for SE Linux)]"\ + "-c[show different scheduler information]"\ + "$filterexcl-C[by command name]:processes:->pname"\ + "(--columns)--cols[set screen width]:width:( )"\ + "(--cols)--columns[set screen width]:width:( )"\ + "--deselect[negate selection]"\ + "$filterexcl-d[all except session leaders]"\ + "$filterexcl-e[all processes]"\ + "--forest[ASCII art process tree]"\ + "(--context -F --format -o -O)-f[full format listing]"\ + "(--context -f --format -o -O)-F[extra full format]"\ + "(--context -f -F -j -l -o -O)--format[user-defined format]:output format:->format"\ + "$filterexcl-g[by session OR by effective group name]:groups:->groups"\ + "$filterexcl-G[by real group ID (supports names)]:groups:->rgid"\ + "$filterexcl--group[by session OR by effective group name]:groups:->groups"\ + "$filterexcl--Group[by real group ID (supports names)]:groups:->rgid"\ + "-H[show process hierarchy]"\ + "(--no-heading)--heading[repeat header lines, one per page of output]"\ + "-j[jobs format]"\ + "-l[long format. the -y option is often useful with this]"\ + "-L[show threads, possibly with LWP and NLWP columns]"\ + "-m[show threads after processes]"\ + "-M[add a column of security data]"\ + "-N[negate selection]"\ + "(--heading --header)--no-heading[omit header lines]"\ + "(--context -f -F --format -j -l)-o[user-defined format]:output format:->format"\ + "(--context -f -F --format -j -l)-O[preloaded -o (user-defined with some)]:output format:->format"\ + "$filterexcl-p[by process ID]:process IDs:->pid"\ + "$filterexcl--pid[by process ID]:process IDs:->pid"\ + "$filterexcl--ppid[select by parent process ID]:process IDs:->ppid"\ + "--rows[set screen height.]:height:( )"\ + "$filterexcl-s[by session IDs]:sessions:->sid"\ + "$filterexcl--sid[by session IDs]:sessions:->sid"\ + "--sort[specify sorting order]:sort specs:->sortspec"\ + "$filterexcl-t[by tty]:ttys:->tty"\ + "-T[show threads, possibly with SPID column]"\ + "$filterexcl--tty[by tty]:ttys:->tty"\ + "$filterexcl-u[by effective user ID (supports names)]:users:->users"\ + "$filterexcl-U[by real user ID (supports names)]:users:->users"\ + "$filterexcl--user[by effective user ID (supports names)]:users:->users"\ + "$filterexcl--User[by real user ID (supports names)]:users:->users"\ + "(--version)-V[print the procps version]"\ + "(-V)--version[print the procps version]"\ + "-w[wide output]"\ + "-y[use with -l, do not show flags, show rss in place of addr]"\ + "1:BSD-style options (complete - to see unix & gnu-style options):((T\:'all processes on this terminal' a\:'all w/ tty, including other users' r\:'only running processes' x\:'processes w/o controlling ttys' t\:'list by tty' j\:'BSD jobs control format' l\:'BSD long format' s\:'signal format' v\:'virtual memory format' u\:'user-oriented format' X\:'register format' L\:'list format codes' S\:'sum info of children into parents' c\:'true command name' n\:'numeric WCHAN & UID' H\:'show threads as if they were processes' U\:'by effective user ID' p\:'by process ID'))"\ + - debug "--info[print debugging info]" + +case "$state" in + pid) + compset -P '*,' + local -a used pid + used=(${(s:,:)IPREFIX}) + pid=(${(uon)$(ps -A o pid=)}) + _wanted pgid expl 'process id' compadd -S ',' -q -F used $pid + ;; + users) + _users + ;; + rgid) + compset -P '*,' + local -a used rgid + used=(${(s:,:)IPREFIX}) + rgid=(${(uon)$(ps -A o rgid=)}) + _wanted rgid expl 'process group id' compadd -S ',' -q -F used $rgid + ;; + groups) + _groups + ;; + pname) + local ispat="pattern matching " + if (( ${+opt_args[-x]} )) + then + ispat="" + fi + if (( ${+opt_args[-f]} )) + then + _wanted pname expl $ispat'process command line' compadd ${(u)${(f)"$(ps -A o cmd=)"}} + else + _wanted pname expl $ispat'process name' compadd ${(u)${(f)"$(ps -A co cmd=)"}} + fi + ;; + sid) + compset -P '*,' + local -a used sid + used=(${(s:,:)IPREFIX}) + sid=(${(uon)$(ps -A o sid=)}) + _wanted sid expl 'session id' compadd -S ',' -q -F used $sid + ;; + tty) + compset -P '*,' + local -a used ttys + used=(${(s:,:)IPREFIX}) + ttys=( /dev/tty*(N) /dev/pts/*(N) ) + _wanted tty expl 'terminal device' compadd -S ',' -q -F used ${ttys#/dev/} + ;; + ppid) + compset -P '*,' + local -a used ppid + used=(${(s:,:)IPREFIX}) + ppid=(${(uon)$(ps -A o ppid=)}) + _wanted ppid expl 'parent process id' compadd -S ',' -q -F used $ppid + ;; + sortspec) + compset -P '*,' + local -a used spec minuspec pluspec allspec + used=(${(s:,:)IPREFIX/[-+]/}) + spec=(${(uo)$(ps L|cut -f 1 -d" ")}) + _wanted spec expl 'format specifier (prefix with - for decreasing order)' compadd -S ',' -q -F used $spec + ;; + format) + compset -P '*,' + local -a used spec + used=(${(s:,:)IPREFIX}) + spec=(${(uo)$(ps L|cut -f 1 -d" ")}) + _wanted spec expl 'format specifier' compadd -S ',' -q -F used $spec + ;; +esac From 9b33101c7f41fee8b5f937c982936fce1fc574fe Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Fri, 14 Mar 2014 21:52:27 +0000 Subject: [PATCH 02/73] Note about version --- src/_ps | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/_ps b/src/_ps index 61010c6..2321cb0 100644 --- a/src/_ps +++ b/src/_ps @@ -1,5 +1,7 @@ #compdef ps +# This works with procps version 3.2.8 + local context state state_descr line typeset -A opt_args local filterexcl="(-A -a -C -d -e -g -G --group --Group -p --pid --ppid -s --sid -t --tty -u -U --user --User)" From 67db8fb2852656c48a129b4d786a945a02178c77 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Fri, 14 Mar 2014 22:41:15 +0000 Subject: [PATCH 03/73] Add -w special option for _arguments --- src/_ps | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/_ps b/src/_ps index 2321cb0..a7e6be6 100644 --- a/src/_ps +++ b/src/_ps @@ -6,7 +6,7 @@ local context state state_descr line typeset -A opt_args local filterexcl="(-A -a -C -d -e -g -G --group --Group -p --pid --ppid -s --sid -t --tty -u -U --user --User)" -_arguments -s \ +_arguments -s -w \ "$filterexcl-A[all processes]"\ "$filterexcl-a[all w/ tty except session leaders]"\ "--cumulative[include some dead child process data (as a sum with the parent)]"\ From ab53d842a9fe3396c9bfbc9cd7b9dec7aec1126b Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 20 Mar 2014 14:01:33 +0000 Subject: [PATCH 04/73] Add _comma_separated helper function Helper function for completing comma separated values --- src/_comma_separated | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 src/_comma_separated diff --git a/src/_comma_separated b/src/_comma_separated new file mode 100644 index 0000000..2f59505 --- /dev/null +++ b/src/_comma_separated @@ -0,0 +1,11 @@ +#autoload + +# This function can be used to complete comma separated values. +# The first argument should be a description for the completion items, +# and any further args are the completion items themselves. + +compset -P '*,' +local -a used vals +used=(${(s:,:)IPREFIX}) +_wanted tty expl $1 compadd -S ',' -q -F used "$@[2,-1]" + From f73ebdc3a76a526cc1f6858a10f2b84951a832b9 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 20 Mar 2014 14:47:24 +0000 Subject: [PATCH 05/73] Utilize _comma_separated function to squash code a bit --- src/_ps | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/src/_ps b/src/_ps index a7e6be6..dd8ba5c 100644 --- a/src/_ps +++ b/src/_ps @@ -1,6 +1,18 @@ #compdef ps -# This works with procps version 3.2.8 +# This works with procps version 3.2.8 + +# This depends on the _comma_separated function, which should be available from the same +# place you got this file. If it isn't then you can uncomment the following lines to define +# the function: +# +# _comma_separated() +# { +# compset -P '*,' +# local -a used vals +# used=(${(s:,:)IPREFIX}) +# _wanted tty expl $1 compadd -S ',' -q -F used "$@[2,-1]" +# } local context state state_descr line typeset -A opt_args From ad94b7ec67c1d5238cd503b36001334544af9107 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Mon, 24 Mar 2014 00:44:51 +0000 Subject: [PATCH 06/73] Initial commit of howto test --- zsh-completions-howto.org | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 zsh-completions-howto.org diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org new file mode 100644 index 0000000..eeeeafb --- /dev/null +++ b/zsh-completions-howto.org @@ -0,0 +1,8 @@ +* Test +hi +** this +there +*** foobar +does +** one +this look ok? From f787586b3a8998cf0d025b141882ce99eccd51cd Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Mon, 24 Mar 2014 01:18:49 +0000 Subject: [PATCH 07/73] Basic structure --- zsh-completions-howto.org | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index eeeeafb..de45ce0 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -1,8 +1,15 @@ -* Test -hi -** this -there -*** foobar -does -** one -this look ok? +* Intro +** Defining completion functions +* Utility functions with example code +** compadd +** _gnu_generic +** _arguments +** _regex_arguments +** _regex_words +** _values +** _comma_separated +* Putting it all together +* Other resources +Nicely formatted short tutorial showing basic usage of the _arguments function: http://wikimatze.de/writing-zsh-completion-for-padrino.html +A slightly more advanced tutorial showing usage of the _arguments function: http://www.linux-mag.com/id/1106/ +zshcompsys man page: http://linux.die.net/man/1/zshcompsys From 38e4c2eec7590d5813216e5932d41998df67f9ad Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Mon, 24 Mar 2014 01:22:31 +0000 Subject: [PATCH 08/73] Alter links --- zsh-completions-howto.org | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index de45ce0..d520545 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -4,12 +4,15 @@ ** compadd ** _gnu_generic ** _arguments + :PROPERTIES: + :ID: 64bcd501-b0f0-48c7-b8e2-07af708b95ec + :END: ** _regex_arguments ** _regex_words ** _values ** _comma_separated * Putting it all together * Other resources -Nicely formatted short tutorial showing basic usage of the _arguments function: http://wikimatze.de/writing-zsh-completion-for-padrino.html -A slightly more advanced tutorial showing usage of the _arguments function: http://www.linux-mag.com/id/1106/ -zshcompsys man page: http://linux.die.net/man/1/zshcompsys +[[http://wikimatze.de/writing-zsh-completion-for-padrino.html][Here]] is a nicely formatted short tutorial showing basic usage of the [[id:64bcd501-b0f0-48c7-b8e2-07af708b95ec][_arguments]] function, +and [[http://www.linux-mag.com/id/1106/][here]] is a slightly more advanced tutorial using the [[id:64bcd501-b0f0-48c7-b8e2-07af708b95ec][_arguments]] function. +[[http://linux.die.net/man/1/zshcompsys][Here]] is the zshcompsys man page. From ed73fce676a8713babc78bbcc7380f7b026bec8a Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Mon, 24 Mar 2014 01:53:02 +0000 Subject: [PATCH 09/73] Intro --- zsh-completions-howto.org | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index d520545..fc06a84 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -1,18 +1,27 @@ * 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, which can be looked up in the +[[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-System][official documentation]]. + +Hopefully, after reading this, you will be able to get up and running with your own completion scripts pretty quickly. +Please make any scripts that you create publically available for others (e.g. by forking this repository and making a [[id:64bcd501-b0f0-48c7-b8e2-07af708b95ec][pull request]]). + ** Defining completion functions +Completion functions for a given command * Utility functions with example code ** compadd ** _gnu_generic ** _arguments - :PROPERTIES: - :ID: 64bcd501-b0f0-48c7-b8e2-07af708b95ec - :END: + ** _regex_arguments ** _regex_words ** _values ** _comma_separated +* 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 [[id:64bcd501-b0f0-48c7-b8e2-07af708b95ec][_arguments]] function, -and [[http://www.linux-mag.com/id/1106/][here]] is a slightly more advanced tutorial using the [[id:64bcd501-b0f0-48c7-b8e2-07af708b95ec][_arguments]] function. -[[http://linux.die.net/man/1/zshcompsys][Here]] is the zshcompsys man page. +[[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. From ea01659a66059d888d7f815a946e3bd0c9d38bf1 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Mon, 24 Mar 2014 02:07:22 +0000 Subject: [PATCH 10/73] Test src block --- zsh-completions-howto.org | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index fc06a84..a104cd0 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -2,14 +2,18 @@ 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, which can be looked up in the -[[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-System][official documentation]]. +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]]. -Hopefully, after reading this, you will be able to get up and running with your own completion scripts pretty quickly. -Please make any scripts that you create publically available for others (e.g. by forking this repository and making a [[id:64bcd501-b0f0-48c7-b8e2-07af708b95ec][pull request]]). +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 a given command +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 * Utility functions with example code ** compadd ** _gnu_generic From b27db238c91d6f59db0e2dc91370f8b0e66ef1a0 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Mon, 24 Mar 2014 03:13:23 +0000 Subject: [PATCH 11/73] update --- zsh-completions-howto.org | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index a104cd0..02b6bb4 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -14,15 +14,34 @@ You can add a directory to $fpath by adding a line like this to your ~/.zshrc fi #+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 From db2dfce0b68eb027e28ee27c3b3bbfcbd1b0644b Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Mon, 24 Mar 2014 04:01:31 +0000 Subject: [PATCH 12/73] update --- zsh-completions-howto.org | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 02b6bb4..49ea099 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -6,8 +6,8 @@ understand explanation for creating zsh completion functions. I do not go into a 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 +* Getting started +** defining a completion function to use for a command 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: @@ -22,8 +22,8 @@ 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: +You can also use the compdef command directly (e.g. in your ~/.zshrc file) to tell zsh which function to use for completing +a command like this: #+BEGIN_SRC sh > compdef _function foobar #+END_SRC @@ -32,6 +32,25 @@ or if you want to supply arguments: > compdef '_function arg1 arg2' foobar #+END_SRC See [[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Functions-4][here]] for more details. +** completing generic gnu commands +Many [[http://www.gnu.org/][gnu]] commands have a standardized way of listing option descriptions (when the --help option is used). +For these commands you can use the _gnu_generic function for automatically creating completions, like this: +#+BEGIN_SRC sh +> compdef _gnu_generic foobar +#+END_SRC +** using completions from one command for completing another command +If you want a command, say cmd1, to have the same completions as another, say cmd2, you can do this: +#+BEGIN_SRC sh +> compdef cmd1=cmd2 +#+END_SRC +This can be useful for example if you have created an alias for a command to help you remember it. +** Writing your own completion functions +A good way to get started is to look at some already defined completion functions. +On my linux installation these are found in /usr/share/zsh/functions/Completion/Unix +and /usr/share/zsh/functions/Completion/Linux and a few other subdirs. + +You will notice that the _arguments function is used a lot. This is a utility function that makes +it easy to write simple completion functions. * Utility functions with example code ** compadd ** _gnu_generic From ffc9b482911054fff77a4f07f6135ed1afea385d Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Mon, 24 Mar 2014 04:04:08 +0000 Subject: [PATCH 13/73] update --- zsh-completions-howto.org | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 49ea099..1b8c80d 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -7,7 +7,7 @@ and examples to get you up and running. If you need more details you can look it 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 -** defining a completion function to use for a command +** Defining a completion function to use for a command 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: @@ -32,13 +32,13 @@ or if you want to supply arguments: > compdef '_function arg1 arg2' foobar #+END_SRC See [[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Functions-4][here]] for more details. -** completing generic gnu commands +** Completing generic gnu commands Many [[http://www.gnu.org/][gnu]] commands have a standardized way of listing option descriptions (when the --help option is used). For these commands you can use the _gnu_generic function for automatically creating completions, like this: #+BEGIN_SRC sh > compdef _gnu_generic foobar #+END_SRC -** using completions from one command for completing another command +** Using completions from one command for completing another command If you want a command, say cmd1, to have the same completions as another, say cmd2, you can do this: #+BEGIN_SRC sh > compdef cmd1=cmd2 From 5af6a68833f26a8d9afb9c5b1992316e03abcf08 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Mon, 24 Mar 2014 04:07:08 +0000 Subject: [PATCH 14/73] update --- zsh-completions-howto.org | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 1b8c80d..aef9ce3 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -7,7 +7,7 @@ and examples to get you up and running. If you need more details you can look it 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 -** Defining a completion function to use for a command +** Telling zsh which completion function to use for a command 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: @@ -38,7 +38,7 @@ For these commands you can use the _gnu_generic function for automatically creat #+BEGIN_SRC sh > compdef _gnu_generic foobar #+END_SRC -** Using completions from one command for completing another command +** Copying completions from another command If you want a command, say cmd1, to have the same completions as another, say cmd2, you can do this: #+BEGIN_SRC sh > compdef cmd1=cmd2 From 2e3bd231fd7a19d6465382e1a34efbc9a4e74c23 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Mon, 24 Mar 2014 04:07:52 +0000 Subject: [PATCH 15/73] update --- zsh-completions-howto.org | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index aef9ce3..b0effd8 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -7,7 +7,7 @@ and examples to get you up and running. If you need more details you can look it 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 -** Telling zsh which completion function to use for a command +** Telling zsh which function to use for completing a command 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: From 6fde93200f3d57eb3b36d36553b860b3d085713b Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Mon, 24 Mar 2014 04:19:08 +0000 Subject: [PATCH 16/73] update --- zsh-completions-howto.org | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index b0effd8..39823d9 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -49,8 +49,12 @@ A good way to get started is to look at some already defined completion function On my linux installation these are found in /usr/share/zsh/functions/Completion/Unix and /usr/share/zsh/functions/Completion/Linux and a few other subdirs. -You will notice that the _arguments function is used a lot. This is a utility function that makes -it easy to write simple completion functions. +You will notice that the _arguments function is used a lot in these files. +This is a utility function that makes it easy to write simple completion functions. +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. * Utility functions with example code ** compadd ** _gnu_generic From bbb5598fcd3413f8f6fb87f519a4660a5e3ef208 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Mon, 24 Mar 2014 15:36:59 +0000 Subject: [PATCH 17/73] update --- zsh-completions-howto.org | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 39823d9..5147bd3 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -27,6 +27,10 @@ a command like this: #+BEGIN_SRC sh > compdef _function foobar #+END_SRC +or to use the same completions for several commands: +#+BEGIN_SRC sh +> compdef _function foobar goocar hoodar +#+END_SRC or if you want to supply arguments: #+BEGIN_SRC sh > compdef '_function arg1 arg2' foobar @@ -38,13 +42,19 @@ For these commands you can use the _gnu_generic function for automatically creat #+BEGIN_SRC sh > compdef _gnu_generic foobar #+END_SRC +or to use _gnu_generic with several different commands: +#+BEGIN_SRC sh +> compdef _gnu_generic foobar goocar hoodar +#+END_SRC +This line can be placed in your ~/.zshrc file. ** Copying completions from another command -If you want a command, say cmd1, to have the same completions as another, say cmd2, you can do this: +If you want a command, say cmd1, to have the same completions as another, say cmd2, which has already had +completions defined for it, you can do this: #+BEGIN_SRC sh > compdef cmd1=cmd2 #+END_SRC This can be useful for example if you have created an alias for a command to help you remember it. -** Writing your own completion functions +* Writing your own completion functions A good way to get started is to look at some already defined completion functions. On my linux installation these are found in /usr/share/zsh/functions/Completion/Unix and /usr/share/zsh/functions/Completion/Linux and a few other subdirs. @@ -55,6 +65,18 @@ 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. +** 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, +e.g. like this: +#+BEGIN_SRC sh +_arguments '--help[show help]' '-?[show help]' '1:First arg:_files' +#+END_SRC +This example completes the options --help & -? when trying to complete a hyphen, which will both be listed together +with the same description in this case. The first non-option argument is completed using the _files function which +completes file/directories. + + * Utility functions with example code ** compadd ** _gnu_generic From 815c0a73ffaa6463908e32577d41139dab2be2d1 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Mon, 24 Mar 2014 22:20:53 +0000 Subject: [PATCH 18/73] 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 From 886184642fa59a257e8850eab49878cabf5edc68 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Tue, 25 Mar 2014 16:02:14 +0000 Subject: [PATCH 19/73] update --- zsh-completions-howto.org | 48 ++++++++++++++++++++------------------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index d24aff3..634faab 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -68,27 +68,31 @@ However, most of the time you will not need to use compadd, since there are many 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 | | +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]]. +*** main utility functions for overall completion +| _arguments | Used to specify how to complete individual command line options for a command with unix style options. Often used. | +| _regex_arguments | Creates a function for matching commandline arguments with regular expressions, and then performing actions/completions. | +| _gnu_generic | Can be used to complete options for commands that understand the `--help' option. | +| _alternative | Loop over tag labels and perform actions based on matching tag label. | +*** functions for performing complex completions +| _values | Used for completing arbitrary keywords (values) and their arguments, or comma separated lists of such combinations. | +| _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. | +*** 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. | +| _net_interfaces | Used for completing network interface names | +| _users | Used for completing user names | +| _groups | Used for completing group names | +| _options | Used for completing the names of shell options. | +| _parameters | Used for completing the names of shell parameters/variables (can restrict to those matching a pattern). | +*** other functions +| _message | Used for displaying help messages in places where no completions can be generated. | +| _regex_words | Can be used to generate arguments for the _regex_arguments command. This is easier than writing the arguments manually. | +| _guard | Can be used in the ACTION of specifications for _arguments and similar functions to check the word being completed. | + ** 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, @@ -100,8 +104,6 @@ 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]]. From 67d5524896f2686675f0c03b6f5d49290becfe75 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Tue, 25 Mar 2014 16:02:50 +0000 Subject: [PATCH 20/73] remove _comma_separated Just realised you can do the same thing with _values --- src/_comma_separated | 11 ----------- 1 file changed, 11 deletions(-) delete mode 100644 src/_comma_separated diff --git a/src/_comma_separated b/src/_comma_separated deleted file mode 100644 index 2f59505..0000000 --- a/src/_comma_separated +++ /dev/null @@ -1,11 +0,0 @@ -#autoload - -# This function can be used to complete comma separated values. -# The first argument should be a description for the completion items, -# and any further args are the completion items themselves. - -compset -P '*,' -local -a used vals -used=(${(s:,:)IPREFIX}) -_wanted tty expl $1 compadd -S ',' -q -F used "$@[2,-1]" - From 0edd329b8a7ab20796b8f839c90d44b72fd47074 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Tue, 25 Mar 2014 21:12:55 +0000 Subject: [PATCH 21/73] update --- zsh-completions-howto.org | 52 +++++++++++++++++++++------------------ 1 file changed, 28 insertions(+), 24 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 634faab..b15ce7e 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -65,16 +65,17 @@ 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 _regex_arguments which are easier to use. +and _describe 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]]. *** main utility functions for overall completion -| _arguments | Used to specify how to complete individual command line options for a command with unix style options. Often used. | -| _regex_arguments | Creates a function for matching commandline arguments with regular expressions, and then performing actions/completions. | -| _gnu_generic | Can be used to complete options for commands that understand the `--help' option. | -| _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. | +| _regex_arguments | Creates a function for matching commandline arguments with regular expressions, and then performing actions/completions. | +| _gnu_generic | Can be used to complete options for commands that understand the `--help' option. | +| _alternative | Loop over tag labels and perform actions based on matching tag label. | +| _describe | Used for creating simple completions consisting of single words with descriptions (but no actions). Easier to use than _arguments | *** functions for performing complex completions | _values | Used for completing arbitrary keywords (values) and their arguments, or comma separated lists of such combinations. | | _combination | Used to complete combinations of values, for example pairs of hostnames and usernames. | @@ -88,11 +89,32 @@ The full list of utility functions, with full explanations, is available [[http: | _groups | Used for completing group names | | _options | Used for completing the names of shell options. | | _parameters | Used for completing the names of shell parameters/variables (can restrict to those matching a pattern). | +*** functions for handling cached completions +If you have a very large number of completions you can save them in a cache file so that the completions load quickly. +| _cache_invalid | indicates whether the completions cache corresponding to a given cache identifier needs rebuilding | +| _retrieve_cache | retrieves completion information from a cache file | +| _store_cache | store completions corresponding to a given cache identifier in a cache file | *** other functions | _message | Used for displaying help messages in places where no completions can be generated. | | _regex_words | Can be used to generate arguments for the _regex_arguments command. This is easier than writing the arguments manually. | | _guard | Can be used in the ACTION of specifications for _arguments and similar functions to check the word being completed. | - +*** 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 ** 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, @@ -107,24 +129,6 @@ completes file/directories. 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 From 89a769a7af7e3a19cc0e2d99adb60863bc571820 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Tue, 25 Mar 2014 21:38:46 +0000 Subject: [PATCH 22/73] update --- zsh-completions-howto.org | 42 ++++++++++++++++++--------------------- 1 file changed, 19 insertions(+), 23 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index b15ce7e..000f592 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -70,12 +70,13 @@ and _describe 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]]. +Examples of how to use these functions are given in the next section. *** main utility functions for overall completion -| _arguments | Used to specify how to complete individual command line options for a command with unix style options. Often used. | -| _regex_arguments | Creates a function for matching commandline arguments with regular expressions, and then performing actions/completions. | -| _gnu_generic | Can be used to complete options for commands that understand the `--help' option. | | _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. | | _describe | Used for creating simple completions consisting of single 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 | _values | Used for completing arbitrary keywords (values) and their arguments, or comma separated lists of such combinations. | | _combination | Used to complete combinations of values, for example pairs of hostnames and usernames. | @@ -115,6 +116,8 @@ Here the non-option argument #+BEGIN_SRC sh _arguments '--help[show help]' '-?[show help]' '1:First arg:_files' #+END_SRC +** Writing completion functions using _describe +** Writing completion functions using _alternative ** 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, @@ -130,32 +133,25 @@ There are a couple of tutorials on how to use _arguments [[http://www.linux-mag. 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]]. - -** 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 -** _arguments -** _regex_arguments -** _regex_words -** _values -** _comma_separated -** _files -** _net_interfaces -* testing & debugging +** Writing completion functions using _regex_arguments and _regex_words +*** Patterns +* Testing & debugging To reload a completion function: #+BEGIN_SRC sh > unfunction _func > autoload -U _func #+END_SRC -* gotchas +The following functions can be called to obtain useful information. +If the default keybindings don't work you can try pressing Alt+x and then enter the command name. +| Function | Default keybinding | Description | +|-----------------+--------------------+--------------------------------------------------------------------------------------------------------------------------------| +| _complete_help | Ctrl+x h | displays information about context names, tags, and completion functions used when completing at the current cursor position | +| _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 | +* Gotchas +Take care to use the correct type of quotes around 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. * 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, From f5a7053b70d70cca52fbad28d2e01572fe768832 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Tue, 25 Mar 2014 21:53:43 +0000 Subject: [PATCH 23/73] update --- zsh-completions-howto.org | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 000f592..8bb44eb 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -117,6 +117,22 @@ Here the non-option argument _arguments '--help[show help]' '-?[show help]' '1:First arg:_files' #+END_SRC ** Writing 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, e.g. like this: +#+BEGIN_SRC sh +local -a options +options=('-c:description for -c opt' '-d:description for -d opt') +_describe 'values' options +#+END_SRC +You can use several different lists separated by -- e.g. like this: +#+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 +#+END_SRC + ** Writing completion functions using _alternative ** Writing completion functions using _arguments The _arguments function makes it easy to create completion functions. From ffcc35f6b6190d11b4ac72576e04db5233a3a27a Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Tue, 25 Mar 2014 22:05:59 +0000 Subject: [PATCH 24/73] update --- zsh-completions-howto.org | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 8bb44eb..e5496c1 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -107,6 +107,7 @@ The actions can take one of the following forms: | (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) | +| FUNCTION | Name of a function to call for generating matches or performing some other action, e.g. _files or _message | | {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 @@ -119,20 +120,22 @@ _arguments '--help[show help]' '-?[show help]' '1:First arg:_files' ** Writing 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, e.g. like this: +the parameter name as an argument to _describe. The following example creates completion candidates -c and -d, with +the descriptions. #+BEGIN_SRC sh local -a options options=('-c:description for -c opt' '-d:description for -d opt') _describe 'values' options #+END_SRC -You can use several different lists separated by -- e.g. like this: + +You can use several different lists separated by a double hyphen e.g. like this: #+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 #+END_SRC - +See the [[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-Functions][official documentation]] for more info. ** Writing completion functions using _alternative ** Writing completion functions using _arguments The _arguments function makes it easy to create completion functions. From de8fd3f8bd54057e2aa84918bc1297094ff6fac7 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Tue, 25 Mar 2014 22:07:11 +0000 Subject: [PATCH 25/73] update --- zsh-completions-howto.org | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index e5496c1..b70d22b 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -103,13 +103,13 @@ If you have a very large number of completions you can save them in a cache file 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) | -| FUNCTION | Name of a function to call for generating matches or performing some other action, e.g. _files or _message | -| {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. | +| ( ) | Argument is required but no matches are generated for it. | +| (ITEM1 ITEM2) | List of possible matches | +| ((ITEM1\:DESC1 ITEM2\:DESC2)) | 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) | +| FUNCTION | Name of a function to call for generating matches or performing some other action, e.g. _files or _message | +| {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 From df91dbdc38a54d03897a59dc602ba7227e3a201d Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Tue, 25 Mar 2014 23:18:32 +0000 Subject: [PATCH 26/73] update --- zsh-completions-howto.org | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index b70d22b..7961f38 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -71,9 +71,10 @@ and _describe which are easier to use. 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]]. Examples of how to use these functions are given in the next section. + *** main utility functions for overall completion | _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. | +| _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 | | _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. | @@ -112,11 +113,6 @@ The actions can take one of the following forms: | =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 ** Writing 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 @@ -137,6 +133,20 @@ _describe 'values' options -- arguments #+END_SRC See the [[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-Functions][official documentation]] for more info. ** Writing completion functions using _alternative +This function can be used to perform more sophisticated completion strategies than _describe. + +As arguments it takes a list of specifications each in the form `TAG:DESCR:ACTION' where TAG is a tag name, +DESCR is a description, and ACTION is one of the action types listed previously. +For example: +#+BEGIN_SRC sh +_alternative 'args:custom args:(a b c)' 'interfaces:network interfaces:_net_interfaces' +#+END_SRC +The first specification 'args:custom args:(a b c)' adds completion candidates a, b & c with description +'custom args'. The second specification calls the _net_interfaces command which adds network interfaces as completion +candidates. + + + ** 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, From 43f13964802bf1d865ed4325117047770d0bf6a7 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Tue, 25 Mar 2014 23:18:39 +0000 Subject: [PATCH 27/73] update --- zsh-completions-howto.org | 2 -- 1 file changed, 2 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 7961f38..9a0c8a3 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -145,8 +145,6 @@ The first specification 'args:custom args:(a b c)' adds completion candidates a, 'custom args'. The second specification calls the _net_interfaces command which adds network interfaces as completion candidates. - - ** 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, From 390e7b169f12fef84fe889d4772d738f6a1e1e9a Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Tue, 25 Mar 2014 23:23:15 +0000 Subject: [PATCH 28/73] update --- zsh-completions-howto.org | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 9a0c8a3..f75de94 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -141,9 +141,13 @@ For example: #+BEGIN_SRC sh _alternative 'args:custom args:(a b c)' 'interfaces:network interfaces:_net_interfaces' #+END_SRC -The first specification 'args:custom args:(a b c)' adds completion candidates a, b & c with description -'custom args'. The second specification calls the _net_interfaces command which adds network interfaces as completion -candidates. +The first specification adds completion candidates a, b & c with description 'custom args', and the second specification +calls the _net_interfaces command which adds network interfaces as completion candidates. + +We could 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"))' 'interfaces:network interfaces:_net_interfaces' +#+END_SRC ** Writing completion functions using _arguments The _arguments function makes it easy to create completion functions. From fb42f33c02dbdd32f3e73fd4aef78252fbb34d0a Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Tue, 25 Mar 2014 23:24:55 +0000 Subject: [PATCH 29/73] update --- zsh-completions-howto.org | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index f75de94..793c90d 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -144,9 +144,10 @@ _alternative 'args:custom args:(a b c)' 'interfaces:network interfaces:_net_inte The first specification adds completion candidates a, b & c with description 'custom args', and the second specification calls the _net_interfaces command which adds network interfaces as completion candidates. -We could add descriptions to each of the custom args like this: +We could split the specifications over several lines 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"))' 'interfaces:network interfaces:_net_interfaces' +_alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"description c"))'\ + 'interfaces:network interfaces:_net_interfaces' #+END_SRC ** Writing completion functions using _arguments From 146945ef4a2553056f714f4674e3495e5c91b115 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Tue, 25 Mar 2014 23:25:45 +0000 Subject: [PATCH 30/73] update --- zsh-completions-howto.org | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 793c90d..6e26967 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -144,10 +144,10 @@ _alternative 'args:custom args:(a b c)' 'interfaces:network interfaces:_net_inte The first specification adds completion candidates a, b & c with description 'custom args', and the second specification calls the _net_interfaces command which adds network interfaces as completion candidates. -We could split the specifications over several lines 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 _alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"description c"))'\ - 'interfaces:network interfaces:_net_interfaces' + 'interfaces:network interfaces:_net_interfaces' #+END_SRC ** Writing completion functions using _arguments From 3aa5da2dd50d7ec04fdce0211d39c2300b168c1f Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Tue, 25 Mar 2014 23:51:08 +0000 Subject: [PATCH 31/73] update --- zsh-completions-howto.org | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 6e26967..331d006 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -133,25 +133,42 @@ _describe 'values' options -- arguments #+END_SRC See the [[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-Functions][official documentation]] for more info. ** Writing completion functions using _alternative -This function can be used to perform more sophisticated completion strategies than _describe. +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. As arguments it takes a list of specifications each in the form `TAG:DESCR:ACTION' where TAG is a tag name, DESCR is a description, and ACTION is one of the action types listed previously. For example: #+BEGIN_SRC sh -_alternative 'args:custom args:(a b c)' 'interfaces:network interfaces:_net_interfaces' +_alternative 'args:custom args:(a b c)' 'files:filenames:_files' #+END_SRC -The first specification adds completion candidates a, b & c with description 'custom args', and the second specification -calls the _net_interfaces command which adds network interfaces as completion candidates. +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"))'\ - 'interfaces:network interfaces:_net_interfaces' + 'files:filenames:_files' #+END_SRC +If we want to call _files with arguments we can put it in braces, like this: +#+BEGIN_SRC sh +_alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"description c"))'\ + 'files:filenames:{_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=))" +#+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. + + ** Writing completion functions using _arguments -The _arguments function makes it easy to create completion functions. +With the _arguments function you can create much more sophisticated completion functions As arguments it takes special strings specifying the options & arguments to the function being completed, e.g. like this: #+BEGIN_SRC sh From 79878668e52ae4a2116bb201a06d9637010be985 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 00:26:08 +0000 Subject: [PATCH 32/73] update --- zsh-completions-howto.org | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 331d006..2378991 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -104,16 +104,16 @@ If you have a very large number of completions you can save them in a cache file 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) | List of possible matches | -| ((ITEM1\:DESC1 ITEM2\:DESC2)) | 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) | -| FUNCTION | Name of a function to call for generating matches or performing some other action, e.g. _files or _message | -| {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. | +| ( ) | Argument is required but no matches are generated for it. | +| (ITEM1 ITEM2) | List of possible matches | +| ((ITEM1\:DESC1 ITEM2\:DESC2)) | 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) | +| FUNCTION | Name of a function to call for generating matches or performing some other action, e.g. _files or _message | +| {EVAL-STRING} | Evaluate string as shell code to generate matches. This can be used to call a utility function with arguments, e.g. _values or _describe | +| =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. -** Writing 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 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 @@ -131,7 +131,9 @@ 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 #+END_SRC -See the [[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-Functions][official documentation]] for more info. + +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. @@ -166,9 +168,16 @@ _alternative "dirs:user directories:($userdirs)"\ 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. +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}' +#+END_SRC +The _alternative function can itself be used in an ACTION as part of a specification for _arguments or _regex_arguments. +In this case you will have to put it in braces with its arguments, e.g. 'TAG:DESCRIPTION:{_alternative 'values' options}' ** Writing completion functions using _arguments -With the _arguments function you can create much more sophisticated completion functions +With the _arguments function you can create much more sophisticated completion functions. As arguments it takes special strings specifying the options & arguments to the function being completed, e.g. like this: #+BEGIN_SRC sh From 4775d6edf3ee07d57f9886d3f1086f300b2776c0 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 02:03:20 +0000 Subject: [PATCH 33/73] update --- zsh-completions-howto.org | 41 +++++++++++++++++++++++++-------------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 2378991..40d2482 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -78,7 +78,7 @@ Examples of how to use these functions are given in the next section. | _describe | Used for creating simple completions consisting of single 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 +*** functions for performing complex individual completions | _values | Used for completing arbitrary keywords (values) and their arguments, or comma separated lists of such combinations. | | _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 | @@ -104,13 +104,13 @@ If you have a very large number of completions you can save them in a cache file 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) | List of possible matches | -| ((ITEM1\:DESC1 ITEM2\:DESC2)) | 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) | -| FUNCTION | Name of a function to call for generating matches or performing some other action, e.g. _files or _message | -| {EVAL-STRING} | Evaluate string as shell code to generate matches. This can be used to call a utility function with arguments, e.g. _values or _describe | -| =ACTION | Inserts a dummy word into completion command line without changing the point at which completion takes place. | +| ( ) | Argument is required but no matches are generated for it. | +| (ITEM1 ITEM2) | List of possible matches | +| ((ITEM1\:'DESC1' ITEM2\:'DESC2')) | List of possible matches, with descriptions. Make sure to use different quotes than those around the whole specification. | +| ->STRING | Set $state to STRING and continue ($state can be checked in a case statement after the utility function call) | +| FUNCTION | Name of a function to call for generating matches or performing some other action, e.g. _files or _message | +| {EVAL-STRING} | Evaluate string as shell code to generate matches. This can be used to call a utility function with arguments, e.g. _values or _describe | +| =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. ** Writing simple completion functions using _describe @@ -138,8 +138,8 @@ In this case you will have to put it in braces with its arguments, e.g. 'TAG:DES 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. -As arguments it takes a list of specifications each in the form `TAG:DESCR:ACTION' where TAG is a tag name, -DESCR is a description, and ACTION is one of the action types listed previously. +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). For example: #+BEGIN_SRC sh _alternative 'args:custom args:(a b c)' 'files:filenames:_files' @@ -174,10 +174,20 @@ _alternative "dirs:user directories:($userdirs)"\ 'opts:comma separated opts:{_values -s , a b c}' #+END_SRC -The _alternative function can itself be used in an ACTION as part of a specification for _arguments or _regex_arguments. -In this case you will have to put it in braces with its arguments, e.g. 'TAG:DESCRIPTION:{_alternative 'values' options}' +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 much more sophisticated completion functions. +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), +or command arguments. +Basic option specifications take the form '-OPT[DESCRIPTION]'. Arguments for the option can be specified after the option +description like this '-OPT[DESCRIPTION]:MESSAGE1:ACTION1:MESSAGE2:ACTION2' where MESSAGE1 & MESSAGE2 are the messages +printed for the first and second args, and ACTION1 & ACTION2 determine how the completion candidates for those args +are determined (see the ACTIONS section above). + + + As arguments it takes special strings specifying the options & arguments to the function being completed, e.g. like this: #+BEGIN_SRC sh @@ -207,9 +217,10 @@ If the default keybindings don't work you can try pressing Alt+x and then enter | _complete_help | Ctrl+x h | displays information about context names, tags, and completion functions used when completing at the current cursor position | | _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 | -* Gotchas -Take care to use the correct type of quotes around 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. +* Gotchas (things to watch out for) +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, +and make sure to use different quotes around item descriptions. * 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, From e865f3e2207ec3550dc63c5b58ba28fd596ab8e9 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 02:21:27 +0000 Subject: [PATCH 34/73] update --- zsh-completions-howto.org | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 40d2482..289a46c 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -173,6 +173,7 @@ We can use other utility functions such as _values in the ACTION to perform more _alternative "dirs:user directories:($userdirs)"\ 'opts:comma separated opts:{_values -s , a b c}' #+END_SRC +this will complete the items in $userdirs, aswell as a comma separated list containing a, b &/or c. As with _describe, the _alternative function can itself be used in an ACTION as part of a specification for _arguments or _regex_arguments. @@ -181,10 +182,18 @@ With the _arguments function you can create much more sophisticated completion f 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), or command arguments. -Basic option specifications take the form '-OPT[DESCRIPTION]'. Arguments for the option can be specified after the option -description like this '-OPT[DESCRIPTION]:MESSAGE1:ACTION1:MESSAGE2:ACTION2' where MESSAGE1 & MESSAGE2 are the messages -printed for the first and second args, and ACTION1 & ACTION2 determine how the completion candidates for those args -are determined (see the ACTIONS section above). +Basic option specifications take the form '-OPT[DESCRIPTION]', e.g. like this: +#+BEGIN_SRC sh +_arguments '-s[sort output]' '--l[long output]' '-l[long output]' +#+END_SRC +Arguments for the option can be specified after the option description like this '-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. +For example: +#+BEGIN_SRC sh +_arguments '-f[input file]:filename:_files' +#+END_SRC + + From 48553f56d180ed9f1b2a07549fbe3a8ad7bd7050 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 02:21:58 +0000 Subject: [PATCH 35/73] update --- zsh-completions-howto.org | 1 + 1 file changed, 1 insertion(+) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 289a46c..2182698 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -182,6 +182,7 @@ With the _arguments function you can create much more sophisticated completion f 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), or command arguments. + Basic option specifications take the form '-OPT[DESCRIPTION]', e.g. like this: #+BEGIN_SRC sh _arguments '-s[sort output]' '--l[long output]' '-l[long output]' From 92178ce8519ff1cd76f950c0970052fec86d9eda Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 02:22:58 +0000 Subject: [PATCH 36/73] update --- zsh-completions-howto.org | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 2182698..5a71570 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -187,7 +187,7 @@ Basic option specifications take the form '-OPT[DESCRIPTION]', e.g. like this: #+BEGIN_SRC sh _arguments '-s[sort output]' '--l[long output]' '-l[long output]' #+END_SRC -Arguments for the option can be specified after the option description like this '-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. For example: #+BEGIN_SRC sh From 6a77cbd36fa73e97a86c2f07785c95ae193d00fc Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 02:30:49 +0000 Subject: [PATCH 37/73] update --- zsh-completions-howto.org | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 5a71570..41bcac5 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -194,6 +194,18 @@ For example: _arguments '-f[input file]:filename:_files' #+END_SRC +| -OPT | single option | +| +OPT | single option beginning with + | +| -+OPT | single option beginning with + or - | +| +-OPT | single option beginning with + or - | +| {-OPT1,--OPT2} | list of alternatives for an option (e.g. short & long forms). This is not a different specification but a trick that relies on braces expansion. | +| -OPT- | indicates the argument of the option must come directly after the option name, e.g. -optARG | +| -OPT+ | indicates the argument of the option may come directly after the option or as a separate word, e.g. -optARG or -opt ARG | +| -OPT= | indicates the argument of the option may come as a separate word, or separated from the option with an = sign, e.g. -opt=ARG or -opt ARG | +| -OPT=- | indicates the argument of the option must appear after an = sign, not as a separate word | +| OPTSPEC[explanation] | the explanation string will be displayed along with the option (OPTSPEC is any of the previously mentioned option specifications) | +| *OPTSPEC | indicates that the option may be repeated (OPTSPEC is any of the previously mentioned option specifications) | +| OPTSPEC:ARG1:ARG2:etc | for specifying options that take arguments (see below for option argument specification) | From 193a9643f33a70babe7b79cff89e04c4d0138adb Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 02:35:06 +0000 Subject: [PATCH 38/73] update --- zsh-completions-howto.org | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 41bcac5..57da55e 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -194,18 +194,17 @@ For example: _arguments '-f[input file]:filename:_files' #+END_SRC -| -OPT | single option | -| +OPT | single option beginning with + | -| -+OPT | single option beginning with + or - | -| +-OPT | single option beginning with + or - | -| {-OPT1,--OPT2} | list of alternatives for an option (e.g. short & long forms). This is not a different specification but a trick that relies on braces expansion. | -| -OPT- | indicates the argument of the option must come directly after the option name, e.g. -optARG | -| -OPT+ | indicates the argument of the option may come directly after the option or as a separate word, e.g. -optARG or -opt ARG | -| -OPT= | indicates the argument of the option may come as a separate word, or separated from the option with an = sign, e.g. -opt=ARG or -opt ARG | -| -OPT=- | indicates the argument of the option must appear after an = sign, not as a separate word | -| OPTSPEC[explanation] | the explanation string will be displayed along with the option (OPTSPEC is any of the previously mentioned option specifications) | -| *OPTSPEC | indicates that the option may be repeated (OPTSPEC is any of the previously mentioned option specifications) | -| OPTSPEC:ARG1:ARG2:etc | for specifying options that take arguments (see below for option argument specification) | +Command argument specifications take the form 'N:MESSAGE:ACTION' where N indicates that it is the Nth command argument, +and MESSAGE & ACTION are as before. If the N is omitted then it just means the next command argument (after any that have +already been specified). For example: +#+BEGIN_SRC sh +_arguments '-s[sort output]' '1:first arg:_net_interfaces' +#+END_SRC + + + + + From 754ed8aad3ad39eafca7842f68af1dddb8c68718 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 03:01:52 +0000 Subject: [PATCH 39/73] update --- zsh-completions-howto.org | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 57da55e..0b7e025 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -196,13 +196,16 @@ _arguments '-f[input file]:filename:_files' Command argument specifications take the form 'N:MESSAGE:ACTION' where N indicates that it is the Nth command argument, and MESSAGE & ACTION are as before. If the N is omitted then it just means the next command argument (after any that have -already been specified). For example: +already been specified). If a double colon is used at the start (after N) then the argument is optional. +For example: #+BEGIN_SRC sh -_arguments '-s[sort output]' '1:first arg:_net_interfaces' +_arguments '-s[sort output]' '1:first arg:_net_interfaces' '::optional arg:_files' ':next arg:(a b c)' #+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, +and the -s option may be completed at any position. - - +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]]. From 128e5e7d85078edffe484bf64831f2c10f5b25c0 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 15:39:18 +0000 Subject: [PATCH 40/73] update --- zsh-completions-howto.org | 40 +++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 0b7e025..42d7bf8 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -78,7 +78,7 @@ Examples of how to use these functions are given in the next section. | _describe | Used for creating simple completions consisting of single 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 individual completions +*** functions for performing complex completions of single words | _values | Used for completing arbitrary keywords (values) and their arguments, or comma separated lists of such combinations. | | _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 | @@ -204,27 +204,27 @@ _arguments '-s[sort output]' '1:first arg:_net_interfaces' '::optional arg:_file 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, 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. +This means that you can use actions for selecting case statement branches like this: +#+BEGIN_SRC sh +_arguments '-m[music file]:filename:->files' '-f[flags]:flag:->flags' +case "$state" in + files) + local -a music_files + music_files=( Music/**/*.{mp3,wav,flac,ogg} ) + _multi_parts / music_files + ;; + flags) + _values -s , 'flags' a b c d e + ;; +esac +#+END_SRC +In this case paths to music files are completed stepwise descending down directories using the _multi_parts 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, 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]]. - - - - - - -As arguments it takes special strings specifying the options & arguments to the function being completed, -e.g. like this: -#+BEGIN_SRC sh -_arguments '--help[show help]' '-?[show help]' '1:First arg:_files' -#+END_SRC -This example completes the options --help & -? when trying to complete a hyphen, which will both be listed together -with the same description in this case. The first non-option argument is completed using the _files function which -completes file/directories. - -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]]. - +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 *** Patterns * Testing & debugging From 330c97d24dde804713971243d80e33f146227c3e Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 18:23:21 +0000 Subject: [PATCH 41/73] update --- zsh-completions-howto.org | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 42d7bf8..e5823ba 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -178,7 +178,7 @@ this will complete the items in $userdirs, aswell as a comma separated list cont 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 much more sophisticated completion functions. +With the _arguments function you can create more sophisticated completion functions. 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), or command arguments. @@ -226,6 +226,27 @@ I have just given you the basics of _arguments specifications here, you can also 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]]. 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. + +_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, +e.g. like this: +#+BEGIN_SRC sh +_regex_arguments _cmd OTHER_ARGS.. +_cmd "$@" +#+END_SRC + +The OTHER_ARGS should be sequences of specifications for matching & completing sequences of words on the command line. +These sequences can be separated by '|' to represent alternative command line specifications, and you can use +bracketing to arbitrary depth to specify alternate subsequences. +For example: +#+BEGIN_SRC sh +_regex_arguments SEQ1 '|' SEQ2 \( SEQ2a '|' SEQ2b \) +#+END_SRC +this specifies a command line matching either SEQ1, or SEQ2 followed by SEQ2a or SEQ2b. + + *** Patterns * Testing & debugging To reload a completion function: From 1ac268ecc91a9e2df39da7e8acda0d757bc1378e Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 19:06:05 +0000 Subject: [PATCH 42/73] update --- zsh-completions-howto.org | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index e5823ba..b8030ed 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -237,15 +237,21 @@ _regex_arguments _cmd OTHER_ARGS.. _cmd "$@" #+END_SRC -The OTHER_ARGS should be sequences of specifications for matching & completing sequences of words on the command line. -These sequences can be separated by '|' to represent alternative command line specifications, and you can use -bracketing to arbitrary depth to specify alternate subsequences. +The OTHER_ARGS should be sequences of specifications for matching & completing words on the command line. +These sequences can be separated by '|' to represent alternative sequences of words. +You can use bracketing to arbitrary depth to specify alternate subsequences. For example: #+BEGIN_SRC sh _regex_arguments SEQ1 '|' SEQ2 \( SEQ2a '|' SEQ2b \) #+END_SRC this specifies a command line matching either SEQ1, or SEQ2 followed by SEQ2a or SEQ2b. +A specification in a sequence can take the form: /PATTERN/ ':TAG:DESCR:ACTION' +The ':TAG:DESCR:ACTION' part is the same as for the _alternative function (see above), and specifies how to complete +the word on the command line corresponding to that position. +The PATTERN is a regular expression to match the word after it has been completed. +The start of the command line matching PATTERN is then removed before moving on to the next specification (which will +then be matched against the remaining command line). *** Patterns * Testing & debugging From ec9062e0206ee850d4588ea0f0b97755d9043ed7 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 19:08:02 +0000 Subject: [PATCH 43/73] update --- zsh-completions-howto.org | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index b8030ed..25f22aa 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -246,7 +246,7 @@ _regex_arguments SEQ1 '|' SEQ2 \( SEQ2a '|' SEQ2b \) #+END_SRC this specifies a command line matching either SEQ1, or SEQ2 followed by SEQ2a or SEQ2b. -A specification in a sequence can take the form: /PATTERN/ ':TAG:DESCR:ACTION' +A specification in a sequence can take the form: \/PATTERN\/ ':TAG:DESCR:ACTION' The ':TAG:DESCR:ACTION' part is the same as for the _alternative function (see above), and specifies how to complete the word on the command line corresponding to that position. The PATTERN is a regular expression to match the word after it has been completed. From 071dae8b6846107ec60d1e75778e206e538907ca Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 19:09:12 +0000 Subject: [PATCH 44/73] update --- zsh-completions-howto.org | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 25f22aa..474f4d2 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -246,8 +246,8 @@ _regex_arguments SEQ1 '|' SEQ2 \( SEQ2a '|' SEQ2b \) #+END_SRC this specifies a command line matching either SEQ1, or SEQ2 followed by SEQ2a or SEQ2b. -A specification in a sequence can take the form: \/PATTERN\/ ':TAG:DESCR:ACTION' -The ':TAG:DESCR:ACTION' part is the same as for the _alternative function (see above), and specifies how to complete +A specification in a sequence can take the form: ~/PATTERN/ ':TAG:DESCR:ACTION'~ +The ~':TAG:DESCR:ACTION'~ part is the same as for the _alternative function (see above), and specifies how to complete the word on the command line corresponding to that position. The PATTERN is a regular expression to match the word after it has been completed. The start of the command line matching PATTERN is then removed before moving on to the next specification (which will From 2762c687ab088807d7313902077458c959489b02 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 19:10:08 +0000 Subject: [PATCH 45/73] update --- zsh-completions-howto.org | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 474f4d2..f071153 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -246,8 +246,8 @@ _regex_arguments SEQ1 '|' SEQ2 \( SEQ2a '|' SEQ2b \) #+END_SRC this specifies a command line matching either SEQ1, or SEQ2 followed by SEQ2a or SEQ2b. -A specification in a sequence can take the form: ~/PATTERN/ ':TAG:DESCR:ACTION'~ -The ~':TAG:DESCR:ACTION'~ part is the same as for the _alternative function (see above), and specifies how to complete +A specification in a sequence can take the form: / PATTERN / ':TAG:DESCR:ACTION' +The ':TAG:DESCR:ACTION' part is the same as for the _alternative function (see above), and specifies how to complete the word on the command line corresponding to that position. The PATTERN is a regular expression to match the word after it has been completed. The start of the command line matching PATTERN is then removed before moving on to the next specification (which will From 9849b69a9429a183158b116d4865d21775260ec9 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 19:10:33 +0000 Subject: [PATCH 46/73] update --- zsh-completions-howto.org | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index f071153..d19b1fc 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -246,7 +246,7 @@ _regex_arguments SEQ1 '|' SEQ2 \( SEQ2a '|' SEQ2b \) #+END_SRC this specifies a command line matching either SEQ1, or SEQ2 followed by SEQ2a or SEQ2b. -A specification in a sequence can take the form: / PATTERN / ':TAG:DESCR:ACTION' +A specification in a sequence can take the form: / PATTERN / ':TAG:DESCR:ACTION'\ The ':TAG:DESCR:ACTION' part is the same as for the _alternative function (see above), and specifies how to complete the word on the command line corresponding to that position. The PATTERN is a regular expression to match the word after it has been completed. From e1aa5c21c4f0c26539160ccd7420f687e5a93e74 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 19:12:36 +0000 Subject: [PATCH 47/73] update --- zsh-completions-howto.org | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index d19b1fc..aabae7a 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -246,7 +246,8 @@ _regex_arguments SEQ1 '|' SEQ2 \( SEQ2a '|' SEQ2b \) #+END_SRC this specifies a command line matching either SEQ1, or SEQ2 followed by SEQ2a or SEQ2b. -A specification in a sequence can take the form: / PATTERN / ':TAG:DESCR:ACTION'\ +A specification in a sequence can take the form: / PATTERN / ':TAG:DESCR:ACTION' + The ':TAG:DESCR:ACTION' part is the same as for the _alternative function (see above), and specifies how to complete the word on the command line corresponding to that position. The PATTERN is a regular expression to match the word after it has been completed. From 52b79ab52ea1719b275493c8b397c58d40c49724 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 19:13:32 +0000 Subject: [PATCH 48/73] update --- zsh-completions-howto.org | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index aabae7a..52f4ffb 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -246,7 +246,7 @@ _regex_arguments SEQ1 '|' SEQ2 \( SEQ2a '|' SEQ2b \) #+END_SRC this specifies a command line matching either SEQ1, or SEQ2 followed by SEQ2a or SEQ2b. -A specification in a sequence can take the form: / PATTERN / ':TAG:DESCR:ACTION' +A specification in a sequence can take the form: / PATTERN / ':TAG:DESCR:ACTION' The ':TAG:DESCR:ACTION' part is the same as for the _alternative function (see above), and specifies how to complete the word on the command line corresponding to that position. From 8f01a317592b3e3a9f1be297cae4f1cf6692181d Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 19:36:02 +0000 Subject: [PATCH 49/73] update --- zsh-completions-howto.org | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 52f4ffb..8a5697f 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -246,7 +246,7 @@ _regex_arguments SEQ1 '|' SEQ2 \( SEQ2a '|' SEQ2b \) #+END_SRC this specifies a command line matching either SEQ1, or SEQ2 followed by SEQ2a or SEQ2b. -A specification in a sequence can take the form: / PATTERN / ':TAG:DESCR:ACTION' +A specification in a sequence can take the form: / PATTERN/ ':TAG:DESCR:ACTION' The ':TAG:DESCR:ACTION' part is the same as for the _alternative function (see above), and specifies how to complete the word on the command line corresponding to that position. From fdb2079002c9a652e01996a81f97080ae7dfe9d4 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Wed, 26 Mar 2014 19:47:01 +0000 Subject: [PATCH 50/73] update --- zsh-completions-howto.org | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 8a5697f..b999f93 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -249,12 +249,16 @@ this specifies a command line matching either SEQ1, or SEQ2 followed by SEQ2a or A specification in a sequence can take the form: / PATTERN/ ':TAG:DESCR:ACTION' The ':TAG:DESCR:ACTION' part is the same as for the _alternative function (see above), and specifies how to complete -the word on the command line corresponding to that position. -The PATTERN is a regular expression to match the word after it has been completed. +the corresponding word on the command line. +The PATTERN is a regular expression to match the word after it has been completed (see below for more details). The start of the command line matching PATTERN is then removed before moving on to the next specification (which will then be matched against the remaining command line). +If this sounds complicated that's because it is. A simpler alternative is to use the _regex_words function for creating +specifications for _regex_arguments. + *** Patterns +Note * Testing & debugging To reload a completion function: #+BEGIN_SRC sh From 3b777e258a2cdf14dd69e1ba8b40a852f548d535 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 02:52:07 +0000 Subject: [PATCH 51/73] update --- zsh-completions-howto.org | 45 +++++++++++++++++++++++++++++---------- 1 file changed, 34 insertions(+), 11 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index b999f93..0f8ba46 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -117,8 +117,9 @@ _regex_arguments or _alternative functions. 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 descriptions. +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 @@ -126,6 +127,7 @@ _describe 'values' options You can use several different lists separated by a double hyphen e.g. like this: #+BEGIN_SRC sh +#compdef cmd 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') @@ -138,10 +140,11 @@ In this case you will have to put it in braces with its arguments, e.g. 'TAG:DES 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. -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 tag name, DESCRIPTION is a description, and ACTION is one of the action types listed previously (apart from the ->STRING and =ACTION forms). For example: #+BEGIN_SRC sh +#compdef cmd _alternative 'args:custom args:(a b c)' 'files:filenames:_files' #+END_SRC The first specification adds completion candidates a, b & c, and the second specification calls the _files function @@ -149,12 +152,14 @@ 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 +#compdef cmd _alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"description c"))'\ 'files:filenames:_files' #+END_SRC If we want to call _files with arguments we can put it in braces, like this: #+BEGIN_SRC sh +#compdef cmd _alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"description c"))'\ 'files:filenames:{_files -/}' #+END_SRC @@ -162,6 +167,7 @@ _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, e.g: #+BEGIN_SRC sh +#compdef cmd _alternative "dirs:user directories:($userdirs)"\ "pids:process IDs:($(ps -A o pid=))" #+END_SRC @@ -170,6 +176,7 @@ 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: #+BEGIN_SRC sh +#compdef cmd _alternative "dirs:user directories:($userdirs)"\ 'opts:comma separated opts:{_values -s , a b c}' #+END_SRC @@ -185,12 +192,14 @@ or command arguments. Basic option specifications take the form '-OPT[DESCRIPTION]', e.g. like this: #+BEGIN_SRC sh +#compdef cmd _arguments '-s[sort output]' '--l[long output]' '-l[long output]' #+END_SRC 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. For example: #+BEGIN_SRC sh +#compdef cmd _arguments '-f[input file]:filename:_files' #+END_SRC @@ -199,6 +208,7 @@ 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. For example: #+BEGIN_SRC sh +#compdef cmd _arguments '-s[sort output]' '1:first arg:_net_interfaces' '::optional arg:_files' ':next arg:(a b c)' #+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, @@ -206,7 +216,8 @@ 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. 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' case "$state" in files) @@ -233,6 +244,7 @@ _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, e.g. like this: #+BEGIN_SRC sh +#compdef cmd _regex_arguments _cmd OTHER_ARGS.. _cmd "$@" #+END_SRC @@ -242,19 +254,28 @@ These sequences can be separated by '|' to represent alternative sequences of wo You can use bracketing to arbitrary depth to specify alternate subsequences. For example: #+BEGIN_SRC sh -_regex_arguments SEQ1 '|' SEQ2 \( SEQ2a '|' SEQ2b \) +#compdef cmd +_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. -A specification in a sequence can take the form: / PATTERN/ ':TAG:DESCR:ACTION' +Each specification in a sequence must contain a / PATTERN/ part at the start followed by an optional ':TAG:DESCRIPTION:ACTION' +part. Each PATTERN is a regular expression to match a word on the command line. These patterns are processed sequentially +until we reach a pattern that doesn't match at which point any corresponding ACTION is performed to obtain completions +for that word. Note that there needs to be a pattern to match the initial command itself. +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. -The ':TAG:DESCR:ACTION' part is the same as for the _alternative function (see above), and specifies how to complete -the corresponding word on the command line. -The PATTERN is a regular expression to match the word after it has been completed (see below for more details). -The start of the command line matching PATTERN is then removed before moving on to the next specification (which will -then be matched against the remaining command line). +Here is an example +#+BEGIN_SRC sh +#compdef cmd +_regex_arguments _cmd /$'[^\0]##\0'/ /$'[^\0]##\0'/ 'file:filename:_files' '|' /$'word2\0'/ 'file:filename:_files' \ + \( /$'word1\0'/ 'file:filename:_files' '|' /$'word1\0'/ 'file:filename:_files' \) +_cmd "$@" +#+END_SRC -If this sounds complicated that's because it is. A simpler alternative is to use the _regex_words function for creating +If this sounds too complicated a simpler alternative is to use the _regex_words function for creating specifications for _regex_arguments. *** Patterns @@ -277,6 +298,8 @@ If the default keybindings don't work you can try pressing Alt+x and then enter 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, and make sure to use different quotes around item descriptions. + +Remember to include an initial pattern to match the command word when using _regex_arguments (it does not need a matching action). * 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, From b69f5b9d96f193cceafdccda7d16a3819830a7fc Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 13:40:25 +0000 Subject: [PATCH 52/73] update --- zsh-completions-howto.org | 34 +++++++++++++++------------------- 1 file changed, 15 insertions(+), 19 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 0f8ba46..c154b70 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -127,7 +127,6 @@ _describe 'values' options You can use several different lists separated by a double hyphen e.g. like this: #+BEGIN_SRC sh -#compdef cmd 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') @@ -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). For example: #+BEGIN_SRC sh -#compdef cmd _alternative 'args:custom args:(a b c)' 'files:filenames:_files' #+END_SRC 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: #+BEGIN_SRC sh -#compdef cmd _alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"description c"))'\ 'files:filenames:_files' #+END_SRC If we want to call _files with arguments we can put it in braces, like this: #+BEGIN_SRC sh -#compdef cmd _alternative 'args:custom args:((a\:"description a" b\:"description b" c\:"description c"))'\ 'files:filenames:{_files -/}' #+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, e.g: #+BEGIN_SRC sh -#compdef cmd _alternative "dirs:user directories:($userdirs)"\ "pids:process IDs:($(ps -A o pid=))" #+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: #+BEGIN_SRC sh -#compdef cmd _alternative "dirs:user directories:($userdirs)"\ 'opts:comma separated opts:{_values -s , a b c}' #+END_SRC @@ -192,14 +186,12 @@ or command arguments. Basic option specifications take the form '-OPT[DESCRIPTION]', e.g. like this: #+BEGIN_SRC sh -#compdef cmd _arguments '-s[sort output]' '--l[long output]' '-l[long output]' #+END_SRC 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. For example: #+BEGIN_SRC sh -#compdef cmd _arguments '-f[input file]:filename:_files' #+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. For example: #+BEGIN_SRC sh -#compdef cmd _arguments '-s[sort output]' '1:first arg:_net_interfaces' '::optional arg:_files' ':next arg:(a b c)' #+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, @@ -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. This means that you can use actions for selecting case statement branches like this: #+BEGIN_SRC sh -#compdef cmd _arguments '-m[music file]:filename:->files' '-f[flags]:flag:->flags' case "$state" in 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, e.g. like this: #+BEGIN_SRC sh -#compdef cmd _regex_arguments _cmd OTHER_ARGS.. _cmd "$@" #+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. For example: #+BEGIN_SRC sh -#compdef cmd _regex_arguments _cmd SEQ1 '|' SEQ2 \( SEQ2a '|' SEQ2b \) _cmd "$@" #+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, 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 -#compdef cmd -_regex_arguments _cmd /$'[^\0]##\0'/ /$'[^\0]##\0'/ 'file:filename:_files' '|' /$'word2\0'/ 'file:filename:_files' \ - \( /$'word1\0'/ 'file:filename:_files' '|' /$'word1\0'/ 'file:filename:_files' \) +_regex_arguments _hello /$'[^\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 "$@" #+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 much simpler alternative is to use the _regex_words function for creating +specifications for _regex_arguments. +*** _regex_words + + -If this sounds too complicated a simpler alternative is to use the _regex_words function for creating -specifications for _regex_arguments. *** Patterns -Note +Note * = wildcard, # = wildcard * Testing & debugging To reload a completion function: #+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_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) +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: 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. From 57886bb812a9e8619393c4f43da5be44d1befd6a Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 14:10:22 +0000 Subject: [PATCH 53/73] update --- zsh-completions-howto.org | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index c154b70..40e4583 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -268,6 +268,31 @@ word is allowed which can be word2 followed by and a, b, or c, or a filename. If this sounds too complicated a much simpler alternative is to use the _regex_words function for creating specifications for _regex_arguments. *** _regex_words +The _regex_words function makes it much easier to create specifications for _regex_arguments. +The results of calling _regex_words can be stored in a variable which can then be used instead +of a specification for _regex_arguments. + +To create a specification using _regex_words you supply it with a tag followed by a description followed by a list +of specifications for individual words. These specifications take the form 'WORD:DESCRIPTION:SPEC' where WORD is the +word to be completed, DESCRIPTION is a description for it, and SPEC can be another variable created by _regex_words +specifying words that come after the current word or blank if there are no further words. +For example: +#+BEGIN_SRC sh +_regex_words firstword 'The first word' 'word1a:a word:' 'word1b:b word:' 'word1c:c word' +#+END_SRC +the results of this function call will be stored in the $reply array, and so we should store it in another array +before $reply gets changed again, like this: +#+BEGIN_SRC sh +local -a firstword +_regex_words word 'The first word' 'word1a:a word:' 'word1b:b word:' 'word1c:c word' +firstword="$reply[@]" +#+END_SRC +we could then use it with _regex_arguments like this: +#+BEGIN_SRC sh +_regex_arguments _cmd /$'[^\0]##\0'/ "$firstword[@]" +#+END_SRC +Note that I have added an extra pattern for the initial command word itself. + From 90d9164d6c06dd351a1666aafeb340e21c48a172 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 14:13:54 +0000 Subject: [PATCH 54/73] update --- zsh-completions-howto.org | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 40e4583..8c69a0e 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -240,7 +240,9 @@ _cmd "$@" The OTHER_ARGS should be sequences of specifications for matching & completing words on the command line. These sequences can be separated by '|' to represent alternative sequences of words. -You can use bracketing to arbitrary depth to specify alternate subsequences. +You can use bracketing to arbitrary depth to specify alternate subsequences, but the brackets must be quoted +like this \( \) or '(' ')'. + For example: #+BEGIN_SRC sh _regex_arguments _cmd SEQ1 '|' SEQ2 \( SEQ2a '|' SEQ2b \) From 15f97eb949a50ee96d77b7fb57e8fd9f16924779 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 14:25:54 +0000 Subject: [PATCH 55/73] update --- zsh-completions-howto.org | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 8c69a0e..c907044 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -240,8 +240,8 @@ _cmd "$@" The OTHER_ARGS should be sequences of specifications for matching & completing words on the command line. These sequences can be separated by '|' to represent alternative sequences of words. -You can use bracketing to arbitrary depth to specify alternate subsequences, but the brackets must be quoted -like this \( \) or '(' ')'. +You can use bracketing to arbitrary depth to specify alternate subsequences, but the brackets must be backslashed like this \( \) +or quoted like this '(' ')'. For example: #+BEGIN_SRC sh From c5615eeab14e8db8689e48a65b425b6843af7239 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 14:39:47 +0000 Subject: [PATCH 56/73] update --- zsh-completions-howto.org | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index c907044..58b7563 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -292,9 +292,23 @@ firstword="$reply[@]" we could then use it with _regex_arguments like this: #+BEGIN_SRC sh _regex_arguments _cmd /$'[^\0]##\0'/ "$firstword[@]" +_cmd "$@" #+END_SRC Note that I have added an extra pattern for the initial command word itself. +Here is a more complex example where we call _regex_words for different words on the command line +#+BEGIN_SRC sh +local -a firstword firstword2 secondword secondword2 +_regex_words word 'The first word' 'word1a:a word:' 'word1b:b word:' 'word1c:c word' +firstword="$reply[@]" +_regex_words word 'Another first word' 'word11a:1a word:$secondword' 'word11b:1b word:$secondword' 'word11c:1c word:$secondword2' +firstword2="$reply[@]" +_regex_words word 'The second word' 'word2a:a word' 'word2b:b word' 'word2c:c word' +secondword="$reply[@]" +_regex_words word 'Another second word' 'word22a:2a word' 'word22b:2b word' 'word22c:2c word' +secondword2="$reply[@]" +#+END_SRC + From 7abd7c5999f81aa39ca4995367f49ca33523e5e8 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 14:43:59 +0000 Subject: [PATCH 57/73] update --- zsh-completions-howto.org | 1 + 1 file changed, 1 insertion(+) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 58b7563..3544f36 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -7,6 +7,7 @@ give enough information and examples to get you up and running. If you need more [[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]]). +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 Completion functions for commands are stored in files with names beginning with an underscore _, and these files should From dff3fe6d571ba2669fff72a522264948e92a6653 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 15:44:34 +0000 Subject: [PATCH 58/73] update --- zsh-completions-howto.org | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 3544f36..37c4161 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -300,14 +300,18 @@ Note that I have added an extra pattern for the initial command word itself. Here is a more complex example where we call _regex_words for different words on the command line #+BEGIN_SRC sh local -a firstword firstword2 secondword secondword2 -_regex_words word 'The first word' 'word1a:a word:' 'word1b:b word:' 'word1c:c word' -firstword="$reply[@]" -_regex_words word 'Another first word' 'word11a:1a word:$secondword' 'word11b:1b word:$secondword' 'word11c:1c word:$secondword2' -firstword2="$reply[@]" -_regex_words word 'The second word' 'word2a:a word' 'word2b:b word' 'word2c:c word' -secondword="$reply[@]" -_regex_words word 'Another second word' 'word22a:2a word' 'word22b:2b word' 'word22c:2c word' -secondword2="$reply[@]" +_regex_words word1 'The second word' 'woo:tang clan' 'hoo:not me' +secondword=("$reply[@]") +_regex_words word2 'Another second word' 'yee:thou' 'haa:very funny!' +secondword2=("$reply[@]") +_regex_words commands 'The first word' 'foo:do foo' 'man:yeah man' 'chu:at chu' +firstword=("$reply[@]") +_regex_words word4 'Another first word' 'boo:scare somebody:$secondword' 'ga:baby noise:$secondword'\ + 'loo:go to the toilet:$secondword2' +firstword2=("$reply[@]") + +_regex_arguments _hello /$'[^\0]##\0'/ "${firstword[@]}" "${firstword2[@]}" +_hello "$@" #+END_SRC @@ -337,6 +341,9 @@ Take care to use the correct type of quoting for specifications to _arguments or 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. +Check that you have the correct number of :'s in the correct places for specifications for _arguments, +_alternative, _regex_arguments, etc. + Remember to include an initial pattern to match the command word when using _regex_arguments (it does not need a matching action). * Putting it all together * Other resources From d98035be05e1fd18ec3c7a1ae85ca676620d9602 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 16:21:24 +0000 Subject: [PATCH 59/73] update --- zsh-completions-howto.org | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 37c4161..279e839 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -68,13 +68,15 @@ The compadd builtin is the core function used to add completion words to the com However, most of the time you will not need to use compadd, since there are many utility functions such as _arguments and _describe which are easier to use. +For very basic completions the _describe function should be adequate + ** 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]]. Examples of how to use these functions are given in the next section. *** main utility functions for overall completion -| _alternative | Loop over tag labels and perform actions based on matching tag label. | +| _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 | | _gnu_generic | Can be used to complete options for commands that understand the `--help' option. | @@ -313,11 +315,10 @@ firstword2=("$reply[@]") _regex_arguments _hello /$'[^\0]##\0'/ "${firstword[@]}" "${firstword2[@]}" _hello "$@" #+END_SRC - - - - - +In this case the first word can be one of "foo", "man", "chu", "boo", "ga" or "loo". +If the first word is "boo" or "ga" then the second word can be "woo" or "hoo", +and if the first word is "loo" then the second word can be "yee" or "haa", in the other +cases there is no second word. *** Patterns Note * = wildcard, # = wildcard * Testing & debugging From aaca6eddc2fcd25e98ba9c8f6f43564d347f4304 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 17:08:30 +0000 Subject: [PATCH 60/73] update --- zsh-completions-howto.org | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 279e839..44b939a 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -257,7 +257,9 @@ Each specification in a sequence must contain a / PATTERN/ part at the start fol part. Each PATTERN is a regular expression to match a word on the command line. These patterns are processed sequentially until we reach a pattern that doesn't match at which point any corresponding ACTION is performed to obtain completions for that word. Note that there needs to be a pattern to match the initial command itself. -Note that the ':TAG:DESCRIPTION:ACTION' part is interpreted in the same way as for the _alternative function specifications, +See below for further explanation about PATTERNs. + +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. Here is an example: @@ -320,7 +322,11 @@ If the first word is "boo" or "ga" then the second word can be "woo" or "hoo", and if the first word is "loo" then the second word can be "yee" or "haa", in the other cases there is no second word. *** Patterns -Note * = wildcard, # = wildcard +The following patterns can be used. +| * | wildcard - any number of chars | +| ? | wildcard - single char | +| # | zero or more of the previous char | +| ## | one or more of the previous char | * Testing & debugging To reload a completion function: #+BEGIN_SRC sh From 932381030752774ba7114b9e889129412898bdd4 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 17:09:45 +0000 Subject: [PATCH 61/73] update --- zsh-completions-howto.org | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 44b939a..5ff5244 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -254,7 +254,9 @@ _cmd "$@" this specifies a command line matching either SEQ1, or SEQ2 followed by SEQ2a or SEQ2b. Each specification in a sequence must contain a / PATTERN/ part at the start followed by an optional ':TAG:DESCRIPTION:ACTION' -part. Each PATTERN is a regular expression to match a word on the command line. These patterns are processed sequentially +part. + +Each PATTERN is a regular expression to match a word on the command line. These patterns are processed sequentially until we reach a pattern that doesn't match at which point any corresponding ACTION is performed to obtain completions for that word. Note that there needs to be a pattern to match the initial command itself. See below for further explanation about PATTERNs. From e2e590f135375d15787946e9e790e76da44c52b6 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 17:21:27 +0000 Subject: [PATCH 62/73] update --- zsh-completions-howto.org | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 5ff5244..f2ee6c2 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -276,6 +276,19 @@ word is allowed which can be word2 followed by and a, b, or c, or a filename. If this sounds too complicated a much simpler alternative is to use the _regex_words function for creating specifications for _regex_arguments. +*** Patterns +You may notice that the / PATTERN/ specs in previous examples don't look like normal regular expressions. +Often a string parameter in the form $'foo\0' is used. This is so that the \0 in the string is interpreted correctly +as a null char which is used to separate words in the internal representation. If you don't include the \0 at the end +of the pattern you may get problems matching the next word. If you need to use the contents of a variable in a pattern, +you can double quote it so that it gets expanded and then put a string parameter containing a null char afterwards, +like this: "$somevar"$'\0' + +The regular expressions used in / PATTERN/ specs can use the following special chars: +| * | wildcard - any number of chars | +| ? | wildcard - single char | +| # | zero or more of the previous char | +| ## | one or more of the previous char | *** _regex_words The _regex_words function makes it much easier to create specifications for _regex_arguments. The results of calling _regex_words can be stored in a variable which can then be used instead @@ -323,12 +336,6 @@ In this case the first word can be one of "foo", "man", "chu", "boo", "ga" or "l If the first word is "boo" or "ga" then the second word can be "woo" or "hoo", and if the first word is "loo" then the second word can be "yee" or "haa", in the other cases there is no second word. -*** Patterns -The following patterns can be used. -| * | wildcard - any number of chars | -| ? | wildcard - single char | -| # | zero or more of the previous char | -| ## | one or more of the previous char | * Testing & debugging To reload a completion function: #+BEGIN_SRC sh From 0e3c702733e68070712e3b70dad66d43fda57222 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 17:22:52 +0000 Subject: [PATCH 63/73] update --- zsh-completions-howto.org | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index f2ee6c2..542f496 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -277,7 +277,7 @@ word is allowed which can be word2 followed by and a, b, or c, or a filename. If this sounds too complicated a much simpler alternative is to use the _regex_words function for creating specifications for _regex_arguments. *** Patterns -You may notice that the / PATTERN/ specs in previous examples don't look like normal regular expressions. +You may notice that the / PATTERN/ specs in the previous example doesn't look like normal regular expressions. Often a string parameter in the form $'foo\0' is used. This is so that the \0 in the string is interpreted correctly as a null char which is used to separate words in the internal representation. If you don't include the \0 at the end of the pattern you may get problems matching the next word. If you need to use the contents of a variable in a pattern, From 615333072b78afa1a1ee3d07d9fc144a9259a83a Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 17:23:54 +0000 Subject: [PATCH 64/73] update --- zsh-completions-howto.org | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 542f496..df8fc36 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -277,7 +277,7 @@ word is allowed which can be word2 followed by and a, b, or c, or a filename. If this sounds too complicated a much simpler alternative is to use the _regex_words function for creating specifications for _regex_arguments. *** Patterns -You may notice that the / PATTERN/ specs in the previous example doesn't look like normal regular expressions. +You may notice that the / PATTERN/ specs in the previous example don't look like normal regular expressions. Often a string parameter in the form $'foo\0' is used. This is so that the \0 in the string is interpreted correctly as a null char which is used to separate words in the internal representation. If you don't include the \0 at the end of the pattern you may get problems matching the next word. If you need to use the contents of a variable in a pattern, From cebfec8764e7e792aa841fd1efc84c1dc25852c6 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 17:33:38 +0000 Subject: [PATCH 65/73] update --- zsh-completions-howto.org | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index df8fc36..e45642b 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -284,11 +284,13 @@ of the pattern you may get problems matching the next word. If you need to use t you can double quote it so that it gets expanded and then put a string parameter containing a null char afterwards, like this: "$somevar"$'\0' -The regular expressions used in / PATTERN/ specs can use the following special chars: -| * | wildcard - any number of chars | -| ? | wildcard - single char | -| # | zero or more of the previous char | -| ## | one or more of the previous char | +The regular expression syntax for patterns seems to be a bit different from normal regular expressions, +and I can't find documentation anywhere. +However I have managed to work out what the following special chars are for: +| * | wildcard - any number of chars | +| ? | wildcard - single char | +| # | zero or more of the previous char (like * in a normal regular expression) | +| ## | one or more of the previous char (like + in a normal regular expression) | *** _regex_words The _regex_words function makes it much easier to create specifications for _regex_arguments. The results of calling _regex_words can be stored in a variable which can then be used instead From 13e63bfcf8e09d8047cbfebc5f93e73ce4d178db Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 17:58:38 +0000 Subject: [PATCH 66/73] update --- zsh-completions-howto.org | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index e45642b..b68e410 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -338,6 +338,34 @@ In this case the first word can be one of "foo", "man", "chu", "boo", "ga" or "l If the first word is "boo" or "ga" then the second word can be "woo" or "hoo", and if the first word is "loo" then the second word can be "yee" or "haa", in the other cases there is no second word. + +For a good example of the usage of _regex_words have a look at the _ip function. +* complex completions with _values, _sep_parts, & _multi_parts +The _values, _sep_parts & _multi_parts functions can be used either on their own, or as ACTIONs in specifications for +_alternative, _arguments or _regex_arguments. The following examples may be instructive. +See the [[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-System][official documentation]] for more info. + +Space separated list of mp3 files: +#+BEGIN_SRC sh +_values 'mp3 files' ~/*.mp3 +#+END_SRC + +Comma separated list of session id numbers: +#+BEGIN_SRC sh +_values -s , 'session id' "${(uonzf)$(ps -A o sid=)}" +#+END_SRC + +Completes foo@news:woo, or foo@news:laa, or bar@news:woo, etc: +#+BEGIN_SRC sh +_sep_parts '(foo bar)' @ '(news ftp)' : '(woo laa)' +#+END_SRC + +Complete some MAC addresses one octet at a time: +#+BEGIN_SRC sh +_multi_parts : '(00:11:22:33:44:55 00:23:34:45:56:67 00:23:45:56:67:78)' +#+END_SRC + + * Testing & debugging To reload a completion function: #+BEGIN_SRC sh From 337eb7726a7ae7d4dc946dba724a1f3a28dd6be6 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 18:02:46 +0000 Subject: [PATCH 67/73] update --- zsh-completions-howto.org | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index b68e410..055656c 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -365,7 +365,6 @@ Complete some MAC addresses one octet at a time: _multi_parts : '(00:11:22:33:44:55 00:23:34:45:56:67 00:23:45:56:67:78)' #+END_SRC - * Testing & debugging To reload a completion function: #+BEGIN_SRC sh @@ -391,7 +390,8 @@ Check that you have the correct number of :'s in the correct places for specific _alternative, _regex_arguments, etc. Remember to include an initial pattern to match the command word when using _regex_arguments (it does not need a matching action). -* Putting it all together + +Remember to put a null char $'\0' at the end of any PATTERN argument for _regex_arguments * 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. From c99880a2d7dc097cd91b079f9a356aacf8d9967b Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 27 Mar 2014 18:33:09 +0000 Subject: [PATCH 68/73] Use _values instead of _comma_separated --- src/_ps | 78 ++++++++++++++------------------------------------------- 1 file changed, 19 insertions(+), 59 deletions(-) diff --git a/src/_ps b/src/_ps index dd8ba5c..a0755d4 100644 --- a/src/_ps +++ b/src/_ps @@ -1,18 +1,6 @@ #compdef ps -# This works with procps version 3.2.8 - -# This depends on the _comma_separated function, which should be available from the same -# place you got this file. If it isn't then you can uncomment the following lines to define -# the function: -# -# _comma_separated() -# { -# compset -P '*,' -# local -a used vals -# used=(${(s:,:)IPREFIX}) -# _wanted tty expl $1 compadd -S ',' -q -F used "$@[2,-1]" -# } +# This works with procps version 3.2.8 local context state state_descr line typeset -A opt_args @@ -34,9 +22,9 @@ _arguments -s -w \ "(--context -F --format -o -O)-f[full format listing]"\ "(--context -f --format -o -O)-F[extra full format]"\ "(--context -f -F -j -l -o -O)--format[user-defined format]:output format:->format"\ - "$filterexcl-g[by session OR by effective group name]:groups:->groups"\ + "$filterexcl-g[by session OR by effective group name]:groups:_groups"\ "$filterexcl-G[by real group ID (supports names)]:groups:->rgid"\ - "$filterexcl--group[by session OR by effective group name]:groups:->groups"\ + "$filterexcl--group[by session OR by effective group name]:groups:_groups"\ "$filterexcl--Group[by real group ID (supports names)]:groups:->rgid"\ "-H[show process hierarchy]"\ "(--no-heading)--heading[repeat header lines, one per page of output]"\ @@ -59,10 +47,10 @@ _arguments -s -w \ "$filterexcl-t[by tty]:ttys:->tty"\ "-T[show threads, possibly with SPID column]"\ "$filterexcl--tty[by tty]:ttys:->tty"\ - "$filterexcl-u[by effective user ID (supports names)]:users:->users"\ - "$filterexcl-U[by real user ID (supports names)]:users:->users"\ - "$filterexcl--user[by effective user ID (supports names)]:users:->users"\ - "$filterexcl--User[by real user ID (supports names)]:users:->users"\ + "$filterexcl-u[by effective user ID (supports names)]:users:_users"\ + "$filterexcl-U[by real user ID (supports names)]:users:_users"\ + "$filterexcl--user[by effective user ID (supports names)]:users:_users"\ + "$filterexcl--User[by real user ID (supports names)]:users:_users"\ "(--version)-V[print the procps version]"\ "(-V)--version[print the procps version]"\ "-w[wide output]"\ @@ -72,24 +60,10 @@ _arguments -s -w \ case "$state" in pid) - compset -P '*,' - local -a used pid - used=(${(s:,:)IPREFIX}) - pid=(${(uon)$(ps -A o pid=)}) - _wanted pgid expl 'process id' compadd -S ',' -q -F used $pid - ;; - users) - _users + _values -s , 'process id' "${(uonzf)$(ps -A o pid=)}" ;; rgid) - compset -P '*,' - local -a used rgid - used=(${(s:,:)IPREFIX}) - rgid=(${(uon)$(ps -A o rgid=)}) - _wanted rgid expl 'process group id' compadd -S ',' -q -F used $rgid - ;; - groups) - _groups + _values -s , 'process group id' "${(uonzf)$(ps -A o rgid=)}" ;; pname) local ispat="pattern matching " @@ -105,38 +79,24 @@ case "$state" in fi ;; sid) - compset -P '*,' - local -a used sid - used=(${(s:,:)IPREFIX}) - sid=(${(uon)$(ps -A o sid=)}) - _wanted sid expl 'session id' compadd -S ',' -q -F used $sid + _values -s , 'session id' "${(uonzf)$(ps -A o sid=)}" ;; tty) - compset -P '*,' - local -a used ttys - used=(${(s:,:)IPREFIX}) + local -a ttys ttys=( /dev/tty*(N) /dev/pts/*(N) ) - _wanted tty expl 'terminal device' compadd -S ',' -q -F used ${ttys#/dev/} + _values -s , 'terminal device' ${ttys#/dev/} ;; ppid) - compset -P '*,' - local -a used ppid - used=(${(s:,:)IPREFIX}) - ppid=(${(uon)$(ps -A o ppid=)}) - _wanted ppid expl 'parent process id' compadd -S ',' -q -F used $ppid + _values -s , 'parent process id' "${(uonzf)$(ps -A o ppid=)}" ;; sortspec) - compset -P '*,' - local -a used spec minuspec pluspec allspec - used=(${(s:,:)IPREFIX/[-+]/}) - spec=(${(uo)$(ps L|cut -f 1 -d" ")}) - _wanted spec expl 'format specifier (prefix with - for decreasing order)' compadd -S ',' -q -F used $spec + _values -s , 'format specifier (prefix with - for decreasing order)' "${(uozf)$(ps L|cut -f 1 -d" ")}" ;; format) - compset -P '*,' - local -a used spec - used=(${(s:,:)IPREFIX}) - spec=(${(uo)$(ps L|cut -f 1 -d" ")}) - _wanted spec expl 'format specifier' compadd -S ',' -q -F used $spec + _values -s , 'format specifier' "${(uozf)$(ps L|cut -f 1 -d" ")}" ;; esac + +# Local Variables: +# mode:shell-script +# End: From 14ec62058a6e4bb097760eeb6362db474739ef7a Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Fri, 28 Mar 2014 20:51:44 +0000 Subject: [PATCH 69/73] update --- zsh-completions-howto.org | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 055656c..32350a6 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -392,6 +392,12 @@ _alternative, _regex_arguments, etc. Remember to include an initial pattern to match the command word when using _regex_arguments (it does not need a matching action). Remember to put a null char $'\0' at the end of any PATTERN argument for _regex_arguments +* Tips +Sometimes you have a situation where there is just one option that can come after a subcommand, and zsh will complete this +automatically when tab is pressed after the subcommand. If instead you want it listed with its description before completing +you can add another empty option (i.e. \:) to the ACTION like this ':TAG:DESCRIPTION:((opt1\:"description for opt1" \:))' +Note this only applies to utility functions that use ACTIONs in their specification arguments. + * 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. From 4c3c8bcd1089a60a60a76184dbafd1c242e7038e Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Fri, 28 Mar 2014 20:58:12 +0000 Subject: [PATCH 70/73] update --- zsh-completions-howto.org | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 32350a6..34fa070 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -396,7 +396,7 @@ Remember to put a null char $'\0' at the end of any PATTERN argument for _regex_ Sometimes you have a situation where there is just one option that can come after a subcommand, and zsh will complete this automatically when tab is pressed after the subcommand. If instead you want it listed with its description before completing you can add another empty option (i.e. \:) to the ACTION like this ':TAG:DESCRIPTION:((opt1\:"description for opt1" \:))' -Note this only applies to utility functions that use ACTIONs in their specification arguments. +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, From 1f2305485b58a45971507efc223895c4d33ebf7b Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Sat, 29 Mar 2014 02:47:21 +0000 Subject: [PATCH 71/73] Add _iw --- src/_iw | 247 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 247 insertions(+) create mode 100644 src/_iw diff --git a/src/_iw b/src/_iw new file mode 100644 index 0000000..3cc3c59 --- /dev/null +++ b/src/_iw @@ -0,0 +1,247 @@ +#compdef iw + +# Some parameters to hold patterns that will be used later. +local xp='[[:xdigit:]][[:xdigit:]]' +local -a bssid devices flags fouraddr fouronoff frequency high_throughput ifacename ifacetype ifacetypes +local -a matchany matchnum key lladdr lladdrs meshid meshidval ssid value +# matches any word +matchany=(/$'[^\0]##\0'/) +# matches any number +matchnum=(/$'[[:digit:]]##\0'/) +# matches any BSSID +bssid=($matchany ':bssid:BSSID:') +# matches any devices +devices=( /$'[[:alpha:]]##[[:digit:]]##(\.[[:digit:]]##)#\0'/ ':interfaces:network_interface:_net_interfaces' ) +# matches the word 'flags' followed by a list of some of the following words: none fcsfail control otherbss cook +flags=(/$'flags\0'/ ':flags:flags:(flags)' $matchany ':flags:flags:(none fcsfail control otherbss cook)' \#) +# matches the word '4addr' followed by either 'on' or 'off' +fouronoff=(/$'(on|off)\0'/ ':4addr:4addr:(on off)') +fouraddr=( /$'4addr\0'/ ':4addr:4addr:(4addr)' $fouronoff ) +# matches any number (description is 'frequency') +frequency=($matchnum ':freq:frequency:') +# matches one of HT20 HT40+ or HT40- +high_throughput=(/$'HT[0-9]##(+|-)#\0'/ ':HT:high throughput:(HT20 HT40+ HT40-)') +# matches any name (description is 'name') +ifacename=($matchany ':name:name:') +# matches the word 'type' followed by one of: managed ibss monitor mesh wds +ifacetypes=(/$'(managed|ibss|monitor|mesh|wds)\0'/ ':type:type:(managed ibss monitor mesh wds)') +ifacetype=(/$'type\0'/ ':type:type:(type)' $ifacetypes) +# matches any word (description is 'key') +key=($matchany ':key:key:') +# matches a MAC address (i.e. a sequence of six 2-digit numbers separated by spaces), $xp is defined earlier. +lladdr=(/"${xp}:${xp}:${xp}:${xp}:${xp}:${xp}"$'\0'/ ':lladdress:link layer (MAC) address:') +# as above but with a different description +lladdrs=(/"${xp}:${xp}:${xp}:${xp}:${xp}:${xp}"$'\0'/ ':lladdress:link layer (MAC) addresses (use - to match any octet):' \#) +# matches the word 'mesh_id' followed by a number +meshidval=($matchnum ':meshid:mesh ID:') +meshid=(/$'mesh_id\0'/ ':meshid:meshid:(mesh_id)' $meshidval) +# matches any word (description 'SSID') +ssid=($matchany ':ssid:SSID:') +# matches any word (description 'value') +value=($matchany ':val:value:') +# matches any number (description 'value') +numvalue=($matchnum ':val:value:') + +# Use the _regex_words function to create a variable containing command words to go after "iw reg" +local -a reg_cmds +_regex_words regulatory-commands "reg command" \ + 'g*et:print out the kernels current regulatory domain information'\ + 's*et:notify the kernel about the current regulatory domain' +reg_cmds=("$reply[@]") + +# Options for to go after "iw event" +local -a event_opts +_regex_words event-options "event option" \ + '-t:print timestamp' \ + '-r:print relative timstamp' \ + '-f:print full frame for auth/assoc etc' +event_opts=("$reply[@]") + +# Commands to go after "iw phy wowlan enable" +local -a phy_wowlan_enable_cmds +_regex_words phy-wowlan-enable-commands "phy WoWLAN enable commands" \ + '4*way-handshake:enable WoWLAN with 4way handshake trigger' \ + 'a*ny:enable WoWLAN with any trigger' \ + 'd*isconnect:enable WoWLAN with disconnect trigger' \ + 'e*ap-identity-request:enable WoWLAN with EAP identity request trigger' \ + 'g*tk-rekey-failure:enable WoWLAN with gtk rekey failure trigger' \ + 'm*agic-packet:enable WoWLAN with magic packet trigger' \ + 'p*atterns:MAC address triggers:$lladdrs' \ + 'r*fkill-release:enable WoWLAN with rfkill release trigger' +phy_wowlan_enable_cmds=("$reply[@]") + +# Commands to go after "iw phy wowlan" +local -a phy_wowlan_cmds +_regex_words phy-wowlan-commands "phy WoWLAN commands" \ + 's*how:show WoWLAN status' \ + 'd*isable:disable WoWLAN' \ + 'e*nable:enable WoWLAN:$phy_wowlan_enable_cmds' +phy_wowlan_cmds=("$reply[@]") + +# Some parameters to hold patterns that will be used for "iw phy set" commands +# (not perfect, but mostly OK). +local -a phy_set_antenna phy_set_channel phy_set_coverage phy_set_frag phy_set_freq phy_set_distance +local -a phy_set_name phy_set_netns phy_set_rts phy_set_txpower phy_txpower_opt +phy_set_antenna=($matchany ':antenna:bitmap:') +phy_set_channel=($matchnum ':channel:channel (1-14):' $high_throughput) +phy_set_coverage=($matchnum ':coverage:coverage class (0-255):') +phy_set_distance=($matchnum ':distance:valid values\: 0 - 114750:') +phy_set_frag=(/$'([0-9]##|off)\0'/ ':channel:channel (1-14):(1 2 3 4 5 6 7 8 9 10 11 12 13 14 off)') +phy_set_freq=($frequency $high_throughput) +phy_set_name=($matchany ':name:device name:') +phy_set_netns=($matchany ':netns:network namespace:') +phy_set_rts=($matchnum ':rts:rts threshold:') +phy_txpower_opt=($matchany ':txpower:tx power in mBm:') +_regex_words phy-set-txpower "set txpower" \ + 'a*uto:auto:' \ + 'f*ixed:fixed:$phy_txpower_opt' \ + 'l*imit:limit:$phy_txpower_opt' +phy_set_txpower=("$reply[@]") + +# Commands to go after "iw phy set" +local -a phy_set_cmds +_regex_words phy-set-commands "phy set commands" \ + 'a*ntenna:set a bitmap of allowed antennas to use for TX and RX:$phy_set_antenna' \ + 'ch*annel:set channel:$phy_set_channel' \ + 'co*verage:set coverage class (1 for every 3 usec of air propagation time):$phy_set_coverage' \ + 'd*istance:set appropriate coverage class for given link distance in meters:$phy_set_distance' \ + 'fra*g:set fragmentation threshold:$phy_set_frag' \ + 'fre*q:set frequency/channel the hardware is using, including HT configuration:$phy_set_freq' \ + 'na*me:rename this wireless device:$phy_set_name' \ + 'ne*tns:set network namespace:$phy_set_netns' \ + 'r*ts:set rts threshold:$phy_set_rts' \ + 't*xpower:specify transmit power level and setting type:$phy_set_txpower' +phy_set_cmds=("$reply[@]") + +# Commands to go after "iw phy interface" +local -a phy_interface_cmds +# This needs work (should not offer meshid, fouraddr of flags more than once, and need to accomodate multiple flag options) +phy_interface_cmds=(\( /$'add\0'/ ':add:add a new virtual interface with the given configuration:(add)' $ifacename $ifacetype \ + \( $meshid \| $fouraddr \| $flags \) \# \)) + +# Commands to go after "iw phy " +local -a phy_cmds +_regex_words phy-commands "phy command" \ + 's*et:set/configure interface properties:$phy_set_cmds' \ + 'inf*o:show capabilities for the specified wireless device' \ + 'int*erface:add a new virtual interface with the given configuration:$phy_interface_cmds' \ + 'w*owlan:WoWLAN commands:$phy_wowlan_cmds' +phy_cmds=("$reply[@]") + +# Parameters to hold patterns for dev commands +local -a dev_cmds_connect dev_cmds_cqm dev_cmds_get dev_cmds_ibss dev_cmds_interface dev_cmds_mesh dev_cmds_scan_options +local -a dev_cmds_mpath dev_cmds_offchannel dev_cmds_roc dev_cmds_scan dev_cmds_set dev_cmds_station dev_cmds_survey +dev_cmds_connect=($ssid $frequency $bssid $key) +dev_cmds_cqm=(/$'rssi\0'/ ':rssi:rssi:(rssi)' $matchnum ':thresh:threshold:' $matchnum ':hysteresis:hysteresis:') +dev_cmds_get=(/$'(mesh_param|power_save)\0'/ ':get:parameter:(mesh_param power_save)' $value) +# TODO: THIS NEEDS WORK! THE FINAL OPTIONS FOR JOIN NEED WORK +# dev ibss join [fixed-freq] [] [beacon-interval ] [basic-rates ] [mcast-rate ] [key d:0:abcde] +dev_cmds_ibss=(\( /$'leave\0'/ ':cmd:command:((leave:"Leave the IBSS cell"))' \| \( /$'join\0'/ ':cmd:command:((join\:"Join an IBSS cell"))' $ssid $frequency \( /$'fixed-freq\0'/ ':opt:option:((fixed-freq\:"fixed frequency (no args)"))' \| $bssid \| /$'beacon-interval\0'/ ':opt:option:((beacon-interval\:"beacon interval (takes single arg)"))' $numvalue \| /$'basic-rates\0'/ ':opt:option:((basic-rates\:"basic rates (comma separated list of rates)"))' $numvalue \| /$'mcast-rate\0'/ ':opt:option:((mcast-rate\:"multicast rate (takes single arg)"))' $numvalue \| $key \) \# \) \)) +dev_cmds_interface=(/$'add\0'/ ':add:add:(add)' $ifacename $ifacetype \( $meshid \| $fouraddr \| $flags \) \# ) +dev_cmds_mesh=(\( /$'leave\0'/ ':leave:leave a mesh:(leave)' \| /$'join\0'/ ':join:join a mesh:(join)' \ + $matchnum ':meshid:mesh ID:' $matchany ':parameter:mesh parameters [=]*:' \# \)) +dev_cmds_mpath=(\( /$'(del|get)\0'/ ':mpath:mesh path command:((del\:"remove the mesh path to the given node" \ +get\:"get information on mesh path to the given node"))' $lladdr \| /$'(new|set)\0'/ ':mpath:mesh path \ +command:((new\:"create a new mesh path (instead of relying on automatic discovery)" set\:"set an existing mesh \ +paths next hop"))' $lladdr /$'next_hop\0'/ ':nexthop:next hop:(next_hop)' $lladdr \| /$'dump\0'/ ':mpath:mesh path \ +command:((dump\:"list known mesh paths"))' \)) +dev_cmds_offchannel=($frequency $matchnum ':duration:duration:') +dev_cmds_roc=(/$'start\0'/ ':start:start:(start)' $frequency $matchnum ':time:time:') +dev_cmds_scan_options=(/$'freq\0'/ ':freq:freq:(freq)' $frequency $frequency \# /$'ies\0'/ ':ies:ies:(ies)' $lladdr \( /$'ssid\0'/ ':ssid:ssid:(ssid)' $ssid \# \| /$'passive\0'/ ':opt:passive:(passive)' \)) +dev_cmds_scan=(\( $dev_cmds_scan_options \| $matchany -'! [[ $match[1] =~ "dump|trigger" ]]' ':opt:option:((-u\:"include unknown data in results" \:""))' $dev_cmds_scan_options \| /$'dump\0'/ ':cmd:command:((dump\:"dump the current scan results"))' $matchany ':opt:option:((-u\:"include unknown data in results" \:""))' \| /$'trigger\0'/ ':cmd:command:((trigger\:"trigger a scan on the given frequencies with probing for the given SSIDs (or wildcard if not given) unless passive scanning is requested"))' $dev_cmds_scan_options \)) +local -a dev_cmds_set_bitrates dev_cmds_set_freq dev_cmds_set_mesh_param +local -a dev_cmds_set_monitor dev_cmds_set_peer dev_cmds_set_power_save +local -a dev_cmds_set_type dev_cmds_set_txpower +# dev set bitrates [legacy-<2.4|5> *] +dev_cmds_set_bitrates=(/$'legacy-*\0'/ ':opt:legacy:(legacy-2.4 legacy-2.5)' $matchnum ':rate:legacy rate in Mbps:') +# dev set freq [HT20|HT40+|HT40-] +dev_cmds_set_freq=($frequency $high_throughput) +# dev set mesh_param = [=]* +dev_cmds_set_mesh_param=( $matchany ':val:param=value:' \# ) +# dev set monitor * +dev_cmds_set_monitor=( $matchany ':flag:flag:((none\:"no special flags" fcsfail\:"show frames with FCS errors"\ + control\:"show control frames" otherbss\:"show frames from other BSSes" cook\:"use cooked mode"))' \# ) +# dev set peer +dev_cmds_set_peer=($lladdr) +# dev set power_save +dev_cmds_set_power_save=(/$'(on|off)\0'/ ':opt:power save mode:(on off)') + +_regex_words setcmds "dev set commands" \ + '4*addr:set interface 4addr (WDS) mode:$fouronoff'\ + 'b*itrates:set/clear specified rate masks:$dev_cmds_set_bitrates'\ + 'c*hannel:set channel:$phy_set_channel'\ + 'f*req:set frequency:$dev_cmds_set_freq'\ + 'mesh_param:set mesh parameters:$dev_cmds_set_mesh_param'\ + 'meshid:set mesh id:$meshidval'\ + 'mo*nitor:set monitor flags:$dev_cmds_set_monitor'\ + 'pe*er:set interface WDS peer MAC address:$dev_cmds_set_peer'\ + 'po*wer_save:set power save on/off:$dev_cmds_set_power_save'\ + 'tx*power:set transmission power:$phy_set_txpower'\ + 'ty*pe:set type:$ifacetypes' +dev_cmds_set=("$reply[@]") + +local -a dev_cmds_station_plink dev_cmds_station_vlan +dev_cmds_station_plink=(/$'(open|block)\0'/ ':opt::(open block)') +dev_cmds_station_vlan=($matchnum ':val:ifindex:') + +local -a dev_cmds_station_set +_regex_words stationsetcmds "dev station set commands"\ + 'plink_action:set peer link action:$dev_cmds_station_plink'\ + 'vlan:set AP VLAN:$dev_cmds_station_vlan' +dev_cmds_station_set=(\( $lladdr \) "$reply[@]") + +_regex_words stationcmds "dev station commands" \ + 'del:remove the given station entry (use with caution!):$lladdr'\ + 'dump:list all stations known, e.g. the AP on managed interfaces:'\ + 'get:get information for a specific station:$lladdr'\ + 'set:set AP VLAN or mesh peer link action:$dev_cmds_station_set' +dev_cmds_station=("$reply[@]") + +dev_cmds_survey=(/$'dump\0'/ ':dump:list all gathered channel survey data:(dump)') + +local -a dev_cmds +_regex_words dev-commands "dev commands" \ + 'co*nnect:join a network:$dev_cmds_connect' \ + 'cq*m:set connection quality monitor RSSI threshold:$dev_cmds_cqm' \ + 'de*l:remove this virtual interface' \ + 'di*sconnect:disconnect from the current network' \ + 'g*et:retrieve mesh parameter / power save state:$dev_cmds_get' \ + 'ib*ss:join/leave IBSS cell:$dev_cmds_ibss' \ + 'inf*o:show information for this interface' \ + 'int*erface:add an interface:$dev_cmds_interface' \ + 'l*ink:print information about the current link, if any' \ + 'me*sh:join/leave a mesh:$dev_cmds_mesh' \ + 'mp*ath:mesh path commands:$dev_cmds_mpath' \ + 'o*ffchannel:leave operating channel and go to the given channel for a while:$dev_cmds_offchannel' \ + 'r*oc:roc:$dev_cmds_roc' \ + 'sc*an:scan:$dev_cmds_scan' \ + 'se*t:set interface parameter:$dev_cmds_set' \ + 'st*ation:station commands:$dev_cmds_station' \ + 'su*rvey:list all gathered channel survey data:$dev_cmds_survey' +dev_cmds=( $devices "$reply[@]") + +# Arguments to _regex_arguments, built up in array $args. +local -a args reply +# Command word. Don't care what that is. +args=( $matchany ) + +local -a phydevs +phy_devs=( \( $(iw list|grep '^[[:alnum:]]\+'|cut -f 2 -d ' ') \) ) +phy_cmds=( \( $matchany ":test:test:$phy_devs[*]" \) "$phy_cmds[@]" ) + +_regex_words commands "iw command" \ + 'd*ev:commands to control/list the software devices:$dev_cmds' \ + 'e*vent:monitor events from the kernel:$event_opts' \ + 'h*elp:print usage for each command' \ + 'l*ist:list all wireless devices and their capabilities' \ + 'p*hy:commands to control the physical device:$phy_cmds' \ + 'r*eg:get/set regulatory domain:$reg_cmds' +args+=("$reply[@]") + +_regex_arguments _iw "${args[@]}" + +_iw "$@" + +# Local Variables: +# mode:shell-script +# End: From 7ce65d97da3cfc307781539385e608ecb7678c83 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Sat, 29 Mar 2014 02:52:11 +0000 Subject: [PATCH 72/73] update --- zsh-completions-howto.org | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index 34fa070..ee4fc17 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -340,7 +340,7 @@ and if the first word is "loo" then the second word can be "yee" or "haa", in th cases there is no second word. For a good example of the usage of _regex_words have a look at the _ip function. -* complex completions with _values, _sep_parts, & _multi_parts +** complex completions with _values, _sep_parts, & _multi_parts The _values, _sep_parts & _multi_parts functions can be used either on their own, or as ACTIONs in specifications for _alternative, _arguments or _regex_arguments. The following examples may be instructive. See the [[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-System][official documentation]] for more info. From fe4106b9bf9189789c066baf5c9de181b75d4174 Mon Sep 17 00:00:00 2001 From: Joe Bloggs Date: Thu, 3 Apr 2014 04:52:02 +0100 Subject: [PATCH 73/73] Add notes about compadd --- zsh-completions-howto.org | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/zsh-completions-howto.org b/zsh-completions-howto.org index ee4fc17..d494a10 100644 --- a/zsh-completions-howto.org +++ b/zsh-completions-howto.org @@ -365,6 +365,42 @@ Complete some MAC addresses one octet at a time: _multi_parts : '(00:11:22:33:44:55 00:23:34:45:56:67 00:23:45:56:67:78)' #+END_SRC +** Adding completion words directly using compadd +For more fine grained control you can use the builtin compadd function to add completion words directly. +This function has many different options for controlling how completions are displayed and how text on the command line +can be altered when words are completed. Read the [[http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-System][official documentation]] for full details. +Here I just give a few simple examples. + +Add some words to the list of possible completions: +#+BEGIN_SRC sh +compadd foo bar blah +#+END_SRC + +As above but also display an explanation: +#+BEGIN_SRC sh +compadd -X 'Some completions' foo bar blah +#+END_SRC + +As above but automatically insert a prefix of "what_" before the completed word: +#+BEGIN_SRC sh +compadd -P what_ foo bar blah +#+END_SRC + +As above but automatically insert a suffix of "_todo" after the completed word: +#+BEGIN_SRC sh +compadd -S _todo foo bar blah +#+END_SRC + +As above but automatically remove the "_todo" suffix if a blank char is typed after the suffix: +#+BEGIN_SRC sh +compadd -P _todo -q foo bar blah +#+END_SRC + +Add words in array $wordsarray to the list of possible completions +#+BEGIN_SRC sh +compadd -a wordsarray +#+END_SRC + * Testing & debugging To reload a completion function: #+BEGIN_SRC sh