cmdr
Check-in [d24c736d84]
Not logged in

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

Overview
Comment:Documented the new fail-* convenience commands for validation types.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:d24c736d8408fc9eacaea1f2b0c91a9d8d9e3bb4
User & Date: aku 2016-06-22 19:54:00
Context
2016-06-22
20:01
Drop the todo marker about the fail-* commands from the changes document check-in: 24b3dc9ad2 user: aku tags: trunk
19:54
Documented the new fail-* convenience commands for validation types. check-in: d24c736d84 user: aku tags: trunk
19:01
Restructured the file hierarchy, sorted the package files into related groups. check-in: b09c92cbff user: aku tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to doc/cmdr_vcommon.man.

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70



71
72
73
74
75
76
77
78


79
80
81

82
83
84


85
86
87






























88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106



107
108
109
110
111
112
113
114


115
116
117

118
119
120


121
122
123






























124
125
126
127
128
129
130
[section API]
[list_begin definitions][comment {-- begin api definitions --}]

[comment {- - -- --- ----- -------- ------------- ---------------------}]
[call [cmd ::cmdr::validate::common] [method fail] \
     [arg p] [arg code] [arg type] [arg x] [opt [arg context]]]

When invoked this command throws an error indicating a validation type
failure. The arguments provide the information used to construct both
error message and code.

[para] The generated string has the form:
[example {
    Expected $type for $p.type "$x"$context, got "$x"
}]

[list_begin arguments]
[arg_def [package cmdr::parameter] p]
The [package cmdr::parameter] instance whose validation failed. The
error message will contain this parameter's type and label (flag in
case of an option).

[arg_def list code]
A list providing additional elements for the error code, detailing the
internal name of the validation type triggering the error.

[arg_def string type]
A string providing the human-readable name of the validation type
triggering the error.

[arg_def string x]
The string value failing the validation.

[arg_def string context]
Additional context to show in the message. Defaults to the empty string.
[list_end]

[comment {- - -- --- ----- -------- ------------- ---------------------}]
[call [cmd ::cmdr::validate::common] [method fail-unknown-thing] \
     [arg p] [arg code] [arg type] [arg x] [opt [arg context]]]

When invoked this command throws an error indicating a validation type
failure. The arguments provide the information used to construct both
error message and code.

[para] The generated string has the form:
[example {
    Found a problem with $p.type "$p.the-name":
    A(n) $type named "$x" does not exist$context.
    Please use a different value.
}]

[list_begin arguments]
[arg_def [package cmdr::parameter] p]



The [package cmdr::parameter] instance whose validation failed. The
error message will contain this parameter's type and label (flag in
case of an option).

[arg_def list code]
A list providing additional elements for the error code, detailing the
internal name of the validation type triggering the error.



[arg_def string type]
A string providing the human-readable name of the validation type
triggering the error.


[arg_def string x]
The string value failing the validation.



[arg_def string context]
Additional context to show in the message. Defaults to the empty string.






























[list_end]

[comment {- - -- --- ----- -------- ------------- ---------------------}]
[call [cmd ::cmdr::validate::common] [method fail-known-thing] \
     [arg p] [arg code] [arg type] [arg x] [opt [arg context]]]

When invoked this command throws an error indicating a validation type
failure. The arguments provide the information used to construct both
error message and code.

[para] The generated string has the form:
[example {
    Found a problem with $p.type "$p.the-name":
    A(n) $type named "$x" already exists$context.
    Please use a different name.
}]

[list_begin arguments]
[arg_def [package cmdr::parameter] p]



The [package cmdr::parameter] instance whose validation failed. The
error message will contain this parameter's type and label (flag in
case of an option).

[arg_def list code]
A list providing additional elements for the error code, detailing the
internal name of the validation type triggering the error.



[arg_def string type]
A string providing the human-readable name of the validation type
triggering the error.


[arg_def string x]
The string value failing the validation.



[arg_def string context]
Additional context to show in the message. Defaults to the empty string.






























[list_end]

[comment {- - -- --- ----- -------- ------------- ---------------------}]
[call [cmd ::cmdr::validate::common] [method complete-enum] \
     [arg choices] [arg nocase] [arg buffer]]

When invoked this command returns a list of strings containing just







|
<
<







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






|
<
<





|



<
>
>
>
|
|
|

|
<
<

>
>
|
|
|
>

<
|
>
>

<
<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>






|
<
<





|



<
>
>
>
|
|
|

|
<
<

>
>
|
|
|
>

<
|
>
>

<
<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







17
18
19
20
21
22
23
24


25
26
27
28
29
30
31
32

















33
34
35
36
37
38
39


40
41
42
43
44
45
46
47
48

49
50
51
52
53
54
55
56


57
58
59
60
61
62
63
64

65
66
67
68


69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105


106
107
108
109
110
111
112
113
114

115
116
117
118
119
120
121
122


123
124
125
126
127
128
129
130

131
132
133
134


135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
[section API]
[list_begin definitions][comment {-- begin api definitions --}]

[comment {- - -- --- ----- -------- ------------- ---------------------}]
[call [cmd ::cmdr::validate::common] [method fail] \
     [arg p] [arg code] [arg type] [arg x] [opt [arg context]]]

[include parts/fail_description.inc]



[para] The generated string has the form:
[example {
    Expected $type for $p.type "$x"$context, got "$x"
}]

[list_begin arguments]
[include parts/fail_args.inc]

















[list_end]

[comment {- - -- --- ----- -------- ------------- ---------------------}]
[call [cmd ::cmdr::validate::common] [method fail-unknown-thing] \
     [arg p] [arg code] [arg type] [arg x] [opt [arg context]]]

[include parts/fail_description.inc]



[para] The generated string has the form:
[example {
    Found a problem with $p.type "$p.the-name":
    A(n) $type named "$x" does not exist$context.
     Please use a different value.
}]

[list_begin arguments]

[include parts/fail_args.inc]
[list_end]

[comment {- - -- --- ----- -------- ------------- ---------------------}]
[call [cmd ::cmdr::validate::common] [method fail-unknown-thing-msg] \
     [arg msg] [arg p] [arg code] [arg type] [arg x] [opt [arg context]]]

[vset method fail-unknown-thing][include parts/fail_desc_variant.inc]



[para] The generated string has the form:
[example {
    Found a problem with $p.type "$p.the-name":
    A(n) $type named "$x" does not exist$context.
     $msg.
}]


[list_begin arguments]
[include parts/fail_msg_args.inc]
[list_end]



[comment {- - -- --- ----- -------- ------------- ---------------------}]
[call [cmd ::cmdr::validate::common] [method fail-unknown-simple] \
     [arg p] [arg code] [arg type] [arg x] [opt [arg context]]]

[include parts/fail_description.inc]

[para] The generated string has the form:
[example {
    $type "$x" does not exist$context.
     Please use a different value.
}]

[list_begin arguments]
[include parts/fail_args.inc]
[list_end]

