From c21b91b916e23f202a0ae3b2a7aafe4e595e7b5c Mon Sep 17 00:00:00 2001 From: Tanaka Akira Date: Mon, 23 Aug 1999 10:07:44 +0000 Subject: Initial revision --- Util/completion-style-guide | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 Util/completion-style-guide (limited to 'Util') 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). -- cgit 1.4.1