[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method root]]

This accessor method returns the root actor instance the actor belongs
to.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method set] [arg key] [option -extend] [option --] [arg data]]

This method sets the contents of the common block named by [arg key]
to [arg data]. If the block does not exist it is created. Otherwise
its existing content is written over.

[para] Using option [option -extend] will change the behaviour to
       extend inherited content instead of writing over it.

[para] Using option [option --] will prevent misinterpretation of the
       following argument as option, even if it begins with a dash.

[list_begin arguments]
[arg_def string key]  The name of the common block to write.
[arg_def any    data] The data to store in the block.
[list_end][comment {--- arguments --}]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <actor>] [method super]]

After attachment the actor will accept the following 3 commands:

[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 >= 0). Unlimited for n < 0.
}]

Under most circumstances the attachment is handled through the
[cmd shandler] method of officers. See [package cmdr::officer], and
the [sectref Example] for more information.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::history] [method save-to] [arg path]]

When invoked this command sets the package-wide history save file used
by the commands to the [arg path].

[para] The result of the command is the empty string.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::history] [method initial-limit] [arg limit]]

When invoked this command sets the package-wide limit on history size
to [arg limit]. A value less than zero means "no limit".

[para] The result of the command is the empty string.

[list_end]

[section Example]

Below an example on how to activate history for an officer.
The example was taken from the [cmd fx] application extending the
[cmd fossil] DVCS.

[example {
cmdr history initial-limit 20
cmdr history save-to       ~/.fx_history

cmdr create fx::fx [file tail $::argv0] {
    shandler ::cmdr::history::attach

    [...]
}
}]

[include parts/feedback.inc]
[manpage_end]

[comment {-*- tcl -*- doctools manpage}]
[include parts/definitions.inc]
[vset VERSION 1]
[manpage_begin [vset LABEL_PAGER] [vset MAN_SECTION] [vset VERSION]]
[include parts/module.inc]
[require linenoise]
[require cmdr::tty]
[require cmdr::pager]
[titledesc [vset TITLE_PAGER]]
[description]
[include parts/welcome.inc]

This package provides a single utility command to manage the automatic
paging of long output, like it is done [vset PROJECT]'s automatic help.

[section API]
[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::pager] [method text]]

When invoked this command either simply prints the [arg text] to stdout,

[subsection {Changes for version 1.1}]

[list_begin enumerated]
[comment {- - -- --- ----- -------- ------------- ---------------------}]

[enum] Fixed broken requirement references in the meta data of packages
       [package cmdr::help::json] and [package cmdr::help::sql].

[enum] Fixed initialization issues in the help generator.

[enum] Fixed generated help, added the application name to the output
       when in a cmdr shell.

[enum] Fixed the generation of help format [const by-categorized], when
       encountering sections with sub-sections and no commands of their
       own.

[enum] Fixed bad method scoping in method [method extend] of officers.

[enum] Extended officer method [method extend] to return the created
       private, for immediate post-creation re-configuration.

[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] Added many new standard validation types to package
       [package cmdr::validate]:

[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] iso8601 date/time,
       [enum] year
       [enum] weekday, 
       [enum] hour:minute
       [list_end]
[list_end]

[enum] Added more helper commands for validation failure messages to
       package [package cmdr::validate::common].

       [list_begin enumerated]
       [enum] [cmd fail-unknown-thing]
       [enum] [cmd fail-unknown-thing-msg]
       [enum] [cmd fail-unknown-simple]
       [enum] [cmd fail-unknown-simple-msg]
       [enum] [cmd fail-known-thing]
       [enum] [cmd fail-known-thing-msg]
       [enum] [cmd fail-known-simple]
       [enum] [cmd fail-known-simple-msg]

-- TODO -- document --

       [list_end]

[enum] Modified integer validation to have a proper internal
       representation: decimal. Octal, hex, etc. input is now
       normalized to this.

