argparse

This is a fork of argparse project initially developed by Andy Goth mailto:andrew.m.goth@gmail.com.

See original repository, and wiki page.

Starting from 0.6 version, the base implementation is in C. Tcl-only version is still availible and will be availible in future with the same feature set. C version in order of magnitude faster than Tcl-only version due to cashing of the parsed once argument definition.

Installation

You have two ways: install from git repo (convinient for Linux users) or from archive package release.

Additionaly, package was added into “batteries included” Magicsplat distribution of Tcl8.6 and Tcl9.0.

From git repo

To install default C implementation, run following commands:

  • git clone https://github.com/georgtree/argparse.git

  • ./configure

  • sudo make install

During installation manpages are also installed.

For test package in place run make test.

For package uninstall run sudo make uninstall.

To install Tcl-only version, the sequence is the same, except the flag --enable-tcl-only provided to ./configure script.

From archive

To install the package you should extract archive with source code and add path of the package folder to auto_path variable:

lappend auto_path "path to argparse package"
package require argparse

There are two pre-compiled version: for Linux x86-64 and for Windows x86-64 UCRT. Both archives provide C and Tcl-only versions, you can select the version you need in pkgIndex.tcl by conditional statement.

Synopsys

package require Tcl 8.6-
package require textutil::adjust
argparse ?-globalSwitch ...? ?--? definition ?arguments?

Description

The argparse package provides a powerful argument parser command named argparse capable of flexibly processing and validating many varieties of switches and parameters.

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

In addition to Tcl command argument parsing, argparse is suitable for command line argument parsing, operating on the value of the ::argv global variable. To use it with argparse, you should provide argv as an argument to procedure after definition.

argparse may be applied to a variety of special purposes beyond standard argument parsing. For example, argparse can parse custom variadic data structures formatted as lists of switches and/or parameters of a highly dynamic nature. Another example: by calling 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.

Quick Start

The 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.

Consider the following:

package require argparse
proc greet {args} {
    argparse {
        {-salutation= -default hello}
        -modifier=
        -title
        subject
    }
    set msg $salutation
    if {[info exists title]} {
        set msg [string totitle $msg]
    }
    if {[info exists modifier]} {
        append msg ", " $modifier
    }
    append msg " " $subject
}

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

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

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

greet world
==> hello world

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

greet -salutation howdy world
==> howdy world

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

greet -title -mod "my dear" world
==> Hello, my dear world

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

greet -title
==> hello -title

The fourth time greet is called, it is given one argument. Because the final argument is always bound to the subject parameter, subject is set to -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 greet.

Concepts

This section lists and explains the concepts and terminology employed by the 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.

Argument

The actual values passed to the argparse command to be parsed are known as arguments. There are two ways of providing arguments, via local variable args of current scope procedure, or explicitly as an argument after definition.

Definition

The definition determines how the argparse command parses its arguments. Definitions are Tcl lists of any length, each word of which is an element. Each definition contains a unique, non-empty name element consisting of alphanumerics, underscores, and minus (not as the first character), then zero or more of the element switches

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

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

The example of such procedure is source:

proc genNums {args} {
    argparse {
        # {Optional sequence control switches}
        {-from= -default 1}
        {-to=   -default 10}
        {-step= -default 1}
        {-prec= -default 1}
        # {Required output list variable}
        listVar^
    }
    if {$step < 0} {
        set op ::tcl::mathop::>
    } else {
        set op ::tcl::mathop::<
    }
    for {set n $from} {[$op $n $to]} {set n [expr {$n + $step}]} {
        lappend listVar [format %.*f $prec $n]
    }
}
genNums -from 0 -to 10 -step 2 sequenceVar
puts $sequenceVar
0.0 2.0 4.0 6.0 8.0

In this example procedure definition {-prec= -default 1} is added and defines precision of resulted sequence of numbers. Instead of returning value via return command we save resulted list directly in variable of caller scope sequenceVar.

Global Switch

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

Element

A definition contains any number of elements. For the most part, each element defines either a switch or a parameter. Elements may also be comments or global switches. An element is itself a Tcl list whose required first word is the name (with optional shorthand aliases and flags] and whose optional subsequent words are element switches.

In addition to switches and parameters, elements may be comments or lists of global switches.

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.

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

{-from= -default 1}

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

Element Switch

An element switch configures a single element in the definition. Element switches are listed following the name word of the definition element.

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

Name

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

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

If the name is #, the element is a 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 global switches.

Key

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

By default, the key defaults to the name, but it is possible to use the -key element switch to explicitly declare an element’s key.

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

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.

Switch

Switch is the optional element, that could be made mandatory with -required element switch. It could be defined either with shorthand - before name or with -switch element switch.

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.

When -switch and -optional are both used, -catchall, -default, and -upvar are disallowed.

Parameter

Parameter is the mandatory element that is provided without any preceding flags before name, and it’s position in the list of definitions is the same as it must be passed to argparse procedure.

In definition list it is also could be explicitly stated with -parameter element switch. 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.

Value

Value is the argument that is passed into variable (or dictionary value) for particular parameter or switch if it is defined with -argument or shorthand = after switch name. -optional, -required, -catchall, and -upvar imply -argument when used with -switch. Consequently, switches require an argument when any of the shorthand flag characters 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.

We can also explicitly specify particular value which is assigned to switch key whet switch is presented is present with -value after switch name in definition.

-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).

Alias

Alias is the alternative name of the switch element. It can be provided by -alias ALIAS element switch, or before the base name with | shorthand flag, but after - flag. For example:

{-variable= -alias var -required}

or

{-var|variable= -required}

Also supported multiple aliases for single switch, for example:

{-variable= -alias {var v} -required}

or

