cmdr
Check-in [b9126a7a27]
Not logged in
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:Added a behaviour flag "no-promote" to parameters, to allow rejection of promotion of unknown flag strings to input values on principle. Bumped version to 0.13, updated embedded documentation.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:b9126a7a27ed0cbf5c42eda11198d1fcedb7e7c7
User & Date: aku 2013-11-17 01:01:41
Context
2013-11-22
20:52
Modified officers. Auto-create an 'exit'-command, if not in conflict with user commands. Method as backend for private. Usable by others as well. Bumped version to 0.14. check-in: 8d7fcadf53 user: andreask tags: trunk
2013-11-17
01:01
Added a behaviour flag "no-promote" to parameters, to allow rejection of promotion of unknown flag strings to input values on principle. Bumped version to 0.13, updated embedded documentation. check-in: b9126a7a27 user: aku tags: trunk
2013-11-16
23:15
Moved dictsort utility into util for wider use. Sort parts of the help structures for easier testing. Fixed bugs in the help generation (1) Skip imported helper commands which are not formats. (2) Rendering of list inputs was off. -- Bumped version to 0.12, help (json, sql) to 0.2, fixed requirements -- Updated embedded documentation. check-in: 0ed8f3610b user: aku tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to actor.tcl.

309
310
311
312
313
314
315
316

    ##
    # # ## ### ##### ######## #############
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::actor 0.12







|
309
310
311
312
313
314
315
316

    ##
    # # ## ### ##### ######## #############
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::actor 0.13

build.tcl became a regular file.

Changes to cmdr.tcl.

71
72
73
74
75
76
77
78
proc ::cmdr::interactive? {} {
    variable interactive
    return  $interactive
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr 0.12







|
71
72
73
74
75
76
77
78
proc ::cmdr::interactive? {} {
    variable interactive
    return  $interactive
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr 0.13

Changes to config.tcl.

849
850
851
852
853
854
855

856
857
858

859

860
861
862
863
864
865
866
....
1356
1357
1358
1359
1360
1361
1362
1363
		debug.cmdr/config {[P size] ? $word}
		if {[string match -* $word]} {
		    try {
			my ProcessOption
		    } trap {CMDR CONFIG BAD OPTION} {e o} {
			# Test if we have regular arguments left, and
			# if the first of them is willing to accept

			# the word. If yes, the bad option is treated
			# as regular argument.
			if {![A size] ||

			    ![[dict get $mymap [A peek]] accept $word]} {

			    return {*}$o $e
			}

			debug.cmdr/config {as argument}
			P unget $word
			my ProcessArgument
		    }
................................................................................
    }

    # # ## ### ##### ######## #############
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::config 0.12







>
|
|

>

>







 







|
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
....
1359
1360
1361
1362
1363
1364
1365
1366
		debug.cmdr/config {[P size] ? $word}
		if {[string match -* $word]} {
		    try {
			my ProcessOption
		    } trap {CMDR CONFIG BAD OPTION} {e o} {
			# Test if we have regular arguments left, and
			# if the first of them is willing to accept
			# the word (on principle, and by type). If
			# yes, the bad option is treated as regular
			# argument.
			if {![A size] ||
			    [[dict get $mymap [A peek]] nopromote] ||
			    ![[dict get $mymap [A peek]] accept $word]} {
			    # Not accepted, throw as error.
			    return {*}$o $e
			}

			debug.cmdr/config {as argument}
			P unget $word
			my ProcessArgument
		    }
................................................................................
    }

    # # ## ### ##### ######## #############
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::config 0.13

Changes to doc/cmdr_parameter.man.

349
350
351
352
353
354
355






356
357
358
359
360
361
362
modification.
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method name]]

This method returns the internal name of the parameter.







[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method options]]

This method returns the list of option flags recognized
by the parameter. 








>
>
>
>
>
>







349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
modification.
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method name]]

This method returns the internal name of the parameter.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method nopromote]]

This method returns the state of the non-promotion flag of the
parameter.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method options]]

This method returns the list of option flags recognized
by the parameter. 

Changes to doc/parts/dsl_para_general.inc.

1
2
3
4
5















6
7
8
9
10
11
12

[para] The general handling of a [term parameter] is influenced by
three commands:

[list_begin definitions]
















[comment {- - -- --- ----- -------- -------------}]
[call [cmd optional]]

This command marks the parameter as [term optional], i.e. as something
the user may skip on the command line, with the application supplying
sensible defaults (See section [sectref Representations]).





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







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

[para] The general handling of a [term parameter] is influenced by
three commands:

[list_begin definitions]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd no-promotion]]

When the framework encounters an unknown flag during the
[term Parsing] phase it will not unconditionally throw an error about
it, but first check if the next available [term input]
[term parameter] (if any) could accept the flag string as its value,
per that [term input]'s [term {validation type}], and if yes, does so.

[para] This command causes the rejection of such flag strings by this
parameter on general principle, without having to validate it.

[para] [emph Note] that it is only useful for and applicable to
[term input] [term parameters].

[comment {- - -- --- ----- -------- -------------}]
[call [cmd optional]]

This command marks the parameter as [term optional], i.e. as something
the user may skip on the command line, with the application supplying
sensible defaults (See section [sectref Representations]).

Changes to embedded/man/files/cmdr_dsl_parameter.n.

244
245
246
247
248
249
250


251
252
253
254
255
256
257
...
359
360
361
362
363
364
365













366
367
368
369
370
371
372
.SH NAME
cmdr_dsl_parameter \- Cmdr - Parameter Specification Language
.SH SYNOPSIS
\fBlabel\fR \fItext\fR
.sp
\fBalias\fR \fIname\fR
.sp


\fBoptional\fR
.sp
\fBtest\fR
.sp
\fBundocumented\fR
.sp
\fBdefault\fR \fIvalue\fR
................................................................................
.PP
.PP
.SS "GENERAL CONTROL"
.PP
The general handling of a \fIparameter\fR is influenced by
three commands:
.TP













