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

Artifact 17ec4fa88a232d9e0fbf5557b1e9170f61e5b0ff:



<html><head>
<title>cmdr::private - 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_private.man' by tcllib/doctools with format 'html'
   -->
<! -- Copyright &copy; 2013-2016 Andreas Kupries   -- Copyright &copy; 2013-2016 Documentation, Andreas Kupries
   -->
<! -- CVS: $Id$ cmdr::private.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::private(n) 1.3.1 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::private - Cmdr - (Internal) Single command handling, options, and arguments</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="#synopsis">Synopsis</a></li>
<li class="section"><a href="#section1">Description</a></li>
<li class="section"><a href="#section2">Class API</a></li>
<li class="section"><a href="#section3">Instance API</a></li>
<li class="section"><a href="#section4">Help Information</a></li>
<li class="section"><a href="#section5">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="synopsis" class="section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="synopsis">
<ul class="requirements">
<li>package require <b class="pkgname">cmdr::private</b></li>
</ul>
<ul class="syntax">
<li><a href="#1"><b class="cmd">::cmdr::private</b> <b class="method">new</b> <i class="arg">super</i> <i class="arg">name</i> <i class="arg">arguments</i> <i class="arg">action</i></a></li>
<li><a href="#2"><b class="cmd">::cmdr::private</b> <b class="method">create</b> <i class="arg">obj</i> <i class="arg">super</i> <i class="arg">name</i> <i class="arg">arguments</i> <i class="arg">action</i></a></li>
<li><a href="#3"><b class="cmd">&lt;private&gt;</b> <b class="method">complete-words</b> <i class="arg">parse</i></a></li>
<li><a href="#4"><b class="cmd">&lt;private&gt;</b> <b class="method">do</b> <span class="opt">?<i class="arg">word</i>...?</span></a></li>
<li><a href="#5"><b class="cmd">&lt;private&gt;</b> <b class="method">intercept</b> <i class="arg">cmd</i></a></li>
<li><a href="#6"><b class="cmd">&lt;private&gt;</b> <b class="method">ehandler</b> <i class="arg">cmd</i></a></li>
<li><a href="#7"><b class="cmd">&lt;private&gt;</b> <b class="method">custom-setup</b> <i class="arg">cmd</i></a></li>
<li><a href="#8"><b class="cmd">&lt;private&gt;</b> <b class="method">find</b> <i class="arg">path</i></a></li>
<li><a href="#9"><b class="cmd">&lt;private&gt;</b> <b class="method">help</b> <span class="opt">?<i class="arg">prefix</i>?</span></a></li>
<li><a href="#10"><b class="cmd">&lt;private&gt;</b> <b class="method">unknown</b> <i class="arg">m</i> <span class="opt">?<i class="arg">word</i>...?</span></a></li>
</ul>
</div>
</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 package implements <em>privates</em>, the leaves of command
hierarchies.  While each private can execute only a single action they
have parameters, i.e. arguments and options with which to configure
the behaviour of their action.</p>
<p>This class is sub-class of <b class="package"><a href="cmdr_actor.html">cmdr::actor</a></b>.</p>
</div>
<div id="section2" class="section"><h2><a name="section2">Class API</a></h2>
<p>The class API is not public. It is used internally by the framework
when parsing a command hierarchy specification to create the necessary
private instances.</p>
<p>It is described here for use by developers maintaining,
modifying and extending the framework itself. A user of the framework
has no need for it.</p>
<dl class="definitions">
<dt><a name="1"><b class="cmd">::cmdr::private</b> <b class="method">new</b> <i class="arg">super</i> <i class="arg">name</i> <i class="arg">arguments</i> <i class="arg">action</i></a></dt>
<dd><p>Create an auto-named instance of <b class="class">cmdr::private</b>.</p>
<p><em>Not used</em>.</p></dd>
<dt><a name="2"><b class="cmd">::cmdr::private</b> <b class="method">create</b> <i class="arg">obj</i> <i class="arg">super</i> <i class="arg">name</i> <i class="arg">arguments</i> <i class="arg">action</i></a></dt>
<dd><p>Create a new instance of <b class="class">cmdr::private</b>, named <i class="arg">obj</i>.
Used by the DSL processing parts of the framework to instantiate privates.</p>
<dl class="arguments">
<dt>object <i class="arg">super</i></dt>
<dd><p>The instance command of the actor (officer actually) which contains the new private.</p></dd>
<dt>string <i class="arg">name</i></dt>
<dd><p>The user-visible name of the command.</p></dd>
<dt>script <i class="arg">arguments</i></dt>
<dd><p>The specification of the private's parameters.
Please read <i class="term"><a href="cmdr_dsl_parameter.html">Cmdr - Parameter Specification Language</a></i> for the details.</p></dd>
<dt>cmd-prefix <i class="arg">action</i></dt>
<dd><p>The command prefix to invoke when this private is selected for
execution.  It takes a single argument, the instance command of the
hidden <b class="package"><a href="cmdr_config.html">cmdr::config</a></b> container holding the private's
parameters. The result of the action, if there is any, is ignored by
the framework.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="section"><h2><a name="section3">Instance API</a></h2>
<p>The instance API is not public. It is used internally by the framework
during the parsing of a command hierarchy specification to configure
the private instances, and when processing a command line at
runtime to manage word-completion, etc.</p>
<p>It is described here for use by developers maintaining,
modifying and extending the framework itself. A user of the framework
has no need for it, although they have indirect access through
parameters and their container.</p>
<dl class="definitions">
<dt><a name="3"><b class="cmd">&lt;private&gt;</b> <b class="method">complete-words</b> <i class="arg">parse</i></a></dt>
<dd><p>This method is part of the main shell command line
completion. For the details of its workings please read
<i class="term"><a href="cmdr_dev_completion.html">Cmdr - Internals of command line completion</a></i>.</p>
<p>Given the completion state <i class="arg">parse</i> of a partial
command line it returns a list of strings which are the valid
completions at this point.</p>
<dl class="arguments">
<dt>dict <i class="arg">parse</i></dt>
<dd><p>A dictionary holding the current completion state of a partial command
line.</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">&lt;private&gt;</b> <b class="method">do</b> <span class="opt">?<i class="arg">word</i>...?</span></a></dt>
<dd><p>This method parses the <i class="arg">word</i>s of the command line, matching them
to the parameters of the private, be they arguments, or options. When
done without error it invokes the action of the private with the
filled container of parameters.</p>
<dl class="arguments">
<dt>string <i class="arg">word</i></dt>
<dd><p>The words of the command line to parse and match to parameters.</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">&lt;private&gt;</b> <b class="method">intercept</b> <i class="arg">cmd</i></a></dt>
<dd></dd>
<dt><a name="6"><b class="cmd">&lt;private&gt;</b> <b class="method">ehandler</b> <i class="arg">cmd</i></a></dt>
<dd><p><em>Note:</em> While the form <b class="method">ehandler</b> is still usable, it is
deprecated and will be removed in a future release.
This method specifies a command prefix to wrap around the parsing of
the command line for the private, and the execution of its action.</p>
<dl class="arguments">
<dt>cmd-prefix <i class="arg">cmd</i></dt>
<dd><p>A command prefix taking a single argument, a script. The command
prefix has to execute this script in its caller's context. The script
will parse words for the private,m and perform its action. The command
prefix then has the responsbility to perform any custom cleanup action
required by the application using the framework to prevent leakage of
data between multiple commands executed one after the other (i.e. in
an interactive shell run by the framework).</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">&lt;private&gt;</b> <b class="method">custom-setup</b> <i class="arg">cmd</i></a></dt>
<dd><p>This method specifies a command prefix which will be run all the
regular setup of an officer from its specification is done, to perform
customizations.</p>
<p>The <b class="cmd">&lt;private&gt;</b> here ignores such calls.</p>
<p>The method exists only to avoid having to special-case code the
places propagating these commands down the hierarchy.</p></dd>
<dt><a name="8"><b class="cmd">&lt;private&gt;</b> <b class="method">find</b> <i class="arg">path</i></a></dt>
<dd><p>This method returns the instance command of the sub-ordinate with the
given <i class="arg">path</i> of names. An error is thrown if such a sub-ordinate
does not exist, i.e. whenever <i class="arg">path</i> is not empty, as a private
has no sub-ordinates, ever.</p>
<p>Note, as implied above, an empty <i class="arg">path</i> is allowed and
refers to the private itself.</p>
<p>See also method <b class="method">find</b> of <b class="package">cdmr::officer</b> for the
high-end of the recursion which may end in this method.</p>
<dl class="arguments">
<dt>string <i class="arg">path</i></dt>
<dd><p>The path of names to the sub-ordinate to look for.</p></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">&lt;private&gt;</b> <b class="method">help</b> <span class="opt">?<i class="arg">prefix</i>?</span></a></dt>
<dd><p>This method returns the help information for the private and its
parameters. The <i class="arg">prefix</i>, if specified provides the name of the
private within the help data. It defaults to the empty string.
The result of the command is a structure of the form
described in section <span class="sectref"><a href="#section4">Help Information</a></span>.</p>
<dl class="arguments">
<dt>string <i class="arg">prefix</i></dt>
<dd><p>The name to use for the private within the generated help.</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">&lt;private&gt;</b> <b class="method">unknown</b> <i class="arg">m</i> <span class="opt">?<i class="arg">word</i>...?</span></a></dt>
<dd><p>This method overrides the standard behaviour for unknown methods.
Instead of throwing an error they are routed to the hidden container
of the private's parameters, of class <b class="package"><a href="cmdr_config.html">cmdr::config</a></b>.</p>
<dl class="arguments">
<dt>string <i class="arg">m</i></dt>
<dd><p>The name of the unknown method.</p></dd>
<dt>string <i class="arg">word</i></dt>
<dd><p>The argument (one or more) of the unknown method.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section4" class="section"><h2><a name="section4">Help Information</a></h2>
<p>The help information generated by various places of the framework
is a dictionary containing the following keys:</p>
<dl class="definitions">
<dt>arguments</dt>
<dd><p>A list of strings, the names of the command arguments, in order.
These names are keys into the <b class="variable">parameters</b> sub-dictionary.</p></dd>
<dt>desc</dt>
<dd><p>The command's description, i.e. help text.</p></dd>
<dt>opt2para</dt>
<dd><p>A dictionary mapping option flags to option names.
These names are keys into the <b class="variable">parameters</b> sub-dictionary.</p></dd>
<dt>options</dt>
<dd><p>A dictionary mapping option names to their descriptions.</p></dd>
<dt>parameters</dt>
<dd><p>A dictionary mapping parameter names to their definition.
Each definition is a dictionary containing the keys below.
See also package <b class="package"><a href="cmdr_parameter.html">cmdr::parameter</a></b>.</p>
<dl class="definitions">
<dt>cmdline</dt>
<dd><p>Output of method <b class="method">cmdline</b>.</p></dd>
<dt>code</dt>
<dd><p>Output of method <b class="method">code</b>.</p></dd>
<dt>default</dt>
<dd><p>Output of method <b class="method">default</b>.</p></dd>
<dt>defered</dt>
<dd><p>Output of method <b class="method">defered</b>.</p></dd>
<dt>description</dt>
<dd><p>Output of method <b class="method">description</b>.</p></dd>
<dt>documented</dt>
<dd><p>Output of method <b class="method">documented</b>.</p></dd>
<dt>flags</dt>
<dd><p>A dictionary mapping flag names to flag
                   types, i.e. <b class="const">primary</b>, <b class="const">alias</b>,
                   or <b class="const">inverted</b>.</p></dd>