[comment {- - -- --- ----- -------- ------------- ---------------------}]
[call [cmd ::cmdr::validate::common] [method fail-unknown-simple-msg] \
     [arg msg] [arg p] [arg code] [arg type] [arg x] [opt [arg context]]]

[vset method fail-unknown-simple][include parts/fail_desc_variant.inc]

[para] The generated string has the form:
[example {
    $type "$x" does not exist$context.
     $msg.
}]

[list_begin arguments]
[include parts/fail_msg_args.inc]
[list_end]

[comment {- - -- --- ----- -------- ------------- ---------------------}]
[call [cmd ::cmdr::validate::common] [method fail-known-thing] \
     [arg p] [arg code] [arg type] [arg x] [opt [arg context]]]

[include parts/fail_description.inc]



[para] The generated string has the form:
[example {
    Found a problem with $p.type "$p.the-name":
    A(n) $type named "$x" already exists$context.
     Please use a different name.
}]

[list_begin arguments]

[include parts/fail_args.inc]
[list_end]

[comment {- - -- --- ----- -------- ------------- ---------------------}]
[call [cmd ::cmdr::validate::common] [method fail-known-thing-msg] \
     [arg msg] [arg p] [arg code] [arg type] [arg x] [opt [arg context]]]

[vset method fail-known-thing][include parts/fail_desc_variant.inc]



[para] The generated string has the form:
[example {
    Found a problem with $p.type "$p.the-name":
    A(n) $type named "$x" already exists$context.
     $msg.
}]


[list_begin arguments]
[include parts/fail_msg_args.inc]
[list_end]



[comment {- - -- --- ----- -------- ------------- ---------------------}]
[call [cmd ::cmdr::validate::common] [method fail-known-simple] \
     [arg p] [arg code] [arg type] [arg x] [opt [arg context]]]

[include parts/fail_description.inc]

[para] The generated string has the form:
[example {
    $type named "$x" already exists$context.
     Please use a different name.
}]

[list_begin arguments]
[include parts/fail_args.inc]
[list_end]

[comment {- - -- --- ----- -------- ------------- ---------------------}]
[call [cmd ::cmdr::validate::common] [method fail-known-simple-msg] \
     [arg msg] [arg p] [arg code] [arg type] [arg x] [opt [arg context]]]

[vset method fail-known-simple][include parts/fail_desc_variant.inc]

[para] The generated string has the form:
[example {
    $type named "$x" already exists$context.
     $msg.
}]

[list_begin arguments]
[include parts/fail_msg_args.inc]
[list_end]

[comment {- - -- --- ----- -------- ------------- ---------------------}]
[call [cmd ::cmdr::validate::common] [method complete-enum] \
     [arg choices] [arg nocase] [arg buffer]]

When invoked this command returns a list of strings containing just

Added doc/parts/fail_args.inc.











































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
[arg_def [package cmdr::parameter] p]
The [package cmdr::parameter] instance whose validation failed.
The error message will contain this parameter's type and label
(flag in case of an option).

[arg_def list code]
A list of additional elements for the error code to throw.
Should detail the internal name of the validation type triggering the
error.

[arg_def string type]
A string holding a human-readable name for the validation type
triggering the error. (Conversely to the [arg code], which is for
machine-readability, i.e. trapping)

[arg_def string x]
The string value which failed the validation.

[arg_def string context]
Additional context to show in the message.
Defaults to the empty string.

Added doc/parts/fail_desc_variant.inc.











>
>
>
>
>
1
2
3
4
5
A variant of [method [vset method]] which takes an additional
user-specified message text as the first argument.

[para]
[include fail_description.inc]

Added doc/parts/fail_description.inc.







>
>
>
1
2
3
When invoked this command throws an error indicating a validation type
failure. The arguments provide the information used to construct both
error message and code.

Added doc/parts/fail_msg_args.inc.











>
>
>
>
>
1
2
3
4
5
[arg_def string msg]
A custom message to put into the generated error message.
See the example above.

[include fail_args.inc]

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

277
278
279
280
281
282
283






284
285






286
287
288
289
290
291
292
...
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
.SH SYNOPSIS
package require \fBcmdr::validate::common \fR
.sp
\fB::cmdr::validate::common\fR \fBfail\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
.sp
\fB::cmdr::validate::common\fR \fBfail-unknown-thing\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
.sp






\fB::cmdr::validate::common\fR \fBfail-known-thing\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
.sp






\fB::cmdr::validate::common\fR \fBcomplete-enum\fR \fIchoices\fR \fInocase\fR \fIbuffer\fR
.sp
\fB::cmdr::validate::common\fR \fBcomplete-substr\fR \fIchoices\fR \fInocase\fR \fIbuffer\fR
.sp
\fB::cmdr::validate::common\fR \fBcomplete-glob\fR \fIfilter\fR \fIbuffer\fR
.sp
\fB::cmdr::validate::common\fR \fBok-directory\fR \fIpath\fR
................................................................................

    Expected $type for $p\&.type "$x"$context, got "$x"

.CE
.RS
.TP
\fBcmdr::parameter\fR \fIp\fR
The \fBcmdr::parameter\fR instance whose validation failed\&. The
error message will contain this parameter's type and label (flag in
case of an option)\&.
.TP
list \fIcode\fR
A list providing additional elements for the error code, detailing the
internal name of the validation type triggering the error\&.

.TP
string \fItype\fR
A string providing the human-readable name of the validation type

triggering the error\&.

.TP
string \fIx\fR
The string value failing the validation\&.
.TP
string \fIcontext\fR
Additional context to show in the message\&. Defaults to the empty string\&.

.RE
.TP
\fB::cmdr::validate::common\fR \fBfail-unknown-thing\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
When invoked this command throws an error indicating a validation type
failure\&. The arguments provide the information used to construct both
error message and code\&.
.sp
The generated string has the form:
.CS


    Found a problem with $p\&.type "$p\&.the-name":
    A(n) $type named "$x" does not exist$context\&.
    Please use a different value\&.

.CE
.RS
.TP
\fBcmdr::parameter\fR \fIp\fR
The \fBcmdr::parameter\fR instance whose validation failed\&. The
error message will contain this parameter's type and label (flag in
case of an option)\&.
.TP
list \fIcode\fR
A list providing additional elements for the error code, detailing the
internal name of the validation type triggering the error\&.

.TP
string \fItype\fR










































A string providing the human-readable name of the validation type
triggering the error\&.
.TP





string \fIx\fR
The string value failing the validation\&.
.TP
string \fIcontext\fR
Additional context to show in the message\&. Defaults to the empty string\&.

.RE
.TP



















































































\fB::cmdr::validate::common\fR \fBfail-known-thing\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
When invoked this command throws an error indicating a validation type
failure\&. The arguments provide the information used to construct both
error message and code\&.
.sp
The generated string has the form:
.CS


    Found a problem with $p\&.type "$p\&.the-name":
    A(n) $type named "$x" already exists$context\&.
    Please use a different name\&.

