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

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. family | ancestors | descendants | both | trunk files | file ages | folders eed0701b51da37c299c8ae694ee64b9865a95638 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

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 

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

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

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

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

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