diff options
author | Tanaka Akira <akr@users.sourceforge.net> | 1999-08-23 10:07:44 +0000 |
---|---|---|
committer | Tanaka Akira <akr@users.sourceforge.net> | 1999-08-23 10:07:44 +0000 |
commit | c21b91b916e23f202a0ae3b2a7aafe4e595e7b5c (patch) | |
tree | 30c6fdd6dadba05d7b566ae99ca51ae980a2514e /Util | |
parent | 0066a6a007cc06e959d1d040f80d1ea0e72076c2 (diff) | |
download | zsh-c21b91b916e23f202a0ae3b2a7aafe4e595e7b5c.tar.gz zsh-c21b91b916e23f202a0ae3b2a7aafe4e595e7b5c.tar.xz zsh-c21b91b916e23f202a0ae3b2a7aafe4e595e7b5c.zip |
Initial revision
Diffstat (limited to 'Util')
-rw-r--r-- | Util/completion-style-guide | 44 |
1 files changed, 44 insertions, 0 deletions
diff --git a/Util/completion-style-guide b/Util/completion-style-guide new file mode 100644 index 000000000..307954760 --- /dev/null +++ b/Util/completion-style-guide @@ -0,0 +1,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). |