[enum] 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, 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.
     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] Added 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] Added support for an option [option -extend] for common blocks,
       allowing their extension in a subordinate instead of just
       replacing the entire content.

[enum] Extended boolean options to allow the specification of negative
       aliases, i.e. representing the inverted option. See the DSL
       commands [cmd neg-alias] and [cmd !alias] in
       [term {Cmdr - Parameter Specification Language}].

[enum] Extended the DSL for options in general with the ability to set
       a label for the option argument so that the generated help can
       be more descriptive. The option name is used as fallback for
       options for which no such label was specified.

       See DSL command [cmd label] in
       [term {Cmdr - Parameter Specification Language}].

[enum] Extended officers to accept all unique command prefixes of
       their subordinates for dispatch.

[enum] Modified the help system to use the [const short] format for
       interior nodes of the command hierarchy by default.

[enum] Modified the help system to exclude auto-added commands from
       the output generated by format [const by-category].



[enum] ... A suite of bug fixes ... // TODO: list the details.

[comment {- - -- --- ----- -------- ------------- ---------------------}]
[list_end]

[list_begin definitions]
[def [cmd alias]]        [method Alias]
[def [cmd common]]       [package cmdr::actor] [method set]
[def [cmd default]]      [method Default]
[def [cmd description]]  [package cmdr::actor] [method description:]
[def [cmd ehandler]]     [method ehandler]
[def [cmd shandler]]     [method shandler]
[def [cmd officer]]      [method Officer], forward to [method DefineAction]
[def [cmd private]]      [method Private], forward to [method DefineAction]
[def [cmd undocumented]] [package cmdr::actor] [method undocumented]
[list_end]

The name of the alias.

[arg_def string name'...]
The path to the actor, as list of names.
[list_end]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd common] [arg name] [option -extend] [option --] [arg text]]

This is another structuring command, for structuring the specification
itself instead of the command tree it declares.

[para] It creates named values, usually code blocks, which can be
shared between specifications. Note that while each block is visible
in the current [term officer] and its subordinates, parents and

the [term option] in the example, as it makes the debug setup
available to all privates without having to explicitly include the
block, and possibly forgetting such.

[para] Generally speaking, the framework reserves all blocks whose
name begins with a star, i.e [const *], for its own use.

[para] Using option [option -extend] will change the behaviour to
       extend inherited content instead of writing over it.

[para] Using option [option --] will prevent misinterpretation of the
       following argument as option, even if it begins with a dash.

[list_begin arguments]
[arg_def string name]
The name of the common block.

[arg_def string text]
The text of the block.
[list_end]

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 [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 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
management commands to the actor in question.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd officer] [arg name] [arg script]]

This command creates a named subordinate [term officer] with its
specification [arg script] of officer commands as described here.

.sp
\fB<actor>\fR \fBname:\fR \fIname\fR
.sp
\fB<actor>\fR \fBparse-line\fR \fIline\fR
.sp
\fB<actor>\fR \fBroot\fR
.sp
\fB<actor>\fR \fBset\fR \fIkey\fR \fB-extend\fR \fB--\fR \fIdata\fR
.sp
\fB<actor>\fR \fBsuper\fR
.sp
\fB<actor>\fR \fBsuper:\fR \fIobj\fR
.sp
\fB<actor>\fR \fBundocumented\fR
.sp

The command line\&.
.RE
.TP
\fB<actor>\fR \fBroot\fR
This accessor method returns the root actor instance the actor belongs
to\&.
.TP
\fB<actor>\fR \fBset\fR \fIkey\fR \fB-extend\fR \fB--\fR \fIdata\fR
This method sets the contents of the common block named by \fIkey\fR
to \fIdata\fR\&. If the block does not exist it is created\&. Otherwise
its existing content is written over\&.
.sp
Using option \fB-extend\fR will change the behaviour to
extend inherited content instead of writing over it\&.
.sp
Using option \fB--\fR will prevent misinterpretation of the
following argument as option, even if it begins with a dash\&.
.RS
.TP
string \fIkey\fR
The name of the common block to write\&.
.TP
any \fIdata\fR
The data to store in the block\&.

