blob: 2980d89ebcd9b40a55176ef46b53c7b40aa66dc4 (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
# zsh(1)
## Keybindings
Change input mode:
```zsh
bindkey -v change to vi keymap
bindkey -e change to emacs keymap
```
Define key-mappings:
```zsh
bindkey list mappings in current keymap
bindkey in-str cmd create mapping for `in-str` to `cmd`
bindkey -r in-str remove binding for `in-str`
# C-v <key> dump <key> code, which can be used in `in-str`
# zle -l list all functions for keybindings
# man zshzle(1) STANDARD WIDGETS: get description of functions
```
## Completion
### Installation
Completion functions are provided via files and need to be placed in a location
covered by `$fpath`. By convention the completion files are names as `_<CMD>`.
A completion skeleton for the command `foo`, stored in `_foo`
```zsh
#compdef _foo foo
function _foo() {
...
}
```
Alternatively one can install a completion function explicitly by calling `compdef <FUNC> <CMD>`.
### Completion Variables
Following variables are available in Completion functions:
```zsh
$words # array with command line in words
$#words # number words
$CURRENT # index into $words for cursor position
$words[CURRENT-1] # previous word (relative to cursor position)
```
### Completion Functions
- `_describe` simple completion, just words + description
- `_arguments` sophisticated completion, allow to specify actions
#### Completion with [`_describe`][zsh-comp-fn]
```zsh
_describe MSG COMP
```
- `MSG` simple string with header message
- `COMP` array of completions where each entry is `"opt:description"`
```zsh
function _foo() {
local -a opts
opts=('bla:desc for bla' 'blu:desc for blu')
_describe 'foo-msg' opts
}
compdef _foo foo
foo <TAB><TAB>
-- foo-msg --
bla -- desc for bla
blu -- desc for blu
```
#### Completion with [`_arguments`][zsh-comp-fn]
```zsh
_arguments SPEC [SPEC...]
```
where `SPEC` can have one of the following forms:
- `OPT[DESC]:MSG:ACTION`
- `N:MSG:ACTION`
Available actions
```zsh
(op1 op2) list possible matches
->VAL set $state=VAL and continue, `$state` can be checked later in switch case
FUNC call func to generate matches
{STR} evaluate `STR` to generate matches
```
### Example
Skeleton to copy/paste for writing simple completions.
Assume a program `foo` with the following interface:
```zsh
foo -c green|red|blue -s low|high -f <file> -d <dir> -h
```
The completion handler could be implemented as follows in a file called `_foo`:
```zsh
#compdef _foo foo
function _foo_color() {
local colors=()
colors+=('green:green color')
colors+=('red:red color')
colors+=('blue:blue color')
_describe "color" colors
}
function _foo() {
_arguments \
"-c[define color]:color:->s_color" \
"-s[select sound]:sound:(low high)" \
"-f[select file]:file:_files" \
"-d[select dir]:dir:_files -/" \
"-h[help]"
case $state in
s_color) _foo_color;;
esac
}
```
> `_files` is a zsh builtin utility function to complete files/dirs see
> - [zsh completion functions][zsh-comp-fn]
> - [zsh completion utility functions][zsh-comp-utility-fn]
[zsh-comp-fn]: http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-Functions
[zsh-comp-utility-fn]: https://github.com/zsh-users/zsh-completions/blob/master/zsh-completions-howto.org#utility-functions
|