.CE
.RS
.TP
\fBcmdr::parameter\fR \fIp\fR
The \fBcmdr::parameter\fR instance whose validation failed\&. The
error message will contain this parameter's type and label (flag in
case of an option)\&.
.TP
list \fIcode\fR
A list providing additional elements for the error code, detailing the
internal name of the validation type triggering the error\&.

.TP
string \fItype\fR










































A string providing the human-readable name of the validation type
triggering the error\&.
.TP





string \fIx\fR
The string value failing the validation\&.
.TP
string \fIcontext\fR
Additional context to show in the message\&. Defaults to the empty string\&.




















































































.RE
.TP
\fB::cmdr::validate::common\fR \fBcomplete-enum\fR \fIchoices\fR \fInocase\fR \fIbuffer\fR
When invoked this command returns a list of strings containing just
the elements of \fIchoices\fR the value of \fIbuffer\fR is a prefix
of\&. When \fInocase\fR is set the command will ignore letter case and
treat the string in \fIbuffer\fR as all-lowercase\&.







>
>
>
>
>
>


>
>
>
>
>
>







 







|
|
|


|
|
>


<
>
|
>


|


|
>













|





|
|
|


|
|
>


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

>
>
>
>
>

|


|
>


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











|





|
|
|


|
|
>


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

>
>
>
>
>

|


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







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
...
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
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
.SH SYNOPSIS
package require \fBcmdr::validate::common \fR
.sp
\fB::cmdr::validate::common\fR \fBfail\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
.sp
\fB::cmdr::validate::common\fR \fBfail-unknown-thing\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
.sp
\fB::cmdr::validate::common\fR \fBfail-unknown-thing-msg\fR \fImsg\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
.sp
\fB::cmdr::validate::common\fR \fBfail-unknown-simple\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
.sp
\fB::cmdr::validate::common\fR \fBfail-unknown-simple-msg\fR \fImsg\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
.sp
\fB::cmdr::validate::common\fR \fBfail-known-thing\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
.sp
\fB::cmdr::validate::common\fR \fBfail-known-thing-msg\fR \fImsg\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
.sp
\fB::cmdr::validate::common\fR \fBfail-known-simple\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
.sp
\fB::cmdr::validate::common\fR \fBfail-known-simple-msg\fR \fImsg\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
.sp
\fB::cmdr::validate::common\fR \fBcomplete-enum\fR \fIchoices\fR \fInocase\fR \fIbuffer\fR
.sp
\fB::cmdr::validate::common\fR \fBcomplete-substr\fR \fIchoices\fR \fInocase\fR \fIbuffer\fR
.sp
\fB::cmdr::validate::common\fR \fBcomplete-glob\fR \fIfilter\fR \fIbuffer\fR
.sp
\fB::cmdr::validate::common\fR \fBok-directory\fR \fIpath\fR
................................................................................

    Expected $type for $p\&.type "$x"$context, got "$x"

.CE
.RS
.TP
\fBcmdr::parameter\fR \fIp\fR
The \fBcmdr::parameter\fR instance whose validation failed\&.
The error message will contain this parameter's type and label
(flag in case of an option)\&.
.TP
list \fIcode\fR
A list of additional elements for the error code to throw\&.
Should detail the internal name of the validation type triggering the
error\&.
.TP
string \fItype\fR

A string holding a human-readable name for the validation type
triggering the error\&. (Conversely to the \fIcode\fR, which is for
machine-readability, i\&.e\&. trapping)
.TP
string \fIx\fR
The string value which failed the validation\&.
.TP
string \fIcontext\fR
Additional context to show in the message\&.
Defaults to the empty string\&.
.RE
.TP
\fB::cmdr::validate::common\fR \fBfail-unknown-thing\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
When invoked this command throws an error indicating a validation type
failure\&. The arguments provide the information used to construct both
error message and code\&.
.sp
The generated string has the form:
.CS


    Found a problem with $p\&.type "$p\&.the-name":
    A(n) $type named "$x" does not exist$context\&.
     Please use a different value\&.

.CE
.RS
.TP
\fBcmdr::parameter\fR \fIp\fR
The \fBcmdr::parameter\fR instance whose validation failed\&.
The error message will contain this parameter's type and label
(flag in case of an option)\&.
.TP
list \fIcode\fR
A list of additional elements for the error code to throw\&.
Should detail the internal name of the validation type triggering the
error\&.
.TP
string \fItype\fR
A string holding a human-readable name for the validation type
triggering the error\&. (Conversely to the \fIcode\fR, which is for
machine-readability, i\&.e\&. trapping)
.TP
string \fIx\fR
The string value which failed the validation\&.
.TP
string \fIcontext\fR
Additional context to show in the message\&.
Defaults to the empty string\&.
.RE
.TP
\fB::cmdr::validate::common\fR \fBfail-unknown-thing-msg\fR \fImsg\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
A variant of \fBfail-unknown-thing\fR which takes an additional
user-specified message text as the first argument\&.
.sp
When invoked this command throws an error indicating a validation type
failure\&. The arguments provide the information used to construct both
error message and code\&.
.sp
The generated string has the form:
.CS


    Found a problem with $p\&.type "$p\&.the-name":
    A(n) $type named "$x" does not exist$context\&.
     $msg\&.

.CE
.RS
.TP
string \fImsg\fR
A custom message to put into the generated error message\&.
See the example above\&.
.TP
\fBcmdr::parameter\fR \fIp\fR
The \fBcmdr::parameter\fR instance whose validation failed\&.
The error message will contain this parameter's type and label
(flag in case of an option)\&.
.TP
list \fIcode\fR
A list of additional elements for the error code to throw\&.
Should detail the internal name of the validation type triggering the
error\&.
.TP
string \fItype\fR
A string holding a human-readable name for the validation type
triggering the error\&. (Conversely to the \fIcode\fR, which is for
machine-readability, i\&.e\&. trapping)
.TP
string \fIx\fR
The string value which failed the validation\&.
.TP
string \fIcontext\fR
Additional context to show in the message\&.
Defaults to the empty string\&.
.RE
.TP
\fB::cmdr::validate::common\fR \fBfail-unknown-simple\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
When invoked this command throws an error indicating a validation type
failure\&. The arguments provide the information used to construct both
error message and code\&.
.sp
The generated string has the form:
.CS


    $type "$x" does not exist$context\&.
     Please use a different value\&.

