cmdr
Check-in [c1ba65f517]
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 [email protected]
or submit via the online form by Sep 9.

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

Overview
Comment:Near completed parameter documentation.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: c1ba65f517cd59caf2bb716ebc3d2091d25e4459
User & Date: andreask 2013-11-01 22:52:22
Context
2013-11-03
07:18
Updated embedded documentation check-in: b4bc5bcb6e user: aku tags: trunk
2013-11-01
22:52
Near completed parameter documentation. check-in: c1ba65f517 user: andreask tags: trunk
2013-10-31
23:22
Start the parameter documentation check-in: fc5d203228 user: andreask tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to doc/cmdr_parameter.man.

7
8
9
10
11
12
13

14
15
16
17
18
19
20
..
71
72
73
74
75
76
77

78
79
80
81
82
83
84
85
86
87
88
89
90
91
92



93







94
95
96
97
98
99
100
101

102
103
104
105

106
107
108
109
110

111







112
113
114
115



116
117
118



119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

141


















142
143

























































































144
145
146
147
148
149


150
151
152
153


154
155
156
157
158



159
160
161







162
163
164
165
166
167




168
169
170
171


172





173
174
175
176



177















178
179


180
181
182
183
184
185

186
187
188
189


190



191
192
193
194


195























196
197


198
199
200
201
202
203
204
205
206
207

208
209
210
211
212
213
214
215
216

217
218
219
220
221
222
223
224
225


226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347




348
349
350
351
352
353
354
355
356


357
358
359
360



361
362
363
364
365



366
367
368
369
370
371
372
373
374

375
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
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
[description]
[include parts/welcome.inc]

This package implements [emph parameters], collections of which (see
[package cmdr::config]) serve as the configuration of privates (see
[package cmdr::private]).


[section {Class API}]

The class API is not public. It is used internally by the framework
when parsing a command hierarchy specification to create the necessary
parameter instances.

[para] It is described here for use by developers maintaining,
................................................................................

Tcl-script specifying the parameter in detail. Please read
[term [vset TITLE_DSL]], section --TODO-- for the details.

[list_end][comment arguments]
[list_end][comment definitions]


[section {Instance API}]

Most of the instance API is not public.

[para] It is described here for use by developers maintaining,
modifying and extending the framework itself. A user of the framework
has no need for it.

---TODO-- mark the methods which are public -- and/or write a separate document?

[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method accept] [arg x]]

When invoked this method ...











[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method cmdline] [arg ...]]

When invoked this method ...


[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]


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

When invoked this method ...









[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method complete-words] [arg ...]]

When invoked this method ...




[list_begin arguments]
[arg_def list list]



[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method config] [arg word...]]

When invoked this method either returns the [package cmdr::config] instance
containing the parameter, or the result of applying the words to that config
instance. It is through this method that any script with access to a single
parameter instance of a private will have access to all its parameters.

[list_begin arguments]
[arg_def string word...]
The method and its arguments to apply to the config instance holding
the parameter. If none are specified the method [method self] is
implied, causing the return of the config instance itself.

[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method default] [arg ...]]

When invoked this method ...




















[list_begin arguments]
[arg_def list list]

























































































[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method defered] [arg ...]]

When invoked this method ...



[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]



[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method description] [arg ...]]

When invoked this method ...




[list_begin arguments]
[arg_def list list]







[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method documented] [arg ...]]

When invoked this method ...





[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]








[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method dontinteract] [arg ...]]

When invoked this method ...



















[list_begin arguments]
[arg_def list list]


[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method flag] [arg ...]]

When invoked this method ...


[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]






[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method forget] [arg ...]]

When invoked this method ...


























[list_begin arguments]
[arg_def list list]


[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method generator] [arg ...]]

When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]


[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method hasdefault] [arg ...]]

When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]


[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method help] [arg ...]]

When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]



[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method interactive] [arg ...]]

When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method interact] [arg ...]]

When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method isbool] [arg ...]]

When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method is] [arg ...]]

When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method label] [arg ...]]

When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method list] [arg ...]]

When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method locker] [arg ...]]

When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method lock] [arg ...]]

When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

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

When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

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

When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method ordered] [arg ...]]

When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method presence] [arg ...]]

When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method primary] [arg ...]]