\fBoptional\fR
This command marks the parameter as \fIoptional\fR, i\&.e\&. as something
the user may skip on the command line, with the application supplying
sensible defaults (See section \fBRepresentations\fR)\&.
This causes the framework to expend some effort in the \fIParsing\fR
phase to determine whether an argument word should be assigned to the
parameter, or not\&.







>
>







 







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







244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
...
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
.SH NAME
cmdr_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
.sp
\fBdefault\fR \fIvalue\fR
................................................................................
.PP
.PP
.SS "GENERAL CONTROL"
.PP
The general handling of a \fIparameter\fR is influenced by
three commands:
.TP
\fBno-promotion\fR
When the framework encounters an unknown flag during the
\fIParsing\fR phase it will not unconditionally throw an error about
it, but first check if the next available \fIinput\fR
\fIparameter\fR (if any) could accept the flag string as its value,
per that \fIinput\fR's \fIvalidation type\fR, and if yes, does so\&.
.sp
This command causes the rejection of such flag strings by this
parameter on general principle, without having to validate it\&.
.sp
\fINote\fR that it is only useful for and applicable to
\fIinput\fR \fIparameters\fR\&.
.TP
\fBoptional\fR
This command marks the parameter as \fIoptional\fR, i\&.e\&. as something
the user may skip on the command line, with the application supplying
sensible defaults (See section \fBRepresentations\fR)\&.
This causes the framework to expend some effort in the \fIParsing\fR
phase to determine whether an argument word should be assigned to the
parameter, or not\&.

Changes to embedded/man/files/cmdr_parameter.n.

294
295
296
297
298
299
300


301
302
303
304
305
306
307
...
619
620
621
622
623
624
625




626
627
628
629
630
631
632
.sp
\fB<parameter>\fR \fBlocker\fR
.sp
\fB<parameter>\fR \fBlock\fR \fIreason\fR
.sp
\fB<parameter>\fR \fBname\fR
.sp


\fB<parameter>\fR \fBoptions\fR
.sp
\fB<parameter>\fR \fBordered\fR
.sp
\fB<parameter>\fR \fBpresence\fR
.sp
\fB<parameter>\fR \fBprimary\fR \fIoption\fR
................................................................................
string \fIreason\fR
The name of the parameter locking this one against further
modification\&.
.RE
.TP
\fB<parameter>\fR \fBname\fR
This method returns the internal name of the parameter\&.




.TP
\fB<parameter>\fR \fBoptions\fR
This method returns the list of option flags recognized
by the parameter\&.
.TP
\fB<parameter>\fR \fBordered\fR
This accessor method returns the "order" flag







>
>







 







>
>
>
>







294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
...
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
.sp
\fB<parameter>\fR \fBlocker\fR
.sp
\fB<parameter>\fR \fBlock\fR \fIreason\fR
.sp
\fB<parameter>\fR \fBname\fR
.sp
\fB<parameter>\fR \fBnopromote\fR
.sp
\fB<parameter>\fR \fBoptions\fR
.sp
\fB<parameter>\fR \fBordered\fR
.sp
\fB<parameter>\fR \fBpresence\fR
.sp
\fB<parameter>\fR \fBprimary\fR \fIoption\fR
................................................................................
string \fIreason\fR
The name of the parameter locking this one against further
modification\&.
.RE
.TP
\fB<parameter>\fR \fBname\fR
This method returns the internal name of the parameter\&.
.TP
\fB<parameter>\fR \fBnopromote\fR
This method returns the state of the non-promotion flag of the
parameter\&.
.TP
\fB<parameter>\fR \fBoptions\fR
This method returns the list of option flags recognized
by the parameter\&.
.TP
\fB<parameter>\fR \fBordered\fR
This accessor method returns the "order" flag

Changes to embedded/www/doc/files/cmdr_dsl_parameter.html.

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
...
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
...
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
...
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
...
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
...
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
...
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
...
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
...
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
</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">optional</b></a></li>
<li><a href="#4"><b class="cmd">test</b></a></li>
<li><a href="#5"><b class="cmd">undocumented</b></a></li>
<li><a href="#6"><b class="cmd">default</b> <i class="arg">value</i></a></li>
<li><a href="#7"><b class="cmd">generate</b> <i class="arg">cmdprefix</i></a></li>
<li><a href="#8"><b class="cmd">interact</b> <span class="opt">?<i class="arg">prompt</i>?</span></a></li>
<li><a href="#9"><b class="cmd">list</b></a></li>
<li><a href="#10"><b class="cmd">defered</b></a></li>
<li><a href="#11"><b class="cmd">immediate</b></a></li>
<li><a href="#12"><b class="cmd">validate</b> <i class="arg">cmdprefix</i></a></li>
<li><a href="#13"><b class="cmd">presence</b></a></li>
<li><a href="#14"><b class="cmd">when-complete</b> <i class="arg">cmdprefix</i></a></li>
<li><a href="#15"><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
................................................................................
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="3"><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="4"><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.
The details are explained in --TODO--(sectref:flow/parsing,flow/optional)--.</p></dd>
<dt><a name="5"><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>
................................................................................
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="6"><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="7"><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>
................................................................................
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="8"><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
................................................................................
<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="9"><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>.
................................................................................
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="10"><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="11"><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>
................................................................................
Where snit's types expect only a single method to validate the input
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 delivery of a default representation and support for command line
completion.</p>
<dl class="definitions">
<dt><a name="12"><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>
................................................................................
<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="13"><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
................................................................................
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="14"><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="15"><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>







>
|
|
|
|
|
|
|
|
|
|
|
|
|







 







>
>
>
>
>
>
>
>
>
>
|








|




|







 







|


|







 







|







 







|







 







|



|







 







|







 







|







 







|







