cmdr
Check-in [eed0701b51]
Not logged in

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

Overview
Comment:Moved old docs into an attic. Completed the todos, except very minor parts. Includes backend example, reserved blocks. Added, completed DSL informaton, mainly where to find them, and how DSL commands map to methods.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:eed0701b51da37c299c8ae694ee64b9865a95638
User & Date: andreask 2013-11-28 22:35:55
Context
2013-11-28
23:59
Link from intro to dsl intro, starting the chain through dsl and flow. check-in: 4e1cb948ac user: andreask tags: trunk
22:35
Moved old docs into an attic. Completed the todos, except very minor parts. Includes backend example, reserved blocks. Added, completed DSL informaton, mainly where to find them, and how DSL commands map to methods. check-in: eed0701b51 user: andreask tags: trunk
19:21
Added docs for the flow at runtime. Documented some of the reserved common blocks. check-in: 6b1f531bbb user: andreask tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Name change from doc/api.txt to doc/attic/api.txt.

Name change from doc/fill_rules.txt to doc/attic/fill_rules.txt.

Name change from doc/notes.txt to doc/attic/notes.txt.

Name change from doc/notes_actions.txt to doc/attic/notes_actions.txt.

Name change from doc/notes_arguments.txt to doc/attic/notes_arguments.txt.

Name change from doc/notes_classes.txt to doc/attic/notes_classes.txt.

Name change from doc/notes_complete.txt to doc/attic/notes_complete.txt.

Name change from doc/notes_help.txt to doc/attic/notes_help.txt.

Name change from doc/notes_parameters.txt to doc/attic/notes_parameters.txt.

Name change from doc/notes_validators.txt to doc/attic/notes_validators.txt.

Name change from doc/spec_value to doc/attic/spec_value.

Changes to doc/cmdr_dev_completion.man.

1
2
3
4
5
6
7
8
9
10
[comment {-*- tcl -*- doctools manpage}]
[include parts/definitions.inc]
[manpage_begin [vset LABEL_COMPLETE] [vset MAN_SECTION] [vset VERSION]]
[include parts/module.inc]
[require cmdr]
[titledesc [vset TITLE_DEV_COMPLETE]]
[description]
[include parts/welcome.inc]

This internal document provides an overview on how the framework


|







1
2
3
4
5
6
7
8
9
10
[comment {-*- tcl -*- doctools manpage}]
[include parts/definitions.inc]
[manpage_begin [vset LABEL_DEV_COMPLETE] [vset MAN_SECTION] [vset VERSION]]
[include parts/module.inc]
[require cmdr]
[titledesc [vset TITLE_DEV_COMPLETE]]
[description]
[include parts/welcome.inc]

This internal document provides an overview on how the framework

Added doc/cmdr_dev_dsl.man.













































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
[comment {-*- tcl -*- doctools manpage}]
[include parts/definitions.inc]
[manpage_begin [vset LABEL_DEV_DSL] [vset MAN_SECTION] [vset VERSION]]
[include parts/module.inc]
[require cmdr]
[titledesc [vset TITLE_DEV_DSL]]
[description]
[include parts/welcome.inc]

This internal document provides an overview on how the framework
implements the specification languages for officers, privates,
and parameters.

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

[section {Officer DSL}]   [include parts/dev_dsl_officer.inc]
[section {Private DSL}]   [include parts/dev_dsl_private.inc]
[section {Parameter DSL}] [include parts/dev_dsl_parameter.inc]

[include parts/feedback.inc]
[manpage_end]

Changes to doc/cmdr_dsl.man.

23
24
25
26
27
28
29




30
31
32
33
34
35
36
[comment ================================================]
[subsection {Basic private commands with inputs}]
[include parts/ex_alias0.inc]

[comment ================================================]
[subsection {Simple command nesting}]
[include parts/ex_alias1.inc]





[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Language Reference}]

With the examples behind us we can now go and specify the entire
specification language. If you have skipped here on first reading,
ignoring the examples, please go back and read them first.







>
>
>
>







23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
[comment ================================================]
[subsection {Basic private commands with inputs}]
[include parts/ex_alias0.inc]

[comment ================================================]
[subsection {Simple command nesting}]
[include parts/ex_alias1.inc]

[comment ================================================]
[subsection {Simple backend}]
[include parts/ex_alias_backend.inc]

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Language Reference}]

With the examples behind us we can now go and specify the entire
specification language. If you have skipped here on first reading,
ignoring the examples, please go back and read them first.