When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method process] [arg ...]]

When invoked this method ...





[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method prompt] [arg ...]]

When invoked this method ...



[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]




[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method required] [arg ...]]

When invoked this method ...




[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method reset] [arg ...]]

When invoked this method ...


[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

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

When invoked this method returns the parameter instance itself.




[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method set?] [arg ...]]

When invoked this method ...



[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]



[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method setq] [arg ...]]




When invoked this method ...

[list_begin arguments]
[arg_def list list]


[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method set] [arg ...]]

When invoked this method ...










[list_begin arguments]
[arg_def list list]



[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method string] [arg ...]]

When invoked this method ...


[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method threshold:] [arg ...]]



When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method threshold] [arg ...]]


When invoked this method ...

[list_begin arguments]
[arg_def list list]


[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method type] [arg ...]]

When invoked this method ...

[list_begin arguments]
[arg_def list list]

[list_end][comment {--- arguments --}]



[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method undefined!] [arg ...]]

When invoked this method ...

[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method validator] [arg ...]]

When invoked this method ...


[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]




[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method value] [arg ...]]

When invoked this method ...





[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]








[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method when-complete] [arg ...]]

When invoked this method ...



[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method when-set] [arg ...]]

When invoked this method ...



[list_begin arguments]
[arg_def list list]
[list_end][comment {--- arguments --}]

[list_end][comment {-- definitions --}]








[include parts/feedback.inc]
[manpage_end]






>







 







>








|





|
>
>
>

>
>
>
>
>
>
>

|



|

|
>

<
|
|
>




|
>

>
>
>
>
>
>
>

|

<
>
>
>


|
>
>
>





|













|

|
>

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

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



|

|
>
>

<
<
|
>
>


|

<
>
>
>


|
>
>
>
>
>
>
>



|

<
>
>
>
>

<
<
<
>
>

>
>
>
>
>

|

<
>
>
>

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

|
>
>



|

<
>

<
<
<
>
>

>
>
>

|

<
>
>

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

|
>
>



|

|

|
|
|
>

<
<
<
<
<

|
<
>

<
<
<
<
<
<
|
<
>
>

<
<
<
<
<
<
<



<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|

<
>
>
>
>

<
<
<
<

|

<
>
>

<
<
<
>
>
>


|

<
>
>
>


|



|

<
>

<
<
<
<

|

<
>
>
>


|

<
>
>

<
<
<
>
>

<
<
>
>
>

<
<

|
>
>



|

|
>

>
>
>
>
>
>
>
>

|
>
>
>



|

|
<
>
|
<
<


|

>
>
|

|
<
<

<
<
>

<
<

|
>
>



|

|

|
<
>
|
>
>


|

<
<
|
|
|


|

|
>

<
|
|

>
>
>

|

<
>
>
>
>

<
<
<
>
>

>
>
>
>
>

|

<
>
>

<
<
<
<

|

<
>
>

<
<
|

<
>
>
>
>
>
>
>
>


7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
..
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286


287
288
289
290
291
292
293

294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311

312
313
314
315
316



317
318
319
320
321
322
323
324
325
326
327

328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355

356
357



358
359
360
361
362
363
364
365
366

367
368
369
370
371
372
373
374
375
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
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
558
559
560
561



562
563
564
565
566
567
568
569
570
571
572

573
574
575




576
577
578

579
580
581


582
583

584
585
586
587
588
589
590
591
592
593
[description]
[include parts/welcome.inc]

This package implements [emph parameters], collections of which (see
[package cmdr::config]) serve as the configuration of privates (see
[package cmdr::private]).

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Class API}]

The class API is not public. It is used internally by the framework
when parsing a command hierarchy specification to create the necessary
parameter instances.

[para] It is described here for use by developers maintaining,
................................................................................

Tcl-script specifying the parameter in detail. Please read
[term [vset TITLE_DSL]], section --TODO-- for the details.

[list_end][comment arguments]
[list_end][comment definitions]

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Instance API}]

Most of the instance API is not public.

[para] It is described here for use by developers maintaining,
modifying and extending the framework itself. A user of the framework
has no need for it.

--TODO-- mark the methods which are public -- and/or write a separate document?

[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method accept] [arg x]]

