cmdr
Check-in [df9e5b0c47]
Not logged in
Bounty program for improvements to Tcl and certain Tcl packages.

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

Overview
Comment:DSL docs mostly complete. Still possible to split into multiple documents. Still to do related docs on execution flow.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:df9e5b0c4702e39ef856419a173ed3958c523864
User & Date: andreask 2013-11-14 23:37:52
Context
2013-11-15
00:31
Updated embedded documentation check-in: 9223d03cfb user: aku tags: trunk
2013-11-14
23:37
DSL docs mostly complete. Still possible to split into multiple documents. Still to do related docs on execution flow. check-in: df9e5b0c47 user: andreask tags: trunk
20:06
Outline of the DSL docs, plus fixing up the references to it. check-in: cf3f9e2ff9 user: andreask tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to doc/cmdr_dsl.man.

26
27
28
29
30
31
32




33
34
35
36
37
38
39

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Language Reference}]

With the examples behind us we can now go and specify the entire
specification language. If you have skipped here on first reading,
ignoring the examples, please go back and read them first.





[comment ================================================]
[subsection Officers]
[include parts/dsl_officer.inc]

[comment ================================================]
[subsection Privates]







>
>
>
>







26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Language Reference}]

With the examples behind us we can now go and specify the entire
specification language. If you have skipped here on first reading,
ignoring the examples, please go back and read them first.

[comment ================================================]
[subsection General]
[include parts/dsl_general.inc]

[comment ================================================]
[subsection Officers]
[include parts/dsl_officer.inc]

[comment ================================================]
[subsection Privates]

Name change from doc/parts/figures/erd.dia to doc/figures/erd.dia.

Added doc/figures/erd.png.

cannot compute difference between binary files

Added doc/figures/erd.txt.



















>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
      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

Changes to doc/parts/definitions.inc.

19
20
21
22
23
24
25
26
27
28
[vset TITLE_PARAMETER "[vset PTITLE] - Command parameters"]
[vset TITLE_PRIVATE   "[vset PTITLE] - Single command handling, options, and arguments"]
[vset TITLE_UTIL      "[vset PTITLE] - General Utilities - Internal"]
[vset TITLE_VALIDATE  "[vset PTITLE] - Standard validation types for parameters"]
[vset TITLE_VCOMMON   "[vset PTITLE] - Utilities for Validation Types"]

[comment {- Miscellanea ............. - - -- --- ----- --------}]
[comment {
	TODO - DSL introduction, examples, reference
}]







<
<
<
19
20
21
22
23
24
25



[vset TITLE_PARAMETER "[vset PTITLE] - Command parameters"]
[vset TITLE_PRIVATE   "[vset PTITLE] - Single command handling, options, and arguments"]
[vset TITLE_UTIL      "[vset PTITLE] - General Utilities - Internal"]
[vset TITLE_VALIDATE  "[vset PTITLE] - Standard validation types for parameters"]
[vset TITLE_VCOMMON   "[vset PTITLE] - Utilities for Validation Types"]

[comment {- Miscellanea ............. - - -- --- ----- --------}]



Added doc/parts/dsl_general.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

[para] The conceptual model underneath the command hierarchy is that
of a tree.

[para] The inner nodes of the tree represent command ensembles, here
called "officer"s. Each officer knows one or more commands, and
delegates actual execution to their respective specification, which
may be another officer, or a private.

[para] The leaf nodes of the tree represent the individual commands,
here called "private"s. Each private is responsible for a single
action, and knows how to perform it and the parameters used to
configure that action at runtime.

[para] The same model is graphically presented in the
Entity-Relationship-Diagram below.

[image erd]

[para] The "Actor" in that diagram is the common base class for the
ensembles and commands and not directly relevant to users.

[para] The "Config" on the other hand is the second interface seen by
the user, as the sole argument to the action command prefix of
[cmd private] (See section [sectref Officer]).

This container holds all the declared parameters of the command the
action is invoked for, and provides easy access to them through its
methods (see package [package cmdr::config]) at the time of execution.

Changes to doc/parts/dsl_officer.inc.

14
15
16
17
18
19
20


