Changes to doc/cmdr_help.man.

46
47
48
49
50
51
52
53

54
55
















56
57
58

[section {Format Notes}]

The format [const by-category] looks for and uses the block
[const *category-order*] for when the user wishes to override the
natural (alphabetical) order of display for the toplevel sections.

[para] This block has to be defined in the root of the command hierarchy.


@EDIT --TODO-- details of the *category-order* definition.

















[include parts/feedback.inc]
[manpage_end]







|
>

<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>



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

[section {Format Notes}]

The format [const by-category] looks for and uses the block
[const *category-order*] for when the user wishes to override the
natural (alphabetical) order of display for the toplevel sections.

[para] This block has to be defined by the user, in the root of
the command hierarchy.


Its value has to be a dictionary mapping from the names of toplevel
sections/categories to an integer number. This is used to change
the order of displaying these sections in the generated text.

[para] Sections with higher/larger numbers are shown first, and
lower/smaller numbers move towards the end. Negative numbers are
possible.

[para] Sections not mentioned in the dictionary are assigned their
natural number. This is calculated by sorting all sections
alphabetically ([option -dict]) ascending and assigning [const 0]
to the first section, [const -10] to the next, and so on.

[para] The generated section/category [const Miscellaneous] is
given the number [const -10000] to force it to the end (bottom)
of the help text, if it was generated.

[include parts/feedback.inc]
[manpage_end]

Changes to doc/cmdr_howto_development.man.

131
132
133
134
135
136
137
138









139









140
141
142
143
144
145
dictionary mapping from toplevel section/category names to an integer
number to override the natural order of displaying these sections in
the help.

[para] The details are explained in section [term {Format Notes}] of
[term [vset TITLE_HELP]].

[def [const *prefix*]]   --@EDIT todo-document--internal









[def [const *in-shell*]] --@EDIT todo-document--public-where?









[list_end]

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[include parts/related.inc]
[include parts/feedback.inc]
[manpage_end]







|
>
>
>
>
>
>
>
>
>
|
>
>
>
>
>
>
>
>
>






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
dictionary mapping from toplevel section/category names to an integer
number to override the natural order of displaying these sections in
the help.

[para] The details are explained in section [term {Format Notes}] of
[term [vset TITLE_HELP]].

[def [const *prefix*]]

Publicly documented for users as read-only this block's value is
managed by the framework.

Set during the [term Dispatch] phase it provides to access to the
actual command name used to invoke a [term private].

[para] See also section [term Execution] of [term [vset TITLE_FLOW]].

[def [const *in-shell*]]

Publicly documented for users as read-only this block's value is
managed by the framework. Not set until the first main- or mini-shell
was active its value is boolean flag indicating if an interactive
shell is currently active ([const true]) or not ([const false], or not
existing).

[para] See also section [term Execution] of [term [vset TITLE_FLOW]].

[list_end]

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[include parts/related.inc]
[include parts/feedback.inc]
[manpage_end]

Changes to doc/cmdr_parameter.man.

572
573
574
575
576
577
578
579
580
581
582
583
584
585
586

An error is thrown if the value could not be determined.
(See method [method undefined!]).

If the value is newly computed the action triggers the
execution of the "when-complete" callback.

[para] --TODO-- describe generation rules and order.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method when-complete]]

This method returns the "when-complete" command prefix callback,
if it was set, and an empty list otherwise.








|







572
573
574
575
576
577
578
579
580
581
582
583
584
585
586

An error is thrown if the value could not be determined.
(See method [method undefined!]).

If the value is newly computed the action triggers the
execution of the "when-complete" callback.

[para][include parts/para_value.inc]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <parameter>] [method when-complete]]

This method returns the "when-complete" command prefix callback,
if it was set, and an empty list otherwise.

Changes to doc/parts/definitions.inc.

7
8
9
10
11
12
13

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

43
44
45
46
47
48
49
[vset TITLE_DEV      "[vset PTITLE] - The Developer's Guide"	 ]

[comment {- Custom documents & titles - - -- --- ----- --------}]
[vset TITLE_MAIN          "[vset PTITLE] - Main package and API"]
[vset TITLE_ACTOR         "[vset PTITLE] - (Internal) Base class for officers and privates"]
[vset TITLE_CONFIG        "[vset PTITLE] - (Partially internal) Collection of parameters for privates"]
[vset TITLE_DEV_COMPLETE  "[vset PTITLE] - Internals of command line completion"]

