cmdr
Check-in [e33e0f5b2d]
Not logged in

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

Overview
Comment:Continued work on the dev guide. Complete architecture and package dependency information. Regenerated figures and embedded documentation.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:e33e0f5b2db06bc1564d2df61195a53adf6748cf
User & Date: aku 2013-11-26 05:17:22
Context
2013-11-26
05:34
Tweaked documented titles for better marking of internals. Fixed a few issues with validation types, mainly shuffling text blocks around, plus fix in API documentation. check-in: dbd259771b user: aku tags: trunk
05:17
Continued work on the dev guide. Complete architecture and package dependency information. Regenerated figures and embedded documentation. check-in: e33e0f5b2d user: aku tags: trunk
00:32
Continued documentation work, first fillings for the dev-guide, more figures. check-in: 172951e9a3 user: andreask tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Added doc/figures/architecture.png.

cannot compute difference between binary files

Added doc/figures/dsl_dependencies.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
35
36
37
38
39
40
41
42
43
44
45
46
# -*- tcl -*- tcl.tk//DSL diagram//EN//1.0
# # ## ### ##### ######## #############
## DSL parameters, defaults.

proc default {var value} {
    upvar 1 $var v
    if {[info exists v]} return
    set v $value
}

default grid [3 mm]
default bw   8
default bh   4
default ll   2
#default textfont {Helvetica 10}

# # ## ### ##### ######## #############
## Derived values

set boxwidth     [expr {$bw   * $grid}]
set boxheight    [expr {$bh   * $grid}]
set movelength   [expr {$ll   * $grid}]
set arcradius    [expr {$ll/2 * $grid}]

proc grid {n} {
    variable grid
    expr {$n * $grid}
}

# # ## ### ##### ######## #############
## Macros for dependency arrows and navigation.

proc --- {{n 1}} {
    variable movelength
    line [direction] [expr {$n * $movelength}]
}
proc ---> {{n 1}} {
    variable movelength
    arrow [direction] [expr {$n * $movelength}]
}
proc l {} { arc cw }
proc r {} { arc }
proc d {} { if {[direction] eq "west"} { arc } else { arc cw } }

# # ## ### ##### ######## #############
return

Changes to doc/figures/erd.png.

cannot compute difference between binary files

Added doc/figures/pkg_dependencies.dia.



























































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
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
# -*- tcl -*- tcl.tk//DSL diagram//EN//1.0
## ====================================================================
## DSL for dependency diagram. Default parameters.

source [file join [file dirname [file normalize [info script]]] dsl_dependencies.inc]

## ====================================================================
## Dependencies, bottom-up, one procedure per package.

proc actor     {} { box cmdr::actor                            }
proc util      {} { box cmdr::util                             }
proc vcommon   {} { box cmdr::validate::common width [grid 15] color blue stroke 2 }
proc parameter {} { box cmdr::parameter        width [grid 10] color blue stroke 2 dashed }

proc validate {} {
    box cmdr::validate width [grid 9]
    group { down ; ---> ; vcommon }
}

proc help {} {
    box cmdr::help
    group { down ; ---> ; util }
}

proc help_json {} {
    box cmdr::help::json width [grid 10] color blue stroke 2
    group { down ; ---> 16 ; help }
}

proc help_sql {} {
    box cmdr::help::sql width [grid 10] color blue stroke 2
    group { down ; --- ; l ; --- 4 ; r ; ---> 14 ; # help
    }
}

proc config {} {
    box cmdr::config color blue stroke 2 dashed
    group { down ; --- ; l ; --- 5 ; r ; ---> ; parameter }
    group { down ; ---> 3 ; validate }
    group { down ; --- ; r ; --- 4.5 ; l ; ---> ; # help
    }
}

proc private {} {
    box cmdr::private
    group { down ; --- ; l ; --- 5 ; r ; ---> ; actor }
    group { down ; ---> 3 ; config }
}

proc officer {} {
    box cmdr::officer
    group { down ; ---> 3 ; private }
    group { down ; --- ; l ; --- 6 ; r ; ---> 6 ; #actor
    }
}

proc cmdr {} {
    box cmdr color blue stroke 2
    group { down ; ---> ; officer }
}

## ====================================================================

proc layout {} {
    east
    cmdr
    move
    move
    help_json
    move
    help_sql
    move
}

## ====================================================================

layout

Added doc/figures/pkg_dependencies.png.

cannot compute difference between binary files

Changes to doc/parts/architecture.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


[para] All packages in the framework belong to one of three layers,
as shown below:

[image architecture].



[list_begin itemized]






[item] The topmost layer contains only a single package,
[package cmdr], which is a trivial entry point to the system.

[item] The bottom layer contains the mainly internal utility packages.
The exception is [package cmdr::validate::common], for use in bespoke
validation types. See the document about [term [vset TITLE_DEV_VT]]
for details.

[item] The important pieces implementing the various entities are all
in the middle layer. The relationship of these entities can be seen in
the next diagram:

[image erd]
[list_end]

[para] Packages marked with a dashed blue border are public in parts,
and private in parts.





[para] Packages marked with an unbroken blue border are fully public.





|
>
>



>
>
>
>
>

|










|


|
|
>
>
>
>

<
>
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
35
36
37

38

