Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Begin writing documentation |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | amg-argparse |
Files: | files | file ages | folders |
SHA3-256: |
b40a9f709a2b52f2d299cc741e453554 |
User & Date: | andy 2019-04-17 06:47:36.484 |
Context
2019-04-26
| ||
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 | |
06:45 | Allow parse_args-style comments check-in: 487e9d220e user: andy tags: amg-argparse | |
Changes
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 |
︙ | ︙ |