cmdr
Check-in [6b1f531bbb]
Not logged in

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

Overview
Comment:Added docs for the flow at runtime. Documented some of the reserved common blocks.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:6b1f531bbbf5590c2f792c7bf3e80fc08b39dadf
User & Date: andreask 2013-11-28 19:21:42
Context
2013-11-28
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
05:39
Another round of tweaking labels for nicer sorting. check-in: df97aa496f user: aku tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to doc/cmdr_dsl.man.

     6      6   [include parts/welcome.inc]
     7      7   
     8      8   This document is for users of the cmdr framework. It introduces the
     9      9   domain-specific language for the specification of command hierarchies
    10     10   with commands and their parameters by way of examples and then
    11     11   provides links to the detailed reference documents.
    12     12   
           13  +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
    13     14   [include parts/related_dsl.inc]
    14     15   
    15     16   [comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
    16     17   [section {Introductory examples}]
    17     18   
    18     19   Instead of immediately diving into the full syntax of the
    19     20   specification language first a few examples to demonstrate the general

Changes to doc/cmdr_dsl_parameter.man.

     9      9   domain-specific language for the specification of parameters in
    10     10   detail.
    11     11   
    12     12   [include parts/related_dsl.inc]
    13     13   
    14     14   [section {Language Reference}]
    15     15   [include parts/dsl_parameter.inc]
           16  +
           17  +[para] Please continue reading with [term [vset TITLE_FLOW]].
    16     18   
    17     19   [include parts/related.inc]
    18     20   [include parts/feedback.inc]
    19     21   [manpage_end]
    20     22   

Added doc/cmdr_flow.man.

            1  +[include parts/definitions.inc]
            2  +[manpage_begin [vset LABEL_FLOW] [vset MAN_SECTION] [vset VERSION]]
            3  +[include parts/module.inc]
            4  +[titledesc [vset TITLE_FLOW]]
            5  +[description]
            6  +[include parts/welcome.inc]
            7  +
            8  +This document is for users of the cmdr framework.
            9  +
           10  +If you have not read [term [vset TITLE_DSL]] and the related documents
           11  +yet, please do so.
           12  +
           13  +The explanations how the framework processes a command line at runtime
           14  +guided by a specified command hierarchy presuppose knowledge of
           15  +command-hierarchy specifications.
           16  +
           17  +[para] A command line is processed in four distinct phases, namely
           18  +[sectref Dispatch], [sectref Parsing], [sectref Completion], and
           19  +[sectref Execution]. Each is explained in more detail in the
           20  +referenced sections.
           21  +
           22  +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
           23  +[include parts/related_dsl.inc]
           24  +
           25  +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
           26  +[section Dispatch]
           27  +[include parts/flow_dispatch.inc]
           28  +
           29  +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
           30  +[section Parsing]
           31  +[include parts/flow_parsing.inc]
           32  +
           33  +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
           34  +[section Completion]
           35  +[include parts/flow_completion.inc]
           36  +
           37  +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
           38  +[section Execution]
           39  +[include parts/flow_execution.inc]
           40  +
           41  +[include parts/related.inc]
           42  +[include parts/feedback.inc]
           43  +[manpage_end]
           44  +

Changes to doc/cmdr_help.man.

    47     47   [section {Format Notes}]
    48     48   
    49     49   The format [const by-category] looks for and uses the block
    50     50   [const *category-order*] for when the user wishes to override the
    51     51   natural (alphabetical) order of display for the toplevel sections.
    52     52   
    53     53   [para] This block has to be defined in the root of the command hierarchy.
           54  +
           55  +@EDIT --TODO-- details of the *category-order* definition.
    54     56   
    55     57   [include parts/feedback.inc]
    56     58   [manpage_end]

Changes to doc/cmdr_howto_development.man.

   102    102   [term [vset TITLE_HELP]]) as well.
   103    103   
   104    104   [comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
   105    105   [section {Command Line Completion}]
   106    106   
   107    107   The document [term [vset TITLE_DEV_COMPLETE]] describes the inner
   108    108   workings of the command line completion provided by the framework.
          109  +
          110  +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
          111  +[section {Common Blocks}]
          112  +
          113  +The framework reserves all blocks whose name begins with a star, i.e
          114  +[const *], for its own use.
          115  +
          116  +Currently the following names are in use:
          117  +
          118  +[list_begin definitions]
          119  +[def [const *all*]]
          120  +Publicly documented for users, this block is expected to contain
          121  +parameter specification commands. These commands are automatically
          122  +added to all privates found in the command hierarchy containing the
          123  +block.
          124  +
          125  +[para] The details are explained by the description of command
          126  +[cmd common] in [term [vset TITLE_DSL_OFFICER]].
          127  +
          128  +[def [const *category-order*]]
          129  +
          130  +Publicly documented for users, this block is expected to contain a
          131  +dictionary mapping from toplevel section/category names to an integer
          132  +number to override the natural order of displaying these sections in
          133  +the help.
          134  +
          135  +[para] The details are explained in section [term {Format Notes}] of
          136  +[term [vset TITLE_HELP]].
          137  +
          138  +[def [const *prefix*]]   --@EDIT todo-document--internal
          139  +[def [const *in-shell*]] --@EDIT todo-document--public-where?
          140  +[list_end]
   109    141   
   110    142   [comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
   111    143   [include parts/related.inc]
   112    144   [include parts/feedback.inc]
   113    145   [manpage_end]

Changes to doc/parts/definitions.inc.

    22     22   [vset TITLE_HELP_SQL      "[vset PTITLE] - Formatting help as series of SQL commands"]
    23     23   [vset TITLE_OFFICER       "[vset PTITLE] - (Internal) Aggregation of multiple commands for dispatch."]
    24     24   [vset TITLE_PARAMETER     "[vset PTITLE] - (Partially internal) Command parameters"]
    25     25   [vset TITLE_PRIVATE       "[vset PTITLE] - (Internal) Single command handling, options, and arguments"]
    26     26   [vset TITLE_UTIL          "[vset PTITLE] - (Internal) General Utilities"]
    27     27   [vset TITLE_VALIDATE      "[vset PTITLE] - Standard validation types for parameters"]
    28     28   [vset TITLE_VCOMMON       "[vset PTITLE] - Utilities for Validation Types"]
           29  +[vset TITLE_FLOW          "[vset PTITLE] - Runtime Processing Flow"]
    29     30   
    30     31   [comment {- Miscellanea ............. - - -- --- ----- --------}]
    31     32   [vset LABEL_INTRO         [vset PROJECT]-introduction]
    32     33   [vset LABEL_LICENSE       [vset PROJECT]-license]
    33     34   [vset LABEL_CHANGES       [vset PROJECT]-changes]
    34     35   [vset LABEL_SOURCES       [vset PROJECT]-howto-get-sources]
    35     36   [vset LABEL_INSTALL       [vset PROJECT]-installation]
................................................................................
    50     51   [vset LABEL_HELP_SQL      [vset PROJECT]::help::sql]
    51     52   [vset LABEL_OFFICER       [vset PROJECT]::officer]
    52     53   [vset LABEL_PARAMETER     [vset PROJECT]::parameter]
    53     54   [vset LABEL_PRIVATE       [vset PROJECT]::private]
    54     55   [vset LABEL_UTIL          [vset PROJECT]::util]
    55     56   [vset LABEL_VALIDATE      [vset PROJECT]::validate]
    56     57   [vset LABEL_VCOMMON       [vset PROJECT]::validate::common]
           58  +[vset LABEL_FLOW          [vset PROJECT]-spec-flow]

Changes to doc/parts/dsl_officer.inc.

   104    104   
   105    105   This is an advanced command which should normally only be specified at
   106    106   the top of the whole hierarchy (from which its value will
   107    107   automatically propagate to all subordinates).
   108    108   
   109    109   [para] At runtime the framework will call the specified command prefix
   110    110   with a single argument, a script whose execution is equivalent to the
   111         -phases "Parsing", "Completion", and "Execution" of the framework, as
   112         -described in --TODO--(sectref:flow/phases)--. The handler [emph must]
   113         -call this script, and can perform any application-specific actions
   114         -before and after.
          111  +phases [term Parsing], [term Completion], and [term Execution] of the
          112  +framework, as described in [term [vset TITLE_FLOW]].
          113  +
          114  +The handler [emph must] call this script, and can perform any
          115  +application-specific actions before and after.
   115    116   
   116    117   [para] This handler's main uses are two-fold:
   117    118   
   118    119   [list_begin enumerated]
   119    120   
   120    121   [enum] Capture and hande application-specific errors which should not
   121    122   abort the application, nor shown as Tcl stacktrace.

Changes to doc/parts/dsl_para_general.inc.

    36     36   [comment {- - -- --- ----- -------- -------------}]
    37     37   [call [cmd test]]
    38     38   
    39     39   This command is related to the above, switching the runtime from the
    40     40   standard regime for acceptance (based on counting and thresholds) to a
    41     41   different regime based on validation.
    42     42   
    43         -The details are explained in --TODO--(sectref:flow/parsing,flow/optional)--.
           43  +[para] More details are explained in section [term Parsing] of
           44  +[term [vset TITLE_FLOW]].
    44     45   
    45     46   [comment {- - -- --- ----- -------- -------------}]
    46     47   [call [cmd undocumented]]
    47     48   
    48     49   This command excludes the [term parameter] from the generated help.
    49     50   
    50     51   [para] Its main use case is the hiding of [term option]s giving an

Added doc/parts/flow_completion.inc.

            1  +
            2  +[para] This phase is reached when all words of the command line have
            3  +been processed and no error was thrown by the preceding phases.
            4  +
            5  +At this point we know the [package cmdr::private] instance to use, and
            6  +its parameters may have a string representation.
            7  +
            8  +[para] All [term immediate]-mode parameters are now given their
            9  +internal representation.
           10  +
           11  +The parameters marked as [term defered] are ignored here and will get
           12  +theirs on first access by the backend.
           13  +
           14  +[para] This completion of parameters is done in their order of
           15  +declaration within the enclosing [term private] command.
           16  +
           17  +Note that when parameters have dependencies between them, i.e. the
           18  +calculation of their internal representation requires the internal
           19  +representation of another parameter, then this order may be violated
           20  +as the requesting parameter triggers completion in the requested one
           21  +on access.
           22  +
           23  +If this is behaviour not wanted then it is the responsibility of the
           24  +user specifying the [term private] to place the parameters into an
           25  +order where all parameters access only previously completed parameters
           26  +during their own completion.

Added doc/parts/flow_dispatch.inc.

            1  +
            2  +[para] The first phase determines the [package cmdr::private] instance
            3  +to use.  To this end it processes words from the command line and uses
            4  +them to navigate the tree of [package cmdr::officer] instances until a
            5  +[term private] is reached.
            6  +
            7  +[para] Each word of the command line is treated as the name of the
            8  +[package cmdr::officer] instance to descend into.
            9  +
           10  +An error will be thrown when encountering a name for which there is no
           11  +known actor (officer or private), and the current [term officer] has
           12  +no [term default] declared for it.
           13  +
           14  +[para] On the converse, when reaching the end of the command line but
           15  +not reaching a [term private] the framework will not throw an
           16  +error. It will start an interactive command line shell instead. This
           17  +[term {main shell}] provides access to exactly the commands of the
           18  +[package cmdr::officer] instance which was reached, plus two
           19  +pseudo-commands to either exit this shell or gain help.
           20  +
           21  +[para] Execution of the command tree specification, i.e. the
           22  +generation of the in-memory command tree and the actor instances bound
           23  +in it, is intertwined with this descent through the command tree.
           24  +
           25  +I.e. instead of processing the entire specification immediately in
           26  +full it is lazily unfolded on demand, ignoring all parts which are not
           27  +needed.
           28  +
           29  +Note that the generated data structures are not destroyed after
           30  +[sectref Execution], but kept, avoiding the need to re-parse the parts
           31  +of the specification already used at least once when an interactive
           32  +command line shell is active.

Added doc/parts/flow_execution.inc.

            1  +
            2  +[para] The last phase is also the most simple.
            3  +
            4  +[para] It only invokes the Tcl command prefix associated with the
            5  +chosen [package cmdr::private] instance, providing it with the
            6  +[package cmdr::config] instance holding the parameter information
            7  +extracted from the command line as its single argument.
            8  +
            9  +[para] Listing --TODO--backend-example-\ref{ex/execution} is an
           10  +example of very simple action implementations, matching to the example
           11  +specifications provided in [term [vset TITLE_DSL]]
           12  +
           13  +
           14  +[para] All parameters declared for a [term private] are made
           15  +accessible through individual methods associated with each.
           16  +
           17  +As example, a parameter with system name [var P] is mapped to the
           18  +method [method @P], with all instance methods provided by the
           19  +[package cmdr::parameter] class accessible as sub-methods.
           20  +
           21  +This general access to all methods may be removed in the future,
           22  +restricting actions and callbacks to a safe subset.
           23  +
           24  +[comment { @EDIT --todo-- figure out if we want this table (safe para methods) in the docs, and where
           25  +A first approximation of such a set can be found in the table
           26  +below.
           27  +
           28  +[example {
           29  +
           30  + cmdline      & True if the parameter accessible on command line. \\
           31  + config \arg{...} & Access to the methods of the container the
           32  +                    parameter belongs to, and thus all other
           33  +                    parameters of the private. \\
           34  + default      & Default value, if specified. See \cmd{hasdefault}. \\
           35  + defered      & True if the internal representation is generated on
           36  +                demand. \\
           37  + description \arg{?detail?} & Help text. May be generated. \\
           38  + documented   & True if the parameter is not hidden from help. \\
           39  + forget       & Squash the internal representation. See also
           40  +                \cmd{reset}. \\
           41  + generator    & Command prefix to generate a default value (internal
           42  +                representation). \\
           43  + hasdefault   & True if a default value was specified. See
           44  +                \cmd{default}. \\
           45  + help         & Help structure describing the parameter. \\
           46  + interactive  & True if the parameter allows interactive entry of its
           47  +                value. \\
           48  + is \arg{type} & Check if the result of \cmd{type} matches the
           49  +                 argument. \\
           50  + isbool       & True if the parametr is a boolean option. \\
           51  + list         & True if the parameter holds a list of values. \\
           52  + lock \arg{reason} & For use in \cmd{when-set} callbacks. Allows
           53  +                      parameters to exclude each other's use. \\
           54  + locker       & The \arg{reason} set by \cmd{lock}, if any. \\
           55  + name         & The parameter's name. \\
           56  + options      & List of option flags, if any. \\
           57  + ordered      & True if the parameter is positional. \\
           58  + presence     & True if the parameter is a boolean option not taking
           59  +                arguments. \\
           60  + primary \arg {option} & True if the provided flag name is the
           61  +                         primary option to be recognized (instead of
           62  +                         an alias, or complement). \\
           63  + prompt       & Text used as prompt during interactive entry. \\
           64  + required     & True if the option is mandatory (\const(input) only). \\
           65  + reset        & Squash internal and string representations. See also
           66  +                \cmd{forget}. \\
           67  + self         & The parameter's instance command \\
           68  + set \arg{value} & Programmatically set the string representation. \\
           69  + set?     & True if the string representation was set. \\
           70  + string          & Return the string representation, or error. \\
           71  + type         & Parameter type. One of \const{input}, \const{option}, or
           72  +                \const{state}. \\
           73  + validator    & Command prefix used to validate the string
           74  +                representation and transform it into the internal
           75  +                representation. \\
           76  + value        & Return the internal representation. May calculate it
           77  +                now from the string representation. \\
           78  + when-complete & Command prefix invoked when the internal representation is set. \\
           79  + when-set     & Command prefix invoked when the string representation is set. \\
           80  +
           81  +
           82  +}]
           83  +}]
           84  +
           85  +
           86  +[para] Calling [method @P] without arguments is a shorthand for
           87  +calling ``@P value'', i.e. the retrieval of the parameter's internal
           88  +representation. Which may calculate the value if the call is the first
           89  +access and the parameter specified as [term defered].

Added doc/parts/flow_parsing.inc.

            1  +
            2  +[vset EXAMPLE_T {Example for Handling optional Inputs by Threshold}]
            3  +
            4  +[para] This is the most complex phase internally, as it has to assign
            5  +the left-over words to the parameters of the chosen
            6  +[package cmdr::private] instance, taking into account the kind of
            7  +parameters, their requiredness, listness, and other attributes.
            8  +
            9  +[para] Generally processing the words from left to right
           10  +[term options] are detected in all positions, through their flags
           11  +(primary, aliases, and all unique prefixes), followed by their
           12  +(string) value to assign.
           13  +
           14  +[para] When a word cannot be the flag for an option the positional
           15  +[term inputs] are considered, in order of their declarations.
           16  +
           17  +For a mandatory [term input] the word is simply assigned as its string
           18  +value and processing continues with the next word, and the next
           19  +[term input], if any.
           20  +
           21  +Operation becomes more complex when the [term input] under
           22  +consideration is [term optional].
           23  +
           24  +Now it is necessary to truly decide if the word should be assigned to
           25  +this [term input] or the following.
           26  +
           27  +[para] The standard method for this decision is to count words and
           28  +compare to the count of mandatory [term inputs] left.
           29  +
           30  +If there are more words available than required to satisfy all
           31  +mandatory [term inputs], then we can and do assign the current word to
           32  +the optional input.
           33  +
           34  +Otherwise the current [term input] is skipped and we consider the
           35  +next.
           36  +
           37  +A set of condensed examples can be found in section
           38  +[sectref [vset EXAMPLE_T]].
           39  +
           40  +They demonstrate how a various numbers of argument words are assigned
           41  +to a specific set of [term inputs], [term optional] and non.
           42  +
           43  +This is called the [term threshold] algorithm.
           44  +
           45  +[para] The non-triviality in the above description is in the phrase to
           46  +[term {count words}].
           47  +
           48  +We cannot simply count all words left on the command line.
           49  +
           50  +To get a proper count we have discard/ignore all words belonging to
           51  +options.
           52  +
           53  +At this point the processor essentially works ahead, processing and
           54  +removing all flags/options and their arguments from the command line
           55  +before performing the comparison and making its decision.
           56  +
           57  +[para] The whole behaviour however can be changed via [cmd test]
           58  +(See section [term {General control}] of [term [vset TITLE_DSL_PARAMETER]]).
           59  +
           60  +Instead of counting words the current word is run through the
           61  +validation type of the current [term input].
           62  +
           63  +On acceptance the value is assigned to it, otherwise that [term input]
           64  +is skipped and the next one put under consideration.
           65  +
           66  +[para] After all of the above the system will process any options
           67  +found after the last word assigned to the last [term input] to
           68  +consider.
           69  +
           70  +[para] Errors are thrown if we either find more words than
           71  +[term inputs] to assign to, or encounter an unknown option flag.
           72  +
           73  +Note that not having enough words for all required [term inputs] is
           74  +not an error unless the framework is not allowed to start an
           75  +interactive shell.
           76  +
           77  +In this [term {mini shell}] all parameters are mapped to shell
           78  +commands taking a single argument, the string value of parameter to
           79  +assign.
           80  +
           81  +Additional five pseudo commands are available to either abort, or
           82  +commit to the action, or gain help ([cmd .ok], [cmd .run],
           83  +[cmd .exit], [cmd .cancel], and [cmd .help]).
           84  +
           85  +[para] Parameters marked as [term list]-valued also trigger special
           86  +behaviours.
           87  +
           88  +For [term options] the assigned values get accumulated instead of each
           89  +new value overwriting the last.
           90  +
           91  +For [term inputs] only one such parameter can exist, and will be the
           92  +last of the [term private].
           93  +
           94  +The processor now takes all remaining words and assign them to this
           95  +parameter.
           96  +
           97  +If the list is also optional then options may be processed ahead or
           98  +not, depending on the chosen decision mode, as described for regular
           99  +inputs above.
          100  +
          101  +[para] Then are the [term boolean] and [term presence] [term options]
          102  +modifying the handling of flags and flag arguments.
          103  +
          104  +The details of this were already explained in section
          105  +[term Validation] of [term [vset TITLE_DSL_PARAMETER]].
          106  +
          107  +
          108  +[subsection [vset EXAMPLE_T]]
          109  +
          110  +The examples in this section demonstrate how the [term threshold]
          111  +algorithm assigns a various number of argument words to a specific set
          112  +of [term inputs], [term optional] and non.
          113  +
          114  +[para][example {
          115  + Parameter    | A? | B | C? | D? | E
          116  + #Required    |   2|   |   1|   1|
          117  +--------------+----+---+----+----+----
          118  + 2 arguments: |    | a |    |    | b
          119  + 3 arguments: | a  | b |    |    | c
          120  + 4 arguments: | a  | b | c  |    | d
          121  + 5 arguments: | a  | b | c  | d  | e
          122  +}]

Changes to doc/parts/related_dsl.inc.

     1      1   [section {Related Specification Documents}]
     2      2   
     3      3   [list_begin enum]
     4      4   [enum] [term [vset TITLE_DSL]]
     5      5   [enum] [term [vset TITLE_DSL_OFFICER]]
     6      6   [enum] [term [vset TITLE_DSL_PRIVATE]]
     7      7   [enum] [term [vset TITLE_DSL_PARAMETER]]
            8  +[enum] [term [vset TITLE_FLOW]]
     8      9   [list_end]