officers/private
* Renamed 'ehandler' to intercept. Documented the change. Kept the old
name around, deprecated it.
* Renamed 'shandler' to custom-setup, and documented it. Extended the
implementation to support a list of customizations, instead of a
single.
* Fixed handling of *prefix* for --help. Code wrongly extended the
local copy of the block, instead of the root copy.
Updated docs, change information.
Regenerated the embedded docs.

officers/private
* Renamed 'ehandler' to intercept. Documented the change. Kept the old
name around, deprecated it.
* Renamed 'shandler' to custom-setup, and documented it. Extended the
implementation to support a list of cusomizations, instead of a
single.
* Fixed handling of *prefix* for --help. Code wrongly extended the
local copy of the block, instead of the root copy.
Updated docs, change information.
Regenerated the embedded docs.

[list_begin arguments]
[arg_def string word]
The words of the command line to parse and match to parameters.
[list_end][comment arguments]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method ehandler] [arg cmd]]
This method specifies a command prefix to wrap around the parsing of
the command line for the officer, and the execution of its action.
[list_begin arguments]
[arg_def cmd-prefix cmd]
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 officer,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).
[list_end][comment arguments]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method exit]]
This hook-method for the main shell returns a boolean value indicating
whether the main shell was stopped and has to exit ([const true]), or
not ([const false]).

[list_begin arguments]
[arg_def string word]
The words of the command line to parse and match to parameters.
[list_end][comment arguments]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method intercept] [arg cmd]]
[call [cmd <officer>] [method ehandler] [arg cmd]]
[emph Note:] While the form [method ehandler] is still usable, it isdeprecated 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 officer, and the execution of its action.
[list_begin arguments]
[arg_def cmd-prefix cmd]
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 officer,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).
[list_end][comment arguments]
[comment {- - -- --- ----- -------- -------------}][call [cmd <officer>] [method custom-setup] [arg cmd]]This method specifies a command prefix which will be run all theregular setup of the officer from its specification is done, toperform customizations.[para] An example of this can be seen in the package[package cmdr::history]. It provides a command[cmd cmdr::history::attach] to add the history management commands tothe actor in question, suitable as argument to this method.[para] When called multiple times, the specified commandsaccumulate. This makes it easy to specify several indepedentcustomizations.[list_begin arguments][arg_def cmd-prefix cmd]A command prefix taking a single argument, the instance command of an[package cmd::actor]. The command prefix has full access to this actorand can modify it as it sees fit. The common use case will be theextension of the actor with additional subordinates.[list_end][comment arguments]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method exit]]
This hook-method for the main shell returns a boolean value indicating
whether the main shell was stopped and has to exit ([const true]), or
not ([const false]).

[list_begin arguments]
[arg_def string word]
The words of the command line to parse and match to parameters.
[list_end][comment arguments]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd <private>] [method ehandler] [arg cmd]]
This method specifies a command prefix to wrap around the parsing of
the command line for the private, and the execution of its action.
[list_begin arguments]
[arg_def cmd-prefix cmd]
A command prefix taking a single argument, a script. The command
................................................................................
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).
[list_end][comment arguments]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd <private>] [method find] [arg path]]
This method returns the instance command of the sub-ordinate with the
given [arg path] of names. An error is thrown if such a sub-ordinate
does not exist, i.e. whenever [arg path] is not empty, as a private
has no sub-ordinates, ever.

[list_begin arguments]
[arg_def string word]
The words of the command line to parse and match to parameters.
[list_end][comment arguments]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd <private>] [method intercept] [arg cmd]]
[call [cmd <private>] [method ehandler] [arg cmd]]
[emph Note:] While the form [method ehandler] is still usable, it isdeprecated 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.
[list_begin arguments]
[arg_def cmd-prefix cmd]
A command prefix taking a single argument, a script. The command
................................................................................
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).
[list_end][comment arguments]
[comment {- - -- --- ----- -------- -------------}][call [cmd <private>] [method custom-setup] [arg cmd]]This method specifies a command prefix which will be run all theregular setup of an officer from its specification is done, to performcustomizations.[para] The [cmd <private>] here ignores such calls.[para] The method exists only to avoid having to special-case code theplaces propagating these commands down the hierarchy.
[comment {- - -- --- ----- -------- -------------}]
[call [cmd <private>] [method find] [arg path]]
This method returns the instance command of the sub-ordinate with the
given [arg path] of names. An error is thrown if such a sub-ordinate
does not exist, i.e. whenever [arg path] is not empty, as a private
has no sub-ordinates, ever.

[subsection {Changes for version 1.2}]
[vset tcllib http://core.tcl.tk/tcllib/doc/trunk/embedded/www]
[vset tm [vset tcllib]/tcllib/files/modules]
[list_begin enumerated]
[comment {- - -- --- ----- -------- ------------- ---------------------}]
[enum] Extended the package [package cmdr::validate] with many new standard validation types:[list_begin enumerated]
[enum] Double
[enum] Percent
[enum] Posint (positive integers, > 0)
[enum] Paths and channels
[list_begin enumerated]
[enum] Readable file
[enum] Writable file
[enum] Read/writable file
[enum] Readable directory
[enum] Read/writeable directory
[enum] readable path
[enum] Read/writable path
[enum] Readable path, as channel
[enum] Writable path, as channel
[enum] Read/writable path, as channel
[list_end]
[enum] Date and time related:
[list_begin enumerated]
[enum] ISO-8601 date/time,
[enum] year
[enum] weekday,
[enum] hour:minute
[list_end]
[list_end]
[enum] In package [package cmdr::validate], modified the integer validation type to have a proper internal representation: decimal. Input in octal, hex, etc. is now normalized to this.[enum] Extended package [package cmdr::validate::common] with more helper commands for the generation of validation failure messages
[list_begin enumerated]
[enum] [cmd fail-unknown-thing-msg]
[enum] [cmd fail-unknown-simple]
[enum] [cmd fail-unknown-simple-msg]
[enum] [cmd fail-known-thing-msg]
[enum] [cmd fail-known-simple]
[enum] [cmd fail-known-simple-msg]
[list_end]
[enum] Added various new supporting packages:[list_begin definitions]
[def [package cmdr::tty]]
Test for terminal. [def [package cmdr::color]] Color management, ansi control sequences.
[def [package cmdr::ask]] User interaction commands.
[def [package cmdr::pager]] Text display with automatic invokation of a pager for tall
output.
[def [package cmdr::history]] Pluggable management of command history.
[def [package cmdr::table]]
Table formatting, a simplified interface to
[uri [vset tcllib]/toc.html Tcllib]'s
[package struct::matrix] and [package report] packages.[def [package cmdr::validate::valtype-support]]
Even more validation types, now as wrappers around the validation commands provided by
[uri [vset tcllib]/toc.html Tcllib]:
[list_begin enumerated]
[enum] [uri [vset tm]/valtype/cc_amex.html valtype::creditcard::amex]
[enum] [uri [vset tm]/valtype/cc_discover.html valtype::creditcard::discover]
[enum] [uri [vset tm]/valtype/cc_mastercard.html valtype::creditcard::mastercard]
[enum] [uri [vset tm]/valtype/cc_visa.html valtype::creditcard::visa]
[enum] [uri [vset tm]/valtype/ean13.html valtype::gs1::ean13]
[enum] [uri [vset tm]/valtype/iban.html valtype::iban]
[enum] [uri [vset tm]/valtype/imei.html valtype::imei]
[enum] [uri [vset tm]/valtype/isbn.html valtype::isbn]
[enum] [uri [vset tm]/valtype/luhn.html valtype::luhn]
[enum] [uri [vset tm]/valtype/luhn5.html valtype::luhn5]
[enum] [uri [vset tm]/valtype/usnpi.html valtype::usnpi]
[enum] [uri [vset tm]/valtype/verhoeff.html valtype::verhoeff]
[list_end]
[list_end]
[enum] Extended package [package cmdr::officer] with [list_begin enumerated] [enum] Support for per-officer options. The most common use
case will likely be the declaration of global options in
the root officer.
[para] Related to this, a new common block [const *config*] is
set to the active [package config] 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.
[enum] Support for an option [option -extend] for common
blocks, allowing their extension in a subordinate
instead of just replacing the entire content.
[enum] Support to accept all unique command prefixes of an officer's subordinates for dispatch. [list_end][enum] Extended package [package cmdr::parameter] with [list_begin enumerated] [enum] Support for the specification of negative aliases for boolean options, i.e. representing the inverted option.
[para] See the DSL commands [cmd neg-alias] and [cmd !alias] in
[term {Cmdr - Parameter Specification Language}].
[enum] 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. [para] See DSL command [cmd label] in
[term {Cmdr - Parameter Specification Language}].
[list_end][enum] Help system changes [list_begin enumerated] [enum] Modified it to use the [const short] format for interior
nodes of the command hierarchy by default.
[enum] Modified it to exclude auto-added commands from the output generated by format [const by-category].
[enum] Modified the format [const full] to show the option arguments for those which have such. See also the extension of package [package cmdr::parameter] with support for option labels, this is what is used here. [enum] Modified it to declare a standard global option [option --help] (with aliases [option -h] and [option -?]). Using the option invokes the standard help (command) on the current command, if any, or the global help if there is no command. [enum] 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. [list_end][enum] Fixed the handling of common block [const *all*] in package [package cmdr::officer]. While it was ok trapping and ignoring a missing definition of this block, trapping everything which could go wrong was not. [para][uri http://core.tcl.tk/akupries/cmdr/info/9159f68bc35d9747 Details].[enum] Fixed a long-standing bug of package [package cmdr::config] in the forced calculation of parameter values in method [method Force]). 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. [para] 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. [para][uri http://core.tcl.tk/akupries/cmdr/info/f74095b252d4c9df Details][enum] Modified the formatting of [package cmdr::config] 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.[enum] General fixes to testsuite, code comments, bogus variable names, typos in error messages, etc.
[comment {- - -- --- ----- -------- ------------- ---------------------}]
[list_end]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd description] [arg text]]
This command declares the help text of the [term officer].
[comment {- - -- --- ----- -------- -------------}]
[call [cmd ehandler] [arg cmdprefix]]
This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates).
[para] At runtime the framework will call the specified command prefix
with a single argument, a script whose execution is equivalent to the
................................................................................
cleanup code transient state [emph will] leak between multiple
commands run from such a shell, something which is definitely not
wanted.
[list_end]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd shandler] [arg cmdprefix]]
This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates).
[para] At runtime the framework will call the specified command prefix
with a single argument, the command of the actor we wish toinitialize.
The command prefix is then allowed to modify that actor as it sees
fit. The common use case will be the extension of the object with
additional subordinates.
An example of this is the package [package cmdr::history] which
provides a command [cmd cmdr::history::attach] to add the history

