<html><head>
<title>cmdr-changes - 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_changes.man' by tcllib/doctools with format 'html'
-->
<! -- Copyright © 2013-2016 Andreas Kupries -- Copyright © 2013-2016 Documentation, Andreas Kupries
-->
<! -- CVS: $Id$ cmdr-changes.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-changes(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-changes - Cmdr - Log of Changes</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">Changes</a>
<ul>
<li class="subsection"><a href="#subsection1">Changes for version 1.2</a></li>
<li class="subsection"><a href="#subsection2">Changes for version 1.1</a></li>
<li class="subsection"><a href="#subsection3">Changes for version 1</a></li>
</ul>
</li>
<li class="section"><a href="#section3">Related Documents</a></li>
<li class="section"><a href="#section4">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 provides an overview of the changes <b class="package"><a href="cmdr.html">cmdr</a></b>
underwent from version to version.</p>
</div>
<div id="section2" class="section"><h2><a name="section2">Changes</a></h2>
<div id="subsection1" class="subsection"><h3><a name="subsection1">Changes for version 1.2</a></h3>
<ol class="enumerated">
<li><p>Extended the package <b class="package"><a href="cmdr_validate.html">cmdr::validate</a></b> with many new
standard validation types:</p>
<ol class="enumerated">
<li><p>Double</p></li>
<li><p>Percent</p></li>
<li><p>Posint (positive integers, > 0)</p></li>
<li><p>Paths and channels</p>
<ol class="enumerated">
<li><p>Readable file</p></li>
<li><p>Writable file</p></li>
<li><p>Read/writable file</p></li>
<li><p>Readable directory</p></li>
<li><p>Read/writeable directory</p></li>
<li><p>readable path</p></li>
<li><p>Read/writable path</p></li>
<li><p>Readable path, as channel</p></li>
<li><p>Writable path, as channel</p></li>
<li><p>Read/writable path, as channel</p></li>
</ol>
</li>
<li><p>Date and time related:</p>
<ol class="enumerated">
<li><p>ISO-8601 date/time,</p></li>
<li><p>year</p></li>
<li><p>weekday,</p></li>
<li><p>hour:minute</p></li>
</ol>
</li>
</ol>
</li>
<li><p>In package <b class="package"><a href="cmdr_validate.html">cmdr::validate</a></b>, modified the integer
validation type to have a proper internal representation:
decimal. Input in octal, hex, etc. is now normalized to this.</p></li>
<li><p>Extended package <b class="package"><a href="cmdr_vcommon.html">cmdr::validate::common</a></b> with more
helper commands for the generation of validation failure
messages</p>
<ol class="enumerated">
<li><p><b class="cmd">fail-unknown-thing-msg</b></p></li>
<li><p><b class="cmd">fail-unknown-simple</b></p></li>
<li><p><b class="cmd">fail-unknown-simple-msg</b></p></li>
<li><p><b class="cmd">fail-known-thing-msg</b></p></li>
<li><p><b class="cmd">fail-known-simple</b></p></li>
<li><p><b class="cmd">fail-known-simple-msg</b></p></li>
</ol>
</li>
<li><p>Added various new supporting packages:</p>
<dl class="definitions">
<dt><b class="package"><a href="cmdr_tty.html">cmdr::tty</a></b></dt>
<dd><p>Test for terminal.</p></dd>
<dt><b class="package"><a href="cmdr_color.html">cmdr::color</a></b></dt>
<dd><p>Color management, ansi control sequences.</p></dd>
<dt><b class="package"><a href="cmdr_ask.html">cmdr::ask</a></b></dt>
<dd><p>User interaction commands.</p></dd>
<dt><b class="package"><a href="cmdr_pager.html">cmdr::pager</a></b></dt>
<dd><p>Text display with automatic invokation of a pager for tall
output.</p></dd>
<dt><b class="package"><a href="cmdr_history.html">cmdr::history</a></b></dt>
<dd><p>Pluggable management of command history.</p></dd>
<dt><b class="package"><a href="cmdr_table.html">cmdr::table</a></b></dt>
<dd><p>Table formatting, a simplified interface to
<a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/toc.html">Tcllib</a>'s
<b class="package">struct::matrix</b> and <b class="package">report</b> packages.</p></dd>
<dt><b class="package">cmdr::validate::valtype-support</b></dt>
<dd><p>Even more validation types, now as wrappers around the
validation commands provided by
<a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/toc.html">Tcllib</a>:</p>
<ol class="enumerated">
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/cc_amex.html">valtype::creditcard::amex</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/cc_discover.html">valtype::creditcard::discover</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/cc_mastercard.html">valtype::creditcard::mastercard</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/cc_visa.html">valtype::creditcard::visa</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/ean13.html">valtype::gs1::ean13</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/iban.html">valtype::iban</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/imei.html">valtype::imei</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/isbn.html">valtype::isbn</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/luhn.html">valtype::luhn</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/luhn5.html">valtype::luhn5</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/usnpi.html">valtype::usnpi</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/verhoeff.html">valtype::verhoeff</a></p></li>
</ol></dd>
</dl>
</li>
<li><p>Extended package <b class="package"><a href="cmdr_officer.html">cmdr::officer</a></b> with</p>
<ol class="enumerated">
<li><p>Support for per-officer options. The most common use
case will likely be the declaration of global options in
the root officer.</p>
<p>Related to this, a new common block <b class="const">*config*</b> is
set to the active <b class="package">config</b> instance, which will
be different from the defining instance, for per-officer
options. This gives the per-officer options access to
the arguments (and options) of the current command,
instead of only their own sibling options.</p></li>
<li><p>Support for an option <b class="option">-extend</b> for common
blocks, allowing their extension in a subordinate
instead of just replacing the entire content.</p></li>
<li><p>Support to accept all unique command prefixes of an
officer's subordinates for dispatch.</p></li>
</ol>
</li>
<li><p>Extended package <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> with</p>
<ol class="enumerated">
<li><p>Support for the specification of negative aliases for
boolean options, i.e. representing the inverted option.</p>
<p>See the DSL commands <b class="cmd">neg-alias</b> and <b class="cmd">!alias</b> in
<i class="term"><a href="cmdr_dsl_parameter.html">Cmdr - Parameter Specification Language</a></i>.</p></li>
<li><p>Support for option labeling, for use in the generated
help, to make it more descriptive. Options for which no
label is specified will use their name as fallback.</p>
<p>See DSL command <b class="cmd">label</b> in
<i class="term"><a href="cmdr_dsl_parameter.html">Cmdr - Parameter Specification Language</a></i>.</p></li>
</ol>
</li>
<li><p>Help system changes</p>
<ol class="enumerated">
<li><p>Modified it to use the <b class="const">short</b> format for interior
nodes of the command hierarchy by default.</p></li>
<li><p>Modified it to exclude auto-added commands from the
output generated by format <b class="const">by-category</b>.</p></li>
<li><p>Modified the format <b class="const">full</b> to show the option
arguments for those which have such. See also the
extension of package <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b> with
support for option labels, this is what is used here.</p></li>
<li><p>Modified it to declare a standard global option
<b class="option">--help</b> (with aliases <b class="option">-h</b> and
<b class="option">-?</b>). Using the option invokes the standard help
(command) on the current command, if any, or the global
help if there is no command.</p></li>
<li><p>Modified to use a minimum width of 10 characters for
descriptions. If the user narrowed the terminal this far
then having the text either cut off at the right edge,
or wrapped around is not worse then the help trying to
wrap the sentence with word boundaries, etc. Also,
trying to use negative width threw Tcl errors.</p></li>
</ol>
</li>
<li><p>Fixed the handling of common block <b class="const">*all*</b> in package
<b class="package"><a href="cmdr_officer.html">cmdr::officer</a></b>. While it was ok trapping and ignoring
a missing definition of this block, trapping everything which
could go wrong was not.</p>
<p><a href="http://core.tcl.tk/akupries/cmdr/info/9159f68bc35d9747">Details</a>.</p></li>
<li><p>Fixed a long-standing bug of package <b class="package"><a href="cmdr_config.html">cmdr::config</a></b> in
the forced calculation of parameter values in method
<b class="method">Force</b>). Any error in the calculations left an internal
flag set, causing future invokations to believe to be in a
recursive call and thus do nothing.</p>
<p>While this had no effect on regular operation, i.e.
with the application exiting after each command, in interactive
mode this misbehaviour disabled all checks and validations for
the command in question, and also retained old parameter
values.</p>
<p><a href="http://core.tcl.tk/akupries/cmdr/info/f74095b252d4c9df">Details</a></p></li>
<li><p>Modified the formatting of <b class="package"><a href="cmdr_config.html">cmdr::config</a></b> state when
interactively entering it for a private. Parameter names now
are shown as declared, and an additional flag character
indicates if it is inherited from above, or not.</p></li>
<li><p>General fixes to testsuite, code comments, bogus variable
names, typos in error messages, etc.</p></li>
</ol>
</div>
<div id="subsection2" class="subsection"><h3><a name="subsection2">Changes for version 1.1</a></h3>
<ol class="enumerated">
<li><p>Fixed broken requirement references in the meta data of packages
<b class="package"><a href="cmdr_help_json.html">cmdr::help::json</a></b> and <b class="package"><a href="cmdr_help_sql.html">cmdr::help::sql</a></b>.</p></li>
<li><p>Fixed initialization issues in the help generator.</p></li>
<li><p>Fixed generated help, added the application name to the output
when in a cmdr shell.</p></li>
<li><p>Fixed the generation of help format <b class="const">by-categorized</b>, when
encountering sections with sub-sections and no commands of their
own.</p></li>
<li><p>Fixed bad method scoping in method <b class="method">extend</b> of officers.</p></li>
<li><p>Extended officer method <b class="method">extend</b> to return the created
private, for immediate post-creation re-configuration.</p></li>
<li><p>Extended system with new help format <i class="term">tcl</i>, and associated
package <b class="package"><a href="cmdr_help_tcl.html">cmdr::help::tcl</a></b>. Similar to format <i class="term">json</i>
the help is printed as a nested data structure, just using Tcl
syntax.</p></li>
<li><p>Extended officers and privates with method <b class="method">find</b> for
path lookup of sub-ordinates.</p></li>
</ol>
</div>
<div id="subsection3" class="subsection"><h3><a name="subsection3">Changes for version 1</a></h3>
<p>This is the first release of cmdr.
The changes therefore describe the initial features of the system.</p>
<p>In detail:</p>
<ol class="enumerated">
<li><p>cmdr requires Tcl 8.5 or higher.
Tcl 8.4 or less is not supported.</p></li>
<li><p>The framework provides a DSL for the declaration of a hierarchy
of commands and their parameters (named options, positional
arguments, hidden state), with help texts, type information, and
various callbacks (command actions, parameter definition,
parameter completion, type validation, command completion, etc.)</p></li>
<li><p>At runtime the framework provides parsing and processing of command
lines per specifications written in that DSL, determining the command
to run, and the mapping from command line words to its parameters.</p></li>
<li><p>The framework also provides shells for the interactive entry of
commands and parameters, with command line completion.</p></li>
<li><p>Last, but not least is the automatic generation of command line
help for commands and parameters, based on the information provided
in a specification.</p></li>
</ol>
</div>
</div>
<div id="section3" class="section"><h2><a name="section3">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">Cmdr - Log of Changes</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="section4" class="section"><h2><a name="section4">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>