Welcome to the Cmdr project, written by Andreas Kupries\&.
.PP
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]
Added many new standard validation types to package
\fBcmdr::validate\fR:
.RS
.IP [1]
Double
.IP [2]
Percent
.IP [3]
Posint (positive integers, > 0)
.IP [4]
Paths and channels
.RS
.IP [1]
Readable file
.IP [2]
Writable file
.IP [3]
Read/writable file
.IP [4]
Readable directory
.IP [5]
Read/writeable directory
.IP [6]
readable path
.IP [7]
Read/writable path
.IP [8]
Readable path, as channel
.IP [9]
Writable path, as channel
.IP [10]
Read/writable path, as channel
.RE
.IP [5]
Date and time related:
.RS
.IP [1]
iso8601 date/time,
.IP [2]
year
.IP [3]
weekday,
.IP [4]
hour:minute
.RE
.RE
.IP [2]
Added more helper commands for validation failure messages to
package \fBcmdr::validate::common\fR\&.
.RS
.IP [1]
\fBfail-unknown-thing\fR
.IP [2]
\fBfail-unknown-thing-msg\fR
.IP [3]
\fBfail-unknown-simple\fR
.IP [4]
\fBfail-unknown-simple-msg\fR
.IP [5]
\fBfail-known-thing\fR
.IP [6]
\fBfail-known-thing-msg\fR
.IP [7]
\fBfail-known-simple\fR
.IP [8]
\fBfail-known-simple-msg\fR
-- TODO -- document --
.RE
.IP [3]
Modified integer validation to have a proper internal
representation: decimal\&. Octal, hex, etc\&. input is now
normalized to this\&.
.IP [4]
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, 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\&.
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]
\fIvaltype::creditcard::mastercard\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/cc_mastercard\&.html]
.IP [4]
\fIvaltype::creditcard::visa\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/cc_visa\&.html]
.IP [5]
\fIvaltype::gs1::ean13\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/ean13\&.html]
.IP [6]
\fIvaltype::iban\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/iban\&.html]
.IP [7]
\fIvaltype::imei\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/imei\&.html]
.IP [8]
\fIvaltype::isbn\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/isbn\&.html]
.IP [9]
\fIvaltype::luhn\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/luhn\&.html]
.IP [10]
\fIvaltype::luhn5\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/luhn5\&.html]
.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]
Added 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-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\&.
.IP [6]
Added support for an option \fB-extend\fR for common blocks,
allowing their extension in a subordinate instead of just
replacing the entire content\&.
.IP [7]
Extended boolean options to allow the specification of negative
aliases, i\&.e\&. representing the inverted option\&. See the DSL
commands \fBneg-alias\fR and \fB!alias\fR in
\fICmdr - Parameter Specification Language\fR\&.
.IP [8]
Extended the DSL for options in general with the ability to set
a label for the option argument so that the generated help can
be more descriptive\&. The option name is used as fallback for
options for which no such label was specified\&.
See DSL command \fBlabel\fR in
\fICmdr - Parameter Specification Language\fR\&.
.IP [9]
Extended officers to accept all unique command prefixes of
their subordinates for dispatch\&.
.IP [10]
Modified the help system to use the \fBshort\fR format for
interior nodes of the command hierarchy by default\&.
.IP [11]
Modified the help system to exclude auto-added commands from
the output generated by format \fBby-category\fR\&.
.IP [12]
\&.\&.\&. A suite of bug fixes \&.\&.\&. // TODO: list the details\&.
.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\&.
.IP [3]
Fixed generated help, added the application name to the output
when in a cmdr shell\&.
.IP [4]
Fixed the generation of help format \fBby-categorized\fR, when
encountering sections with sub-sections and no commands of their
own\&.
.IP [5]
Fixed bad method scoping in method \fBextend\fR of officers\&.
.IP [6]
Extended officer method \fBextend\fR to return the created
private, for immediate post-creation re-configuration\&.

