From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 2408 invoked by alias); 16 Jun 2018 04:17:35 -0000 Mailing-List: contact zsh-workers-help@zsh.org; run by ezmlm Precedence: bulk X-No-Archive: yes List-Id: Zsh Workers List List-Post: List-Help: List-Unsubscribe: X-Seq: 43031 Received: (qmail 26676 invoked by uid 1010); 16 Jun 2018 04:17:35 -0000 X-Qmail-Scanner-Diagnostics: from mail-it0-f67.google.com by f.primenet.com.au (envelope-from , uid 7791) with qmail-scanner-2.11 (clamdscan: 0.99.2/21882. spamassassin: 3.4.1. Clear:RC:0(209.85.214.67):SA:0(-1.9/5.0):. Processed in 1.443589 secs); 16 Jun 2018 04:17:35 -0000 X-Spam-Checker-Version: SpamAssassin 3.4.1 (2015-04-28) on f.primenet.com.au X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H3,RCVD_IN_MSPIKE_WL,SPF_PASS,T_DKIMWL_WL_MED,T_DKIM_INVALID autolearn=ham autolearn_force=no version=3.4.1 X-Envelope-From: dana@dana.is X-Qmail-Scanner-Mime-Attachments: | X-Qmail-Scanner-Zip-Files: | DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=dana-is.20150623.gappssmtp.com; s=20150623; h=from:content-transfer-encoding:mime-version:subject:message-id:date :to; bh=KxKf3Iaej7eEQBi8FlzkJuaohRk5AtQtAkCfPe2v5Cg=; b=e4SoAJ42L2Sq0T23hzhbwj+qgNY/xCwdbGnnCbUnUUFHzwFfpkRv1BuojGs95DFDjK FtT6UZhenFch06ITScV60P75bCMW3cPoWXEO2WtR3bwW9UxzYZ1AX4TJxlknUNYnEggK QARA9AVrOk7jaYCaWl7dG1x5fVrA6USYam11mrtit6nUX7g3EKA0SGazqCj8KqYPa4qJ FGilot5U34qdp34Hkzq6nPSVPHqwV7bLr/RAyeHtjX5zDrCA/lOS9apQ7CpPSGuYdrXa Nwydm93zjJQsBn51+kp5ATY5rVA05RtqoYRXt/2t+SwmoMUtVO8HxwNjk0/MFRui+6Bd JodA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:content-transfer-encoding:mime-version :subject:message-id:date:to; bh=KxKf3Iaej7eEQBi8FlzkJuaohRk5AtQtAkCfPe2v5Cg=; b=SnC0BrbRKeCaL4Oil4GRHAcQrlCYcVvhoNo/mgFyiBo6Xzdu4GY6bCzT/bHnV0WKxH urSuDnp0+tOuhVFusRTaETbMqhpWw+0BKmCogwoJlJZyzKR8oeWrvHT6LWdD9HGc3DkR qHOfKkia8tEOZXlcufqx2d4rj3ZumFY8TwjFhmeCvW6eyNcDabOliFbLybEqsgvy5mvG uDsXLIzBVjxQyVi8MYNEGLVSKacz4E8VBOTs3hvcoV9MznoE4OrcT8Rrdtvw6GrDbHU8 4a5JilbeN27qZAR+JUA2y73j4uiFvHBX7il7EPKZXqweAaOd4vpAr9n/RBnjTYjjqEpm Q1HQ== X-Gm-Message-State: APt69E3Wx4JGA37GT3f8rluyIDIiYKGhmXnLteIaYW7w+BQe8H47Qhjp Ljo7XYQbQol3dVm/xpZ9wflH8/lomJw= X-Google-Smtp-Source: ADUXVKLxdj+dFQJozGjuSt6VSi+fxghQWOFHs8D6NlsyawBY6xZlhedsxmuTg4+ucaYnJzPJ0UNYjg== X-Received: by 2002:a24:b304:: with SMTP id e4-v6mr3677170itf.13.1529122650487; Fri, 15 Jun 2018 21:17:30 -0700 (PDT) From: dana Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Mime-Version: 1.0 (Mac OS X Mail 10.3 \(3273\)) Subject: [PATCH] Update completion style guide Message-Id: Date: Fri, 15 Jun 2018 23:17:29 -0500 To: Zsh workers X-Mailer: Apple Mail (2.3273) 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. =20 +* 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 =3D=3D $y ]] } { + myfunc $x + } + foreach x in $y { + myfunc $x + } + + # Weird tricks + () for 1 { + myfunc $1 + } $x + Descriptions: =20 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}'