From: dana <dana@dana.is>
To: Zsh workers <zsh-workers@zsh.org>
Subject: [PATCH] Update completion style guide
Date: Fri, 15 Jun 2018 23:17:29 -0500 [thread overview]
Message-ID: <B7838EA3-664A-4682-9895-865F2901E065@dana.is> (raw)
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}'
next reply other threads:[~2018-06-16 4:17 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-06-16 4:17 dana [this message]
2019-12-01 21:53 dana
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=B7838EA3-664A-4682-9895-865F2901E065@dana.is \
--to=dana@dana.is \
--cc=zsh-workers@zsh.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).