[comment {- - -- --- ----- -------- -------------}]
[call [cmd description] [arg text]]
This command declares the help text of the [term officer].
[comment {- - -- --- ----- -------- -------------}]
[call [cmd intercept] [arg cmdprefix]]
[call [cmd ehandler] [arg cmdprefix]]
[emph Note:] While the form [cmd ehandler] is still usable, it isdeprecated and will be removed in a future release.
This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates).
[para] At runtime the framework will call the specified command prefix
with a single argument, a script whose execution is equivalent to the
................................................................................
cleanup code transient state [emph will] leak between multiple
commands run from such a shell, something which is definitely not
wanted.
[list_end]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd custom-setup] [arg cmdprefix]]
This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates).
[para] When called multiple times, the specified commandsaccumulate. This makes it easy to specify several indepedentcustomizations.
[para] At runtime the framework will invoke all the specified commands
with a single argument, the command of the actor to initialize.
The command prefix is then allowed to modify that actor as it sees
fit. The common use case will be the extension of the object with
additional subordinates.
An example of this is the package [package cmdr::history] which
provides a command [cmd cmdr::history::attach] to add the history

Changes to doc/parts/dsl_para_support.inc.

21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

The returned callback sets the [arg name]d sibling parameter to the
specified [arg value]. A simple method of communication between
parameters of a command.
[para] Useful for use with [cmd when-set] and/or [cmd when-complete]
[call [cmd touch] [arg name] [arg value]]
The returned callback sets the [arg name]d sibling parameter to the
specified [arg value], if and only if that parameter exists. A simple
method of communication between parameters of a command, where the
sibling may not exists, depending on usage context.
[para] Useful for use with [cmd when-set] and/or [cmd when-complete]

|

21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

The returned callback sets the [arg name]d sibling parameter to the
specified [arg value]. A simple method of communication between
parameters of a command.
[para] Useful for use with [cmd when-set] and/or [cmd when-complete]
[call [cmd touch?] [arg name] [arg value]]
The returned callback sets the [arg name]d sibling parameter to the
specified [arg value], if and only if that parameter exists. A simple
method of communication between parameters of a command, where the
sibling may not exists, depending on usage context.
[para] Useful for use with [cmd when-set] and/or [cmd when-complete]

For availability please read \fICmdr - How To Get The Sources\fR\&.
.PP
This document provides an overview of the changes \fBcmdr\fR
underwent from version to version\&.
.SH CHANGES
.SS "CHANGES FOR VERSION 1\&.2"
.IP [1]
Extended the package \fBcmdr::validate\fR with many newstandard validation types:
.RS
.IP [1]
Double
.IP [2]
Percent
.IP [3]
Posint (positive integers, > 0)
................................................................................
.IP [10]
Read/writable path, as channel
.RE
.IP [5]
Date and time related:
.RS
.IP [1]
ISO-8601 date/time,
.IP [2]
year
.IP [3]
weekday,
.IP [4]
hour:minute
.RE
.RE
.IP [2]
In package \fBcmdr::validate\fR, modified the integervalidation type to have a proper internal representation:decimal\&. Input in octal, hex, etc\&. is now normalized to this\&..IP [3]Extended package \fBcmdr::validate::common\fR with morehelper commands for the generation of validation failuremessages
.RS
.IP [1]
\fBfail-unknown-thing-msg\fR
.IP [2]
\fBfail-unknown-simple\fR
.IP [3]
\fBfail-unknown-simple-msg\fR
.IP [4]
\fBfail-known-thing-msg\fR
.IP [5]
\fBfail-known-simple\fR
.IP [6]
\fBfail-known-simple-msg\fR
.RE
.IP [4]
Added various new supporting packages:
.RS
.TP
\fBcmdr::tty\fR
Test for terminal\&.
.TP
\fBcmdr::color\fR
Color management, ansi control sequences\&.
.TP
\fBcmdr::ask\fR
User interaction commands\&.
.TP
\fBcmdr::pager\fR
Text display with automatic invokation of a pager for tall
output\&.
.TP
\fBcmdr::history\fR
Pluggable management of command history\&.
.TP
\fBcmdr::table\fR
Table formatting, a simplified interface to
\fITcllib\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/toc\&.html]'s
\fBstruct::matrix\fR and \fBreport\fR packages\&.
.TP
\fBcmdr::validate::valtype-support\fR
Even more validation types, now as wrappers around the
validation commands provided by
\fITcllib\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/toc\&.html]:
.RS
.IP [1]
\fIvaltype::creditcard::amex\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/cc_amex\&.html]
.IP [2]
\fIvaltype::creditcard::discover\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/cc_discover\&.html]
.IP [3]
................................................................................
.IP [11]
\fIvaltype::usnpi\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/usnpi\&.html]
.IP [12]
\fIvaltype::verhoeff\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/verhoeff\&.html]
.RE
.RE
.IP [5]
Extended package \fBcmdr::officer\fR with.RS.IP [1]Support for per-officer options\&. The most common use
case will likely be the declaration of global options in
the root officer\&.
.sp
Related to this, a new common block \fB*config*\fR is
set to the active \fBconfig\fR instance, which will
be different from the defining instance, for per-officeroptions\&. This gives the per-officer options access to
the arguments (and options) of the current command,
instead of only their own sibling options\&.
.IP [2]
Support for an option \fB-extend\fR for common
blocks, allowing their extension in a subordinate
instead of just replacing the entire content\&.
.IP [3]
Support to accept all unique command prefixes of anofficer's subordinates for dispatch\&..RE.IP [6]Extended package \fBcmdr::parameter\fR with.RS.IP [1]Support for the specification of negative aliases forboolean options, i\&.e\&. representing the inverted option\&.
.spSee the DSL commands \fBneg-alias\fR and \fB!alias\fR in
\fICmdr - Parameter Specification Language\fR\&.
.IP [2]
Support for option labeling, for use in the generatedhelp, to make it more descriptive\&. Options for which no
label is specified will use their name as fallback\&..sp
See DSL command \fBlabel\fR in
\fICmdr - Parameter Specification Language\fR\&.
.RE
.IP [7]
Help system changes.RS
.IP [1]
Modified it to use the \fBshort\fR format for interior
nodes of the command hierarchy by default\&.
.IP [2]
Modified it to exclude auto-added commands from the
output generated by format \fBby-category\fR\&.
.IP [3]Modified the format \fBfull\fR to show the optionarguments for those which have such\&. See also theextension of package \fBcmdr::parameter\fR withsupport for option labels, this is what is used here\&..IP [4]Modified it to declare a standard global option\fB--help\fR (with aliases \fB-h\fR and\fB-?\fR)\&. Using the option invokes the standard help(command) on the current command, if any, or the globalhelp if there is no command\&..IP [5]Modified to use a minimum width of 10 characters fordescriptions\&. If the user narrowed the terminal this farthen having the text either cut off at the right edge,or wrapped around is not worse then the help trying towrap the sentence with word boundaries, etc\&. Also,trying to use negative width threw Tcl errors\&..RE.IP [8]Fixed the handling of common block \fB*all*\fR in package\fBcmdr::officer\fR\&. While it was ok trapping and ignoringa missing definition of this block, trapping everything whichcould go wrong was not\&..sp\fIDetails\fR [http://core\&.tcl\&.tk/akupries/cmdr/info/9159f68bc35d9747]\&..IP [9]Fixed a long-standing bug of package \fBcmdr::config\fR inthe forced calculation of parameter values in method\fBForce\fR)\&. Any error in the calculations left an internalflag set, causing future invokations to believe to be in arecursive call and thus do nothing\&..spWhile this had no effect on regular operation, i\&.e\&.with the application exiting after each command, in interactivemode this misbehaviour disabled all checks and validations forthe command in question, and also retained old parametervalues\&..sp\fIDetails\fR [http://core\&.tcl\&.tk/akupries/cmdr/info/f74095b252d4c9df]
.IP [10]
Modified the formatting of \fBcmdr::config\fR state wheninteractively entering it for a private\&. Parameter names noware shown as declared, and an additional flag characterindicates if it is inherited from above, or not\&..IP [11]General fixes to testsuite, code comments, bogus variablenames, typos in error messages, etc\&.
.PP
.SS "CHANGES FOR VERSION 1\&.1"
.IP [1]
Fixed broken requirement references in the meta data of packages
\fBcmdr::help::json\fR and \fBcmdr::help::sql\fR\&.
.IP [2]
Fixed initialization issues in the help generator\&.

.sp
\fBcommon\fR \fIname\fR \fB-extend\fR \fB--\fR \fItext\fR
.sp
\fBdefault\fR
.sp
\fBdescription\fR \fItext\fR
.sp
\fBehandler\fR \fIcmdprefix\fR
.sp
\fBshandler\fR \fIcmdprefix\fR
.sp
\fBofficer\fR \fIname\fR \fIscript\fR
.sp
\fBprivate\fR \fIname\fR \fIscript\fR \fIcmdprefix\fR
.sp
\fBundocumented\fR
.sp
................................................................................
word does not match any of the commands known to this \fIofficer\fR
this default is used\&. If no default is specified an error will be
thrown instead\&.
.TP
\fBdescription\fR \fItext\fR
This command declares the help text of the \fIofficer\fR\&.
.TP
\fBehandler\fR \fIcmdprefix\fR
This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates)\&.
.sp
At runtime the framework will call the specified command prefix
with a single argument, a script whose execution is equivalent to the
phases \fIParsing\fR, \fICompletion\fR, and \fIExecution\fR of the
................................................................................
This is especially important if the interactive command line shells of
the framework are enabled\&. Without such a handler and its bespoke
cleanup code transient state \fIwill\fR leak between multiple
commands run from such a shell, something which is definitely not
wanted\&.
.RE
.TP
\fBshandler\fR \fIcmdprefix\fR
This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates)\&.
.sp
At runtime the framework will call the specified command prefix
with a single argument, the command of the actor we wish toinitialize\&.
The command prefix is then allowed to modify that actor as it sees
fit\&. The common use case will be the extension of the object with
additional subordinates\&.
An example of this is the package \fBcmdr::history\fR which
provides a command \fBcmdr::history::attach\fR to add the history
management commands to the actor in question\&.
.TP

