Tcl Library Source Code

Check-in [2c12551d21]
Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Continue writing documentation
Timelines: family | ancestors | descendants | both | amg-argparse
Files: files | file ages | folders
SHA3-256: 2c12551d21209af0bb6ddb8a1af658af420592c582d56bbde2f777477c79b671
User & Date: andy 2019-04-26 17:51:10
Context
2019-04-26
17:51
Update to-do list Leaf check-in: 9064b9d02f user: andy tags: amg-argparse
17:51
Continue writing documentation check-in: 2c12551d21 user: andy tags: amg-argparse
2019-04-17
06:47
Begin writing documentation check-in: b40a9f709a user: andy tags: amg-argparse
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to modules/argparse/argparse.man.

    14     14   [usage [cmd argparse]\
    15     15       [opt [arg {-globalSwitch ...}]]\
    16     16       [opt [option --]]\
    17     17       [arg definition]\
    18     18       [opt [arg arguments]]]
    19     19   [description]
    20     20   
    21         -The [package argparse] package provides a powerful, feature-heavy argument
    22         -parser command named [cmd argparse] capable of flexibly processing many
    23         -varieties of switches and parameters.
           21  +The [package argparse] package provides a powerful argument parser command named
           22  +[cmd argparse] capable of flexibly processing and validating many varieties of
           23  +switches and parameters.
    24     24   
    25     25   [para]
    26     26   
    27     27   Tcl commands requiring more advanced argument parsing than provided by the
    28     28   standard [cmd proc] command can be declared to accept [const args] (i.e. any
    29     29   number of arguments), then can call [cmd argparse] to perform the real argument
    30     30   parsing.
