<html><head>
<title>cmdr-spec-dsl - Cmdr, a framework for command line parsing and dispatch</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.toc,UL.toc UL, UL.toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.section, LI.subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.requirements LI, UL.syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
--></style>
</head>
<! -- Generated from file 'cmdr_dsl.man' by tcllib/doctools with format 'html'
-->
<! -- Copyright © 2013-2016 Andreas Kupries -- Copyright © 2013-2016 Documentation, Andreas Kupries
-->
<! -- CVS: $Id$ cmdr-spec-dsl.n
-->
<body><div class="doctools">
<hr> [
<a href="../../../../../../home">Home</a>
| <a href="../../toc.html">Main Table Of Contents</a>
| <a href="../toc.html">Table Of Contents</a>
| <a href="../../index.html">Keyword Index</a>
] <hr>
<h1 class="title">cmdr-spec-dsl(n) 1.2 doc "Cmdr, a framework for command line parsing and dispatch"</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>cmdr-spec-dsl - Cmdr - Introduction to the Specification Language</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">
<li class="section"><a href="#toc">Table Of Contents</a></li>
<li class="section"><a href="#section1">Description</a></li>
<li class="section"><a href="#section2">Related Specification Documents</a></li>
<li class="section"><a href="#section3">Introductory examples</a>
<ul>
<li class="subsection"><a href="#subsection1">Basic private commands with inputs</a></li>
<li class="subsection"><a href="#subsection2">Simple command nesting</a></li>
<li class="subsection"><a href="#subsection3">Simple backend</a></li>
</ul>
</li>
<li class="section"><a href="#section4">Language Reference</a></li>
<li class="section"><a href="#section5">Related Documents</a></li>
<li class="section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="section"><a href="#keywords">Keywords</a></li>
<li class="section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="section"><h2><a name="section1">Description</a></h2>
<p>Welcome to the Cmdr project, written by Andreas Kupries.</p>
<p>For availability please read <i class="term"><a href="cmdr_howto_get_sources.html">Cmdr - How To Get The Sources</a></i>.</p>
<p>This document is for users of the cmdr framework. It introduces the
domain-specific language for the specification of command hierarchies
with commands and their parameters by way of examples and then
provides links to the detailed reference documents.</p>
</div>
<div id="section2" class="section"><h2><a name="section2">Related Specification Documents</a></h2>
<ol class="enumerated">
<li><p><i class="term">Cmdr - Introduction to the Specification Language</i></p></li>
<li><p><i class="term"><a href="cmdr_dsl_officer.html">Cmdr - Officer Specification Language</a></i></p></li>
<li><p><i class="term"><a href="cmdr_dsl_private.html">Cmdr - Private Specification Language</a></i></p></li>
<li><p><i class="term"><a href="cmdr_dsl_parameter.html">Cmdr - Parameter Specification Language</a></i></p></li>
<li><p><i class="term"><a href="cmdr_flow.html">Cmdr - Runtime Processing Flow</a></i></p></li>
</ol>
</div>
<div id="section3" class="section"><h2><a name="section3">Introductory examples</a></h2>
<p>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.</p>
<div id="subsection1" class="subsection"><h3><a name="subsection1">Basic private commands with inputs</a></h3>
<p>This example specifies a command line providing 3 commands for
the management of command aliases.
This is actually a slice of <b class="syscmd">stackato</b>'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.</p>
<p>"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).</p>
<pre class="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
</pre>
<p>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 <b class="variable">$argv</b>, i.e. the application's
command line.</p>
</div>
<div id="subsection2" class="subsection"><h3><a name="subsection2">Simple command nesting</a></h3>
<p>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.</p>
<p>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.</p>
<p>"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.</p>
<pre class="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
}
}
...
</pre>
</div>
<div id="subsection3" class="subsection"><h3><a name="subsection3">Simple backend</a></h3>
<p>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.</p>
<p>Note further that while this example uses a
<b class="cmd">namespace ensemble</b> to organize the backend other methods are
possible too, i.e. all the various object systems for Tcl would be
suitable as well.</p>
<p>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.</p>
<pre class="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 lines, hidden from kettle scanner.
</pre>
</div>
</div>
<div id="section4" class="section"><h2><a name="section4">Language Reference</a></h2>
<p>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.</p>
<p>The conceptual model underneath the command hierarchy is that
of a tree.</p>
<p>The inner nodes of the tree represent command ensembles, here
called <i class="term">officer</i>s. Each officer knows one or more commands to
perform, and delegates actual execution to their respective
specification, which may be another <i class="term">officer</i>, or a <i class="term">private</i>.</p>
<p>The leaf nodes of the tree represent the individual commands,
here called <i class="term">private</i>s.
Each <i class="term">private</i> is responsible for a single action and knows how
to perform it, and the set of <i class="term">parameter</i>s used to configure that
action at runtime.</p>
<p>The same model is graphically presented in the
Entity-Relationship-Diagram below.</p>
<p><img alt="erd" src="../../image/erd.png"></p>
<p>The <i class="term">actor</i> in that diagram is the common base class for the
ensembles and commands and not directly relevant to users.</p>
<p>The <i class="term">config</i> on the other hand is the second interface
seen by the user, as the sole argument to the action command prefix of
<b class="cmd">private</b>. See <i class="term"><a href="cmdr_dsl_officer.html">Cmdr - Officer Specification Language</a></i> for the details.
This container, an instance of <b class="package"><a href="cmdr_config.html">cmdr::config</a></b>, holds all the
declared parameters of the command the action is invoked for, and
provides easy access to them through its methods at the time of
execution.</p>
<p>Please continue reading with <i class="term"><a href="cmdr_dsl_officer.html">Cmdr - Officer Specification Language</a></i>.</p>
</div>
<div id="section5" class="section"><h2><a name="section5">Related Documents</a></h2>
<ol class="enumerated">
<li><p><i class="term"><a href="cmdr_introduction.html">Cmdr - Introduction to the project</a></i></p></li>
<li><p><i class="term"><a href="cmdr_license.html">Cmdr - License</a></i></p></li>
<li><p><i class="term"><a href="cmdr_changes.html">Cmdr - Log of Changes</a></i></p></li>
<li><p><i class="term"><a href="cmdr_howto_get_sources.html">Cmdr - How To Get The Sources</a></i></p></li>
<li><p><i class="term"><a href="cmdr_howto_installation.html">Cmdr - The Installer's Guide</a></i></p></li>
<li><p><i class="term"><a href="cmdr_howto_development.html">Cmdr - The Developer's Guide</a></i></p></li>
</ol>
</div>
<div id="section6" class="section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>Both the package(s) and this documentation will undoubtedly contain
bugs and other problems.
Please report such at
<a href="https:/core.tcl.tk/akupries/cmdr">Cmdr Tickets</a>.</p>
<p>Please also report any ideas you may have for enhancements of
either package(s) and/or documentation.</p>
</div>
<div id="keywords" class="section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../index.html#key4">arguments</a>, <a href="../../index.html#key5">command hierarchy</a>, <a href="../../index.html#key9">command line completion</a>, <a href="../../index.html#key11">command line handling</a>, <a href="../../index.html#key13">command tree</a>, <a href="../../index.html#key0">editing command line</a>, <a href="../../index.html#key8">help for command line</a>, <a href="../../index.html#key6">hierarchy of commands</a>, <a href="../../index.html#key3">interactive command shell</a>, <a href="../../index.html#key1">optional arguments</a>, <a href="../../index.html#key2">options</a>, <a href="../../index.html#key12">parameters</a>, <a href="../../index.html#key10">processing command line</a>, <a href="../../index.html#key7">tree of commands</a></p>
</div>
<div id="copyright" class="section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2013-2016 Andreas Kupries<br>
Copyright © 2013-2016 Documentation, Andreas Kupries</p>
</div>
</div></body></html>