{-var|v|variable= -required}

The name of the element is the last name in the list of aliases, if it is provided via shorhand syntax.

Shorthand flag

If neither -switch nor -parameter are used, a shorthand flag 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:

Shorthand flag

Description

=

Same as -argument; only valid for switches

?

Same as -optional

!

Same as -required

*

Same as -catchall

^

Same as -upvar

Comment

Comment is the element started with # at the start of definition in the definition list.

Global Switches

Switch

Description

-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

-pfirst

Set required parameters to appear before switches; conflicts with -mixed

-long

Recognize --switch long option alternative syntax

-equalarg

Recognize -switch=arg inline argument alternative syntax

-normalize

Normalize switch syntax in passthrough result keys

-reciprocal

Every element’s -require constraints are reciprocal

-level levelSpec

Every -upvar element’s [upvar] level; defaults to 1

-template templateString

Transform default element names using a substitution template

-pass passKey

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

-transform commandPrefix

Default value transformation for eligible elements

-validate validDef

Define named validation expressions to be used by elements

-enum enumDef

Define named enumeration lists to be used by elements

-help description

Enable help message generating when -help argument is provided

-helplevel value

Set -level option for return command in help evaluation

-synopsis text

Override the argument synopsis; requires -help

-synopsiscmd command

Override the displayed command name; requires -help

-helpret

Set to return help message as a return value of procedure instead of putting into stdout

--

Force next argument to be interpreted as the definition list

Help Return Depth

The Tcl and native implementations use the same -helplevel convention. The default is 2: stop parsing, return from the procedure or constructor that called argparse, and skip its remaining body. The level includes the argparse procedure itself, even when using the native implementation.

  • 1: stop parsing and return to the caller, which continues after the argparse call.

  • 2 (default): return from the immediate calling procedure, method or constructor.

  • 3: return through two calling procedures or methods.

Without -helpret, help is printed to stdout and the result is empty. With -helpret, help is returned as the result at the requested depth. Help ignores required arguments and does not assign parsed variables. Zero, negative, noninteger and out-of-range levels are errors.

Earlier native versions did not account for the Tcl implementation’s procedure frame. If native-only calling code used -helplevel 1 to exit its own procedure, use the default 2 instead. More generally, increase an explicit positive level by one when preserving that earlier native behavior. Replace earlier -helplevel 0 uses with -helplevel 1 to return to the caller without exiting it.

Element Switches

Switch

Description

-switch

Element is a switch; conflicts with -parameter

-parameter

Element is a parameter; conflicts with -switch

-alias aliasName

Alias names; requires -switch

-ignore

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

-key keyName

Override key name; not affected by -template

-pass keyName

Pass through to result key; not affected by -template

-default value

Value if omitted; conflicts with -required and -keep

-keep

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

-value value

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 levelSpec

This element’s [upvar] level; requires -upvar

-standalone

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

-require nameList

If element is present, other elements that must be present

-forbid nameList

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

-allow nameList

If element is present, other elements that is not in the nameList must not be present

-multiple

Collect repeated argument-taking switch values into a list

-exclusive

No-argument abbreviation for -allow {}; no other elements may be present

-imply argList

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

-reciprocal

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

-transform commandPrefix

Transform accepted values before storing them

-action commandPrefix

Invoke a callback instead of assigning a caller variable

-withname

Pass the canonical element name before the callback value

-validate validNameOrDef

Name of validation expression, or inline validation definition

-errormsg message

Custom error message that replaces the default one; requires -validate

-enum enumNameOrDef

Name of enumeration list, or inline enumeration definition

-type typeName

Validate value according to type defined in string command, requires -argument

-help description

Provide description to element that is displayed when help message is generated

-hsuppress

Suppress help generation for certain element

Collecting unassigned arguments

With -catchall element switch, we can collects the rest of otherwise unassigned arguments to list and save to switch’s key. Let’s consider next example:

proc applyOperator {args} {
    argparse {
        {-op= -enum {+ *}}
        {-elements= -catchall}
    }
    set result [lindex $elements 0]
    foreach element [lrange $elements 1 end] {
        set result [::tcl::mathop::$op $result $element]
    }
    return $result
}

applyOperator -op * -elements 1 2 3 4 5
==> 120

This procedure make summation or product of all arguments passed after -elements switch with -catchall element switch. There is also an example of using -enum switch to validate possible values of argument to -op switch.

At most one parameter may use -catchall.

Default values

Element switch -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.

Validation

-validate and -enum provide element value validation. The global -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 global -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. Let’s consider the example:

proc exponentiation {args} {
    argparse {
        {-b!= -validate {[string is double $arg]}}
        {-n!= -validate {[string is double $arg]}}
    }
    return [expr {$b**$n}]
}

exponentiation -b 2 -n 4
==> 16

This simple function return exponentiation of number b in n. Our simple tests verify that the arguments are strings that could be considered as floating numbers, and only after that set the corresponding variables.

If wrong string is provided, a error message appears:

exponentiation -b a -n 4
-b value "a" fails validation: [string is double $arg]
while executing
"argparse {
    {-b!= -validate {[string is double $arg]}}
    {-n!= -validate {[string is double $arg]}}
}"
(procedure "exponentiation" line 2)

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.

Additional built-in validation of argument is done with help of string command. All types (classes) are supported except true and false class. To declare type of argument, the switch -type should be provided to definition of switch or parameter with one of the argument: alnum alpha ascii boolean control dict digit double graph integer list lower print punct space upper wideinteger wordchar xdigit. If you specify type for switch, the switch should be defined with -argument (or = shorthand). Conflicts with -upvar, -boolean and -enum, combination of -switch, -optional and type is forbidden.

As an example, we can use previously proposed procedure:

proc genNums {args} {
    argparse {
        # {Optional sequence control switches}
        {-from= -default 1 -type double}
        {-to=   -default 10 -type double}
        {-step= -default 1 -type double}
        {-prec= -default 1 -type double}
        # {Required output list variable}
        listVar^
    }
    if {$step < 0} {
        set op ::tcl::mathop::>
    } else {
        set op ::tcl::mathop::<
    }
    for {set n $from} {[$op $n $to]} {set n [expr {$n + $step}]} {
        lappend listVar [format %.*f $prec $n]
    }
}

If we provide the wrong argument type to genNums procedure, the error occurs:

genNums -from 0 -to 10.. -step 2 sequenceVar
-to value "10.." is not of the type double
while executing
"argparse {
    # {Optional sequence control switches}
    {-from= -default 1 -type double}
    {-to=   -default 10 -type double}
    {..."
(procedure "genNums" line 2)

For -validation switch the custom error message could be provided by element switch -errormsg. For substitution, arg and name variables are availible, as well as internal dictionary opt that contains processed definition of element. For example, the previously defined procedure could be rewritted with custom error messages:

proc exponentiation {args} {
    argparse {
        {-b!= -validate {[string is double $arg]} -errormsg {Value of switch '$name' must be double, '$arg' was provided}}
        {-n!= -validate {[string is double $arg]} -errormsg {Value of switch '$name' must be double, '$arg' was provided}}
    }
    return [expr {$b**$n}]
}

exponentiation -b 2 -n 4t
Value of switch '-n' must be double, '4t' was provided
while executing
"argparse {
    {-b!= -validate {[string is double $arg]} -errormsg {Value of switch '$name' must be double, '$arg' was provided}}
    {-n!= -v..."
(procedure "exponentiation" line 2)

Forbid

If the presence of an element should be forbidden in combination with certain other elements, use the -forbid switch followed by a list of element names. In next example, we can forbid using arguments that logically incompatible:

proc sheduleEvent {args} {
    set arguments [argparse -inline -validate [dict create date {[regexp {^(0[1-9]|[12][0-9]|3[01])-(0[1-9]|1[0-2])-\d{4}$} $arg]} time {[regexp {^([01][0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9])?$} $arg]}] {
        {date -validate date}
        {time -validate time}
        {-allday -forbid {duration endtime}}
        {-duration= -forbid {allday endtime} -validate time}
        {-endtime= -forbid {allday duration} -validate time}
    }]
    if {![dict exists $arguments allday] && ![dict exists $arguments duration] && ![dict exists $arguments endtime]} {
        return -code error "One of the switch must be presented: -allday, -duration or -endtime"
    }
    return $arguments
}

This procedure provides template for sheduling event. As input, date in format DD-MM-YYYY and time in format HH:MM of the event provides as parameters, and the duration of the event could be provided by different mutually exclusively switches:

switch name

description

-allday

select the duration of event to the end of the day

-duration

set duration of the event in format HH:MM

-endtime

set end time of the event in format HH:MM

Additionaly, the validation expressions for the date format and time format regular expression is used. These expression are supplied as named expressions in dictionary argument to global switch -validate.

One of the switches -allday, -duration or -endtime must be presented, so additional checking is done after argument processing.

Normal operation:

sheduleEvent -duration 01:30 20-12-2024 13:30
==> duration 01:30 date 20-12-2024 time 13:30

Error is issued in case of providing conflicting switches:

sheduleEvent -allday -duration 01:30 20-12-2024 13:30
-allday conflicts with -duration
while executing
"argparse -inline -validate [dict create date {[regexp {^(0[1-9]|[12][0-9]|3[01])-(0[1-9]|1[0-2])-\d{4}$} $arg]} time {[regexp {^([01][0-9]|2[0-3]):[0-..."
(procedure "sheduleEvent" line 2)

Allow

Element switch -allow is inverse of -forbid switch. Only elements from definition list could be presented if element is presented. As an example, we can use previous procedure but now implemented with -allow instead of forbid:

proc sheduleEvent {args} {
    set arguments [argparse -inline -validate [dict create date {[regexp {^(0[1-9]|[12][0-9]|3[01])-(0[1-9]|1[0-2])-\d{4}$} $arg]} time {[regexp {^([01][0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9])?$} $arg]}] {
        {date -validate date}
        {time -validate time}
        {-allday -allow {date time}}
        {-duration= -allow {date time} -validate time}
        {-endtime= -allow {date time} -validate time}
    }]
    if {![dict exists $arguments allday] && ![dict exists $arguments duration] && ![dict exists $arguments endtime]} {
        return -code error "One of the switch must be presented: -allday, -duration or -endtime"
    }
    return $arguments
}

Normal operation:

sheduleEvent -duration 01:30 20-12-2024 13:30
==> duration 01:30 date 20-12-2024 time 13:30

Error is issued in case of providing conflicting switches:

sheduleEvent -allday -duration 01:30 20-12-2024 13:30
allday doesn't allow duration
while executing
"argparse -inline -validate [dict create date {[regexp {^(0[1-9]|[12][0-9]|3[01])-(0[1-9]|1[0-2])-\d{4}$} $arg]} time {[regexp {^([01][0-9]|2[0-3]):[0-..."
(procedure "sheduleEvent" line 2)

Value transformations and actions

Use -transform commandPrefix to convert an accepted input value before it is stored. The prefix is a Tcl list: by default argparse appends the value as one final word and invokes that command in the caller’s frame. It can name a procedure, a built-in command, an ensemble subcommand, or an apply lambda.

argparse -inline {
    {-colour= -enum {red green blue} -transform {string toupper}}
    {-count= -type integer -validate {$arg > 0} -transform {apply {{value} {expr {$value * 2}}}}}
} {-colour gr -count 3}
# Returns: colour GREEN count 6

Enumeration expansion, -validate, and -type checks happen before the callback. The callback receives the accepted value; its return value is stored without further validation and may have a different type. An error in validation prevents the callback for that value from running.

A global -transform commandPrefix supplies the default transformation for argument-taking switches and positional parameters. An element’s -transform overrides it; -transform {} explicitly disables it. Argument-free switches and -upvar elements do not inherit the global transformation.

argparse -inline -transform {string trim} {
    -title=
    {-code= -transform {string toupper}}
    {-literal= -transform {}}
} {-title {  hello  } -code abc -literal {  unchanged  }}
# Returns: title hello code ABC literal {  unchanged  }

Use the element option -action commandPrefix when the callback itself handles the value, for example by calling an object’s configuration method. In ordinary mode argparse neither sets nor unsets that element’s caller variable, including when the element is omitted or has a default. With -inline, the callback return value is included under the element’s result key. -key changes that key as usual. An action overrides the global transformation. Explicit -action and -transform on the same element conflict; an action prefix must not be empty.

oo::class create Settings {
    variable settings
    constructor {} {
        set settings {}
    }
    method configure {key value} {
        dict set settings $key $value
        return $value
    }
    method parse {args} {
        argparse {
            {-colour= -enum {red green blue} -action {my configure colour}}
        }
        return $settings
    }
}
set object [Settings new]
$object parse -colour gr
# Returns: colour green
$object destroy
Settings destroy

The prefix {my configure colour} invokes my configure colour green in the method that called argparse. Relative command names use that caller’s namespace. A callback procedure or lambda has its normal local frame; it may use upvar 1 to access the argparse caller. Prefix arguments can be built dynamically with list, for example [list my configure $settingName].

Add the no-argument element option -withname to append the canonical element name before the value. This allows several elements to use the same configuration method without repeating their names in the command prefixes:

# Inside an object method:
argparse {
    {-colour= -alias c -enum {red green blue} -action {my configure} -withname}
    {-width= -type integer -action {my configure} -withname}
} {-c gr -width 4}
# Invokes: my configure -colour green
#          my configure -width 4

For switches the name includes one leading dash. Aliases, abbreviations, --colour, and equal-argument syntax all produce the same canonical name, such as -colour. Positional parameters receive their declared name without an added dash. Neither -key nor the global -template changes the callback name. Existing prefix words come first, followed by the name and then the value; each is a separate Tcl word.

-withname works with both -action and -transform, including an inherited global transformation:

argparse -inline -transform list {
    {-colour= -withname}
    {file -withname}
} {-colour green example.txt}
# Returns: colour {-colour green} file {file example.txt}

It requires a nonempty effective callback. Using it without a callback, or together with an empty -transform {} opt-out, is an error. It is an element option, not a global option. Without -withname, callbacks continue to receive only the value. With repeated switches or catchalls, the same canonical name accompanies each value. Validation, defaults, pass-through, and error handling follow the same rules with or without -withname.

The following conventions apply:

  • Only supplied values invoke callbacks. Omitted elements and -default values do not; defaults are already final values. An optional switch supplied without a value also does not invoke its callback.

  • A callback runs for every occurrence, even without -multiple; the last result then wins. With -multiple, results are collected in occurrence order. A list-valued result remains one list element.

  • A catchall validates and type-checks its entire input list first, then invokes its callback once per value. An empty catchall invokes nothing. Results form an outer list, without flattening.

  • A supplied optional switch value retains the usual two-element presence wrapper, with the callback result in the second element.

  • -pass retains the existing pre-transformation values and syntax, including under -normalize. This avoids applying transformations twice when forwarded arguments are parsed again. A separate pass-through destination is still assigned for an action. Use distinct keys for an action and its pass-through destination; action keys are excluded from caller-variable assignment.

  • Explicit callbacks require a positional parameter or an argument-taking switch, and conflict with -upvar. They do not imply -argument; use -a= or -argument where needed.

  • Help generation never invokes callbacks. Callback commands are resolved when invoked, so definitions can refer to commands created later.

  • Callback errors retain their error code and stack trace with added element context. Non-OK completion codes such as a raw return, break, or continue are reported as errors. Normal returns from callback procedures and lambdas work as usual.

Callbacks run during parsing, not after all input and constraints have been checked. Switch callbacks run as switches are consumed; positional callbacks run when positional values are allocated, after switch processing. Earlier side effects are not rolled back if a later value, callback, or constraint fails. For configuration that must change only after the complete input is accepted, first parse with -inline without callbacks that modify state, then apply the resulting dictionary after argparse succeeds.

Repeated switch arguments

Use the no-argument element option -multiple on an argument-taking switch to collect every occurrence into a list, in command-line order. Without it, repeated switches retain their existing last-value-wins behavior.

argparse -inline {
    {-a= -multiple}
    -b=
} {-a 1 -b 2 -a 3}
# Returns: a {1 3} b 2

One occurrence produces a one-element list. Each argument remains one element, including an empty string or a value that itself contains a list; values are never flattened:

argparse -inline {{-a= -multiple}} {-a {x y} -a {} -a z}
# Returns: a {{x y} {} z}

Aliases, unambiguous prefixes, -long, and -equalarg all collect into the same canonical element. -type, -enum, and -validate apply separately to each supplied value; enumeration prefixes are expanded before collection. A missing argument on any occurrence is an error.

Omission follows the ordinary rules: without -default there is no result key, and a caller variable is unset unless -keep applies. -default must be a valid Tcl list and represents the entire fallback list. For example, {-a= -multiple -default {}} supplies an empty list when omitted, while {-a= -multiple -default {x y}} supplies two default values. Explicit occurrences replace the whole default; it is never prepended. As with ordinary defaults, fallback values are not passed through type, enumeration, or expression validation. -keep does not append new values to an existing caller variable.

-required demands at least one occurrence. Constraints such as -require, -allow, -forbid, and -exclusive still operate on element presence: repeating a switch does not introduce a new element, and default values do not count as explicit presence. Shared-key restrictions remain unchanged.

-pass preserves every occurrence using the normal pass-through rules. With -normalize, an omitted switch’s default list becomes repeated switch/value pairs; an empty default adds no pairs. For example, {-a= -multiple -pass forwarded -default {x y}} produces {-a x -a y} in forwarded when normalized.

-multiple requires an argument-taking switch (use = or -argument, or an option such as -type that already implies an argument). It does not itself imply -argument. It conflicts with -parameter, -optional, -catchall, -upvar, -boolean, and -value. Positional parameters, flags, optional switch arguments, and catchall switches therefore cannot use it.

The generated synopsis shows ?-a value? ... for an optional repeatable switch and -a value ?-a value? ... for a required one. The ellipsis repeats the whole switch/value pair; it does not permit bare additional values. Repeated occurrences may be interleaved with other permitted switches.

Exclusive elements

The no-argument element switch -exclusive abbreviates -allow {}. It can be used on a switch or a positional parameter and is normalized to an empty allow list before ordinary constraint processing.

For example, these definitions have the same behavior:

{-version -exclusive}
{-version -allow {}}

An exclusive element permits no other present elements. Its own argument values are permitted, and repeated occurrences or aliases of the same switch still count as the same element. Defaults belonging to omitted elements do not count as present elements. The existing argument consumption, validation, and required-element rules are unchanged.

proc inspectConfig {args} {
    argparse -inline {
        {-version -exclusive}
        -verbose
        {file -optional}
    }
}
inspectConfig -version
# Returns: version {}
inspectConfig -version -verbose
# Error: version doesn't allow verbose
inspectConfig -version settings.conf
# Error: version doesn't allow file

-exclusive does not waive required switches or parameters. It is therefore different from -standalone, which disables required-element checks and require/forbid/allow constraints when it is processed. A present standalone switch also disables the empty allow constraint produced by -exclusive. If an exclusive element requires another element, the resulting constraints can be unsatisfiable; this abbreviation does not introduce automatic contradiction checking.

Combining -exclusive with an explicit -allow is rejected in either order, including -allow {}: -exclusive and -allow conflict. Combining it with -forbid produces the ordinary normalized diagnostic -allow and -forbid conflict. Repeating -exclusive itself is harmless.

Detailed help describes both -exclusive and -allow {} as Allows no other elements.

Reciprocal

Swtich with name -reciprocal is presented both as global switch and element switch. In global case all elements with -require switch are reciprocal to elements with names in argument to -require switch. Let’s consider this definition:

argparse -reciprocal {
    {-a= -require {b c}}
    -b
    -c=
}

With -reciprocal global switch, the -b and -c switches also require -a switch, because -a switch requires them, so, it is equivalent to:

argparse {
    {-a= -require {b c}}
    {-b -require a}
    {-c= -require a}
}

Element switch -reciprocal do the same thing but only for that particular element.

Imply

-imply element switch allows to specify additional argument to the switch. Extra argument will be assigned to different switch specified in argument to -imply switch. For example:

proc implyTest {args} {
    set arguments [argparse -inline {
        -a=
        {-b= -imply -c}
        -c=
    }]
    return $arguments
}

If we provide an additional argument to -b, it will be assigned to -c key:

implyTest -a 1 -b 2 3
==> a 1 b 2 c 3

If additional argument is not provided, the error is raised:

implyTest -a 1 -b 2
-c requires an argument
while executing
"argparse -inline {
    -a=
    {-b= -imply -c}
    -c=
}"
(procedure "implyTest" line 2)

And if -b switch with argument is not provided at all, -c is also considered omitted:

implyTest -a 1
==> a 1

Passthrough and normalization

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 global switch -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.

Upvar Elements

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.

Template

Swtich with name -template is presented both as global switch and element switch. In global case all elements names go through substitution before setting the caller variables or creating key of the dictionary if -inline is provided. As an element switch individual substitution templates could be provided. The most important usage is to use template to create array where names of elements become keys of array. As a substitution mark % symbol is used.

As an example let’s use our previous procedure:

proc genNums {args} {
    argparse -template vars(%) {
        # {Optional sequence control switches}
        {-from= -default 1 -type double}
        {-to=   -default 10 -type double}
        {-step= -default 1 -type double}
        {-prec= -default 1 -type double}
    }
    if {$vars(step) < 0} {
        set op ::tcl::mathop::>
    } else {
        set op ::tcl::mathop::<
    }
    for {set n $vars(from)} {[$op $n $vars(to)]} {set n [expr {$n + $vars(step)}]} {
        lappend result [format %.*f $vars(prec) $n]
    }
    return $result
}
genNums -from 0 -to 10 -step 2
==> 0.0 2.0 4.0 6.0 8.0

Here all switches are accesible as an array element.

-template applies to elements using neither -key nor -pass. To protect "%" or "" from replacement, precede it with "".

Help

Package allows to generate help description of command for the user when -help switch is provided as argument. In that case, message with procedure and arguments description is put to stdout, and other arguments are ignored. So, we can provide interactive help for the user of the command. To activate, global switch -help must be provided. Let’s take previous procedure genNums and add help to it:

proc genNums {args} {
    argparse -template vars(%) -help {Procedure generates sequence of numbers.} {
        # {Optional sequence control switches}
        {-from= -default 1 -type double -help {Provides start of sequence}}
        {-to= -default 10 -type double -help {Provides end of sequence}}
        {-step= -default 1 -type double -help {Provides step between adjacent numbers of sequence}}
        {-prec= -default 1 -type double -help {Provides precision of numbers in the sequence}}
    }
    if {$vars(step) < 0} {
        set op ::tcl::mathop::>
    } else {
        set op ::tcl::mathop::<
    }
    for {set n $vars(from)} {[$op $n $vars(to)]} {set n [expr {$n + $vars(step)}]} {
        lappend result [format %.*f $vars(prec) $n]
    }
    return $result
}
genNums -help
genNums ?-from value? ?-to value? ?-step value? ?-prec value?

Procedure generates sequence of numbers.. Can accepts unambiguous prefixes
instead of switches names. Accepts switches only before parameters.
    Switches:
        -from value - Provides start of sequence. Default value is 1. Type
            double.
        -to value - Provides end of sequence. Default value is 10. Type double.
        -step value - Provides step between adjacent numbers of sequence.
            Default value is 1. Type double.
        -prec value - Provides precision of numbers in the sequence. Default
            value is 1. Type double.
        -help - Help switch, when provided, forces ignoring all other switches
            and parameters, prints the help message to stdout, and returns up to 2
            levels above the current level.

Generated message contains information important for the user of the command, not all information that is in definition of elements. Individual description for each parameter can be added as end argument to element switch -help.

Let’s use another procedure, this time with switches and parameters presented:

proc sheduleEvent {args} {
    set arguments [argparse -help {Procedure shedules event at cetain date. At least one of the switches must be provided: -allday, -duration or -endtime} -inline -validate [dict create date {[regexp {^(0[1-9]|[12][0-9]|3[01])-(0[1-9]|1[0-2])-\d{4}$} $arg]} time {[regexp {^([01][0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9])?$} $arg]}] {
        {date -validate date -help {Provides date in format DD-MM-YY}}
        {time -validate time -help {Provides time in format HH:MM}}
        {-allday -allow {date time} -help {Set event duration for the rest of the day}}
        {-duration= -allow {date time} -validate time -help {Set event duration in format HH:MM}}
        {-endtime= -allow {date time} -validate time -help {Set end time of event in format HH:MM}}
    }]
    if {![dict exists $arguments allday] && ![dict exists $arguments duration] && ![dict exists $arguments endtime]} {
        return -code error "One of the switch must be presented: -allday, -duration or -endtime"
    }
    return $arguments
}
sheduleEvent -help
sheduleEvent ?-allday? ?-duration value? ?-endtime value? date time

Procedure shedules event at cetain date. At least one of the switches must be
provided: -allday, -duration or -endtime. Can accepts unambiguous prefixes
instead of switches names. Accepts switches only before parameters.
    Switches:
        -allday - Set event duration for the rest of the day. Allows date or
            time.
        -duration value - Set event duration in format HH:MM. Allows date or
            time.
        -endtime value - Set end time of event in format HH:MM. Allows date or
            time.
        -help - Help switch, when provided, forces ignoring all other switches
            and parameters, prints the help message to stdout, and returns up to 2
            levels above the current level.
    Parameters:
        date - Provides date in format DD-MM-YY.
        time - Provides time in format HH:MM.

Help Synopsis

When help is enabled with the global -help description switch, the help message begins with a structural synopsis, followed by a blank line and the existing description, switches, and parameters. This behavior is the same in the C and Tcl implementations. The synopsis is generated only when help is requested; it does not change parsing or validation.

Conventions

The synopsis uses Tcl manual conventions. Question marks delimit optional material; they are not literal characters to type. A bare item is required in the ordinary structural form. value and parameter names are placeholders, not literal arguments. An ellipsis means repetition, not a literal argument.

  • An optional flag is shown as ?-verbose?.

  • An optional switch taking a required value is ?-output value?.

  • A required switch taking a value is -output value.

  • An optional switch with an optional value is ?-option ?value??. The outer question marks make the switch optional; the inner pair makes its value optional. This does not change the existing consumption rule: if an argument is available to the switch, it is consumed, even if it resembles another switch.

  • A required parameter is input; an optional parameter is ?input?.

  • An optional catchall parameter is ?files ...?; a required catchall parameter is files ?files ...?. The latter requires at least one value.

  • An optional catchall switch is ?-rest ?value ...??; a required catchall switch is -rest ?value ...?. Requiring the switch does not require a nonempty collection of values.

  • Global -pass adds ?arg ...? for otherwise unassigned arguments. Consult the pass-through rules for unknown switches and argument assignment; the suffix does not make every argument sequence valid.

Switches appear in definition order, followed by parameters in definition order. With -pfirst, required parameters appear first, then switches, then optional parameters; order within each group is preserved. With -mixed, the synopsis still shows a representative switches-first layout, but switches may occur after parameters as explained in the detailed help. Catchall allocation and the reservation of required parameter values follow the normal parsing rules; the synopsis is not an executable grammar.

Only canonical single-dash switch names are shown. Aliases, abbreviated names, --name alternatives enabled by -long, and -name=value alternatives enabled by -equalarg remain supported. Defaults do not make a switch required. -hsuppress hides an element from both the synopsis and detailed help, even if it is required. The built-in help switch is described below the synopsis, rather than included in its argument list. Long synopsis text is wrapped at whitespace, with four-space continuation indentation; a single long word is not split. Letter case is preserved.

For example:

proc convert {args} {
    argparse -help {Convert an input file} {
        {-output= -required}
        -format=
        -compress
        input
        {columns -catchall}
    }
}
convert -help

The first paragraph is:

convert -output value ?-format value? ?-compress? input ?columns ...?

Command name and manual argument text

Two independent global switches control the two parts of the synopsis:

  • -synopsiscmd command supplies the displayed command name or command prefix. It always overrides inference, and leaves the argument synopsis automatically generated unless -synopsis is also supplied.

  • -synopsis text supplies only the argument portion. It does not contain the command name and does not replace the other help sections.

Both switches require the global -help switch, even on a call that does not request help. Otherwise the parser reports -synopsiscmd requires -help or -synopsis requires -help. An empty help description is sufficient: -help {}. Supplying either switch without its value is an error.

Both values are plain display text: they are not evaluated, substituted, or checked against the argument definition. Brace text containing dollar signs, brackets, or semicolons when calling argparse, so Tcl itself does not substitute it before the call. Normal whitespace wrapping still applies; this is not a verbatim multiline-layout facility. Leading and trailing whitespace around the combined synopsis is removed.

An empty -synopsis {} displays only the command name. An empty -synopsiscmd {} displays only the argument portion. Supplying both as empty strings suppresses the synopsis paragraph entirely.

To retain generated arguments but override the command prefix:

argparse -help {Convert an input file} -synopsiscmd {tools convert} {
    -output=
    input
    {columns -catchall}
}

The synopsis is:

tools convert ?-output value? input ?columns ...?

To override both parts independently:

argparse -help {Convert an input file} -synopsiscmd {tools convert} -synopsis {?-output filename? input ?column ...?} {
    -output=
    input
    {columns -catchall}
}

Automatic inference and ensembles

Without -synopsiscmd, argparse inspects its immediate caller. For a procedure it uses the first word of that invocation, preserving the spelling Tcl exposes there, including namespace qualifiers. Actual argument values are never included. A wrapper procedure is not skipped: if convert calls parseOptions, and parseOptions calls argparse, the inferred command is parseOptions.

In a normal TclOO method, inference uses the fully qualified object name and the current method name. In a constructor, it uses the fully qualified class of the object being constructed, including when the constructor is inherited from a superclass. A directly identifiable Class create name invocation is shown as Class create objectName; objectName is a placeholder, never the actual instance name. Other constructor invocations use Class new. This fallback also applies when a superclass constructor is reached through next, because its immediate invocation no longer identifies the original creation form. Custom factories, aliases, and forwarding commands may likewise need an explicit -synopsiscmd override. A manual -synopsis still replaces only the argument portion; class-name inference remains active.

For example, if ::Solver defines the constructor and ::SpecialSolver inherits it, help requested with SpecialSolver new -help begins with ::SpecialSolver new, while SpecialSolver create mySolver -help begins with ::SpecialSolver create objectName. Neither form exposes an anonymous object name such as ::oo::Obj38 or TclOO’s internal <constructor> method marker. An explicit -synopsiscmd {solverFactory build} replaces either inferred prefix with solverFactory build.

Destructors use the ordinary first-invocation-word fallback. At top level there is no caller procedure, so the fallback is command, not the script filename. Other dispatch mechanisms may expose implementation names rather than the user-facing command. Explicit names are recommended whenever the public invocation matters. Ordinary methods named constructor or destructor are still displayed as object methods; TclOO identifies the special lifecycle methods with the distinct markers <constructor> and <destructor>.

Ensemble dispatch generally exposes the mapped implementation command. Its public name cannot be recovered reliably: several ensembles or subcommands can map to the same procedure, and the procedure may also be called directly. The original source text may contain variable substitutions rather than command names. argparse does not scan ensemble maps or evaluate source text to guess the public invocation.

Specify the public prefix in the implementation:

namespace eval tools {
    proc convertImpl {args} {
        argparse -help {Convert an input file} -synopsiscmd {tools convert} {
            -output=
            input
        }
    }
    namespace ensemble create -command ::tools -map {convert ::tools::convertImpl}
}
tools convert -help

The synopsis is tools convert ?-output value? input. Without the override it would use ::tools::convertImpl, including when the ensemble subcommand is abbreviated to conv.

Structural limits and constraints

The synopsis summarizes individual elements; it does not promise that every displayed combination is legal. Detailed help remains authoritative for -require, -allow, and -forbid. In particular, -require {b c} requires both elements, while -allow {b c} permits only those other elements when its owning element is present; it does not require either one. Positional parameters participate in these constraints too. Every active allow rule must be satisfied. If an element has both require and allow rules, both are included in its description. Shared-key conflicts and reciprocal requirements also remain in the detailed descriptions rather than being converted into synopsis alternatives.

For example:

argparse -help {Select features} -synopsiscmd select {
    {-a -forbid b}
    {-b -forbid c}
    -c
}

The synopsis is select ?-a? ?-b? ?-c?. The pair -a -c is legal, whereas -a -b and -b -c are not. The generator deliberately does not invent an alternative group that would exclude the legal pair. Contradictory definitions are not diagnosed by synopsis generation: a required switch that another switch forbids is still shown as required.

-standalone can waive requirements and conflicts at runtime, and -imply can supply required switches indirectly or consume additional values. Their effects are not expanded into the generated synopsis.

For example, {-b= -imply -c} together with {-c= -required} is structurally shown as ?-b value? -c value, even though -b first second supplies both values through implication. Use -synopsis to describe such special modes precisely. Custom validation and checks performed by the calling procedure are also outside the generator’s scope. A manually supplied synopsis documents those rules; it does not enforce them or change parser behavior.

Argument Processing Sequence

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.

Normal processing

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 -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.

Let’s look at normal operation in the next example:

proc argProcSeq {args} {
    set arguments [argparse -inline {
        -a=
        -b=
        -c
        d
        e?
    }]
    return $arguments
}
argProcSeq -c -a 1 2
==> c {} a 1 d 2

First switches are processed, and there one argument left and it is assigned to required parameter r. If we provided another additional argument, it will be assigned to optional parameter e:

argProcSeq -c -a 1 2 3
==> c {} a 1 d 2 e 3

More complicated example:

proc argProcSeq {args} {
    set arguments [argparse -inline {
        -a=
        -b=
        -c
        d
        e?
        f
    }]
    return $arguments
}
argProcSeq -c -a 1 2 3
==> c {} a 1 d 2 f 3

In that case the last two arguments is assigned to two required parameters. If we provide two arguments after switch -a, then again they are assigned to required parameters, but because -a require argument, the error is thrown:

argProcSeq -c -a 1 2
-a requires an argument
while executing
"argparse -inline {
    -a=
    -b=
    -c
    d
    e?
    f
}"
(procedure "argProcSeq" line 2)