This method validates the string value [arg x]
against the validation type of the parameter and returns a
boolean value indicating success ([const true]), or not
([const false]).

The internal representation of [arg x] is not kept but
released immediately. The parameter itself is not changed
either.

This is used during runtime by the 'test'-based processing
of optional arguments.

[list_begin arguments]
[arg_def string x]
[list_end][comment {--- arguments --}]

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

This accessor method returns the "cmdline" flag
set during parameter construction.


A result of [const true] indicates that the parameter is
visible on the command line (option, or argument), and
otherwise ([const false]) hidden (state).

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

This method returns a string encoding the flags
"required" and "list". The mapping is as follows:

[list_begin definitions]
[def [const +]] required, scalar
[def [const ?]] optional, scalar
[def [const +*]] required, list
[def [const ?*]] optional, list.
[list_end]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method complete-words] [arg parse]]


This method is given the completion state [arg parse] of a partial
command line and returns a list of strings which are the valid
completions at this point, for the parameter.

[list_begin arguments]
[arg_def dict parse]
A dictionary holding the current completion state of a partial command
line.
[para] --TODO-- Describe the state fields and their meaning.
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method config] [arg word...]]

This method either returns the [package cmdr::config] instance
containing the parameter, or the result of applying the words to that config
instance. It is through this method that any script with access to a single
parameter instance of a private will have access to all its parameters.

[list_begin arguments]
[arg_def string word...]
The method and its arguments to apply to the config instance holding
the parameter. If none are specified the method [method self] is
implied, causing the return of the config instance itself.

[list_end][comment {--- arguments --}]

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

This method returns the default value set by
the parameter's specification, or the empty string.

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

This accessor method returns the "defered" flag
set during parameter construction.

A result of [const true] indicates that the parameter's
internal representation is computed on-demand, and otherwise
([const false]) during the completion phase.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method description] [opt [arg detail]]]

This method returns the parameter's help text.
If the [arg detail] is specified and the name of an automatic
option controlled by this parameter its implicit description
is returned instead of the description of its primary.

[list_begin arguments]
[arg_def string detail]
Optional. The name of a automatic option controlled by the
parameter.
[list_end][comment {--- arguments --}]

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

This accessor method returns the "documented"
flag of the parameter.

A value of [const true] indicates that the parameter
should be included in generated help, otherwise not.

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

This method disables interactive entry
of the parameter's value for one time. I.e. after
the information was used (see method [method value])
the flag automatically resets.

The result of the method is the empty string.

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

This method returns the text of the primary
flag of the parameter, including leading dashes.

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

This method releases the internal representation
of the parameter's value, if it has any.

See also method [method reset] for a stronger form.

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

This method returns the "generate" command prefix callback,
if it was set, and an empty list otherwise.

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

This method returns a boolean flag
indicating if the parameter's specification declared
a default value for it ([const true]), or not ([const false]).

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

This method returns the help information for the parameter.

Note that this method does [emph not] check the "documented"
flag of the parameter. That is the responsibility of the
caller.

The result of the command is a structure of the form
described in section [sectref {Help Information}].

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

This method returns the "interactive" flag of the parameter.

A result of [const true] indicates that the parameter's
string representation has to be queried interactively if no
value was specified at runtime.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method interact] [opt [arg prompt]]]

This method interactively queries the string representation of
the parameter from the user.

If no [arg prompt] is specified the parameter's prompt from the
specification is used. See also method [method prompt].

The interaction takes the "list"-ness of the parameter into account.

Note that the entered string(s) is/are validated and invalid
information is rejected.

[list_begin arguments]
[arg_def string prompt]
Optional. The prompt to use for the interaction.

[list_end][comment {--- arguments --}]

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

This method returns a boolean value indicating if the parameter
uses the standard validation type "boolean" ([const true]) or
not ([const false]).



The parts of the parameter responsible for processing option
arguments use this information to invoke the hard-wired special
cases for this type, or not.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method is] [arg type]]


This method returns a boolean value indicating if the
parameter is of the specified [arg type] ([const true])
or not ([const false]).

[list_begin arguments]
[arg_def string type]
The type to check the parameter against.
Recognized values are
[list_begin definitions]
[def [const argument]]
[def [const option]]
[def [const state]]
[list_end]
[list_end][comment {--- arguments --}]

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