.CE
.RS
.TP
\fBcmdr::parameter\fR \fIp\fR
The \fBcmdr::parameter\fR instance whose validation failed\&.
The error message will contain this parameter's type and label
(flag in case of an option)\&.
.TP
list \fIcode\fR
A list of additional elements for the error code to throw\&.
Should detail the internal name of the validation type triggering the
error\&.
.TP
string \fItype\fR
A string holding a human-readable name for the validation type
triggering the error\&. (Conversely to the \fIcode\fR, which is for
machine-readability, i\&.e\&. trapping)
.TP
string \fIx\fR
The string value which failed the validation\&.
.TP
string \fIcontext\fR
Additional context to show in the message\&.
Defaults to the empty string\&.
.RE
.TP
\fB::cmdr::validate::common\fR \fBfail-unknown-simple-msg\fR \fImsg\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
A variant of \fBfail-unknown-simple\fR which takes an additional
user-specified message text as the first argument\&.
.sp
When invoked this command throws an error indicating a validation type
failure\&. The arguments provide the information used to construct both
error message and code\&.
.sp
The generated string has the form:
.CS


    $type "$x" does not exist$context\&.
     $msg\&.

.CE
.RS
.TP
string \fImsg\fR
A custom message to put into the generated error message\&.
See the example above\&.
.TP
\fBcmdr::parameter\fR \fIp\fR
The \fBcmdr::parameter\fR instance whose validation failed\&.
The error message will contain this parameter's type and label
(flag in case of an option)\&.
.TP
list \fIcode\fR
A list of additional elements for the error code to throw\&.
Should detail the internal name of the validation type triggering the
error\&.
.TP
string \fItype\fR
A string holding a human-readable name for the validation type
triggering the error\&. (Conversely to the \fIcode\fR, which is for
machine-readability, i\&.e\&. trapping)
.TP
string \fIx\fR
The string value which failed the validation\&.
.TP
string \fIcontext\fR
Additional context to show in the message\&.
Defaults to the empty string\&.
.RE
.TP
\fB::cmdr::validate::common\fR \fBfail-known-thing\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
When invoked this command throws an error indicating a validation type
failure\&. The arguments provide the information used to construct both
error message and code\&.
.sp
The generated string has the form:
.CS


    Found a problem with $p\&.type "$p\&.the-name":
    A(n) $type named "$x" already exists$context\&.
     Please use a different name\&.

.CE
.RS
.TP
\fBcmdr::parameter\fR \fIp\fR
The \fBcmdr::parameter\fR instance whose validation failed\&.
The error message will contain this parameter's type and label
(flag in case of an option)\&.
.TP
list \fIcode\fR
A list of additional elements for the error code to throw\&.
Should detail the internal name of the validation type triggering the
error\&.
.TP
string \fItype\fR
A string holding a human-readable name for the validation type
triggering the error\&. (Conversely to the \fIcode\fR, which is for
machine-readability, i\&.e\&. trapping)
.TP
string \fIx\fR
The string value which failed the validation\&.
.TP
string \fIcontext\fR
Additional context to show in the message\&.
Defaults to the empty string\&.
.RE
.TP
\fB::cmdr::validate::common\fR \fBfail-known-thing-msg\fR \fImsg\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
A variant of \fBfail-known-thing\fR which takes an additional
user-specified message text as the first argument\&.
.sp
When invoked this command throws an error indicating a validation type
failure\&. The arguments provide the information used to construct both
error message and code\&.
.sp
The generated string has the form:
.CS


    Found a problem with $p\&.type "$p\&.the-name":
    A(n) $type named "$x" already exists$context\&.
     $msg\&.

.CE
.RS
.TP
string \fImsg\fR
A custom message to put into the generated error message\&.
See the example above\&.
.TP
\fBcmdr::parameter\fR \fIp\fR
The \fBcmdr::parameter\fR instance whose validation failed\&.
The error message will contain this parameter's type and label
(flag in case of an option)\&.
.TP
list \fIcode\fR
A list of additional elements for the error code to throw\&.
Should detail the internal name of the validation type triggering the
error\&.
.TP
string \fItype\fR
A string holding a human-readable name for the validation type
triggering the error\&. (Conversely to the \fIcode\fR, which is for
machine-readability, i\&.e\&. trapping)
.TP
string \fIx\fR
The string value which failed the validation\&.
.TP
string \fIcontext\fR
Additional context to show in the message\&.
Defaults to the empty string\&.
.RE
.TP
\fB::cmdr::validate::common\fR \fBfail-known-simple\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
When invoked this command throws an error indicating a validation type
failure\&. The arguments provide the information used to construct both
error message and code\&.
.sp
The generated string has the form:
.CS


    $type named "$x" already exists$context\&.
     Please use a different name\&.

.CE
.RS
.TP
\fBcmdr::parameter\fR \fIp\fR
The \fBcmdr::parameter\fR instance whose validation failed\&.
The error message will contain this parameter's type and label
(flag in case of an option)\&.
.TP
list \fIcode\fR
A list of additional elements for the error code to throw\&.
Should detail the internal name of the validation type triggering the
error\&.
.TP
string \fItype\fR
A string holding a human-readable name for the validation type
triggering the error\&. (Conversely to the \fIcode\fR, which is for
machine-readability, i\&.e\&. trapping)
.TP
string \fIx\fR
The string value which failed the validation\&.
.TP
string \fIcontext\fR
Additional context to show in the message\&.
Defaults to the empty string\&.
.RE
.TP
\fB::cmdr::validate::common\fR \fBfail-known-simple-msg\fR \fImsg\fR \fIp\fR \fIcode\fR \fItype\fR \fIx\fR ?\fIcontext\fR?
A variant of \fBfail-known-simple\fR which takes an additional
user-specified message text as the first argument\&.
.sp
When invoked this command throws an error indicating a validation type
failure\&. The arguments provide the information used to construct both
error message and code\&.
.sp
The generated string has the form:
.CS


    $type named "$x" already exists$context\&.
     $msg\&.

.CE
.RS
.TP
string \fImsg\fR
A custom message to put into the generated error message\&.
See the example above\&.
.TP
\fBcmdr::parameter\fR \fIp\fR
The \fBcmdr::parameter\fR instance whose validation failed\&.
The error message will contain this parameter's type and label
(flag in case of an option)\&.
.TP
list \fIcode\fR
A list of additional elements for the error code to throw\&.
Should detail the internal name of the validation type triggering the
error\&.
.TP
string \fItype\fR
A string holding a human-readable name for the validation type
triggering the error\&. (Conversely to the \fIcode\fR, which is for
machine-readability, i\&.e\&. trapping)
.TP
string \fIx\fR
The string value which failed the validation\&.
.TP
string \fIcontext\fR
Additional context to show in the message\&.
Defaults to the empty string\&.
.RE
.TP
\fB::cmdr::validate::common\fR \fBcomplete-enum\fR \fIchoices\fR \fInocase\fR \fIbuffer\fR
When invoked this command returns a list of strings containing just
the elements of \fIchoices\fR the value of \fIbuffer\fR is a prefix
of\&. When \fInocase\fR is set the command will ignore letter case and
treat the string in \fIbuffer\fR as all-lowercase\&.

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

124
125
126
127
128
129
130



131



