Tcl Library Source Code

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

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

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

Changes to modules/argparse/argparse.man.

14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
..
40
41
42
43
44
45
46
47
48
49
50


51























































































































52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
..
76
77
78
79
80
81
82
83
84


85
86
87
88
89
90
91

92
93
94
95
96
97
98
99
100
101
102
103
104

105

106
107
108
109
110
111
112
113
114
115


116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

131
132
133
134
135
136
137

138
139
140
141
142
143
144
...
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178




179
180
181
182
183
184
185
...
357
358
359
360
361
362
363
364
365
366
367
[usage [cmd argparse]\
    [opt [arg {-globalSwitch ...}]]\
    [opt [option --]]\
    [arg definition]\
    [opt [arg arguments]]]
[description]

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

[para]

Tcl commands requiring more advanced argument parsing than provided by the
standard [cmd proc] command can be declared to accept [const args] (i.e. any
number of arguments), then can call [cmd argparse] to perform the real argument
parsing.
................................................................................
[cmd argparse] may be applied to a variety of special purposes beyond standard
argument parsing.  For example, [cmd argparse] can parse custom variadic data
structures formatted as lists of switches and/or parameters of a highly dynamic
nature.  Another example: by calling [cmd argparse] multiple times, it is
possible to parse nested or multi-part argument lists in which arguments to
subsystems are embedded in passthrough switches or parameters.

[section {Quick Start Guide}]

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


























































































































[section Concepts]

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

[subsection Definition]

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

[para]

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

[example {
................................................................................
    # {Required output list variable}
    listVar^
}
}]

[subsection Element]

A [term definition] contains any number of [term elements].  For the most part,
each element defines either a [term switch] or a [term parameter].  An element


is itself a Tcl list whose required first word is the [term name] (with optional
shorthand [term aliases] and [term flags]) and whose optional subsequent words
are [term {element switches}].

[para]

In addition to switches and parameters, elements may be [term comments] or lists

of [term {global switches}].

[para]

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

[para]

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


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


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

[subsection Name]

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



[para]

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

[para]

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

[subsection Key]

In addition to having a [term name], every [term switch] and [term parameter]

[term definition] [term element] has a [term key].  Unlike names, multiple
elements may share the same key, subject to restrictions.

[para]

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


[para]

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

[subsection Alias]
................................................................................

[subsection Flag]

[subsection {Global Switch}]

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

[subsection {Element Switch}]

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

[para]

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

[subsection Switch]

[subsection Parameter]

[subsection Comment]

[subsection Argument]

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





[section {Global Switches}]

[list_begin options]

[opt_def -inline]

................................................................................

[section {Return Value}]

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

[section Author]

Andy Goth

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






|
|
|







 







|

|
|
>
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>











|







 







|
|
>
>
|
|
|



|
>
|












>
|
>

|
|
|
|



|
|
>
>








|
|
|



|
>
|
|



|
|
>







 







|
|
|



|
|
|



|
|
|
|











>
>
>
>







 







|



14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
..
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
...
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
...
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
...
491
492
493
494
495
496
497
498
499
500
501
[usage [cmd argparse]\
    [opt [arg {-globalSwitch ...}]]\
    [opt [option --]]\
    [arg definition]\
    [opt [arg arguments]]]
[description]

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

[para]

Tcl commands requiring more advanced argument parsing than provided by the
standard [cmd proc] command can be declared to accept [const args] (i.e. any
number of arguments), then can call [cmd argparse] to perform the real argument
parsing.
................................................................................
[cmd argparse] may be applied to a variety of special purposes beyond standard
argument parsing.  For example, [cmd argparse] can parse custom variadic data
structures formatted as lists of switches and/or parameters of a highly dynamic
nature.  Another example: by calling [cmd argparse] multiple times, it is
possible to parse nested or multi-part argument lists in which arguments to
subsystems are embedded in passthrough switches or parameters.

[section {Quick Start}]

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

[para]

Consider the following:

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

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

[para]

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

[para]

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

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

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

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

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

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

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

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

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

[section Concepts]

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

[subsection Definition]

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

[para]

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

[example {
................................................................................
    # {Required output list variable}
    listVar^
}
}]

[subsection Element]

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

[para]

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

[para]

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

[para]

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

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

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

[subsection Name]

Aside from [sectref Alias aliases] and [sectref Flag flags], the first word of
each [sectref Switch switch] or [sectref Parameter parameter]
[sectref Element element] in the [sectref Definition definition] is the
[term name].

[para]

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

[para]

If the name is "[option #]", the element is a [sectref Comment comment] and is
ignored.  If the name is empty string, the element is neither a switch nor a
parameter and is instead a list of [sectref {Global Switch} {global switches}].

[subsection Key]

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

[para]

By default, the key defaults to the name, but it is possible to use the
[option -key] [sectref {Element Switch} {element switch}] to explicitly declare
an element's key.

[para]

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

[subsection Alias]
................................................................................

[subsection Flag]

[subsection {Global Switch}]

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

[subsection {Element Switch}]

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

[para]

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

[subsection Switch]

[subsection Parameter]

[subsection Comment]

[subsection Argument]

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

[subsection Required]

[subsection Optional]

[section {Global Switches}]

[list_begin options]

[opt_def -inline]

................................................................................

[section {Return Value}]

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

[section Author]

Andy Goth <[email protected]>

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