.sp
\fBcommon\fR \fIname\fR \fB-extend\fR \fB--\fR \fItext\fR
.sp
\fBdefault\fR
.sp
\fBdescription\fR \fItext\fR
.sp
\fBintercept\fR \fIcmdprefix\fR.sp
\fBehandler\fR \fIcmdprefix\fR
.sp
\fBcustom-setup\fR \fIcmdprefix\fR
.sp
\fBofficer\fR \fIname\fR \fIscript\fR
.sp
\fBprivate\fR \fIname\fR \fIscript\fR \fIcmdprefix\fR
.sp
\fBundocumented\fR
.sp
................................................................................
word does not match any of the commands known to this \fIofficer\fR
this default is used\&. If no default is specified an error will be
thrown instead\&.
.TP
\fBdescription\fR \fItext\fR
This command declares the help text of the \fIofficer\fR\&.
.TP
\fBintercept\fR \fIcmdprefix\fR.TP
\fBehandler\fR \fIcmdprefix\fR
\fINote:\fR While the form \fBehandler\fR is still usable, it isdeprecated and will be removed in a future release\&.
This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates)\&.
.sp
At runtime the framework will call the specified command prefix
with a single argument, a script whose execution is equivalent to the
phases \fIParsing\fR, \fICompletion\fR, and \fIExecution\fR of the
................................................................................
This is especially important if the interactive command line shells of
the framework are enabled\&. Without such a handler and its bespoke
cleanup code transient state \fIwill\fR leak between multiple
commands run from such a shell, something which is definitely not
wanted\&.
.RE
.TP
\fBcustom-setup\fR \fIcmdprefix\fR
This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates)\&.
.sp
When called multiple times, the specified commandsaccumulate\&. This makes it easy to specify several indepedentcustomizations\&..sp
At runtime the framework will invoke all the specified commands
with a single argument, the command of the actor to initialize\&.
The command prefix is then allowed to modify that actor as it sees
fit\&. The common use case will be the extension of the object with
additional subordinates\&.
An example of this is the package \fBcmdr::history\fR which
provides a command \fBcmdr::history::attach\fR to add the history
management commands to the actor in question\&.
.TP

.sp
\fBwhen-set\fR \fIcmdprefix\fR
.sp
\fBstop!\fR
.sp
\fBtouch\fR \fIname\fR \fIvalue\fR
.sp
\fBtouch\fR \fIname\fR \fIvalue\fR
.sp
\fBdisallow\fR \fIname\fR
.sp
.BE
.SH DESCRIPTION
.PP
Welcome to the Cmdr project, written by Andreas Kupries\&.
................................................................................
\fBtouch\fR \fIname\fR \fIvalue\fR
The returned callback sets the \fIname\fRd sibling parameter to the
specified \fIvalue\fR\&. A simple method of communication between
parameters of a command\&.
.sp
Useful for use with \fBwhen-set\fR and/or \fBwhen-complete\fR
.TP
\fBtouch\fR \fIname\fR \fIvalue\fR
The returned callback sets the \fIname\fRd sibling parameter to the
specified \fIvalue\fR, if and only if that parameter exists\&. A simple
method of communication between parameters of a command, where the
sibling may not exists, depending on usage context\&.
.sp
Useful for use with \fBwhen-set\fR and/or \fBwhen-complete\fR
.TP

.sp
\fBwhen-set\fR \fIcmdprefix\fR
.sp
\fBstop!\fR
.sp
\fBtouch\fR \fIname\fR \fIvalue\fR
.sp
\fBtouch?\fR \fIname\fR \fIvalue\fR
.sp
\fBdisallow\fR \fIname\fR
.sp
.BE
.SH DESCRIPTION
.PP
Welcome to the Cmdr project, written by Andreas Kupries\&.
................................................................................
\fBtouch\fR \fIname\fR \fIvalue\fR
The returned callback sets the \fIname\fRd sibling parameter to the
specified \fIvalue\fR\&. A simple method of communication between
parameters of a command\&.
.sp
Useful for use with \fBwhen-set\fR and/or \fBwhen-complete\fR
.TP
\fBtouch?\fR \fIname\fR \fIvalue\fR
The returned callback sets the \fIname\fRd sibling parameter to the
specified \fIvalue\fR, if and only if that parameter exists\&. A simple
method of communication between parameters of a command, where the
sibling may not exists, depending on usage context\&.
.sp
Useful for use with \fBwhen-set\fR and/or \fBwhen-complete\fR
.TP

history list ?n? - Show last n history entries\&. Defaults to all\&.
history clear - Drop all history entries
history limit ?n? - Limit history to 'n' entries (n >= 0)\&. Unlimited for n < 0\&.
.CE
.IP
Under most circumstances the attachment is handled through the
\fBshandler\fR method of officers\&. See \fBcmdr::officer\fR, and
the \fBExample\fR for more information\&.
.TP
\fB::cmdr::history\fR \fBsave-to\fR \fIpath\fR
When invoked this command sets the package-wide history save file used
by the commands to the \fIpath\fR\&.
.sp
The result of the command is the empty string\&.
................................................................................
.CS
cmdr history initial-limit 20
cmdr history save-to ~/\&.fx_history
cmdr create fx::fx [file tail $::argv0] {
shandler ::cmdr::history::attach
[\&.\&.\&.]
}
.CE
.SH "BUGS, IDEAS, FEEDBACK"
Both the package(s) and this documentation will undoubtedly contain

history list ?n? - Show last n history entries\&. Defaults to all\&.
history clear - Drop all history entries
history limit ?n? - Limit history to 'n' entries (n >= 0)\&. Unlimited for n < 0\&.
.CE
.IP
Under most circumstances the attachment is handled through the
method \fBcustom-setup\fR of officers\&. See \fBcmdr::officer\fR, and
the \fBExample\fR for more information\&.
.TP
\fB::cmdr::history\fR \fBsave-to\fR \fIpath\fR
When invoked this command sets the package-wide history save file used
by the commands to the \fIpath\fR\&.
.sp
The result of the command is the empty string\&.
................................................................................
.CS
cmdr history initial-limit 20
cmdr history save-to ~/\&.fx_history
cmdr create fx::fx [file tail $::argv0] {
custom-setup ::cmdr::history::attach
[\&.\&.\&.]
}
.CE
.SH "BUGS, IDEAS, FEEDBACK"
Both the package(s) and this documentation will undoubtedly contain

.sp
\fB<officer>\fR \fBdefault\fR
.sp
\fB<officer>\fR \fBdispatch\fR \fIcmd\fR
.sp
\fB<officer>\fR \fBdo\fR ?\fIword\fR\&.\&.\&.?
.sp
\fB<officer>\fR \fBehandler\fR \fIcmd\fR
.sp
\fB<officer>\fR \fBexit\fR
.sp
\fB<officer>\fR \fBextend\fR \fIpath\fR \fIarguments\fR \fIaction\fR
.sp
\fB<officer>\fR \fBfind\fR \fIpath\fR
.sp
................................................................................
This represents the "Dispatch" phase of command line processing\&.
.RS
.TP
string \fIword\fR
The words of the command line to parse and match to parameters\&.
.RE
.TP
\fB<officer>\fR \fBehandler\fR \fIcmd\fR
This method specifies a command prefix to wrap around the parsing of
the command line for the officer, and the execution of its action\&.
.RS
.TP
cmd-prefix \fIcmd\fR
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 officer,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)\&.
.RE
.TP
\fB<officer>\fR \fBexit\fR
This hook-method for the main shell returns a boolean value indicating
whether the main shell was stopped and has to exit (\fBtrue\fR), or
not (\fBfalse\fR)\&.
.TP
\fB<officer>\fR \fBextend\fR \fIpath\fR \fIarguments\fR \fIaction\fR

.sp
\fB<officer>\fR \fBdefault\fR
.sp
\fB<officer>\fR \fBdispatch\fR \fIcmd\fR
.sp
\fB<officer>\fR \fBdo\fR ?\fIword\fR\&.\&.\&.?
.sp
\fB<officer>\fR \fBintercept\fR \fIcmd\fR.sp
\fB<officer>\fR \fBehandler\fR \fIcmd\fR
.sp\fB<officer>\fR \fBcustom-setup\fR \fIcmd\fR
.sp
\fB<officer>\fR \fBexit\fR
.sp
\fB<officer>\fR \fBextend\fR \fIpath\fR \fIarguments\fR \fIaction\fR
.sp
\fB<officer>\fR \fBfind\fR \fIpath\fR
.sp
................................................................................
This represents the "Dispatch" phase of command line processing\&.
.RS
.TP
string \fIword\fR
The words of the command line to parse and match to parameters\&.
.RE
.TP
\fB<officer>\fR \fBintercept\fR \fIcmd\fR.TP
\fB<officer>\fR \fBehandler\fR \fIcmd\fR
\fINote:\fR While the form \fBehandler\fR is still usable, it isdeprecated 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 officer, and the execution of its action\&.
.RS
.TP
cmd-prefix \fIcmd\fR
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 officer,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)\&.
.RE
.TP\fB<officer>\fR \fBcustom-setup\fR \fIcmd\fRThis method specifies a command prefix which will be run all theregular setup of the officer from its specification is done, toperform customizations\&..spAn example of this can be seen in the package\fBcmdr::history\fR\&. It provides a command\fBcmdr::history::attach\fR to add the history management commands tothe actor in question, suitable as argument to this method\&..spWhen called multiple times, the specified commandsaccumulate\&. This makes it easy to specify several indepedentcustomizations\&..RS.TPcmd-prefix \fIcmd\fRA command prefix taking a single argument, the instance command of an\fBcmd::actor\fR\&. The command prefix has full access to this actorand can modify it as it sees fit\&. The common use case will be theextension of the actor with additional subordinates\&..RE
.TP
\fB<officer>\fR \fBexit\fR
This hook-method for the main shell returns a boolean value indicating
whether the main shell was stopped and has to exit (\fBtrue\fR), or
not (\fBfalse\fR)\&.
.TP
\fB<officer>\fR \fBextend\fR \fIpath\fR \fIarguments\fR \fIaction\fR

