about summary refs log tree commit diff
path: root/Util/completion-style-guide
diff options
context:
space:
mode:
Diffstat (limited to 'Util/completion-style-guide')
-rw-r--r--Util/completion-style-guide44
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).