132
133
134
135
136
137
138
139
140
141
142
143
...
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
...
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
<div class="synopsis">
<ul class="requirements">
<li>package require <b class="pkgname">cmdr::validate::common</b></li>
</ul>
<ul class="syntax">
<li><a href="#1"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail</b> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-unknown-thing</b> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></li>



<li><a href="#3"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-known-thing</b> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></li>



<li><a href="#4"><b class="cmd">::cmdr::validate::common</b> <b class="method">complete-enum</b> <i class="arg">choices</i> <i class="arg">nocase</i> <i class="arg">buffer</i></a></li>
<li><a href="#5"><b class="cmd">::cmdr::validate::common</b> <b class="method">complete-substr</b> <i class="arg">choices</i> <i class="arg">nocase</i> <i class="arg">buffer</i></a></li>
<li><a href="#6"><b class="cmd">::cmdr::validate::common</b> <b class="method">complete-glob</b> <i class="arg">filter</i> <i class="arg">buffer</i></a></li>
<li><a href="#7"><b class="cmd">::cmdr::validate::common</b> <b class="method">ok-directory</b> <i class="arg">path</i></a></li>
<li><a href="#8"><b class="cmd">::cmdr::validate::common</b> <b class="method">lead-in</b> <i class="arg">text</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 package publicly exports three commands for use in the
................................................................................
error message and code.</p>
<p>The generated string has the form:</p>
<pre class="example">
    Expected $type for $p.type &quot;$x&quot;$context, got &quot;$x&quot;
</pre>
<dl class="arguments">
<dt><b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> <i class="arg">p</i></dt>
<dd><p>The <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> instance whose validation failed. The
error message will contain this parameter's type and label (flag in
case of an option).</p></dd>
<dt>list <i class="arg">code</i></dt>
<dd><p>A list providing additional elements for the error code, detailing the
internal name of the validation type triggering the error.</p></dd>

<dt>string <i class="arg">type</i></dt>
<dd><p>A string providing the human-readable name of the validation type

triggering the error.</p></dd>

<dt>string <i class="arg">x</i></dt>
<dd><p>The string value failing the validation.</p></dd>
<dt>string <i class="arg">context</i></dt>
<dd><p>Additional context to show in the message. Defaults to the empty string.</p></dd>

</dl></dd>
<dt><a name="2"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-unknown-thing</b> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></dt>
<dd><p>When invoked this command throws an error indicating a validation type
failure. The arguments provide the information used to construct both
error message and code.</p>
<p>The generated string has the form:</p>
<pre class="example">
    Found a problem with $p.type &quot;$p.the-name&quot;:
    A(n) $type named &quot;$x&quot; does not exist$context.
    Please use a different value.
</pre>
<dl class="arguments">
<dt><b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> <i class="arg">p</i></dt>
<dd><p>The <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> instance whose validation failed. The
error message will contain this parameter's type and label (flag in
case of an option).</p></dd>
<dt>list <i class="arg">code</i></dt>
<dd><p>A list providing additional elements for the error code, detailing the
internal name of the validation type triggering the error.</p></dd>

<dt>string <i class="arg">type</i></dt>
<dd><p>A string providing the human-readable name of the validation type
































triggering the error.</p></dd>




<dt>string <i class="arg">x</i></dt>
<dd><p>The string value failing the validation.</p></dd>
<dt>string <i class="arg">context</i></dt>
<dd><p>Additional context to show in the message. Defaults to the empty string.</p></dd>

</dl></dd>





























































<dt><a name="3"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-known-thing</b> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></dt>
<dd><p>When invoked this command throws an error indicating a validation type
failure. The arguments provide the information used to construct both
error message and code.</p>
<p>The generated string has the form:</p>
<pre class="example">
    Found a problem with $p.type &quot;$p.the-name&quot;:
    A(n) $type named &quot;$x&quot; already exists$context.
    Please use a different name.
</pre>
<dl class="arguments">
<dt><b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> <i class="arg">p</i></dt>
<dd><p>The <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> instance whose validation failed. The
error message will contain this parameter's type and label (flag in
case of an option).</p></dd>
<dt>list <i class="arg">code</i></dt>
<dd><p>A list providing additional elements for the error code, detailing the
internal name of the validation type triggering the error.</p></dd>

<dt>string <i class="arg">type</i></dt>
<dd><p>A string providing the human-readable name of the validation type
































triggering the error.</p></dd>




<dt>string <i class="arg">x</i></dt>
<dd><p>The string value failing the validation.</p></dd>
<dt>string <i class="arg">context</i></dt>
<dd><p>Additional context to show in the message. Defaults to the empty string.</p></dd>

</dl></dd>





























































<dt><a name="4"><b class="cmd">::cmdr::validate::common</b> <b class="method">complete-enum</b> <i class="arg">choices</i> <i class="arg">nocase</i> <i class="arg">buffer</i></a></dt>
<dd><p>When invoked this command returns a list of strings containing just
the elements of <i class="arg">choices</i> the value of <i class="arg">buffer</i> is a prefix
of. When <i class="arg">nocase</i> is set the command will ignore letter case and
treat the string in <i class="arg">buffer</i> as all-lowercase.</p>
<dl class="arguments">
<dt>list <i class="arg">choices</i></dt>
<dd><p>The list of values which can complete the data in <i class="arg">buffer</i>.</p></dd>
<dt>boolean <i class="arg">nocase</i></dt>
<dd><p>A boolean flag specifying if the completion is done ignoring
letter-case (<b class="const">true</b>, <b class="const">nocase</b>), or not (<b class="const">false</b>)).</p></dd>
<dt>string <i class="arg">buffer</i></dt>
<dd><p>The string to complete via the list of <i class="arg">choices</i>.</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">::cmdr::validate::common</b> <b class="method">complete-substr</b> <i class="arg">choices</i> <i class="arg">nocase</i> <i class="arg">buffer</i></a></dt>
<dd><p>When invoked this command returns a list of strings containing just
the elements of <i class="arg">choices</i> the value of <i class="arg">buffer</i> is a substring
of. When <i class="arg">nocase</i> is set the command will ignore letter case and
treat the string in <i class="arg">buffer</i> as all-lowercase.</p>
<dl class="arguments">
<dt>list <i class="arg">choices</i></dt>
<dd><p>The list of values which can complete the data in <i class="arg">buffer</i>.</p></dd>
<dt>boolean <i class="arg">nocase</i></dt>
<dd><p>A boolean flag specifying if the completion is done ignoring
letter-case (<b class="const">true</b>, <b class="const">nocase</b>), or not (<b class="const">false</b>)).</p></dd>
<dt>string <i class="arg">buffer</i></dt>
<dd><p>The string to complete via the list of <i class="arg">choices</i>.</p></dd>
</dl></dd>
<dt><a name="6"><b class="cmd">::cmdr::validate::common</b> <b class="method">complete-glob</b> <i class="arg">filter</i> <i class="arg">buffer</i></a></dt>
<dd><p>When invoked this command returns a list of strings, the paths in the
filesystem the value of <i class="arg">buffer</i> is a prefix of, and not rejected
by the <i class="arg">filter</i> command (prefix).</p>
<p>Note that when the value of <i class="arg">buffer</i> is a relative path the
current working directory is used to locate matches.</p>
<dl class="arguments">
<dt>cmd-prefix <i class="arg">filter</i></dt>
................................................................................
<dd><p>A command prefix taking a single argument, the candidate path, and
returning a boolean value indicating (non-)acceptance of the path. A
result of <b class="const">true</b> accepts the candidate, <b class="const">false</b> rejects
it.</p></dd>
<dt>string <i class="arg">buffer</i></dt>
<dd><p>The string, a partial path, to complete.</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">::cmdr::validate::common</b> <b class="method">ok-directory</b> <i class="arg">path</i></a></dt>
<dd><p>When invoked this command checks if the specified <i class="arg">path</i> is
suitable as a directory and returns the boolean value <b class="const">true</b> if
so, and <b class="const">false</b> else.</p>
<p>for the <i class="arg">path</i> to be suitable the following conditions must hold:</p>
<ol class="enumerated">
<li><p>If the <i class="arg">path</i> exists:</p>
<ol class="enumerated">
................................................................................
</ol>
</li>
</ol>
<dl class="arguments">
<dt>string <i class="arg">path</i></dt>
<dd><p>The path to check.</p></dd>
</dl></dd>
<dt><a name="8"><b class="cmd">::cmdr::validate::common</b> <b class="method">lead-in</b> <i class="arg">text</i></a></dt>
<dd><p>A utility command supporting the construction of error messages. Given the
<i class="arg">text</i> the command returns a modified text with a proper prefix of
either <b class="const">A</b> or <b class="const">An</b>.</p>
<p>The basic heuristics is to use <b class="const">An</b> if <i class="arg">text</i> begins with
a vocal, and <b class="const">A</b> otherwise. This heuristic is bypassed if the the
<i class="arg">text</i> already has a prefix of <b class="const">An</b> or <b class="const">A</b> separated by a
space from the remainder of the string. In that case the <i class="arg">text</i> is







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







 