.sp
\fB::cmdr::private\fR \fBcreate\fR \fIobj\fR \fIsuper\fR \fIname\fR \fIarguments\fR \fIaction\fR
.sp
\fB<private>\fR \fBcomplete-words\fR \fIparse\fR
.sp
\fB<private>\fR \fBdo\fR ?\fIword\fR\&.\&.\&.?
.sp
\fB<private>\fR \fBehandler\fR \fIcmd\fR
.sp
\fB<private>\fR \fBfind\fR \fIpath\fR
.sp
\fB<private>\fR \fBhelp\fR ?\fIprefix\fR?
.sp
\fB<private>\fR \fBunknown\fR \fIm\fR ?\fIword\fR\&.\&.\&.?
.sp
................................................................................
filled container of parameters\&.
.RS
.TP
string \fIword\fR
The words of the command line to parse and match to parameters\&.
.RE
.TP
\fB<private>\fR \fBehandler\fR \fIcmd\fR
This method specifies a command prefix to wrap around the parsing of
the command line for the private, and the execution of its action\&.
.RS
.TP
cmd-prefix \fIcmd\fR
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)\&.
.RE
.TP
\fB<private>\fR \fBfind\fR \fIpath\fR
This method returns the instance command of the sub-ordinate with the
given \fIpath\fR of names\&. An error is thrown if such a sub-ordinate
does not exist, i\&.e\&. whenever \fIpath\fR is not empty, as a private
has no sub-ordinates, ever\&.
.sp
Note, as implied above, an empty \fIpath\fR is allowed and

.sp
\fB::cmdr::private\fR \fBcreate\fR \fIobj\fR \fIsuper\fR \fIname\fR \fIarguments\fR \fIaction\fR
.sp
\fB<private>\fR \fBcomplete-words\fR \fIparse\fR
.sp
\fB<private>\fR \fBdo\fR ?\fIword\fR\&.\&.\&.?
.sp
\fB<private>\fR \fBintercept\fR \fIcmd\fR.sp
\fB<private>\fR \fBehandler\fR \fIcmd\fR
.sp\fB<private>\fR \fBcustom-setup\fR \fIcmd\fR
.sp
\fB<private>\fR \fBfind\fR \fIpath\fR
.sp
\fB<private>\fR \fBhelp\fR ?\fIprefix\fR?
.sp
\fB<private>\fR \fBunknown\fR \fIm\fR ?\fIword\fR\&.\&.\&.?
.sp
................................................................................
filled container of parameters\&.
.RS
.TP
string \fIword\fR
The words of the command line to parse and match to parameters\&.
.RE
.TP
\fB<private>\fR \fBintercept\fR \fIcmd\fR.TP
\fB<private>\fR \fBehandler\fR \fIcmd\fR
\fINote:\fR While the form \fBehandler\fR is still usable, it isdeprecated 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\&.
.RS
.TP
cmd-prefix \fIcmd\fR
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)\&.
.RE
.TP
\fB<private>\fR \fBcustom-setup\fR \fIcmd\fRThis method specifies a command prefix which will be run all theregular setup of an officer from its specification is done, to performcustomizations\&..spThe \fB<private>\fR here ignores such calls\&..spThe method exists only to avoid having to special-case code theplaces propagating these commands down the hierarchy\&..TP
\fB<private>\fR \fBfind\fR \fIpath\fR
This method returns the instance command of the sub-ordinate with the
given \fIpath\fR of names\&. An error is thrown if such a sub-ordinate
does not exist, i\&.e\&. whenever \fIpath\fR is not empty, as a private
has no sub-ordinates, ever\&.
.sp
Note, as implied above, an empty \fIpath\fR is allowed and

