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

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

Overview
Comment:Another placeholder, for the DSL spec, and filled out actor reference
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 67f83ccddb0000d87987191582993a7f2fbcec02
User & Date: andreask 2013-11-05 00:40:43
Context
2013-11-05
05:55
Updated embedded documentation check-in: ca14a9b8c1 user: aku tags: trunk
00:40
Another placeholder, for the DSL spec, and filled out actor reference check-in: 67f83ccddb user: andreask tags: trunk
2013-11-04
22:45
Moved all title setup into definitions. check-in: d1574f44fb user: andreask tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to doc/cmdr_actor.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
[comment {-*- tcl -*- doctools manpage}]
[include parts/definitions.inc]
[manpage_begin [vset PROJECT]_actor [vset MAN_SECTION] [vset VERSION]]
[include parts/module.inc]
[require cmdr::util]
[titledesc [vset TITLE_ACTOR]]
[description]
[include parts/welcome.inc]

This internal package implements the base class containing functionality
common to [package cmdr::officer] and [package cmdr::private].

--TODO-- Describe the common parts (common blocks, super chain, completion support, DSL support)

[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
command 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::actor] [method new]]

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

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::actor] [method create] [arg obj]]

Create a new instance of [class cmdr::actor], named [arg obj].

[list_end][comment definitions]

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

Most of the instance API is not public.

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

[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method completions] [arg parse] [arg cmdlist]]

This method is given the completion state [arg parse] of a partial
command line and a list of completions at the end of the line. It
returns a list of strings which are the valid completions of the whole
line, properly quoted.

[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.

[arg_def list cmdlist]
List of valid completions.
[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method description]]

This accessor method returns the human-readable description of the
actor.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method description:] [arg text]]

This method sets the description of the actor to the [arg text].

[list_begin arguments]
[arg_def string text] The description to remember.
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method dname]]

This accessor method returns the display name of the actor.  This is
the [method name] of the actor prefixed with the contents of the
reserved common block [const *prefix*], set during command line
processing with the actual command path to reach the current actor.

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

This method processes the command-line given as a list of words.  Here
in the bse class it does nothing. It is a virtual method expecting to
be redefined by the derived classes.

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

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

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

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method exists] [arg key]]

This method returns a boolean value indicating whether the common
block named by [arg key] exists in the actor and its parents
([const true]), or not ([const false]).

[list_begin arguments]
[arg_def string key]
The name of the common block to check for.
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method fullname]]

This method returns the full name of the actor.

This is the [method name] of the actor prefixed with the path to it in
the specification, i.e. the names of all actors in the chain of
supers.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method get] [arg key]]

This method returns the content of the common block named by
[arg key]. An error is thrown if the block is not known to the actor,
nor its parents.

[list_begin arguments]
[arg_def string key]
The name of the common block to retrieve.
[list_end][comment {--- arguments --}]

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

This accessor method returns the empty string. It is a virtual method
expecting to be redefined by the derived classes.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method keys]]

This accessor method returns a list of names for the set of common
blocks known to this actor, and all of its parents.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method lappend] [arg key] [arg data]]

This method extends the contents of the common block named
by [arg key] with [arg data].

Conceptually this is a get/lappend/set operation, i.e. while the
existing block content is taken from the actor or its parents, the new
content is always stored in the actor.

[list_begin arguments]
[arg_def string key]  The name of the common block to extend.
[arg_def any    data] The data to add to the block.
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method match] [arg parse] [arg cmdlist]]

This method is given the completion state [arg parse] of a partial
command line and a list of possible completions. The result is a list
of valid completions, filtered against the current word in the command
line.

[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.

[arg_def list cmdlist]
List of possible completions.
[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method name]]

This accessor method returns the name of the actor.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method name:] [arg name]]

This method sets the name of the actor.

[list_begin arguments]
[arg_def string name]
The name to remember.
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method parse-line] [arg line]]

This method is the main helper to begin command completion. Given the
entered command [arg line] it parses it into words and returns a parse
structure as is taken by all other methods taking part in command
completion.

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


[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method root]]

This accessor method returns the root actor instance the actor belongs
to.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method set] [arg key] [arg data]]

This method sets the contents of the common block named by [arg key]
to [arg data]. If the block does not exist it is created. Otherwise
its existing content is written over.

[list_begin arguments]
[arg_def string key]  The name of the common block to write.
[arg_def any    data] The data to store in the block.
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method super]]

This accessor method returns the parent actor instance.  For the root
of the tree this is the empty string.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method super:] [arg obj]]

This method links the actor to its parent actor.

[list_begin arguments]
[arg_def cmdr::actor obj]
The parent actor instance to remember.
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method undocumented]]

This method marks the actor as undocumented.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method unset] [arg key]]

This method removes the common block named by [arg key]
from the actor. Note that definitions in parents are
not touched by this.

[list_begin arguments]
[arg_def string key]  The name of the common block to remove.
[list_end][comment {--- arguments --}]

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


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

[include parts/feedback.inc]
[manpage_end]

Added doc/cmdr_dsl.man.