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

Overview
Comment: Outline of the DSL docs, plus fixing up the references to it. family | ancestors | descendants | both | files | file ages | folders cf3f9e2ff9f56566afea324b7c4cdb9a9e3394b5 andreask 2013-11-14 20:06:10 Outline of the DSL docs, plux fixing up the references to it.
Context
 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 17:45 Fixed missing module description (config setting) check-in: 39b36bc1a3 user: andreask tags: trunk
Changes

Changes to doc/cmdr.man.

 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51  [list_begin arguments] [arg_def string name] The user-visible name of the command (hierarchy). [arg_def script actions] The specification of the subordinate commands. On the command line these are the toplevel commands of the application using the hierarchy. Please read [term [vset TITLE_DSL]], section --TODO-- for the details. [list_end][comment arguments] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr] [method interactive] [opt [arg enable]]] This command globally (de)activates the interactive parts of the framework, as per the value of [arg enable].   | > <  35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51  [list_begin arguments] [arg_def string name] The user-visible name of the command (hierarchy). [arg_def script actions] The specification of the subordinate commands. On the command line these are the toplevel commands of the application using the hierarchy. Please read [term [vset TITLE_DSL]], (section "Officers") for the details. [list_end][comment arguments] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr] [method interactive] [opt [arg enable]]] This command globally (de)activates the interactive parts of the framework, as per the value of [arg enable]. 

Changes to doc/cmdr_config.man.

 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56  [arg_def cmdr::config context] The instance command of the [package cmdr::private] instance the configuration will belong to. [arg_def script spec] Tcl-script specifying the parameters in detail. Please read [term [vset TITLE_DSL]], section --TODO-- for the details. [list_end][comment arguments] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::config] [method interactive] [opt [arg enable]]] Class method to change the global interaction default for the   |  42 43 44 45 46 47 48 49 50 51 52 53 54 55 56  [arg_def cmdr::config context] The instance command of the [package cmdr::private] instance the configuration will belong to. [arg_def script spec] Tcl-script specifying the parameters in detail. Please read [term [vset TITLE_DSL]] (section "Parameters") for the details. [list_end][comment arguments] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::config] [method interactive] [opt [arg enable]]] Class method to change the global interaction default for the 

