Index: doc/cmdr_actor.man ================================================================== --- doc/cmdr_actor.man +++ doc/cmdr_actor.man @@ -225,16 +225,22 @@ This accessor method returns the root actor instance the actor belongs to. [comment {- - -- --- ----- -------- -------------}] -[call [cmd ] [method set] [arg key] [arg data]] +[call [cmd ] [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 --}] Index: doc/cmdr_history.man ================================================================== --- doc/cmdr_history.man +++ doc/cmdr_history.man @@ -33,10 +33,14 @@ [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 @@ -51,8 +55,25 @@ 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] Index: doc/cmdr_pager.man ================================================================== --- doc/cmdr_pager.man +++ doc/cmdr_pager.man @@ -9,11 +9,11 @@ [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 [vset PROJECT]'s automatic help. +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]] Index: doc/parts/changes1.1.inc ================================================================== --- doc/parts/changes1.1.inc +++ doc/parts/changes1.1.inc @@ -9,11 +9,11 @@ [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 by-categorized, when +[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. Index: doc/parts/changes1.2.inc ================================================================== --- doc/parts/changes1.2.inc +++ doc/parts/changes1.2.inc @@ -1,62 +1,130 @@ [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] Many new validation types: +[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 // TODO: List exact -[enum] Wrappers around the Tcllib valtypes // TODO: List exact -[enum] Date and time related: iso8601 date/time, year, weekday, hour:minute +[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] More helper commands for validation failure messages. +[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] 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 tty]] Test for terminal. -[def [package color]] Color management, ansi control sequences. -[def [package ask]] User interaction commands. -[def [package pager]] Text display with automatic invokation of a pager - for tall output. -[def [package history]] Pluggable management of command history. -[def [package table]] Table formatting, simplified interface to Tcllib's - [package struct::matrix] and [package report] packages. +[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. Most common use case - are likely global options added to the root officer. - -[para] A new common block [const *config*] is set to the active - [package config] instance, 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 otion [option -exted] for common blocks +[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 specification of negative - aliases, i.e. representing the inverted option. +[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] Extended the DSL for options with the ability to set a label - for the option argument so that help can be more descriptive. - The option name is used as fallback for options with no such - label specified. +[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] Index: doc/parts/dev_dsl_officer.inc ================================================================== --- doc/parts/dev_dsl_officer.inc +++ doc/parts/dev_dsl_officer.inc @@ -15,9 +15,10 @@ [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] Index: doc/parts/dsl_officer.inc ================================================================== --- doc/parts/dsl_officer.inc +++ doc/parts/dsl_officer.inc @@ -29,11 +29,11 @@ [arg_def string name'...] The path to the actor, as list of names. [list_end] [comment {- - -- --- ----- -------- -------------}] -[call [cmd common] [arg name] [arg text]] +[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 @@ -71,10 +71,16 @@ 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] @@ -130,10 +136,29 @@ 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 Index: embedded/man/files/cmdr_actor.n ================================================================== --- embedded/man/files/cmdr_actor.n +++ embedded/man/files/cmdr_actor.n @@ -313,11 +313,11 @@ .sp \fB\fR \fBparse-line\fR \fIline\fR .sp \fB\fR \fBroot\fR .sp -\fB\fR \fBset\fR \fIkey\fR \fIdata\fR +\fB\fR \fBset\fR \fIkey\fR \fB-extend\fR \fB--\fR \fIdata\fR .sp \fB\fR \fBsuper\fR .sp \fB\fR \fBsuper:\fR \fIobj\fR .sp @@ -499,14 +499,20 @@ .TP \fB\fR \fBroot\fR This accessor method returns the root actor instance the actor belongs to\&. .TP -\fB\fR \fBset\fR \fIkey\fR \fIdata\fR +\fB\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 Index: embedded/man/files/cmdr_changes.n ================================================================== --- embedded/man/files/cmdr_changes.n +++ embedded/man/files/cmdr_changes.n @@ -281,10 +281,180 @@ 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] @@ -291,11 +461,11 @@ 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 by-categorized, when +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] Index: embedded/man/files/cmdr_dev_dsl.n ================================================================== --- embedded/man/files/cmdr_dev_dsl.n +++ embedded/man/files/cmdr_dev_dsl.n @@ -316,10 +316,13 @@ \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 Index: embedded/man/files/cmdr_dsl_officer.n ================================================================== --- embedded/man/files/cmdr_dsl_officer.n +++ embedded/man/files/cmdr_dsl_officer.n @@ -277,17 +277,19 @@ .SH SYNOPSIS \fBalias\fR \fIname\fR \fB=\fR \fIname'\fR\&.\&.\&. .sp \fBalias\fR \fIname\fR .sp -\fBcommon\fR \fIname\fR \fItext\fR +\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 @@ -342,11 +344,11 @@ .TP string \fIname'\&.\&.\&.\fR The path to the actor, as list of names\&. .RE .TP -\fBcommon\fR \fIname\fR \fItext\fR +\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 @@ -382,10 +384,16 @@ 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 @@ -431,10 +439,25 @@ 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 Index: embedded/man/files/cmdr_history.n ================================================================== --- embedded/man/files/cmdr_history.n +++ embedded/man/files/cmdr_history.n @@ -316,10 +316,14 @@ 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 @@ -329,10 +333,27 @@ 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]\&. Index: embedded/man/files/cmdr_pager.n ================================================================== --- embedded/man/files/cmdr_pager.n +++ embedded/man/files/cmdr_pager.n @@ -289,11 +289,11 @@ 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 cmdr's automatic help\&. +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\&. Index: embedded/man/files/cmdr_vt_time.n ================================================================== --- embedded/man/files/cmdr_vt_time.n +++ embedded/man/files/cmdr_vt_time.n @@ -292,26 +292,27 @@ .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 ISO 8601 -syntax\&. +\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 representation is the epoch for the validated -input\&. +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 %H:%M:%S and -returns the conversion result as its own\&. +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 Index: embedded/www/doc/files/cmdr_actor.html ================================================================== --- embedded/www/doc/files/cmdr_actor.html +++ embedded/www/doc/files/cmdr_actor.html @@ -145,11 +145,11 @@
  • <actor> match parse cmdlist
  • <actor> name
  • <actor> name: name
  • <actor> parse-line line
  • <actor> root
    • -
  • <actor> set key data
    • +
  • <actor> set key -extend -- data
  • <actor> super
  • <actor> super: obj
  • <actor> undocumented
  • <actor> unset key
    • @@ -292,14 +292,18 @@

    The command line.

    <actor> root

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

    -
    <actor> set key data
    +
    <actor> set key -extend -- data

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

    +

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

    +

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

    string key

    The name of the common block to write.

    any data

    The data to store in the block.

    Index: embedded/www/doc/files/cmdr_changes.html ================================================================== --- embedded/www/doc/files/cmdr_changes.html +++ embedded/www/doc/files/cmdr_changes.html @@ -113,12 +113,13 @@
    • Table Of Contents
    • Description
    • Changes
    • Related Documents
    • Bugs, Ideas, Feedback
    • Keywords
      • @@ -130,18 +131,140 @@

      For availability please read Cmdr - How To Get The Sources.

      This document provides an overview of the changes cmdr underwent from version to version.

      Changes

      -

      Changes for version 1.1

      +

      Changes for version 1.2

      +
        +

      1. Added many new standard validation types to package + cmdr::validate:

        +
          +

        1. Double

          2. +

        2. Percent

          3. +

        3. Posint (positive integers, > 0)

          4. +

        4. Paths and channels

          +
            + +

          1. Readable file

            2. +

          2. Writable file

            3. +

          3. Read/writable file

            4. +

          4. Readable directory

            5. +

          5. Read/writeable directory

            6. +

          6. readable path

            7. +

          7. Read/writable path

            8. +

          8. Readable path, as channel

            9. +

          9. Writable path, as channel

            10. +

          10. Read/writable path, as channel

            11. +
          +
          5. +

        5. Date and time related:

          +
            + +

          1. iso8601 date/time,

            2. +

          2. year

            3. +

          3. weekday,

            4. +

          4. hour:minute

            5. +
          +
          6. +
        +
        2. +

      2. Added more helper commands for validation failure messages to + package cmdr::validate::common.

        +
          + +

        1. fail-unknown-thing

          2. +

        2. fail-unknown-thing-msg

          3. +

        3. fail-unknown-simple

          4. +

        4. fail-unknown-simple-msg

          5. +

        5. fail-known-thing

          6. +

        6. fail-known-thing-msg

          7. +

        7. fail-known-simple

          8. +

        8. fail-known-simple-msg +-- TODO -- document --

          9. +
        +
        3. +

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

        4. +

      4. Various new supporting packages:

        +
        +
        cmdr::tty
        +

        Test for terminal.

        +
        cmdr::color
        +

        Color management, ansi control sequences.

        +
        cmdr::ask
        +

        User interaction commands.

        +
        cmdr::pager
        +

        Text display with automatic invokation of + a pager for tall output.

        +
        cmdr::history
        +

        Pluggable management of command history.

        +
        cmdr::table
        +

        Table formatting, simplified interface to + Tcllib's + struct::matrix and + report packages.

        +
        cmdr::validate::valtype-support
        +

        Even more validation types. + Wrappers around the validation commands provided by + Tcllib:

        +
          + +

        1. valtype::creditcard::amex

          2. +

        2. valtype::creditcard::discover

          3. +

        3. valtype::creditcard::mastercard

          4. +

        4. valtype::creditcard::visa

          5. +

        5. valtype::gs1::ean13

          6. +

        6. valtype::iban

          7. +

        7. valtype::imei

          8. +

        8. valtype::isbn

          9. +

        9. valtype::luhn

          10. +

        10. valtype::luhn5

          11. +

        11. valtype::usnpi

          12. +

        12. valtype::verhoeff

          13. +
        +
        +
        5. +

      5. Added support for per-officer options. The most common use case + will likely be the declaration of global options in the root + officer.

        +

        Related to this, a new common block *config* is set to + the active 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.

        6. +

      6. Added support for an option -extend for common blocks, + allowing their extension in a subordinate instead of just + replacing the entire content.

        7. +

      7. Extended boolean options to allow the specification of negative + aliases, i.e. representing the inverted option. See the DSL + commands neg-alias and !alias in + Cmdr - Parameter Specification Language.

        8. +

      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 label in + Cmdr - Parameter Specification Language.

        9. +

      9. Extended officers to accept all unique command prefixes of + their subordinates for dispatch.

        10. +

      10. Modified the help system to use the short format for + interior nodes of the command hierarchy by default.

        11. +

      11. Modified the help system to exclude auto-added commands from + the output generated by format by-category.

        12. +

      12. ... A suite of bug fixes ... // TODO: list the details.

        13. +
      +
      +

      Changes for version 1.1

      1. Fixed broken requirement references in the meta data of packages cmdr::help::json and cmdr::help::sql.

      2. Fixed initialization issues in the help generator.

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

        4. -

      4. Fixed the generation of help format by-categorized, when +

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

      6. Fixed bad method scoping in method extend of officers.

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

        8. @@ -151,11 +274,11 @@ syntax.

      8. Extended officers and privates with method find for path lookup of sub-ordinates.

      -

      Changes for version 1

      +

      Changes for version 1

      This is the first release of cmdr. The changes therefore describe the initial features of the system.

      In detail:

      1. cmdr requires Tcl 8.5 or higher. Index: embedded/www/doc/files/cmdr_dev_dsl.html ================================================================== --- embedded/www/doc/files/cmdr_dev_dsl.html +++ embedded/www/doc/files/cmdr_dev_dsl.html @@ -156,10 +156,12 @@

        Default

        description

        cmdr::actor description:

        ehandler

        ehandler

        +
        shandler
        +

        shandler

        officer

        Officer, forward to DefineAction

        private

        Private, forward to DefineAction

        undocumented
        Index: embedded/www/doc/files/cmdr_dsl_officer.html ================================================================== --- embedded/www/doc/files/cmdr_dsl_officer.html +++ embedded/www/doc/files/cmdr_dsl_officer.html @@ -125,17 +125,18 @@

        Description

        Welcome to the Cmdr project, written by Andreas Kupries.

        @@ -175,11 +176,11 @@
        string name

        The name of the alias.

        string name'...

        The path to the actor, as list of names.

    -
    common name text
    +
    common name -extend -- text

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

    It creates named values, usually code blocks, which can be shared between specifications. Note that while each block is visible in the current officer and its subordinates, parents and @@ -208,10 +209,14 @@ the 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.

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

    +

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

    +

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

    string name

    The name of the common block.

    string text

    The text of the block.

    @@ -247,24 +252,37 @@ the framework are enabled. Without such a handler and its bespoke cleanup code transient state will leak between multiple commands run from such a shell, something which is definitely not wanted.

    -
    officer name script
    +
    shandler 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).

    +

    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 cmdr::history which +provides a command cmdr::history::attach to add the history +management commands to the actor in question.

    +
    officer name script

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

    -
    private name script cmdprefix
    +
    private name script cmdprefix

    This command creates a named subordinate private with its specification script of private commands (See Cmdr - Private Specification Language), and a command prefix to invoke when it is chosen.

    This command prefix is called with a single argument, the cmdr::config instance holding the parameters of the private.

    For an example see section Simple backend of Cmdr - Introduction to the Specification Language.

    -
    undocumented
    +
    undocumented

    This command excludes the officer (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.

    Index: embedded/www/doc/files/cmdr_history.html ================================================================== --- embedded/www/doc/files/cmdr_history.html +++ embedded/www/doc/files/cmdr_history.html @@ -113,11 +113,12 @@

    Synopsis

    @@ -155,11 +156,13 @@ 
         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 +shandler method of officers. See cmdr::officer, and +the Example for more information.

    ::cmdr::history save-to path

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

    The result of the command is the empty string.

    ::cmdr::history initial-limit limit
    @@ -166,11 +169,24 @@

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

    The result of the command is the empty string.

    -

    Bugs, Ideas, Feedback

    +

    Example

    +

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

    +
    +cmdr history initial-limit 20
+cmdr history save-to       ~/.fx_history
+cmdr create fx::fx [file tail $::argv0] {
+    shandler ::cmdr::history::attach
+    [...]
+}
+
    +
    +

    Bugs, Ideas, Feedback

    Both the package(s) and this documentation will undoubtedly contain bugs and other problems. Please report such at Cmdr Tickets.

    Please also report any ideas you may have for enhancements of Index: embedded/www/doc/files/cmdr_pager.html ================================================================== --- embedded/www/doc/files/cmdr_pager.html +++ embedded/www/doc/files/cmdr_pager.html @@ -134,11 +134,11 @@

    Description

    Welcome to the Cmdr project, written by Andreas Kupries.

    For availability please read Cmdr - How To Get The Sources.

    This package provides a single utility command to manage the automatic -paging of long output, like cmdr's automatic help.

    +paging of long output, like it is done cmdr's automatic help.

    API

    ::cmdr::pager text

    When invoked this command either simply prints the text to stdout, Index: embedded/www/doc/files/cmdr_vt_time.html ================================================================== --- embedded/www/doc/files/cmdr_vt_time.html +++ embedded/www/doc/files/cmdr_vt_time.html @@ -134,22 +134,23 @@

    Description

    Welcome to the Cmdr project, written by Andreas Kupries.

    For availability please read Cmdr - How To Get The Sources.

    This package provides the validation type -::cmdr::validate::time which accepts timestamps in ISO 8601 -syntax.

    -

    The internal representation is the epoch for the validated -input.

    +::cmdr::validate::time which accepts timestamps in both ISO 8601 +syntax and as epoch values, i.e. positive integer seconds since the +beginning of unix time.

    +

    The internal, canonical representation is the epoch for the +validated input.

    The type has no input completion.

    The details of the exported standard API can be found in Cmdr - Writing custom validation types. The chosen default is "now".

    A single non-standard method is provided:

    ::cmdr::validate::time 2external epoch
    -

    This method converts the epoch of a time to the form %H:%M:%S and -returns the conversion result as its own.

    +

    This method converts the epoch of a time to the form +%Y-%m-%dT%H:%M:%S and returns the conversion result as its own.

    Bugs, Ideas, Feedback

    Both the package(s) and this documentation will undoubtedly contain bugs and other problems. Index: pager.tcl ================================================================== --- pager.tcl +++ pager.tcl @@ -101,16 +101,14 @@ global env if {[info exists env(PAGER)]} { lappend pager $env(PAGER) } - lappend pager {less -R -f -F} + 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) - # -F quit immediately if the entire text can be shown - # on the screen lappend pager more foreach p $pager { debug.cmdr/pager {Looking for cmd ($p)} set cmd [auto_execok [lindex $p 0]]