diff options
Diffstat (limited to 'Util/completion-style-guide')
-rw-r--r-- | Util/completion-style-guide | 44 |
1 files changed, 0 insertions, 44 deletions
diff --git a/Util/completion-style-guide b/Util/completion-style-guide deleted file mode 100644 index 307954760..000000000 --- a/Util/completion-style-guide +++ /dev/null @@ -1,44 +0,0 @@ -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). |