................................................................................
    40     40   [cmd argparse] may be applied to a variety of special purposes beyond standard
    41     41   argument parsing.  For example, [cmd argparse] can parse custom variadic data
    42     42   structures formatted as lists of switches and/or parameters of a highly dynamic
    43     43   nature.  Another example: by calling [cmd argparse] multiple times, it is
    44     44   possible to parse nested or multi-part argument lists in which arguments to
    45     45   subsystems are embedded in passthrough switches or parameters.
    46     46   
    47         -[section {Quick Start Guide}]
    48         -
    49         -The [cmd argparse] command is featureful and complex, but it is not necessary to
    50         -understand it in depth before using it for simple tasks.
           47  +[section {Quick Start}]
           48  +
           49  +The [cmd argparse] command may have many complex features, but it is not
           50  +necessary to understand it in depth before using it for the most common tasks.
           51  +Its syntax is reasonably intuitive, so the best thing to do is see it in action
           52  +before reading the precise details on how it works.
           53  +
           54  +[para]
           55  +
           56  +Consider the following:
           57  +
           58  +[example_begin]
           59  +% proc greet {args} {
           60  +      [cmd {argparse {
           61  +          {-salutation= -default hello}
           62  +          -modifier=
           63  +          -title
           64  +          subject
           65  +      }}]
           66  +      set msg [var {$salutation}]
           67  +      if {[lb]info exists [var title][rb]} {
           68  +          set msg [lb]string totitle $msg[rb]
           69  +      }
           70  +      if {[lb]info exists [var modifier][rb]} {
           71  +          append msg ", " [var {$modifier}]
           72  +      }
           73  +      append msg " " [var {$subject}]
           74  +  }
           75  +% [cmd {greet world}]
           76  +hello world
           77  +% [cmd {greet -salutation howdy world}]
           78  +howdy world
           79  +% [cmd {greet -title -mod "my dear" world}]
           80  +Hello, my dear world
           81  +% [cmd {greet -title}]
           82  +hello -title
           83  +[example_end]
           84  +
           85  +This example demonstrates many of the [cmd argparse] core concepts and features.
           86  +The [cmd greet] command is defined to accept [const args].  When not explicitly
           87  +given an argument list to parse, [cmd argparse] parses the value of the
           88  +[const args] variable and stores the results into local variables having the
           89  +same [sectref Name names] as the various [sectref Element elements] of the
           90  +[sectref Definition definition].
           91  +
           92  +[para]
           93  +
           94  +Here, the definition is a list of four elements, named [var salutation],
           95  +[var modifier], [var title], and [var subject].  Because their names are
           96  +prefixed with "[option -]", [var salutation], [var modifier], and [var title]
           97  +are [sectref Switch switches], whereas [var subject], lacking a "[option -]"
           98  +prefix, is a [sectref Parameter parameter].  Two of the switches are given a
           99  +"[option =]" suffix, which means they each take an [sectref Argument argument],
          100  +whereas [var title] does not.  In addition to these [sectref Flag flag]
          101  +characters, the [var salutation] element is surrounded with braces because it
          102  +contains more list words used to further customize how it is handled.  Namely,
          103  +it uses the [option -default] [sectref {Element Switches} {element switch}] to
          104  +set its default value to [const hello], in case [option -salutation] is not
          105  +present in the argument list.
          106  +
          107  +[para]
          108  +
          109  +By default, switches are [sectref Optional optional] and parameters are
          110  +[sectref Required required].
          111  +[var salutation], [var modifier], and [var title], being switches, are all
          112  +optional, but since [var salutation] has a default value, its variable's
          113  +existence is therefore guaranteed.  Likewise, [var subject], being a parameter,
          114  +is required, and its variable's existence is also guaranteed.  On the contrary,
          115  +because [var modifier] and [var title] are optional and have no default value,
          116  +it is necessary to use [cmd {info exists}] to confirm their variables' existence
          117  +before attempting to read them.  Because [var title] does not accept an
          118  +argument, its variable's value (if the variable exists at all) is predefined to
          119  +be empty string.
          120  +
          121  +[example_begin]
          122  +% [cmd {greet world}]
          123  +hello world
          124  +[example_end]
          125  +
          126  +The first time [cmd greet] is called, it is given only one argument, which is
          127  +bound to the [var subject] parameter.  Normally, switch arguments appear to the
          128  +left of parameter arguments, and parameter arguments are bound first.  Thus, the
          129  +final argument to [cmd greet] is always bound to the [var subject] parameter,
          130  +even if it happens to resemble a switch, and is therefore stored in the
          131  +[var subject] variable.  Because their associated switches do not appear in the
          132  +argument list, the [var salutation] variable is set to its default value
          133  +([const hello]), and the [var modifier] and [var title] variables are unset due
          134  +to lacking a default.
          135  +
          136  +[example_begin]
          137  +% [cmd {greet -salutation howdy world}]
          138  +howdy world
          139  +[example_end]
          140  +
          141  +The second time [cmd greet] is called, it is given three arguments.  As
          142  +discussed above, the final argument ([const world]) is immediately stored into
          143  +the [var subject] variable before any switch processing occurs.  Next, the
          144  +remaining two arguments are examined and determined to be the name and value of
          145  +the [var salutation] switch.  Thus, the second argument ([const howdy]) is
          146  +stored in the [var salutation] variable.  The [var modifier] and [var title]
          147  +variables are unset.
          148  +
          149  +[example_begin]
          150  +% [cmd {greet -title -mod "my dear" world}]
          151  +Hello, my dear world
          152  +[example_end]
          153  +
          154  +The third time [cmd greet] is called, it is given four arguments.  The first is
          155  +[option -title], causing the [var title] variable to be set to empty string.
          156  +The second is the name of the [var modifier] switch.  More precisely, it is an
          157  +unambiguous prefix thereof, i.e. an abbreviation.  This causes the third
          158  +argument ([const {my dear}]) to be stored in the [var modifier] variable, and
          159  +the final argument ([const world]) is stored in the [var subject] variable.  As
          160  +for the [var salutation] variable, it is set to its default ([var hello]).
          161  +
          162  +[example_begin]
          163  +% [cmd {greet -title}]
          164  +hello -title
          165  +[example_end]
          166  +
          167  +The fourth time [cmd greet] is called, it is given one argument.  Because the
          168  +final argument is always bound to the [var subject] parameter, [var subject] is
          169  +set to [option -title] even though there happens to be a switch with the same
          170  +name.  There are no remaining arguments, so the switches are all handled
          171  +according to defaults, just like in the first call to [cmd greet].
    51    172   
    52    173   [section Concepts]
    53    174   
    54    175   This section lists and explains the concepts and terminology employed by the
    55    176   [package argparse] package.  The concepts are numerous and interrelated, so it
    56    177   may be necessary to read this section multiple times and to refer back to it
    57    178   while reading the remainder of this document.
    58    179   
    59    180   [subsection Definition]
    60    181   
    61    182   The [term definition] determines how the [cmd argparse] command parses its
    62    183   arguments.  Definitions are Tcl lists of any length, each word of which is an
    63         -[term element].
          184  +[sectref Element element].
    64    185   
    65    186   [para]
    66    187   
    67    188   The following example definition may conceivably be used by a command that
    68    189   stores a sequence of numbers into a variable.
    69    190   
    70    191   [example {
................................................................................
    76    197       # {Required output list variable}
    77    198       listVar^
    78    199   }
    79    200   }]
    80    201   
    81    202   [subsection Element]
    82    203   
    83         -A [term definition] contains any number of [term elements].  For the most part,
    84         -each element defines either a [term switch] or a [term parameter].  An element
    85         -is itself a Tcl list whose required first word is the [term name] (with optional
    86         -shorthand [term aliases] and [term flags]) and whose optional subsequent words
    87         -are [term {element switches}].
          204  +A [sectref Definition definition] contains any number of [term elements].  For
          205  +the most part, each element defines either a [sectref Switch switch] or a
          206  +[sectref Parameter parameter].  Elements may also be [sectref Comment comments]
          207  +or [sectref {Global Switch} {global switches}].  An element is itself a Tcl list
          208  +whose required first word is the [sectref Name name] (with optional shorthand
          209  +[sectref Alias aliases] and [sectref Flag flags]) and whose optional subsequent
          210  +words are [sectref {Element Switch} {element switches}].
    88    211   
    89    212   [para]
    90    213   
    91         -In addition to switches and parameters, elements may be [term comments] or lists
    92         -of [term {global switches}].
          214  +In addition to switches and parameters, elements may be
          215  +[sectref Comment comments] or lists of
          216  +[sectref {Global Switch} {global switches}].
    93    217   
    94    218   [para]
    95    219   
    96    220   The example definition shown above contains one parameter element, three switch
    97    221   elements, two comment elements, and no global switches.  All switch and
    98    222   parameter elements in the example make use of shorthand flags.
    99    223   
   100    224   [para]
   101    225   
   102    226   One element from the above example is repeated here so it may be examined more
   103    227   closely.
   104    228   
   105         -[example {{-from= -default 1}}]
          229  +[example {
          230  +    {-from= -default 1}
          231  +}]
   106    232   
   107         -The name of this element is [const from].  It uses the [const -] and [const =]
   108         -flags, as well as the [const -default] element switch with argument [const 1].
   109         -The specific meaning of flags and element switches are described elsewhere in
   110         -this document.
          233  +The name of this element is [const from].  It uses the "[option -]" and
          234  +"[option =]" flags, as well as the [option -default] element switch with
          235  +argument [const 1].  The specific meaning of flags and element switches are
          236  +described elsewhere in this document.
   111    237   
   112    238   [subsection Name]
   113    239   
   114         -Aside from [term aliases] and [term flags], the first word of each [term switch]
   115         -or [term parameter] [term element] in the [term definition] is the [term name].
          240  +Aside from [sectref Alias aliases] and [sectref Flag flags], the first word of
          241  +each [sectref Switch switch] or [sectref Parameter parameter]
          242  +[sectref Element element] in the [sectref Definition definition] is the
          243  +[term name].
   116    244   
   117    245   [para]
   118    246   
   119    247   Switch and parameter element names may not be used more than once within a
   120    248   definition.
   121    249   
   122    250   [para]
   123    251   
   124         -If the name is [const #], the element is a [term comment] and is ignored.  If
   125         -the name is empty string, the element is neither a switch nor a parameter and is
   126         -instead a list of [term {global switches}].
          252  +If the name is "[option #]", the element is a [sectref Comment comment] and is
          253  +ignored.  If the name is empty string, the element is neither a switch nor a
          254  +parameter and is instead a list of [sectref {Global Switch} {global switches}].
   127    255   
   128    256   [subsection Key]
   129    257   
   130         -In addition to having a [term name], every [term switch] and [term parameter]
   131         -[term definition] [term element] has a [term key].  Unlike names, multiple
   132         -elements may share the same key, subject to restrictions.
          258  +In addition to having a [sectref Name name], every [sectref Switch switch] and
          259  +[sectref Parameter parameter] [sectref Definition definition]
          260  +[sectref Element element] has a [term key].  Unlike names, multiple elements may
          261  +share the same key, subject to restrictions.
   133    262   
   134    263   [para]
   135    264   
   136         -By default, the key defaults to the name, but it is possible to use the [const\
   137         --key] [term {element switch}] to explicitly declare an element's key.
          265  +By default, the key defaults to the name, but it is possible to use the
          266  +[option -key] [sectref {Element Switch} {element switch}] to explicitly declare
          267  +an element's key.
   138    268   
   139    269   [para]
   140    270   
   141    271   Keys determine the variable names or dict keys [cmd argparse] uses to return the
   142    272   argument value of the switch or parameter.
   143    273   
   144    274   [subsection Alias]
................................................................................
   145    275   
   146    276   [subsection Flag]
   147    277   
   148    278   [subsection {Global Switch}]
   149    279   
   150    280   A [term {global switch}] configures the overall operation of the [cmd argparse]
   151    281   command.  Global switches are optional initial arguments to [cmd argparse] and
   152         -may only appear before the [term definition] argument.  Global switches may also
   153         -be embedded within special definition [term elements] whose [term name] is empty
   154         -string.
          282  +may only appear before the [sectref Definition definition] argument.  Global
          283  +switches may also be embedded within special definition
          284  +[sectref Element elements] whose [sectref Name name] is empty string.
   155    285   
   156    286   [subsection {Element Switch}]
   157    287   
   158         -An [term {element switch}] configures a single [term element] in the [term\
   159         -definition].  Element switches are listed following the the [term name] word of
   160         -the definition element.
          288  +An [term {element switch}] configures a single [sectref Element element] in the
          289  +[sectref Definition definition].  Element switches are listed following the the
          290  +[sectref Name name] word of the definition element.
   161    291   
   162    292   [para]
   163    293   
   164         -In the above example definition, each [term switch] element explicitly uses the
   165         -[option -default] element switch.  Due to use of the [option -] and [option =]
   166         -shorthand [term flags], each switch element also implicitly uses the [option\
   167         --switch] and [option -argument] element switches.
          294  +In the above example definition, each [sectref Switch switch] element explicitly
          295  +uses the [option -default] element switch.  Due to use of the "[option -]" and
          296  +"[option =]" shorthand [sectref Flag flags], each switch element also implicitly
          297  +uses the [option -switch] and [option -argument] element switches.
   168    298   
   169    299   [subsection Switch]
   170    300   
   171    301   [subsection Parameter]
   172    302   
   173    303   [subsection Comment]
   174    304   
   175    305   [subsection Argument]
   176    306   
   177    307   The actual values passed to the [cmd argparse] command to be parsed are known as
   178    308   arguments.
          309  +
          310  +[subsection Required]
          311  +
          312  +[subsection Optional]
   179    313   
   180    314   [section {Global Switches}]
   181    315   
   182    316   [list_begin options]
   183    317   
   184    318   [opt_def -inline]
   185    319   
................................................................................
   235    369   
   236    370   [opt_def -enum enumDef]
   237    371   
   238    372   Define named enumeration lists to be used by elements
   239    373   
   240    374   [opt_def --]
   241    375   
   242         -Force next argument to be interpreted as the definition list 
          376  +Force next argument to be interpreted as the definition list
   243    377   
   244    378   [list_end]
   245    379   
   246    380   [section {Element Switches}]
   247    381   
   248    382   [list_begin options]
   249    383   
................................................................................
   333    467   
   334    468   [opt_def -validate validNameOrDef]
   335    469   
   336    470   Name of validation expression, or inline validation definition
   337    471   
   338    472   [opt_def -enum enumNameOrDef]
   339    473   
   340         -Name of enumeration list, or inline enumeration definition 
          474  +Name of enumeration list, or inline enumeration definition
   341    475   
   342    476   [list_end]
   343    477   
   344    478   [section Shorthand]
   345    479   
   346    480   [subsection Aliases]
   347    481   
................................................................................
   357    491   
   358    492   [section {Return Value}]
   359    493   
   360    494   [include ../doctools2base/include/feedback.inc]
   361    495   
   362    496   [section Author]
   363    497   
   364         -Andy Goth
          498  +Andy Goth <[email protected]>
   365    499   
   366    500   [comment { vim: set sts=4 sw=4 tw=80 et ft=tcl: }]
   367    501   [manpage_end]