This method returns the human-readable name of the parameter,
for use in help. If not specifically overridden by the
parameter's specification this is the same as the internal
name (See method [method name]).




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

This accessor method returns the "list" flag of the parameter.

A value of [const true] indicates that the parameter's value
is a list, otherwise a scalar.

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


This accessor method returns the string set by method
[method lock] below, or the empty string if
[method lock] was not used.

[emph Note]: This information is reset by method
[method reset], but not by [method forget].

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method lock] [arg reason]]

This method locks the parameter against modification
by the methods [method set] and [method setq], and
remembers the [arg reason] for it. The reason is
expected to be the name of another parameter whose
use disallows the use of this one.

[emph Note]: Such a lock is reset by method
[method reset], but not by [method forget].

[list_begin arguments]
[arg_def string reason]
The name of the parameter locking this one against further
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. 

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


This accessor method returns the "order" flag
set during parameter construction.

A result of [const true] indicates that the parameter
is specified by order at runtime (argument), and otherwise
([const false]) by name (option).

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

This method returns a boolean value indicating if
the option parameter is set as presence-option
([const true]) or not ([const false]).

The parts of the parameter responsible for processing option
arguments use this information to invoke the hard-wired special
cases for presence, or not.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method primary] [arg option]]

This method returns a boolean value indicating if the named [arg option]
is the primary option of this parameter ([const true]), or not ([const false]).

An error will be thrown if the named option is not controlled by the parameter.

[list_begin arguments]
[arg_def string option]
The name of the option to check.

[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method process] [arg detail] [arg queue]]

This method extracts the value of the parameter from the command line.

A [method presence] option takes nothing, whereas an [method isbool] option
takes the first value in the [arg queue], if it is a proper boolean, and
defaults to [const true] if not. Any other argument or option takes  the
first value in [arg queue].






[list_begin arguments]
[arg_def string detail]

The name of the parameter, or the option flag referencing it.







[arg_def struct::queue queue]

The queue instance holding the words of the command line not yet
processed by the system.








[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]












































































































[call [cmd <parameter>] [method prompt]]


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. "Enter [var name]:".





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


This accessor method returns the "required" flag
set during parameter construction.




A result of [const true] indicates that the parameter
must be specified by the user at runtime, and otherwise
may be left unspecified ([const false]).

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method reset] [opt [arg cleanup]]]


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 [method forget].

[list_begin arguments]
[arg_def boolean cleanup]
[list_end][comment {--- arguments --}]

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


This method returns the parameter instance itself.





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


This accessor method returns a boolean value indicating
if the parameter was given a string representation at
runtime ([const true]), or not ([const false]).

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method setq] [arg queue]]


This method sets the first element of the [arg queue]
as the value of the parameter.




For a "list" parameter all elements of the queue are
taken as the new value of the parameter.



This is not quite analogous to method [method set] below.
They behave the same for scalar parameters, and differ
for "list" parameters.



[list_begin arguments]
[arg_def stack::queue queue]
The queue instance holding the words of the command
line not yet processed.
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method set] [arg value]]

This method sets the [arg value] as the new string
representation of the parameter.

For a "list" parameter the string representation is
[emph extended] with the [arg value].

This action triggers the execution of the "when-set" callback.

A previously existing internal representation is
forgotten (See [method forget]).

[list_begin arguments]
[arg_def string value]
The new value of the parameter, or an extension of the
existing value.

[list_end][comment {--- arguments --}]

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

This accessor method returns the string representation of

the parameter. If such was not set an error will be thrown
(See method [method undefined!]).



[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method threshold:] [arg n]]

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.



[list_begin arguments]
[arg_def integer n]
The acceptance threshold for the parameter.

[list_end][comment {--- arguments --}]

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

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 [method accept]) instead
of using a threshold.

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



This accessor method returns the type of the parameter, one of
[const argument], [const option], or [const state]. See also
method [method is] for type-checking.

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

This method explicitly throws a "parameter undefined" error
for this parameter.


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