[para] All packages in the framework belong to one of three layers,
as shown below:

[para][image architecture]

[para] Note that:

[list_begin itemized]

[item] Packages marked with a dashed blue border are public in parts,
and private in parts.

[item] Packages marked with an unbroken blue border are fully public.

[item] The topmost layer contains only a single package,
[package cmdr], which is the trivial entry point to the system.

[item] The bottom layer contains the mainly internal utility packages.
The exception is [package cmdr::validate::common], for use in bespoke
validation types. See the document about [term [vset TITLE_DEV_VT]]
for details.

[item] The important pieces implementing the various entities are all
in the middle layer. The relationship of these entities can be seen in
the next diagram:

[para][image erd]
[list_end]

[para] The dependencies between the packages are very
straight-forward, following mostly directly out of the relationships
shown above, plus the few where the utilities are imported. To reduce
the complexity of the diagram below a few direct dependencies on
[package cmdr::util] were omitted where indirectly present through
other dependencies (i.e. through [package cmdr::help]):


[para][image pkg_dependencies]

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

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
\fICmdr - The Installer's Guide\fR
.PP
first, if that was not done already\&. Here we assume that the sources
are already available in a directory of your choice, that it is known
how to build and install the project, and that all the necessary
requisites are available\&.
.SH "DEVELOPMENT TOOLS"
Cmdr (currently) does not require tools beyond those needed for
build and installation\&.














.SH "DEMONSTRATION/EXAMPLE APPLICATIONS"
Cmdr (currently) does not have demonstrations, nor examples\&.
.SH "DIRECTORY STRUCTURE"
Explain the physical layout (directory structure)\&.


























































































































.SH "ARCHITECTURE & CONCEPTS"

.IP [1]
Explain the internal architecture\&.
.IP [2]
Explain file dependencies, if any\&.

.IP [3]
Explain package dependencies, if any\&.





















.IP [4]
Explain the internal data structures, if any\&.


.IP [5]
Explain entity relationships (UML ERD), if any\&.

.IP [6]
Explain important operation sequences (UML SD), if any\&.


























.PP











.SH "RELATED DOCUMENTS"
.IP [1]
\fICmdr - Introduction to the project\fR
.IP [2]
\fICmdr - License\fR
.IP [3]
\fICmdr - Log of Changes\fR







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




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

>

|

<
>

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