If we provide four arguments after -a:

argProcSeq -c -a 1 2 3 4
==> c {} a 1 d 2 e 3 f 4

All three arguments are assigned to parameters in order presented in definition. So, if only two remaining arguments are there - they are assigned to two required parameters, but if three parameters presented, optional parameter also gets the value in order in definition.

There is a special case when argument to parameter looks like a switch:

argProcSeq -c -a 1 -2 3 4
bad switch "-2": must be -a, -b, or -c
while executing
"argparse -inline {
    -a=
    -b=
    -c
    d
    e?
    f
}"
(procedure "argProcSeq" line 2)

The error is appeared because after counting required parameters (two required), last two arguments are assigned to that parameters, and the -2 looks like a switch, so argparse tries to parse it as a switch. To fix that we can use --:

argProcSeq -c -a 1 -- -2 3 4
==> c {} a 1 d -2 e 3 f 4

If one of the last two switches appears with -, all is processed as it should:

argProcSeq -c -a 1 -- 2 -3 4
==> c {} a 1 d 2 e -3 f 4

Processing with parameters first

If -mixed is not used and -pfirst is used, the required parameters are counted, then that number of arguments at the start of the argument list are treated as parameters even if they begin with -.

The global switch -pfirst allows to assign first n arguments to n required parameters irrespectively of how these arguments looks like. Then switches and optional parameters are processed.

