Tcl Library Source Code

- Add switch to put parameters before switches
  - Some Tcl commands work this way
  - Examples: [chan copy], [zlib gunzip], [clock], [registry broadcast]
- 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
- Change from a result dict to a result array
  - Makes more complex validation expressions possible
  - If `-inline` is used, use [array get] to get the return value
- Allow validation expressions to see the result array, not just the switch or
  parameter being validated
  - Use [upvar] rather than [array get] and [array set] to expose the result
    array into the validation expression
  - Also use [upvar] to link the arg variable to the current value
  - Validation expressions can then be (ab)used to modify the results
  - Necessary to do validation expressions as a separate final pass
  - Still do enumeration immediately so their final result values will be
    reflected in the validation
- Allow enumerations to have validation expressions
  - No real reason why these two have to conflict
- 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
- Automatic command usage error message
  - Takes the place of Tcl\_WrongNumArgs()
- Single-character switch clustering
  - Requires use of `-long` for switches with multi-character names
- Reimplement in C for performance reasons
  - No bytecoding needed
  - Continue to maintain Tcl version for reference and portability
  - Provide stubs-enabled C API
  - One function for parsing definition list
  - One function for parsing argument list against preparsed definition list
  - Custom Tcl\_Obj type for preparsed definition list
- Test suite
  - Possibly the most daunting part of the project

<!-- vim: set sts=4 sw=4 tw=80 et ft=markdown: -->

[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 argument parser command named
[cmd argparse] capable of flexibly processing and validating 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}]

The [cmd argparse] command may have many complex features, but it is not
necessary to understand it in depth before using it for the most common tasks.
Its syntax is reasonably intuitive, so the best thing to do is see it in action
before reading the precise details on how it works.

[para]

Consider the following:

[example_begin]
% proc greet {args} {
      [cmd {argparse {
          {-salutation= -default hello}
          -modifier=
          -title
          subject
      }}]
      set msg [var {$salutation}]
      if {[lb]info exists [var title][rb]} {
          set msg [lb]string totitle $msg[rb]
      }
      if {[lb]info exists [var modifier][rb]} {
          append msg ", " [var {$modifier}]
      }
      append msg " " [var {$subject}]
  }
% [cmd {greet world}]
hello world
% [cmd {greet -salutation howdy world}]
howdy world
% [cmd {greet -title -mod "my dear" world}]
Hello, my dear world
% [cmd {greet -title}]
hello -title
[example_end]

This example demonstrates many of the [cmd argparse] core concepts and features.
The [cmd greet] command is defined to accept [const args].  When not explicitly
given an argument list to parse, [cmd argparse] parses the value of the
[const args] variable and stores the results into local variables having the
same [sectref Name names] as the various [sectref Element elements] of the
[sectref Definition definition].

[para]

Here, the definition is a list of four elements, named [var salutation],
[var modifier], [var title], and [var subject].  Because their names are
prefixed with "[option -]", [var salutation], [var modifier], and [var title]
are [sectref Switch switches], whereas [var subject], lacking a "[option -]"
prefix, is a [sectref Parameter parameter].  Two of the switches are given a
"[option =]" suffix, which means they each take an [sectref Argument argument],
whereas [var title] does not.  In addition to these [sectref Flag flag]
characters, the [var salutation] element is surrounded with braces because it
contains more list words used to further customize how it is handled.  Namely,
it uses the [option -default] [sectref {Element Switches} {element switch}] to
set its default value to [const hello], in case [option -salutation] is not
present in the argument list.

[para]

By default, switches are [sectref Optional optional] and parameters are
[sectref Required required].
[var salutation], [var modifier], and [var title], being switches, are all
optional, but since [var salutation] has a default value, its variable's
existence is therefore guaranteed.  Likewise, [var subject], being a parameter,
is required, and its variable's existence is also guaranteed.  On the contrary,
because [var modifier] and [var title] are optional and have no default value,
it is necessary to use [cmd {info exists}] to confirm their variables' existence
before attempting to read them.  Because [var title] does not accept an
argument, its variable's value (if the variable exists at all) is predefined to
be empty string.

[example_begin]
% [cmd {greet world}]
hello world
[example_end]

The first time [cmd greet] is called, it is given only one argument, which is
bound to the [var subject] parameter.  Normally, switch arguments appear to the
left of parameter arguments, and parameter arguments are bound first.  Thus, the
final argument to [cmd greet] is always bound to the [var subject] parameter,
even if it happens to resemble a switch, and is therefore stored in the
[var subject] variable.  Because their associated switches do not appear in the
argument list, the [var salutation] variable is set to its default value
([const hello]), and the [var modifier] and [var title] variables are unset due
to lacking a default.

[example_begin]
% [cmd {greet -salutation howdy world}]
howdy world
[example_end]

The second time [cmd greet] is called, it is given three arguments.  As
discussed above, the final argument ([const world]) is immediately stored into
the [var subject] variable before any switch processing occurs.  Next, the
remaining two arguments are examined and determined to be the name and value of
the [var salutation] switch.  Thus, the second argument ([const howdy]) is
stored in the [var salutation] variable.  The [var modifier] and [var title]
variables are unset.

[example_begin]
% [cmd {greet -title -mod "my dear" world}]
Hello, my dear world
[example_end]

The third time [cmd greet] is called, it is given four arguments.  The first is
[option -title], causing the [var title] variable to be set to empty string.
The second is the name of the [var modifier] switch.  More precisely, it is an
unambiguous prefix thereof, i.e. an abbreviation.  This causes the third
argument ([const {my dear}]) to be stored in the [var modifier] variable, and
the final argument ([const world]) is stored in the [var subject] variable.  As
for the [var salutation] variable, it is set to its default ([var hello]).

