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
|
For now this is just a list of things one should or shouldn't do.
1) Use the functions `_files' and `_path_files' instead of `compgen'
with the `-f', `-/', or `-g' options.
2) *Never* use `compgen' with the `-s' option. This can always be done
by a call to `compadd' which is faster.
3) Using `compgen' with the `-k' option should only be done if a) the
array is already existent or b) it is very large (several hundred
or thousend elements). In other cases using `compadd' is faster.
4) Supply match specifications to `compadd' and `compgen' if there are
sensible ones.
5) Use `_description' when adding matches with `compadd' or
`compgen'. Use `_message' in places where no matches can be
generated. If you want to add different types of matches, add them
with multiple calls to `compadd' or `compgen', supplying different
descriptions.
6) Use helper functions that do option completion for you (like
`_arguments' and `_values') -- it will make your life much
easier.
7) Use helper functions like `_users' and `_groups' instead of direct
calls to `compgen -u' or some ad hoc mechanisms to generate such
information. This ensures that users can change the way these things
will be completed everywhere by just using their own implementations
for these functions.
8) Make sure that the return value of your functions is correct: zero
if matches where added and non-zero if no matches were found.
In some cases you'll need to test the value of `$compstate[nmatches]'
for this. This should always be done by first saving the old value
(`local nm="$compstate[nmatches]"') and later comparing this with
the current value after all matches have been added (e.g. by
writing `[[ nm -ne compstate[nmatches] ]]' at the end of your
function). This guarantees that your functions will be re-usable
because calling functions may rely on the correct return value.
9) In places where different behaviors may be useful, add a
configuration key to allow users to select the behavior they
prefer. Names for configuration keys should look like `prefix_name',
where `prefix' is the (probably abbreviated) name of your function
and `name' describes what can be configured.
When testing the values of configuration keys, the empty string
should result in the same behavior as if the key were unset. This
can be achieved by the test `[[ -n "$compconfig[prefix_name]" ]]'.
10) When writing helper functions that generate matches, the arguments
of these should be given unchanged to `compadd' or `compgen' (if
they are not used by the helper function itself).
11) When option names are generated as possible matches, add them *with*
the `-', `+', or `--' at the beginning. This is the style used
throughout the completion system from the distribution and makes it
easier to distinguish options from other matches in completion lists.
Also, when adding options as matches, put them in a sorted group
named `option'. The best way to do this is by using the `_description'
helper function as in:
local expl
_description expl option
compadd "$expl[@]" - <option-names ...>
Also, before adding options as possible matches, test the
`option_prefix' configuration key. If it set and it doesn't contain
the sub-string `!cmd' (where `cmd' is the name of the command that
is completed for) options should only be added if the prefix character
(`-' or `+') is on the line or if no other useful matches could be
generated. This can be achieved by first generating these other matches
(if any) and then using a test like:
if [[ nm -eq "$compstate[nmatches]" ||
-z "$compconfig[option_prefix]" ||
"$compconfig[option_prefix]" = *\!${words[1]}* ||
"$PREFIX" = [-+]* ]]; then
# Add options...
fi
Finally, it is good style to display descriptions for options that
aren't self-explanatory. See the `_display' function and it's use
in `_arguments'.
All this should make it look like a really good idea to just use the
supplied `_arguments' function to complete options.
|
