cmdr: Artifact Content

Artifact 4dc6404de2efb97c7f8e65867edfefefb09cf0e0:

File doc/parts/flow_execution.inc — part of check-in [f121133cf2] at 2014-11-27 21:53:52 on branch trunk — Created a new reserved common block, *config*, in the root-actor. Used to convey the active instance of cmdr::config to parameter callbacks. This different from the definition config for global parameters. For regular parameters it is the same as found as the first argument of the callback. The active instance is needed when a global parameter interacts with regular ones of the active private. (user: andreask size: 6100)
[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 *config*]]

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

Its value is managed by the framework, specifically by privates.

[para] It is a command name, i.e. object handle, to the active
instance of [class cmdr::config]. For regular parameters that is the
same handle given to them in their various callbacks. For a global
parameter however the active config object is what the parameter is
currently used by, whereas the callback argument is where it was
defined in and inherited from.

[para] This distinction is important when the global parameter has to
look at and work with non-global parameters of the active
private. These can only be found in the active context.

[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
                demand. \\
 description \arg{?detail?} & Help text. May be generated. \\
 documented   & True if the parameter is not hidden from help. \\
 forget       & Squash the internal representation. See also
                \cmd{reset}. \\
 generator    & Command prefix to generate a default value (internal
                representation). \\
 hasdefault   & True if a default value was specified. See
                \cmd{default}. \\
 help         & Help structure describing the parameter. \\
 interactive  & True if the parameter allows interactive entry of its
                value. \\
 is \arg{type} & Check if the result of \cmd{type} matches the
                 argument. \\
 isbool       & True if the parametr is a boolean option. \\
 list         & True if the parameter holds a list of values. \\
 lock \arg{reason} & For use in \cmd{when-set} callbacks. Allows
                      parameters to exclude each other's use. \\
 locker       & The \arg{reason} set by \cmd{lock}, if any. \\
 name         & The parameter's name. \\
 options      & List of option flags, if any. \\
 ordered      & True if the parameter is positional. \\
 presence     & True if the parameter is a boolean option not taking
                arguments. \\
 primary \arg {option} & True if the provided flag name is the
                         primary option to be recognized (instead of
                         an alias, or complement). \\
 prompt       & Text used as prompt during interactive entry. \\
 required     & True if the option is mandatory (\const(input) only). \\
 reset        & Squash internal and string representations. See also
                \cmd{forget}. \\
 self         & The parameter's instance command \\
 set \arg{value} & Programmatically set the string representation. \\
 set?     & True if the string representation was set. \\
 string          & Return the string representation, or error. \\
 type         & Parameter type. One of \const{input}, \const{option}, or
                \const{state}. \\
 validator    & Command prefix used to validate the string
                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].