cmdr
Check-in [df9e5b0c47]
Not logged in

Overview
Comment: DSL docs mostly complete. Still possible to split into multiple documents. Still to do related docs on execution flow. family | ancestors | descendants | both | trunk files | file ages | folders df9e5b0c4702e39ef856419a173ed3958c523864 andreask 2013-11-14 23:37:52
Context
 2013-11-15 00:31 Updated embedded documentation check-in: 9223d03cfb user: aku tags: trunk 2013-11-14 23:37 DSL docs mostly complete. Still possible to split into multiple documents. Still to do related docs on execution flow. check-in: df9e5b0c47 user: andreask tags: trunk 20:06 Outline of the DSL docs, plus fixing up the references to it. check-in: cf3f9e2ff9 user: andreask tags: trunk
Changes

Changes to doc/cmdr_dsl.man.

 26 27 28 29 30 31 32 33 34 35 36 37 38 39   [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. [comment ================================================] [subsection Officers] [include parts/dsl_officer.inc] [comment ================================================] [subsection Privates]   > > > >  26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43   [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. [comment ================================================] [subsection General] [include parts/dsl_general.inc] [comment ================================================] [subsection Officers] [include parts/dsl_officer.inc] [comment ================================================] [subsection Privates] 

Name change from doc/parts/figures/erd.dia to doc/figures/erd.dia.

cannot compute difference between binary files

     > > > > > > > > >  1 2 3 4 5 6 7 8 9   is-a is-a /-1:1-> actor <-1:1-\ / \ officer ---1:(0-n)--> private --1:1-> config --1:(0-n)-> parameter | ^ has has has | | \--/ 1:(0-n) has 

Changes to doc/parts/definitions.inc.

 19 20 21 22 23 24 25 26 27 28  [vset TITLE_PARAMETER "[vset PTITLE] - Command parameters"] [vset TITLE_PRIVATE "[vset PTITLE] - Single command handling, options, and arguments"] [vset TITLE_UTIL "[vset PTITLE] - General Utilities - Internal"] [vset TITLE_VALIDATE "[vset PTITLE] - Standard validation types for parameters"] [vset TITLE_VCOMMON "[vset PTITLE] - Utilities for Validation Types"] [comment {- Miscellanea ............. - - -- --- ----- --------}] [comment { TODO - DSL introduction, examples, reference }]   < < <  19 20 21 22 23 24 25  [vset TITLE_PARAMETER "[vset PTITLE] - Command parameters"] [vset TITLE_PRIVATE "[vset PTITLE] - Single command handling, options, and arguments"] [vset TITLE_UTIL "[vset PTITLE] - General Utilities - Internal"] [vset TITLE_VALIDATE "[vset PTITLE] - Standard validation types for parameters"] [vset TITLE_VCOMMON "[vset PTITLE] - Utilities for Validation Types"] [comment {- Miscellanea ............. - - -- --- ----- --------}] 

     > > > > > > > > > > > > > > > > > > > > > > > > > > > > >  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   [para] The conceptual model underneath the command hierarchy is that of a tree. [para] The inner nodes of the tree represent command ensembles, here called "officer"s. Each officer knows one or more commands, and delegates actual execution to their respective specification, which may be another officer, or a private. [para] The leaf nodes of the tree represent the individual commands, here called "private"s. Each private is responsible for a single action, and knows how to perform it and the parameters used to configure that action at runtime. [para] The same model is graphically presented in the Entity-Relationship-Diagram below. [image erd] [para] The "Actor" in that diagram is the common base class for the ensembles and commands and not directly relevant to users. [para] The "Config" on the other hand is the second interface seen by the user, as the sole argument to the action command prefix of [cmd private] (See section [sectref Officer]). This container holds all the declared parameters of the command the action is invoked for, and provides easy access to them through its methods (see package [package cmdr::config]) at the time of execution. 

Changes to doc/parts/dsl_officer.inc.

 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28  private

     > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >  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   Of the four callbacks supported by parameters the first two, "generate" and "validate" have been described already, in the sections --TODO--\ref{para/reps} about representations and --TODO--\ref{para/vtype} about validation types, respectively. [para] This section explains the commonalities between the callbacks in general, and the last two, for notifications about state changes in detail. [para] All callbacks are treated as command prefixes, not scripts. There are no placeholder substitutions, only arguments added to each command prefix on invokation. This does not harm the generality of the system, as complex scripts can be used via procedures or equivalents (i.e. [cmd apply]). [para] The two callbacks not yet described are the state-change callbacks through which the framework can actively drive parts of the application while processing the command line, whereas normally the application drives access to parameters through their methods. [list_begin definitions] [def "[cmd when-complete] [arg cmdprefix]"] This command declares the state-change callback to invoke when the internal representation of the parameter is generated from the string representation, or the various ways of getting a default. [para] The callback is invoked with two arguments, the [package cmdr::parameter] instance of the parameter which changed, and its internal representation, in this order. [def "[cmd when-set] [arg cmdprefix]"] This command declares the state-change callback to invoke when the string representation of the parameter is set during command line parsing. [para] The callback is invoked with two arguments, the [package cmdr::parameter] instance of the parameter which changed, and its string representation, in this order. [list_end] Due to their nature these callbacks are invoked at runtime during either parsing, completion," or execution. The details are shown in the table below. The specification commands influencing the timing, i.e. forcing the use in a specific phase are shown in the intersection of callback and phase. [example { | Dispatch | Parsing | Completion | Execution --------------------+----------+---------+-------------+----------- validate (default) | * | | | --------------------+----------+---------+-------------+----------- validate (complete) | | * | immediate | defered when-set | | * | | --------------------+----------+---------+-------------+----------- generate | | | immediate | defered validate (validate) | | test | immediate | defered validate (release) | | test | immediate | defered --------------------+----------+---------+-------------+----------- when-complete | | | immediate | 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   [para] The general handling of a parameter is influenced by three commands. [list_begin definitions] [def "[cmd optional]"] This command marks the parameter as optional, i.e. as something the user may skip on the command line, and the application supplying sensible defaults. --TODO--(sectref:para/vtype)-- During parsing the framework will then expend some effort to determine whether an argument word should be assigned to the parameter, or not. [para] This setting is only applicable to "inputs", as "options" are optional by definition, and "state" is hidden. [def "[cmd test]"] This command is related to the above, switching from the standard regime for acceptance based on counting and thresholds to a different one based on validation. The details are explained in section --TODO--(sectref:flow/parsing, flow/optional)--. [def "[cmd undocumented]"] Like "officers" and "privates" parameters can be hidden from the generated help. This is the command for doing so, the same as for the first two. [para] The main use case is the hiding of options giving an application developer access to the internals of their application, something a regular user has no need of, and doesn't have to know about. [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 29 30 31 32 33 34 35 36 37 38 39 40   [para] We have two commands to influence the visible naming of all parameters. [para] As background, all parameters are named for proper identification within the framework and other Tcl code, i.e. the various callbacks, including a "private"s action. This "system name" has to be unique within the "private" a parameter belongs to. Beyond that however the visible parameters have to be identified within help texts, and, in case of "options", for detection during "Parsing". That is the visible naming, seen by a user of any application whose command line processing is based on the [vset PTITLE] framework. [list_begin definitions] [def "[cmd label] [arg text]"] This command declares the visible name, if different from the system name used as the default. Note that in most cases this default is good enough, obviating the need for this command. [para] The only use case seen so far is when two semantically equivalent input and option parameters clash, requiring different internal names due to the requirement for uniqueness, yet also the same visible name and flag within the help to highlight their connection and equivalence. [def "[cmd alias] [arg name]"] For option parameters the "label" command and its default specifies the name of the primary flag recognized during parsing. If that is not enough for a specific option this command allows the specification of any number additional flags to be recognized. [para] Note however that the framework automatically recognizes not only the specified flags, but also all unique prefixes, obviating the need for this command in many cases. [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 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125   [para] An important concept of parameters is something taken up from Tcl itself. The differentation between string and internal representations. Where Tcl uses internal representations to speed up its execution here this separation is that of between the information delivered to the application by a user, and the application-specific data structures behind them. [para] All parameters will have an internal representation. This is usually derived from the string representation provided by the user. The details of that process are explained in section --TODO--(sectref:para/vtype)-- about validation types. However we have cases where the user cannot specify a string representation ("states"), or is allowed to choose not to (optional "inputs", "options"). For these cases three specification commands are made available enabling us to programmatically choose the internal representation. [list_begin definitions] [def "[cmd default] [arg value]"] This command provides a constant value for the internal representation. [def "[cmd generate] [arg cmdprefix]"] This command provides a callback to compute the internal representation at runtime. This is useful if the default is something which cannot be captured as a fixed value, for example a handle to some resource, or a dynamically created object. [para] The command prefix is invoked with a single argument, the [package cmdr::parameter] instance for which to generate the internal representation. [list_end] [para] The commands "default" and "generate" exclude each other, i.e. only of them can be specified. If neither are specified, and we need a default (see the cases above) a default is chosen per the two rules below: [list_begin enumerated] [enum] Use the empty string for a "list" parameter. [enum] Use the default value supplied by the chosen validation type (See section --TODO--(sectref:para/vtype)--). [list_end] [list_begin definitions] [def "[cmd interact] [opt [arg prompt]]"] This command actually does not specify an internal representation, but activates another method for the user to specify a string value for the parameter, outside of the command line. As such it has priority over either "default" and "generate," and can be specified with either. A parameter marked with it will interactively ask the user for a value if none was specified on the command line. [para] The default [arg prompt] is derived from the system name. [list_end] [para] To recapitulate: [list_begin enumerated] [enum] A string representation specified on the command line has the highest priority and goes through the chosen validation type to get the associated internal representation. [enum] If activated via "interact" a small shell is run asking the user for a value (or more, as per "list", see below). The result goes through the chosen validation type to get the associated internal representation. [enum] After that the internal representation is either the declared "default," or the result of invoking the "generate" callback. As internal representations they are [emph not] run through the chosen validation type. [list_end] [list_begin definitions] [def "[cmd list]"] This command is used to mark parameters whose string and thus internal value should be treated as a list. By default all parameters are scalar. [para] This affects the handling of the parameter during parsing, by "interact" above, and the use of the validation type. The last two ask for multiple values, and feed the elements of the string value separately through validation instead of just the string value in one. During parsing treatment of "options" changes from keeping only the last assigned value to accumulation of all values. Similarly a list-"input" takes all remaining words on the command line for itself instead of just the current word. Because of this list-"inputs" are only allowed as the last parameter of a "private." [list_end] [para] The last two specification commands dealing with the representations control when the internal representation is created. [list_begin definitions] [def "[cmd defered]"] This command marks a parameter as defered, with the internal representation computed on first access to its value. This is the default for "state" parameters. [def "[cmd immediate]"] This command marks a parameter as immediate, with the internal representation computed in the "Completion" phase. This is the default for "input" and "option" parameters. [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 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   [para] The answer to the necessity of moving between the string and internal representations described in the previous section are the validation types. Given a string representation they either return the associated internal representation or raise an error, signaling that the input was illegal. This part of their work, the verification of the legality of the input string gave them their name. [comment {--TODO--(textblock shared with cmdr-vtypes.man)}] [para] The general concept of validation types was taken from [package snit], and modified to suit [vset PTITLE]. Where snit's types expect only a single method to validate the input [vset PTITLE] expects all types to support an ensemble of [emph four] methods, one for the basic validation and transformation of the input, another for the release of any internal representation so generated, plus delivery of a default representation and support for command line completion. [list_begin definitions] [def "[cmd validate] [arg cmdprefix]"] This command specifies a validation type for the parameter, in the form of a command prefix. The set of methods this callback has to support, their signatures, etc. are all explained in [term [vset TITLE_DEV_VT]]. This document contains the implementation of the standard boolean validation type as an example as well. [para] Because of the same necessity all parameters must have a validation type assigned to them, and the system will choose which, if the user did not. This choice is made per the six rules below and always returns one of the standard types implemented in package [package cmdr::validate]. [list_begin enumerated] [enum] Use "identity" if a "generate" callback is specified. [enum] Use "boolean" if no "default" is specified and the parameter is an option. [enum] Use "identity" if no "default" is specified and the parameter is an input. [enum] Use "boolean" if the specified "default" value is a Tcl boolean. [enum] Use "integer" if the specified "default" value is a Tcl integer. [enum] Use "identity" as fallback of last resort. [list_end] [def "[cmd presence]"] This command is best discussed as part of the wider area of "boolean" options, i.e. options with validation type "boolean" assigned to them. These have associated special behaviours, both in the handling of the specification, and during parsing. [para] First, normal boolean options. They have automatic aliases declared for them, derived from their primary flag. An option named "foo" will have an alias of "no-foo", and the reverse. During parsing the "foo" and "no-foo" flags have inverse semantics, and both are allowed to occur without option argument following the flag. This is in contrast to all other options which must have such an argument. The parser essentially uses the validation type to decide if the word after the flag is a proper boolean value, or not, i.e. an argument to assign to the parameter, or not. [para] Now "presence" declares a variant of the above, a boolean option without the automatic aliases, and [emph never] taking an argument during parsing. Its mere [emph presence] on the command line will set its parameter. Their default value is consequently fixed to [const false] as well. [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 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 .. 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125   [comment { No tables in doctools, using an example to get a tabular formatting. }] [comment { TODO doctools: table markup }] [comment { TODO doctools: named TOCs for commands - embedded small TOCs}] [comment { Command & Attribute & Input & Option & State & Notes -- & name & -- & -- & -- & Parameter name, unique within the \cprivate. -- & description & -- & -- & -- & Help text. -- & visible & yes & yes & no & Parameter is (in)visible to \parsing. -- & ordered & yes & no & n/a & Access during \parsing is ordered. label & label & \texttt{name} & \texttt{name} & n/a & Name to use in the help, and as primary flag (for an \coption). alias & aliases & n/a & none & n/a & Declare alternate flag for an \coption to be recognized by. Multiple aliases are allowed. optional & optionality & no & n/a (yes) & n/a (no) & Declare \cinput as optional. test & acceptance & threshold & n/a & n/a & Control the matching of words to optional \cinputs (\ra\ref{flow/optional}). undocumented & undocumented & no & no & n/a (yes) & Declare as hidden from help. list & listness & no & no & no & Declare as list-valued. default & default & $*$ & $*$ & $*$ & Set constant default value. Details in section \ref{para/reps}. generate & generate & $*$ & $*$ & $*$ & Set callback returning the default value. Details in section \ref{para/reps}. interact & interact, prompt & $*$ & $*$ & $*$ & Enable the interactive entry of the string value. Default prompt derives from the \texttt{label}. Details in section \ref{para/reps}. defered & defered & no & no & yes & Defer calculation of the internal representation until demanded. immediate & defered & yes & yes & no & Complement of \cdefered. Calculate the internal representation during \completion. presence & presence & no & no & n/a & Declare as boolean \coption without argument. Implies \cdefault and \cvalidate settings. ................................................................................ Set callback executed when the value becomes known. when-set & when-set & none & none & none & Set callback executed when the string value becomes known. }] [example { alias & Declare alternate flag for an option. default & Set constant default value. defered & Defer calculation of the internal representation until demanded. generate & Set callback returning the default value. immediate & Complement of defered. interact ?? & Enable the interactive entry of the string value. label & Name to use in the help, and as primary flag (for an option). list & Declare as list-valued. optional & Declare input as optional. presence & Declare as boolean option without argument. test & Control the matching of words to optional inputs. undocumented & Declare as hidden from help. validate & Declare validation type. when-complete & Set callback executed when the value becomes known. when-set & Set callback executed when the string value becomes known. }] [list_begin definitions] [def "[cmd alias] [arg name]"] [def "[cmd default] [arg value]"] [def "[cmd defered]"] [def "[cmd generate] [arg cmdprefix]"] [def "[cmd immediate]"] [def "[cmd interact] [opt [arg prompt]]"] [def "[cmd label] [arg text]"] [def "[cmd list]"] [def "[cmd optional]"] [def "[cmd presence]"] [def "[cmd test]"] [def "[cmd undocumented]"] [def "[cmd validate] [arg cmdprefix]"] [def "[cmd when-complete] [arg cmdprefix]"] [def "[cmd when-set] [arg cmdprefix]"] [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 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 .. 74 75 76 77 78 79 80   [para] The parameters of private commands are the heart of the system, providing the space needed to transfer the command arguments to the implementations, and having the most attributes controlling their behaviour. [para] This complexity is mitigated strongly by the use of sensible defaults for each of the three possible kinds of parameter, i.e. positional "inputs", named "options", and "state" hidden from the command line. [para] Each kind has its own construction command in the DSL for [sectref Privates] which specifies the common information which cannot have defaults, i.e. [list_begin enumerated] [enum] the name identifying it to the system, [enum] the help text describing it in informal speech, and, of course, [enum] the parameter specification itself, using the commands of this section. [list_end] [comment { No tables in doctools, using an example to get a tabular formatting. }] [comment { TODO doctools: table markup }] [comment { TODO doctools: named TOCs for commands - embedded small TOCs}] [example { alias N Declare alternate flag for an option. default R Set constant default value. defered R Defer calculation of the internal representation until demanded. generate R Set callback returning the default value. immediate R Complement of defered. interact ?? R Enable the interactive entry of the string value. label N Name to use in the help, and as primary flag (for an option). list R Declare as list-valued. optional G Declare input as optional. presence V Declare as boolean option without argument. test G Control the matching of words to optional inputs. undocumented G Declare as hidden from help. validate V Declare validation type. when-complete C Set callback executed when the value becomes known. when-set C Set callback executed when the string value becomes known. }] [para][emph Naming] [include dsl_para_naming.inc] [para][emph {General control}] [include dsl_para_general.inc] [para][emph Representations] [include dsl_para_reps.inc] [para][emph Validation] [include dsl_para_validation.inc] [para][emph Signaling] [include dsl_para_callbacks.inc] [comment { Command & Attribute & Input & Option & State & Notes presence & presence & no & no & n/a & Declare as boolean \coption without argument. Implies \cdefault and \cvalidate settings. ................................................................................ Set callback executed when the value becomes known. when-set & when-set & none & none & none & Set callback executed when the string value becomes known. }] 
  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24   [comment { No tables in doctools, using an example to get a tabular formatting. }] [comment { TODO doctools: table markup }] [comment { TODO doctools: named TOCs for commands - embedded small TOCs}] [example { description Set help text for command. input