\fBDefault\fR
.TP
\fBdescription\fR
\fBcmdr::actor\fR \fBdescription:\fR
.TP
\fBehandler\fR
\fBehandler\fR
.TP
\fBshandler\fR
\fBshandler\fR
.TP
\fBofficer\fR
\fBOfficer\fR, forward to \fBDefineAction\fR
.TP
\fBprivate\fR
\fBPrivate\fR, forward to \fBDefineAction\fR
.TP

.SH NAME
cmdr-spec-dsl-officer \- Cmdr - Officer Specification Language
.SH SYNOPSIS
\fBalias\fR \fIname\fR \fB=\fR \fIname'\fR\&.\&.\&.
.sp
\fBalias\fR \fIname\fR
.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

string \fIname\fR
The name of the alias\&.
.TP
string \fIname'\&.\&.\&.\fR
The path to the actor, as list of names\&.
.RE
.TP
\fBcommon\fR \fIname\fR \fB-extend\fR \fB--\fR \fItext\fR
This is another structuring command, for structuring the specification
itself instead of the command tree it declares\&.
.sp
It creates named values, usually code blocks, which can be
shared between specifications\&. Note that while each block is visible
in the current \fIofficer\fR and its subordinates, parents and
siblings have no access\&.

specified underneath this \fIofficer\fR\&. A very important trait for
the \fIoption\fR in the example, as it makes the debug setup
available to all privates without having to explicitly include the
block, and possibly forgetting such\&.
.sp
Generally speaking, the framework reserves all blocks whose
name begins with a star, i\&.e \fB*\fR, for its own use\&.
.sp
Using option \fB-extend\fR will change the behaviour to
extend inherited content instead of writing over it\&.
.sp
Using option \fB--\fR will prevent misinterpretation of the
following argument as option, even if it begins with a dash\&.
.RS
.TP
string \fIname\fR
The name of the common block\&.
.TP
string \fItext\fR
The text of the block\&.

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 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
\fBofficer\fR \fIname\fR \fIscript\fR
This command creates a named subordinate \fIofficer\fR with its
specification \fIscript\fR of officer commands as described here\&.
.TP
\fBprivate\fR \fIname\fR \fIscript\fR \fIcmdprefix\fR
This command creates a named subordinate \fIprivate\fR with its
specification \fIscript\fR of private commands

    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\&.
.TP
\fB::cmdr::history\fR \fBinitial-limit\fR \fIlimit\fR
When invoked this command sets the package-wide limit on history size
to \fIlimit\fR\&. A value less than zero means "no limit"\&.
.sp
The result of the command is the empty string\&.
.PP
.SH EXAMPLE
Below an example on how to activate history for an officer\&.
The example was taken from the \fBfx\fR application extending the
\fBfossil\fR DVCS\&.
.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
bugs and other problems\&.
Please report such at
\fICmdr Tickets\fR [https:/core\&.tcl\&.tk/akupries/cmdr]\&.
.PP
Please also report any ideas you may have for enhancements of

.SH DESCRIPTION
.PP
Welcome to the Cmdr project, written by Andreas Kupries\&.
.PP
For availability please read \fICmdr - How To Get The Sources\fR\&.
.PP
This package provides a single utility command to manage the automatic
paging of long output, like it is done cmdr's automatic help\&.
.SH API
.TP
\fB::cmdr::pager\fR \fBtext\fR
When invoked this command either simply prints the \fItext\fR to stdout,
or invokes an external pager application to manage the output\&.
.sp
The pager is only invoked when

