
<html><head>
<title>cmdr_development - 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_howto_development.man' by tcllib/doctools with format 'html'
   -->
<! -- Copyright &copy; 2013-2016 Andreas Kupries   -- Copyright &copy; 2013-2016 Documentation, Andreas Kupries
   -->
<! -- CVS: $Id$ cmdr_development.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_development(n) 1.2 doc &quot;Cmdr, a framework for command line parsing and dispatch&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>cmdr_development - Cmdr - The Developer's Guide</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">Development Tools</a></li>
<li class="section"><a href="#section3">Demonstration/Example Applications</a></li>
<li class="section"><a href="#section4">Directory structure</a></li>
<li class="section"><a href="#section5">Extended Build Actions</a></li>
<li class="section"><a href="#section6">Architecture &amp; Concepts</a></li>
<li class="section"><a href="#section7">Validation Types</a></li>
<li class="section"><a href="#section8">Help Formats</a></li>
<li class="section"><a href="#section9">Command Line Completion</a></li>
<li class="section"><a href="#section10">Common Blocks</a></li>
<li class="section"><a href="#section11">Related Documents</a></li>
<li class="section"><a href="#section12">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>The audience of this document are anyone wishing to modify
Cmdr in any way, shape, or form. This can be a maintainer
fixing bugs, a developer adding functionality, or patching it to
accommodate local cicumstances, etc.</p>
<p>Please read</p>
<ol class="enumerated">
<li><p><i class="term"><a href="cmdr_howto_get_sources.html">Cmdr - How To Get The Sources</a></i> and</p></li>
<li><p><i class="term"><a href="cmdr_howto_installation.html">Cmdr - The Installer's Guide</a></i></p></li>
</ol>
<p>first, if that was not done already. Here we assume that the sources
are already available in a directory of your choice, that it is known
how to build and install the project, and that all the necessary
requisites are available.</p>
</div>
<div id="section2" class="section"><h2><a name="section2">Development Tools</a></h2>
<p>Cmdr requires the following tools going beyond those needed
for build and installation.</p>
<dl class="definitions">
<dt><b class="syscmd">dia</b></dt>
<dd><p>Processor for <b class="package">diagram</b>-based figures.
See package <b class="package">tklib</b>.</p></dd>
<dt><b class="syscmd">dtplite</b></dt>
<dd><p>Processor for <b class="package">doctools</b>-based documentation files, i.e. the
&quot;<b class="file">.man</b>&quot; files under &quot;<b class="file">doc/</b>&quot;.
See package <b class="package">tcllib</b>.</p>
<p>This requirement is optional. If a Tcllib providing the package
<b class="package">dtplite</b> is installed then <b class="syscmd">kettle</b> will use the
package in favor of the external application.</p></dd>
</dl>
</div>
<div id="section3" class="section"><h2><a name="section3">Demonstration/Example Applications</a></h2>
<p>Cmdr (currently) does not have demonstrations, nor examples.</p>
</div>
<div id="section4" class="section"><h2><a name="section4">Directory structure</a></h2>
<p>The directory structure of the sources is as explained below:</p>
<dl class="definitions">
<dt>&quot;<b class="file">build.tcl</b>&quot;</dt>
<dd><p>The main file of the <b class="syscmd">kettle</b>-based build-system.</p></dd>
<dt>&quot;<b class="file">doc/</b>&quot;</dt>
<dd><p>Main directory for all documentation.</p>
<p>Based on the <b class="package">doctools</b> package and tools provided by
<b class="package">Tcllib</b>.</p></dd>
<dt>&quot;<b class="file">doc/figures/</b>&quot;</dt>
<dd><p>Main directory for all diagrams and figures used by the documentation.</p>
<p>Based on the <b class="package">diagram</b> package and tools provided by
<b class="package">Tklib</b>.</p></dd>
<dt>&quot;<b class="file">embedded/</b>&quot;</dt>
<dd><p>Compiled documentation (manpages and HTML).
Part of the repository for</p>
<ol class="enumerated">
<li><p>easy access from the repository's web interface
(<a href="http://fossil-scm.org/index.html/doc/tip/www/embeddeddoc.wiki">embedded documentation</a>),
and</p></li>
<li><p>quicker installation (no need to compile during the
installation process itself).</p></li>
</ol></dd>
<dt>&quot;<b class="file">tests/</b>&quot;</dt>
<dd><p>Main directory for the test-suite.</p>
<p>Based on the <b class="package">tcltest</b> package distributed with the Tcl
core.</p></dd>
<dt>&quot;<b class="file">actor.tcl</b>&quot;</dt>
<dd><p>Package <b class="package"><a href="cmdr_actor.html">cmdr::actor</a></b>.</p></dd>
<dt>&quot;<b class="file">cmdr.tcl</b>&quot;</dt>
<dd><p>Package <b class="package"><a href="cmdr.html">cmdr</a></b>.</p></dd>
<dt>&quot;<b class="file">config.tcl</b>&quot;</dt>
<dd><p>Package <b class="package"><a href="cmdr_config.html">cmdr::config</a></b>.</p></dd>
<dt>&quot;<b class="file">help.tcl</b>&quot;</dt>
<dd><p>Package <b class="package"><a href="cmdr_help.html">cmdr::help</a></b>.</p></dd>
<dt>&quot;<b class="file">help_json.tcl</b>&quot;</dt>
<dd><p>Package <b class="package"><a href="cmdr_help_json.html">cmdr::help::json</a></b>.</p></dd>
<dt>&quot;<b class="file">help_sql.tcl</b>&quot;</dt>
<dd><p>Package <b class="package"><a href="cmdr_help_sql.html">cmdr::help::sql</a></b>.</p></dd>
<dt>&quot;<b class="file">help_tcl.tcl</b>&quot;</dt>
<dd><p>Package <b class="package"><a href="cmdr_help_tcl.html">cmdr::help::tcl</a></b>.</p></dd>
<dt>&quot;<b class="file">officer.tcl</b>&quot;</dt>
<dd><p>Package <b class="package"><a href="cmdr_officer.html">cmdr::officer</a></b>.</p></dd>
<dt>&quot;<b class="file">parameter.tcl</b>&quot;</dt>
<dd><p>Package <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b>.</p></dd>
<dt>&quot;<b class="file">private.tcl</b>&quot;</dt>
<dd><p>Package <b class="package"><a href="cmdr_private.html">cmdr::private</a></b>.</p></dd>
<dt>&quot;<b class="file">util.tcl</b>&quot;</dt>
<dd><p>Package <b class="package"><a href="cmdr_util.html">cmdr::util</a></b>.</p></dd>
<dt>&quot;<b class="file">validate.tcl</b>&quot;</dt>
<dd><p>Package <b class="package"><a href="cmdr_validate.html">cmdr::validate</a></b>.</p></dd>
<dt>&quot;<b class="file">vcommon.tcl</b>&quot;</dt>
<dd><p>Package <b class="package"><a href="cmdr_vcommon.html">cmdr::validate::common</a></b>.</p></dd>
</dl>
</div>
<div id="section5" class="section"><h2><a name="section5">Extended Build Actions</a></h2>
<p>Our build-system is based on <b class="syscmd">kettle</b>, as already explained in
the <i class="term"><a href="cmdr_howto_installation.html">Cmdr - The Installer's Guide</a></i>. Beyond the targets useful for
installation it also provides targets aiding developers and
maintainers. These are:</p>
<dl class="definitions">
<dt>Validation of the documentation</dt>
<dd>
<pre class="example">
% /path/to/cmdr/build.tcl validate-doc
</pre>
</dd>
<dt>Regeneration of the embedded documentation</dt>
<dd>
<pre class="example">
% /path/to/cmdr/build.tcl doc
</pre>
</dd>
<dt>Regeneration of the figures for the documentation</dt>
<dd>
<pre class="example">
% /path/to/cmdr/build.tcl figures
</pre>
</dd>
<dt>Execution of the test-suite</dt>
<dd><p>The most basic execution of the test-suite is done with</p>
<pre class="example">
% /path/to/cmdr/build.tcl test
</pre>
<p>When the test-suite reports issues with the framework use of
the more extended form below is indicated, with a <b class="const">&lt;stem&gt;</b> of
your choice. This will generate a number of files whose name starts
with the prefix &quot;<b class="file">&lt;stem&gt;.</b>&quot;. These will contain extended test logs,
details about errors and failures, etc.</p>
<pre class="example">
% /path/to/cmdr/build.tcl test --log &lt;stem&gt;
</pre>
</dd>
</dl>
</div>
<div id="section6" class="section"><h2><a name="section6">Architecture &amp; Concepts</a></h2>
<p>All packages in the framework belong to one of three layers,
as shown below:</p>
<p><img alt="architecture" src="../../image/architecture.png"></p>
<p>Note that:</p>
<ul class="itemized">
<li><p>Packages marked with a dashed blue border are public in parts,
and private in parts.</p></li>
<li><p>Packages marked with an unbroken blue border are fully public.</p></li>
<li><p>The topmost layer contains only a single package,
<b class="package"><a href="cmdr.html">cmdr</a></b>, which is the trivial entry point to the system.</p></li>
<li><p>The bottom layer contains the mainly internal utility packages.
The exception is <b class="package"><a href="cmdr_vcommon.html">cmdr::validate::common</a></b>, for use in bespoke
validation types. See the document about <i class="term"><a href="cmdr_vtypes.html">Cmdr - Writing custom validation types</a></i>
for details.</p></li>
<li><p>The important pieces implementing the various entities are all
in the middle layer. The relationship of these entities can be seen in
the next diagram:</p>
<p><img alt="erd" src="../../image/erd.png"></p></li>
</ul>
<p>The dependencies between the packages are very
straight-forward, following mostly directly out of the relationships
shown above, plus the few where the utilities are imported. To reduce
the complexity of the diagram below a few direct dependencies on
<b class="package"><a href="cmdr_util.html">cmdr::util</a></b> were omitted where indirectly present through
other dependencies (i.e. through <b class="package"><a href="cmdr_help.html">cmdr::help</a></b>):</p>
<p><img alt="pkg_dependencies" src="../../image/pkg_dependencies.png"></p>
</div>
<div id="section7" class="section"><h2><a name="section7">Validation Types</a></h2>
<p>Everything said in the public document <i class="term"><a href="cmdr_vtypes.html">Cmdr - Writing custom validation types</a></i>
applies to the standard validation types of the framework (as listed
in <i class="term"><a href="cmdr_validate.html">Cmdr - Standard validation types for parameters</a></i>) as well.</p>
</div>
<div id="section8" class="section"><h2><a name="section8">Help Formats</a></h2>
<p>Everything said in the public document <i class="term"><a href="cmdr_helpformats.html">Cmdr - Writing custom help formats</a></i>
applies to the standard help formats of the framework (as listed in
<i class="term"><a href="cmdr_help.html">Cmdr - (Internal) Utilities for help text formatting and setup</a></i>) as well.</p>
</div>
<div id="section9" class="section"><h2><a name="section9">Command Line Completion</a></h2>
<p>The document <i class="term"><a href="cmdr_dev_completion.html">Cmdr - Internals of command line completion</a></i> describes the inner
workings of the command line completion provided by the framework.</p>
</div>
<div id="section10" class="section"><h2><a name="section10">Common Blocks</a></h2>
<p>The framework reserves all blocks whose name begins with a star, i.e
<b class="const">*</b>, for its own use.
Currently the following names are in use:</p>
<dl class="definitions">
<dt><b class="const">*all*</b></dt>
<dd><p>Publicly documented for users, this block is expected to contain
parameter specification commands. These commands are automatically
added to all privates found in the command hierarchy containing the
block.</p>
<p>The details are explained by the description of command
<b class="cmd">common</b> in <i class="term"><a href="cmdr_dsl_officer.html">Cmdr - Officer Specification Language</a></i>.</p></dd>
<dt><b class="const">*category-order*</b></dt>
<dd><p>Publicly documented for users, this block is expected to contain a
dictionary mapping from toplevel section/category names to an integer
number to override the natural order of displaying these sections in
the help.</p>
<p>The details are explained in section <i class="term">Format Notes</i> of
<i class="term"><a href="cmdr_help.html">Cmdr - (Internal) Utilities for help text formatting and setup</a></i>.</p></dd>
<dt><b class="const">*config*</b></dt>
<dd><p>Publicly documented for users as read-only this block's value is
managed by the framework, and only found in the root actor.</p>
<p>It is a command name, i.e. object handle, to the active
instance of <b class="class">cmdr::config</b>. 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.</p>
<p>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.</p></dd>
<dt><b class="const">*prefix*</b></dt>
<dd><p>Publicly documented for users as read-only this block's value is
managed by the framework.
Set during the <i class="term">Dispatch</i> phase it provides to access to the
actual command name used to invoke a <i class="term">private</i>.</p>
<p>See also section <i class="term">Execution</i> of <i class="term"><a href="cmdr_flow.html">Cmdr - Runtime Processing Flow</a></i>.</p></dd>
<dt><b class="const">*in-shell*</b></dt>
<dd><p>Publicly documented for users as read-only this block's value is
managed by the framework. Not set until the first main- or mini-shell
was active its value is boolean flag indicating if an interactive
shell is currently active (<b class="const">true</b>) or not (<b class="const">false</b>, or not
existing).</p>
<p>See also section <i class="term">Execution</i> of <i class="term"><a href="cmdr_flow.html">Cmdr - Runtime Processing Flow</a></i>.</p></dd>
</dl>
</div>
<div id="section11" class="section"><h2><a name="section11">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">Cmdr - The Developer's Guide</i></p></li>
</ol>
</div>
<div id="section12" class="section"><h2><a name="section12">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 &copy; 2013-2016 Andreas Kupries<br>
Copyright &copy; 2013-2016 Documentation, Andreas Kupries</p>
</div>
</div></body></html>
