about summary refs log tree commit diff
path: root/Doc/Zsh/mod_complist.yo
blob: 460d4a609825f2867b9db8e5f1129b83316bf9e8 (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
texinode(The complist Module)(The deltochar Module)(The compctl Module)(Zsh Modules)
sect(The complist Module)
cindex(completion, listing)
The tt(complist) module offers two extensions to completion listings:
the ability to highlight matches in such a list and a different
style of menu-completion.

subsect(Parameters)
For both extensions one of the parameters tt(ZLS_COLORS) or tt(ZLS_COLOURS)
must be set, even if the value is empty (which uses all the default values
given below). These describe how matches are highlighted. The format of the
value of these parameters is the same as used by the GNU version of the
tt(ls) command: a colon-separated list of specifications of the form
`var(name)=var(value)'. The var(name) may be one of the following strings,
most of which specify file-types for which the var(value) will be used. The
strings and their default values are:

startitem()
item(tt(no 0))(
for normal text (not the string displayed for a match)
)
item(tt(fi 0))(
for regular files
)
item(tt(di 32))(
for directories
)
item(tt(ln 36))(
for symbolic links
)
item(tt(pi 31))(
for named pipes (FIFOs)
)
item(tt(so 33))(
for sockets
)
item(tt(bd 44;37))(
for block devices
)
item(tt(cd 44;37))(
for character devices
)
item(tt(ex 35))(
for executable files
)
item(tt(mi) var(none))(
for names not naming a file (default is the value defined for tt(fi))
)
item(tt(lc \e[))(
for the left code (see below)
)
item(tt(rc m))(
for the right code
)
item(tt(ec) var(none))(
for the end code
)
enditem()

Apart from these strings, the var(name) may also be an asterisk
(`tt(*)') followed by any string. The var(value) given for such a
string will be used for all files whose name ends with the string.

When printing a match, the code prints the value of tt(lc), the value
for the file-type or the last matching specification with a `tt(*)',
the value of tt(rc), the string to display for the match itself, and
then the value of tt(ec) if that is defined or the values of tt(lc),
tt(no), and tt(rc) if tt(ec) is not defined.

The default values are ISO 6429 (ANSI) compliant and can be used on
vt100 compatible terminals such as tt(xterm)s. On monochrome terminals
the default values will have no visual effect.

Whenever one of the parameters tt(ZLS_COLORS) or tt(ZLS_COLOURS) is set 
and the tt(complist) module is loaded or linked into the shell,
completion lists will be colored.

subsect(Menu selection)
The tt(complist) module also offers a different style of selecting
matches from a list called menu-selection. It can be invoked directly by
the widget tt(menu-select) defined by the module.  Alternatively,
the parameter tt(SELECTMIN) can be set to an integer giving the minimum
number of matches which must be present before menu selection is
automatically turned on.  This second method requires that menu completion
be started, either directly from a widget such as tt(menu-complete), or due
to one of the options tt(MENU_COMPLETE) or tt(AUTO_MENU) being set.  If
tt(SELECTMIN) is set, but is 0, 1 or empty, menu selection will always be
started during menu completion if the completion is ambiguous.

After menu-selection is started, the matches will be listed. The
matches to insert into the command line can be selected from this
list. In the list one match is highlighted using the value for tt(ma)
from the tt(ZLS_COLORS) or tt(ZLS_COLOURS) parameter. The default
value for this it `tt(7)' which forces the selected match to be
highlighted using standout mode on a vt100 compatible terminal.

Selecting matches is done by moving the mark around using the zle movement
functions. The zle functions tt(send-break) and tt(accept-line) can be used
to leave menu-selection, leaving the match currently inserted into the line
in place. The functions tt(accept-and-hold) and
tt(accept-and-menu-complete) can be used to accept the match currently
inserted and continue inserting matches after that. Matches inserted this
way can be removed by invoking the tt(undo) function. Keys bound to one of
the completion functions will cycle to the next (or, in case of
tt(reverse-menu-complete), the previous) match, and the tt(redisplay) and
tt(clear-screen) functions work as usual without leaving
menu-selection. Any other zle function leaves menu-selection and executes
that function.

During this selection the widget uses the keymap tt(menuselect). Any
key that is not defined in this keymap or that is bound to
tt(undefined-key) is looked up in the keymap currently selected. This
is used to ensure that the most important keys used during selection
have sensible default (namely the cursor keys, return, and TAB). However,
keys in the the tt(menuselect) keymap can be modified directly using the
tt(bindkey) builtin command (see
ifzman(zmanref(zshmodules))\
ifnzman(noderef(The zle Module))\
).