[example_begin]
% [cmd {greet -title}]
hello -title
[example_end]

The fourth time [cmd greet] is called, it is given one argument.  Because the
final argument is always bound to the [var subject] parameter, [var subject] is
set to [option -title] even though there happens to be a switch with the same
name.  There are no remaining arguments, so the switches are all handled
according to defaults, just like in the first call to [cmd greet].

[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
[sectref Element 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 [sectref Definition definition] contains any number of [term elements].  For
the most part, each element defines either a [sectref Switch switch] or a
[sectref Parameter parameter].  Elements may also be [sectref Comment comments]
or [sectref {Global Switch} {global switches}].  An element is itself a Tcl list
whose required first word is the [sectref Name name] (with optional shorthand
[sectref Alias aliases] and [sectref Flag flags]) and whose optional subsequent
words are [sectref {Element Switch} {element switches}].

[para]

In addition to switches and parameters, elements may be
[sectref Comment comments] or lists of
[sectref {Global Switch} {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 "[option -]" and
"[option =]" flags, as well as the [option -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 [sectref Alias aliases] and [sectref Flag flags], the first word of
each [sectref Switch switch] or [sectref Parameter parameter]
[sectref Element element] in the [sectref Definition 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 "[option #]", the element is a [sectref Comment 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 [sectref {Global Switch} {global switches}].

[subsection Key]

In addition to having a [sectref Name name], every [sectref Switch switch] and
[sectref Parameter parameter] [sectref Definition definition]
[sectref Element 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
[option -key] [sectref {Element Switch} {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 [sectref Definition definition] argument.  Global
switches may also be embedded within special definition
[sectref Element elements] whose [sectref Name name] is empty string.

[subsection {Element Switch}]

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

[para]

In the above example definition, each [sectref Switch switch] element explicitly
uses the [option -default] element switch.  Due to use of the "[option -]" and
"[option =]" shorthand [sectref Flag 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.

[subsection Required]

[subsection Optional]

[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 <[email protected]>

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

# argparse.tcl --
#
# Feature-heavy argument parsing package
#
# Copyright (C) 2019 Andy Goth <[email protected]>
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
package require Tcl 8.6
package provide argparse 0.5

# argparse --
# Parses an argument list according to a definition list.  The result may be
# stored into caller variables or returned as a dict.
#
# The [argparse] command accepts the following switches:
#
# -inline        Return the result dict rather than setting caller variables
# -exact         Require exact switch name matches, and do not accept prefixes
# -mixed         Allow switches to appear after parameters
# -long          Recognize "--switch" long option alternative syntax
# -equalarg      Recognize "-switch=arg" inline argument alternative syntax
# -normalize     Normalize switch syntax in pass-through result keys
# -reciprocal    Every element's -require constraints are reciprocal
# -level LEVEL   Every -upvar element's [upvar] level; defaults to 1
# -template TMP  Transform default element names using a substitution template
# -pass KEY      Pass unrecognized elements through to a result key
# -keep          Do not unset omitted element variables; conflicts with -inline
# -boolean       Treat switches as having -boolean wherever possible
# -validate DEF  Define named validation expressions to be used by elements
# -enum DEF      Define named enumeration lists to be used by elements
# --             Force next argument to be interpreted as the definition list
#
# After the above switches comes the definition list argument, then finally the
# optional argument list argument.  If the argument list is omitted, it is taken
# from the caller's args variable.
#
# A special syntax is provided allowing the above switches to appear within the
# definition list argument.  If an element of the definition list is a list
# whose first element is empty string, its subsequent elements are treated as
# additional overall switches to [argparse].
#
# Each element of the definition list is itself a list containing a unique,
# non-empty name element consisting of alphanumerics, underscores, and minus
# (not as the first character), then zero or more of the following switches:
#
# -switch        Element is a switch; conflicts with -parameter
# -parameter     Element is a parameter; conflicts with -switch
# -alias ALIAS   Alias name; requires -switch
# -ignore        Element is omitted from result; conflicts with -key and -pass
# -key KEY       Override key name; not affected by -template
# -pass KEY      Pass through to result key; not affected by -template
# -default VAL   Value if omitted; conflicts with -required and -keep
# -keep          Do not unset if omitted; requires -optional; conflicts -inline
# -value VAL     Value if present; requires -switch; conflicts with -argument
# -boolean       Equivalent to "-default 0 -value 1"
# -argument      Value is next argument following switch; requires -switch
# -optional      Switch value is optional, or parameter is optional
# -required      Switch is required, or stop -catchall from implying -optional
# -catchall      Value is list of all otherwise unassigned arguments
# -upvar         Links caller variable; conflicts with -inline and -catchall
# -level LEVEL   This element's [upvar] level; requires -upvar
# -standalone    If element is present, ignore -required, -require, and -forbid
# -require LIST  If element is present, other elements that must be present
# -forbid LIST   If element is present, other elements that must not be present
# -imply LIST    If element is present, extra switch arguments; requires -switch
# -reciprocal    This element's -require is reciprocal; requires -require
# -validate DEF  Name of validation expression, or inline validation definition
# -enum DEF      Name of enumeration list, or inline enumeration definition
#
# If the first (possibly only) word of a definition list element is the single
# character "#", the element is ignored.  If the definition list element is only
# one word long, the following element is ignored as well.  This may be used to
# place comments directly within the definition list.
#
# If neither -switch nor -parameter are used, a shorthand form is permitted.  If
# the name is preceded by "-", it is a switch; otherwise, it is a parameter.  An
# alias may be written after "-", then followed by "|" and the switch name.  The
# element name may be followed by any number of flag characters:
#
# "="            Same as -argument; only valid for switches
# "?"            Same as -optional
# "!"            Same as -required
# "*"            Same as -catchall
# "^"            Same as -upvar
#
# -default specifies the value to assign to element keys when the element is
# omitted.  If -default is not used, keys for omitted switches and parameters
# are omitted from the result, unless -catchall is used, in which case the
# default value for -default is empty string.
#
# At most one parameter may use -catchall.
#
# Multiple elements may share the same -key value if they are switches, do not
# use -argument or -catchall, and do not use -default for more than one element.
# Such elements are automatically are given -forbid constraints to prevent them
# from being used simultaneously.  If such an element does not use -boolean or
# -value, the element name is used as its default -value.
#
# -value specifies the value to assign to switch keys when the switch is
# present.  -value may not be used with -argument, -optional, -required, or
# -catchall.  -value normally defaults to empty string, except when -boolean is
# used (1 is the default -value) or multiple switches share the same -key (the
# element name is the default -value).
#
# -optional, -required, -catchall, and -upvar imply -argument when used with
# -switch.  Consequently, switches require an argument when any of the shorthand
# flag characters defined above are used, and it is not necessary to explicitly
# specify "=" if any of the other flag characters are used.
#
# If -argument is used, the value assigned to the switch's key is normally the
# next argument following the switch.  With -catchall, the value assigned to the
# switch's key is instead the list of all remaining arguments.  With -optional,
# the following processing is applied:
#
# - If the switch is not present, the switch's key is omitted from the result.
# - If the switch is not the final argument, its value is a two-element list
#   consisting of empty string and the argument following the switch.
# - If the switch is the final argument, its value is empty string.
#
# By default, switches are optional and parameters are required.  Switches can
# be made required with -required, and parameters can be made optional with
# -optional.  -catchall also makes parameters optional, unless -required is
# used, in which case at least one argument must be assigned to the parameter.
# Otherwise, using -required with -parameter has no effect.  -switch -optional
# -required means the switch must be present but may be the final argument.
#
# When -switch and -optional are both used, -catchall, -default, and -upvar are
# disallowed.  -parameter -optional -required is also a disallowed combination.
#
# -validate and -enum provide element value validation.  The overall -validate
# and -enum switches declare named validation expressions and enumeration lists,
# and the per-element -validate and -enum switches select which validation
# expressions and enumeration lists are used on which elements.  The argument to
# the overall -validate and -enum switches is a dict mapping from validation or
# enumeration name to validation expressions or enumeration lists.  The argument
# to a per-element -validate switch is a validation name or expression, and the
# argument to a per-element -enum switch is an enumeration name or list.  An
# element may not use both -validate and -enum.
#
# A validation expression is an [expr] expression parameterized on a variable
# named arg which is replaced with the argument.  If the expression evaluates to
# true, the argument is accepted.
#
# An enumeration list is a list of possible argument values.  If the argument
# appears in the enumeration list, the argument is accepted.  Unless -exact is
# used, if the argument is a prefix of exactly one element of the enumeration
# list, the argument is replaced with the enumeration list element.
#
# Unambiguous prefixes of switch names are acceptable, unless the -exact switch
# is used.  Switches in the argument list normally begin with a single "-" but
# can also begin with "--" if the -long switch is used.  Arguments to switches
# normally appear as the list element following the switch, but if -equalarg is
# used, they may be supplied within the switch element itself, delimited with an
# "=" character, e.g. "-switch=arg".
#
# The per-element -pass switch causes the element argument or arguments to be
# appended to the value of the indicated pass-through result key.  Many elements
# may use the same pass-through key.  If -normalize is used, switch arguments
# are normalized to not use aliases, abbreviations, the "--" prefix, or the "="
# argument delimiter; otherwise, switches will be expressed the same way they
# appear in the original input.  Furthermore, -normalize causes omitted switches
# that accept arguments and have default values, as well as omitted parameters
# that have default values, to be explicitly included in the pass-through key.
# If -mixed is used, pass-through keys will list all switches first before
# listing any parameters.  If the first parameter value for a pass-through key
# starts with "-", its value will be preceded by "--" so that it will not appear
# to be a switch.  If no arguments are assigned to a pass-through key, its value
# will be empty string.  The intention is that the value of a pass-through key
# can be parsed again to get the original data, and if -normalize is used, it
# will not be necessary to use -mixed, -long, -equalarg, -alias, or -default to
# get the correct result.  However, pathological use of -default can conflict
# with this goal.  For example, if the first optional parameter has no -default
# but the second one does, then parsing the result of -normalize can assign the
# default value to the first parameter rather than the second.
#
# The [argparse] -pass switch may be used to collect unrecognized arguments into
# a pass-through key, rather than failing with an error.  Normalization and
# unmixing will not be applied to these arguments because it is not possible to
# reliably determine if they are switches or parameters.  In particular, it is
# not known if an undefined switch expects an argument.
#
# [argparse] produces a set of keys and values.  The keys are the names of
# caller variables into which the values are stored, unless -inline is used, in
# which case the key-value pairs are returned as a dict.  The element names
# default to the key names, unless overridden by -key, -pass, or -template.  If
# both -key and -pass are used, two keys are defined: one having the element
# value, the other having the pass-through elements.  Unless -keep or -inline
# are used, the caller variables for omitted switches and parameters are unset.
#
# -template applies to elements using neither -key nor -pass.  Its value is a
# substitution template applied to element names to determine key names.  "%" in
# the template is replaced with the element name.  To protect "%" or "\" from
# replacement, precede it with "\".  One use for -template is to put the result
# in an array, e.g. with "-template arrayName(%)".
#
# Elements with -upvar are special.  Rather than having normal values, they are
# bound to caller variables using the [upvar] command.  -upvar conflicts with
# -inline because it is not possible to map a dict value to a variable.  Due to
# limitations of arrays and [upvar], -upvar cannot be used with keys whose names
# resemble array elements.  -upvar conflicts with -catchall because the value
# must be a variable name, not a list.  The combination -switch -optional -upvar
# is disallowed for the same reason.  If -upvar is used with switches or with
# optional parameters, [info exists KEY] returns 1 both when the element is not
# present and when its value is the name of a nonexistent variable.  To tell the
# difference, check if [info vars KEY] returns an empty list; if so, the element
# is not present.  Note that the argument to [info vars] is a [string match]
# pattern, so it may be necessary to precede *?[]\ characters with backslashes.
#
# Argument processing is performed in three stages: switch processing, parameter
# allocation, and parameter assignment.  Each argument processing stage and pass
# is performed left-to-right.
#
# All switches must normally appear in the argument list before any parameters.
# Switch processing terminates with the first argument (besides arguments to
# switches) that does not start with "-" (or "--", if -long is used).  The
# special switch "--" can be used to force switch termination if the first
# parameter happens to start with "-".  If no switches are defined, the first
# argument is known to be a parameter even if it starts with "-".
#
# When the -mixed switch is used, switch processing continues after encountering
# arguments that do not start with "-" or "--".  This is convenient but may be
# ambiguous in cases where parameters look like switches.  To resolve ambiguity,
# the special "--" switch terminates switch processing and forces all remaining
# arguments to be parameters.
#
# When -mixed is not used, the required parameters are counted, then that number
# of arguments at the end of the argument list are treated as parameters even if
# they begin with "-".  This avoids the need for "--" in many cases.
#
# After switch processing, parameter allocation determines how many arguments to
# assign to each parameter.  Arguments assigned to switches are not used in
# parameter processing.  First, arguments are allocated to required parameters;
# second, to optional, non-catchall parameters; and last to catchall parameters.
# Finally, each parameter is assigned the allocated number of arguments.
proc ::argparse {args} {
    # Common validation helper routine.
    set validateHelper {apply {{name opt args} {
        if {[dict exists $opt enum]} {
            set command [list tcl::prefix match -message "$name value"\
                    {*}[if {[uplevel 1 {info exists exact}]} {list -exact}]\
                    [dict get $opt enum]]
            set args [lmap arg $args {{*}$command $arg}]
        } elseif {[dict exists $opt validate]} {
            foreach arg $args [list if [dict get $opt validate] {} else {
                return -code error -level 2\
                        "$name value \"$arg\" fails [dict get $opt validateMsg]"
            }]
        }
        return $args
    }}}

    # Process arguments.
    set level 1
    set enum {}
    set validate {}
    for {set i 0} {$i < [llength $args]} {incr i} {
        if {[catch {
            regsub {^-} [tcl::prefix match -message switch {
                -boolean -enum -equalarg -exact -inline -keep -level -long
                -mixed -normalize -pass -reciprocal -template -validate
            } [lindex $args $i]] {} switch
        } msg]} {
            # Do not allow "--" or definition lists nested within the special
            # empty-string element containing extra overall switches.
            if {[info exists reparse]} {
                return -code error $msg
            }

            # Stop after "--" or at the first non-switch argument.
            if {[lindex $args $i] eq "--"} {
                incr i
            }

            # Extract definition and args from the argument list, pulling from
            # the caller's args variable if the args parameter is omitted.
            switch [expr {[llength $args] - $i}] {
            0 {
                break
            } 1 {
                set definition [lindex $args end]
                set argv [uplevel 1 {::set args}]
            } 2 {
                set definition [lindex $args end-1]
                set argv [lindex $args end]
            } default {
                return -code error "too many arguments"
            }}

            # Convert any definition list elements named empty string to instead
            # be overall switches, and arrange to reparse those switches.  Also,
            # remove inline comments from the definition list.
            set args {}
            set reparse {}
            set i -1
            foreach elem $definition[set definition {}] {
                if {[lindex $elem 0] eq "#"} {
                    if {[llength $elem] == 1} {
                        set comment {}
                    }
                } elseif {[info exists comment]} {
                    unset comment
                } elseif {[lindex $elem 0] eq {}} {
                    lappend args {*}[lrange $elem 1 end]
                } else {
                    lappend definition $elem
                }
            }
        } elseif {$switch ni {enum level pass template validate}} {
            # Process switches with no arguments.
            set $switch {}
        } elseif {$i == [llength $args] - 1} {
            return -code error "-$switch requires an argument"
        } else {
            # Process switches with arguments.
            set $switch [lindex $args [incr i]]
        }
    }

    # Fail if no definition argument was supplied.
    if {![info exists definition]} {
        return -code error "missing required parameter: definition"
    }

    # Forbid using -inline and -keep at the same time.
    if {[info exists inline] && [info exists keep]} {
        return -code error "-inline and -keep conflict"
    }

    # Parse element definition list.
    set def {}
    set aliases {}
    set order {}
    set switches {}
    set upvars {}
    set omitted {}
    foreach elem $definition {
        # Read element definition switches.
        set opt {}
        for {set i 1} {$i < [llength $elem]} {incr i} {
            if {[set switch [regsub {^-} [tcl::prefix match {
                -alias -argument -boolean -catchall -default -enum -forbid
                -ignore -imply -keep -key -level -optional -parameter -pass
                -reciprocal -require -required -standalone -switch -upvar
                -validate -value
            } [lindex $elem $i]] {}]] ni {
                alias default enum forbid imply key pass require validate value
            }} {
                # Process switches without arguments.
                dict set opt $switch {}
            } elseif {$i == [llength $elem] - 1} {
                return -code error "-$switch requires an argument"
            } else {
                # Process switches with arguments.
                incr i
                dict set opt $switch [lindex $elem $i]
            }
        }

        # Process the first element of the element definition.
        if {![llength $elem]} {
            return -code error "element definition cannot be empty"
        } elseif {[dict exists $opt switch] && [dict exists $opt parameter]} {
            return -code error "-switch and -parameter conflict"
        } elseif {[info exists inline] && [dict exists $opt keep]} {
            return -code error "-inline and -keep conflict"
        } elseif {![dict exists $opt switch] && ![dict exists $opt parameter]} {
            # If -switch and -parameter are not used, parse shorthand syntax.
            if {![regexp -expanded {
                ^(?:(-)             # Leading switch "-"
                (?:(\w[\w-]*)\|)?)? # Optional switch alias
                (\w[\w-]*)          # Switch or parameter name
                ([=?!*^]*)$         # Optional flags
            } [lindex $elem 0] _ minus alias name flags]} {
                return -code error "bad element shorthand: [lindex $elem 0]"
            }
            if {$minus ne {}} {
                dict set opt switch {}
            } else {
                dict set opt parameter {}
            }
            if {$alias ne {}} {
                dict set opt alias $alias
            }
            foreach flag [split $flags {}] {
                dict set opt [dict get {
                    = argument ? optional ! required * catchall ^ upvar
                } $flag] {}
            }
        } elseif {![regexp {^\w[\w-]*$} [lindex $elem 0]]} {
            return -code error "bad element name: [lindex $elem 0]"
        } else {
            # If exactly one of -switch or -parameter is used, the first element
            # of the definition is the element name, with no processing applied.
            set name [lindex $elem 0]
        }

        # Check for collisions.
        if {[dict exists $def $name]} {
            return -code error "element name collision: $name"
        }

        if {[dict exists $opt switch]} {
            # -optional, -required, -catchall, and -upvar imply -argument when
            # used with switches.
            foreach switch {optional required catchall upvar} {
                if {[dict exists $opt $switch]} {
                    dict set opt argument {}
                }
            }
        } else {
            # Parameters are required unless -catchall or -optional are used.
            if {([dict exists $opt catchall] || [dict exists $opt optional])
             && ![dict exists $opt required]} {
                dict set opt optional {}
            } else {
                dict set opt required {}
            }
        }

        # Check requirements and conflicts.
        foreach {switch other} {reciprocal require   level upvar} {
            if {[dict exists $opt $switch] && ![dict exists $opt $other]} {
                return -code error "-$switch requires -$other"
            }
        }
        foreach {switch others} {
            parameter {alias boolean value argument imply}
            ignore    {key pass}
            required  {boolean default}
            argument  {boolean value}
            upvar     {boolean inline catchall}
            boolean   {default value}
            enum      validate
        } {
            if {[dict exists $opt $switch]} {
                foreach other $others {
                    if {[dict exists $opt $other]} {
                        return -code error "-$switch and -$other conflict"
                    }
                }
            }
        }
        if {[dict exists $opt upvar] && [info exists inline]} {
            return -code error "-upvar and -inline conflict"
        }

        # Check for disallowed combinations.
        foreach combination {
            {switch optional catchall}
            {switch optional upvar}
            {switch optional default}
            {switch optional boolean}
            {parameter optional required}
        } {
            foreach switch [list {*}$combination {}] {
                if {$switch eq {}} {
                    return -code error "[join [lmap switch $combination {
                        string cat - $switch
                    }]] is a disallowed combination"
                } elseif {![dict exists $opt $switch]} {
                    break
                }
            }
        }

        # Replace -boolean with "-default 0 -value 1".
        if {([info exists boolean] && [dict exists $opt switch]
          && ![dict exists $opt argument] && ![dict exists $opt upvar]
          && ![dict exists $opt default] && ![dict exists $opt value]
          && ![dict exists $opt required]) || [dict exists $opt boolean]} {
            dict set opt default 0
            dict set opt value 1
        }

        # Insert default -level if -upvar is used.
        if {[dict exists $opt upvar] && ![dict exists $opt level]} {
            dict set opt level $level
        }

        # Compute default output key if -ignore, -key, and -pass aren't used.
        if {![dict exists $opt ignore] && ![dict exists $opt key]
         && ![dict exists $opt pass]} {
            if {[info exists template]} {
                dict set opt key [string map\
                        [list \\\\ \\ \\% % % $name] $template]
            } else {
                dict set opt key $name
            }
        }

        if {[dict exists $opt parameter]} {
            # Keep track of parameter order.
            lappend order $name

            # Forbid more than one catchall parameter.
            if {[dict exists $opt catchall]} {
                if {[info exists catchall]} {
                    return -code error "multiple catchall parameters:\
                            $catchall and $name"
                } else {
                    set catchall $name
                }
            }
        } elseif {![dict exists $opt alias]} {
            # Build list of switches.
            lappend switches -$name
        } elseif {![regexp {^\w[\w-]*$} [dict get $opt alias]]} {
            return -code error "bad alias: [dict get $opt alias]"
        } elseif {[dict exists $aliases [dict get $opt alias]]} {
            return -code error "element alias collision: [dict get $opt alias]"
        } else {
            # Build list of switches (with aliases), and link switch aliases.
            dict set aliases [dict get $opt alias] $name
            lappend switches -[dict get $opt alias]|$name
        }

        # Map from upvar keys back to element names, and forbid collisions.
        if {[dict exists $opt upvar] && [dict exists $opt key]} {
            if {[dict exists $upvars [dict get $opt key]]} {
                return -code error "multiple upvars to the same variable:\
                        [dict get $upvars [dict get $opt key]] $name"
            }
            dict set upvars [dict get $opt key] $name
        }

        # Look up named enumeration lists and validation expressions.
        if {[dict exists $opt enum]
         && [dict exists $enum [dict get $opt enum]]} {
            dict set opt enum [dict get $enum [dict get $opt enum]]
        } elseif {[dict exists $opt validate]} {
            if {[dict exists $validate [dict get $opt validate]]} {
                dict set opt validateMsg "[dict get $opt validate] validation"
                dict set opt validate [dict get $validate\
                        [dict get $opt validate]]
            } else {
                dict set opt validateMsg "validation: [dict get $opt validate]"
            }
        }

        # Save element definition.
        dict set def $name $opt

        # Prepare to identify omitted elements.
        dict set omitted $name {}
    }

    # Process constraints and shared key logic.
    dict for {name opt} $def {
        # Verify constraint references.
        foreach constraint {require forbid} {
            if {[dict exists $opt $constraint]} {
                foreach otherName [dict get $opt $constraint] {
                    if {![dict exists $def $otherName]} {
                        return -code error "$name -$constraint references\
                                undefined element: $otherName"
                    }
                }
            }
        }

        # Create reciprocal requirements.
        if {([info exists reciprocal] || [dict exists $opt reciprocal])
          && [dict exists $opt require]} {
            foreach other [dict get $opt require] {
                dict update def $other otherOpt {
                    dict lappend otherOpt require $name
                }
            }
        }

        # Perform shared key logic.
        if {[dict exists $opt key]} {
            dict for {otherName otherOpt} $def {
                if {$name ne $otherName && [dict exists $otherOpt key]
                 && [dict get $otherOpt key] eq [dict get $opt key]} {
                    # Limit when shared keys may be used.
                    if {[dict exists $opt parameter]} {
                        return -code error "$name cannot be a parameter because\
                                it shares a key with $otherName"
                    } elseif {[dict exists $opt argument]} {
                        return -code error "$name cannot use -argument because\
                                it shares a key with $otherName"
                    } elseif {[dict exists $opt catchall]} {
                        return -code error "$name cannot use -catchall because\
                                it shares a key with $otherName"
                    } elseif {[dict exists $opt default]
                           && [dict exists $otherOpt default]} {
                        return -code error "$name and $otherName cannot both\
                                use -default because they share a key"
                    }

                    # Create forbid constraints on shared keys.
                    if {![dict exists $otherOpt forbid]
                     || $name ni [dict get $otherOpt forbid]} {
                        dict update def $otherName otherOpt {
                            dict lappend otherOpt forbid $name
                        }
                    }

                    # Set default -value for shared keys.
                    if {![dict exists $opt value]} {
                        dict set def $name value $name
                    }
                }
            }
        }
    }

    # Handle default pass-through switch by creating a dummy element.
    if {[info exists pass]} {
        dict set def {} pass $pass
    }

    # Force required parameters to bypass switch logic.
    set end [expr {[llength $argv] - 1}]
    if {![info exists mixed]} {
        foreach name $order {
            if {[dict exists $def $name required]} {
                incr end -1
            }
        }
    }
    set force [lreplace $argv 0 $end]
    set argv [lrange $argv 0 $end]

    # Perform switch logic.
    set result {}
    set missing {}
    if {$switches ne {}} {
        # Build regular expression to match switches.
        set re ^-
        if {[info exists long]} {
            append re -?
        }
        append re {(\w[\w-]*)}
        if {[info exists equalarg]} {
            append re (?:(=)(.*))?
        } else {
            append re ()()
        }
        append re $

        # Process switches, and build the list of parameter arguments.
        set params {}
        while {$argv ne {}} {
            # Check if this argument appears to be a switch.
            set argv [lassign $argv arg]
            if {[regexp $re $arg _ name equal val]} {
                # This appears to be a switch.  Fall through to the handler.
            } elseif {$arg eq "--"} {
                # If this is the special "--" switch to end all switches, all
                # remaining arguments are parameters.
                set params $argv
                break
            } elseif {[info exists mixed]} {
                # If -mixed is used and this is not a switch, it is a parameter.
                # Add it to the parameter list, then go to the next argument.
                lappend params $arg
                continue
            } else {
                # If this is not a switch, terminate switch processing, and
                # process this and all remaining arguments as parameters.
                set params [linsert $argv 0 $arg]
                break
            }

            # Process switch aliases.
            if {[dict exists $aliases $name]} {
                set name [dict get $aliases $name]
            }

            # Preliminary guess for the normalized switch name.
            set normal -$name

            # Perform switch name lookup.
            if {[dict exists $def $name switch]} {
                # Exact match.  No additional lookup needed.
            } elseif {![info exists exact] && ![catch {
                tcl::prefix match -message switch [lmap {key data} $def {
                    if {[dict exists $data switch]} {
                        set key
                    } else {
                        continue
                    }
                }] $name
            } name]} {
                # Use the switch whose prefix unambiguously matches.
                set normal -$name
            } elseif {[dict exists $def {}]} {
                # Use default pass-through if defined.
                set name {}
            } else {
                # Fail if this is an invalid switch.
                set switches [lsort $switches]
                if {[llength $switches] > 1} {
                    lset switches end "or [lindex $switches end]"
                }
                set switches [join $switches\
                        {*}[if {[llength $switches] > 2} {list ", "}]]
                return -code error "bad switch \"$arg\": must be $switches"
            }

            # If the switch is standalone, ignore all constraints.
            if {[dict exists $def $name standalone]} {
                foreach other [dict keys $def] {
                    dict unset def $other required
                    dict unset def $other require
                    dict unset def $other forbid
                    if {[dict exists $def $other parameter]} {
                        dict set def $other optional {}
                    }
                }
            }

            # Keep track of which elements are present.
            dict set def $name present {}

            # If the switch value was set using -switch=value notation, insert
            # the value into the argument list to be handled below.
            if {$equal eq "="} {
                set argv [linsert $argv 0 $val]
            }

            # Load key and pass into local variables for easy access.
            unset -nocomplain key pass
            foreach var {key pass} {
                if {[dict exists $def $name $var]} {
                    set $var [dict get $def $name $var]
                }
            }

            # Keep track of which switches have been seen.
            dict unset omitted $name

            # Validate switch arguments and store values into the result dict.
            if {[dict exists $def $name catchall]} {
                # The switch is catchall, so store all remaining arguments.
                set argv [{*}$validateHelper $normal\
                        [dict get $def $name] {*}$argv]
                if {[info exists key]} {
                    dict set result $key $argv
                }
                if {[info exists pass]} {
                    if {[info exists normalize]} {
                        dict lappend result $pass $normal {*}$argv
                    } else {
                        dict lappend result $pass $arg {*}$argv
                    }
                }
                break
            } elseif {![dict exists $def $name argument]} {
                # The switch expects no arguments.
                if {$equal eq "="} {
                    return -code error "$normal doesn't allow an argument"
                }
                if {[info exists key]} {
                    if {[dict exists $def $name value]} {
                        dict set result $key [dict get $def $name value]
                    } else {
                        dict set result $key {}
                    }
                }
                if {[info exists pass]} {
                    if {[info exists normalize]} {
                        dict lappend result $pass $normal
                    } else {
                        dict lappend result $pass $arg
                    }
                }
            } elseif {$argv ne {}} {
                # The switch was given the expected argument.
                set argv0 [lindex [{*}$validateHelper $normal\
                        [dict get $def $name] [lindex $argv 0]] 0]
                if {[info exists key]} {
                    if {[dict exists $def $name optional]} {
                        dict set result $key [list {} $argv0]
                    } else {
                        dict set result $key $argv0
                    }
                }
                if {[info exists pass]} {
                    if {[info exists normalize]} {
                        dict lappend result $pass $normal $argv0
                    } elseif {$equal eq "="} {
                        dict lappend result $pass $arg
                    } else {
                        dict lappend result $pass $arg [lindex $argv 0]
                    }
                }
                set argv [lrange $argv 1 end]
            } else {
                # The switch was not given the expected argument.
                if {![dict exists $def $name optional]} {
                    return -code error "$normal requires an argument"
                }
                if {[info exists key]} {
                    dict set result $key {}
                }
                if {[info exists pass]} {
                    if {[info exists normalize]} {
                        dict lappend result $pass $normal
                    } else {
                        dict lappend result $pass $arg
                    }
                }
            }

            # Insert this switch's implied arguments into the argument list.
            if {[dict exists $def $name imply]} {
                set argv [concat [dict get $def $name imply] $argv]
                dict unset def $name imply
            }
        }

        # Build list of missing required switches.
        dict for {name opt} $def {
            if {[dict exists $opt switch] && ![dict exists $opt present]
             && [dict exists $opt required]} {
                if {[dict exists $opt alias]} {
                    lappend missing -[dict get $opt alias]|$name
                } else {
                    lappend missing -$name
                }
            }
        }

        # Fail if at least one required switch is missing.
        if {$missing ne {}} {
            set missing [lsort $missing]
            if {[llength $missing] > 1} {
                lset missing end "and [lindex $missing end]"
            }
            set missing [join $missing\
                    {*}[if {[llength $missing] > 2} {list ", "}]]
            return -code error [string cat "missing required switch"\
                    {*}[if {[llength $missing] > 1} {list es}] ": " $missing]
        }
    } else {
        # If no switches are defined, bypass the switch logic and process all
        # arguments using the parameter logic.
        set params $argv
    }

    # Allocate one argument to each required parameter, including catchalls.
    set alloc {}
    lappend params {*}$force
    set count [llength $params]
    set i 0
    foreach name $order {
        if {[dict exists $def $name required]} {
            if {$count} {
                dict set alloc $name 1
                dict unset omitted $name
                incr count -1
            } else {
                lappend missing $name
            }
        }
        incr i
    }

    # Fail if at least one required parameter is missing.
    if {$missing ne {}} {
        if {[llength $missing] > 1} {
            lset missing end "and [lindex $missing end]"
        }
        return -code error [string cat "missing required parameter"\
                {*}[if {[llength $missing] > 1} {list s}] ": "\
                [join $missing {*}[if {[llength $missing] > 2} {list ", "}]]]
    }

    # Try to allocate one argument to each optional, non-catchall parameter,
    # until there are no arguments left.
    if {$count} {
        foreach name $order {
            if {![dict exists $def $name required]
             && ![dict exists $def $name catchall]} {
                dict set alloc $name 1
                dict unset omitted $name
                if {![incr count -1]} {
                    break
                }
            }
        }
    }

    # Process excess arguments.
    if {$count} {
        if {[info exists catchall]} {
            # Allocate remaining arguments to the catchall parameter.
            dict incr alloc $catchall $count
            dict unset omitted $catchall
        } elseif {[dict exists $def {}]} {
            # If there is no catchall parameter, instead allocate to the default
            # pass-through result key.
            lappend order {}
            dict set alloc {} $count
        } else {
            return -code error "too many arguments"
        }
    }

    # Check constraints.
    dict for {name opt} $def {
        if {[dict exists $opt present]} {
            foreach {match condition description} {
                1 require requires 0 forbid "conflicts with"
            } {
                if {[dict exists $opt $condition]} {
                    foreach otherName [dict get $opt $condition] {
                        if {[dict exists $def $otherName present] != $match} {
                            foreach var {name otherName} {
                                if {[dict exists $def [set $var] switch]} {
                                    set $var -[set $var]
                                }
                            }
                            return -code error "$name $description $otherName"
                        }
                    }
                }
            }
        }
    }

    # If normalization is enabled, explicitly store into the pass-through keys
    # all omitted switches that have a pass-through key, accept an argument, and
    # have a default value.
    if {[info exists normalize]} {
        dict for {name opt} $def {
            if {[dict exists $opt switch] && [dict exists $opt pass]
             && [dict exists $opt argument] && [dict exists $opt default]
             && [dict exists $omitted $name]} {
                dict lappend result [dict get $opt pass]\
                        -$name [dict get $opt default]
            }
        }
    }

    # Validate parameters and store in result dict.
    set i 0
    foreach name $order {
        set opt [dict get $def $name]
        if {[dict exists $alloc $name]} {
            if {![dict exists $opt catchall] && $name ne {}} {
                set val [lindex [{*}$validateHelper $name\
                        $opt [lindex $params $i]] 0]
                if {[dict exists $opt pass]} {
                    if {[string index $val 0] eq "-"
                     && ![dict exists $result [dict get $opt pass]]} {
                        dict lappend result [dict get $opt pass] --
                    }
                    dict lappend result [dict get $opt pass] $val
                }
                incr i
            } else {
                set step [dict get $alloc $name]
                set val [lrange $params $i [expr {$i + $step - 1}]]
                if {$name ne {}} {
                    set val [{*}$validateHelper $name $opt {*}$val]
                }
                if {[dict exists $opt pass]} {
                    if {[string index [lindex $val 0] 0] eq "-"
                     && ![dict exists $result [dict get $opt pass]]} {
                        dict lappend result [dict get $opt pass] --
                    }
                    dict lappend result [dict get $opt pass] {*}$val
                }
                incr i $step
            }
            if {[dict exists $opt key]} {
                dict set result [dict get $opt key] $val
            }
        } elseif {[info exists normalize] && [dict exists $opt default]
               && [dict exists $opt pass]} {
            # If normalization is enabled and this omitted parameter has both a
            # default value and a pass-through key, explicitly store the default
            # value in the pass-through key, located in the correct position so
            # that it can be recognized again later.
            if {[string index [dict get $opt default] 0] eq "-"
             && ![dict exists $result [dict get $opt pass]]} {
                dict lappend result [dict get $opt pass] --
            }
            dict lappend result [dict get $opt pass] [dict get $opt default]
        }
    }

    # Create default values for missing elements.
    dict for {name opt} $def {
        if {[dict exists $opt key]
         && ![dict exists $result [dict get $opt key]]} {
            if {[dict exists $opt default]} {
                dict set result [dict get $opt key] [dict get $opt default]
            } elseif {[dict exists $opt catchall]} {
                dict set result [dict get $opt key] {}
            }
        }
        if {[dict exists $opt pass]
         && ![dict exists $result [dict get $opt pass]]} {
            dict set result [dict get $opt pass] {}
        }
    }

    if {[info exists inline]} {
        # Return result dict.
        return $result
    } else {
        # Unless -keep was used, unset caller variables for omitted elements.
        if {![info exists keep]} {
            dict for {name val} $omitted {
                set opt [dict get $def $name]
                if {![dict exists $opt keep] && [dict exists $opt key]
                 && ![dict exists $result [dict get $opt key]]} {
                    uplevel 1 [list ::unset -nocomplain [dict get $opt key]]
                }
            }
        }

        # Process results.
        dict for {key val} $result {
            if {[dict exists $upvars $key]} {
                # If this element uses -upvar, link to the named variable.
                uplevel 1 [list ::upvar\
                        [dict get $def [dict get $upvars $key] level] $val $key]
            } else {
                # Store result into caller variables.
                uplevel 1 [list ::set $key $val]
            }
        }
    }
}

# vim: set sts=4 sw=4 tw=80 et ft=tcl:

package ifneeded argparse 0.5 [list source [file join $dir argparse.tcl]]

[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]

Module  0compatibility _tcl  _null  _null
# Wrapper packages redirecting deprecated/moved packages to their old
# implementations. See pkgIndex.tcl for more notes.

#       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