|







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
...
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
...
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
...
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
...
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
...
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
...
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
...
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
...
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
</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">no-promotion</b></a></li>
<li><a href="#4"><b class="cmd">optional</b></a></li>
<li><a href="#5"><b class="cmd">test</b></a></li>
<li><a href="#6"><b class="cmd">undocumented</b></a></li>
<li><a href="#7"><b class="cmd">default</b> <i class="arg">value</i></a></li>
<li><a href="#8"><b class="cmd">generate</b> <i class="arg">cmdprefix</i></a></li>
<li><a href="#9"><b class="cmd">interact</b> <span class="opt">?<i class="arg">prompt</i>?</span></a></li>
<li><a href="#10"><b class="cmd">list</b></a></li>
<li><a href="#11"><b class="cmd">defered</b></a></li>
<li><a href="#12"><b class="cmd">immediate</b></a></li>
<li><a href="#13"><b class="cmd">validate</b> <i class="arg">cmdprefix</i></a></li>
<li><a href="#14"><b class="cmd">presence</b></a></li>
<li><a href="#15"><b class="cmd">when-complete</b> <i class="arg">cmdprefix</i></a></li>
<li><a href="#16"><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
................................................................................
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="3"><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="4"><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="5"><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.
The details are explained in --TODO--(sectref:flow/parsing,flow/optional)--.</p></dd>
<dt><a name="6"><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>
................................................................................
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="7"><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="8"><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>
................................................................................
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="9"><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
................................................................................
<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="10"><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>.
................................................................................
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="11"><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="12"><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>
................................................................................
Where snit's types expect only a single method to validate the input
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 delivery of a default representation and support for command line
completion.</p>
<dl class="definitions">
<dt><a name="13"><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>
................................................................................
<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="14"><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
................................................................................
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="15"><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="16"><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>

Changes to embedded/www/doc/files/cmdr_parameter.html.

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
...
408
409
410
411
412
413
414



415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
<li><a href="#20"><b class="cmd">&lt;parameter&gt;</b> <b class="method">isbool</b></a></li>
<li><a href="#21"><b class="cmd">&lt;parameter&gt;</b> <b class="method">is</b> <i class="arg">type</i></a></li>
<li><a href="#22"><b class="cmd">&lt;parameter&gt;</b> <b class="method">label</b></a></li>
<li><a href="#23"><b class="cmd">&lt;parameter&gt;</b> <b class="method">list</b></a></li>
<li><a href="#24"><b class="cmd">&lt;parameter&gt;</b> <b class="method">locker</b></a></li>
<li><a href="#25"><b class="cmd">&lt;parameter&gt;</b> <b class="method">lock</b> <i class="arg">reason</i></a></li>
<li><a href="#26"><b class="cmd">&lt;parameter&gt;</b> <b class="method">name</b></a></li>