'\"'\" Generated from file 'cmdr_table\&.man' by tcllib/doctools with format 'nroff''\" Copyright (c) 2013-2016 Andreas Kupries'\" Copyright (c) 2013-2016 Documentation, Andreas Kupries'\".TH "cmdr::table" n 0\&.1 doc "Cmdr, a framework for command line parsing and dispatch".\" The -*- nroff -*- definitions below are for supplemental macros used.\" in Tcl/Tk manual entries..\".\" .AP type name in/out ?indent?.\" Start paragraph describing an argument to a library procedure..\" type is type of argument (int, etc.), in/out is either "in", "out",.\" or "in/out" to describe whether procedure reads or modifies arg,.\" and indent is equivalent to second arg of .IP (shouldn't ever be.\" needed; use .AS below instead).\".\" .AS ?type? ?name?.\" Give maximum sizes of arguments for setting tab stops. Type and.\" name are examples of largest possible arguments that will be passed.\" to .AP later. If args are omitted, default tab stops are used..\".\" .BS.\" Start box enclosure. From here until next .BE, everything will be.\" enclosed in one large box..\".\" .BE.\" End of box enclosure..\".\" .CS.\" Begin code excerpt..\".\" .CE.\" End code excerpt..\".\" .VS ?version? ?br?.\" Begin vertical sidebar, for use in marking newly-changed parts.\" of man pages. The first argument is ignored and used for recording.\" the version when the .VS was added, so that the sidebars can be.\" found and removed when they reach a certain age. If another argument.\" is present, then a line break is forced before starting the sidebar..\".\" .VE.\" End of vertical sidebar..\".\" .DS.\" Begin an indented unfilled display..\".\" .DE.\" End of indented unfilled display..\".\" .SO ?manpage?.\" Start of list of standard options for a Tk widget. The manpage.\" argument defines where to look up the standard options; if.\" omitted, defaults to "options". The options follow on successive.\" lines, in three columns separated by tabs..\".\" .SE.\" End of list of standard options for a Tk widget..\".\" .OP cmdName dbName dbClass.\" Start of description of a specific option. cmdName gives the.\" option's name as specified in the class command, dbName gives.\" the option's name in the option database, and dbClass gives.\" the option's class in the option database..\".\" .UL arg1 arg2.\" Print arg1 underlined, then print arg2 normally..\".\" .QW arg1 ?arg2?.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation)..\".\" .PQ arg1 ?arg2?.\" Print an open parenthesis, arg1 in quotes, then arg2 normally.\" (for trailing punctuation) and then a closing parenthesis..\".\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages..if t .wh -1.3i ^B.nr ^l \n(.l.ad b.\" # Start an argument description.de AP.ie !"\\$4"" .TP \\$4.el \{\. ie !"\\$2"" .TP \\n()Cu. el .TP 15.\}.ta \\n()Au \\n()Bu.ie !"\\$3"" \{\\&\\$1 \\fI\\$2\\fP (\\$3).\".b.\}.el \{\.br.ie !"\\$2"" \{\\&\\$1 \\fI\\$2\\fP.\}.el \{\\&\\fI\\$1\\fP.\}.\}...\" # define tabbing values for .AP.de AS.nr )A 10n.if !"\\$1"" .nr )A \\w'\\$1'u+3n.nr )B \\n()Au+15n.\".if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n.nr )C \\n()Bu+\\w'(in/out)'u+2n...AS Tcl_Interp Tcl_CreateInterp in/out.\" # BS - start boxed text.\" # ^y = starting y location.\" # ^b = 1.de BS.br.mk ^y.nr ^b 1u.if n .nf.if n .ti 0.if n \l'\\n(.lu\(ul'.if n .fi...\" # BE - end boxed text (draw box now).de BE.nf.ti 0.mk ^t.ie n \l'\\n(^lu\(ul'.el \{\.\" Draw four-sided box normally, but don't draw top of.\" box if the box started on an earlier page..ie !\\n(^b-1 \{\\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'.\}.el \}\\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'.\}.\}.fi.br.nr ^b 0...\" # VS - start vertical sidebar.\" # ^Y = starting y location.\" # ^v = 1 (for troff; for nroff this doesn't matter).de VS.if !"\\$2"" .br.mk ^Y.ie n 'mc \s12\(br\s0.el .nr ^v 1u...\" # VE - end of vertical sidebar.de VE.ie n 'mc.el \{\.ev 2.nf.ti 0.mk ^t\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'.sp -1.fi.ev.\}.nr ^v 0...\" # Special macro to handle page bottom: finish off current.\" # box/sidebar if in box/sidebar mode, then invoked standard.\" # page bottom macro..de ^B.ev 2'ti 0'nf.mk ^t.if \\n(^b \{\.\" Draw three-sided box if this is the box's first page,.\" draw two sides but no top otherwise..ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c.\}.if \\n(^v \{\.nr ^x \\n(^tu+1v-\\n(^Yu\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c.\}.bp'fi.ev.if \\n(^b \{\.mk ^y.nr ^b 2.\}.if \\n(^v \{\.mk ^Y.\}...\" # DS - begin display.de DS.RS.nf.sp...\" # DE - end display.de DE.fi.RE.sp...\" # SO - start of list of standard options.de SO'ie '\\$1'' .ds So \\fBoptions\\fR'el .ds So \\fB\\$1\\fR.SH "STANDARD OPTIONS".LP.nf.ta 5.5c 11c.ft B...\" # SE - end of list of standard options.de SE.fi.ft R.LPSee the \\*(So manual entry for details on the standard options....\" # OP - start of full description for a single option.de OP.LP.nf.ta 4cCommand-Line Name: \\fB\\$1\\fRDatabase Name: \\fB\\$2\\fRDatabase Class: \\fB\\$3\\fR.fi.IP...\" # CS - begin code excerpt.de CS.RS.nf.ta .25i .5i .75i 1i...\" # CE - end code excerpt.de CE.fi.RE...\" # UL - underline word.de UL\\$1\l'|0\(ul'\\$2...\" # QW - apply quotation marks to word.de QW.ie '\\*(lq'"' ``\\$1''\\$2.\"" fix emacs highlighting.el \\*(lq\\$1\\*(rq\\$2...\" # PQ - apply parens and quotation marks to word.de PQ.ie '\\*(lq'"' (``\\$1''\\$2)\\$3.\"" fix emacs highlighting.el (\\*(lq\\$1\\*(rq\\$2)\\$3...\" # QR - quoted range.de QR.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3.\"" fix emacs highlighting.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3...\" # MT - "empty" string.de MT.QW ""...BS.SH NAMEcmdr::table \- Cmdr - Simple Table creation.SH SYNOPSISpackage require \fBcmdr::util \fR.sp\fB::cmdr::table\fR \fBgeneral\fR \fIvar\fR \fIheaders\fR \fIscript\fR.sp\fB::cmdr::table\fR \fBdict\fR \fIvar\fR \fIscript\fR.sp\fB::cmdr::table\fR \fBborders\fR ?\fIenable\fR?.sp\fB::cmdr::table\fR \fBshow\fR ?\fIcmd\fR\&.\&.\&.?.sp\fBt\fR \fBborders\fR ?\fIenable\fR?.sp\fBt\fR \fBheaders\fR ?\fIenable\fR?.sp\fBt\fR \fBstyle\fR ?\fIstyle\fR?.sp\fBt\fR \fBadd\fR \fIword\fR\&.\&.\&..sp\fBt\fR \fB+\fR \fIword\fR\&.\&.\&..sp\fBt\fR \fB+=\fR \fIword\fR\&.\&.\&..sp\fBt\fR \fB<<\fR \fIword\fR\&.\&.\&..sp\fBt\fR \fB<=\fR \fIword\fR\&.\&.\&..sp\fBt\fR \fBshow*\fR ?\fIcmd\fR?.sp\fBt\fR \fBshow\fR ?\fIcmd\fR?.sp.BE.SH DESCRIPTION.PPWelcome to the Cmdr project, written by Andreas Kupries\&..PPFor availability please read \fICmdr - How To Get The Sources\fR\&..PPThis package provides convenience commands for the easy creation ofsimple tables\&..SH API.TP\fB::cmdr::table\fR \fBgeneral\fR \fIvar\fR \fIheaders\fR \fIscript\fRThis command creates a new table with the words found in the list of\fIheaders\fR as the top row\&.The \fIscript\fR is run in the calling context to configure andpopulate the table\&.The table's object command is stored in the named \fIvar\fR for accessby the \fIscript\fR\&.The result of the command is the table's object command\&..RS.TPvarname \fIvar\fRThe name of the variable in the calling scope the new table's objectcommand will be stored into\&..TPlist \fIheaders\fRThe list of words to user as column headers\&..TPstring \fIscript\fRThe tcl script to be run to configure and populate the table\&..RE.TP\fB::cmdr::table\fR \fBdict\fR \fIvar\fR \fIscript\fRThis command creates a new table intended for the display of a Tcldictionary\&.It will have two columns titled \fBKey\fR and \fBValue\fR\&.The \fIscript\fR is run in the calling context to configure andpopulate the table\&.The table's object command is stored in the named \fIvar\fR for accessby the \fIscript\fR\&.The result of the command is the table's object command\&..RS.TPvarname \fIvar\fRThe name of the variable in the calling scope the new table's objectcommand will be stored into\&..TPstring \fIscript\fRThe tcl script to be run to configure and populate the table\&..RE.TP\fB::cmdr::table\fR \fBborders\fR ?\fIenable\fR?This command configures the global \fIborder\fR setting, whichindicates the (non)use of borders by the tables of this package\&. Notethat changes to this setting influence only the tables created afterthe change\&. Existing tables are not modified\&..spThe result of the command is the new state of the setting\&..spIf the command is called without an argument it simply returns thecurrent state of the setting, without making changes\&..spThe default value for the setting is \fByes\fR\&.Individual tables can override the global settings via their\fBborders\fR method, see \fBTable API\fR\&..RS.TPboolean \fIenable\fRThe new value of the setting\&. Optional\&..RE.TP\fB::cmdr::table\fR \fBshow\fR ?\fIcmd\fR\&.\&.\&.?This command configures the global \fIshow\fR setting, which is thecommand prefix to use to print a table, if the table is not given aspecific command to use\&. Note that changes to this setting influenceonly the tables created after the change\&. Existing tables are notmodified\&..spThe result of the command is the new state of the setting.spIf the command is called without any arguments it simplyreturns the current state of the setting, without making changes\&..spThe default value for the setting is \fBputs\fR\&..RS.TPword \fIcmd\fRThe command prefix to use for printing a table, as varargs\&.The prefix will be invoked with a single argument, the stringrepresentation of the table\&..RE.PP.SH "TABLE API"This section lists the methods available for configuration andpopulation of the tables created by this package\&..TP\fBt\fR \fBborders\fR ?\fIenable\fR?This is the table-level \fIborders\fR setting\&. On creation a tableinherits the global setting (See \fB::cmdr::table borders\fR)\&. Ifthat is not to suit then this method can be used to override it\&..spThe result of the method is the new state of the setting\&. Whencalled without argument no change is made and the result is thecurrent state of the setting\&..TP\fBt\fR \fBheaders\fR ?\fIenable\fR?This method controls the visibility of the header row\&. By defaultgeneral tables have the header row visisble, while for dict tables theheader is suppressed\&. This method allows the user to override thesedefaults\&..spThe result of the method is the new state of the setting\&. Whencalled without argument no change is made and the result is thecurrent state of the setting\&..TP\fBt\fR \fBstyle\fR ?\fIstyle\fR?This method allows the user to force the use of a completely customstyle\&.Please see the documentation for the Tcllib package \fBreport\fRon how to define table styles\&..spThe package defines four styles of its own, all using thecommon prefix \fBcmdr/table/\fR in their names\&.When no custom style is set the table chooses between these based onits \fIborders\fR and \fIheaders\fR settings\&..spThe result of the method is the new state of the setting\&. Whencalled without argument then no change is made and the result is thecurrent state of the setting\&..spTo revert from a custom style to the automatic choice invokethis method with the empty string as the name of the style\&..TP\fBt\fR \fBadd\fR \fIword\fR\&.\&.\&..TP\fBt\fR \fB+\fR \fIword\fR\&.\&.\&..TP\fBt\fR \fB+=\fR \fIword\fR\&.\&.\&..TP\fBt\fR \fB<<\fR \fIword\fR\&.\&.\&..TP\fBt\fR \fB<=\fR \fIword\fR\&.\&.\&.This method adds a new row to the table, containing the given words\&.If less words than headers are specified the row is padded with empty columns\&.If too many words are specified the superfluous words are ignored\&..spThe result of the method is the empty string\&..TP\fBt\fR \fBshow*\fR ?\fIcmd\fR?This method formats the table into a string and then invokes thecommand prefix \fIcmd\fR to print that string\&. The command prefix isrun at the global namespace and level\&. If the \fIcmd\fR is notspecified the global \fIshow\fR setting is used instead\&..spThe result of the method is the empty string\&..TP\fBt\fR \fBshow\fR ?\fIcmd\fR?This is a variant of method \fBshow*\fR above which not only printsthe table as above, but also destroys it\&..PP.SH "BUGS, IDEAS, FEEDBACK"Both the package(s) and this documentation will undoubtedly containbugs and other problems\&.Please report such at\fICmdr Tickets\fR [https:/core\&.tcl\&.tk/akupries/cmdr]\&..PPPlease also report any ideas you may have for enhancements ofeither package(s) and/or documentation\&..SH KEYWORDSarguments, command hierarchy, command line completion, command line handling, command tree, editing command line, help for command line, hierarchy of commands, interactive command shell, optional arguments, options, parameters, processing command line, tree of commands.SH COPYRIGHT.nfCopyright (c) 2013-2016 Andreas KupriesCopyright (c) 2013-2016 Documentation, Andreas Kupries.fi

<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/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>

<div class="synopsis">
<ul class="syntax">
<li><a href="#1"><b class="cmd">alias</b> <i class="arg">name</i> <b class="const">=</b> <i class="arg">name'</i>...</a></li>
<li><a href="#2"><b class="cmd">alias</b> <i class="arg">name</i></a></li>
<li><a href="#3"><b class="cmd">common</b> <i class="arg">name</i> <b class="option">-extend</b> <b class="option">--</b> <i class="arg">text</i></a></li>
<li><a href="#4"><b class="cmd">default</b></a></li>
<li><a href="#5"><b class="cmd">description</b> <i class="arg">text</i></a></li>
<li><a href="#6"><b class="cmd">ehandler</b> <i class="arg">cmdprefix</i></a></li>
<li><a href="#7"><b class="cmd">shandler</b> <i class="arg">cmdprefix</i></a></li>
<li><a href="#8"><b class="cmd">officer</b> <i class="arg">name</i> <i class="arg">script</i></a></li>
<li><a href="#9"><b class="cmd">private</b> <i class="arg">name</i> <i class="arg">script</i> <i class="arg">cmdprefix</i></a></li>
<li><a href="#10"><b class="cmd">undocumented</b></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 document is for users of the cmdr framework. It introduces the
................................................................................
command to use at runtime.
This means that if during &quot;Dispatch&quot; phase the currently processed
word does not match any of the commands known to this <i class="term">officer</i>
this default is used. If no default is specified an error will be
thrown instead.</p></dd>
<dt><a name="5"><b class="cmd">description</b> <i class="arg">text</i></a></dt>
<dd><p>This command declares the help text of the <i class="term">officer</i>.</p></dd>
<dt><a name="6"><b class="cmd">ehandler</b> <i class="arg">cmdprefix</i></a></dt>
<dd><p>This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates).</p>
<p>At runtime the framework will call the specified command prefix
with a single argument, a script whose execution is equivalent to the
phases <i class="term">Parsing</i>, <i class="term">Completion</i>, and <i class="term">Execution</i> of the
framework, as described in <i class="term"><a href="cmdr_flow.html">Cmdr - Runtime Processing Flow</a></i>.
The handler <em>must</em> call this script, and can perform any
................................................................................
and/or actions may have set during their execution.
This is especially important if the interactive command line shells of
the framework are enabled. Without such a handler and its bespoke
cleanup code transient state <em>will</em> leak between multiple
commands run from such a shell, something which is definitely not
wanted.</p></li>
</ol></dd>
<dt><a name="7"><b class="cmd">shandler</b> <i class="arg">cmdprefix</i></a></dt>
<dd><p>This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates).</p>
<p>At runtime the framework will call the specified command prefix
with a single argument, the command of the actor we wish toinitialize.
The command prefix is then allowed to modify that actor as it sees
fit. The common use case will be the extension of the object with
additional subordinates.
An example of this is the package <b class="package"><a href="cmdr_history.html">cmdr::history</a></b> which
provides a command <b class="cmd">cmdr::history::attach</b> to add the history
management commands to the actor in question.</p></dd>
<dt><a name="8"><b class="cmd">officer</b> <i class="arg">name</i> <i class="arg">script</i></a></dt>
<dd><p>This command creates a named subordinate <i class="term">officer</i> with its
specification <i class="arg">script</i> of officer commands as described here.</p></dd>
<dt><a name="9"><b class="cmd">private</b> <i class="arg">name</i> <i class="arg">script</i> <i class="arg">cmdprefix</i></a></dt>
<dd><p>This command creates a named subordinate <i class="term">private</i> with its
specification <i class="arg">script</i> of private commands
(See <i class="term"><a href="cmdr_dsl_private.html">Cmdr - Private Specification Language</a></i>), and a command prefix to invoke
when it is chosen.</p>
<p>This command prefix is called with a single argument, the
<b class="package"><a href="cmdr_config.html">cmdr::config</a></b> instance holding the <i class="term">parameter</i>s of the
private.</p>
<p>For an example see section <i class="term">Simple backend</i>
of <i class="term"><a href="cmdr_dsl.html">Cmdr - Introduction to the Specification Language</a></i>.</p></dd>
<dt><a name="10"><b class="cmd">undocumented</b></a></dt>
<dd><p>This command excludes the <i class="term">officer</i> (and its subordinates) from
the generated help.
Note that subordinates reachable through aliases may be included,
under the alias name, if they are not explicitly excluded themselves.</p></dd>
</dl>
<p>Please continue reading with <i class="term"><a href="cmdr_dsl_private.html">Cmdr - Private Specification Language</a></i>.</p>
</div>

<div class="synopsis">
<ul class="syntax">
<li><a href="#1"><b class="cmd">alias</b> <i class="arg">name</i> <b class="const">=</b> <i class="arg">name'</i>...</a></li>
<li><a href="#2"><b class="cmd">alias</b> <i class="arg">name</i></a></li>
<li><a href="#3"><b class="cmd">common</b> <i class="arg">name</i> <b class="option">-extend</b> <b class="option">--</b> <i class="arg">text</i></a></li>
<li><a href="#4"><b class="cmd">default</b></a></li>
<li><a href="#5"><b class="cmd">description</b> <i class="arg">text</i></a></li>
<li><a href="#6"><b class="cmd">intercept</b> <i class="arg">cmdprefix</i></a></li>
<li><a href="#7"><b class="cmd">ehandler</b> <i class="arg">cmdprefix</i></a></li>
<li><a href="#8"><b class="cmd">custom-setup</b> <i class="arg">cmdprefix</i></a></li>
<li><a href="#9"><b class="cmd">officer</b> <i class="arg">name</i> <i class="arg">script</i></a></li>
<li><a href="#10"><b class="cmd">private</b> <i class="arg">name</i> <i class="arg">script</i> <i class="arg">cmdprefix</i></a></li>
<li><a href="#11"><b class="cmd">undocumented</b></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 document is for users of the cmdr framework. It introduces the
................................................................................
command to use at runtime.
This means that if during &quot;Dispatch&quot; phase the currently processed
word does not match any of the commands known to this <i class="term">officer</i>
this default is used. If no default is specified an error will be
thrown instead.</p></dd>
<dt><a name="5"><b class="cmd">description</b> <i class="arg">text</i></a></dt>
<dd><p>This command declares the help text of the <i class="term">officer</i>.</p></dd>
<dt><a name="6"><b class="cmd">intercept</b> <i class="arg">cmdprefix</i></a></dt><dd></dd>
<dt><a name="7"><b class="cmd">ehandler</b> <i class="arg">cmdprefix</i></a></dt>
<dd><p><em>Note:</em> While the form <b class="cmd">ehandler</b> is still usable, it isdeprecated and will be removed in a future release.
This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates).</p>
<p>At runtime the framework will call the specified command prefix
with a single argument, a script whose execution is equivalent to the
phases <i class="term">Parsing</i>, <i class="term">Completion</i>, and <i class="term">Execution</i> of the
framework, as described in <i class="term"><a href="cmdr_flow.html">Cmdr - Runtime Processing Flow</a></i>.
The handler <em>must</em> call this script, and can perform any
................................................................................
and/or actions may have set during their execution.
This is especially important if the interactive command line shells of
the framework are enabled. Without such a handler and its bespoke
cleanup code transient state <em>will</em> leak between multiple
commands run from such a shell, something which is definitely not
wanted.</p></li>
</ol></dd>
<dt><a name="8"><b class="cmd">custom-setup</b> <i class="arg">cmdprefix</i></a></dt>
<dd><p>This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates).</p>
<p>When called multiple times, the specified commandsaccumulate. This makes it easy to specify several indepedentcustomizations.</p>
<p>At runtime the framework will invoke all the specified commands
with a single argument, the command of the actor to initialize.
The command prefix is then allowed to modify that actor as it sees
fit. The common use case will be the extension of the object with
additional subordinates.
An example of this is the package <b class="package"><a href="cmdr_history.html">cmdr::history</a></b> which
provides a command <b class="cmd">cmdr::history::attach</b> to add the history
management commands to the actor in question.</p></dd>
<dt><a name="9"><b class="cmd">officer</b> <i class="arg">name</i> <i class="arg">script</i></a></dt>
<dd><p>This command creates a named subordinate <i class="term">officer</i> with its
specification <i class="arg">script</i> of officer commands as described here.</p></dd>
<dt><a name="10"><b class="cmd">private</b> <i class="arg">name</i> <i class="arg">script</i> <i class="arg">cmdprefix</i></a></dt>
<dd><p>This command creates a named subordinate <i class="term">private</i> with its
specification <i class="arg">script</i> of private commands
(See <i class="term"><a href="cmdr_dsl_private.html">Cmdr - Private Specification Language</a></i>), and a command prefix to invoke
when it is chosen.</p>
<p>This command prefix is called with a single argument, the
<b class="package"><a href="cmdr_config.html">cmdr::config</a></b> instance holding the <i class="term">parameter</i>s of the
private.</p>
<p>For an example see section <i class="term">Simple backend</i>
of <i class="term"><a href="cmdr_dsl.html">Cmdr - Introduction to the Specification Language</a></i>.</p></dd>
<dt><a name="11"><b class="cmd">undocumented</b></a></dt>
<dd><p>This command excludes the <i class="term">officer</i> (and its subordinates) from
the generated help.
Note that subordinates reachable through aliases may be included,
under the alias name, if they are not explicitly excluded themselves.</p></dd>
</dl>
<p>Please continue reading with <i class="term"><a href="cmdr_dsl_private.html">Cmdr - Private Specification Language</a></i>.</p>
</div>

