Tcl Library Source Code

- Remove `-boolean` 
  - Instead, act as if `-boolean` were always being passed to [argparse]
  - Remove `-keep` as well
  - Add an `-unset` switch to selectively change the behavior to unsetting a
    variable or omitting a dict key when the switch is not present
- Remove `-switch` and `-parameter`
  - Instead make `-` "shorthand" mandatory when declaring a switch
- Documentation
  - Instead of having a big comment, use doctools
- Help text generation
  - Parameter and switch descriptions given by per-element `-help` switch
  - Need overall `-help` switch to provide narrative description
  - May need special grouping elements to organize switches and parameters
  - Text formatting and word wrapping

[vset CATEGORY argparse]
[vset ARGPARSE_VERSION 0.4]
[manpage_begin argparse n [vset ARGPARSE_VERSION]]
[keywords {argument processing}]
[keywords argv]
[keywords argv0]
[keywords {cmdline processing}]
[keywords {command line processing}]
[see_also cmdline(n)]
[moddesc {Command switch and parameter parsing}]
[titledesc {Procedure for processing command switches and parameters.}]
[category {Programming tools}]
[require Tcl 8.6]
[usage [cmd argparse]\
    [opt [arg {-globalSwitch ...}]]\
    [opt [option --]]\
    [arg definition]\
    [opt [arg arguments]]]
[description]

The [package argparse] package provides a powerful, feature-heavy argument
parser command named [cmd argparse] capable of flexibly processing many
varieties of switches and parameters.

[para]

Tcl commands requiring more advanced argument parsing than provided by the
standard [cmd proc] command can be declared to accept [const args] (i.e. any
number of arguments), then can call [cmd argparse] to perform the real argument
parsing.

[para]

In addition to Tcl command argument parsing, [cmd argparse] is suitable for
command line argument parsing, operating on the value of the [var ::argv] global
variable.

[para]

[cmd argparse] may be applied to a variety of special purposes beyond standard
argument parsing.  For example, [cmd argparse] can parse custom variadic data
structures formatted as lists of switches and/or parameters of a highly dynamic
nature.  Another example: by calling [cmd argparse] multiple times, it is
possible to parse nested or multi-part argument lists in which arguments to
subsystems are embedded in passthrough switches or parameters.

[section {Quick Start Guide}]

The [cmd argparse] command is featureful and complex, but it is not necessary to
understand it in depth before using it for simple tasks.

[section Concepts]

This section lists and explains the concepts and terminology employed by the
[package argparse] package.  The concepts are numerous and interrelated, so it
may be necessary to read this section multiple times and to refer back to it
while reading the remainder of this document.

[subsection Definition]

The [term definition] determines how the [cmd argparse] command parses its
arguments.  Definitions are Tcl lists of any length, each word of which is an
[term element].

[para]

The following example definition may conceivably be used by a command that
stores a sequence of numbers into a variable.

[example {
{
    # {Optional sequence control switches}
    {-from= -default 1}
    {-to=   -default 10}
    {-step= -default 1}
    # {Required output list variable}
    listVar^
}
}]

[subsection Element]

A [term definition] contains any number of [term elements].  For the most part,
each element defines either a [term switch] or a [term parameter].  An element
is itself a Tcl list whose required first word is the [term name] (with optional
shorthand [term aliases] and [term flags]) and whose optional subsequent words
are [term {element switches}].

[para]

In addition to switches and parameters, elements may be [term comments] or lists
of [term {global switches}].

[para]

The example definition shown above contains one parameter element, three switch
elements, two comment elements, and no global switches.  All switch and
parameter elements in the example make use of shorthand flags.

[para]

One element from the above example is repeated here so it may be examined more
closely.

[example {{-from= -default 1}}]

The name of this element is [const from].  It uses the [const -] and [const =]
flags, as well as the [const -default] element switch with argument [const 1].
The specific meaning of flags and element switches are described elsewhere in
this document.

[subsection Name]

Aside from [term aliases] and [term flags], the first word of each [term switch]
or [term parameter] [term element] in the [term definition] is the [term name].

[para]

Switch and parameter element names may not be used more than once within a
definition.

[para]