21







































22







23


24


























25



26









27





28
private <name> <script> <cmdprefix>  Declare a simple command  = private
undocumented                         Hide ensemble from help.
}]

[list_begin definitions]
[def "[cmd alias] [arg name] [const =] [arg name']..."]
[def "[cmd alias] [arg name]"]


















[def "[cmd common] [arg name] [arg text]"]







































[def "[cmd default]"]







[def "[cmd description] [arg text]"]


[def "[cmd ehandler] [arg cmdprefix]"]


























[def "[cmd officer] [arg name] [arg script]"]



[def "[cmd private] [arg name] [arg script] [arg cmdprefix]"]









[def "[cmd undocumented]"]





[list_end]







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

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

>
>
>
>
>
>
>

>
>

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

>
>
>

>
>
>
>
>
>
>
>
>

>
>
>
>
>

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
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
private <name> <script> <cmdprefix>  Declare a simple command  = private
undocumented                         Hide ensemble from help.
}]

[list_begin definitions]
[def "[cmd alias] [arg name] [const =] [arg name']..."]
[def "[cmd alias] [arg name]"]

This is a structuring command, for the command hierarchy. Its main
uses are the creation of alternate command names, and of shortcuts
through the command hierarchy. 

[para] For example, stackato's command specification for alias management is
more like [sectref {Basic setup, command nesting}] and uses shortcuts
similar to what is shown in
--TODO--(example ls-alias2)-- to provide the look of a flat namespace.

[para] In the first form the [arg name] is given the explicit path to
the command it is an alias for. In the second form it implicitly
refers to the immediately preceding officer or private.

Note that "immediately" is interpreted at the current level. The
system is [emph not] looking into a nested specification for its last
command.

[def "[cmd common] [arg name] [arg text]"]

This is another structuring command, for structuring the specification
itself instead of the command tree it declares.

[para] It creates named values, usually code blocks, which can be
shared between specifications. Note that while each block is visible
in the current officer and its subordinates, parents and siblings have
no access.

[para] An example of such a block would be

[example {
common *all* {
    option debug {
	Activate client internal tracing.
    } {
	undocumented
	list
	when-complete [lambda {p tags} {
	    foreach t $tags { debug on $t }
	}]
    }
}
}]

This example defines an option to access the subsystem for debug
narative (See package [package Tcllib]). 

The example is actually special, as the block named [const *all*] is
reserved by the framework. This block, if defined, is automatically
included at the front of all "private" specifications, i.e. shared
across all the specified commands underneath this officer. A very
important trait for the option in the example, as it makes the debug
setup available to all commands without having to explicitly include
the block, and possibly forgetting such.

[para] Generally speaking, the framework reserves all blocks whose
name begins with a star, i.e [const *], for its own use.

[def "[cmd default]"]
This command sets up a special kind of alias. The last "private" or
"officer" is set as the default command to use at runtime.

This means that if during "Dispatch" the currently processed word does
not match any of the commands known to this officer this default is
used. If no default is specified an error will be thrown instead.

[def "[cmd description] [arg text]"]
This command declares the help text of the officer.

[def "[cmd ehandler] [arg cmdprefix]"]

This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates).

[para] At runtime the framework will call the specified command prefix
with a single argument, a script whose execution is equivalent to the
phases "Parsing", "Completion", and "Execution" of the framework, as
described in section --TODO--(sectref:flow/phases)--. The handler [emph must]
call this script, and can perform any application-specific actions
before and after.

[para] This handler's main uses are two-fold:
[list_begin enumerated]
[enum] Capture and hande application-specific errors which should not
abort the application, or shown as Tcl stacktrace.

[enum] Cleanup of application-specific transient settings the
parameter callbacks and/or command implementations may have set during
their execution. This is especially important if the interactive
command line shells of the framework are active. Without such a
handler and its bespoke cleanup code transient settings will leak
between multiple commands run from such a shell, something which is
definitely not wanted.
[list_end]

[def "[cmd officer] [arg name] [arg script]"]
This command creates a named subordinate officer with its
specification [arg script] of officer commands as described here.