<p>After attachment the actor will accept the following 3 commands:</p>
<pre class="example">
history list ?n? - Show last n history entries. Defaults to all.
history clear - Drop all history entries
history limit ?n? - Limit history to 'n' entries (n &gt;= 0). Unlimited for n &lt; 0.
</pre>
<p>Under most circumstances the attachment is handled through the
<b class="cmd">shandler</b> method of officers. See <b class="package"><a href="cmdr_officer.html">cmdr::officer</a></b>, and
the <span class="sectref"><a href="#section3">Example</a></span> for more information.</p></dd>
<dt><a name="2"><b class="cmd">::cmdr::history</b> <b class="method">save-to</b> <i class="arg">path</i></a></dt>
<dd><p>When invoked this command sets the package-wide history save file used
by the commands to the <i class="arg">path</i>.</p>
<p>The result of the command is the empty string.</p></dd>
<dt><a name="3"><b class="cmd">::cmdr::history</b> <b class="method">initial-limit</b> <i class="arg">limit</i></a></dt>
<dd><p>When invoked this command sets the package-wide limit on history size
................................................................................
<p>Below an example on how to activate history for an officer.
The example was taken from the <b class="cmd">fx</b> application extending the
<b class="cmd">fossil</b> DVCS.</p>
<pre class="example">
cmdr history initial-limit 20
cmdr history save-to ~/.fx_history
cmdr create fx::fx [file tail $::argv0] {
shandler ::cmdr::history::attach
[...]
}
</pre>
</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.

