Tcl Library Source Code

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

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

Overview
Comment:Begin writing documentation
Timelines: family | ancestors | amg-argparse
Files: files | file ages | folders
SHA3-256:b40a9f709a2b52f2d299cc741e45355455ce69c5fa43b99063d2124bcea890d1
User & Date: andy 2019-04-17 06:47:36
Context
2019-04-17
06:47
Begin writing documentation Leaf check-in: b40a9f709a user: andy tags: amg-argparse
06:45
Allow parse_args-style comments check-in: 487e9d220e user: andy tags: amg-argparse
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to modules/argparse/TODO.md.

1
2
3
4
5


6
7
8
9
10
11
12
- Remove `-boolean` 
  - Instead, act as if `-boolean` were always being passed to [argparse]
  - Remove `-keep` as well
  - Add an `-unset` switch to selectively change the behavior to unsetting a
    variable or omitting a dict key when the switch is not present


- Documentation
  - Instead of having a big comment, use doctools
- Help text generation
  - Parameter and switch descriptions given by per-element `-help` switch
  - Need overall `-help` switch to provide narrative description
  - May need special grouping elements to organize switches and parameters
  - Text formatting and word wrapping





>
>







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

Added modules/argparse/argparse.man.































































































































































































































































































































































































































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
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
192
193
194
195
196
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
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
[vset CATEGORY argparse]
[vset ARGPARSE_VERSION 0.4]
[manpage_begin argparse n [vset ARGPARSE_VERSION]]
[keywords {argument processing}]
[keywords argv]
[keywords argv0]
[keywords {cmdline processing}]
[keywords {command line processing}]
[see_also cmdline(n)]
[moddesc {Command switch and parameter parsing}]
[titledesc {Procedure for processing command switches and parameters.}]
[category {Programming tools}]
[require Tcl 8.6]
[usage [cmd argparse]\
    [opt [arg {-globalSwitch ...}]]\
    [opt [option --]]\
    [arg definition]\
    [opt [arg arguments]]]
[description]

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

[para]

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

[para]

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

[para]

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

[section {Quick Start Guide}]

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

[section Concepts]

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

[subsection Definition]

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

[para]

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

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

[subsection Element]

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

[para]

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

[para]

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

[para]

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

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

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

[subsection Name]

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

[para]

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

[para]

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

[subsection Key]

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

[para]

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

[para]

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

[subsection Alias]

[subsection Flag]

[subsection {Global Switch}]

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

[subsection {Element Switch}]

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

[para]

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

[subsection Switch]

[subsection Parameter]

[subsection Comment]

[subsection Argument]

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

[section {Global Switches}]

[list_begin options]

[opt_def -inline]

Return the result dict rather than setting caller variables

[opt_def -exact]

Require exact switch name matches, and do not accept prefixes

[opt_def -mixed]

Allow switches to appear after parameters

[opt_def -long]

Recognize "--switch" long option alternative syntax

[opt_def -equalarg]

Recognize "-switch=arg" inline argument alternative syntax

[opt_def -normalize]

Normalize switch syntax in passthrough result keys

[opt_def -reciprocal]

Every element's -require constraints are reciprocal

[opt_def -level levelSpec]

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

[opt_def -template templateString]

Transform default element names using a substitution template

[opt_def -pass passKey]

Pass unrecognized elements through to a result key

[opt_def -keep]

Do not unset omitted element variables; conflicts with -inline

[opt_def -boolean]

Treat switches as having -boolean wherever possible

[opt_def -validate validDef]

Define named validation expressions to be used by elements

[opt_def -enum enumDef]

Define named enumeration lists to be used by elements

[opt_def --]

Force next argument to be interpreted as the definition list 

[list_end]

[section {Element Switches}]

[list_begin options]

[opt_def -switch]

Element is a switch; conflicts with -parameter

[opt_def -parameter]

Element is a parameter; conflicts with -switch

[opt_def -alias aliasName]

Alias name; requires -switch

[opt_def -ignore]

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

[opt_def -key keyName]

Override key name; not affected by -template

[opt_def -pass keyName]

Pass through to result key; not affected by -template

[opt_def -default value]

Value if omitted; conflicts with -required and -keep

[opt_def -keep]

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

[opt_def -value value]

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

[opt_def -boolean]

Equivalent to "-default 0 -value 1"

[opt_def -argument]

Value is next argument following switch; requires -switch

[opt_def -optional]

Switch value is optional, or parameter is optional

[opt_def -required]

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

[opt_def -catchall]

Value is list of all otherwise unassigned arguments

[opt_def -upvar]

Links caller variable; conflicts with -inline and -catchall

[opt_def -level levelSpec]

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

[opt_def -standalone]

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

[opt_def -require nameList]

If element is present, other elements that must be present

[opt_def -forbid nameList]

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

[opt_def -imply argList]

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

[opt_def -reciprocal]

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

[opt_def -validate validNameOrDef]

Name of validation expression, or inline validation definition

[opt_def -enum enumNameOrDef]

Name of enumeration list, or inline enumeration definition 

[list_end]

[section Shorthand]

[subsection Aliases]

[subsection Flags]

[section Validation]

[section Passthrough]

[section {Upvar Elements}]

[section {Argument Processing Sequence}]

[section {Return Value}]

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

[section Author]

Andy Goth

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

Changes to modules/cmdline/cmdline.man.

1
2
3
4
5
6

7
8
9
10
11
12
13
[manpage_begin cmdline n 1.5]
[keywords {argument processing}]
[keywords argv]
[keywords argv0]
[keywords {cmdline processing}]
[keywords {command line processing}]

[moddesc   {Command line and option processing}]
[titledesc {Procedures to process command lines and options.}]
[category  {Programming tools}]
[require Tcl 8.2]
[require cmdline [opt 1.3.3]]
[description]







>







1
2
3
4
5
6
7
8
9
10
11
12
13
14
[manpage_begin cmdline n 1.5]
[keywords {argument processing}]
[keywords argv]
[keywords argv0]
[keywords {cmdline processing}]
[keywords {command line processing}]
[see_also argparse(n)]
[moddesc   {Command line and option processing}]
[titledesc {Procedures to process command lines and options.}]
[category  {Programming tools}]
[require Tcl 8.2]
[require cmdline [opt 1.3.3]]
[description]

Changes to support/installation/modules.tcl.

32
33
34
35
36
37
38

39
40
41
42
43
44
45

Exclude calendar
Exclude exif

#       name         pkg   doc   example
Module  aes         _tcl  _man  _null
Module  amazon-s3   _tcl  _man  _null

Module  asn         _tcl  _man  _null
Module  base32      _tcl  _man  _null
Module  base64      _tcl  _man  _null
Module  bee         _tcl  _man  _null
Module  bench       _tcl _null  _null
Module  bibtex      _tcl  _man  _exa
Module  blowfish    _tcl  _man  _null







>







32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

Exclude calendar
Exclude exif

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