[def "[cmd private] [arg name] [arg script] [arg cmdprefix]"]
This command creates a named subordinate private with its
specification [arg script] of private commands as described in the
following section, and a command prefix to invoke when it is chosen.

[para] This command prefix is called with a single argument, the
[package cmdr::config] instance holding the parameters of the private.

--TODO--(ref:backend-example-code)--

[def "[cmd undocumented]"]
Use of this command influences the generation of help, excluding all
officers having this marker (and their subordinates) from the
help. Note that subordinates reachable through aliases may be
included, under the alias name, if not explicitly excluded themselves.

[list_end]

Added doc/parts/dsl_para_callbacks.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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

Of the four callbacks supported by parameters the first two,
"generate" and "validate" have been described already, in the sections
--TODO--\ref{para/reps} about representations and
--TODO--\ref{para/vtype} about validation types, respectively.

[para] This section explains the commonalities between the callbacks
in general, and the last two, for notifications about state changes in
detail.

[para] All callbacks are treated as command prefixes, not
scripts.

There are no placeholder substitutions, only arguments added to each
command prefix on invokation. This does not harm the generality of the
system, as complex scripts can be used via procedures or equivalents
(i.e. [cmd apply]).

[para] The two callbacks not yet described are the state-change
callbacks through which the framework can actively drive parts of the
application while processing the command line, whereas normally the
application drives access to parameters through their methods.

[list_begin definitions]
[def "[cmd when-complete] [arg cmdprefix]"]

This command declares the state-change callback to invoke when the
internal representation of the parameter is generated from the string
representation, or the various ways of getting a default.

[para] The callback is invoked with two arguments, the
[package cmdr::parameter] instance of the parameter which changed, and
its internal representation, in this order.

[def "[cmd when-set] [arg cmdprefix]"]

This command declares the state-change callback to invoke when the
string representation of the parameter is set during command line
parsing.

[para] The callback is invoked with two arguments, the
[package cmdr::parameter] instance of the parameter which changed, and
its string representation, in this order.


[list_end]

Due to their nature these callbacks are invoked at runtime during
either parsing, completion," or execution. The details are shown in
the table below. The specification commands influencing the timing,
i.e. forcing the use in a specific phase are shown in the intersection
of callback and phase.

[example {
                    | Dispatch | Parsing | Completion  | Execution
--------------------+----------+---------+-------------+-----------
validate (default)  | *        |         |             |          
--------------------+----------+---------+-------------+-----------
validate (complete) |          | *       | immediate   | defered
when-set            |          | *       |             |          
--------------------+----------+---------+-------------+-----------
generate            |          |         | immediate   | defered
validate (validate) |          | test    | immediate   | defered
validate (release)  |          | test    | immediate   | defered
--------------------+----------+---------+-------------+-----------
when-complete       |          |         | immediate   | defered
--------------------+----------+---------+-------------+-----------
}]

Added doc/parts/dsl_para_general.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

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

[list_begin definitions]
[def "[cmd optional]"]

This command marks the parameter as optional, i.e. as something the
user may skip on the command line, and the application supplying
sensible defaults. --TODO--(sectref:para/vtype)--

During parsing the framework will then expend some effort to determine
whether an argument word should be assigned to the parameter, or not.

[para] This setting is only applicable to "inputs", as "options" are
optional by definition, and "state" is hidden.

[def "[cmd test]"]

This command is related to the above, switching from the standard
regime for acceptance based on counting and thresholds to a different
one based on validation. The details are explained in section
--TODO--(sectref:flow/parsing, flow/optional)--.

[def "[cmd undocumented]"]

Like "officers" and "privates" parameters can be hidden from the
generated help. This is the command for doing so, the same as for the
first two.

[para] The main use case is the hiding of options giving an
application developer access to the internals of their application,
something a regular user has no need of, and doesn't have to know
about.

[list_end]




Added doc/parts/dsl_para_naming.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

[para] We have two commands to influence the visible naming of all
parameters.