<p>After attachment the actor will accept the following 3 commands:</p>
<pre class="example">
history list ?n? - Show last n history entries. Defaults to all.
history clear - Drop all history entries
history limit ?n? - Limit history to 'n' entries (n &gt;= 0). Unlimited for n &lt; 0.
</pre>
<p>Under most circumstances the attachment is handled through the
method <b class="cmd">custom-setup</b> of officers. See <b class="package"><a href="cmdr_officer.html">cmdr::officer</a></b>, and
the <span class="sectref"><a href="#section3">Example</a></span> for more information.</p></dd>
<dt><a name="2"><b class="cmd">::cmdr::history</b> <b class="method">save-to</b> <i class="arg">path</i></a></dt>
<dd><p>When invoked this command sets the package-wide history save file used
by the commands to the <i class="arg">path</i>.</p>
<p>The result of the command is the empty string.</p></dd>
<dt><a name="3"><b class="cmd">::cmdr::history</b> <b class="method">initial-limit</b> <i class="arg">limit</i></a></dt>
<dd><p>When invoked this command sets the package-wide limit on history size
................................................................................
<p>Below an example on how to activate history for an officer.
The example was taken from the <b class="cmd">fx</b> application extending the
<b class="cmd">fossil</b> DVCS.</p>
<pre class="example">
cmdr history initial-limit 20
cmdr history save-to ~/.fx_history
cmdr create fx::fx [file tail $::argv0] {
custom-setup ::cmdr::history::attach
[...]
}
</pre>
</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.

<li><a href="#3"><b class="cmd">&lt;officer&gt;</b> <b class="method">children</b></a></li>
<li><a href="#4"><b class="cmd">&lt;officer&gt;</b> <b class="method">complete</b> <i class="arg">line</i></a></li>
<li><a href="#5"><b class="cmd">&lt;officer&gt;</b> <b class="method">complete-words</b> <i class="arg">parse</i></a></li>
<li><a href="#6"><b class="cmd">&lt;officer&gt;</b> <b class="method">continued</b> <i class="arg">line</i></a></li>
<li><a href="#7"><b class="cmd">&lt;officer&gt;</b> <b class="method">default</b></a></li>
<li><a href="#8"><b class="cmd">&lt;officer&gt;</b> <b class="method">dispatch</b> <i class="arg">cmd</i></a></li>
<li><a href="#9"><b class="cmd">&lt;officer&gt;</b> <b class="method">do</b> <span class="opt">?<i class="arg">word</i>...?</span></a></li>
<li><a href="#10"><b class="cmd">&lt;officer&gt;</b> <b class="method">ehandler</b> <i class="arg">cmd</i></a></li>
<li><a href="#11"><b class="cmd">&lt;officer&gt;</b> <b class="method">exit</b></a></li>
<li><a href="#12"><b class="cmd">&lt;officer&gt;</b> <b class="method">extend</b> <i class="arg">path</i> <i class="arg">arguments</i> <i class="arg">action</i></a></li>
<li><a href="#13"><b class="cmd">&lt;officer&gt;</b> <b class="method">find</b> <i class="arg">path</i></a></li>
<li><a href="#14"><b class="cmd">&lt;officer&gt;</b> <b class="method">has</b> <i class="arg">name</i></a></li>
<li><a href="#15"><b class="cmd">&lt;officer&gt;</b> <b class="method">hasdefault</b></a></li>
<li><a href="#16"><b class="cmd">&lt;officer&gt;</b> <b class="method">help</b> <span class="opt">?<i class="arg">prefix</i>?</span></a></li>
<li><a href="#17"><b class="cmd">&lt;officer&gt;</b> <b class="method">known</b></a></li>
<li><a href="#18"><b class="cmd">&lt;officer&gt;</b> <b class="method">learn</b> <i class="arg">script</i></a></li>
<li><a href="#19"><b class="cmd">&lt;officer&gt;</b> <b class="method">lookup</b> <i class="arg">name</i></a></li>
<li><a href="#20"><b class="cmd">&lt;officer&gt;</b> <b class="method">prompt1</b></a></li>
<li><a href="#21"><b class="cmd">&lt;officer&gt;</b> <b class="method">prompt2</b></a></li>
<li><a href="#22"><b class="cmd">&lt;officer&gt;</b> <b class="method">report</b> <i class="arg">what</i> <i class="arg">data</i></a></li>
<li><a href="#23"><b class="cmd">&lt;officer&gt;</b> <b class="method">shell-exit</b> <i class="arg">config</i></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>officers</em>, the inner nodes of command
................................................................................
to the sub-ordinates of the officer. When done without error it
recursively invokes the chosen sub-ordinate to continue processing.</p>
<p>This represents the &quot;Dispatch&quot; phase of command line processing.</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="10"><b class="cmd">&lt;officer&gt;</b> <b class="method">ehandler</b> <i class="arg">cmd</i></a></dt>
<dd><p>This method specifies a command prefix to wrap around the parsing of
the command line for the officer, 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 officer,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="11"><b class="cmd">&lt;officer&gt;</b> <b class="method">exit</b></a></dt>
<dd><p>This hook-method for the main shell returns a boolean value indicating
whether the main shell was stopped and has to exit (<b class="const">true</b>), or
not (<b class="const">false</b>).</p></dd>
<dt><a name="12"><b class="cmd">&lt;officer&gt;</b> <b class="method">extend</b> <i class="arg">path</i> <i class="arg">arguments</i> <i class="arg">action</i></a></dt>
<dd><p>A convenience method to create a &quot;private&quot; command underneath this
officer, with the command name <i class="arg">path</i> (a list of names). Any
intermediate officers are created as needed. An error is thrown if any
of the intermediates already exist as a (non-extensible) private, or
if the last command already exists.</p>
<p>The arguments after the <i class="arg">path</i> match the constructor of
privates in number and semantics.</p>
................................................................................
<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>
<dt><a name="13"><b class="cmd">&lt;officer&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> (a list) of names. An error is thrown if such a sub-ordinate
does not exist. This is an extension of <b class="method">lookup</b> to paths of names.</p>
<p>An empty <i class="arg">path</i> is allowed and refers to the officer itself.</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="14"><b class="cmd">&lt;officer&gt;</b> <b class="method">has</b> <i class="arg">name</i></a></dt>
<dd><p>This method returns a boolean value indicating if this officer has a
sub-ordinate of the given <i class="arg">name</i> (<b class="const">true</b>), or not
(<b class="const">false</b>). See also method <b class="method">lookup</b>.</p>
<dl class="arguments">
<dt>string <i class="arg">name</i></dt>
<dd><p>The name of the sub-ordinate to look for.</p></dd>
</dl></dd>
<dt><a name="15"><b class="cmd">&lt;officer&gt;</b> <b class="method">hasdefault</b></a></dt>
<dd><p>This method returns a boolean value indicating if this officer has a
default sub-ordinate (<b class="const">true</b>), or not (<b class="const">false</b>). See also
method <b class="method">default</b>.</p></dd>
<dt><a name="16"><b class="cmd">&lt;officer&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 officer and its
subordinates. The <i class="arg">prefix</i>, if specified provides the name of the
officer 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 officer within the generated help.</p></dd>
</dl></dd>
<dt><a name="17"><b class="cmd">&lt;officer&gt;</b> <b class="method">known</b></a></dt>
<dd><p>This method returns a list containing the names of the subordinate
actors managed by this officer.
See also method <b class="method">children</b> which returns a list of instance
commands.
See also method <b class="method">lookup</b> to map names to instance commands.</p></dd>
<dt><a name="18"><b class="cmd">&lt;officer&gt;</b> <b class="method">learn</b> <i class="arg">script</i></a></dt>
<dd><p>This method takes a regular specification script and uses it to extend
the set of subordinates known to this officer. This is the same type
of script as used during construction, except here we dynamically
extend the officer.</p>
<dl class="arguments">
<dt>script <i class="arg">actions</i></dt>
<dd><p>The specification of the officer's additional subordinates.
Please read <i class="term"><a href="cmdr_dsl_officer.html">Cmdr - Officer Specification Language</a></i> for the details.</p></dd>
</dl></dd>
<dt><a name="19"><b class="cmd">&lt;officer&gt;</b> <b class="method">lookup</b> <i class="arg">name</i></a></dt>
<dd><p>This method returns the instance command of the sub-ordinate with the
given <i class="arg">name</i>. An error is thrown if such a sub-ordinate does not
exist. See also method <b class="method">has</b>.</p>
<dl class="arguments">
<dt>string <i class="arg">name</i></dt>
<dd><p>The name of the sub-ordinate to look for.</p></dd>
</dl></dd>
<dt><a name="20"><b class="cmd">&lt;officer&gt;</b> <b class="method">prompt1</b></a></dt>
<dd><p>This hook-method for the main shell returns the primary prompt string
to use.</p></dd>
<dt><a name="21"><b class="cmd">&lt;officer&gt;</b> <b class="method">prompt2</b></a></dt>
<dd><p>This hook-method for the main shell returns the secondary prompt
string for use within a continuation. As the main shell does not
support continuation lines it should not be invoked ever, and thus
always throws an error should it be invoked.</p></dd>
<dt><a name="22"><b class="cmd">&lt;officer&gt;</b> <b class="method">report</b> <i class="arg">what</i> <i class="arg">data</i></a></dt>
<dd><p>This hook-method for the main shell is responsible for the reporting
of the command results.</p>
<p>Its result is the empty string.</p>
<dl class="arguments">
<dt>enum <i class="arg">what</i></dt>
<dd><p>The result code of the command, one of <b class="const">ok</b>, or <b class="const">fail</b>.</p></dd>
<dt>any <i class="arg">data</i></dt>
<dd><p>The result of the command, or an error message in case of failure.</p></dd>
</dl></dd>
<dt><a name="23"><b class="cmd">&lt;officer&gt;</b> <b class="method">shell-exit</b> <i class="arg">config</i></a></dt>
<dd><p>This is the backend for a private ending the main shell,
be it automatically created by the pacge, or by a user.</p>
<p>The argument is the <b class="package"><a href="cmdr_config.html">cmdr::config</a></b>
instance holding the parameters. The method does not
expect any and ignore it.</p></dd>
</dl>
</div>

