<html><head>
<title>cmdr-introduction - 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_introduction.man' by tcllib/doctools with format 'html'
-->
<! -- Copyright © 2013-2016 Andreas Kupries -- Copyright © 2013-2016 Documentation, Andreas Kupries
-->
<! -- CVS: $Id$ cmdr-introduction.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-introduction(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-introduction - Cmdr - Introduction to the project</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">System Architecture</a></li>
<li class="section"><a href="#section3">Command Hierarchy Specifications</a></li>
<li class="section"><a href="#section4">Extensibility</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>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 <b class="variable">$::argv</b>. 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.</p>
</div>
<div id="section2" class="section"><h2><a name="section2">System Architecture</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="section3" class="section"><h2><a name="section3">Command Hierarchy Specifications</a></h2>
<p>This is a bit large for this document, and can be found in the
separate <i class="term"><a href="cmdr_dsl.html">Cmdr - Introduction to the Specification Language</a></i>.</p>
</div>
<div id="section4" class="section"><h2><a name="section4">Extensibility</a></h2>
<p>While the framework as is should cover most to all of the common cases
where is always the possibility of encountering unanticipated
situations.
Because of that the framework has two places where it can be extended
to make it fit uncommon requirements.
And while the DSL document chain referenced in the previous section
does mention these as well in the appropriate places this is a bit
hidden.
So, for better visibility, an early mention:</p>
<ol class="enumerated">
<li><p>While the framework has a set of standard validation types for
checking and converting inputs these handle only very generic types of
input.
Applications often have special input requiring bespoke validation.
How to write such is explained in <i class="term"><a href="cmdr_vtypes.html">Cmdr - Writing custom validation types</a></i>.</p></li>
<li><p>Less often an application may require a special format for help
generated from its command hierarchy, beyond the standard formats made
available by the framework.
How to write such is explained in <i class="term"><a href="cmdr_helpformats.html">Cmdr - Writing custom help formats</a></i>.</p></li>
</ol>
</div>
<div id="section5" class="section"><h2><a name="section5">Related Documents</a></h2>
<ol class="enumerated">
<li><p><i class="term">Cmdr - Introduction to the project</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>