|
|
|

|
|
>

<
>
|
>

|

|
>









|



|
|
|

|
|
>

<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
>
>
>
>

|

|
>

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







|



|
|
|

|
|
>

<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
>
>
>
>

|

|
>

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













|













|







 







|







 







|







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
...
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
...
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
<div class="synopsis">
<ul class="requirements">
<li>package require <b class="pkgname">cmdr::validate::common</b></li>
</ul>
<ul class="syntax">
<li><a href="#1"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail</b> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-unknown-thing</b> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-unknown-thing-msg</b> <i class="arg">msg</i> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-unknown-simple</b> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-unknown-simple-msg</b> <i class="arg">msg</i> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-known-thing</b> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></li>
<li><a href="#7"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-known-thing-msg</b> <i class="arg">msg</i> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></li>
<li><a href="#8"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-known-simple</b> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></li>
<li><a href="#9"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-known-simple-msg</b> <i class="arg">msg</i> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></li>
<li><a href="#10"><b class="cmd">::cmdr::validate::common</b> <b class="method">complete-enum</b> <i class="arg">choices</i> <i class="arg">nocase</i> <i class="arg">buffer</i></a></li>
<li><a href="#11"><b class="cmd">::cmdr::validate::common</b> <b class="method">complete-substr</b> <i class="arg">choices</i> <i class="arg">nocase</i> <i class="arg">buffer</i></a></li>
<li><a href="#12"><b class="cmd">::cmdr::validate::common</b> <b class="method">complete-glob</b> <i class="arg">filter</i> <i class="arg">buffer</i></a></li>
<li><a href="#13"><b class="cmd">::cmdr::validate::common</b> <b class="method">ok-directory</b> <i class="arg">path</i></a></li>
<li><a href="#14"><b class="cmd">::cmdr::validate::common</b> <b class="method">lead-in</b> <i class="arg">text</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 package publicly exports three commands for use in the
................................................................................
error message and code.</p>
<p>The generated string has the form:</p>
<pre class="example">
    Expected $type for $p.type &quot;$x&quot;$context, got &quot;$x&quot;
</pre>
<dl class="arguments">
<dt><b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> <i class="arg">p</i></dt>
<dd><p>The <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> instance whose validation failed.
The error message will contain this parameter's type and label
(flag in case of an option).</p></dd>
<dt>list <i class="arg">code</i></dt>
<dd><p>A list of additional elements for the error code to throw.
Should detail the internal name of the validation type triggering the
error.</p></dd>
<dt>string <i class="arg">type</i></dt>

<dd><p>A string holding a human-readable name for the validation type
triggering the error. (Conversely to the <i class="arg">code</i>, which is for
machine-readability, i.e. trapping)</p></dd>
<dt>string <i class="arg">x</i></dt>
<dd><p>The string value which failed the validation.</p></dd>
<dt>string <i class="arg">context</i></dt>
<dd><p>Additional context to show in the message.
Defaults to the empty string.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-unknown-thing</b> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></dt>
<dd><p>When invoked this command throws an error indicating a validation type
failure. The arguments provide the information used to construct both
error message and code.</p>
<p>The generated string has the form:</p>
<pre class="example">
    Found a problem with $p.type &quot;$p.the-name&quot;:
    A(n) $type named &quot;$x&quot; does not exist$context.
     Please use a different value.
</pre>
<dl class="arguments">
<dt><b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> <i class="arg">p</i></dt>
<dd><p>The <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> instance whose validation failed.
The error message will contain this parameter's type and label
(flag in case of an option).</p></dd>
<dt>list <i class="arg">code</i></dt>
<dd><p>A list of additional elements for the error code to throw.
Should detail the internal name of the validation type triggering the
error.</p></dd>
<dt>string <i class="arg">type</i></dt>

<dd><p>A string holding a human-readable name for the validation type
triggering the error. (Conversely to the <i class="arg">code</i>, which is for
machine-readability, i.e. trapping)</p></dd>
<dt>string <i class="arg">x</i></dt>
<dd><p>The string value which failed the validation.</p></dd>
<dt>string <i class="arg">context</i></dt>
<dd><p>Additional context to show in the message.
Defaults to the empty string.</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-unknown-thing-msg</b> <i class="arg">msg</i> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></dt>
<dd><p>A variant of <b class="method">fail-unknown-thing</b> which takes an additional
user-specified message text as the first argument.</p>
<p>When invoked this command throws an error indicating a validation type
failure. The arguments provide the information used to construct both
error message and code.</p>
<p>The generated string has the form:</p>
<pre class="example">
    Found a problem with $p.type &quot;$p.the-name&quot;:
    A(n) $type named &quot;$x&quot; does not exist$context.
     $msg.
