Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/georgtree/argparse

Argument preprocessor for Tcl
https://github.com/georgtree/argparse

Last synced: 4 months ago
JSON representation

Argument preprocessor for Tcl

Awesome Lists containing this project

README 

          
# argparse



This is a fork of argparse project initially developed by Andy Goth .



See [original repository](https://core.tcl-lang.org/tcllib/timeline?r=amg-argparse), and 

[wiki page](https://wiki.tcl-lang.org/page/argparse).



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](https://www.magicsplat.com/tcl-installer/index.html#packages) 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:

```tcl

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.



## Table of content



  - [Table of content](#table-of-content)

  - [Synopsys](#synopsys)

  - [Description](#description)

  - [Quick Start](#quick-start)

  - [Concepts](#concepts)

    - [Argument](#argument)

    - [Definition](#definition)

    - [Global Switch](#global-switch)

    - [Element](#element)

    - [Element Switch](#element-switch)

    - [Name](#name)

    - [Key](#key)

    - [Switch](#switch)

    - [Parameter](#parameter)

    - [Value](#value)

    - [Alias](#alias)

    - [Shorthand flag](#shorthand-flag)

    - [Comment](#comment)

  - [Global Switches](#global-switches)

  - [Element Switches](#element-switches)

  - [Collecting unassigned arguments](#collecting-unassigned-arguments)

  - [Default values](#default-values)

  - [Validation](#validation)

  - [Forbid](#forbid)

  - [Allow](#allow)

  - [Reciprocal](#reciprocal)

  - [Imply](#imply)

  - [Passthrough and normalization](#passthrough-and-normalization)

  - [Upvar Elements](#upvar-elements)

  - [Template](#template)

  - [Help](#help)

  - [Argument Processing Sequence](#argument-processing-sequence)

    - [Normal processing](#normal-processing)

    - [Processing with parameters first](#processing-with-parameters-first)

    - [Processing with mixed](#processing-with-mixed)

  - [Return Value](#return-value)

  - [Author(s)](#author(s))



## Synopsys



``` text

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:



```tcl

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](#name) as the various [elements](#element) of the

[definition](#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](#switch), whereas `subject`, lacking a

`-` prefix, is a [parameter](#parameter). Two of the switches are given a `=` suffix, which means they each take an

[argument](#argument), whereas `title` does not. In addition to these [flag](#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](#element-switches) to set its default value to `hello`, in case `-salutation` is

not present in the argument list.



By default, switches are [optional](#optional) and parameters are [required](#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.



```tcl

greet world

```

```text

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



```tcl

greet -salutation howdy world

```

```text

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



```tcl

greet -title -mod "my dear" world

```

```text

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



```tcl

greet -title

```

```text

==> 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](#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](#element-switch)



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



``` tcl

{

    # {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](https://stackoverflow.com/a/38436286/21306711):



```tcl

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

```

```text

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](#definition) argument. Global switches may also be

embedded within special definition [elements](#element) whose [name](#name) is empty string.



### Element



A [definition](#definition) contains any number of *elements*. For the most part, each element defines either a

[switch](#switch) or a [parameter](#parameter). Elements may also be [comments](#comment) or [global

switches](#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](#switch) and [parameters](#parameter), elements may be [comments](#comment) or lists of 

[global switches](#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.



``` tcl

{-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](#element) in the [definition](#definition). Element switches are 

listed following the [name](#name) word of the definition element.



In the above example definition, each [switch](#switch) element explicitly uses the `-default` element switch. Due to 

use of the `-` and `=` shorthand [flags](#flag), each switch element also implicitly uses the `-switch` and `-argument`

element switches.



### Name



Aside from [aliases](#alias) and [flags](#flag), the first word of each [switch](#switch) or [parameter](#parameter) 

[element](#element) in the [definition](#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](#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](#global-switches).



### Key



In addition to having a [name](#name), every [switch](#switch) and [parameter](#parameter) [definition](#definition) 

[element](#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](#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](#element-switch). 

It could be defined either with shorthand `-` before name or with `-switch` [element 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](#element) that is provided without any preceding flags before name, and it's

position in the list of [definitions](#definition) 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](#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](#parameter) or

[switch](#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](#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](#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](#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](#name) of the [switch](#switch) element. It can be provided by `-alias ALIAS` element 

switch, or before the base name with `|` shorthand flag, but after `-` flag. For example:



``` tcl

{-variable= -alias var -required}

```



or



``` tcl

{-var|variable= -required}

```



Also supported multiple aliases for single switch, for example:



``` tcl

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

```



or



``` tcl

{-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](#name) is preceded by

`-`, it is a [switch](#switch); otherwise, it is a [parameter](#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](#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                                    |

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

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



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

| `-imply argList`           | If element is present, extra switch arguments; requires `-switch`                       |

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

| `-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 is] 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](#element-switch), we can collects the rest of otherwise unassigned 

[arguments](#argument) to list and save to switch's [key](#key). Let's consider next example:



```tcl

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

```

```text

==> 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](#validation) possible values of argument to `-op`

switch.



At most one parameter may use `-catchall`.



## Default values



[Element switch](#element-switch) `-default` specifies the [value](#value) to assign to [element](#element)

[keys](#key) when the element is omitted. If `-default` is not used, keys for omitted [switches](#switch) and

[parameters](#parameter) 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](#element) [value](#value) validation.  The global `-validate` and `-enum`

[switches](#global-switch) 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](#argument). If the expression evaluates to `true`, the argument is accepted. Let's consider the example:



```tcl

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

```

```text

==> 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:



```tcl

exponentiation -b a -n 4

```

```{tclerr}

-b value "a" fails validation: [string is double $arg]

```



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 is] 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](#shorthand-flag)). Conflicts with `-upvar`, `-boolean` and `-enum`, combination of

`-switch`, `-optional` and `type` is forbidden.



As an example, we can use previously proposed procedure:



```tcl

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:



```tcl

genNums -from 0 -to 10.. -step 2 sequenceVar

```

```{tclerr}

-to value "10.." is not of the type double

```



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:

```tcl

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

```

```{tclerr}

Value of switch '-n' must be double, '4t' was provided

```



## Forbid



If the presence of an [element](#element) should be forbidden in combination with certain other elements, use the

`-forbid` [switch](#element-switch) followed by a list of element names. In next example, we can forbid using

arguments that logically incompatible:



```tcl

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](#parameter), and the duration of the event could be provided by different mutually

exclusively [switches](#switch):



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



```tcl

sheduleEvent -duration 01:30 20-12-2024 13:30

```

```text

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

```



Error is issued in case of providing conflicting switches:



```tcl

sheduleEvent -allday -duration 01:30 20-12-2024 13:30

```

```{tclerr}

-allday conflicts with -duration

```



## Allow



[Element switch](#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:



```tcl

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:



```tcl

sheduleEvent -duration 01:30 20-12-2024 13:30

```

```text

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

```



Error is issued in case of providing conflicting switches:



```tcl

sheduleEvent -allday -duration 01:30 20-12-2024 13:30

```

```{tclerr}

allday doesn't allow duration

```



## Reciprocal



Swtich with name `-reciprocal` is presented both as [global switch](#global-switch) and

[element switch](#element-switch). In global case all [elements](#element) with `-require` switch are reciprocal to

elements with names in argument to `-require` switch. Let's consider this definition:



```tcl

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:



```tcl

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](#element-switch) allows to specify additional argument to the [switch](#switch). Extra 

[argument](#argument) will be assigned to different switch specified in argument to `-imply` switch. For example:



```tcl

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](#key):



```tcl

implyTest -a 1 -b 2 3

```

```text

==> a 1 b 2 c 3

```



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



```tcl

implyTest -a 1 -b 2

```

```{tclerr}

-c requires an argument

```



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



```tcl

implyTest -a 1

```

```text

==> a 1

```



## Passthrough and normalization



The per-element `-pass` [switch](#element-switch) causes the [element](#element) [argument](#argument) or arguments to

be appended to the value of the indicated pass-through result [key](#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](#value), as well as

omitted [parameters](#parameter) 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](#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](#element) with `-upvar` are special. Rather than having normal [values](#value), 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](#key) whose

[names](#name) 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](#switch) or with optional [parameters](#parameter), `[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](#global-switch) and [element switch](#element-switch).

In global case all [elements](#element) 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:



```tcl

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

```

```text

==> 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](#global-switch) `-help` must be

provided. Let's take previous procedure `genNums` and add help to it:



```tcl

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

```

```{tclerr}



```



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 and argument to [element switch](#element-switch)

`-help`.



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



```tcl

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

```

```{tclerr}



```



## Argument Processing Sequence



[Argument](#argument) processing is performed in three stages: [switch](#switch) processing, [parameter](#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:



```tcl

proc argProcSeq {args} {

    set arguments [argparse -inline {

        -a=

        -b=

        -c

        d

        e?

    }]

    return $arguments

}

argProcSeq -c -a 1 2

```

```text

==> 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`:



```tcl

argProcSeq -c -a 1 2 3

```

```text

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

```



More complicated example:



```tcl

proc argProcSeq {args} {

    set arguments [argparse -inline {

        -a=

        -b=

        -c

        d

        e?

        f

    }]

    return $arguments

}

argProcSeq -c -a 1 2 3

```

```text

==> 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:



```tcl

argProcSeq -c -a 1 2

```

```{tclerr}

-a requires an argument

```



If we provide four arguments after `-a`:



```tcl

argProcSeq -c -a 1 2 3 4

```

```text

==> 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:



```tcl

argProcSeq -c -a 1 -2 3 4

```

```{tclerr}

bad switch "-2": must be -a, -b, or -c

```



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 `--`:



```tcl

argProcSeq -c -a 1 -- -2 3 4

```

```text

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

```



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



```tcl

argProcSeq -c -a 1 -- 2 -3 4

```

```text

==> 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:



```tcl

proc argProcSeq {args} {

    set arguments [argparse -inline -pfirst {

        -a=

        -b=

        -c

        d

        e?

        f

    }]

    return $arguments

}

argProcSeq 1 2 -c -a 1

```

```text

==> c {} a 1 d 1 f 2

```



```tcl

argProcSeq 1 2 3 -c -a 1

```

```text

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

```



Also, the remaining parameters could be provided after switches:



```tcl

argProcSeq 1 2 -c -a 1 3

```

```text

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

```



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



```tcl

argProcSeq 1 2 -c -a 1 -3

```

```{tclerr}

bad switch "-3": must be -a, -b, or -c

```



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



```tcl

argProcSeq 1 2 -c -a 1 -- -3

```

```text

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

```



Also there is a special treatment of `-catchall` parameter:



```tcl

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

```

```text

==> 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:



```tcl

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

```

```text

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

```



The result is different from the last example from [chapter](#processing-with-parameters-first) 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:



```tcl

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

```

```text

==> 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:



```tcl

argProcSeq 1 -c -2 -a 1 3 4

```

```{tclerr}

bad switch "-2": must be -a, -b, or -c

```



```tcl

argProcSeq 1 -c -a 1 -- -2 3 4

```

```text

==> 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](#key) and [values](#value). 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](#element) [names](#name) 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  - all code and most of documentation



George Yashin  - some documentation, test suite and new features, C implementation



Ashok P. Nadkarni  - fix of C implementation and valuable advices about the code architecture