cmdr
Artifact [b4940cf5a8]
Not logged in
Bounty program for improvements to Tcl and certain Tcl packages.

Artifact b4940cf5a8a9880ef921b9333709e74089aa5ee3:



<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 &copy; 2013-2016 Andreas Kupries   -- Copyright &copy; 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 &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-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, &gt; 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 &copy; 2013-2016 Andreas Kupries<br>
Copyright &copy; 2013-2016 Documentation, Andreas Kupries</p>
</div>
</div></body></html>