Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Added docs for negative aliases. |
---|---|
Timelines: | family | ancestors | descendants | both | neg-aliases |
Files: | files | file ages | folders |
SHA1: |
21b94c7e508f1688fd1541ac2c730d73 |
User & Date: | aku 2015-05-12 22:02:26.130 |
Context
2015-05-12
| ||
22:03 | Merged work on negative aliases. check-in: 88c1cb79e5 user: aku tags: trunk | |
22:02 | Added docs for negative aliases. Closed-Leaf check-in: 21b94c7e50 user: aku tags: neg-aliases | |
21:53 | Added tests checking runtime handling of negative aliases. check-in: af44ad2581 user: aku tags: neg-aliases | |
Changes
Changes to doc/parts/dsl_para_naming.inc.
︙ | ︙ | |||
43 44 45 46 47 48 49 50 51 52 53 54 | If that is not enough for a specific [term option] this command allows the specification of any number additional flags to be recognized. [para] Note however that the framework automatically recognizes not only the specified flag(s), but also all their unique prefixes, obviating the need for this command in many cases. [list_end] | > > > > > > > > > > > > > > | 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 | If that is not enough for a specific [term option] this command allows the specification of any number additional flags to be recognized. [para] Note however that the framework automatically recognizes not only the specified flag(s), but also all their unique prefixes, obviating the need for this command in many cases. [comment {- - -- --- ----- -------- -------------}] [call [cmd neg-alias] [arg name]] [call [cmd !alias] [arg name]] This command applies only to [term boolean] [term option]s. For them it allows the specification of any number additional flags to be recognized, which are aliases of its [emph inverted] form, i.e. of [const --no-FOO] for an option [const FOO]. [para] This in contrast to [cmd alias]es, which are for the regular form of the option. [para] Note further that the framework automatically recognizes not only the specified flag(s), but also all their unique prefixes, obviating the need for this command in many cases. [list_end] |
Changes to embedded/man/files/cmdr_dsl_parameter.n.
︙ | ︙ | |||
275 276 277 278 279 280 281 282 283 284 285 286 287 288 | .SH NAME cmdr-spec-dsl-parameter \- Cmdr - Parameter Specification Language .SH SYNOPSIS \fBlabel\fR \fItext\fR .sp \fBalias\fR \fIname\fR .sp \fBno-promotion\fR .sp \fBoptional\fR .sp \fBtest\fR .sp \fBundocumented\fR | > > > > | 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 | .SH NAME cmdr-spec-dsl-parameter \- Cmdr - Parameter Specification Language .SH SYNOPSIS \fBlabel\fR \fItext\fR .sp \fBalias\fR \fIname\fR .sp \fBneg-alias\fR \fIname\fR .sp \fB!alias\fR \fIname\fR .sp \fBno-promotion\fR .sp \fBoptional\fR .sp \fBtest\fR .sp \fBundocumented\fR |
︙ | ︙ | |||
387 388 389 390 391 392 393 394 395 396 397 398 399 400 | \fIParsing\fR phase\&. If that is not enough for a specific \fIoption\fR this command allows the specification of any number additional flags to be recognized\&. .sp Note however that the framework automatically recognizes not only the specified flag(s), but also all their unique prefixes, obviating the need for this command in many cases\&. .PP .PP .SS "GENERAL CONTROL" .PP The general handling of a \fIparameter\fR is influenced by three commands: .TP | > > > > > > > > > > > > > | 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 | \fIParsing\fR phase\&. If that is not enough for a specific \fIoption\fR this command allows the specification of any number additional flags to be recognized\&. .sp Note however that the framework automatically recognizes not only the specified flag(s), but also all their unique prefixes, obviating the need for this command in many cases\&. .TP \fBneg-alias\fR \fIname\fR .TP \fB!alias\fR \fIname\fR This command applies only to \fIboolean\fR \fIoption\fRs\&. For them it allows the specification of any number additional flags to be recognized, which are aliases of its \fIinverted\fR form, i\&.e\&. of \fB--no-FOO\fR for an option \fBFOO\fR\&. .sp This in contrast to \fBalias\fRes, which are for the regular form of the option\&. .sp Note further that the framework automatically recognizes not only the specified flag(s), but also all their unique prefixes, obviating the need for this command in many cases\&. .PP .PP .SS "GENERAL CONTROL" .PP The general handling of a \fIparameter\fR is influenced by three commands: .TP |
︙ | ︙ |
Changes to embedded/www/doc/files/cmdr_dsl_parameter.html.
︙ | ︙ | |||
131 132 133 134 135 136 137 | </ul> </div> <div id="synopsis" class="section"><h2><a name="synopsis">Synopsis</a></h2> <div class="synopsis"> <ul class="syntax"> <li><a href="#1"><b class="cmd">label</b> <i class="arg">text</i></a></li> <li><a href="#2"><b class="cmd">alias</b> <i class="arg">name</i></a></li> | | | | | | | | | | | | | > > | | | 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 | </ul> </div> <div id="synopsis" class="section"><h2><a name="synopsis">Synopsis</a></h2> <div class="synopsis"> <ul class="syntax"> <li><a href="#1"><b class="cmd">label</b> <i class="arg">text</i></a></li> <li><a href="#2"><b class="cmd">alias</b> <i class="arg">name</i></a></li> <li><a href="#3"><b class="cmd">neg-alias</b> <i class="arg">name</i></a></li> <li><a href="#4"><b class="cmd">!alias</b> <i class="arg">name</i></a></li> <li><a href="#5"><b class="cmd">no-promotion</b></a></li> <li><a href="#6"><b class="cmd">optional</b></a></li> <li><a href="#7"><b class="cmd">test</b></a></li> <li><a href="#8"><b class="cmd">undocumented</b></a></li> <li><a href="#9"><b class="cmd">default</b> <i class="arg">value</i></a></li> <li><a href="#10"><b class="cmd">generate</b> <i class="arg">cmdprefix</i></a></li> <li><a href="#11"><b class="cmd">interact</b> <span class="opt">?<i class="arg">prompt</i>?</span></a></li> <li><a href="#12"><b class="cmd">list</b></a></li> <li><a href="#13"><b class="cmd">defered</b></a></li> <li><a href="#14"><b class="cmd">immediate</b></a></li> <li><a href="#15"><b class="cmd">validate</b> <i class="arg">cmdprefix</i></a></li> <li><a href="#16"><b class="cmd">presence</b></a></li> <li><a href="#17"><b class="cmd">when-complete</b> <i class="arg">cmdprefix</i></a></li> <li><a href="#18"><b class="cmd">when-set</b> <i class="arg">cmdprefix</i></a></li> </ul> </div> </div> <div id="section1" class="section"><h2><a name="section1">Description</a></h2> <p>Welcome to the Cmdr project, written by Andreas Kupries.</p> <p>For availability please read <i class="term"><a href="cmdr_howto_get_sources.html">Cmdr - How To Get The Sources</a></i>.</p> <p>This document is for users of the cmdr framework. It introduces the |
︙ | ︙ | |||
215 216 217 218 219 220 221 222 223 224 225 226 227 | the name of the <i class="term">primary flag</i> recognized during the <i class="term">Parsing</i> phase. If that is not enough for a specific <i class="term">option</i> this command allows the specification of any number additional flags to be recognized.</p> <p>Note however that the framework automatically recognizes not only the specified flag(s), but also all their unique prefixes, obviating the need for this command in many cases.</p></dd> </dl> </div> <div id="subsection2" class="subsection"><h3><a name="subsection2">General control</a></h3> <p>The general handling of a <i class="term">parameter</i> is influenced by three commands:</p> <dl class="definitions"> | > > > > > > > > > > | | | | | 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 | the name of the <i class="term">primary flag</i> recognized during the <i class="term">Parsing</i> phase. If that is not enough for a specific <i class="term">option</i> this command allows the specification of any number additional flags to be recognized.</p> <p>Note however that the framework automatically recognizes not only the specified flag(s), but also all their unique prefixes, obviating the need for this command in many cases.</p></dd> <dt><a name="3"><b class="cmd">neg-alias</b> <i class="arg">name</i></a></dt> <dd></dd> <dt><a name="4"><b class="cmd">!alias</b> <i class="arg">name</i></a></dt> <dd><p>This command applies only to <i class="term">boolean</i> <i class="term">option</i>s. For them it allows the specification of any number additional flags to be recognized, which are aliases of its <em>inverted</em> form, i.e. of <b class="const">--no-FOO</b> for an option <b class="const">FOO</b>.</p> <p>This in contrast to <b class="cmd">alias</b>es, which are for the regular form of the option.</p> <p>Note further that the framework automatically recognizes not only the specified flag(s), but also all their unique prefixes, obviating the need for this command in many cases.</p></dd> </dl> </div> <div id="subsection2" class="subsection"><h3><a name="subsection2">General control</a></h3> <p>The general handling of a <i class="term">parameter</i> is influenced by three commands:</p> <dl class="definitions"> <dt><a name="5"><b class="cmd">no-promotion</b></a></dt> <dd><p>When the framework encounters an unknown flag during the <i class="term">Parsing</i> phase it will not unconditionally throw an error about it, but first check if the next available <i class="term">input</i> <i class="term">parameter</i> (if any) could accept the flag string as its value, per that <i class="term">input</i>'s <i class="term">validation type</i>, and if yes, does so.</p> <p>This command causes the rejection of such flag strings by this parameter on general principle, without having to validate it.</p> <p><em>Note</em> that it is only useful for and applicable to <i class="term">input</i> <i class="term"><a href="../../index.html#key12">parameters</a></i>.</p></dd> <dt><a name="6"><b class="cmd">optional</b></a></dt> <dd><p>This command marks the parameter as <i class="term">optional</i>, i.e. as something the user may skip on the command line, with the application supplying sensible defaults (See section <span class="sectref"><a href="#subsection3">Representations</a></span>). This causes the framework to expend some effort in the <i class="term">Parsing</i> phase to determine whether an argument word should be assigned to the parameter, or not.</p> <p>This setting is only applicable to <i class="term">input</i>s, as <i class="term">option</i>s are optional by definition, and <i class="term">state</i> is hidden.</p></dd> <dt><a name="7"><b class="cmd">test</b></a></dt> <dd><p>This command is related to the above, switching the runtime from the standard regime for acceptance (based on counting and thresholds) to a different regime based on validation.</p> <p>More details are explained in section <i class="term">Parsing</i> of <i class="term"><a href="cmdr_flow.html">Cmdr - Runtime Processing Flow</a></i>.</p></dd> <dt><a name="8"><b class="cmd">undocumented</b></a></dt> <dd><p>This command excludes the <i class="term">parameter</i> from the generated help.</p> <p>Its main use case is the hiding of <i class="term">option</i>s giving an application developer access to the internals of their application, something a regular user has no need of, and doesn't have to know about.</p></dd> </dl> </div> |
︙ | ︙ | |||
272 273 274 275 276 277 278 | The details of that process are explained in section <span class="sectref"><a href="#subsection4">Validation</a></span>. However we have cases where the user cannot specify a string representation (<i class="term">state</i>s), or is allowed to choose not to (optional <i class="term">input</i>s, <i class="term">option</i>s). For these cases three specification commands are made available enabling us to programmatically choose the internal representation.</p> <dl class="definitions"> | | | | | 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 | The details of that process are explained in section <span class="sectref"><a href="#subsection4">Validation</a></span>. However we have cases where the user cannot specify a string representation (<i class="term">state</i>s), or is allowed to choose not to (optional <i class="term">input</i>s, <i class="term">option</i>s). For these cases three specification commands are made available enabling us to programmatically choose the internal representation.</p> <dl class="definitions"> <dt><a name="9"><b class="cmd">default</b> <i class="arg">value</i></a></dt> <dd><p>This command specifies a constant default value for the internal representation.</p></dd> <dt><a name="10"><b class="cmd">generate</b> <i class="arg">cmdprefix</i></a></dt> <dd><p>This command specifies a callback to compute the default internal representation at runtime. This is useful if the default is something which cannot be captured as a fixed value. An example would be a handle to some resource, or a dynamically created object.</p> <p>The command prefix is invoked with a single argument, the <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> instance for which to generate the internal representation.</p></dd> </dl> <p>The commands <b class="cmd">default</b> and <b class="cmd">generate</b> exclude each other, i.e. only of them can be specified, but not both. If neither are specified, and we need a default (see the cases above) then a default is chosen by the framework itself, as per the two rules below:</p> <ol class="enumerated"> <li><p>Use the empty string for a <b class="cmd">list</b> parameter.</p></li> <li><p>Use the default value supplied by the chosen <i class="term">validation type</i> (See section <span class="sectref"><a href="#subsection4">Validation</a></span>).</p></li> </ol> <dl class="definitions"> <dt><a name="11"><b class="cmd">interact</b> <span class="opt">?<i class="arg">prompt</i>?</span></a></dt> <dd><p>This command actually does not specify an <i class="term">internal representation</i>, but activates another method for the user to specify the <i class="term">string representation</i> of the <i class="term">parameter</i>, outside of the command line. As such it has priority over either <b class="cmd">default</b> and <b class="cmd">generate</b>, and can be specified with either. A <i class="term">parameter</i> marked with it will interactively ask the user for a value if none was specified on |
︙ | ︙ | |||
324 325 326 327 328 329 330 | <li><p>After that the <i class="term">internal representation</i> is either the declared <b class="cmd">default</b> value, or the result of invoking the <b class="cmd">generate</b> callback. As <i class="term">internal representation</i>s the resulting values are <em>not</em> run through the chosen <i class="term">validation type</i>.</p></li> </ol> <dl class="definitions"> | | | 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 | <li><p>After that the <i class="term">internal representation</i> is either the declared <b class="cmd">default</b> value, or the result of invoking the <b class="cmd">generate</b> callback. As <i class="term">internal representation</i>s the resulting values are <em>not</em> run through the chosen <i class="term">validation type</i>.</p></li> </ol> <dl class="definitions"> <dt><a name="12"><b class="cmd">list</b></a></dt> <dd><p>This command marks the <i class="term">parameter</i> as a list. In other words, its <i class="term">string</i> and <i class="term">internal representation</i> is actually a list of such, instead of a single value. By default all parameters are scalar.</p> <p>This affects the handling of the parameter by the <i class="term">Parsing</i> phase, by <b class="cmd">interact</b> above, and the use of the <i class="term">validation type</i>. |
︙ | ︙ | |||
347 348 349 350 351 352 353 | this list-<i class="term">inputs</i> are only allowed as the last <i class="term">parameter</i> of a <i class="term">private</i>.</p></dd> </dl> <p>The last two specification commands dealing with the representations control <em>when</em> the <i class="term">internal representation</i> is created.</p> <dl class="definitions"> | | | | 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 | this list-<i class="term">inputs</i> are only allowed as the last <i class="term">parameter</i> of a <i class="term">private</i>.</p></dd> </dl> <p>The last two specification commands dealing with the representations control <em>when</em> the <i class="term">internal representation</i> is created.</p> <dl class="definitions"> <dt><a name="13"><b class="cmd">defered</b></a></dt> <dd><p>This command marks a <i class="term">parameter</i> as <i class="term">defered</i>, causing its <i class="term">internal representation</i> to be computed on first access to its value. This is the default for <i class="term">state</i> parameters.</p></dd> <dt><a name="14"><b class="cmd">immediate</b></a></dt> <dd><p>This command marks a <i class="term">parameter</i> as <i class="term">immediate</i>, causing its <i class="term">internal representation</i> to be computed in the <i class="term">Completion</i> phase. This is the default for <i class="term">input</i> and <i class="term">option</i> parameters.</p></dd> </dl> </div> <div id="subsection4" class="subsection"><h3><a name="subsection4">Validation</a></h3> |
︙ | ︙ | |||
376 377 378 379 380 381 382 | Cmdr expects all types to support an ensemble of <em>four</em> methods. One for the basic validation and transformation of the input, another for the release of any internal representation so generated, plus two more for delivery of a default representation and support for command line completion.</p> <dl class="definitions"> | | | | 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 | Cmdr expects all types to support an ensemble of <em>four</em> methods. One for the basic validation and transformation of the input, another for the release of any internal representation so generated, plus two more for delivery of a default representation and support for command line completion.</p> <dl class="definitions"> <dt><a name="15"><b class="cmd">validate</b> <i class="arg">cmdprefix</i></a></dt> <dd><p>This command specifies a <i class="term">validation type</i> for the <i class="term">parameter</i>, in the form of a command prefix (or the name of one of the builtin types, see package <b class="package"><a href="cmdr_validate.html">cmdr::validate</a></b>). The set of methods this callback has to support, their signatures, etc. are all explained in <i class="term"><a href="cmdr_vtypes.html">Cmdr - Writing custom validation types</a></i>. This document contains the implementation of the standard boolean validation type as an example as well.</p> <p>Because of the same necessity all <i class="term">parameter</i>s must have a <i class="term">validation type</i> assigned to them, and the system will choose which, if the user did not. This choice is made as per the six rules below and always returns one of the standard types implemented by package <b class="package"><a href="cmdr_validate.html">cmdr::validate</a></b>.</p> <ol class="enumerated"> <li><p>Use <b class="const">identity</b> if a <b class="cmd">generate</b> callback is specified.</p></li> <li><p>Use <b class="const">boolean</b> if no <b class="cmd">default</b> is specified and the parameter is an <i class="term">option</i>.</p></li> <li><p>Use <b class="const">identity</b> if no <b class="cmd">default</b> is specified and the parameter is an <i class="term">input</i>.</p></li> <li><p>Use <b class="const">boolean</b> if the specified <b class="cmd">default</b> value is a Tcl boolean.</p></li> <li><p>Use <b class="const">integer</b> if the specified <b class="cmd">default</b> value is a Tcl integer.</p></li> <li><p>Use <b class="const">identity</b> as fallback of last resort.</p></li> </ol></dd> <dt><a name="16"><b class="cmd">presence</b></a></dt> <dd><p>This command is best discussed as part of the wider area of <i class="term">boolean</i> <i class="term">option</i>s, i.e. <i class="term">option</i>s with the standard <i class="term">validation type</i> <b class="const">boolean</b> assigned to them. These have associated special behaviours, both in the handling of the specification, and in the <i class="term">Parsing</i> phase.</p> <p>First, normal boolean options. They have automatic aliases declared for them, derived from their |
︙ | ︙ | |||
442 443 444 445 446 447 448 | system, as complex scripts can be used via procedures or equivalents (i.e. <b class="cmd">apply</b>).</p> <p>The two callbacks not yet described are the state-change callbacks through which the framework can actively drive parts of the application while processing the command line, whereas normally the application drives access to parameters through their methods.</p> <dl class="definitions"> | | | | 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 | system, as complex scripts can be used via procedures or equivalents (i.e. <b class="cmd">apply</b>).</p> <p>The two callbacks not yet described are the state-change callbacks through which the framework can actively drive parts of the application while processing the command line, whereas normally the application drives access to parameters through their methods.</p> <dl class="definitions"> <dt><a name="17"><b class="cmd">when-complete</b> <i class="arg">cmdprefix</i></a></dt> <dd><p>This command declares the state-change callback to invoke when the <i class="term">internal representation</i> of the <i class="term">parameter</i> is generated from the <i class="term">string representation</i>, or the various ways of getting a default.</p> <p>The callback is invoked with two arguments, the <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> instance of the changed <i class="term">parameter</i>, and its <i class="term">internal representation</i>, in this order.</p></dd> <dt><a name="18"><b class="cmd">when-set</b> <i class="arg">cmdprefix</i></a></dt> <dd><p>This command declares the state-change callback to invoke when the <i class="term">string representation</i> of the <i class="term">parameter</i> is set during command line parsing.</p> <p>The callback is invoked with two arguments, the <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> instance of the changed <i class="term">parameter</i>, and its <i class="term">string representation</i>, in this order.</p></dd> </dl> |
︙ | ︙ |