mirror of
git://git.code.sf.net/p/zsh/code
synced 2025-10-31 18:10:56 +01:00
44 lines
2.6 KiB
Text
44 lines
2.6 KiB
Text
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).
|