This method returns the "validate" command prefix callback
(i.e. the parameter's validation type).

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


This accessor method returns the internal representation of
the parameter. If necessary the data is computed from the
parameter's string representation, "default" value, or
"generate" callback.




An error is thrown if the value could not be determined.
(See method [method undefined!]).

If the value is newly computed the action triggers the
execution of the "when-complete" callback.

[para] --TODO-- describe generation rules and order.

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


This method returns the "when-complete" command prefix callback,
if it was set, and an empty list otherwise.





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


This method returns the "when-set" command prefix callback,
if it was set, and an empty list otherwise.



[list_end][comment {-- definitions --}]


[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Help Information}]

The help information generated for parameters is a
dictionary containing the keys below:

[include parts/help_para_structure.inc]

[include parts/feedback.inc]
[manpage_end]

Changes to doc/cmdr_private.man.

8
9
10
11
12
13
14

15
16
17
18
19
20
21
..
52
53
54
55
56
57
58

59
60
61
62
63
64
65
..
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
...
113
114
115
116
117
118
119
120
121
122
123
124
125
126

127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145




146
147
148
[include parts/welcome.inc]

This package implements [emph privates], the leaves of command
hierarchies.  While each private can execute only a single option they
have parameters, i.e. arguments and options with which to configure
the behaviour of their action.


[section {Class API}]

The class API is not public. It is used internally by the framework
when parsing a command hierarchy specification to create the necessary
private instances.

[para] It is described here for use by developers maintaining,
................................................................................
hidden [package cmdr::config] container holding the private's
parameters. The result of the action, if there is any, is ignored by
the framework.

[list_end][comment arguments]
[list_end][comment definitions]


[section {Instance API}]

The instance API is not public. It is used internally by the framework
when during the processing of a command line at runtime

parsing a command hierarchy specification to create the necessary
private instances.
................................................................................
[para] It is described here for use by developers maintaining,
modifying and extending the framework itself. A user of the framework
has no need for it, although they have indirect access through
parameters and their container.

[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd private] [method complete-words] [arg parse]]

This command is given the completion state [arg parse] of a partial
command line and returns a list of strings which are the vaid
completions at this point.

[list_begin arguments]
[arg_def dict parse]
A dictionary holding the current completion state of a partial command
line.

[para] -- TODO -- Describe the state fields and their meaning.

[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd private] [method do] [opt [arg word]...]]

This method parses the [arg word]s of the command line, matching them
to the parameters of the private, be they arguments, or options. When
done without error it invokes the action of the private with the
filled container of parameters.

[list_begin arguments]
[arg_def string word]
The words of the command line to parse and match to parameters.
[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd private] [method ehandler] [arg cmd]]

This method specifies a command prefix to wrap around the parsing of
the command line for the private, and the execution of its action.

[list_begin arguments]
[arg_def cmd-prefix cmd]
A command prefix taking a single argument, a script. The command
................................................................................
prefix then has the responsbility to perform any custom cleanup action
required by the application using the framework to prevent leakage of
data between multiple commands executed one after the other (i.e. in
an interactive shell run by the framework).
[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd private] [method help] [opt [arg prefix]]]

This method returns the help information for the private and its
parameters. The [arg prefix], if specified provides the name of the
private within the help data. It defaults to the empty string.

[para] -- TODO -- describe help structure --> custom help formats


[list_begin arguments]
[arg_def string prefix]
The name to use for the private within the generated help.
[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd private] [method unknown] [arg m] [opt [arg word]...]]

This method overrides the standard behaviour for unknown methods.
Instead of throwing an error they are routed to the hidden container
of the private's parameters, of class [package cmdr::config].

[list_begin arguments]
[arg_def string m]    The name of the unknown method.
[arg_def string word] The argument (one or more) of the unknown method.
[list_end][comment arguments]

[list_end][comment definitions]





[include parts/feedback.inc]
[manpage_end]






>







 







>







 







|

|
|












|












|







 







|





|
>







|











>
>
>
>



8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
..
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
..
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
...
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
[include parts/welcome.inc]

This package implements [emph privates], the leaves of command
hierarchies.  While each private can execute only a single option they
have parameters, i.e. arguments and options with which to configure
the behaviour of their action.

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Class API}]

The class API is not public. It is used internally by the framework
when parsing a command hierarchy specification to create the necessary
private instances.

[para] It is described here for use by developers maintaining,
................................................................................
hidden [package cmdr::config] container holding the private's
parameters. The result of the action, if there is any, is ignored by
the framework.