<li><a href="#27"><b class="cmd">&lt;parameter&gt;</b> <b class="method">options</b></a></li>
<li><a href="#28"><b class="cmd">&lt;parameter&gt;</b> <b class="method">ordered</b></a></li>
<li><a href="#29"><b class="cmd">&lt;parameter&gt;</b> <b class="method">presence</b></a></li>
<li><a href="#30"><b class="cmd">&lt;parameter&gt;</b> <b class="method">primary</b> <i class="arg">option</i></a></li>
<li><a href="#31"><b class="cmd">&lt;parameter&gt;</b> <b class="method">process</b> <i class="arg">detail</i> <i class="arg">queue</i></a></li>
<li><a href="#32"><b class="cmd">&lt;parameter&gt;</b> <b class="method">prompt</b></a></li>
<li><a href="#33"><b class="cmd">&lt;parameter&gt;</b> <b class="method">required</b></a></li>
<li><a href="#34"><b class="cmd">&lt;parameter&gt;</b> <b class="method">reset</b> <span class="opt">?<i class="arg">cleanup</i>?</span></a></li>
<li><a href="#35"><b class="cmd">&lt;parameter&gt;</b> <b class="method">self</b></a></li>
<li><a href="#36"><b class="cmd">&lt;parameter&gt;</b> <b class="method">set?</b></a></li>
<li><a href="#37"><b class="cmd">&lt;parameter&gt;</b> <b class="method">setq</b> <i class="arg">queue</i></a></li>
<li><a href="#38"><b class="cmd">&lt;parameter&gt;</b> <b class="method">set</b> <i class="arg">value</i></a></li>
<li><a href="#39"><b class="cmd">&lt;parameter&gt;</b> <b class="method">string</b></a></li>
<li><a href="#40"><b class="cmd">&lt;parameter&gt;</b> <b class="method">threshold:</b> <i class="arg">n</i></a></li>
<li><a href="#41"><b class="cmd">&lt;parameter&gt;</b> <b class="method">threshold</b></a></li>
<li><a href="#42"><b class="cmd">&lt;parameter&gt;</b> <b class="method">type</b></a></li>
<li><a href="#43"><b class="cmd">&lt;parameter&gt;</b> <b class="method">undefined!</b></a></li>
<li><a href="#44"><b class="cmd">&lt;parameter&gt;</b> <b class="method">validator</b></a></li>
<li><a href="#45"><b class="cmd">&lt;parameter&gt;</b> <b class="method">value</b></a></li>
<li><a href="#46"><b class="cmd">&lt;parameter&gt;</b> <b class="method">when-complete</b></a></li>
<li><a href="#47"><b class="cmd">&lt;parameter&gt;</b> <b class="method">when-set</b></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 package implements <em>parameters</em>, collections of which (see
................................................................................
<dl class="arguments">
<dt>string <i class="arg">reason</i></dt>
<dd><p>The name of the parameter locking this one against further
modification.</p></dd>
</dl></dd>
<dt><a name="26"><b class="cmd">&lt;parameter&gt;</b> <b class="method">name</b></a></dt>
<dd><p>This method returns the internal name of the parameter.</p></dd>



<dt><a name="27"><b class="cmd">&lt;parameter&gt;</b> <b class="method">options</b></a></dt>
<dd><p>This method returns the list of option flags recognized
by the parameter.</p></dd>
<dt><a name="28"><b class="cmd">&lt;parameter&gt;</b> <b class="method">ordered</b></a></dt>
<dd><p>This accessor method returns the &quot;order&quot; flag
set during parameter construction.
A result of <b class="const">true</b> indicates that the parameter
is specified by order at runtime (argument), and otherwise
(<b class="const">false</b>) by name (option).</p></dd>
<dt><a name="29"><b class="cmd">&lt;parameter&gt;</b> <b class="method">presence</b></a></dt>
<dd><p>This method returns a boolean value indicating if
the option parameter is set as presence-option
(<b class="const">true</b>) or not (<b class="const">false</b>).
The parts of the parameter responsible for processing option
arguments use this information to invoke the hard-wired special
cases for presence, or not.</p></dd>
<dt><a name="30"><b class="cmd">&lt;parameter&gt;</b> <b class="method">primary</b> <i class="arg">option</i></a></dt>
<dd><p>This method returns a boolean value indicating if the named <i class="arg">option</i>
is the primary option of this parameter (<b class="const">true</b>), or not (<b class="const">false</b>).
An error will be thrown if the named option is not controlled by the parameter.</p>
<dl class="arguments">
<dt>string <i class="arg">option</i></dt>
<dd><p>The name of the option to check.</p></dd>
</dl></dd>
<dt><a name="31"><b class="cmd">&lt;parameter&gt;</b> <b class="method">process</b> <i class="arg">detail</i> <i class="arg">queue</i></a></dt>
<dd><p>This method extracts the value of the parameter from the command line.
A <b class="method">presence</b> option takes nothing, whereas an <b class="method">isbool</b> option
takes the first value in the <i class="arg">queue</i>, if it is a proper boolean, and
defaults to <b class="const">true</b> if not. Any other argument or option takes  the
first value in <i class="arg">queue</i>.</p>
<dl class="arguments">
<dt>string <i class="arg">detail</i></dt>
<dd><p>The name of the parameter, or the option flag referencing it.</p></dd>
<dt>struct::queue <i class="arg">queue</i></dt>
<dd><p>The queue instance holding the words of the command line not yet
processed by the system.</p></dd>
</dl></dd>
<dt><a name="32"><b class="cmd">&lt;parameter&gt;</b> <b class="method">prompt</b></a></dt>
<dd><p>This method returns the prompt string used by the parameter for
interactive entry. If not overridden by the parameter's specification
this defaults to a string derived from the internal name of the
parameter, i.e. &quot;Enter <b class="variable">name</b>:&quot;.</p></dd>
<dt><a name="33"><b class="cmd">&lt;parameter&gt;</b> <b class="method">required</b></a></dt>
<dd><p>This accessor method returns the &quot;required&quot; flag
set during parameter construction.
A result of <b class="const">true</b> indicates that the parameter
must be specified by the user at runtime, and otherwise
may be left unspecified (<b class="const">false</b>).</p></dd>
<dt><a name="34"><b class="cmd">&lt;parameter&gt;</b> <b class="method">reset</b> <span class="opt">?<i class="arg">cleanup</i>?</span></a></dt>
<dd><p>This method sets the parameter into the initial state where
it has neither string nor internal representation, nor is
it locked. This is a stronger form of <b class="method">forget</b>.</p>
<dl class="arguments">
<dt>boolean <i class="arg">cleanup</i></dt>
<dd></dd>
</dl></dd>
<dt><a name="35"><b class="cmd">&lt;parameter&gt;</b> <b class="method">self</b></a></dt>
<dd><p>This method returns the parameter instance itself.</p></dd>
<dt><a name="36"><b class="cmd">&lt;parameter&gt;</b> <b class="method">set?</b></a></dt>
<dd><p>This accessor method returns a boolean value indicating
if the parameter was given a string representation at
runtime (<b class="const">true</b>), or not (<b class="const">false</b>).</p></dd>
<dt><a name="37"><b class="cmd">&lt;parameter&gt;</b> <b class="method">setq</b> <i class="arg">queue</i></a></dt>
<dd><p>This method sets the first element of the <i class="arg">queue</i>
as the value of the parameter.
For a &quot;list&quot; parameter all elements of the queue are
taken as the new value of the parameter.
This is not quite analogous to method <b class="method">set</b> below.
They behave the same for scalar parameters, and differ
for &quot;list&quot; parameters.</p>
<dl class="arguments">
<dt>stack::queue <i class="arg">queue</i></dt>
<dd><p>The queue instance holding the words of the command
line not yet processed.</p></dd>
</dl></dd>
<dt><a name="38"><b class="cmd">&lt;parameter&gt;</b> <b class="method">set</b> <i class="arg">value</i></a></dt>
<dd><p>This method sets the <i class="arg">value</i> as the new string
representation of the parameter.
For a &quot;list&quot; parameter the string representation is
<em>extended</em> with the <i class="arg">value</i>.
This action triggers the execution of the &quot;when-set&quot; callback.
A previously existing internal representation is
forgotten (See <b class="method">forget</b>).</p>
<dl class="arguments">
<dt>string <i class="arg">value</i></dt>
<dd><p>The new value of the parameter, or an extension of the
existing value.</p></dd>
</dl></dd>
<dt><a name="39"><b class="cmd">&lt;parameter&gt;</b> <b class="method">string</b></a></dt>
<dd><p>This accessor method returns the string representation of
the parameter. If such was not set an error will be thrown
(See method <b class="method">undefined!</b>).</p></dd>
<dt><a name="40"><b class="cmd">&lt;parameter&gt;</b> <b class="method">threshold:</b> <i class="arg">n</i></a></dt>
<dd><p>This method specifies the minimum number of words needed after
the optional argument parameter for it to accept the current
word for itself.
Parameters which are not optional arguments ignore this method.
The result of the method is the empty string.</p>
<dl class="arguments">
<dt>integer <i class="arg">n</i></dt>
<dd><p>The acceptance threshold for the parameter.</p></dd>
</dl></dd>
<dt><a name="41"><b class="cmd">&lt;parameter&gt;</b> <b class="method">threshold</b></a></dt>
<dd><p>This method returns the threshold set on the parameter.
An empty string indicates a parameter without threshold.
A value of -1 indicates that the optional argument accepts
based on validation (See method <b class="method">accept</b>) instead
of using a threshold.</p></dd>
<dt><a name="42"><b class="cmd">&lt;parameter&gt;</b> <b class="method">type</b></a></dt>
<dd><p>This accessor method returns the type of the parameter, one of
<b class="const">argument</b>, <b class="const">option</b>, or <b class="const">state</b>. See also
method <b class="method">is</b> for type-checking.</p></dd>
<dt><a name="43"><b class="cmd">&lt;parameter&gt;</b> <b class="method">undefined!</b></a></dt>
<dd><p>This method explicitly throws a &quot;parameter undefined&quot; error
for this parameter.</p></dd>
<dt><a name="44"><b class="cmd">&lt;parameter&gt;</b> <b class="method">validator</b></a></dt>
<dd><p>This method returns the &quot;validate&quot; command prefix callback
(i.e. the parameter's validation type).</p></dd>
<dt><a name="45"><b class="cmd">&lt;parameter&gt;</b> <b class="method">value</b></a></dt>
<dd><p>This accessor method returns the internal representation of
the parameter. If necessary the data is computed from the
parameter's string representation, &quot;default&quot; value, or
&quot;generate&quot; callback.
An error is thrown if the value could not be determined.
(See method <b class="method">undefined!</b>).
If the value is newly computed the action triggers the
execution of the &quot;when-complete&quot; callback.</p>
<p>--TODO-- describe generation rules and order.</p></dd>
<dt><a name="46"><b class="cmd">&lt;parameter&gt;</b> <b class="method">when-complete</b></a></dt>
<dd><p>This method returns the &quot;when-complete&quot; command prefix callback,
if it was set, and an empty list otherwise.</p></dd>
<dt><a name="47"><b class="cmd">&lt;parameter&gt;</b> <b class="method">when-set</b></a></dt>
<dd><p>This method returns the &quot;when-set&quot; command prefix callback,
if it was set, and an empty list otherwise.</p></dd>
</dl>
</div>
<div id="section4" class="section"><h2><a name="section4">Help Information</a></h2>
<p>The help information generated for parameters is a
dictionary containing the keys below:</p>







>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|







 







>
>
>
|


|





|






|







|












|




|





|







|

|



|












|












|



|









|





|



|


|


|









|


|







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
...
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
<li><a href="#20"><b class="cmd">&lt;parameter&gt;</b> <b class="method">isbool</b></a></li>
<li><a href="#21"><b class="cmd">&lt;parameter&gt;</b> <b class="method">is</b> <i class="arg">type</i></a></li>
<li><a href="#22"><b class="cmd">&lt;parameter&gt;</b> <b class="method">label</b></a></li>
<li><a href="#23"><b class="cmd">&lt;parameter&gt;</b> <b class="method">list</b></a></li>
<li><a href="#24"><b class="cmd">&lt;parameter&gt;</b> <b class="method">locker</b></a></li>
<li><a href="#25"><b class="cmd">&lt;parameter&gt;</b> <b class="method">lock</b> <i class="arg">reason</i></a></li>
<li><a href="#26"><b class="cmd">&lt;parameter&gt;</b> <b class="method">name</b></a></li>
<li><a href="#27"><b class="cmd">&lt;parameter&gt;</b> <b class="method">nopromote</b></a></li>
<li><a href="#28"><b class="cmd">&lt;parameter&gt;</b> <b class="method">options</b></a></li>
<li><a href="#29"><b class="cmd">&lt;parameter&gt;</b> <b class="method">ordered</b></a></li>
<li><a href="#30"><b class="cmd">&lt;parameter&gt;</b> <b class="method">presence</b></a></li>
<li><a href="#31"><b class="cmd">&lt;parameter&gt;</b> <b class="method">primary</b> <i class="arg">option</i></a></li>
<li><a href="#32"><b class="cmd">&lt;parameter&gt;</b> <b class="method">process</b> <i class="arg">detail</i> <i class="arg">queue</i></a></li>
<li><a href="#33"><b class="cmd">&lt;parameter&gt;</b> <b class="method">prompt</b></a></li>
<li><a href="#34"><b class="cmd">&lt;parameter&gt;</b> <b class="method">required</b></a></li>
<li><a href="#35"><b class="cmd">&lt;parameter&gt;</b> <b class="method">reset</b> <span class="opt">?<i class="arg">cleanup</i>?</span></a></li>
<li><a href="#36"><b class="cmd">&lt;parameter&gt;</b> <b class="method">self</b></a></li>
<li><a href="#37"><b class="cmd">&lt;parameter&gt;</b> <b class="method">set?</b></a></li>
<li><a href="#38"><b class="cmd">&lt;parameter&gt;</b> <b class="method">setq</b> <i class="arg">queue</i></a></li>
<li><a href="#39"><b class="cmd">&lt;parameter&gt;</b> <b class="method">set</b> <i class="arg">value</i></a></li>
<li><a href="#40"><b class="cmd">&lt;parameter&gt;</b> <b class="method">string</b></a></li>
<li><a href="#41"><b class="cmd">&lt;parameter&gt;</b> <b class="method">threshold:</b> <i class="arg">n</i></a></li>
<li><a href="#42"><b class="cmd">&lt;parameter&gt;</b> <b class="method">threshold</b></a></li>
<li><a href="#43"><b class="cmd">&lt;parameter&gt;</b> <b class="method">type</b></a></li>
<li><a href="#44"><b class="cmd">&lt;parameter&gt;</b> <b class="method">undefined!</b></a></li>
<li><a href="#45"><b class="cmd">&lt;parameter&gt;</b> <b class="method">validator</b></a></li>
<li><a href="#46"><b class="cmd">&lt;parameter&gt;</b> <b class="method">value</b></a></li>
<li><a href="#47"><b class="cmd">&lt;parameter&gt;</b> <b class="method">when-complete</b></a></li>
<li><a href="#48"><b class="cmd">&lt;parameter&gt;</b> <b class="method">when-set</b></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 package implements <em>parameters</em>, collections of which (see
................................................................................
<dl class="arguments">
<dt>string <i class="arg">reason</i></dt>
<dd><p>The name of the parameter locking this one against further
modification.</p></dd>
</dl></dd>
<dt><a name="26"><b class="cmd">&lt;parameter&gt;</b> <b class="method">name</b></a></dt>
<dd><p>This method returns the internal name of the parameter.</p></dd>
<dt><a name="27"><b class="cmd">&lt;parameter&gt;</b> <b class="method">nopromote</b></a></dt>
<dd><p>This method returns the state of the non-promotion flag of the
parameter.</p></dd>
<dt><a name="28"><b class="cmd">&lt;parameter&gt;</b> <b class="method">options</b></a></dt>
<dd><p>This method returns the list of option flags recognized
by the parameter.</p></dd>
<dt><a name="29"><b class="cmd">&lt;parameter&gt;</b> <b class="method">ordered</b></a></dt>
<dd><p>This accessor method returns the &quot;order&quot; flag
set during parameter construction.
A result of <b class="const">true</b> indicates that the parameter
is specified by order at runtime (argument), and otherwise
(<b class="const">false</b>) by name (option).</p></dd>
<dt><a name="30"><b class="cmd">&lt;parameter&gt;</b> <b class="method">presence</b></a></dt>
<dd><p>This method returns a boolean value indicating if
the option parameter is set as presence-option
(<b class="const">true</b>) or not (<b class="const">false</b>).
The parts of the parameter responsible for processing option
arguments use this information to invoke the hard-wired special
cases for presence, or not.</p></dd>
<dt><a name="31"><b class="cmd">&lt;parameter&gt;</b> <b class="method">primary</b> <i class="arg">option</i></a></dt>
<dd><p>This method returns a boolean value indicating if the named <i class="arg">option</i>
is the primary option of this parameter (<b class="const">true</b>), or not (<b class="const">false</b>).
An error will be thrown if the named option is not controlled by the parameter.</p>
<dl class="arguments">
<dt>string <i class="arg">option</i></dt>
<dd><p>The name of the option to check.</p></dd>
</dl></dd>
<dt><a name="32"><b class="cmd">&lt;parameter&gt;</b> <b class="method">process</b> <i class="arg">detail</i> <i class="arg">queue</i></a></dt>
<dd><p>This method extracts the value of the parameter from the command line.
A <b class="method">presence</b> option takes nothing, whereas an <b class="method">isbool</b> option
takes the first value in the <i class="arg">queue</i>, if it is a proper boolean, and
defaults to <b class="const">true</b> if not. Any other argument or option takes  the
first value in <i class="arg">queue</i>.</p>
<dl class="arguments">
<dt>string <i class="arg">detail</i></dt>
<dd><p>The name of the parameter, or the option flag referencing it.</p></dd>
<dt>struct::queue <i class="arg">queue</i></dt>
<dd><p>The queue instance holding the words of the command line not yet
processed by the system.</p></dd>
</dl></dd>
<dt><a name="33"><b class="cmd">&lt;parameter&gt;</b> <b class="method">prompt</b></a></dt>
<dd><p>This method returns the prompt string used by the parameter for
interactive entry. If not overridden by the parameter's specification
this defaults to a string derived from the internal name of the
parameter, i.e. &quot;Enter <b class="variable">name</b>:&quot;.</p></dd>
<dt><a name="34"><b class="cmd">&lt;parameter&gt;</b> <b class="method">required</b></a></dt>
<dd><p>This accessor method returns the &quot;required&quot; flag
set during parameter construction.
A result of <b class="const">true</b> indicates that the parameter
must be specified by the user at runtime, and otherwise
may be left unspecified (<b class="const">false</b>).</p></dd>
<dt><a name="35"><b class="cmd">&lt;parameter&gt;</b> <b class="method">reset</b> <span class="opt">?<i class="arg">cleanup</i>?</span></a></dt>
<dd><p>This method sets the parameter into the initial state where
it has neither string nor internal representation, nor is
it locked. This is a stronger form of <b class="method">forget</b>.</p>
<dl class="arguments">
<dt>boolean <i class="arg">cleanup</i></dt>
<dd></dd>
</dl></dd>
<dt><a name="36"><b class="cmd">&lt;parameter&gt;</b> <b class="method">self</b></a></dt>
<dd><p>This method returns the parameter instance itself.</p></dd>
<dt><a name="37"><b class="cmd">&lt;parameter&gt;</b> <b class="method">set?</b></a></dt>
<dd><p>This accessor method returns a boolean value indicating
if the parameter was given a string representation at
runtime (<b class="const">true</b>), or not (<b class="const">false</b>).</p></dd>
<dt><a name="38"><b class="cmd">&lt;parameter&gt;</b> <b class="method">setq</b> <i class="arg">queue</i></a></dt>
<dd><p>This method sets the first element of the <i class="arg">queue</i>
as the value of the parameter.
For a &quot;list&quot; parameter all elements of the queue are
taken as the new value of the parameter.
This is not quite analogous to method <b class="method">set</b> below.
They behave the same for scalar parameters, and differ
for &quot;list&quot; parameters.</p>
<dl class="arguments">
<dt>stack::queue <i class="arg">queue</i></dt>
<dd><p>The queue instance holding the words of the command
line not yet processed.</p></dd>
</dl></dd>
<dt><a name="39"><b class="cmd">&lt;parameter&gt;</b> <b class="method">set</b> <i class="arg">value</i></a></dt>
<dd><p>This method sets the <i class="arg">value</i> as the new string
representation of the parameter.
For a &quot;list&quot; parameter the string representation is
<em>extended</em> with the <i class="arg">value</i>.
This action triggers the execution of the &quot;when-set&quot; callback.
A previously existing internal representation is
forgotten (See <b class="method">forget</b>).</p>
<dl class="arguments">
<dt>string <i class="arg">value</i></dt>
<dd><p>The new value of the parameter, or an extension of the
existing value.</p></dd>
</dl></dd>
<dt><a name="40"><b class="cmd">&lt;parameter&gt;</b> <b class="method">string</b></a></dt>
<dd><p>This accessor method returns the string representation of
the parameter. If such was not set an error will be thrown
(See method <b class="method">undefined!</b>).</p></dd>
<dt><a name="41"><b class="cmd">&lt;parameter&gt;</b> <b class="method">threshold:</b> <i class="arg">n</i></a></dt>
<dd><p>This method specifies the minimum number of words needed after
the optional argument parameter for it to accept the current
word for itself.
Parameters which are not optional arguments ignore this method.
The result of the method is the empty string.</p>
<dl class="arguments">
<dt>integer <i class="arg">n</i></dt>
<dd><p>The acceptance threshold for the parameter.</p></dd>
</dl></dd>
<dt><a name="42"><b class="cmd">&lt;parameter&gt;</b> <b class="method">threshold</b></a></dt>
<dd><p>This method returns the threshold set on the parameter.
An empty string indicates a parameter without threshold.
A value of -1 indicates that the optional argument accepts
based on validation (See method <b class="method">accept</b>) instead
of using a threshold.</p></dd>
<dt><a name="43"><b class="cmd">&lt;parameter&gt;</b> <b class="method">type</b></a></dt>
<dd><p>This accessor method returns the type of the parameter, one of
<b class="const">argument</b>, <b class="const">option</b>, or <b class="const">state</b>. See also
method <b class="method">is</b> for type-checking.</p></dd>
<dt><a name="44"><b class="cmd">&lt;parameter&gt;</b> <b class="method">undefined!</b></a></dt>
<dd><p>This method explicitly throws a &quot;parameter undefined&quot; error
for this parameter.</p></dd>
<dt><a name="45"><b class="cmd">&lt;parameter&gt;</b> <b class="method">validator</b></a></dt>
<dd><p>This method returns the &quot;validate&quot; command prefix callback
(i.e. the parameter's validation type).</p></dd>
<dt><a name="46"><b class="cmd">&lt;parameter&gt;</b> <b class="method">value</b></a></dt>
<dd><p>This accessor method returns the internal representation of
the parameter. If necessary the data is computed from the
parameter's string representation, &quot;default&quot; value, or
&quot;generate&quot; callback.
An error is thrown if the value could not be determined.
(See method <b class="method">undefined!</b>).
If the value is newly computed the action triggers the
execution of the &quot;when-complete&quot; callback.</p>
<p>--TODO-- describe generation rules and order.</p></dd>
<dt><a name="47"><b class="cmd">&lt;parameter&gt;</b> <b class="method">when-complete</b></a></dt>
<dd><p>This method returns the &quot;when-complete&quot; command prefix callback,
if it was set, and an empty list otherwise.</p></dd>
<dt><a name="48"><b class="cmd">&lt;parameter&gt;</b> <b class="method">when-set</b></a></dt>
<dd><p>This method returns the &quot;when-set&quot; command prefix callback,
if it was set, and an empty list otherwise.</p></dd>
</dl>
</div>
<div id="section4" class="section"><h2><a name="section4">Help Information</a></h2>
<p>The help information generated for parameters is a
dictionary containing the keys below:</p>

Changes to help.tcl.

506
507
508
509
510
511
512
513

    return $categories
}


# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::help 0.12







|
506
507
508
509
510
511
512
513

    return $categories
}


# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::help 0.13

Changes to officer.tcl.

614
615
616
617
618
619
620
621
	myreplexit myhandler

    # # ## ### ##### ######## #############
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::officer 0.12







|
614
615
616
617
618
619
620
621
	myreplexit myhandler

    # # ## ### ##### ######## #############
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::officer 0.13

Changes to parameter.tcl.

71
72
73
74
75
76
77

78
79
80
81
82
83
84
...
175
176
177
178
179
180
181

182
183
184
185
186
187
188
...
212
213
214
215
216
217
218

219
220
221
222
223
224
225
...
259
260
261
262
263
264
265
266
267

268
269
270
271

272
273
274
275
276
277
278
...
360
361
362
363
364
365
366










367
368
369
370
371
372
373
...
509
510
511
512
513
514
515




516
517
518
519
520
521
522
....
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192

	set mydescription $desc		; # [R2]

	set myisordered   $order	; # [R3,4,5,6]
	set myiscmdline   $cmdline	; # [R3,4,5,6]
	set myisrequired  $required	; # [R7,8,9,10]
	set myisdefered   $defered      ; # [R ???]


	my C1_StateIsUnordered
	my C2_OptionIsOptional
	my C3_StateIsRequired

	set mystopinteraction no ;# specified interaction is not suppressed.
	set myislist       no ;# scalar vs list parameter
................................................................................
    }

    # Core classification properties
    method ordered      {} { return $myisordered }
    method cmdline      {} { return $myiscmdline }
    method required     {} { return $myisrequired }
    method defered      {} { return $myisdefered }


    method list         {} { return $myislist }
    method presence     {} { return $myonlypresence }
    method documented   {} { return $myisdocumented }
    method isbool       {} { return [expr {$myvalidate eq "::cmdr::validate::boolean"}] }
    method locker       {} { return $mylocker }

................................................................................
    method help {} {
	# Generate a dictionary describing the parameter configuration.
	if {[catch {
	    my code
	} thecode]} {
	    set thecode {}
	}

	return [dict create \
		    cmdline     $myiscmdline    \
		    code        $thecode        \
		    default     $mydefault      \
		    defered     $myisdefered    \
		    description $mydescription  \
		    documented  $myisdocumented \
................................................................................

	# Import the DSL commands to translate the specification.
	link \
	    {alias         Alias} \
	    {default       Default} \
	    {defered       Defered} \
	    {generate      Generate} \
	    {interact      Interact} \
	    {immediate     Immediate} \

	    {label         Label} \
	    {list          List} \
	    {presence      Presence} \
	    {optional      Optional} \

	    {test          Test} \
	    {undocumented  Undocumented} \
	    {validate      Validate} \
	    {when-complete WhenComplete} \
	    {when-set      WhenSet}
	eval $valuespec

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

    method Immediate {} {
	# Consider adding checks against current state, prevent use
	# of calls not making an actual change.
	set myisdefered no
	return
    }











    method Default {value} {
	my C9_PresenceDefaultConflict
	# Check most of the relevant constraint(s) after making the
	# change. That is easier than re-casting the expressions for
	# the proposed change.
	set myhasdefault yes
................................................................................
	my Assert {$myisordered} \
	{Option "@" has no test-mode}

    forward Test_NotRequired \
	my Assert {!$myisrequired} \
	{Required argument "@" has no test-mode}





    # # ## ### ##### ######## #############
    ## Internal: DSL support. General helpers.

    method Assert {expr msg} {
	# Note: list is a local command, we want the builtin
	if {[uplevel 1 [::list expr $expr]]} return
	return -code error \
................................................................................
    variable myname mylabel mydescription \
	myisordered myiscmdline myislist myisrequired \
	myinteractive myprompt mydefault myhasdefault \
	mywhencomplete mywhenset mygenerate myvalidate \
	myflags mythreshold myhasstring mystring \
	myhasvalue myvalue mylocker mystopinteraction \
	myisdocumented myonlypresence myisdefered \
	myisundefined

    # # ## ### ##### ######## #############
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::parameter 0.12







>







 







>







 







>







 







<

>


|

>







 







>
>
>
>
>
>
>
>
>
>







 







>
>
>
>







 







|






|
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
...
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
...
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
...
262
263
264
265
266
267
268

269
270
271
272
273
274
275
276
277
278
279
280
281
282
...
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
...
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
....
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210

	set mydescription $desc		; # [R2]

	set myisordered   $order	; # [R3,4,5,6]
	set myiscmdline   $cmdline	; # [R3,4,5,6]
	set myisrequired  $required	; # [R7,8,9,10]
	set myisdefered   $defered      ; # [R ???]
	set mynopromote   no

	my C1_StateIsUnordered
	my C2_OptionIsOptional
	my C3_StateIsRequired

	set mystopinteraction no ;# specified interaction is not suppressed.
	set myislist       no ;# scalar vs list parameter
................................................................................
    }

    # Core classification properties
    method ordered      {} { return $myisordered }
    method cmdline      {} { return $myiscmdline }
    method required     {} { return $myisrequired }
    method defered      {} { return $myisdefered }
    method nopromote    {} { return $mynopromote }

    method list         {} { return $myislist }
    method presence     {} { return $myonlypresence }
    method documented   {} { return $myisdocumented }
    method isbool       {} { return [expr {$myvalidate eq "::cmdr::validate::boolean"}] }
    method locker       {} { return $mylocker }

................................................................................
    method help {} {
	# Generate a dictionary describing the parameter configuration.
	if {[catch {
	    my code
	} thecode]} {
	    set thecode {}
	}
	# mynopromote - Irrelevant to help
	return [dict create \
		    cmdline     $myiscmdline    \
		    code        $thecode        \
		    default     $mydefault      \
		    defered     $myisdefered    \
		    description $mydescription  \
		    documented  $myisdocumented \
................................................................................

	# Import the DSL commands to translate the specification.
	link \
	    {alias         Alias} \
	    {default       Default} \
	    {defered       Defered} \
	    {generate      Generate} \

	    {immediate     Immediate} \
	    {interact      Interact} \
	    {label         Label} \
	    {list          List} \
	    {no-promotion  NoPromote} \
	    {optional      Optional} \
	    {presence      Presence} \
	    {test          Test} \
	    {undocumented  Undocumented} \
	    {validate      Validate} \
	    {when-complete WhenComplete} \
	    {when-set      WhenSet}
	eval $valuespec

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

    method Immediate {} {
	# Consider adding checks against current state, prevent use
	# of calls not making an actual change.
	set myisdefered no
	return
    }

    method NoPromote {} {
	# Arguments only. Options cannot take unknown option as value,
	# nor can hidden state.
	my Promote_InputOnly
	# Consider adding checks against current state, prevent use
	# of calls not making an actual change.
	set mynopromote yes
	return
    }

    method Default {value} {
	my C9_PresenceDefaultConflict
	# Check most of the relevant constraint(s) after making the
	# change. That is easier than re-casting the expressions for
	# the proposed change.
	set myhasdefault yes
................................................................................
	my Assert {$myisordered} \
	{Option "@" has no test-mode}

    forward Test_NotRequired \
	my Assert {!$myisrequired} \
	{Required argument "@" has no test-mode}

    forward Promote_InputOnly \
	my Assert {$myisordered && $myiscmdline} \
	{Non-input parameter "@" does not handle promotion}

    # # ## ### ##### ######## #############
    ## Internal: DSL support. General helpers.

    method Assert {expr msg} {
	# Note: list is a local command, we want the builtin
	if {[uplevel 1 [::list expr $expr]]} return
	return -code error \
................................................................................
    variable myname mylabel mydescription \
	myisordered myiscmdline myislist myisrequired \
	myinteractive myprompt mydefault myhasdefault \
	mywhencomplete mywhenset mygenerate myvalidate \
	myflags mythreshold myhasstring mystring \
	myhasvalue myvalue mylocker mystopinteraction \
	myisdocumented myonlypresence myisdefered \
	myisundefined mynopromote

    # # ## ### ##### ######## #############
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::parameter 0.13

Changes to private.tcl.

165
166
167
168
169
170
171
172
    variable myarguments mycmd myinit myconfig myhandler

    # # ## ### ##### ######## #############
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::private 0.12







|
165
166
167
168
169
170
171
172
    variable myarguments mycmd myinit myconfig myhandler

    # # ## ### ##### ######## #############
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::private 0.13

Changes to util.tcl.

66
67
68
69
70
71
72
73
	lappend r $k [dict get $dict $k]
    }
    return $r
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::util 0.12







|
66
67
68
69
70
71
72
73
	lappend r $k [dict get $dict $k]
    }
    return $r
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::util 0.13

Changes to validate.tcl.

317
318
319
320
321
322
323
324
325
    if {![file readable    $path]} {return 0}
    if {![file writable    $path]} {return 0}
    return 1
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::validate 0.12
return







|

317
318
319
320
321
322
323
324
325
    if {![file readable    $path]} {return 0}
    if {![file writable    $path]} {return 0}
    return 1
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::validate 0.13
return

Changes to vcommon.tcl.

105
106
107
108
109
110
111
112
113

    debug.cmdr/validate/common {= [join $candidates "\n= "]} 10
    return $candidates
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::validate::common 0.12
return







|

105
106
107
108
109
110
111
112
113

    debug.cmdr/validate/common {= [join $candidates "\n= "]} 10
    return $candidates
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::validate::common 0.13
return