cmdr
Check-in [f7695638e8]
Not logged in

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

Overview
Comment:Added back-references from packages to the devguide for command-line completion.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:f7695638e8793475076778f273ce448939beeb46
User & Date: andreask 2013-11-27 18:25:48
Context
2013-11-27
19:23
Extended information about help formats and how to write them. Documented the DSL "section" command. check-in: f30dbe0098 user: andreask tags: trunk
18:25
Added back-references from packages to the devguide for command-line completion. check-in: f7695638e8 user: andreask tags: trunk
07:55
Continued the dev-guide in general, and completion internals in particular. Added draft diagram code for sequence diagrams. Snarfed from my 2012 kinetcl paper. Has to be modded for the completions. Todo: Document standard help formats, and how to write formats. Todo: Back-reference from the package docs to the completion internals. check-in: 5a6408a944 user: aku tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to doc/cmdr_actor.man.

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
...
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
...
198
199
200
201
202
203
204



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
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]]

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

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








>
>
>
|
|
|
|






<
<







 







>
>
>
|
|
|
<






<
<







 







>
>
>
|
|
|
|





<







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
...
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
...
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
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 part of command line completion. For the details of
its workings please read [term [vset TITLE_DEV_COMPLETE]].

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



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

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

................................................................................
[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 part of command line completion. For the details of
its workings please read [term [vset TITLE_DEV_COMPLETE]].

[para] Given the completion state [arg parse] of a partial command
line and a list of possible completions it returns 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.



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

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

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

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

This method is part of command line completion. For the details of
its workings please read [term [vset TITLE_DEV_COMPLETE]].

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

Changes to doc/cmdr_config.man.

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

This method returns a list of parameter names,
for the parameters which are arguments.

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

This hook-method for the mini-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 <config>] [method complete-repl] [arg parse]]





This internal method is used by the hook-method [method complete]
for the mini-shell, see above. It 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 <config>] [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 <config>] [method continued] [arg line]]

This hook-method for the mini-shell is responsible for the detection
of a continuation-line in the entered command [arg line]. It always







|
>
>
>
>
|
|









>
>
>
>
|
<
|
|
>





<
<





>
>
>
>
|
|






<
<







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

This method returns a list of parameter names,
for the parameters which are arguments.

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

This method is part of the mini shell command line
completion. For the details of its workings please read
[term [vset TITLE_DEV_COMPLETE]].

[para] This hook-method, the entrypoint for the repl
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 <config>] [method complete-repl] [arg parse]]

This internal method is part of the mini shell command line
completion. For the details of its workings please read
[term [vset TITLE_DEV_COMPLETE]].

[para] It is used by the hook-method [method complete] (see above).

Given the completion state [arg parse] of a partial command
line it 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.


[list_end][comment {--- arguments --}]

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

This method is part of the main shell command line
completion. For the details of its workings please read
[term [vset TITLE_DEV_COMPLETE]].

[para] Given the completion state [arg parse] of a partial
command line it 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.


[list_end][comment {--- arguments --}]

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

This hook-method for the mini-shell is responsible for the detection
of a continuation-line in the entered command [arg line]. It always

Changes to doc/cmdr_officer.man.

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







>
>
>
>
|
|






<
<
<







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
[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 part of the main shell command line
completion. For the details of its workings please read
[term [vset TITLE_DEV_COMPLETE]].

[para] Given the completion state [arg parse] of a partial
command line it 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.



[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

Changes to doc/cmdr_parameter.man.

128
129
130
131
132
133
134




135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
[def [const +*]] required, list
[def [const ?*]] optional, list.
[list_end]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [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, for the parameter.

[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 <parameter>] [method config] [arg word...]]

This method either returns the [package cmdr::config] instance
containing the parameter, or the result of applying the words to that config







>
>
>
>
|
|






<







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
[def [const +*]] required, list
[def [const ?*]] optional, list.
[list_end]

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

This method is part of the main shell command line
completion. For the details of its workings please read
[term [vset TITLE_DEV_COMPLETE]].

[para] Given the completion state [arg parse] of a partial
command line it returns a list of strings which are the valid
completions at this point, for the parameter.

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

[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method config] [arg word...]]

This method either returns the [package cmdr::config] instance
containing the parameter, or the result of applying the words to that config

Changes to doc/cmdr_private.man.

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
has no need for it, although they have indirect access through
parameters and their container.

[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd <private>] [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 <private>] [method do] [opt [arg word]...]]

This method parses the [arg word]s of the command line, matching them
to the parameters of the private, be they arguments, or options. When







>
>
>
>
|
|






<
<
<







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
has no need for it, although they have indirect access through
parameters and their container.

[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd <private>] [method complete-words] [arg parse]]

This method is part of the main shell command line
completion. For the details of its workings please read
[term [vset TITLE_DEV_COMPLETE]].

[para] Given the completion state [arg parse] of a partial
command line it 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.



[list_end][comment arguments]

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

This method parses the [arg word]s of the command line, matching them
to the parameters of the private, be they arguments, or options. When

Changes to doc/parts/completion_main.inc.

101
102
103
104
105
106
107
108
[para] Note that the automaton and its results can be precomputed,
this happens in the internal method [method CompletionGraph].

[list_end]

[list_end]

[comment { @ EDIT: --- todo --- sequence diagram main shell completion }]







|
101
102
103
104
105
106
107
108
[para] Note that the automaton and its results can be precomputed,
this happens in the internal method [method CompletionGraph].

[list_end]

[list_end]

[comment { @EDIT: --- todo --- sequence diagram main shell completion }]

Changes to doc/parts/completion_mini.inc.

76
77
78
79
80
81
82
83
84

[para] The hardwired commands fall here implicitly under unknown
parameter.

[list_end]
[list_end]

[comment { @ EDIT: --- todo --- sequence diagram mini shell completion }]








|

76
77
78
79
80
81
82
83
84

[para] The hardwired commands fall here implicitly under unknown
parameter.

[list_end]
[list_end]

[comment { @EDIT: --- todo --- sequence diagram mini shell completion }]