</pre>
<dl class="arguments">
<dt>string <i class="arg">msg</i></dt>
<dd><p>A custom message to put into the generated error message.
See the example above.</p></dd>
<dt><b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> <i class="arg">p</i></dt>
<dd><p>The <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> instance whose validation failed.
The error message will contain this parameter's type and label
(flag in case of an option).</p></dd>
<dt>list <i class="arg">code</i></dt>
<dd><p>A list of additional elements for the error code to throw.
Should detail the internal name of the validation type triggering the
error.</p></dd>
<dt>string <i class="arg">type</i></dt>
<dd><p>A string holding a human-readable name for the validation type
triggering the error. (Conversely to the <i class="arg">code</i>, which is for
machine-readability, i.e. trapping)</p></dd>
<dt>string <i class="arg">x</i></dt>
<dd><p>The string value which failed the validation.</p></dd>
<dt>string <i class="arg">context</i></dt>
<dd><p>Additional context to show in the message.
Defaults to the empty string.</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-unknown-simple</b> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></dt>
<dd><p>When invoked this command throws an error indicating a validation type
failure. The arguments provide the information used to construct both
error message and code.</p>
<p>The generated string has the form:</p>
<pre class="example">
    $type &quot;$x&quot; does not exist$context.
     Please use a different value.
</pre>
<dl class="arguments">
<dt><b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> <i class="arg">p</i></dt>
<dd><p>The <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> instance whose validation failed.
The error message will contain this parameter's type and label
(flag in case of an option).</p></dd>
<dt>list <i class="arg">code</i></dt>
<dd><p>A list of additional elements for the error code to throw.
Should detail the internal name of the validation type triggering the
error.</p></dd>
<dt>string <i class="arg">type</i></dt>
<dd><p>A string holding a human-readable name for the validation type
triggering the error. (Conversely to the <i class="arg">code</i>, which is for
machine-readability, i.e. trapping)</p></dd>
<dt>string <i class="arg">x</i></dt>
<dd><p>The string value which failed the validation.</p></dd>
<dt>string <i class="arg">context</i></dt>
<dd><p>Additional context to show in the message.
Defaults to the empty string.</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-unknown-simple-msg</b> <i class="arg">msg</i> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></dt>
<dd><p>A variant of <b class="method">fail-unknown-simple</b> which takes an additional
user-specified message text as the first argument.</p>
<p>When invoked this command throws an error indicating a validation type
failure. The arguments provide the information used to construct both
error message and code.</p>
<p>The generated string has the form:</p>
<pre class="example">
    $type &quot;$x&quot; does not exist$context.
     $msg.
</pre>
<dl class="arguments">
<dt>string <i class="arg">msg</i></dt>
<dd><p>A custom message to put into the generated error message.
See the example above.</p></dd>
<dt><b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> <i class="arg">p</i></dt>
<dd><p>The <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> instance whose validation failed.
The error message will contain this parameter's type and label
(flag in case of an option).</p></dd>
<dt>list <i class="arg">code</i></dt>
<dd><p>A list of additional elements for the error code to throw.
Should detail the internal name of the validation type triggering the
error.</p></dd>
<dt>string <i class="arg">type</i></dt>
<dd><p>A string holding a human-readable name for the validation type
triggering the error. (Conversely to the <i class="arg">code</i>, which is for
machine-readability, i.e. trapping)</p></dd>
<dt>string <i class="arg">x</i></dt>
<dd><p>The string value which failed the validation.</p></dd>
<dt>string <i class="arg">context</i></dt>
<dd><p>Additional context to show in the message.
Defaults to the empty string.</p></dd>
</dl></dd>
<dt><a name="6"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-known-thing</b> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></dt>
<dd><p>When invoked this command throws an error indicating a validation type
failure. The arguments provide the information used to construct both
error message and code.</p>
<p>The generated string has the form:</p>
<pre class="example">
    Found a problem with $p.type &quot;$p.the-name&quot;:
    A(n) $type named &quot;$x&quot; already exists$context.
     Please use a different name.
</pre>
<dl class="arguments">
<dt><b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> <i class="arg">p</i></dt>
<dd><p>The <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> instance whose validation failed.
The error message will contain this parameter's type and label
(flag in case of an option).</p></dd>
<dt>list <i class="arg">code</i></dt>
<dd><p>A list of additional elements for the error code to throw.
Should detail the internal name of the validation type triggering the
error.</p></dd>
<dt>string <i class="arg">type</i></dt>

<dd><p>A string holding a human-readable name for the validation type
triggering the error. (Conversely to the <i class="arg">code</i>, which is for
machine-readability, i.e. trapping)</p></dd>
<dt>string <i class="arg">x</i></dt>
<dd><p>The string value which failed the validation.</p></dd>
<dt>string <i class="arg">context</i></dt>
<dd><p>Additional context to show in the message.
Defaults to the empty string.</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-known-thing-msg</b> <i class="arg">msg</i> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></dt>
<dd><p>A variant of <b class="method">fail-known-thing</b> which takes an additional
user-specified message text as the first argument.</p>
<p>When invoked this command throws an error indicating a validation type
failure. The arguments provide the information used to construct both
error message and code.</p>
<p>The generated string has the form:</p>
<pre class="example">
    Found a problem with $p.type &quot;$p.the-name&quot;:
    A(n) $type named &quot;$x&quot; already exists$context.
     $msg.
</pre>
<dl class="arguments">
<dt>string <i class="arg">msg</i></dt>
<dd><p>A custom message to put into the generated error message.
See the example above.</p></dd>
<dt><b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> <i class="arg">p</i></dt>
<dd><p>The <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> instance whose validation failed.
The error message will contain this parameter's type and label
(flag in case of an option).</p></dd>
<dt>list <i class="arg">code</i></dt>
<dd><p>A list of additional elements for the error code to throw.
Should detail the internal name of the validation type triggering the
error.</p></dd>
<dt>string <i class="arg">type</i></dt>
<dd><p>A string holding a human-readable name for the validation type
triggering the error. (Conversely to the <i class="arg">code</i>, which is for
machine-readability, i.e. trapping)</p></dd>
<dt>string <i class="arg">x</i></dt>
<dd><p>The string value which failed the validation.</p></dd>
<dt>string <i class="arg">context</i></dt>
<dd><p>Additional context to show in the message.
Defaults to the empty string.</p></dd>
</dl></dd>
<dt><a name="8"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-known-simple</b> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></dt>
<dd><p>When invoked this command throws an error indicating a validation type
failure. The arguments provide the information used to construct both
error message and code.</p>
<p>The generated string has the form:</p>
<pre class="example">
    $type named &quot;$x&quot; already exists$context.
     Please use a different name.