[para] As background, all parameters are named for proper
identification within the framework and other Tcl code, i.e. the
various callbacks, including a "private"s action. This "system name"
has to be unique within the "private" a parameter belongs to. Beyond
that however the visible parameters have to be identified within help
texts, and, in case of "options", for detection during "Parsing". That
is the visible naming, seen by a user of any application whose command
line processing is based on the [vset PTITLE] framework.

[list_begin definitions]

[def "[cmd label] [arg text]"]
This command declares the visible name, if different from the system
name used as the default. Note that in most cases this default is good
enough, obviating the need for this command.

[para] The only use case seen so far is when two semantically
equivalent input and option parameters clash, requiring different
internal names due to the requirement for uniqueness, yet also the
same visible name and flag within the help to highlight their
connection and equivalence.

[def "[cmd alias] [arg name]"]
For option parameters the "label" command and its default specifies
the name of the primary flag recognized during parsing. If that is not
enough for a specific option this command allows the specification of
any number additional flags to be recognized.

[para] Note however that the framework automatically recognizes not
only the specified flags, but also all unique prefixes, obviating the
need for this command in many cases.

[list_end]



Added doc/parts/dsl_para_reps.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
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

[para] An important concept of parameters is something taken up from
Tcl itself.

The differentation between string and internal representations.

Where Tcl uses internal representations to speed up its execution here
this separation is that of between the information delivered to the
application by a user, and the application-specific data structures
behind them.

[para] All parameters will have an internal representation.

This is usually derived from the string representation provided by the
user.

The details of that process are explained in section
--TODO--(sectref:para/vtype)--
about validation types.

However we have cases where the user cannot specify a string
representation ("states"), or is allowed to choose not to (optional
"inputs", "options").

For these cases three specification commands are made available
enabling us to programmatically choose the internal representation.

[list_begin definitions]
[def "[cmd default] [arg value]"]

This command provides a constant value for the internal
representation.

[def "[cmd generate] [arg cmdprefix]"]

This command provides a callback to compute the internal
representation at runtime. This is useful if the default is something
which cannot be captured as a fixed value, for example a handle to
some resource, or a dynamically created object.

[para] The command prefix is invoked with a single argument, the
[package cmdr::parameter] instance for which to generate the internal
representation. 

[list_end]

[para] The commands "default" and "generate" exclude each other,
i.e. only of them can be specified.

If neither are specified, and we need a default (see the cases
above) a default is chosen per the two rules below:

[list_begin enumerated]
[enum] Use the empty string for a "list" parameter.

[enum] Use the default value supplied by the chosen validation type
       (See section --TODO--(sectref:para/vtype)--).
[list_end]

[list_begin definitions]
[def "[cmd interact] [opt [arg prompt]]"]
This command actually does not specify an internal representation, but
activates another method for the user to specify a string value for
the parameter, outside of the command line. 

As such it has priority over either "default" and "generate," and can
be specified with either. A parameter marked with it will
interactively ask the user for a value if none was specified on the
command line.

[para] The default [arg prompt] is derived from the system name.

[list_end]

[para] To recapitulate:

[list_begin enumerated]

[enum] A string representation specified on the command line has the
       highest priority and goes through the chosen validation type to
       get the associated internal representation.

[enum] If activated via "interact" a small shell is run asking the
       user for a value (or more, as per "list", see below). The
       result goes through the chosen validation type to get the
       associated internal representation.

[enum] After that the internal representation is either the declared
       "default," or the result of invoking the "generate"
       callback. As internal representations they are [emph not] run
       through the chosen validation type.
[list_end]

[list_begin definitions]
[def "[cmd list]"]
This command is used to mark parameters whose string and thus internal
value should be treated as a list. By default all parameters are scalar.

[para] This affects the handling of the parameter during parsing, by
"interact" above, and the use of the validation type. The last two ask
for multiple values, and feed the elements of the string value
separately through validation instead of just the string value in one.
During parsing treatment of "options" changes from keeping only the
last assigned value to accumulation of all values. Similarly a
list-"input" takes all remaining words on the command line for itself
instead of just the current word. Because of this list-"inputs" are
only allowed as the last parameter of a "private."

[list_end]

[para] The last two specification commands dealing with the
representations control when the internal representation is created.