[vset TITLE_DEV_HF        "[vset PTITLE] - Writing custom help formats"]
[vset TITLE_DEV_VT        "[vset PTITLE] - Writing custom validation types"]
[vset TITLE_DSL           "[vset PTITLE] - Introduction to the Specification Language"]
[vset TITLE_DSL_OFFICER   "[vset PTITLE] - Officer Specification Language"]
[vset TITLE_DSL_PRIVATE   "[vset PTITLE] - Private Specification Language"]
[vset TITLE_DSL_PARAMETER "[vset PTITLE] - Parameter Specification Language"]
[vset TITLE_HELP          "[vset PTITLE] - (Internal) Utilities for help text formatting and setup"]
................................................................................
[vset LABEL_SOURCES       [vset PROJECT]-howto-get-sources]
[vset LABEL_INSTALL       [vset PROJECT]-installation]
[vset LABEL_DEV           [vset PROJECT]_development]

[vset LABEL_MAIN          [vset PROJECT]]
[vset LABEL_ACTOR         [vset PROJECT]::actor]
[vset LABEL_CONFIG        [vset PROJECT]::config]
[vset LABEL_COMPLETE      [vset PROJECT]_dev~completion]

[vset LABEL_HELPFORMATS   [vset PROJECT]-user-helpformats]
[vset LABEL_VTYPES        [vset PROJECT]-user-vtypes]
[vset LABEL_DSL           [vset PROJECT]-spec-dsl]
[vset LABEL_DSL_OFFICER   [vset PROJECT]-spec-dsl-officer]
[vset LABEL_DSL_PARAMETER [vset PROJECT]-spec-dsl-parameter]
[vset LABEL_DSL_PRIVATE   [vset PROJECT]-spec-dsl-private]
[vset LABEL_HELP          [vset PROJECT]::help]







>







 







|
>







7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
..
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
[vset TITLE_DEV      "[vset PTITLE] - The Developer's Guide"	 ]

[comment {- Custom documents & titles - - -- --- ----- --------}]
[vset TITLE_MAIN          "[vset PTITLE] - Main package and API"]
[vset TITLE_ACTOR         "[vset PTITLE] - (Internal) Base class for officers and privates"]
[vset TITLE_CONFIG        "[vset PTITLE] - (Partially internal) Collection of parameters for privates"]
[vset TITLE_DEV_COMPLETE  "[vset PTITLE] - Internals of command line completion"]
[vset TITLE_DEV_DSL       "[vset PTITLE] - Internals of DSL handling"]
[vset TITLE_DEV_HF        "[vset PTITLE] - Writing custom help formats"]
[vset TITLE_DEV_VT        "[vset PTITLE] - Writing custom validation types"]
[vset TITLE_DSL           "[vset PTITLE] - Introduction to the Specification Language"]
[vset TITLE_DSL_OFFICER   "[vset PTITLE] - Officer Specification Language"]
[vset TITLE_DSL_PRIVATE   "[vset PTITLE] - Private Specification Language"]
[vset TITLE_DSL_PARAMETER "[vset PTITLE] - Parameter Specification Language"]
[vset TITLE_HELP          "[vset PTITLE] - (Internal) Utilities for help text formatting and setup"]
................................................................................
[vset LABEL_SOURCES       [vset PROJECT]-howto-get-sources]
[vset LABEL_INSTALL       [vset PROJECT]-installation]
[vset LABEL_DEV           [vset PROJECT]_development]

[vset LABEL_MAIN          [vset PROJECT]]
[vset LABEL_ACTOR         [vset PROJECT]::actor]
[vset LABEL_CONFIG        [vset PROJECT]::config]
[vset LABEL_DEV_COMPLETE  [vset PROJECT]_dev~completion]
[vset LABEL_DEV_DSL       [vset PROJECT]_dev~dsl]
[vset LABEL_HELPFORMATS   [vset PROJECT]-user-helpformats]
[vset LABEL_VTYPES        [vset PROJECT]-user-vtypes]
[vset LABEL_DSL           [vset PROJECT]-spec-dsl]
[vset LABEL_DSL_OFFICER   [vset PROJECT]-spec-dsl-officer]
[vset LABEL_DSL_PARAMETER [vset PROJECT]-spec-dsl-parameter]
[vset LABEL_DSL_PRIVATE   [vset PROJECT]-spec-dsl-private]
[vset LABEL_HELP          [vset PROJECT]::help]