</pre>
<dl class="arguments">
<dt><b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> <i class="arg">p</i></dt>
<dd><p>The <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> instance whose validation failed.
The error message will contain this parameter's type and label
(flag in case of an option).</p></dd>
<dt>list <i class="arg">code</i></dt>
<dd><p>A list of additional elements for the error code to throw.
Should detail the internal name of the validation type triggering the
error.</p></dd>
<dt>string <i class="arg">type</i></dt>
<dd><p>A string holding a human-readable name for the validation type
triggering the error. (Conversely to the <i class="arg">code</i>, which is for
machine-readability, i.e. trapping)</p></dd>
<dt>string <i class="arg">x</i></dt>
<dd><p>The string value which failed the validation.</p></dd>
<dt>string <i class="arg">context</i></dt>
<dd><p>Additional context to show in the message.
Defaults to the empty string.</p></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">::cmdr::validate::common</b> <b class="method">fail-known-simple-msg</b> <i class="arg">msg</i> <i class="arg">p</i> <i class="arg">code</i> <i class="arg">type</i> <i class="arg">x</i> <span class="opt">?<i class="arg">context</i>?</span></a></dt>
<dd><p>A variant of <b class="method">fail-known-simple</b> which takes an additional
user-specified message text as the first argument.</p>
<p>When invoked this command throws an error indicating a validation type
failure. The arguments provide the information used to construct both
error message and code.</p>
<p>The generated string has the form:</p>
<pre class="example">
    $type named &quot;$x&quot; already exists$context.
     $msg.
</pre>
<dl class="arguments">
<dt>string <i class="arg">msg</i></dt>
<dd><p>A custom message to put into the generated error message.
See the example above.</p></dd>
<dt><b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> <i class="arg">p</i></dt>
<dd><p>The <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> instance whose validation failed.
The error message will contain this parameter's type and label
(flag in case of an option).</p></dd>
<dt>list <i class="arg">code</i></dt>
<dd><p>A list of additional elements for the error code to throw.
Should detail the internal name of the validation type triggering the
error.</p></dd>
<dt>string <i class="arg">type</i></dt>
<dd><p>A string holding a human-readable name for the validation type
triggering the error. (Conversely to the <i class="arg">code</i>, which is for
machine-readability, i.e. trapping)</p></dd>
<dt>string <i class="arg">x</i></dt>
<dd><p>The string value which failed the validation.</p></dd>
<dt>string <i class="arg">context</i></dt>
<dd><p>Additional context to show in the message.
Defaults to the empty string.</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">::cmdr::validate::common</b> <b class="method">complete-enum</b> <i class="arg">choices</i> <i class="arg">nocase</i> <i class="arg">buffer</i></a></dt>
<dd><p>When invoked this command returns a list of strings containing just
the elements of <i class="arg">choices</i> the value of <i class="arg">buffer</i> is a prefix
of. When <i class="arg">nocase</i> is set the command will ignore letter case and
treat the string in <i class="arg">buffer</i> as all-lowercase.</p>
<dl class="arguments">
<dt>list <i class="arg">choices</i></dt>
<dd><p>The list of values which can complete the data in <i class="arg">buffer</i>.</p></dd>
<dt>boolean <i class="arg">nocase</i></dt>
<dd><p>A boolean flag specifying if the completion is done ignoring
letter-case (<b class="const">true</b>, <b class="const">nocase</b>), or not (<b class="const">false</b>)).</p></dd>
<dt>string <i class="arg">buffer</i></dt>
<dd><p>The string to complete via the list of <i class="arg">choices</i>.</p></dd>
</dl></dd>
<dt><a name="11"><b class="cmd">::cmdr::validate::common</b> <b class="method">complete-substr</b> <i class="arg">choices</i> <i class="arg">nocase</i> <i class="arg">buffer</i></a></dt>
<dd><p>When invoked this command returns a list of strings containing just
the elements of <i class="arg">choices</i> the value of <i class="arg">buffer</i> is a substring
of. When <i class="arg">nocase</i> is set the command will ignore letter case and
treat the string in <i class="arg">buffer</i> as all-lowercase.</p>
<dl class="arguments">
<dt>list <i class="arg">choices</i></dt>
<dd><p>The list of values which can complete the data in <i class="arg">buffer</i>.</p></dd>
<dt>boolean <i class="arg">nocase</i></dt>
<dd><p>A boolean flag specifying if the completion is done ignoring
letter-case (<b class="const">true</b>, <b class="const">nocase</b>), or not (<b class="const">false</b>)).</p></dd>
<dt>string <i class="arg">buffer</i></dt>
<dd><p>The string to complete via the list of <i class="arg">choices</i>.</p></dd>
</dl></dd>
<dt><a name="12"><b class="cmd">::cmdr::validate::common</b> <b class="method">complete-glob</b> <i class="arg">filter</i> <i class="arg">buffer</i></a></dt>
<dd><p>When invoked this command returns a list of strings, the paths in the
filesystem the value of <i class="arg">buffer</i> is a prefix of, and not rejected
by the <i class="arg">filter</i> command (prefix).</p>
<p>Note that when the value of <i class="arg">buffer</i> is a relative path the
current working directory is used to locate matches.</p>
<dl class="arguments">
<dt>cmd-prefix <i class="arg">filter</i></dt>
................................................................................
<dd><p>A command prefix taking a single argument, the candidate path, and
returning a boolean value indicating (non-)acceptance of the path. A
result of <b class="const">true</b> accepts the candidate, <b class="const">false</b> rejects
it.</p></dd>
<dt>string <i class="arg">buffer</i></dt>
<dd><p>The string, a partial path, to complete.</p></dd>
</dl></dd>
<dt><a name="13"><b class="cmd">::cmdr::validate::common</b> <b class="method">ok-directory</b> <i class="arg">path</i></a></dt>
<dd><p>When invoked this command checks if the specified <i class="arg">path</i> is
suitable as a directory and returns the boolean value <b class="const">true</b> if
so, and <b class="const">false</b> else.</p>
<p>for the <i class="arg">path</i> to be suitable the following conditions must hold:</p>
<ol class="enumerated">
<li><p>If the <i class="arg">path</i> exists:</p>
<ol class="enumerated">
................................................................................
</ol>
</li>
</ol>
<dl class="arguments">
<dt>string <i class="arg">path</i></dt>
<dd><p>The path to check.</p></dd>
</dl></dd>
<dt><a name="14"><b class="cmd">::cmdr::validate::common</b> <b class="method">lead-in</b> <i class="arg">text</i></a></dt>
<dd><p>A utility command supporting the construction of error messages. Given the
<i class="arg">text</i> the command returns a modified text with a proper prefix of
either <b class="const">A</b> or <b class="const">An</b>.</p>
<p>The basic heuristics is to use <b class="const">An</b> if <i class="arg">text</i> begins with
a vocal, and <b class="const">A</b> otherwise. This heuristic is bypassed if the the
<i class="arg">text</i> already has a prefix of <b class="const">An</b> or <b class="const">A</b> separated by a
space from the remainder of the string. In that case the <i class="arg">text</i> is