cmdr
Check-in [21b94c7e50]
Not logged in

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: 21b94c7e508f1688fd1541ac2c730d736e8b2c4e
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
Unified Diff Ignore Whitespace Patch
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
138
139
140
141
142
143
144
145
146
147
148
149


150
151
152
153
154
155
156
157
158
</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







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







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
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
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">
<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.</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="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>







>
>
>
>
>
>
>
>
>
>






|









|








|





|







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
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
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>
</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="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







|


|



















|







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
331
332
333
334
335
336
337
338
<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>.







|







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
354
355
356
357
358
359
360
361
362
363
364
365
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>







|



|







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
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
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="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>
<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="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







|




















|







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
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
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>







|







|







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>