But, even if number arguments are enough to assign to both required and optional parameters, required parameters are assigned first - it is different to how it works when parameters arguments are provided after switches. These two examples demonstrating that:

proc argProcSeq {args} {
    set arguments [argparse -inline -pfirst {
        -a=
        -b=
        -c
        d
        e?
        f
    }]
    return $arguments
}
argProcSeq 1 2 -c -a 1
==> c {} a 1 d 1 f 2
argProcSeq 1 2 3 -c -a 1
==> c {} a 1 d 1 f 2 e 3

Also, the remaining parameters could be provided after switches:

argProcSeq 1 2 -c -a 1 3
==> c {} a 1 d 1 f 2 e 3

But it doesn’t work in case of parameter argument looking like a switch:

argProcSeq 1 2 -c -a 1 -3
bad switch "-3": must be -a, -b, or -c
while executing
"argparse -inline -pfirst {
    -a=
    -b=
    -c
    d
    e?
    f
}"
(procedure "argProcSeq" line 2)

In that case we can use the same trick with -- termination of switch processing:

argProcSeq 1 2 -c -a 1 -- -3
==> c {} a 1 d 1 f 2 e -3

Also there is a special treatment of -catchall parameter:

proc argProcSeq {args} {
    set arguments [argparse -inline -pfirst {
        -a=
        -b=
        -c
        d
        e?
        f
        {g -catchall}
    }]
    return $arguments
}
argProcSeq 1 2 -c -a 1 3 4
==> c {} a 1 d 1 f 2 e 3 g 4