.PP
Welcome to the Cmdr project, written by Andreas Kupries\&.
.PP
For availability please read \fICmdr - How To Get The Sources\fR\&.
.PP
.PP
This package provides the validation type
\fB::cmdr::validate::time\fR which accepts timestamps in both ISO 8601
syntax and as epoch values, i\&.e\&. positive integer seconds since the
beginning of unix time\&.
.PP
The internal, canonical representation is the epoch for the
validated input\&.
.PP
The type has no input completion\&.
.PP
The details of the exported standard API can be found in
\fICmdr - Writing custom validation types\fR\&. The chosen default is "now"\&.
.PP
A single non-standard method is provided:
.TP
\fB::cmdr::validate::time\fR \fB2external\fR \fIepoch\fR
This method converts the epoch of a time to the form
\fB%Y-%m-%dT%H:%M:%S\fR and returns the conversion result as its own\&.
.PP
.SH "BUGS, IDEAS, FEEDBACK"
Both the package(s) and this documentation will undoubtedly contain
bugs and other problems\&.
Please report such at
\fICmdr Tickets\fR [https:/core\&.tcl\&.tk/akupries/cmdr]\&.
.PP

<li><a href="#13"><b class="cmd">&lt;actor&gt;</b> <b class="method">keys</b></a></li>
<li><a href="#14"><b class="cmd">&lt;actor&gt;</b> <b class="method">lappend</b> <i class="arg">key</i> <i class="arg">data</i></a></li>
<li><a href="#15"><b class="cmd">&lt;actor&gt;</b> <b class="method">match</b> <i class="arg">parse</i> <i class="arg">cmdlist</i></a></li>
<li><a href="#16"><b class="cmd">&lt;actor&gt;</b> <b class="method">name</b></a></li>
<li><a href="#17"><b class="cmd">&lt;actor&gt;</b> <b class="method">name:</b> <i class="arg">name</i></a></li>
<li><a href="#18"><b class="cmd">&lt;actor&gt;</b> <b class="method">parse-line</b> <i class="arg">line</i></a></li>
<li><a href="#19"><b class="cmd">&lt;actor&gt;</b> <b class="method">root</b></a></li>
<li><a href="#20"><b class="cmd">&lt;actor&gt;</b> <b class="method">set</b> <i class="arg">key</i> <b class="option">-extend</b> <b class="option">--</b> <i class="arg">data</i></a></li>
<li><a href="#21"><b class="cmd">&lt;actor&gt;</b> <b class="method">super</b></a></li>
<li><a href="#22"><b class="cmd">&lt;actor&gt;</b> <b class="method">super:</b> <i class="arg">obj</i></a></li>
<li><a href="#23"><b class="cmd">&lt;actor&gt;</b> <b class="method">undocumented</b></a></li>
<li><a href="#24"><b class="cmd">&lt;actor&gt;</b> <b class="method">unset</b> <i class="arg">key</i></a></li>
</ul>
</div>
</div>

<dl class="arguments">
<dt>string <i class="arg">line</i></dt>
<dd><p>The command line.</p></dd>
</dl></dd>
<dt><a name="19"><b class="cmd">&lt;actor&gt;</b> <b class="method">root</b></a></dt>
<dd><p>This accessor method returns the root actor instance the actor belongs
to.</p></dd>
<dt><a name="20"><b class="cmd">&lt;actor&gt;</b> <b class="method">set</b> <i class="arg">key</i> <b class="option">-extend</b> <b class="option">--</b> <i class="arg">data</i></a></dt>
<dd><p>This method sets the contents of the common block named by <i class="arg">key</i>
to <i class="arg">data</i>. If the block does not exist it is created. Otherwise
its existing content is written over.</p>
<p>Using option <b class="option">-extend</b> will change the behaviour to
       extend inherited content instead of writing over it.</p>
<p>Using option <b class="option">--</b> will prevent misinterpretation of the
       following argument as option, even if it begins with a dash.</p>
