[PATCH] Update completion style guide

[PATCH] Update completion style guide

[dana]

Some updates to the completion style guide inspired by Peter's remark in workers
# 43025 and my escaping confusion mentioned in workers # 42992. Not sure about
the formatting on the latter change; tried to stay consistent, but idk.

dana


diff --git a/Etc/completion-style-guide b/Etc/completion-style-guide
index a6fc737a7..3bb1477da 100644
--- a/Etc/completion-style-guide
+++ b/Etc/completion-style-guide
@@ -20,6 +20,26 @@ Coding style:
 * Please try not to use lines longer than 79 characters. Don't worry
   about breaking long `_arguments' or `_values' specs though.
 
+* Never use alternative, unusual, or optional syntax in completion
+  functions (or any other shell code distributed with zsh). In other
+  words, do NOT use the following:
+
+    # Short loops
+    for x in $y myfunc $x
+
+    # Alternative forms
+    if { [[ $x == $y ]] } {
+      myfunc $x
+    }
+    foreach x in $y {
+      myfunc $x
+    }
+
+    # Weird tricks
+    () for 1 {
+      myfunc $1
+    } $x
+
 Descriptions:
 
 Descriptions should not have a trailing full stop and initial capital

diff --git a/Etc/completion-style-guide b/Etc/completion-style-guide
index 3bb1477da..c6f5dcda3 100644
--- a/Etc/completion-style-guide
+++ b/Etc/completion-style-guide
@@ -513,3 +513,20 @@ Misc. remarks
     completion function would contain the code for the default way to
     generate the matches.
     See the `_email_addresses', `_rpm' and `_nslookup' files for examples.
+9)  Be mindful of quoting/escaping edge cases. Notably:
+    * Elements of the `$words' array are derived verbatim from the user's
+      command-line input -- if they type an argument in quotes or escaped
+      by backslashes, that is how it appears in the array.
+    * Option-arguments are stored in `$opt_args` the same way. Further,
+      since multiple arguments to the same option are represented in a
+      colon-delimited fashion, backslashes and colons passed by the user
+      are escaped. For instance, the option-arguments parsed from
+      `-afoo -a "bar" -a 1:2:3' appear in `$opt_args[-a]` as
+      `foo:"bar":1\:2\:3'.
+    * The `_call_program` helper used by many completion functions is
+      implemented using `eval', so arguments to it must be quoted
+      accordingly. As mentioned above, most of the user's own input comes
+      pre-escaped, but you may run into problems passing file names or
+      data derived from another command's output to the helper. Consider
+      using some variation of the `q` expansion flag to deal with this:
+      `_call_program vals $words[1] ${(q-)myfile}'

[PATCH] Update completion style guide

[dana]

Some additions to the completion style guide based on the comments here:

https://github.com/zsh-users/zsh/pull/36

I haven't seen anyone else complain about the superfluous descriptions, so
maybe i'm editorialising a bit, but hopefully it's reasonable?

dana


diff --git a/Etc/completion-style-guide b/Etc/completion-style-guide
index af7c46bfd..53d522764 100644
--- a/Etc/completion-style-guide
+++ b/Etc/completion-style-guide
@@ -69,12 +69,35 @@ for example, do not use:
   '--timeout[specify connection timeout in milliseconds]:timeout'
 but use:
   '--timeout[specify connection timeout]:timeout (ms)'
-  
+To indicate a default value, use square brackets:
+  '--timeout[specify connection timeout]:timeout (ms) [5000]'
+These two conventions can be used together or individually as appropriate.
+
 Group descriptions should be singular because only one thing is being
 completed even though many may be listed. This applies even where you
 complete a list of the things. Tags, functions for completing types of
 things (such as _files), and states should have plural names.
 
+Group descriptions can be omitted where they are handled by a helper/type
+function. For example, the `file' description in the following line is
+unnecessary, as `_files' provides it by default:
+  '--import=[import specified file]:file:_files'
+In this case, the following syntax can be used instead:
+  '--import=[import specified file]: :_files'
+Of course, it may make sense to add an explicit description which is
+more specific than the default:
+  '--config=[use specified config file]:config file:_files'
+
+Similarly, group descriptions can and should be omitted where a `->state'
+is involved, as the description in the argument spec is always ignored
+in these cases. For example, instead of:
+  '--config=[use specified config file]:config file:->config-files'
+use:
+  '--config=[use specified config file]: :->config-files'
+Setting an explicit description here constitutes (a small amount of)
+unnecessary noise, and may be misleading to other developers who update
+the function.
+
 In a function, allow any descriptions passed as an argument to override
 the default you define. For example:
   _wanted directories expl directory _files -/ "$@" -