* [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:
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 -/ "$@" -
^ 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.
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}'
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2019-12-01 21:53 UTC | newest]
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
Code repositories for project(s) associated with this public inbox
https://git.vuxu.org/mirror/zsh/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).