<dl class="arguments">
<dt>string <i class="arg">key</i></dt>
<dd><p>The name of the common block to write.</p></dd>
<dt>any <i class="arg">data</i></dt>
<dd><p>The data to store in the block.</p></dd>
</dl></dd>
<dt><a name="21"><b class="cmd">&lt;actor&gt;</b> <b class="method">super</b></a></dt>

</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">
<li class="section"><a href="#toc">Table Of Contents</a></li>
<li class="section"><a href="#section1">Description</a></li>
<li class="section"><a href="#section2">Changes</a>
<ul>
<li class="subsection"><a href="#subsection1">Changes for version 1.2</a></li>
<li class="subsection"><a href="#subsection2">Changes for version 1.1</a></li>
<li class="subsection"><a href="#subsection3">Changes for version 1</a></li>
</ul>
</li>
<li class="section"><a href="#section3">Related Documents</a></li>
<li class="section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="section"><a href="#keywords">Keywords</a></li>
<li class="section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="section"><h2><a name="section1">Description</a></h2>
<p>Welcome to the Cmdr project, written by Andreas Kupries.</p>
<p>For availability please read <i class="term"><a href="cmdr_howto_get_sources.html">Cmdr - How To Get The Sources</a></i>.</p>
<p>This document provides an overview of the changes <b class="package"><a href="cmdr.html">cmdr</a></b>
underwent from version to version.</p>
</div>
<div id="section2" class="section"><h2><a name="section2">Changes</a></h2>
<div id="subsection1" class="subsection"><h3><a name="subsection1">Changes for version 1.2</a></h3>
<ol class="enumerated">
<li><p>Added many new standard validation types to package
       <b class="package"><a href="cmdr_validate.html">cmdr::validate</a></b>:</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>iso8601 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>Added more helper commands for validation failure messages to
       package <b class="package"><a href="cmdr_vcommon.html">cmdr::validate::common</a></b>.</p>
<ol class="enumerated">
       
<li><p><b class="cmd">fail-unknown-thing</b></p></li>
<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</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>
-- TODO -- document --</p></li>
</ol>
</li>
<li><p>Modified integer validation to have a proper internal
       representation: decimal. Octal, hex, etc. input is now
       normalized to this.</p></li>
<li><p>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">cmdr::table</b></dt>
<dd><p>Table formatting, 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.
     Wrappers around the validation commands provided by
       <a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/toc.html">Tcllib</a>:</p>
<ol class="enumerated">
       
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/cc_amex.html">valtype::creditcard::amex</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/cc_discover.html">valtype::creditcard::discover</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/cc_mastercard.html">valtype::creditcard::mastercard</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/cc_visa.html">valtype::creditcard::visa</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/ean13.html">valtype::gs1::ean13</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/iban.html">valtype::iban</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/imei.html">valtype::imei</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/isbn.html">valtype::isbn</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/luhn.html">valtype::luhn</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/luhn5.html">valtype::luhn5</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/usnpi.html">valtype::usnpi</a></p></li>
<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/verhoeff.html">valtype::verhoeff</a></p></li>
</ol></dd>
</dl>
</li>
<li><p>Added 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>Added 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>Extended boolean options to allow the specification of negative
       aliases, i.e. representing the inverted option. 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>Extended the DSL for options in general with the ability to set
       a label for the option argument so that the generated help can
       be more descriptive. The option name is used as fallback for
       options for which no such label was specified.
       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>
<li><p>Extended officers to accept all unique command prefixes of
       their subordinates for dispatch.</p></li>
<li><p>Modified the help system to use the <b class="const">short</b> format for
       interior nodes of the command hierarchy by default.</p></li>
<li><p>Modified the help system to exclude auto-added commands from
       the output generated by format <b class="const">by-category</b>.</p></li>
