diff options
Diffstat (limited to 'Etc')
| -rw-r--r-- | Etc/FAQ.yo | 10 | ||||
| -rw-r--r-- | Etc/completion-style-guide | 37 |
2 files changed, 40 insertions, 7 deletions
diff --git a/Etc/FAQ.yo b/Etc/FAQ.yo index 72ff7fa3d..12bd4eb3d 100644 --- a/Etc/FAQ.yo +++ b/Etc/FAQ.yo @@ -331,15 +331,11 @@ label(16) The coordinator of development is currently me; the alias email(coordinator@zsh.org) can be used to contact whoever is in the hot - seat. The following are known mirrors (kept frequently up to date); the - first is the official archive site, currently in Australia. All are - available by anonymous FTP. The major sites keep test versions in the + seat. url(https://www.zsh.org/)(https://www.zsh.org/) is the official + archive site, currently in Australia. Test versions are kept in the `testing' subdirectory: such up-to-the-minute development versions should only be retrieved if you actually plan to help test the latest version of - the shell. The following list also appears on the WWW at - url(http://www.zsh.org/)(http://www.zsh.org/) . - -includefile(../Doc/Zsh/ftp_sites.yo) + the shell. A Windows port was created by Amol Deshpandem based on 3.0.5 (which is now rather old). This has now been restored and can be found at diff --git a/Etc/completion-style-guide b/Etc/completion-style-guide index a6fc737a7..af7c46bfd 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 @@ -493,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}' |