cmdr
Check-in [a1c106f24e]
Not logged in

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

Overview
Comment:Draft work on internal workings of the command line completion.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:a1c106f24e1c3ee4e0d519f7f7fe4e5db0cadf79
User & Date: andreask 2013-11-27 01:15:51
Context
2013-11-27
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
01:15
Draft work on internal workings of the command line completion. check-in: a1c106f24e user: andreask tags: trunk
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
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Added doc/complete.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
[comment {-*- tcl -*- doctools manpage}]
[include parts/definitions.inc]
[manpage_begin [vset PROJECT] [vset MAN_SECTION] [vset VERSION]]
[include parts/module.inc]
[require cmdr]
[titledesc [vset TITLE_COMPLETE]]
[description]
[include parts/welcome.inc]

This internal document describes how the framework performs
command-line completion, in both main and mini shells, plus the
relevant data structures and methods.

[para] For more information about the framework's internals please
read [term [vset TITLE_DEV]].

[comment {************************************************************}]
[section {Main Shell}]

[package cmdr::officer] implements the [term {main shell}].

[para] This shell accepts the names of all sub-ordinate commands known
to the officer as commands.

[para] It may additional accept a hard-wired command [cmd .exit],
depending on the parse state (see flag [const doexit]).


[para] The main shell's repl core calls on the instance method
[method complete] for command-line completion.

[para] This method uses the standard [method parse-line] method of its
own [package cmdr::actor] base-class to get the standard parsing
structure used within the framework and then delegates to the instance
method [method complete-words].

[para] Note: The details of the state structure generated by
[method parse-line] and then taken by [method complete-words] are
explained in section [sectref {Parse State}]. Read it before trying to
follow the rules.

[para] [method complete-words] then applies the following rules:


[list_begin enumerated]

[enum] In case of syntax error return an empty list (no completion).

[enum] For an empty command line return all commands, and all commands
	known to the default subordinate, if any.

[enum] If the [term {current word}] (as per [const at]) is not the
	last word, treat it as the name of the sub-ordinate command
	responsible for handling the remaining words and delegate
	completion to it, advancing the current word as needed.

[para] No completion is done if the word does not yield a command to
	delegate to (unknown or ambigous). If a default command is known
	this case will delegate to that.

[para] When recursing in this way the subordinate command will see
	"[const doexit] == [const false]".

[para] If the subordinate is again an officer it will proceed
	using this same set of rules. A [term private] on the other
	hand has its own set of rules, explained below.

[enum] If the [term {current word}] is the last word on the command
	line then completion is done using the set of commands known
	to the officer and its default sub-ordinate, if any.

	No recursion takes place.
[list_end]

[para] When the recursion described above enters a [term private]
command the recursion ends and all remaining arguments are processed
to determine the set of parameters responsible for completion of the
last word.

[para] This is similar to the argument parsing done ... todo ...


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


[comment {************************************************************}]
[section {Mini Shell}]

[package cmdr::config] implements the [term {mini shell}].

[para] This shell accepts the [term system] names of all parameters
held by the config instance as commands, all taking a single value as
their argument, the string value of the parameter indicated by the
command name itself.

[para] It additional accepts five hard-wired commands to control exit
conditions and access to help.

These commands all start with a [const .] and do not take any
arguments at all. They are, in alphabetical order, [const .cancel],
[const .exit], [const .help] [const .ok], and [const .run].

[para] The mini shell's repl core calls on the instance method
[method complete] for command-line completion.

[para] This method uses the standard [method parse-line] method of the
[package cmdr::actor] base-class of the context (a
[package cmdr::private] instance) to get the standard parsing
structure used within the framework and then delegates to the instance
method [method complete-repl].

[para] [method complete-rel] then applies the following rules:

[list_begin enumerated]

[enum] In case of syntax error return an empty list (no completion).

[enum] For an empty command line return all commands.

[enum] For a partial single word return all matching commands.

[enum] For a command containing more than two words no further
	completion is possible, return an empty list.

[enum] After a full single word delegate completion to the
	[package cmdr::parameter] instance indicated by the
	first word and return its results. The relevant
	method is [method complete-words].

[para] No completion is done if the first word does not yield
        a parameter to delegate to (unknown or ambigous), or
	if it is a presence option, which does not take an argument.

[para] The parameter essentially only extracts the word to complete
	from the state structure and then delegates to the validation
	type (method [method complete]) for actual completion.

[list_end]

[para] Note: The details of the state structure generated by
[method parse-line] and then taken by [method complete-repl] are
explained in section [sectref {Parse State}].

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


[comment {************************************************************}]
[section {Parse State}]

The state structure used by all methods relevant to command line
completion is a dictionary containing the six keys list below.

Its only generator is method [method parse-line] of base-class
[package cmdr::actor], all others parts of the system then only read
and manipulate it.

[list_begin definitions]
[def [const ok]]
A boolean flag. [const true] indicates that the [const line] parsed
sucessfully into words. [const false] indicates a syntax error.

[para] The framework expects basic shell syntax with space-separated
words using single- and double-quotes for words containing whitespace
themselves. Note that complex syntax like variable- and
command-substitutions are not allowed.

[def [const line]]
A copy of the unparsed command line.

[def [const words]]

The command [const line] parsed into the bare words. The data is not
valid if [const ok] indicates a parsing error. This is not a list of
strings, but actually a list of tokens.

[para] Each token is a list of four elements containing, in the order
below:

[list_begin enumerated]
[enum] Type of the token (implicitly specifies found quoting).
[enum] Start index of token in [const line] including quoting.
[enum] End index of token in [const line], including quoting.
[enum] The string value of the token, with escapes fully resolved.
	I.e. the actual word.
[list_end]

[para] Note: If [const line] ended in trailing whitespace the last
element of this list will be an empty string representing the word
started by the user, yet still empty.

[def [const nwords]]
The number of element in [const words]. The data is not valid if
[const ok] indicates a parsing error.

[def [const at]]
The index of the [term {current word}] in [const words] currently
considered by the completion code. Initially [const 0] this advances
as the completion code works through the prefix to determine the
context for the completion of the last word.

[def [const doexit]]
A boolean flag. Indicates if the pseudo-command [cmd .exit] is active
([const true]), or not. Initially [const true].

[list_end]

[include parts/feedback.inc]
[manpage_end]