<li><a href="#3"><b class="cmd">&lt;officer&gt;</b> <b class="method">children</b></a></li>
<li><a href="#4"><b class="cmd">&lt;officer&gt;</b> <b class="method">complete</b> <i class="arg">line</i></a></li>
<li><a href="#5"><b class="cmd">&lt;officer&gt;</b> <b class="method">complete-words</b> <i class="arg">parse</i></a></li>
<li><a href="#6"><b class="cmd">&lt;officer&gt;</b> <b class="method">continued</b> <i class="arg">line</i></a></li>
<li><a href="#7"><b class="cmd">&lt;officer&gt;</b> <b class="method">default</b></a></li>
<li><a href="#8"><b class="cmd">&lt;officer&gt;</b> <b class="method">dispatch</b> <i class="arg">cmd</i></a></li>
<li><a href="#9"><b class="cmd">&lt;officer&gt;</b> <b class="method">do</b> <span class="opt">?<i class="arg">word</i>...?</span></a></li>
<li><a href="#10"><b class="cmd">&lt;officer&gt;</b> <b class="method">intercept</b> <i class="arg">cmd</i></a></li>
<li><a href="#11"><b class="cmd">&lt;officer&gt;</b> <b class="method">ehandler</b> <i class="arg">cmd</i></a></li>
<li><a href="#12"><b class="cmd">&lt;officer&gt;</b> <b class="method">custom-setup</b> <i class="arg">cmd</i></a></li>
<li><a href="#13"><b class="cmd">&lt;officer&gt;</b> <b class="method">exit</b></a></li>
<li><a href="#14"><b class="cmd">&lt;officer&gt;</b> <b class="method">extend</b> <i class="arg">path</i> <i class="arg">arguments</i> <i class="arg">action</i></a></li>
<li><a href="#15"><b class="cmd">&lt;officer&gt;</b> <b class="method">find</b> <i class="arg">path</i></a></li>
<li><a href="#16"><b class="cmd">&lt;officer&gt;</b> <b class="method">has</b> <i class="arg">name</i></a></li>
<li><a href="#17"><b class="cmd">&lt;officer&gt;</b> <b class="method">hasdefault</b></a></li>
<li><a href="#18"><b class="cmd">&lt;officer&gt;</b> <b class="method">help</b> <span class="opt">?<i class="arg">prefix</i>?</span></a></li>
<li><a href="#19"><b class="cmd">&lt;officer&gt;</b> <b class="method">known</b></a></li>
<li><a href="#20"><b class="cmd">&lt;officer&gt;</b> <b class="method">learn</b> <i class="arg">script</i></a></li>
<li><a href="#21"><b class="cmd">&lt;officer&gt;</b> <b class="method">lookup</b> <i class="arg">name</i></a></li>
<li><a href="#22"><b class="cmd">&lt;officer&gt;</b> <b class="method">prompt1</b></a></li>
<li><a href="#23"><b class="cmd">&lt;officer&gt;</b> <b class="method">prompt2</b></a></li>
<li><a href="#24"><b class="cmd">&lt;officer&gt;</b> <b class="method">report</b> <i class="arg">what</i> <i class="arg">data</i></a></li>
<li><a href="#25"><b class="cmd">&lt;officer&gt;</b> <b class="method">shell-exit</b> <i class="arg">config</i></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>officers</em>, the inner nodes of command
................................................................................
to the sub-ordinates of the officer. When done without error it
recursively invokes the chosen sub-ordinate to continue processing.</p>
<p>This represents the &quot;Dispatch&quot; phase of command line processing.</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="10"><b class="cmd">&lt;officer&gt;</b> <b class="method">intercept</b> <i class="arg">cmd</i></a></dt><dd></dd>
<dt><a name="11"><b class="cmd">&lt;officer&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 isdeprecated 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 officer, 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 officer,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="12"><b class="cmd">&lt;officer&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 theregular setup of the officer from its specification is done, toperform customizations.</p><p>An example of this can be seen in the package<b class="package"><a href="cmdr_history.html">cmdr::history</a></b>. It provides a command<b class="cmd">cmdr::history::attach</b> to add the history management commands tothe actor in question, suitable as argument to this method.</p><p>When called multiple times, the specified commandsaccumulate. This makes it easy to specify several indepedentcustomizations.</p><dl class="arguments"><dt>cmd-prefix <i class="arg">cmd</i></dt><dd><p>A command prefix taking a single argument, the instance command of an<b class="package">cmd::actor</b>. The command prefix has full access to this actorand can modify it as it sees fit. The common use case will be theextension of the actor with additional subordinates.</p></dd></dl></dd>
<dt><a name="13"><b class="cmd">&lt;officer&gt;</b> <b class="method">exit</b></a></dt>
<dd><p>This hook-method for the main shell returns a boolean value indicating
whether the main shell was stopped and has to exit (<b class="const">true</b>), or
not (<b class="const">false</b>).</p></dd>
<dt><a name="14"><b class="cmd">&lt;officer&gt;</b> <b class="method">extend</b> <i class="arg">path</i> <i class="arg">arguments</i> <i class="arg">action</i></a></dt>
<dd><p>A convenience method to create a &quot;private&quot; command underneath this
officer, with the command name <i class="arg">path</i> (a list of names). Any
intermediate officers are created as needed. An error is thrown if any
of the intermediates already exist as a (non-extensible) private, or
if the last command already exists.</p>
<p>The arguments after the <i class="arg">path</i> match the constructor of
privates in number and semantics.</p>
................................................................................
<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>
<dt><a name="15"><b class="cmd">&lt;officer&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> (a list) of names. An error is thrown if such a sub-ordinate
does not exist. This is an extension of <b class="method">lookup</b> to paths of names.</p>
<p>An empty <i class="arg">path</i> is allowed and refers to the officer itself.</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="16"><b class="cmd">&lt;officer&gt;</b> <b class="method">has</b> <i class="arg">name</i></a></dt>
<dd><p>This method returns a boolean value indicating if this officer has a
sub-ordinate of the given <i class="arg">name</i> (<b class="const">true</b>), or not
(<b class="const">false</b>). See also method <b class="method">lookup</b>.</p>
<dl class="arguments">
<dt>string <i class="arg">name</i></dt>
<dd><p>The name of the sub-ordinate to look for.</p></dd>
</dl></dd>
<dt><a name="17"><b class="cmd">&lt;officer&gt;</b> <b class="method">hasdefault</b></a></dt>
<dd><p>This method returns a boolean value indicating if this officer has a
default sub-ordinate (<b class="const">true</b>), or not (<b class="const">false</b>). See also
method <b class="method">default</b>.</p></dd>
<dt><a name="18"><b class="cmd">&lt;officer&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 officer and its
subordinates. The <i class="arg">prefix</i>, if specified provides the name of the
officer 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 officer within the generated help.</p></dd>
</dl></dd>
<dt><a name="19"><b class="cmd">&lt;officer&gt;</b> <b class="method">known</b></a></dt>
<dd><p>This method returns a list containing the names of the subordinate
actors managed by this officer.
See also method <b class="method">children</b> which returns a list of instance
commands.
See also method <b class="method">lookup</b> to map names to instance commands.</p></dd>
<dt><a name="20"><b class="cmd">&lt;officer&gt;</b> <b class="method">learn</b> <i class="arg">script</i></a></dt>
<dd><p>This method takes a regular specification script and uses it to extend
the set of subordinates known to this officer. This is the same type
of script as used during construction, except here we dynamically
extend the officer.</p>
<dl class="arguments">
<dt>script <i class="arg">actions</i></dt>
<dd><p>The specification of the officer's additional subordinates.
Please read <i class="term"><a href="cmdr_dsl_officer.html">Cmdr - Officer Specification Language</a></i> for the details.</p></dd>
</dl></dd>
<dt><a name="21"><b class="cmd">&lt;officer&gt;</b> <b class="method">lookup</b> <i class="arg">name</i></a></dt>
<dd><p>This method returns the instance command of the sub-ordinate with the
given <i class="arg">name</i>. An error is thrown if such a sub-ordinate does not
exist. See also method <b class="method">has</b>.</p>
<dl class="arguments">
<dt>string <i class="arg">name</i></dt>
<dd><p>The name of the sub-ordinate to look for.</p></dd>
</dl></dd>
<dt><a name="22"><b class="cmd">&lt;officer&gt;</b> <b class="method">prompt1</b></a></dt>
<dd><p>This hook-method for the main shell returns the primary prompt string
to use.</p></dd>
<dt><a name="23"><b class="cmd">&lt;officer&gt;</b> <b class="method">prompt2</b></a></dt>
<dd><p>This hook-method for the main shell returns the secondary prompt
string for use within a continuation. As the main shell does not
support continuation lines it should not be invoked ever, and thus
always throws an error should it be invoked.</p></dd>
<dt><a name="24"><b class="cmd">&lt;officer&gt;</b> <b class="method">report</b> <i class="arg">what</i> <i class="arg">data</i></a></dt>
<dd><p>This hook-method for the main shell is responsible for the reporting
of the command results.</p>
<p>Its result is the empty string.</p>
<dl class="arguments">
<dt>enum <i class="arg">what</i></dt>
<dd><p>The result code of the command, one of <b class="const">ok</b>, or <b class="const">fail</b>.</p></dd>
<dt>any <i class="arg">data</i></dt>
<dd><p>The result of the command, or an error message in case of failure.</p></dd>
</dl></dd>
<dt><a name="25"><b class="cmd">&lt;officer&gt;</b> <b class="method">shell-exit</b> <i class="arg">config</i></a></dt>
<dd><p>This is the backend for a private ending the main shell,
be it automatically created by the pacge, or by a user.</p>
<p>The argument is the <b class="package"><a href="cmdr_config.html">cmdr::config</a></b>
instance holding the parameters. The method does not
expect any and ignore it.</p></dd>
</dl>
</div>

<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">ehandler</b> <i class="arg">cmd</i></a></li>
<li><a href="#6"><b class="cmd">&lt;private&gt;</b> <b class="method">find</b> <i class="arg">path</i></a></li>
<li><a href="#7"><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="#8"><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
................................................................................
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">ehandler</b> <i class="arg">cmd</i></a></dt>
<dd><p>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="6"><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="7"><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="8"><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>

<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
................................................................................
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 isdeprecated 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 theregular setup of an officer from its specification is done, to performcustomizations.</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 theplaces 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>