[list_end][comment arguments]
[list_end][comment definitions]

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Instance API}]

The instance API is not public. It is used internally by the framework
when during the processing of a command line at runtime

parsing a command hierarchy specification to create the necessary
private instances.
................................................................................
[para] It is described here for use by developers maintaining,
modifying and extending the framework itself. A user of the framework
has no need for it, although they have indirect access through
parameters and their container.

[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd <private>] [method complete-words] [arg parse]]

This method is given the completion state [arg parse] of a partial
command line and returns a list of strings which are the valid
completions at this point.

[list_begin arguments]
[arg_def dict parse]
A dictionary holding the current completion state of a partial command
line.

[para] -- TODO -- Describe the state fields and their meaning.

[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <private>] [method do] [opt [arg word]...]]

This method parses the [arg word]s of the command line, matching them
to the parameters of the private, be they arguments, or options. When
done without error it invokes the action of the private with the
filled container of parameters.

[list_begin arguments]
[arg_def string word]
The words of the command line to parse and match to parameters.
[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <private>] [method ehandler] [arg cmd]]

This method specifies a command prefix to wrap around the parsing of
the command line for the private, and the execution of its action.

[list_begin arguments]
[arg_def cmd-prefix cmd]
A command prefix taking a single argument, a script. The command
................................................................................
prefix then has the responsbility to perform any custom cleanup action
required by the application using the framework to prevent leakage of
data between multiple commands executed one after the other (i.e. in
an interactive shell run by the framework).
[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <private>] [method help] [opt [arg prefix]]]

This method returns the help information for the private and its
parameters. The [arg prefix], if specified provides the name of the
private within the help data. It defaults to the empty string.

The result of the command is a structure of the form
described in section [sectref {Help Information}].

[list_begin arguments]
[arg_def string prefix]
The name to use for the private within the generated help.
[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <private>] [method unknown] [arg m] [opt [arg word]...]]

This method overrides the standard behaviour for unknown methods.
Instead of throwing an error they are routed to the hidden container
of the private's parameters, of class [package cmdr::config].

[list_begin arguments]
[arg_def string m]    The name of the unknown method.
[arg_def string word] The argument (one or more) of the unknown method.
[list_end][comment arguments]

[list_end][comment definitions]

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Help Information}]
[include parts/help_structure.inc]

[include parts/feedback.inc]
[manpage_end]

Added doc/parts/help_para_structure.inc.
















































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
[list_begin definitions]
[def cmdline]      Output of method [method cmdline].
[def code]         Output of method [method code].
[def default]      Output of method [method default].
[def defered]      Output of method [method defered].
[def description]  Output of method [method description].
[def documented]   Output of method [method documented].
[def flags]        A dictionary mapping flag names to flag
                   types, i.e. [const primary], [const alias],
                   or [const inverted].
[def generator]    Output of method [method generator].
[def interactive]  Output of method [method interactive].
[def isbool]       Output of method [method isbool].
[def label]        Output of method [method label].
[def list]         Output of method [method list].
[def ordered]      Output of method [method ordered].
[def presence]     Output of method [method presence].
[def prompt]       Output of method [method prompt].
[def required]     Output of method [method required].
[def threshold]    Output of method [method threshold].
[def type]         Output of method [method type].
[def validator]    Output of method [method validator].
[list_end]

Added doc/parts/help_structure.inc.




































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
The help information generated by various places of the framework
is a dictionary containing the following keys:

[list_begin definitions]
[def arguments]
A list of strings, the names of the command arguments, in order.
These names are keys into the [var parameters] sub-dictionary.

[def desc]
The command's description, i.e. help text.

[def opt2para]
A dictionary mapping option flags to option names.
These names are keys into the [var parameters] sub-dictionary.

[def options]
A dictionary mapping option names to their descriptions.

[def parameters]
A dictionary mapping parameter names to their definition.
Each definition is a dictionary containing the keys below.
See also package [package cmdr::parameter].

[include help_para_structure.inc]

[def sections]
A list of sections the command belongs to.
Each section name is a list itself, the path of the section and sub-sections.

[def states]
A list of strings, the names of the command's hidden state parameters.
These names are keys into the [var parameters] sub-dictionary.
[list_end]