Catchall parameters are treated after required and optional parameters.

Processing with mixed

When the -mixed switch is used, switch processing continues after encountering arguments that 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.

Let’s see in example:

proc argProcSeq {args} {
    set arguments [argparse -inline -mixed {
        -a=
        -b=
        -c
        d
        e?
        f
        {g -catchall}
    }]
    return $arguments
}
argProcSeq 1 2 -c -a 1 3 4
==> c {} a 1 d 1 e 2 f 3 g 4

The result is different from the last example from chapter example because in this case the process is going as usual, but can be interrupted by providing switch with possible arguments.

The processing could be altered multiple times:

proc argProcSeq {args} {
    set arguments [argparse -inline -mixed {
        -a=
        -b=
        -c
        d
        e?
        f
        {g -catchall}
    }]
    return $arguments
}
argProcSeq 1 -c 2 -a 1 3 4
==> c {} a 1 d 1 e 2 f 3 g 4

Result is exact the same as in the previous example. Problems started when parameter looks like a switch, in that case only -- can force the rest of arguments considered as parameters arguments:

argProcSeq 1 -c -2 -a 1 3 4
bad switch "-2": must be -a, -b, or -c
while executing
"argparse -inline -mixed {
    -a=
    -b=
    -c
    d
    e?
    f
    {g -catchall}
}"
(procedure "argProcSeq" line 2)
argProcSeq 1 -c -a 1 -- -2 3 4
==> c {} a 1 d -2 e 3 f 4 g {}

in that case the arguments before switch -- that are not arguments to switches and does not look like a switch are ignored.

Return Value

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

Author(s)

Andy Goth mailto:andrew.m.goth@gmail.com - all code and most of documentation

George Yashin mailto:georgtree@gmail.com - some documentation, test suite and new features, C implementation

Ashok P. Nadkarni mailto:apnmbx-wits@yahoo.com - fix of C implementation and valuable advices about the code architecture


Copyright (c) George Yashin