Added doc/parts/dev_dsl_officer.inc.















































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

[para] The officer DSL is implemented in [package cmdr::officer].

[para] While the specification is supplied with the instance
constructor it is not processed immediately, but saved for when it is
actually needed.

[para] The internal instance method [method Setup] is called at all
places requiring access to the specification and processes it (once,
on first call) to provide the necessary in-memory structures.

[para] The DSL commands map to instance methods as shown below:

[list_begin definitions]
[def [cmd alias]]        [method Alias]
[def [cmd common]]       [package cmdr::actor] [method set]
[def [cmd default]]      [method Default]
[def [cmd description]]  [package cmdr::actor] [method description:]
[def [cmd ehandler]]     [method ehandler]
[def [cmd officer]]      [method Officer], forward to [method DefineAction]
[def [cmd private]]      [method Private], forward to [method DefineAction]
[def [cmd undocumented]] [package cmdr::actor] [method undocumented]
[list_end]

Added doc/parts/dev_dsl_parameter.inc.

























































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

[para] The parameter DSL is implemented in [package cmdr::parameter].

[para] The specification is supplied with the instance constructor and
processed immediately. This is different from officers and privates
which defer processing until use. When a parameter is declared the
containing private is in use, and so is the parameter. Thus no delay.

[para] The DSL commands map to instance methods as shown below:

[list_begin definitions]
[def [cmd alias]]         [method Alias]
[def [cmd default]]       [method Default]
[def [cmd defered]]       [method Defered]
[def [cmd generate]]      [method Generate]
[def [cmd immediate]]     [method Immediate]
[def [cmd interact]]      [method Interact]
[def [cmd label]]         [method Label]
[def [cmd list]]          [method List]
[def [cmd no-promotion]]  [method NoPromote]
[def [cmd optional]]      [method Optional]
[def [cmd presence]]      [method Presence]
[def [cmd test]]          [method Test]
[def [cmd undocumented]]  [method Undocumented]
[def [cmd validate]]      [method Validate]
[def [cmd when-complete]] [method WhenComplete]
[def [cmd when-set]]      [method WhenSet]
[list_end]

Added doc/parts/dev_dsl_private.inc.





















































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

[para] The private DSL is only partially implemented in
[package cmdr::private].
Most of the implementation is in [package cmdr::config].

[para] While the specification is supplied with the instance
constructor it is not processed immediately, but saved for when it is
actually needed.

[para] The internal instance method [method Setup] is called at all
places requiring access to the specification and processes it (once,
on first call) to provide the necessary in-memory structures. This
then delegates to the embedded config instance.

[para] The DSL commands map to [emph config] instance methods as shown below:

[list_begin definitions]
[def [cmd description]]  [method Description],  forward to [package cmdr::actor] [method description:]
[def [cmd input]]        [method Input],  forward to [method DefineParameter])
[def [cmd interactive]]  [method Interactive]
[def [cmd option]]       [method Option], forward to [method DefineParameter])
[def [cmd section]]      [method Section]
[def [cmd state]]        [method State],  forward to [method DefineParameter])
[def [cmd undocumented]] [method Undocumented], forward to [package cmdr::actor] [method undocumented]
[def [cmd use]]          [method Use]
[list_end]

Changes to doc/parts/dsl_officer.inc.

147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
(See [term [vset TITLE_DSL_PRIVATE]]), and a command prefix to invoke
when it is chosen.

[para] This command prefix is called with a single argument, the
[package cmdr::config] instance holding the [term parameter]s of the
private.

[comment {
    @EDIT --TODO--(ref:backend-example-code)--
}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd undocumented]]

This command excludes the [term officer] (and its subordinates) from
the generated help.

Note that subordinates reachable through aliases may be included,
under the alias name, if they are not explicitly excluded themselves.

[list_end]







|
|
<











147
148
149
150
151
152
153
154
155

156
157
158
159
160
161
162
163
164
165
166
(See [term [vset TITLE_DSL_PRIVATE]]), and a command prefix to invoke
when it is chosen.

[para] This command prefix is called with a single argument, the
[package cmdr::config] instance holding the [term parameter]s of the
private.

[para] For an example see section [term {Simple backend}]
of [term [vset TITLE_DSL]].


[comment {- - -- --- ----- -------- -------------}]
[call [cmd undocumented]]

This command excludes the [term officer] (and its subordinates) from
the generated help.

