blob: 3079547604f5b99712edd99d4e4f7be9ffbace9a (
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
|
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 `_long_options') -- 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 user 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 `[[ nmm -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).
|