[list_begin definitions]
[def "[cmd defered]"]
This command marks a parameter as defered, with the internal
representation computed on first access to its value. This is the
default for "state" parameters.

[def "[cmd immediate]"]
This command marks a parameter as immediate, with the internal
representation computed in the "Completion" phase. This is the default
for "input" and "option" parameters.

[list_end]

Added doc/parts/dsl_para_validation.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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

[para] The answer to the necessity of moving between the string and
internal representations described in the previous section are the
validation types. Given a string representation they either return the
associated internal representation or raise an error, signaling that
the input was illegal. This part of their work, the verification of
the legality of the input string gave them their name.


[comment {--TODO--(textblock shared with cmdr-vtypes.man)}]
[para] The general concept of validation types was taken from
[package snit], and modified to suit [vset PTITLE]. Where snit's types
expect only a single method to validate the input [vset PTITLE]
expects all types to support an ensemble of [emph four] methods, one
for the basic validation and transformation of the input, another for
the release of any internal representation so generated, plus delivery
of a default representation and support for command line completion.


[list_begin definitions]
[def "[cmd validate] [arg cmdprefix]"]

This command specifies a validation type for the parameter, in the
form of a command prefix.

The set of methods this callback has to support, their signatures,
etc. are all explained in [term [vset TITLE_DEV_VT]]. This document
contains the implementation of the standard boolean validation type as
an example as well.

[para] Because of the same necessity all parameters must have a
validation type assigned to them, and the system will choose which, if
the user did not. This choice is made per the six rules below and
always returns one of the standard types implemented in package
[package cmdr::validate].

[list_begin enumerated]
[enum] Use "identity" if a "generate" callback is specified.
[enum] Use "boolean"  if no "default" is specified and the parameter is an option.
[enum] Use "identity" if no "default" is specified and the parameter is an input.
[enum] Use "boolean"  if the specified "default" value is a Tcl boolean.
[enum] Use "integer"  if the specified "default" value is a Tcl integer.
[enum] Use "identity" as fallback of last resort.
[list_end]

[def "[cmd presence]"]
This command is best discussed as part of the wider area of "boolean"
options, i.e. options with validation type "boolean" assigned to
them. These have associated special behaviours, both in the handling
of the specification, and during parsing.

[para] First, normal boolean options. They have automatic aliases
declared for them, derived from their primary flag. An option named
"foo" will have an alias of "no-foo", and the reverse. During parsing
the "foo" and "no-foo" flags have inverse semantics, and both are
allowed to occur without option argument following the flag. This is
in contrast to all other options which must have such an argument. The
parser essentially uses the validation type to decide if the word
after the flag is a proper boolean value, or not, i.e. an argument to
assign to the parameter, or not.

[para] Now "presence" declares a variant of the above, a boolean
option without the automatic aliases, and [emph never] taking an
argument during parsing. Its mere [emph presence] on the command line
will set its parameter. Their default value is consequently fixed to
[const false] as well.

[list_end]

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





















[comment { No tables in doctools, using an example to get a tabular formatting. }]
[comment { TODO doctools: table markup }]
[comment { TODO doctools: named TOCs for commands - embedded small TOCs}]


























