cmdr
Check-in [65c018615d]
Not logged in
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to tclconference@googlegroups.com
or submit via the online form by Sep 9.

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

Overview
Comment:Filled the officer documentation, and tweaked privates a bit.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:65c018615d1bbdd980b3237fa1c7b80c88878491
User & Date: andreask 2013-11-13 22:44:30
Original Comment: filled the officer documentation, and tweaked privates a bit.
Context
2013-11-13
23:33
Filled in the main package documentation (framework entrypoint) check-in: 5e924d81b9 user: andreask tags: trunk
22:44
Filled the officer documentation, and tweaked privates a bit. check-in: 65c018615d user: andreask tags: trunk
2013-11-05
05:55
Updated embedded documentation check-in: ca14a9b8c1 user: aku tags: trunk
Changes
Hide Diffs Unified Diffs Show Whitespace Changes Patch

Changes to doc/cmdr_officer.man.

















































































































































































































































































































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
[comment {-*- tcl -*- doctools manpage}]
[include parts/definitions.inc]
[manpage_begin [vset PROJECT]_officer [vset MAN_SECTION] [vset VERSION]]
[include parts/module.inc]
[require cmdr::util]
[titledesc [vset TITLE_OFFICER]]
[description]
[include parts/welcome.inc]

This package implements [emph officers], the inner nodes of command
hierarchies.  Each officer can execute many actions, by delegating
them to their sub-ordinate actors, officers and privates.

[para] This class is sub-class of [package cmdr::actor].

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

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

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

[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::officer] [method new] [arg super] [arg name] [arg actions]]

Create an auto-named instance of [class cmdr::officer].
[para] [emph {Not used}].

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::officer] [method create] [arg obj] [arg super] [arg name] [arg actions]]

Create a new instance of [class cmdr::officer], named [arg obj].
Used by the DSL processing parts of the framework to instantiate officers.

[list_begin arguments]
[arg_def object super]
The instance command of the actor (officer actually) which contains the new officer.

[arg_def string name]
The user-visible name of the command.

[arg_def script actions]
The specification of the officer's subordinates.
Please read [term [vset TITLE_DSL]], section --TODO-- for the details.

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

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

The instance API is not public. It is used internally by the framework
during the parsing of a command hierarchy specification to configure
the officer instances, and when processing a command line at runtime
to manage navigation of the hierarchy, word-completion, etc.

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

[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method children]]

This method returns a list containing the instance commands of the
subordinate actors managed by this officer.

See also method [method known] which returns a list of names.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method complete] [arg line]]

This hook-method for the main shell is responsible for computing the
set of completions for the entered [arg line].

[list_begin arguments]
[arg_def string line]
The command line to complete.
[list_end][comment {--- arguments --}]

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

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

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

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

[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method continued] [arg line]]

This hook-method for the main shell is responsible for the detection
of a continuation-line in the entered command [arg line]. It always
returns the boolean value [const false] as the main shell does not
support continuation lines.

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

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

This method returns the instance command of the subordinate to use
during command line processing if the first word does not specify a
known subordinate. An error is thrown if no such default was specified
for this officer. See also method [method hasdefault].

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method dispatch] [arg cmd]]

This hook-method for the main shell is responsible for the recognition
and execution of the supported commands.

[list_begin arguments]
[arg_def string cmd]
The command line containing the command to run.
[list_end][comment {--- arguments --}]

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

This method parses the [arg word]s of the command line, matching them
to the sub-ordinates of the officer. When done without error it
recursively invokes the chosen sub-ordinate to continue processing.

[para] This represents the "Dispatch" phase of command line processing.

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

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

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

[list_begin arguments]
[arg_def cmd-prefix cmd]
A command prefix taking a single argument, a script. The command
prefix has to execute this script in its caller's context. The script
will parse words for the officer,m and perform its action. The command
prefix then has the responsbility to perform any custom cleanup action
required by the application using the framework to prevent leakage of
data between multiple commands executed one after the other (i.e. in
an interactive shell run by the framework).
[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method exit]]

This hook-method for the main shell returns a boolean value indicating
whether the main shell was stopped and has to exit ([const true]), or
not ([const false]).

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method extend] [arg path] [arg arguments] [arg action]]

A convenience method to create a "private" command underneath this
officer, with the command name [arg path] (a list of names). Any
intermediate officers are created as needed. An error is thrown if any
of the intermediates already exist as a (non-extensible) private, or
if the last command already exists.

[para] The arguments after the [arg path] match the constructor of
privates in number and semantics.

[list_begin arguments]
[arg_def script path]
The list of names specifying the route from this officer to the new
private. The last element is the name of the private command, while
the preceding names specify the intermediate officers.

[comment {--- TODO place into text block for inclusion --- see private - constructor}]
[arg_def script arguments]
The specification of the private's parameters.
Please read [term [vset TITLE_DSL]], section --TODO-- for the details.

[arg_def cmd-prefix action]
The command prefix to invoke when this private is selected for
execution.  It takes a single argument, the instance command of the
hidden [package cmdr::config] container holding the private's
parameters. The result of the action, if there is any, is ignored by
the framework.

[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method has] [arg name]]

