cmdr
Check-in [807f15f3f9]
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:Mostly done documentation of cmdr::private.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 807f15f3f909ce2dcf165dcdf836936db633ce58
User & Date: andreask 2013-10-25 23:24:44
Context
2013-10-29
05:35
Regenerated embedded documentation. check-in: 828eb35b6d user: aku tags: trunk
2013-10-25
23:24
Mostly done documentation of cmdr::private. check-in: 807f15f3f9 user: andreask tags: trunk
18:24
Filled out docs for validation types. check-in: fbca18b815 user: andreask tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Added doc/cmdr_private.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
[comment {-*- tcl -*- doctools manpage}]
[include parts/definitions.inc]
[manpage_begin [vset PROJECT]_private [vset MAN_SECTION] [vset VERSION]]
[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.

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

[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::private] [method new] [arg super] [arg name] [arg arguments] [arg action]]

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

[comment {- - -- --- ----- -------- -------------}]
[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
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]
[list_end][comment definitions]

[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]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd private] [method complete-words] [arg parse]]

This command is given the completion state [arg parse] of a partial
command line and returns a list of strings which are the vaid
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
done without error it invokes the action of the private with the
filled container of parameters.

[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 private] [method ehandler] [arg cmd]]

This method specifies a command prefix to wrap around the parsing of
the command line for the private, 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 private,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 private] [method help] [opt [arg prefix]]]

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

[para] -- TODO -- describe help structure --> custom help formats

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

[comment {- - -- --- ----- -------- -------------}]
[call [cmd private] [method unknown] [arg m] [opt [arg word]...]]

This method overrides the standard behaviour for unknown methods.
Instead of throwing an error they are routed to the hidden container
of the private's parameters, of class [package cmdr::config].

[list_begin arguments]
[arg_def string m]    The name of the unknown method.
[arg_def string word] The argument (one or more) of the unknown method.
[list_end][comment arguments]

[list_end][comment definitions]

[include parts/feedback.inc]
[manpage_end]

Changes to doc/cmdr_util.man.

1
2
3
4
5
6
7
8
9
10
11
12
13
[comment {-*- tcl -*- doctools manpage}]
[include parts/definitions.inc]
[manpage_begin [vset PROJECT]_util [vset MAN_SECTION] [vset VERSION]]
[include parts/module.inc]
[require cmdr::util]
[titledesc {General Utilities - Internal}]
[description]
[include parts/welcome.inc]

This internal package provides a single utility command.

[section API]
[list_begin definitions]




|







1
2
3
4
5
6
7
8
9
10
11
12
13
[comment {-*- tcl -*- doctools manpage}]
[include parts/definitions.inc]
[manpage_begin [vset PROJECT]_util [vset MAN_SECTION] [vset VERSION]]
[include parts/module.inc]
[require cmdr::util]
[titledesc [vset TITLE_UTIL]]
[description]
[include parts/welcome.inc]

This internal package provides a single utility command.

[section API]
[list_begin definitions]

Changes to doc/parts/definitions.inc.

1
2
3
4
5
6
7
8

9






10





[include configuration.inc]
[vset TITLE_INTRO   "[vset PTITLE] - Introduction to the project"]
[vset TITLE_LICENSE "[vset PTITLE] - License"			 ]
[vset TITLE_CHANGES "[vset PTITLE] - Log of Changes"    	 ]
[vset TITLE_SOURCES "[vset PTITLE] - How To Get The Sources"	 ]
[vset TITLE_INSTALL "[vset PTITLE] - The Installer's Guide"	 ]
[vset TITLE_DEV     "[vset PTITLE] - The Developer's Guide"	 ]
[comment {- Custom documents & titles - - -- --- ----- --------}]

[vset TITLE_DEV_VT  "[vset PTITLE] - Writing custom validation types"]






[vset TITLE_VALIDATE {Standard validation types for parameters}]





|
|
|
|
|
|

>
|
>
>
>
>
>
>
|
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
[include configuration.inc]
[vset TITLE_INTRO    "[vset PTITLE] - Introduction to the project"]
[vset TITLE_LICENSE  "[vset PTITLE] - License"			 ]
[vset TITLE_CHANGES  "[vset PTITLE] - Log of Changes"    	 ]
[vset TITLE_SOURCES  "[vset PTITLE] - How To Get The Sources"	 ]
[vset TITLE_INSTALL  "[vset PTITLE] - The Installer's Guide"	 ]
[vset TITLE_DEV      "[vset PTITLE] - The Developer's Guide"	 ]
[comment {- Custom documents & titles - - -- --- ----- --------}]
[vset TITLE_DEV_HF    "[vset PTITLE] - Writing custom help formats"]
[vset TITLE_DEV_VT    "[vset PTITLE] - Writing custom validation types"]
[vset TITLE_ACTOR     "[vset PTITLE] - Base class for officers and privates - Internal"]
[vset TITLE_CONFIG    "[vset PTITLE] - Collection of parameters for privates"]
[vset TITLE_OFFICER   "[vset PTITLE] - Aggregation of multiple commands for dispatch."]
[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_DSL       "[vset PTITLE] - Specification Language"]
[comment {- Miscellanea ............. - - -- --- ----- --------}]
[comment {
	TODO - DSL introduction, examples, reference
}]