>
>
>
>
>
>
>
>
>
>
>







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
\fICmdr - The Installer's Guide\fR
.PP
first, if that was not done already\&. Here we assume that the sources
are already available in a directory of your choice, that it is known
how to build and install the project, and that all the necessary
requisites are available\&.
.SH "DEVELOPMENT TOOLS"
Cmdr requires the following tools going beyond those needed
for build and installation\&.
.TP
\fBdia\fR
Processor for \fBdiagram\fR-based figures\&.
See package \fBtklib\fR\&.
.TP
\fBdtplite\fR
Processor for \fBdoctools\fR-based documentation files, i\&.e\&. the
"\fI\&.man\fR" files under "\fIdoc/\fR"\&.
See package \fBtcllib\fR\&.
.sp
This requirement is optional\&. If a Tcllib providing the package
\fBdtplite\fR is installed then \fBkettle\fR will use the
package in favor of the external application\&.
.PP
.SH "DEMONSTRATION/EXAMPLE APPLICATIONS"
Cmdr (currently) does not have demonstrations, nor examples\&.
.SH "DIRECTORY STRUCTURE"
Explain the physical layout (directory structure)\&.
.TP
"\fIbuild\&.tcl\fR"
The main file of the \fBkettle\fR-based build-system\&.
.TP
"\fIdoc/\fR"
Main directory for all documentation\&.
.sp
Based on the \fBdoctools\fR package and tools provided by
\fBTcllib\fR\&.
.TP
"\fIdoc/figures/\fR"
Main directory for all diagrams and figures used by the documentation\&.
.sp
Based on the \fBdiagram\fR package and tools provided by
\fBTklib\fR\&.
.TP
"\fIembedded/\fR"
Compiled documentation (manpages and HTML)\&.
Part of the repository for
.RS
.IP [1]
easy access from the repository's web interface
(\fIembedded documentation\fR [http://fossil-scm\&.org/index\&.html/doc/tip/www/embeddeddoc\&.wiki]),
and
.IP [2]
quicker installation (no need to compile during the
installation process itself)\&.
.RE
.TP
"\fItests/\fR"
Main directory for the test-suite\&.
.sp
Based on the \fBtcltest\fR package distributed with the Tcl
core\&.
.TP
"\fIactor\&.tcl\fR"
== Package \fBcmdr::actor\fR\&.
.TP
"\fIcmdr\&.tcl\fR"
== Package \fBcmdr\fR\&.
.TP
"\fIconfig\&.tcl\fR"
== Package \fBcmdr::config\fR\&.
.TP
"\fIhelp\&.tcl\fR"
== Package \fBcmdr::help\fR\&.
.TP
"\fIhelp_json\&.tcl\fR"
== Package \fBcmdr::help::json\fR\&.
.TP
"\fIhelp_sql\&.tcl\fR"
== Package \fBcmdr::help::sql\fR\&.
.TP
"\fIofficer\&.tcl\fR"
== Package \fBcmdr::officer\fR\&.
.TP
"\fIparameter\&.tcl\fR"
== Package \fBcmdr::parameter\fR\&.
.TP
"\fIprivate\&.tcl\fR"
== Package \fBcmdr::private\fR\&.
.TP
"\fIutil\&.tcl\fR"
== Package \fBcmdr::util\fR\&.
.TP
"\fIvalidate\&.tcl\fR"
== Package \fBcmdr::validate\fR\&.
.TP
"\fIvcommon\&.tcl\fR"
== Package \fBcmdr::validate::common\fR\&.
.PP
.SH "EXTENDED BUILD ACTIONS"
Our build-system is based on \fBkettle\fR, as already explained in
the \fICmdr - The Installer's Guide\fR\&. Beyond the targets useful for
installation it also provides targets aiding developers and
maintainers\&. These are:
.TP
Validation of the documentation
.CS


% /path/to/cmdr/build\&.tcl validate-doc

.CE
.TP
Regeneration of the embedded documentation
.CS


% /path/to/cmdr/build\&.tcl doc

.CE
.TP
Regeneration of the figures for the documentation
.CS


% /path/to/cmdr/build\&.tcl figures

.CE
.TP
Execution of the test-suite
The most basic execution of the test-suite is done with
.CS


% /path/to/cmdr/build\&.tcl test

.CE
.sp
When the test-suite reports issues with the framework use of
the more extended form below is indicated, with a \fB<stem>\fR of
your choice\&. This will generate a number of files whose name starts
with the prefix "\fI<stem>\&.\fR"\&. These will contain extended test logs,
details about errors and failures, etc\&.
.CS


% /path/to/cmdr/build\&.tcl test --log <stem>

.CE
.PP
.SH "ARCHITECTURE & CONCEPTS"
The following sections explain
.IP [1]
the internal architecture and package dependencies\&.
.IP [2]

the internal data structures\&.
.IP [3]

important operation sequences (UML SD)\&.
.PP
.SS "SYSTEM ARCHITECTURE"
.PP
All packages in the framework belong to one of three layers,
as shown below:
.PP
.PS
.nf
+--------------------------------------------+
|                    cmdr                    |
+--------------------------------------------+
| actor, officer, private, config, parameter |
+--------------------------------------------+
|           help*, util, validate*           |
+--------------------------------------------+

.fi
.PE
.PP
Note that:
.IP \(bu

Packages marked with a dashed blue border are public in parts,
and private in parts\&.
.IP \(bu

Packages marked with an unbroken blue border are fully public\&.
.IP \(bu

The topmost layer contains only a single package,
\fBcmdr\fR, which is the trivial entry point to the system\&.
.IP \(bu
The bottom layer contains the mainly internal utility packages\&.
The exception is \fBcmdr::validate::common\fR, for use in bespoke
validation types\&. See the document about \fICmdr - Writing custom validation types\fR
for details\&.
.IP \(bu
The important pieces implementing the various entities are all
in the middle layer\&. The relationship of these entities can be seen in
the next diagram:
.sp
.PS
.nf
      is-a         is-a
    /-1:1-> actor <-1:1-\\
   /                     \\
officer ---1:(0-n)--> private --1:1-> config --1:(0-n)-> parameter
 |  ^      has                  has            has
 |  |
 \\--/
 1:(0-n)
 has

.fi
.PE
.PP
.PP
The dependencies between the packages are very
straight-forward, following mostly directly out of the relationships
shown above, plus the few where the utilities are imported\&. To reduce
the complexity of the diagram below a few direct dependencies on
\fBcmdr::util\fR were omitted where indirectly present through
other dependencies (i\&.e\&. through \fBcmdr::help\fR):
.PP
IMAGE: pkg_dependencies
.SS "DATA STRUCTURES"
.SS "OPERATION SEQUENCES"
.SH "RELATED DOCUMENTS"
.IP [1]
\fICmdr - Introduction to the project\fR
.IP [2]
\fICmdr - License\fR
.IP [3]
\fICmdr - Log of Changes\fR

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

258
259
260
261
262
263
264




























































265
266
267
268
269
270
271
specification, handle the bulk of processing \fB$::argv\fR\&. This
covers determining the requested command, mapping argument words to
command parameters, and validating them\&.
Additional features of the runtime are an integrated help system and
interactive command line shells with basic command and argument
completion\&.
.SH "SYSTEM ARCHITECTURE"




























































.SH "RELATED DOCUMENTS"
.IP [1]
\fICmdr - Introduction to the project\fR
.IP [2]
\fICmdr - License\fR
.IP [3]
\fICmdr - Log of Changes\fR







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







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
specification, handle the bulk of processing \fB$::argv\fR\&. This
covers determining the requested command, mapping argument words to
command parameters, and validating them\&.
Additional features of the runtime are an integrated help system and
interactive command line shells with basic command and argument
completion\&.
.SH "SYSTEM ARCHITECTURE"
.PP
All packages in the framework belong to one of three layers,
as shown below:
.PP
.PS
.nf
+--------------------------------------------+
|                    cmdr                    |
+--------------------------------------------+
| actor, officer, private, config, parameter |
+--------------------------------------------+
|           help*, util, validate*           |
+--------------------------------------------+

.fi
.PE
.PP
Note that:
.IP \(bu
Packages marked with a dashed blue border are public in parts,
and private in parts\&.
.IP \(bu
Packages marked with an unbroken blue border are fully public\&.
.IP \(bu
The topmost layer contains only a single package,
\fBcmdr\fR, which is the trivial entry point to the system\&.
.IP \(bu
The bottom layer contains the mainly internal utility packages\&.
The exception is \fBcmdr::validate::common\fR, for use in bespoke
validation types\&. See the document about \fICmdr - Writing custom validation types\fR
for details\&.
.IP \(bu
The important pieces implementing the various entities are all
in the middle layer\&. The relationship of these entities can be seen in
the next diagram:
.sp
.PS
.nf
      is-a         is-a
    /-1:1-> actor <-1:1-\\
   /                     \\
officer ---1:(0-n)--> private --1:1-> config --1:(0-n)-> parameter
 |  ^      has                  has            has
 |  |
 \\--/
 1:(0-n)
 has

.fi
.PE
.PP
.PP
The dependencies between the packages are very
straight-forward, following mostly directly out of the relationships
shown above, plus the few where the utilities are imported\&. To reduce
the complexity of the diagram below a few direct dependencies on
\fBcmdr::util\fR were omitted where indirectly present through
other dependencies (i\&.e\&. through \fBcmdr::help\fR):
.PP
IMAGE: pkg_dependencies
.SH "RELATED DOCUMENTS"
.IP [1]
\fICmdr - Introduction to the project\fR
.IP [2]
\fICmdr - License\fR
.IP [3]
\fICmdr - Log of Changes\fR

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

284
285
286
287
288
289
290


291
292
293
294
295
296
297
...
527
528
529
530
531
532
533








534
535
536
537
538
539
540
.sp
\fB<officer>\fR \fBprompt1\fR
.sp
\fB<officer>\fR \fBprompt2\fR
.sp
\fB<officer>\fR \fBreport\fR \fIwhat\fR \fIdata\fR
.sp


.BE
.SH DESCRIPTION
.PP
Welcome to the Cmdr project, written by Andreas Kupries\&.
.PP
For availability please read \fICmdr - How To Get The Sources\fR\&.
.PP
................................................................................
.TP
enum \fIwhat\fR
The result code of the command, one of \fBok\fR, or \fBfail\fR\&.
.TP
any \fIdata\fR
The result of the command, or an error message in case of failure\&.
.RE








.PP
.SH "HELP INFORMATION"
The help information generated by various places of the framework
is a dictionary containing the following keys:
.TP
arguments
A list of strings, the names of the command arguments, in order\&.







>
>







 







>
>
>
>
>
>
>
>







284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
...
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
.sp
\fB<officer>\fR \fBprompt1\fR
.sp
\fB<officer>\fR \fBprompt2\fR
.sp
\fB<officer>\fR \fBreport\fR \fIwhat\fR \fIdata\fR
.sp
\fB<officer>\fR \fBshell-exit\fR \fIconfig\fR
.sp
.BE
.SH DESCRIPTION
.PP
Welcome to the Cmdr project, written by Andreas Kupries\&.
.PP
For availability please read \fICmdr - How To Get The Sources\fR\&.
.PP
................................................................................
.TP
enum \fIwhat\fR
The result code of the command, one of \fBok\fR, or \fBfail\fR\&.
.TP
any \fIdata\fR
The result of the command, or an error message in case of failure\&.
.RE
.TP
\fB<officer>\fR \fBshell-exit\fR \fIconfig\fR
This is the backend for a private ending the main shell,
be it automatically created by the pacge, or by a user\&.
.sp
The argument is the \fBcmdr::config\fR
instance holding the parameters\&. The method does not
expect any and ignore it\&.
.PP
.SH "HELP INFORMATION"
The help information generated by various places of the framework
is a dictionary containing the following keys:
.TP
arguments
A list of strings, the names of the command arguments, in order\&.

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

112
113
114
115
116
117
118
119
120






121

122
123
124
125
126
127
128
...
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
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">
<li class="section"><a href="#toc">Table Of Contents</a></li>
<li class="section"><a href="#section1">Description</a></li>
<li class="section"><a href="#section2">Development Tools</a></li>
<li class="section"><a href="#section3">Demonstration/Example Applications</a></li>
<li class="section"><a href="#section4">Directory structure</a></li>
<li class="section"><a href="#section5">Architecture &amp; Concepts</a></li>
<li class="section"><a href="#section6">Related Documents</a></li>






<li class="section"><a href="#section7">Bugs, Ideas, Feedback</a></li>

<li class="section"><a href="#keywords">Keywords</a></li>
<li class="section"><a href="#copyright">Copyright</a></li>
</ul>
</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>
................................................................................
</ol>
<p>first, if that was not done already. Here we assume that the sources
are already available in a directory of your choice, that it is known
how to build and install the project, and that all the necessary
requisites are available.</p>
</div>
<div id="section2" class="section"><h2><a name="section2">Development Tools</a></h2>
<p>Cmdr (currently) does not require tools beyond those needed for
build and installation.</p>












</div>
<div id="section3" class="section"><h2><a name="section3">Demonstration/Example Applications</a></h2>
<p>Cmdr (currently) does not have demonstrations, nor examples.</p>
</div>
<div id="section4" class="section"><h2><a name="section4">Directory structure</a></h2>
<p>Explain the physical layout (directory structure).</p>


















































</div>
<div id="section5" class="section"><h2><a name="section5">Architecture &amp; Concepts</a></h2>









































<ol class="enumerated">
<li><p>Explain the internal architecture.</p></li>
<li><p>Explain file dependencies, if any.</p></li>
<li><p>Explain package dependencies, if any.</p></li>
<li><p>Explain the internal data structures, if any.</p></li>
<li><p>Explain entity relationships (UML ERD), if any.</p></li>
<li><p>Explain important operation sequences (UML SD), if any.</p></li>
</ol>



























</div>





<div id="section6" class="section"><h2><a name="section6">Related Documents</a></h2>
<ol class="enumerated">
<li><p><i class="term"><a href="cmdr_introduction.html">Cmdr - Introduction to the project</a></i></p></li>
<li><p><i class="term"><a href="cmdr_license.html">Cmdr - License</a></i></p></li>
<li><p><i class="term"><a href="cmdr_changes.html">Cmdr - Log of Changes</a></i></p></li>
<li><p><i class="term"><a href="cmdr_howto_get_sources.html">Cmdr - How To Get The Sources</a></i></p></li>
<li><p><i class="term"><a href="cmdr_howto_installation.html">Cmdr - The Installer's Guide</a></i></p></li>
<li><p><i class="term">Cmdr - The Developer's Guide</i></p></li>
</ol>
</div>
<div id="section7" class="section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>Both the package(s) and this documentation will undoubtedly contain
bugs and other problems.
Please report such at
<a href="https:/core.tcl.tk/akupries/cmdr">Cmdr Tickets</a>.</p>
<p>Please also report any ideas you may have for enhancements of
either package(s) and/or documentation.</p>
</div>







|
|
>
>
>
>
>
>
|
>







 







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






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

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

|
<
<
|
<
|

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

>
>
>
>
>
|









|







112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
...
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
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">
<li class="section"><a href="#toc">Table Of Contents</a></li>
<li class="section"><a href="#section1">Description</a></li>
<li class="section"><a href="#section2">Development Tools</a></li>
<li class="section"><a href="#section3">Demonstration/Example Applications</a></li>
<li class="section"><a href="#section4">Directory structure</a></li>
<li class="section"><a href="#section5">Extended Build Actions</a></li>
<li class="section"><a href="#section6">Architecture &amp; Concepts</a>
<ul>
<li class="subsection"><a href="#subsection1">System Architecture</a></li>
<li class="subsection"><a href="#subsection2">Data structures</a></li>
<li class="subsection"><a href="#subsection3">Operation Sequences</a></li>
</ul>
</li>
<li class="section"><a href="#section7">Related Documents</a></li>
<li class="section"><a href="#section8">Bugs, Ideas, Feedback</a></li>
<li class="section"><a href="#keywords">Keywords</a></li>
<li class="section"><a href="#copyright">Copyright</a></li>
</ul>
</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>
................................................................................
</ol>
<p>first, if that was not done already. Here we assume that the sources
are already available in a directory of your choice, that it is known
how to build and install the project, and that all the necessary
requisites are available.</p>
</div>
<div id="section2" class="section"><h2><a name="section2">Development Tools</a></h2>
<p>Cmdr requires the following tools going beyond those needed
for build and installation.</p>
<dl class="definitions">
<dt><b class="syscmd">dia</b></dt>
<dd><p>Processor for <b class="package">diagram</b>-based figures.
See package <b class="package">tklib</b>.</p></dd>
<dt><b class="syscmd">dtplite</b></dt>
<dd><p>Processor for <b class="package">doctools</b>-based documentation files, i.e. the
&quot;<b class="file">.man</b>&quot; files under &quot;<b class="file">doc/</b>&quot;.
See package <b class="package">tcllib</b>.</p>
<p>This requirement is optional. If a Tcllib providing the package
<b class="package">dtplite</b> is installed then <b class="syscmd">kettle</b> will use the
package in favor of the external application.</p></dd>
</dl>
</div>
<div id="section3" class="section"><h2><a name="section3">Demonstration/Example Applications</a></h2>
<p>Cmdr (currently) does not have demonstrations, nor examples.</p>
</div>
<div id="section4" class="section"><h2><a name="section4">Directory structure</a></h2>
<p>Explain the physical layout (directory structure).</p>
<dl class="definitions">
<dt>&quot;<b class="file">build.tcl</b>&quot;</dt>
<dd><p>The main file of the <b class="syscmd">kettle</b>-based build-system.</p></dd>
<dt>&quot;<b class="file">doc/</b>&quot;</dt>
<dd><p>Main directory for all documentation.</p>
<p>Based on the <b class="package">doctools</b> package and tools provided by
<b class="package">Tcllib</b>.</p></dd>
<dt>&quot;<b class="file">doc/figures/</b>&quot;</dt>
<dd><p>Main directory for all diagrams and figures used by the documentation.</p>
<p>Based on the <b class="package">diagram</b> package and tools provided by
<b class="package">Tklib</b>.</p></dd>
<dt>&quot;<b class="file">embedded/</b>&quot;</dt>
<dd><p>Compiled documentation (manpages and HTML).
Part of the repository for</p>
<ol class="enumerated">
<li><p>easy access from the repository's web interface
(<a href="http://fossil-scm.org/index.html/doc/tip/www/embeddeddoc.wiki">embedded documentation</a>),
and</p></li>
<li><p>quicker installation (no need to compile during the
installation process itself).</p></li>
</ol></dd>
<dt>&quot;<b class="file">tests/</b>&quot;</dt>
<dd><p>Main directory for the test-suite.</p>
<p>Based on the <b class="package">tcltest</b> package distributed with the Tcl
core.</p></dd>
<dt>&quot;<b class="file">actor.tcl</b>&quot;</dt>
<dd><p>== Package <b class="package"><a href="cmdr_actor.html">cmdr::actor</a></b>.</p></dd>
<dt>&quot;<b class="file">cmdr.tcl</b>&quot;</dt>
<dd><p>== Package <b class="package"><a href="cmdr.html">cmdr</a></b>.</p></dd>
<dt>&quot;<b class="file">config.tcl</b>&quot;</dt>
<dd><p>== Package <b class="package"><a href="cmdr_config.html">cmdr::config</a></b>.</p></dd>
<dt>&quot;<b class="file">help.tcl</b>&quot;</dt>
<dd><p>== Package <b class="package"><a href="cmdr_help.html">cmdr::help</a></b>.</p></dd>
<dt>&quot;<b class="file">help_json.tcl</b>&quot;</dt>
<dd><p>== Package <b class="package"><a href="cmdr_help_json.html">cmdr::help::json</a></b>.</p></dd>
<dt>&quot;<b class="file">help_sql.tcl</b>&quot;</dt>
<dd><p>== Package <b class="package"><a href="cmdr_help_sql.html">cmdr::help::sql</a></b>.</p></dd>
<dt>&quot;<b class="file">officer.tcl</b>&quot;</dt>
<dd><p>== Package <b class="package"><a href="cmdr_officer.html">cmdr::officer</a></b>.</p></dd>
<dt>&quot;<b class="file">parameter.tcl</b>&quot;</dt>
<dd><p>== Package <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b>.</p></dd>
<dt>&quot;<b class="file">private.tcl</b>&quot;</dt>
<dd><p>== Package <b class="package"><a href="cmdr_private.html">cmdr::private</a></b>.</p></dd>
<dt>&quot;<b class="file">util.tcl</b>&quot;</dt>
<dd><p>== Package <b class="package"><a href="cmdr_util.html">cmdr::util</a></b>.</p></dd>
<dt>&quot;<b class="file">validate.tcl</b>&quot;</dt>
<dd><p>== Package <b class="package"><a href="cmdr_validate.html">cmdr::validate</a></b>.</p></dd>
<dt>&quot;<b class="file">vcommon.tcl</b>&quot;</dt>
<dd><p>== Package <b class="package"><a href="cmdr_vcommon.html">cmdr::validate::common</a></b>.</p></dd>
</dl>
</div>
<div id="section5" class="section"><h2><a name="section5">Extended Build Actions</a></h2>
<p>Our build-system is based on <b class="syscmd">kettle</b>, as already explained in
the <i class="term"><a href="cmdr_howto_installation.html">Cmdr - The Installer's Guide</a></i>. Beyond the targets useful for
installation it also provides targets aiding developers and
maintainers. These are:</p>
<dl class="definitions">
<dt>Validation of the documentation</dt>
<dd>
<pre class="example">
% /path/to/cmdr/build.tcl validate-doc
</pre>
</dd>
<dt>Regeneration of the embedded documentation</dt>
<dd>
<pre class="example">
% /path/to/cmdr/build.tcl doc
</pre>
</dd>
<dt>Regeneration of the figures for the documentation</dt>
<dd>
<pre class="example">
% /path/to/cmdr/build.tcl figures
</pre>
</dd>
<dt>Execution of the test-suite</dt>
<dd><p>The most basic execution of the test-suite is done with</p>
<pre class="example">
% /path/to/cmdr/build.tcl test
</pre>
<p>When the test-suite reports issues with the framework use of
the more extended form below is indicated, with a <b class="const">&lt;stem&gt;</b> of
your choice. This will generate a number of files whose name starts
with the prefix &quot;<b class="file">&lt;stem&gt;.</b>&quot;. These will contain extended test logs,
details about errors and failures, etc.</p>
<pre class="example">
% /path/to/cmdr/build.tcl test --log &lt;stem&gt;
</pre>
</dd>
</dl>
</div>
<div id="section6" class="section"><h2><a name="section6">Architecture &amp; Concepts</a></h2>
<p>The following sections explain</p>
<ol class="enumerated">
<li><p>the internal architecture and package dependencies.</p></li>


<li><p>the internal data structures.</p></li>

<li><p>important operation sequences (UML SD).</p></li>
</ol>
<div id="subsection1" class="subsection"><h3><a name="subsection1">System Architecture</a></h3>
<p>All packages in the framework belong to one of three layers,
as shown below:</p>
<p><img alt="architecture" src="../../image/architecture.png"></p>
<p>Note that:</p>
<ul class="itemized">
<li><p>Packages marked with a dashed blue border are public in parts,
and private in parts.</p></li>
<li><p>Packages marked with an unbroken blue border are fully public.</p></li>
<li><p>The topmost layer contains only a single package,
<b class="package"><a href="cmdr.html">cmdr</a></b>, which is the trivial entry point to the system.</p></li>
<li><p>The bottom layer contains the mainly internal utility packages.
The exception is <b class="package"><a href="cmdr_vcommon.html">cmdr::validate::common</a></b>, for use in bespoke
validation types. See the document about <i class="term"><a href="cmdr_vtypes.html">Cmdr - Writing custom validation types</a></i>
for details.</p></li>
<li><p>The important pieces implementing the various entities are all
in the middle layer. The relationship of these entities can be seen in
the next diagram:</p>
<p><img alt="erd" src="../../image/erd.png"></p></li>
</ul>
<p>The dependencies between the packages are very
straight-forward, following mostly directly out of the relationships
shown above, plus the few where the utilities are imported. To reduce
the complexity of the diagram below a few direct dependencies on
<b class="package"><a href="cmdr_util.html">cmdr::util</a></b> were omitted where indirectly present through
other dependencies (i.e. through <b class="package"><a href="cmdr_help.html">cmdr::help</a></b>):</p>
<p><img alt="pkg_dependencies" src="../../image/pkg_dependencies.png"></p>
</div>
<div id="subsection2" class="subsection"><h3><a name="subsection2">Data structures</a></h3>
</div>
<div id="subsection3" class="subsection"><h3><a name="subsection3">Operation Sequences</a></h3>
</div>
</div>
<div id="section7" class="section"><h2><a name="section7">Related Documents</a></h2>
<ol class="enumerated">
<li><p><i class="term"><a href="cmdr_introduction.html">Cmdr - Introduction to the project</a></i></p></li>
<li><p><i class="term"><a href="cmdr_license.html">Cmdr - License</a></i></p></li>
<li><p><i class="term"><a href="cmdr_changes.html">Cmdr - Log of Changes</a></i></p></li>
<li><p><i class="term"><a href="cmdr_howto_get_sources.html">Cmdr - How To Get The Sources</a></i></p></li>
<li><p><i class="term"><a href="cmdr_howto_installation.html">Cmdr - The Installer's Guide</a></i></p></li>
<li><p><i class="term">Cmdr - The Developer's Guide</i></p></li>
</ol>
</div>
<div id="section8" class="section"><h2><a name="section8">Bugs, Ideas, Feedback</a></h2>
<p>Both the package(s) and this documentation will undoubtedly contain
bugs and other problems.
Please report such at
<a href="https:/core.tcl.tk/akupries/cmdr">Cmdr Tickets</a>.</p>
<p>Please also report any ideas you may have for enhancements of
either package(s) and/or documentation.</p>
</div>

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

133
134
135
136
137
138
139


























140
141
142
143
144
145
146
covers determining the requested command, mapping argument words to
command parameters, and validating them.
Additional features of the runtime are an integrated help system and
interactive command line shells with basic command and argument
completion.</p>
</div>
<div id="section2" class="section"><h2><a name="section2">System Architecture</a></h2>


























</div>
<div id="section3" class="section"><h2><a name="section3">Related Documents</a></h2>
<ol class="enumerated">
<li><p><i class="term">Cmdr - Introduction to the project</i></p></li>
<li><p><i class="term"><a href="cmdr_license.html">Cmdr - License</a></i></p></li>
<li><p><i class="term"><a href="cmdr_changes.html">Cmdr - Log of Changes</a></i></p></li>
<li><p><i class="term"><a href="cmdr_howto_get_sources.html">Cmdr - How To Get The Sources</a></i></p></li>







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







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
covers determining the requested command, mapping argument words to
command parameters, and validating them.
Additional features of the runtime are an integrated help system and
interactive command line shells with basic command and argument
completion.</p>
</div>
<div id="section2" class="section"><h2><a name="section2">System Architecture</a></h2>
<p>All packages in the framework belong to one of three layers,
as shown below:</p>
<p><img alt="architecture" src="../../image/architecture.png"></p>
<p>Note that:</p>
<ul class="itemized">
<li><p>Packages marked with a dashed blue border are public in parts,
and private in parts.</p></li>
<li><p>Packages marked with an unbroken blue border are fully public.</p></li>
<li><p>The topmost layer contains only a single package,
<b class="package"><a href="cmdr.html">cmdr</a></b>, which is the trivial entry point to the system.</p></li>
<li><p>The bottom layer contains the mainly internal utility packages.
The exception is <b class="package"><a href="cmdr_vcommon.html">cmdr::validate::common</a></b>, for use in bespoke
validation types. See the document about <i class="term"><a href="cmdr_vtypes.html">Cmdr - Writing custom validation types</a></i>
for details.</p></li>
<li><p>The important pieces implementing the various entities are all
in the middle layer. The relationship of these entities can be seen in
the next diagram:</p>
<p><img alt="erd" src="../../image/erd.png"></p></li>
</ul>
<p>The dependencies between the packages are very
straight-forward, following mostly directly out of the relationships
shown above, plus the few where the utilities are imported. To reduce
the complexity of the diagram below a few direct dependencies on
<b class="package"><a href="cmdr_util.html">cmdr::util</a></b> were omitted where indirectly present through
other dependencies (i.e. through <b class="package"><a href="cmdr_help.html">cmdr::help</a></b>):</p>
<p><img alt="pkg_dependencies" src="../../image/pkg_dependencies.png"></p>
</div>
<div id="section3" class="section"><h2><a name="section3">Related Documents</a></h2>
<ol class="enumerated">
<li><p><i class="term">Cmdr - Introduction to the project</i></p></li>
<li><p><i class="term"><a href="cmdr_license.html">Cmdr - License</a></i></p></li>
<li><p><i class="term"><a href="cmdr_changes.html">Cmdr - Log of Changes</a></i></p></li>
<li><p><i class="term"><a href="cmdr_howto_get_sources.html">Cmdr - How To Get The Sources</a></i></p></li>

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

145
146
147
148
149
150
151

152
153
154
155
156
157
158
...
345
346
347
348
349
350
351






352
353
354
355
356
357
358
<li><a href="#15"><b class="cmd">&lt;officer&gt;</b> <b class="method">help</b> <span class="opt">?<i class="arg">prefix</i>?</span></a></li>
<li><a href="#16"><b class="cmd">&lt;officer&gt;</b> <b class="method">known</b></a></li>
<li><a href="#17"><b class="cmd">&lt;officer&gt;</b> <b class="method">learn</b> <i class="arg">script</i></a></li>
<li><a href="#18"><b class="cmd">&lt;officer&gt;</b> <b class="method">lookup</b> <i class="arg">name</i></a></li>
<li><a href="#19"><b class="cmd">&lt;officer&gt;</b> <b class="method">prompt1</b></a></li>
<li><a href="#20"><b class="cmd">&lt;officer&gt;</b> <b class="method">prompt2</b></a></li>
<li><a href="#21"><b class="cmd">&lt;officer&gt;</b> <b class="method">report</b> <i class="arg">what</i> <i class="arg">data</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 implements <em>officers</em>, the inner nodes of command
................................................................................
<p>Its result is the empty string.</p>
<dl class="arguments">
<dt>enum <i class="arg">what</i></dt>
<dd><p>The result code of the command, one of <b class="const">ok</b>, or <b class="const">fail</b>.</p></dd>
<dt>any <i class="arg">data</i></dt>
<dd><p>The result of the command, or an error message in case of failure.</p></dd>
</dl></dd>






</dl>
</div>
<div id="section4" class="section"><h2><a name="section4">Help Information</a></h2>
<p>The help information generated by various places of the framework
is a dictionary containing the following keys:</p>
<dl class="definitions">
<dt>arguments</dt>







>







 







>
>
>
>
>
>







145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
...
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
<li><a href="#15"><b class="cmd">&lt;officer&gt;</b> <b class="method">help</b> <span class="opt">?<i class="arg">prefix</i>?</span></a></li>
<li><a href="#16"><b class="cmd">&lt;officer&gt;</b> <b class="method">known</b></a></li>
<li><a href="#17"><b class="cmd">&lt;officer&gt;</b> <b class="method">learn</b> <i class="arg">script</i></a></li>
<li><a href="#18"><b class="cmd">&lt;officer&gt;</b> <b class="method">lookup</b> <i class="arg">name</i></a></li>
<li><a href="#19"><b class="cmd">&lt;officer&gt;</b> <b class="method">prompt1</b></a></li>
<li><a href="#20"><b class="cmd">&lt;officer&gt;</b> <b class="method">prompt2</b></a></li>
<li><a href="#21"><b class="cmd">&lt;officer&gt;</b> <b class="method">report</b> <i class="arg">what</i> <i class="arg">data</i></a></li>
<li><a href="#22"><b class="cmd">&lt;officer&gt;</b> <b class="method">shell-exit</b> <i class="arg">config</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 implements <em>officers</em>, the inner nodes of command
................................................................................
<p>Its result is the empty string.</p>
<dl class="arguments">
<dt>enum <i class="arg">what</i></dt>
<dd><p>The result code of the command, one of <b class="const">ok</b>, or <b class="const">fail</b>.</p></dd>
<dt>any <i class="arg">data</i></dt>
<dd><p>The result of the command, or an error message in case of failure.</p></dd>
</dl></dd>
<dt><a name="22"><b class="cmd">&lt;officer&gt;</b> <b class="method">shell-exit</b> <i class="arg">config</i></a></dt>
<dd><p>This is the backend for a private ending the main shell,
be it automatically created by the pacge, or by a user.</p>
<p>The argument is the <b class="package"><a href="cmdr_config.html">cmdr::config</a></b>
instance holding the parameters. The method does not
expect any and ignore it.</p></dd>
</dl>
</div>
<div id="section4" class="section"><h2><a name="section4">Help Information</a></h2>
<p>The help information generated by various places of the framework
is a dictionary containing the following keys:</p>
<dl class="definitions">
<dt>arguments</dt>

Added embedded/www/image/architecture.png.

cannot compute difference between binary files

Changes to embedded/www/image/erd.png.

cannot compute difference between binary files

Added embedded/www/image/pkg_dependencies.png.

cannot compute difference between binary files