This method returns a boolean value indicating if this officer has a
sub-ordinate of the given [arg name] ([const true]), or not
([const false]). See also method [method lookup].

[list_begin arguments]
[arg_def string name] The name of the sub-ordinate to look for.
[list_end]

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

This method returns a boolean value indicating if this officer has a
default sub-ordinate ([const true]), or not ([const false]). See also
method [method default].

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

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

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

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


[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method known]]

This method returns a list containing the names of the subordinate
actors managed by this officer.

See also method [method children] which returns a list of instance
commands.

See also method [method lookup] to map names to instance commands.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method learn] [arg script]]

This method takes a regular specification script and uses it to extend
the set of subordinates known to this officer. This is the same type
of script as used during construction, except here we dynamically
extend the officer.

[list_begin arguments]
[arg_def script actions]
The specification of the officer's additional subordinates.
Please read [term [vset TITLE_DSL]], section --TODO-- for the details.

[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method lookup] [arg name]]

This method returns the instance command of the sub-ordinate with the
given [arg name]. An error is thrown if such a sub-ordinate does not
exist. See also method [method has].

[list_begin arguments]
[arg_def string name] The name of the sub-ordinate to look for.
[list_end]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method prompt1]]

This hook-method for the main shell returns the primary prompt string
to use.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method prompt2]]

This hook-method for the main shell returns the secondary prompt
string for use within a continuation. As the main shell does not
support continuation lines it should not be invoked ever, and thus
always throws an error should it be invoked.


[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method report] [arg what] [arg data]]

This hook-method for the main shell is responsible for the reporting
of the command results.

[para] Its result is the empty string.

[list_begin arguments]
[arg_def enum what]
The result code of the command, one of [const ok], or [const fail].

[arg_def any data]
The result of the command, or an error message in case of failure.
[list_end][comment {--- arguments --}]

[list_end][comment definitions]

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

[include parts/feedback.inc]
[manpage_end]

Changes to doc/cmdr_private.man.

4
5
6
7
8
9
10
11
12
13


14
15
16
17
18
19
20
..
34
35
36
37
38
39
40
41
42
43
44
45

46
47
48
49
50
51
52
..
57
58
59
60
61
62
63
64
65
66
67

68
69
70
71
72
73
74
[include parts/module.inc]
[require cmdr::util]
[titledesc [vset TITLE_PRIVATE]]
[description]
[include parts/welcome.inc]

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



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

The class API is not public. It is used internally by the framework
when parsing a command hierarchy specification to create the necessary
private instances.
................................................................................
[call [cmd ::cmdr::private] [method create] [arg obj] [arg super] [arg name] [arg arguments] [arg action]]

Create a new instance of [class cmdr::private], named [arg obj].
Used by the DSL processing parts of the framework to instantiate privates.

[list_begin arguments]
[arg_def object super]
The instance command of the actor (officer actually) which contain the private.

[arg_def string name]
The user-visible name of the command.


[arg_def script arguments]
The specification of the private's parameters.
Please read [term [vset TITLE_DSL]], section --TODO-- for the details.

[arg_def cmd-prefix action]
The command prefix to invoke when this private is selected for
execution.  It takes a single argument, the instance command of the
................................................................................
[list_end][comment arguments]
[list_end][comment definitions]

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

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

parsing a command hierarchy specification to create the necessary
private instances.


[para] It is described here for use by developers maintaining,
modifying and extending the framework itself. A user of the framework
has no need for it, although they have indirect access through
parameters and their container.

[list_begin definitions]







|


>
>







 







|




>







 







<
<
|
|
>







4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
..
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
..
60
61
62
63
64
65
66


67
68
69
70
71
72
73
74
75
76
[include parts/module.inc]
[require cmdr::util]
[titledesc [vset TITLE_PRIVATE]]
[description]
[include parts/welcome.inc]

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

[para] This class is sub-class of [package cmdr::actor].

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

The class API is not public. It is used internally by the framework
when parsing a command hierarchy specification to create the necessary
private instances.
................................................................................
[call [cmd ::cmdr::private] [method create] [arg obj] [arg super] [arg name] [arg arguments] [arg action]]

Create a new instance of [class cmdr::private], named [arg obj].
Used by the DSL processing parts of the framework to instantiate privates.

[list_begin arguments]
[arg_def object super]
The instance command of the actor (officer actually) which contains the new private.

[arg_def string name]
The user-visible name of the command.

[comment {--- TODO place into text block for inclusion --- see officer - extend}]
[arg_def script arguments]
The specification of the private's parameters.
Please read [term [vset TITLE_DSL]], section --TODO-- for the details.

[arg_def cmd-prefix action]
The command prefix to invoke when this private is selected for
execution.  It takes a single argument, the instance command of the
................................................................................
[list_end][comment arguments]
[list_end][comment definitions]

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

The instance API is not public. It is used internally by the framework


during the parsing of a command hierarchy specification to configure
the private instances, and when processing a command line at
runtime to manage word-completion, etc.

[para] It is described here for use by developers maintaining,
modifying and extending the framework itself. A user of the framework
has no need for it, although they have indirect access through
parameters and their container.

[list_begin definitions]