<li><p>... A suite of bug fixes ... // TODO: list the details.</p></li>
</ol>
</div>
<div id="subsection2" class="subsection"><h3><a name="subsection2">Changes for version 1.1</a></h3>
<ol class="enumerated">
<li><p>Fixed broken requirement references in the meta data of packages
       <b class="package"><a href="cmdr_help_json.html">cmdr::help::json</a></b> and <b class="package"><a href="cmdr_help_sql.html">cmdr::help::sql</a></b>.</p></li>
<li><p>Fixed initialization issues in the help generator.</p></li>
<li><p>Fixed generated help, added the application name to the output
       when in a cmdr shell.</p></li>
<li><p>Fixed the generation of help format <b class="const">by-categorized</b>, when
       encountering sections with sub-sections and no commands of their
       own.</p></li>
<li><p>Fixed bad method scoping in method <b class="method">extend</b> of officers.</p></li>
<li><p>Extended officer method <b class="method">extend</b> to return the created
       private, for immediate post-creation re-configuration.</p></li>
<li><p>Extended system with new help format <i class="term">tcl</i>, and associated
       package <b class="package"><a href="cmdr_help_tcl.html">cmdr::help::tcl</a></b>. Similar to format <i class="term">json</i>
       the help is printed as a nested data structure, just using Tcl
       syntax.</p></li>
<li><p>Extended officers and privates with method <b class="method">find</b> for
       path lookup of sub-ordinates.</p></li>
</ol>
</div>
<div id="subsection3" class="subsection"><h3><a name="subsection3">Changes for version 1</a></h3>
<p>This is the first release of cmdr.
The changes therefore describe the initial features of the system.</p>
<p>In detail:</p>
<ol class="enumerated">
<li><p>cmdr requires Tcl 8.5 or higher.
       Tcl 8.4 or less is not supported.</p></li>
<li><p>The framework provides a DSL for the declaration of a hierarchy

<dd><p><b class="package"><a href="cmdr_actor.html">cmdr::actor</a></b> <b class="method">set</b></p></dd>
<dt><b class="cmd">default</b></dt>
<dd><p><b class="method">Default</b></p></dd>
<dt><b class="cmd">description</b></dt>
<dd><p><b class="package"><a href="cmdr_actor.html">cmdr::actor</a></b> <b class="method">description:</b></p></dd>
<dt><b class="cmd">ehandler</b></dt>
<dd><p><b class="method">ehandler</b></p></dd>
<dt><b class="cmd">shandler</b></dt>
<dd><p><b class="method">shandler</b></p></dd>
<dt><b class="cmd">officer</b></dt>
<dd><p><b class="method">Officer</b>, forward to <b class="method">DefineAction</b></p></dd>
<dt><b class="cmd">private</b></dt>
<dd><p><b class="method">Private</b>, forward to <b class="method">DefineAction</b></p></dd>
<dt><b class="cmd">undocumented</b></dt>
<dd><p><b class="package"><a href="cmdr_actor.html">cmdr::actor</a></b> <b class="method">undocumented</b></p></dd>
</dl>

</ul>
</div>
<div id="synopsis" class="section"><h2><a name="synopsis">Synopsis</a></h2>
<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.</p>
<dl class="arguments">
<dt>string <i class="arg">name</i></dt>
<dd><p>The name of the alias.</p></dd>
<dt>string <i class="arg">name'...</i></dt>
<dd><p>The path to the actor, as list of names.</p></dd>
</dl></dd>
<dt><a name="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></dt>
<dd><p>This is another structuring command, for structuring the specification
itself instead of the command tree it declares.</p>
<p>It creates named values, usually code blocks, which can be
shared between specifications. Note that while each block is visible
in the current <i class="term">officer</i> and its subordinates, parents and
siblings have no access.</p>
<p>An example of such a block would be</p>

