help / color / Atom feed
* [PATCH] Update completion style guide
@ 2019-12-01 21:53 dana
  0 siblings, 0 replies; 2+ messages in thread
From: dana @ 2019-12-01 21:53 UTC (permalink / raw)
  To: Zsh hackers list

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


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


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'
+  '--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 -/ "$@" -

^ permalink raw reply	[flat|nested] 2+ messages in thread

* [PATCH] Update completion style guide
@ 2018-06-16  4:17 dana
  0 siblings, 0 replies; 2+ messages in thread
From: dana @ 2018-06-16  4:17 UTC (permalink / raw)
  To: Zsh workers

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.


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 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}'

^ permalink raw reply	[flat|nested] 2+ messages in thread

end of thread, back to index

Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-12-01 21:53 [PATCH] Update completion style guide dana
  -- strict thread matches above, loose matches on Subject: below --
2018-06-16  4:17 dana


Archives are clonable: git clone --mirror http://inbox.vuxu.org/zsh-workers

Example config snippet for mirrors

Newsgroup available over NNTP:

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git