Note that subordinates reachable through aliases may be included,
under the alias name, if they are not explicitly excluded themselves.

[list_end]

Changes to doc/parts/dsl_private.inc.

50
51
52
53
54
55
56




57
58
59
60
61
62
63
[para] The section/category is specified as a list of words, each
denoting part of the path to the section. This means that the last
word is the section of the private, with the preceding words the
sections it is nested in.

[para] Multiple calls are possible and accumulate. In other words,
the private can be placed in more than one section/category.





[comment {- - -- --- ----- -------- -------------}]
[call [cmd state] [arg name] [arg help] [arg script]]

This command adds a [term state] (i.e. hidden) [term parameter] to the
[term private], with description [arg help] and its specification
[arg script] of parameter commands as described in







>
>
>
>







50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
[para] The section/category is specified as a list of words, each
denoting part of the path to the section. This means that the last
word is the section of the private, with the preceding words the
sections it is nested in.

[para] Multiple calls are possible and accumulate. In other words,
the private can be placed in more than one section/category.

[para] Note further that [term privates] not put into any section are
automatically placed into a generated section named
[const Miscellaneous].

[comment {- - -- --- ----- -------- -------------}]
[call [cmd state] [arg name] [arg help] [arg script]]

This command adds a [term state] (i.e. hidden) [term parameter] to the
[term private], with description [arg help] and its specification
[arg script] of parameter commands as described in

Added doc/parts/ex_alias_backend.inc.













































































































































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

[para] This example shows a possible implementation of the backend for
the command hierarchies shown in the previous two sections.

It is important to note, I believe, that this backend works for both
command hierarchies, despite the changes to the command names (flat
versus nesting) they do.

[para] Note further that while this example uses a
[cmd {namespace ensemble}] to organize the backend other methods are
possible too, i.e. all the various object systems for Tcl would be
suitable as well.

[para] Lastly, for the sake of brevity this code is incomplete, not
showing any utility commands we may have importet from somewhere else,
nor the low-level workhorse procedures operating on the actual
alias database or whatnot.

[para] [example {
# -*- tcl -*-
# # ## ### ##### ######## ############# #####################

namespace eval ::foo::backend::alias {
    namespace export list add remove
    namespace ensemble create
}

# # ## ### ##### ######## ############# #####################
## Command implementations.

proc ::foo::backend::alias::list {config} {
    set aliases [manager known]

    if {[$config @json]} {
	puts [jmap aliases $aliases]
	return
    }

    [table::do t {Alias Command} {
	foreach {name command} $aliases {
	    $t add $name $command
	}
    } show display]
    return
}

proc ::foo::backend::alias::add {config} {
    set name    [$config @name]
    set command [$config @command]

    manager add $name $command
    say [color green "Successfully aliased '$name' to '$command'"]
    return
}

proc ::foo::backend::alias::remove {config} {
    set name [$config @name]

    if {![manager has $name]} {
	err [color red "Unknown alias '$name'"]
    } else {
	manager remove $name
	say [color green "Successfully unaliased '$name'"]
    }
    return
}

# # ## ### ##### ######## ############# #####################
package provide foo::backend::alias 0
}]

Changes to doc/parts/flow_execution.inc.

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
..
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
[para] The last phase is also the most simple.

[para] It only invokes the Tcl command prefix associated with the
chosen [package cmdr::private] instance, providing it with the
[package cmdr::config] instance holding the parameter information
extracted from the command line as its single argument.

[para] Listing --TODO--backend-example-\ref{ex/execution} is an
example of very simple action implementations, matching to the example
specifications provided in [term [vset TITLE_DSL]]



[para] All parameters declared for a [term private] are made
accessible through individual methods associated with each.

As example, a parameter with system name [var P] is mapped to the
method [method @P], with all instance methods provided by the
[package cmdr::parameter] class accessible as sub-methods.

This general access to all methods may be removed in the future,
restricting actions and callbacks to a safe subset.









































[comment { @EDIT --todo-- figure out if we want this table (safe para methods) in the docs, and where
A first approximation of such a set can be found in the table
below.

[example {


 cmdline      & True if the parameter accessible on command line. \\
 config \arg{...} & Access to the methods of the container the
                    parameter belongs to, and thus all other
                    parameters of the private. \\
 default      & Default value, if specified. See \cmd{hasdefault}. \\
 defered      & True if the internal representation is generated on
................................................................................
                representation and transform it into the internal
                representation. \\
 value        & Return the internal representation. May calculate it
                now from the string representation. \\
 when-complete & Command prefix invoked when the internal representation is set. \\
 when-set     & Command prefix invoked when the string representation is set. \\


}]
}]