Changes to doc/cmdr_dsl.man.

     > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >  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  [include parts/definitions.inc] [manpage_begin [vset PROJECT]_dsl [vset MAN_SECTION] [vset VERSION]] [include parts/module.inc] [titledesc [vset TITLE_DSL]] [description] [include parts/welcome.inc] This document is for users of the cmdr framework. It describes the domain-specific language for the specification of command hierarchies with commands and their parameters (options, and inputs). [comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@] [section {Introductory examples}] Instead of immediately diving into the full syntax of the specification language first a few examples to demonstrate the general look and feel, plus basic features. [comment ================================================] [subsection {Basic setup, private with inputs}] [include parts/ex_alias0.inc] [comment ================================================] [subsection {Basic setup, 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. [comment ================================================] [subsection Officers] [include parts/dsl_officer.inc] [comment ================================================] [subsection Privates] [include parts/dsl_private.inc] [comment ================================================] [subsection Parameters] [include parts/dsl_parameter.inc] [include parts/related.inc] [include parts/feedback.inc] [manpage_end] 

Changes to doc/cmdr_introduction.man.

 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23  [include parts/definitions.inc] [manpage_begin [vset PROJECT]_introduction [vset MAN_SECTION] [vset VERSION]] [include parts/module.inc] [titledesc [vset TITLE_INTRO]] [description] [include parts/welcome.inc] [comment { -- @EDIT Please edit to suit -- [para] What are your goals which drove you here ? [list_begin enumerated][comment {--------------------}] [enum] [list_end][comment {---------------------------------}] }] [section {System Architecture}] [comment { -- @EDIT Please edit to suit -- }] [include parts/related.inc] [include parts/feedback.inc] [manpage_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  [include parts/definitions.inc] [manpage_begin [vset PROJECT]_introduction [vset MAN_SECTION] [vset VERSION]] [include parts/module.inc] [titledesc [vset TITLE_INTRO]] [description] [include parts/welcome.inc] The cmdr framework is a set of 12 related Tcl packages for the easy specification of the interfaces of command line applications. This means the declaration of the set of commands to be provided by an application, and their parameters, be they options or positional inputs. At runtime the internals of the framework, guided by the chosen specification, handle the bulk of processing [var \$::argv]. This covers determining the requested command, mapping argument words to command parameters, and validating them. Additional features of the runtime are an integrated help system and interactive command line shells with basic command and argument completion. [section {System Architecture}] [comment { -- @EDIT Please edit to suit -- }] [include parts/related.inc] [include parts/feedback.inc] [manpage_end]  Changes to doc/cmdr_officer.man.  42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 ... 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 ... 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266  The instance command of the actor (officer actually) which contains the new officer. [arg_def string name] The user-visible name of the command. [arg_def script actions] The specification of the officer's subordinates. Please read [term [vset TITLE_DSL]], section --TODO-- for the details. [list_end][comment arguments] [list_end][comment definitions] [comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@] [section {Instance API}] ................................................................................ The list of names specifying the route from this officer to the new private. The last element is the name of the private command, while the preceding names specify the intermediate officers. [comment {--- TODO place into text block for inclusion --- see private - constructor}] [arg_def script arguments] The specification of the private's parameters. Please read [term [vset TITLE_DSL]], section --TODO-- for the details. [arg_def cmd-prefix action] The command prefix to invoke when this private is selected for execution. It takes a single argument, the instance command of the hidden [package cmdr::config] container holding the private's parameters. The result of the action, if there is any, is ignored by the framework. ................................................................................ the set of subordinates known to this officer. This is the same type of script as used during construction, except here we dynamically extend the officer. [list_begin arguments] [arg_def script actions] The specification of the officer's additional subordinates. Please read [term [vset TITLE_DSL]], section --TODO-- for the details. [list_end][comment arguments] [comment {- - -- --- ----- -------- -------------}] [call [cmd ] [method lookup] [arg name]] This method returns the instance command of the sub-ordinate with the   | | |  42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 ... 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 ... 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266  The instance command of the actor (officer actually) which contains the new officer. [arg_def string name] The user-visible name of the command. [arg_def script actions] The specification of the officer's subordinates. Please read [term [vset TITLE_DSL]] (section "Officers") for the details. [list_end][comment arguments] [list_end][comment definitions] [comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@] [section {Instance API}] ................................................................................ The list of names specifying the route from this officer to the new private. The last element is the name of the private command, while the preceding names specify the intermediate officers. [comment {--- TODO place into text block for inclusion --- see private - constructor}] [arg_def script arguments] The specification of the private's parameters. Please read [term [vset TITLE_DSL]] (section "Parameters") for the details. [arg_def cmd-prefix action] The command prefix to invoke when this private is selected for execution. It takes a single argument, the instance command of the hidden [package cmdr::config] container holding the private's parameters. The result of the action, if there is any, is ignored by the framework. ................................................................................ the set of subordinates known to this officer. This is the same type of script as used during construction, except here we dynamically extend the officer. [list_begin arguments] [arg_def script actions] The specification of the officer's additional subordinates. Please read [term [vset TITLE_DSL]] (section "Officers") for the details. [list_end][comment arguments] [comment {- - -- --- ----- -------- -------------}] [call [cmd ] [method lookup] [arg name]] This method returns the instance command of the sub-ordinate with the  Changes to doc/cmdr_parameter.man.  65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81  help, if not overridden by a [cmd label] declaration (in [arg spec]). [arg_def string description] Human-readable help text for the parameter. [arg_def script spec] Tcl-script specifying the parameter in detail. Please read [term [vset TITLE_DSL]], section --TODO-- for the details. [list_end][comment arguments] [list_end][comment definitions] [comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@] [section {Instance API}]   < |  65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80  help, if not overridden by a [cmd label] declaration (in [arg spec]). [arg_def string description] Human-readable help text for the parameter. [arg_def script spec] Tcl-script specifying the parameter in detail. Please read [term [vset TITLE_DSL]] (section "Parameters") for the details. [list_end][comment arguments] [list_end][comment definitions] [comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@] [section {Instance API}]  Changes to doc/cmdr_private.man.  44 45 46 47 48 49 50 51 52 53 54 55 56 57 58  [arg_def string name] The user-visible name of the command. [comment {--- TODO place into text block for inclusion --- see officer - extend}] [arg_def script arguments] The specification of the private's parameters. Please read [term [vset TITLE_DSL]], section --TODO-- for the details. [arg_def cmd-prefix action] The command prefix to invoke when this private is selected for execution. It takes a single argument, the instance command of the hidden [package cmdr::config] container holding the private's parameters. The result of the action, if there is any, is ignored by the framework.   |  44 45 46 47 48 49 50 51 52 53 54 55 56 57 58  [arg_def string name] The user-visible name of the command. [comment {--- TODO place into text block for inclusion --- see officer - extend}] [arg_def script arguments] The specification of the private's parameters. Please read [term [vset TITLE_DSL]] (section "Privates") for the details. [arg_def cmd-prefix action] The command prefix to invoke when this private is selected for execution. It takes a single argument, the instance command of the hidden [package cmdr::config] container holding the private's parameters. The result of the action, if there is any, is ignored by the framework.  Added doc/parts/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 24 25 26 27 28  [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 = ... Declare an alternate name for a command path. alias Declare an alternate name for the previous command. common Added doc/parts/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 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  [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. validate & validate &$*$&$*$&$*$& Declare validation type. Details in section \ref{para/vtype}. when-complete & when-complete & none & none & none & 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]  Added doc/parts/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  [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 Added doc/parts/ex_alias0.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  [para] This example specifies a command line providing 3 commands for the management of command aliases. This is actually a slice of [syscmd stackato]'s interface, reduced and modified to fit here. While it does not have the necessary backend procedures required to actually run the commands, it is enough to demonstrate basic features, namely the declaration of "privates" with "input" parameters. [para] "privates" are the actual commands, the leaves at the bottom of the hierarchy. Their "inputs" are positional parameters, i.e. the association of argument words on a command line to parameter is done in order of occurence (on command line, and in the specification). [example { # -*- tcl -* package require Tcl 8.5 package require cmdr package require foo-backend cmdr create ::foo foo { private alias+ { description { Create a shortcut for a command (prefix). } input name { The name of the new shortcut. } { validate ::foo::backend::vt::notacommand } input command { The command (prefix) the name will map to. } { list } } ::foo::backend::alias::add private alias- { description { Remove a shortcut by name. } input name { The name of the shortcut to remove. } { validate ::foo::backend::vt::aliasname } } ::foo::backend::alias::remove private alias? { description { List the known aliases (shortcuts). } } ::foo::backend::alias::list } foo do {*}$argv exit }] [para] At the bottom of the example, just above we can also see the very simple Tcl command which invokes the command line processing for a list of words, here coming from [var \\$argv], i.e. the application's command line. 

     > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >  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 decoupling of command names from their implementations seen in the previous example makes it easy to re-arrange and re-label the user visible commands without having to touch any other part of the code. [para] This is demonstrated in the example below, moving the 3 "privates" into an "officer" and renaming them, without changing the actions. Note that the parameter specifications were removed for clarity, as they were not changed compared to the original example. [para] "officers" are named inner nodes in the command hierarchy. They aggregate related commands, which may not only be "privates" as seen here, but sub-officers as well. [example { ... cmdr create ::foo foo { officer alias { description { A collection of commands to manage user-specific shortcuts for command entry } private add { ... } ::foo::backend::alias::add private remove { ... } ::foo::backend::alias::remove private list { ... } ::foo::backend::alias::list } } ... }]