[comment {


Command & Attribute & Input & Option & State & Notes

-- & name        & --  & --  & --  &
Parameter name, unique within the \cprivate.

-- & description & --  & --  & --  &
Help text.

-- & visible     & yes & yes & no  &
Parameter is (in)visible to \parsing.

-- & ordered     & yes & no  & n/a &
Access during \parsing is ordered.

label <text> & label &
\texttt{name} & \texttt{name} & n/a &
Name to use in the help, and as primary flag (for an \coption).

alias <name> & aliases & n/a & none & n/a &
Declare alternate flag for an \coption to be recognized by.
Multiple aliases are allowed.


optional & optionality & no & n/a (yes) & n/a (no) &
Declare \cinput as optional.

test & acceptance & threshold & n/a & n/a &
Control the matching of words to optional \cinputs
(\ra\ref{flow/optional}).

undocumented & undocumented & no & no & n/a (yes) &
Declare as hidden from help.



list & listness & no  & no  & no &
Declare as list-valued.

default <value> & default & $*$ & $*$ & $*$ &
Set constant default value.
Details in section \ref{para/reps}.

generate <cmdprefix> & generate & $*$ & $*$ & $*$ &
Set callback returning the default value.
Details in section \ref{para/reps}.

interact <?prompt?> & interact, prompt & $*$ & $*$ & $*$ &
Enable the interactive entry of the string value.
Default prompt derives from the \texttt{label}.
Details in section \ref{para/reps}.

defered & defered & no & no & yes &
Defer calculation of the internal representation until demanded.

immediate & defered & yes & yes & no &
Complement of \cdefered.
Calculate the internal representation during \completion.



presence & presence &
no & no & n/a &
Declare as boolean \coption without argument.
Implies \cdefault and \cvalidate settings.
................................................................................
Set callback executed when the value becomes known.

when-set <cmdprefix> & when-set &
none & none & none &
Set callback executed when the string value becomes known.

}]

[example {
alias <name>              & Declare alternate flag for an option.
default <value>           & Set constant default value.
defered                   & Defer calculation of the internal representation until demanded.
generate <cmdprefix>      & Set callback returning the default value.
immediate                 & Complement of defered.
interact ?<prompt>?       & Enable the interactive entry of the string value.
label <text>              & Name to use in the help, and as primary flag (for an option).
list                      & Declare as list-valued.
optional                  & Declare input as optional.
presence                  & Declare as boolean option without argument.
test                      & Control the matching of words to optional inputs.
undocumented              & Declare as hidden from help.
validate <cmdprefix>      & Declare validation type.
when-complete <cmdprefix> & Set callback executed when the value becomes known.
when-set <cmdprefix>      & Set callback executed when the string value becomes known.
}]

[list_begin definitions]
[def "[cmd alias] [arg name]"]
[def "[cmd default] [arg value]"]
[def "[cmd defered]"]
[def "[cmd generate] [arg cmdprefix]"]
[def "[cmd immediate]"]
[def "[cmd interact] [opt [arg prompt]]"]
[def "[cmd label] [arg text]"]
[def "[cmd list]"]
[def "[cmd optional]"]
[def "[cmd presence]"]
[def "[cmd test]"]
[def "[cmd undocumented]"]
[def "[cmd validate] [arg cmdprefix]"]
[def "[cmd when-complete] [arg cmdprefix]"]
[def "[cmd when-set] [arg cmdprefix]"]
[list_end]

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



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






<
<

<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<







 







<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
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
..
74
75
76
77
78
79
80





































[para] The parameters of private commands are the heart of the system,
providing the space needed to transfer the command arguments to the
implementations, and having the most attributes controlling their
behaviour.

[para] This complexity is mitigated strongly by the use of sensible
defaults for each of the three possible kinds of parameter, i.e.
positional "inputs", named "options", and "state" hidden from the
command line.

[para] Each kind has its own construction command in the DSL for
[sectref Privates] which specifies the common information which cannot
have defaults, i.e.

[list_begin enumerated]
[enum] the name identifying it to the system,
[enum] the help text describing it in informal speech, and, of course,
[enum] the parameter specification itself, using the commands of this section.
[list_end]

[comment { No tables in doctools, using an example to get a tabular formatting. }]
[comment { TODO doctools: table markup }]
[comment { TODO doctools: named TOCs for commands - embedded small TOCs}]

[example {
alias <name>              N  Declare alternate flag for an option.
default <value>            R Set constant default value.
defered                    R  Defer calculation of the internal representation until demanded.
generate <cmdprefix>       R  Set callback returning the default value.
immediate                  R  Complement of defered.
interact ?<prompt>?        R  Enable the interactive entry of the string value.
label <text>              N  Name to use in the help, and as primary flag (for an option).
list                       R Declare as list-valued.
optional                  G  Declare input as optional.
presence                   V Declare as boolean option without argument.
test                      G  Control the matching of words to optional inputs.
undocumented              G  Declare as hidden from help.
validate <cmdprefix>       V Declare validation type.
when-complete <cmdprefix> C  Set callback executed when the value becomes known.
when-set <cmdprefix>      C  Set callback executed when the string value becomes known.
}]