<dt>generator</dt>
<dd><p>Output of method <b class="method">generator</b>.</p></dd>
<dt>interactive</dt>
<dd><p>Output of method <b class="method">interactive</b>.</p></dd>
<dt>isbool</dt>
<dd><p>Output of method <b class="method">isbool</b>.</p></dd>
<dt>label</dt>
<dd><p>Output of method <b class="method">label</b>.</p></dd>
<dt>list</dt>
<dd><p>Output of method <b class="method">list</b>.</p></dd>
<dt>ordered</dt>
<dd><p>Output of method <b class="method">ordered</b>.</p></dd>
<dt>presence</dt>
<dd><p>Output of method <b class="method">presence</b>.</p></dd>
<dt>prompt</dt>
<dd><p>Output of method <b class="method">prompt</b>.</p></dd>
<dt>required</dt>
<dd><p>Output of method <b class="method">required</b>.</p></dd>
<dt>threshold</dt>
<dd><p>Output of method <b class="method">threshold</b>.</p></dd>
<dt>type</dt>
<dd><p>Output of method <b class="method">type</b>.</p></dd>
<dt>validator</dt>
<dd><p>Output of method <b class="method">validator</b>.</p></dd>
</dl></dd>
<dt>sections</dt>
<dd><p>A list of sections the command belongs to.
Each section name is a list itself, the path of the section and sub-sections.</p></dd>
<dt>states</dt>
<dd><p>A list of strings, the names of the command's hidden state parameters.
These names are keys into the <b class="variable">parameters</b> sub-dictionary.</p></dd>
</dl>
</div>
<div id="section5" class="section"><h2><a name="section5">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>