summary refs log tree commit diff
diff options
context:
space:
mode:
authordana <dana@dana.is>2018-06-16 11:50:43 -0500
committerdana <dana@dana.is>2018-06-16 11:50:43 -0500
commit0daeed20e1828b9026b8800555d3f5dad1088544 (patch)
tree5045752573c3fc3774c1f70137d4594c4f131f54
parent4d19645d49b145a34bcb36eeb3b70ef089c55ba9 (diff)
downloadzsh-0daeed20e1828b9026b8800555d3f5dad1088544.tar.gz
zsh-0daeed20e1828b9026b8800555d3f5dad1088544.tar.xz
zsh-0daeed20e1828b9026b8800555d3f5dad1088544.zip
43031: Add note to style guide about quoting
-rw-r--r--ChangeLog3
-rw-r--r--Etc/completion-style-guide17
2 files changed, 20 insertions, 0 deletions
diff --git a/ChangeLog b/ChangeLog
index f5e36572a..9ec595efe 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,8 @@
 2018-06-16  dana  <dana@dana.is>
 
+	* 43031: Etc/completion-style-guide: Add note about quoting/escaping
+	(cf. 42992)
+
 	* 43031: Etc/completion-style-guide: Add note about optional/variant
 	syntax (cf. 43025)
 
diff --git a/Etc/completion-style-guide b/Etc/completion-style-guide
index ca99c828b..af7c46bfd 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}'