[para][emph Naming]            [include dsl_para_naming.inc]
[para][emph {General control}] [include dsl_para_general.inc]
[para][emph Representations]   [include dsl_para_reps.inc]
[para][emph Validation]        [include dsl_para_validation.inc]
[para][emph Signaling]         [include dsl_para_callbacks.inc]


[comment {


Command & Attribute & Input & Option & State & Notes



























































presence & presence &
no & no & n/a &
Declare as boolean \coption without argument.
Implies \cdefault and \cvalidate settings.
................................................................................
Set callback executed when the value becomes known.

when-set <cmdprefix> & when-set &
none & none & none &
Set callback executed when the string value becomes known.

}]




































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






[comment { No tables in doctools, using an example to get a tabular formatting. }]
[comment { TODO doctools: table markup }]
[comment { TODO doctools: named TOCs for commands - embedded small TOCs}]

[example {
description <text>             Set help text for command.
input <name> <help> <script>   Declare a positional parameter.
interactive                    Allow interactive shell.
option <name> <help> <script>  Declare a named parameter.
state <name> <help> <script>   Declare a hidden parameter.
undocumented                   Hide command from help.
use <name>                     Execute the named common block here.
}]

[list_begin definitions]
[def "[cmd description] [arg text]"]



[def "[cmd input] [arg name] [arg help] [arg script]"]




[def "[cmd interactive]"]









[def "[cmd option] [arg name] [arg help] [arg script]"]




[def "[cmd state] [arg name] [arg help] [arg script]"]




[def "[cmd undocumented]"]




[def "[cmd use] [arg name]"]





[list_end]
>
>
>
>
>












|




>
>
>

>
>
>
>

>
>
>
>
>
>
>
>
>

>
>
>
>

>
>
>
>

>
>
>
>

>
>
>
>
>

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

[para] The specification of simple commands, i.e. "privates" is quite
easy, with only seven commands (see the table below). The important
parts are found in the parameter specifications, explained in the next
section.

[comment { No tables in doctools, using an example to get a tabular formatting. }]
[comment { TODO doctools: table markup }]
[comment { TODO doctools: named TOCs for commands - embedded small TOCs}]

[example {
description <text>             Set help text for command.
input <name> <help> <script>   Declare a positional parameter.
interactive                    Allow interactive shell.
option <name> <help> <script>  Declare a named parameter.
state <name> <help> <script>   Declare a hidden parameter.
undocumented                   Hide command from help.
use <name>                     Execute the named "common" block here.
}]

[list_begin definitions]
[def "[cmd description] [arg text]"]
Like the equivalent command for [sectref Officers] this command
declares the help text for the private.

[def "[cmd input] [arg name] [arg help] [arg script]"]
This command adds an "input" (positional) parameter to the "private",
with description [arg help] and its specification [arg script] of
parameter commands as described in the following section.

[def "[cmd interactive]"]
This command influences the runtime. By default the only interactive
command line shells are associated with the officers. Setting this
marker activates such a shell for the private, to be invoked when
required parameters do not have a value.

[para] The global command [cmd {cmdr::config interactive}] in package
[package cmdr::config] can be used to globally activate this type of
shell for all "privates".

[def "[cmd option] [arg name] [arg help] [arg script]"]
This command adds an "option" (named) parameter to the "private", with
description [arg help] and its specification [arg script] of parameter
commands as described in the following section.

[def "[cmd state] [arg name] [arg help] [arg script]"]
This command adds a "state" (hidden) parameter to the "private", with
description [arg help] and its specification [arg script] of parameter
commands as described in the following section.

[def "[cmd undocumented]"]
Like the equivalent command for [sectref Officers] use of this command
influences the generation of help, excluding all privates having this
marker from it.

[def "[cmd use] [arg name]"]
This command is the counterpart to [cmd common] of [sectref Officers].
It inserts the named block into the specification, executing it. As
such it expects the contents to be a script of private commands as
described in this section.

[list_end]