From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 15060 invoked by alias); 16 Jul 2015 23:20:38 -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: X-Seq: 35808 Received: (qmail 16798 invoked from network); 16 Jul 2015 23:20:36 -0000 X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on f.primenet.com.au X-Spam-Level: X-Spam-Status: No, score=-2.7 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,RCVD_IN_DNSWL_LOW,RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL autolearn=ham autolearn_force=no version=3.4.0 DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed; d= daniel.shahaf.name; h=content-type:date:from:message-id :mime-version:subject:to:x-sasl-enc:x-sasl-enc; s=mesmtp; bh=L9S 7u5/sKNSa4+mCkSvV+yWnPb4=; b=iDxenZxkkiDx6uVFQ7vS/Bd9XjKQlVco7R2 f7i2F5L3cKHr8niHgK88xtFpSF3b0liO7qPlJTWstSHLMQ4Sq2onA8DyuGvVt7wJ jsAWVUld9EeYIu695ry/UIFl1SKcSK2lwPqu0eZ1897UAcVmmCQ1a9gc2OyywqGT gx5OO+Rg= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed; d= messagingengine.com; h=content-type:date:from:message-id :mime-version:subject:to:x-sasl-enc:x-sasl-enc; s=smtpout; bh=L9 S7u5/sKNSa4+mCkSvV+yWnPb4=; b=L1xNoehIWvZd580Ke18zQ+4h+0XtqbJVNl uAJQyezbTl/c4UebBxo5ttzCqiXIpSp9EsWZAz5yeKHRCnr/TH2JckCBQqYZJgsX IfAR75FcGI4nMOrpbT4GUks11Xz7ZDyRfl1XUHFqiZXEfh/bOJlt2cCUCagIt8fX noptLysTM= X-Sasl-enc: d9P++ZDpjqh3hNYariyiZcqx+jvkVHRa/hU4ta9Z7X4G 1437088834 Date: Thu, 16 Jul 2015 23:20:32 +0000 From: Daniel Shahaf To: zsh-workers@zsh.org Subject: [PATCH] _arguments docs: Add options overview and sections Message-ID: <20150716232032.GE2032@tarsus.local2> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="tThc/1wpZn/ma/RB" Content-Disposition: inline User-Agent: Mutt/1.5.21 (2010-09-15) --tThc/1wpZn/ma/RB Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Attached for review. The first patch conslidates the documentation of all of _arguments' options in one place; that patch is 90% moving text around and 10% minor text changes. The second patch divides the long help docstring into "subsections". --tThc/1wpZn/ma/RB Content-Type: text/x-patch; charset=us-ascii Content-Disposition: attachment; filename="0001-_arguments-docs-Add-options-overview.patch" >>From 6d08869e2c4b495cf90e8e1dd876971e8dcec712 Mon Sep 17 00:00:00 2001 From: Daniel Shahaf Date: Wed, 15 Jul 2015 18:05:31 +0000 Subject: [PATCH 1/2] _arguments docs: Bring all option descriptions to one place --- Doc/Zsh/compsys.yo | 135 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 84 insertions(+), 51 deletions(-) diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index af906bf..5fd8e24 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -3530,37 +3530,107 @@ xitem(SPACES()[ tt(:) ] var(spec) ...) item(tt(_arguments) [ var(opt) ... ] tt(-)tt(-) [ tt(-i) var(pats) ] [ tt(-s) var(pair) ] [ var(helpspec) ... ])( This function can be used to give a complete specification for completion for a command whose arguments follow standard UNIX option and argument -conventions. Options to tt(_arguments) itself must be in separate words, -i.e. tt(-s -w), not tt(-sw). +conventions. -When calling tt(_arguments), all var(spec)s that describe options of the -analyzed command line must precede all var(spec)s that describe non-option -(aka "normal") arguments of the analyzed line. To avoid ambiguity, all +Options to tt(_arguments) itself must be in separate words, i.e., tt(-s -w), +not tt(-sw). The options are followed by var(spec)s that describe options and +arguments of the analyzed command. var(spec)s that describe option flags must +precede var(spec)s that describe non-option ("positional" or "normal") +arguments of the analyzed line. To avoid ambiguity, all options to tt(_arguments) itself may be separated from the var(spec) forms by a single colon. -The tt(-s -w -W -A) and tt(-S) options describe how parsing of the command -line should proceed, and are discussed in context below. The `tt(-)tt(-)' +The `tt(-)tt(-)' form is used to intuit var(spec) forms from the help output of the command being analyzed, and is described in detail below. The var(opts) for the `tt(-)tt(-)' form are otherwise the same options as the first form. Note that `tt(-s)' following `tt(-)tt(-)' has a distinct meaning from `tt(-s)' preceding `tt(-)tt(-)', and both may appear. -With the option tt(-n), tt(_arguments) sets the parameter tt(NORMARG) +The options tt(-s), tt(-S), tt(-A) affect the parsing of the command line, +and are useful for commands with standard option parsing. + +The options of tt(_arguments) have the following meanings: + +startitem() +item(tt(-n))( +With this option, tt(_arguments) sets the parameter tt(NORMARG) to the position of the first normal argument in the tt($words) array, -i.e. the position after the end of the options. If that argument +i.e., the position after the end of the options. If that argument has not been reached, tt(NORMARG) is set to tt(-1). The caller should declare `tt(integer NORMARG)' if the tt(-n) option is passed; otherwise the parameter is not used. +) +item(tt(-s))( +Enable em(option stacking) for single-letter options, whereby multiple +single-letter options may be combined into a single word. For example, +the two options `tt(-)var(x)' and `tt(-)var(y)' may be combined into +a single word `tt(-)var(xy)'. By default, every word corresponds to a single +option name (the `tt(-xy)' option). -The option `tt(-M) var(matchspec)' sets a match specification to use to +Options beginning with a single hyphen or plus sign are eligible for stacking; +words beginning with two hyphens are not. +This is suitable for standard GNU options. + +Note that tt(-s) after tt(-)tt(-) has a different meaning, and is documented +below. +) +item(tt(-w))( +In combination with tt(-s), allow option stacking +even if one or more of the options take +arguments. For example, if tt(-x) takes an argument, with no +tt(-s), `tt(-xy)' is considered as a single (unhandled) option; with +tt(-s), tt(-xy) is an option with the argument `tt(y)'; with both tt(-s) +and tt(-w), tt(-xy) may be the option tt(-x) and the option tt(-y) with +arguments still to come. +) +item(tt(-W))( +This option takes tt(-w) a stage further: it is possible to +complete single-letter options even after an argument that occurs in the +same word. However, it depends on the action performed whether options +will really be completed at this point. For more control, use a +utility function like tt(_guard) as part of the action. +) +item(tt(-C))( +Modify the tt(curcontext) parameter for an action of the form `tt(->)var(state)'. +This is discussed in detail below. +) +item(tt(-R))( +Return status 300 instead of zero when a tt($state) is to +be handled, in the `tt(->)var(string)' syntax. +) +item(tt(-S))( +Do not complete options after a `tt(-)tt(-)' appearing on the line, +and ignore the `tt(-)tt(-)'. For example, with tt(-S), in the line + +example(foobar -x -- -y) + +the `tt(-x)' is considered an option, the `tt(-y)' is considered an +argument, and the `tt(-)tt(-)' is considered to be neither. +) +item(tt(-A) var(pat))( +Do not complete options after the first non-option +argument on the line. var(pat) is a pattern matching +all strings which are not to be taken as arguments. For example, to make +tt(_arguments) stop completing options after the first normal argument, but +ignoring all strings starting with a hyphen even if they are not described +by one of the var(optspec)s, the form is `tt(-A "-*")'. +) +item(tt(-O) var(name))( +Pass the elements of the array var(name) as arguments to functions called to +execute var(action)s. +This is discussed in detail below. +) +item(tt(-M) var(matchspec))( +Use var(matchspec) as the match specification to use to completion option names and values. The default var(matchspec) is: example(tt(r:|[_-]=* r:|=*)) -This allows partial word completion after `tt(_)' and `tt(-)', for example +which allows partial word completion after `tt(_)' and `tt(-)', for example `tt(-f-b)' can be completed to `tt(-foo-bar)'. +) +enditem() Each of the following forms is a var(spec) describing individual sets of options or arguments on the command line being analyzed. @@ -3601,26 +3671,6 @@ This describes an option. The colon indicates handling for one or more arguments to the option; if it is not present, the option is assumed to take no arguments. -By default, options are multi-character name, one `tt(-)var(word)' per -option. With tt(-s), options may be single characters, with more than -one option per word, although words starting with two hyphens, such as -`tt(-)tt(-prefix)', are still considered complete option names. This is -suitable for standard GNU options. - -The combination of tt(-s) with tt(-w) allows single-letter options to be -combined in a single word even if one or more of the options take -arguments. For example, if tt(-x) takes an argument, with no -tt(-s) `tt(-xy)' is considered as a single (unhandled) option; with -tt(-s) tt(-xy) is an option with the argument `tt(y)'; with both tt(-s) -and tt(-w), tt(-xy) may be the option tt(-x) and the option tt(-y) with -arguments still to come. - -The option tt(-W) takes this a stage further: it is possible to -complete single-letter options even after an argument that occurs in the -same word. However, it depends on the action performed whether options -will really be completed at this point. For more control, use a -utility function like tt(_guard) as part of the action. - The following forms are available for the initial var(optspec), whether or not the option has arguments. @@ -3682,23 +3732,6 @@ enditem() It is possible for options with a literal `tt(PLUS())' or `tt(=)' to appear, but that character must be quoted, for example `tt(-\+)'. -The options tt(-S) and tt(-A) are available to simplify the specifications -for commands with standard option parsing. With tt(-S), no option will be -completed after a `tt(-)tt(-)' appearing on its own on the line; this -argument will otherwise be ignored; hence in the line - -example(foobar -x -- -y) - -the `tt(-x)' is considered an option but the `tt(-y)' is considered an -argument, while the `tt(-)tt(-)' is considered to be neither. - -With tt(-A), no options will be completed after the first non-option -argument on the line. The tt(-A) must be followed by a pattern matching -all strings which are not to be taken as arguments. For example, to make -tt(_arguments) stop completing options after the first normal argument, but -ignoring all strings starting with a hyphen even if they are not described -by one of the var(optspec)s, the form is `tt(-A "-*")'. - Each var(optarg) following an var(optspec) must take one of the following forms: @@ -3772,9 +3805,9 @@ form below, the var(action) will be executed by calling the tt(_all_labels) function to process all tag labels. No special handling of tags is needed unless a function call introduces a new one. -The option `tt(-O) var(name)' specifies the name of an array whose elements -will be passed as arguments to functions called to execute var(action)s. -For example, this can be used to pass the same set of options for the +The functions called to execute var(action)s will be called with the the +elements of the array named by the `tt(-O) var(name)' option as arguments. +This can be used, for example, to pass the same set of options for the tt(compadd) builtin to all var(action)s. The forms for var(action) are as follows. -- 1.9.1 --tThc/1wpZn/ma/RB Content-Type: text/x-patch; charset=us-ascii Content-Disposition: attachment; filename="0002-_arguments-docs-Divide-into-subsections.patch" >>From 6ff7fb935d437b55c2bc94d8338332b80460a3a4 Mon Sep 17 00:00:00 2001 From: Daniel Shahaf Date: Wed, 15 Jul 2015 18:12:47 +0000 Subject: [PATCH 2/2] _arguments docs: Divide into subsections --- Doc/Zsh/compsys.yo | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 5fd8e24..a53de8b 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -3532,6 +3532,8 @@ This function can be used to give a complete specification for completion for a command whose arguments follow standard UNIX option and argument conventions. +em(Options overview) + Options to tt(_arguments) itself must be in separate words, i.e., tt(-s -w), not tt(-sw). The options are followed by var(spec)s that describe options and arguments of the analyzed command. var(spec)s that describe option flags must @@ -3632,6 +3634,8 @@ which allows partial word completion after `tt(_)' and `tt(-)', for example ) enditem() +em(var(spec)s: overview) + Each of the following forms is a var(spec) describing individual sets of options or arguments on the command line being analyzed. @@ -3799,6 +3803,8 @@ given by an array, and tt(_arguments) is called repeatedly for more specific contexts: on the first call `tt(_arguments $global_options)' is used, and on subsequent calls `tt(_arguments !$^global_options)'. +em(var(spec)s: actions) + In each of the forms above the var(action) determines how completions should be generated. Except for the `tt(->)var(string)' form below, the var(action) will be executed by calling the @@ -3951,6 +3957,8 @@ example(local curcontext="$curcontext") This is useful where it is not possible for multiple states to be valid together. +em(Specifying multiple sets of options) + It is possible to specify multiple sets of options and arguments with the sets separated by single hyphens. The specifications before the first hyphen (if any) are shared by all the remaining sets. @@ -3997,6 +4005,8 @@ A useful alternative is often an option specification with rest-arguments (as in `tt(-foo:*:...)'); here the option tt(-foo) swallows up all remaining arguments as described by the var(optarg) definitions. +em(Intuiting var(spec) forms from the help output) + The option `tt(-)tt(-)' allows tt(_arguments) to work out the names of long options that support the `tt(-)tt(-help)' option which is standard in many GNU commands. The command word is called with the argument @@ -4069,6 +4079,8 @@ as `tt(-)tt(-enable-foo)', but the script also accepts the negated form example(_arguments -- -s "LPAR()(#s)--enable- --disable-RPAR()") +em(Miscellaneous notes) + Finally, note that tt(_arguments) generally expects to be the primary function handling any completion for which it is used. It may have side effects which change the treatment of any matches added by other functions -- 1.9.1 --tThc/1wpZn/ma/RB--