If the name is [const #], the element is a [term comment] and is ignored.  If
the name is empty string, the element is neither a switch nor a parameter and is
instead a list of [term {global switches}].

[subsection Key]

In addition to having a [term name], every [term switch] and [term parameter]
[term definition] [term element] has a [term key].  Unlike names, multiple
elements may share the same key, subject to restrictions.

[para]

By default, the key defaults to the name, but it is possible to use the [const\
-key] [term {element switch}] to explicitly declare an element's key.

[para]

Keys determine the variable names or dict keys [cmd argparse] uses to return the
argument value of the switch or parameter.

[subsection Alias]

[subsection Flag]

[subsection {Global Switch}]

A [term {global switch}] configures the overall operation of the [cmd argparse]
command.  Global switches are optional initial arguments to [cmd argparse] and
may only appear before the [term definition] argument.  Global switches may also
be embedded within special definition [term elements] whose [term name] is empty
string.

[subsection {Element Switch}]

An [term {element switch}] configures a single [term element] in the [term\
definition].  Element switches are listed following the the [term name] word of
the definition element.

[para]

In the above example definition, each [term switch] element explicitly uses the
[option -default] element switch.  Due to use of the [option -] and [option =]
shorthand [term flags], each switch element also implicitly uses the [option\
-switch] and [option -argument] element switches.

[subsection Switch]

[subsection Parameter]

[subsection Comment]

[subsection Argument]

The actual values passed to the [cmd argparse] command to be parsed are known as
arguments.

[section {Global Switches}]

[list_begin options]

[opt_def -inline]

Return the result dict rather than setting caller variables

[opt_def -exact]

Require exact switch name matches, and do not accept prefixes

[opt_def -mixed]

Allow switches to appear after parameters

[opt_def -long]

Recognize "--switch" long option alternative syntax

[opt_def -equalarg]

Recognize "-switch=arg" inline argument alternative syntax

[opt_def -normalize]

Normalize switch syntax in passthrough result keys

[opt_def -reciprocal]

Every element's -require constraints are reciprocal

[opt_def -level levelSpec]

Every -upvar element's [lb]upvar[rb] level; defaults to 1

[opt_def -template templateString]

Transform default element names using a substitution template

[opt_def -pass passKey]

Pass unrecognized elements through to a result key

[opt_def -keep]

Do not unset omitted element variables; conflicts with -inline

[opt_def -boolean]

Treat switches as having -boolean wherever possible

[opt_def -validate validDef]

Define named validation expressions to be used by elements

[opt_def -enum enumDef]

Define named enumeration lists to be used by elements

[opt_def --]

Force next argument to be interpreted as the definition list 

[list_end]

[section {Element Switches}]

[list_begin options]

[opt_def -switch]

Element is a switch; conflicts with -parameter

[opt_def -parameter]

Element is a parameter; conflicts with -switch

[opt_def -alias aliasName]

Alias name; requires -switch

[opt_def -ignore]

Element is omitted from result; conflicts with -key and -pass

[opt_def -key keyName]

Override key name; not affected by -template

[opt_def -pass keyName]

Pass through to result key; not affected by -template

[opt_def -default value]

Value if omitted; conflicts with -required and -keep

[opt_def -keep]

Do not unset if omitted; requires -optional; conflicts -inline

[opt_def -value value]

Value if present; requires -switch; conflicts with -argument

[opt_def -boolean]

Equivalent to "-default 0 -value 1"

[opt_def -argument]

Value is next argument following switch; requires -switch

[opt_def -optional]

Switch value is optional, or parameter is optional

[opt_def -required]

Switch is required, or stop -catchall from implying -optional

[opt_def -catchall]

Value is list of all otherwise unassigned arguments

[opt_def -upvar]

Links caller variable; conflicts with -inline and -catchall

[opt_def -level levelSpec]

This element's [lb]upvar[rb] level; requires -upvar

[opt_def -standalone]

If element is present, ignore -required, -require, and -forbid

[opt_def -require nameList]

If element is present, other elements that must be present

[opt_def -forbid nameList]

If element is present, other elements that must not be present

[opt_def -imply argList]

If element is present, extra switch arguments; requires -switch

[opt_def -reciprocal]

This element's -require is reciprocal; requires -require

[opt_def -validate validNameOrDef]

Name of validation expression, or inline validation definition

[opt_def -enum enumNameOrDef]

Name of enumeration list, or inline enumeration definition 

[list_end]

[section Shorthand]

[subsection Aliases]

[subsection Flags]

[section Validation]

[section Passthrough]

[section {Upvar Elements}]

[section {Argument Processing Sequence}]

[section {Return Value}]

[include ../doctools2base/include/feedback.inc]

[section Author]

Andy Goth

[comment { vim: set sts=4 sw=4 tw=80 et ft=tcl: }]
[manpage_end]

[manpage_begin cmdline n 1.5]
[keywords {argument processing}]
[keywords argv]
[keywords argv0]
[keywords {cmdline processing}]
[keywords {command line processing}]
[see_also argparse(n)]
[moddesc   {Command line and option processing}]
[titledesc {Procedures to process command lines and options.}]
[category  {Programming tools}]
[require Tcl 8.2]
[require cmdline [opt 1.3.3]]
[description]

Exclude calendar
Exclude exif

#       name         pkg   doc   example
Module  aes         _tcl  _man  _null
Module  amazon-s3   _tcl  _man  _null
Module  argparse    _tcl  _man  _null
Module  asn         _tcl  _man  _null
Module  base32      _tcl  _man  _null
Module  base64      _tcl  _man  _null
Module  bee         _tcl  _man  _null
Module  bench       _tcl _null  _null
Module  bibtex      _tcl  _man  _exa
Module  blowfish    _tcl  _man  _null