Initial revision

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).