<i class="term">private</i> specifications, i.e. shared across all the privates
specified underneath this <i class="term">officer</i>. A very important trait for
the <i class="term">option</i> in the example, as it makes the debug setup
available to all privates without having to explicitly include the
block, and possibly forgetting such.</p>
<p>Generally speaking, the framework reserves all blocks whose
name begins with a star, i.e <b class="const">*</b>, for its own use.</p>
<p>Using option <b class="option">-extend</b> will change the behaviour to
       extend inherited content instead of writing over it.</p>
<p>Using option <b class="option">--</b> will prevent misinterpretation of the
       following argument as option, even if it begins with a dash.</p>
<dl class="arguments">
<dt>string <i class="arg">name</i></dt>
<dd><p>The name of the common block.</p></dd>
<dt>string <i class="arg">text</i></dt>
<dd><p>The text of the block.</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">default</b></a></dt>

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 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="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>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">
<li class="section"><a href="#toc">Table Of Contents</a></li>
<li class="section"><a href="#synopsis">Synopsis</a></li>
<li class="section"><a href="#section1">Description</a></li>
<li class="section"><a href="#section2">API</a></li>
<li class="section"><a href="#section3">Example</a></li>
<li class="section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="section"><a href="#keywords">Keywords</a></li>
<li class="section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="synopsis">
<ul class="requirements">

</dl>
<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
to <i class="arg">limit</i>. A value less than zero means &quot;no limit&quot;.</p>
<p>The result of the command is the empty string.</p></dd>
</dl>
</div>
<div id="section3" class="section"><h2><a name="section3">Example</a></h2>
<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.
Please report such at
<a href="https:/core.tcl.tk/akupries/cmdr">Cmdr Tickets</a>.</p>
<p>Please also report any ideas you may have for enhancements of
either package(s) and/or documentation.</p>
</div>

</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 provides a single utility command to manage the automatic
paging of long output, like it is done cmdr's automatic help.</p>
</div>
<div id="section2" class="section"><h2><a name="section2">API</a></h2>
<dl class="definitions">
<dt><a name="1"><b class="cmd">::cmdr::pager</b> <b class="method">text</b></a></dt>
<dd><p>When invoked this command either simply prints the <i class="arg">text</i> to stdout,
or invokes an external pager application to manage the output.</p>
<p>The pager is only invoked when</p>

</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 provides the validation type
<b class="cmd">::cmdr::validate::time</b> which accepts timestamps in both ISO 8601
syntax and as epoch values, i.e. positive integer seconds since the
beginning of unix time.</p>
<p>The internal, canonical representation is the epoch for the
validated input.</p>
<p>The type has no input completion.</p>
<p>The details of the exported standard API can be found in
<i class="term"><a href="cmdr_vtypes.html">Cmdr - Writing custom validation types</a></i>. The chosen default is &quot;now&quot;.</p>
<p>A single non-standard method is provided:</p>
<dl class="definitions">
<dt><a name="1"><b class="cmd">::cmdr::validate::time</b> <b class="method">2external</b> <i class="arg">epoch</i></a></dt>
<dd><p>This method converts the epoch of a time to the form
<b class="const">%Y-%m-%dT%H:%M:%S</b> and returns the conversion result as its own.</p></dd>
</dl>
</div>
<div id="section2" class="section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>Both the package(s) and this documentation will undoubtedly contain
bugs and other problems.
Please report such at
<a href="https:/core.tcl.tk/akupries/cmdr">Cmdr Tickets</a>.</p>

    # can still disable paging, when nothing is found. We look for the
    # user's choice first.

    global env
    if {[info exists env(PAGER)]} {
	lappend pager $env(PAGER)
    }
    lappend pager {less -R -f}
    # -R Show ANSI colors
    # -f do not prompt when thinking that file is binary
    #    (for example due to ANSI colors)


    lappend pager more

    foreach p $pager {
	debug.cmdr/pager {Looking for cmd ($p)}
	set cmd [auto_execok [lindex $p 0]]
	if {[llength $cmd]} {
	    lappend cmd {*}[lrange $p 1 end]