[para] Calling [method @P] without arguments is a shorthand for
calling ``@P value'', i.e. the retrieval of the parameter's internal
representation. Which may calculate the value if the call is the first
access and the parameter specified as [term defered].







<
|
<
<
>











>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
<
<

<
>







 







<
<







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
...
110
111
112
113
114
115
116


117
118
119
120
121
122
123
[para] The last phase is also the most simple.

[para] It only invokes the Tcl command prefix associated with the
chosen [package cmdr::private] instance, providing it with the
[package cmdr::config] instance holding the parameter information
extracted from the command line as its single argument.


[para] For an example of very simple action implementations see


section [term {Simple backend}] of [term [vset TITLE_DSL]].

[para] All parameters declared for a [term private] are made
accessible through individual methods associated with each.

As example, a parameter with system name [var P] is mapped to the
method [method @P], with all instance methods provided by the
[package cmdr::parameter] class accessible as sub-methods.

This general access to all methods may be removed in the future,
restricting actions and callbacks to a safe subset.

[para] Another place providing information to actions is the root and
other actors of the command hierarchy itself, via [cmd common] blocks
whose value is managed by the system. Currently we have

[list_begin definitions]
[def [const *in-shell*]]

This block is read-only, and only found in the root actor.

Its value is managed by the framework.

It is a boolean flag indicating if an interactive shell is currently
active ([const true]) or not ([const false]).

This can be used to modulate command messages and other
context-dependent things.

[para] [emph Note] that the block will not exist until after the first
shell was active. This means that a missing [const *in-shell*] block
should be treated like [const false].

[def [const *prefix*]]

This block is read-only and found in the private actor for the
currently executing action command prefix, accessible through the
[package cmdr::config] instance method [method context].

Its value is managed by the framework.

It is a list of the command names used to reach the [term private]
instance.

This is not the logical path in the command hierarchy, but the actual
path taken, which may be through aliases.

[list_end]


[comment {@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

 @EDIT --todo-- figure out if we want this (safe para methods) in the docs/where




 A first approximation of such a set can be found in the table below.

 cmdline      & True if the parameter accessible on command line. \\
 config \arg{...} & Access to the methods of the container the
                    parameter belongs to, and thus all other
                    parameters of the private. \\
 default      & Default value, if specified. See \cmd{hasdefault}. \\
 defered      & True if the internal representation is generated on
................................................................................
                representation and transform it into the internal
                representation. \\
 value        & Return the internal representation. May calculate it
                now from the string representation. \\
 when-complete & Command prefix invoked when the internal representation is set. \\
 when-set     & Command prefix invoked when the string representation is set. \\



}]


[para] Calling [method @P] without arguments is a shorthand for
calling ``@P value'', i.e. the retrieval of the parameter's internal
representation. Which may calculate the value if the call is the first
access and the parameter specified as [term defered].

Added doc/parts/para_value.inc.

























































































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

[para] A parameter asked for its internal representation goes through
the following steps to deliver the value:

[list_begin enumerated]

[enum] If the internal representation is already known, simply deliver
it as is. In other words, the result of the following steps is cached,
and the steps are run only once.

[enum] If the internal representation has been declared as undefined
already, simply error out (again). This is still part of caching the
result generated by the following steps.

[enum] If the parameter has a string representation use the
parameter's [term {validation type}] to convert it to the proper
internal representation, and return it.

[enum] If interactive entry is possible (per the parameter's
specification) perform the interaction. This saves the entered data as
string representation which is then validated as per the previous
step. Aborting the interaction leaves the parameter as undefined
(which is thrown as error).

[enum] If a [cmd generate] callback exists use it to obtain the
internal representation, and return it.

[enum] If a [cmd default] value exists make it the internal
representation, and return it.

[para] Side note: As the parameter DSL only allows the
declaration of one of [cmd default] or [cmd generate] only one of
these steps can trigger.

[enum] If the parameter is [cmd optional] use the empty string as the
internal representation and return it.

[para] [emph Note] that this rule should never trigger as the
parameter DSL enforces that [term optional] parameters always have one
of [cmd default] or [cmd generate].

[enum] Leave the parameter is undefined and fail (throw an error).

[list_end]