cmdr
Check-in [3cf8d6c96e]
Not logged in
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:More documentation updates for coming release.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 3cf8d6c96e3adc360c5df492dbb9157c7d11c7da
User & Date: aku 2016-06-22 05:47:44
Context
2016-06-22
05:50
Updated copyright year, and regenerated the docs. check-in: d0ef9140a0 user: aku tags: trunk
05:47
More documentation updates for coming release. check-in: 3cf8d6c96e user: aku tags: trunk
2015-11-04
22:37
Prep work for an 1.2 release. Draft list of changes since 1.1 check-in: 76b7d37836 user: andreask tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to doc/cmdr_actor.man.

   223    223   [comment {- - -- --- ----- -------- -------------}]
   224    224   [call [cmd <actor>] [method root]]
   225    225   
   226    226   This accessor method returns the root actor instance the actor belongs
   227    227   to.
   228    228   
   229    229   [comment {- - -- --- ----- -------- -------------}]
   230         -[call [cmd <actor>] [method set] [arg key] [arg data]]
          230  +[call [cmd <actor>] [method set] [arg key] [option -extend] [option --] [arg data]]
   231    231   
   232    232   This method sets the contents of the common block named by [arg key]
   233    233   to [arg data]. If the block does not exist it is created. Otherwise
   234    234   its existing content is written over.
   235    235   
          236  +[para] Using option [option -extend] will change the behaviour to
          237  +       extend inherited content instead of writing over it.
          238  +
          239  +[para] Using option [option --] will prevent misinterpretation of the
          240  +       following argument as option, even if it begins with a dash.
          241  +
   236    242   [list_begin arguments]
   237    243   [arg_def string key]  The name of the common block to write.
   238    244   [arg_def any    data] The data to store in the block.
   239    245   [list_end][comment {--- arguments --}]
   240    246   
   241    247   [comment {- - -- --- ----- -------- -------------}]
   242    248   [call [cmd <actor>] [method super]]

Changes to doc/cmdr_history.man.

    31     31   After attachment the actor will accept the following 3 commands:
    32     32   
    33     33   [example {
    34     34       history list ?n?  - Show last n history entries. Defaults to all.
    35     35       history clear     - Drop all history entries
    36     36       history limit ?n? - Limit history to 'n' entries (n >= 0). Unlimited for n < 0.
    37     37   }]
           38  +
           39  +Under most circumstances the attachment is handled through the
           40  +[cmd shandler] method of officers. See [package cmdr::officer], and
           41  +the [sectref Example] for more information.
    38     42   
    39     43   [comment {- - -- --- ----- -------- -------------}]
    40     44   [call [cmd ::cmdr::history] [method save-to] [arg path]]
    41     45   
    42     46   When invoked this command sets the package-wide history save file used
    43     47   by the commands to the [arg path].
    44     48   
................................................................................
    49     53   
    50     54   When invoked this command sets the package-wide limit on history size
    51     55   to [arg limit]. A value less than zero means "no limit".
    52     56   
    53     57   [para] The result of the command is the empty string.
    54     58   
    55     59   [list_end]
           60  +
           61  +[section Example]
           62  +
           63  +Below an example on how to activate history for an officer.
           64  +The example was taken from the [cmd fx] application extending the
           65  +[cmd fossil] DVCS.
           66  +
           67  +[example {
           68  +cmdr history initial-limit 20
           69  +cmdr history save-to       ~/.fx_history
           70  +
           71  +cmdr create fx::fx [file tail $::argv0] {
           72  +    shandler ::cmdr::history::attach
           73  +
           74  +    [...]
           75  +}
           76  +}]
    56     77   
    57     78   [include parts/feedback.inc]
    58     79   [manpage_end]

Changes to doc/cmdr_pager.man.

     7      7   [require cmdr::tty]
     8      8   [require cmdr::pager]
     9      9   [titledesc [vset TITLE_PAGER]]
    10     10   [description]
    11     11   [include parts/welcome.inc]
    12     12   
    13     13   This package provides a single utility command to manage the automatic
    14         -paging of long output, like [vset PROJECT]'s automatic help.
           14  +paging of long output, like it is done [vset PROJECT]'s automatic help.
    15     15   
    16     16   [section API]
    17     17   [list_begin definitions]
    18     18   [comment {- - -- --- ----- -------- -------------}]
    19     19   [call [cmd ::cmdr::pager] [method text]]
    20     20   
    21     21   When invoked this command either simply prints the [arg text] to stdout,

Changes to doc/parts/changes1.1.inc.

     7      7          [package cmdr::help::json] and [package cmdr::help::sql].
     8      8   
     9      9   [enum] Fixed initialization issues in the help generator.
    10     10   
    11     11   [enum] Fixed generated help, added the application name to the output
    12     12          when in a cmdr shell.
    13     13   
    14         -[enum] Fixed the generation of help format by-categorized, when
           14  +[enum] Fixed the generation of help format [const by-categorized], when
    15     15          encountering sections with sub-sections and no commands of their
    16     16          own.
    17     17   
    18     18   [enum] Fixed bad method scoping in method [method extend] of officers.
    19     19   
    20     20   [enum] Extended officer method [method extend] to return the created
    21     21          private, for immediate post-creation re-configuration.

Changes to doc/parts/changes1.2.inc.

     1      1   [subsection {Changes for version 1.2}]
            2  +[vset tcllib http://core.tcl.tk/tcllib/doc/trunk/embedded/www]
            3  +[vset tm     [vset tcllib]/tcllib/files/modules]
     2      4   
     3      5   [list_begin enumerated]
     4      6   [comment {- - -- --- ----- -------- ------------- ---------------------}]
     5      7   
     6         -[enum] Many new validation types:
            8  +[enum] Added many new standard validation types to package
            9  +       [package cmdr::validate]:
           10  +
     7     11   [list_begin enumerated]
     8         -[enum] double
     9         -[enum] percent
    10         -[enum] posint (positive integers, > 0)
    11         -[enum] paths and channels // TODO: List exact
    12         -[enum] Wrappers around the Tcllib valtypes // TODO: List exact
    13         -[enum] Date and time related: iso8601 date/time, year, weekday, hour:minute
           12  +[enum] Double
           13  +[enum] Percent
           14  +[enum] Posint (positive integers, > 0)
           15  +[enum] Paths and channels
           16  +       [list_begin enumerated]
           17  +       [enum] Readable file
           18  +       [enum] Writable file
           19  +       [enum] Read/writable file
           20  +       [enum] Readable directory
           21  +       [enum] Read/writeable directory
           22  +       [enum] readable path
           23  +       [enum] Read/writable path
           24  +       [enum] Readable path, as channel
           25  +       [enum] Writable path, as channel
           26  +       [enum] Read/writable path, as channel
           27  +       [list_end]
           28  +[enum] Date and time related:
           29  +       [list_begin enumerated]
           30  +       [enum] iso8601 date/time,
           31  +       [enum] year
           32  +       [enum] weekday, 
           33  +       [enum] hour:minute
           34  +       [list_end]
    14     35   [list_end]
    15     36   
    16         -[enum] More helper commands for validation failure messages.
           37  +[enum] Added more helper commands for validation failure messages to
           38  +       package [package cmdr::validate::common].
    17     39   
    18         -[enum] Modified integer validation to have a proper internal representation: decimal. Octal, hex, etc. input is now normalized to this.
           40  +       [list_begin enumerated]
           41  +       [enum] [cmd fail-unknown-thing]
           42  +       [enum] [cmd fail-unknown-thing-msg]
           43  +       [enum] [cmd fail-unknown-simple]
           44  +       [enum] [cmd fail-unknown-simple-msg]
           45  +       [enum] [cmd fail-known-thing]
           46  +       [enum] [cmd fail-known-thing-msg]
           47  +       [enum] [cmd fail-known-simple]
           48  +       [enum] [cmd fail-known-simple-msg]
           49  +
           50  +-- TODO -- document --
           51  +
           52  +       [list_end]
           53  +
           54  +[enum] Modified integer validation to have a proper internal
           55  +       representation: decimal. Octal, hex, etc. input is now
           56  +       normalized to this.
    19     57   
    20     58   [enum] Various new supporting packages:
    21     59   [list_begin definitions]
    22         -[def [package tty]]     Test for terminal.
    23         -[def [package color]]   Color management, ansi control sequences.
    24         -[def [package ask]]     User interaction commands.
    25         -[def [package pager]]   Text display with automatic invokation of a pager
    26         -     	      		for tall output.
    27         -[def [package history]] Pluggable management of command history.
    28         -[def [package table]]   Table formatting, simplified interface to Tcllib's
    29         -     	      		[package struct::matrix] and [package report] packages.
           60  +[def [package cmdr::tty]] Test for terminal.
           61  +[def [package cmdr::color]] Color management, ansi control sequences.
           62  +[def [package cmdr::ask]] User interaction commands.
           63  +[def [package cmdr::pager]] Text display with automatic invokation of
           64  +     	      		    a pager for tall output.
           65  +[def [package cmdr::history]] Pluggable management of command history.
           66  +[def [package cmdr::table]] Table formatting, simplified interface to
           67  +      		            [uri [vset tcllib]/toc.html Tcllib]'s
           68  +      		            [package struct::matrix] and
           69  +			    [package report] packages.
           70  +[def [package cmdr::validate::valtype-support]] Even more validation types.
           71  +     Wrappers around the validation commands provided by
           72  +       [uri [vset tcllib]/toc.html Tcllib]:
           73  +       [list_begin enumerated]
           74  +       [enum] [uri [vset tm]/valtype/cc_amex.html       valtype::creditcard::amex]
           75  +       [enum] [uri [vset tm]/valtype/cc_discover.html   valtype::creditcard::discover]
           76  +       [enum] [uri [vset tm]/valtype/cc_mastercard.html valtype::creditcard::mastercard]
           77  +       [enum] [uri [vset tm]/valtype/cc_visa.html       valtype::creditcard::visa]
           78  +       [enum] [uri [vset tm]/valtype/ean13.html         valtype::gs1::ean13]
           79  +       [enum] [uri [vset tm]/valtype/iban.html          valtype::iban]
           80  +       [enum] [uri [vset tm]/valtype/imei.html          valtype::imei]
           81  +       [enum] [uri [vset tm]/valtype/isbn.html          valtype::isbn]
           82  +       [enum] [uri [vset tm]/valtype/luhn.html          valtype::luhn]
           83  +       [enum] [uri [vset tm]/valtype/luhn5.html         valtype::luhn5]
           84  +       [enum] [uri [vset tm]/valtype/usnpi.html         valtype::usnpi]
           85  +       [enum] [uri [vset tm]/valtype/verhoeff.html      valtype::verhoeff]
           86  +       [list_end]
           87  +
    30     88   [list_end]
    31     89   
    32         -[enum] Added support for per-officer options. Most common use case
    33         -       are likely global options added to the root officer.
           90  +[enum] Added support for per-officer options. The most common use case
           91  +       will likely be the declaration of global options in the root
           92  +       officer.
    34     93   
    35         -[para] A new common block [const *config*] is set to the active
    36         -       [package config] instance, different from the defining instance
    37         -       for per-officer options. This gives the per-officer options
    38         -       access to the arguments (and options) of the current command,
    39         -       instead of only their own sibling options.
           94  +[para] Related to this, a new common block [const *config*] is set to
           95  +       the active [package config] instance, which will be different
           96  +       from the defining instance, , for per-officer options. This
           97  +       gives the per-officer options access to the arguments (and
           98  +       options) of the current command, instead of only their own
           99  +       sibling options.
    40    100   
    41         -[enum] Added support for an otion [option -exted] for common blocks
          101  +[enum] Added support for an option [option -extend] for common blocks,
    42    102          allowing their extension in a subordinate instead of just
    43    103          replacing the entire content.
    44    104   
    45         -[enum] Extended boolean options to allow specification of negative
    46         -       aliases, i.e. representing the inverted option.
          105  +[enum] Extended boolean options to allow the specification of negative
          106  +       aliases, i.e. representing the inverted option. See the DSL
          107  +       commands [cmd neg-alias] and [cmd !alias] in
          108  +       [term {Cmdr - Parameter Specification Language}].
          109  +
          110  +[enum] Extended the DSL for options in general with the ability to set
          111  +       a label for the option argument so that the generated help can
          112  +       be more descriptive. The option name is used as fallback for
          113  +       options for which no such label was specified.
          114  +
          115  +       See DSL command [cmd label] in
          116  +       [term {Cmdr - Parameter Specification Language}].
    47    117   
    48    118   [enum] Extended officers to accept all unique command prefixes of
    49    119          their subordinates for dispatch.
    50    120   
    51    121   [enum] Modified the help system to use the [const short] format for
    52    122          interior nodes of the command hierarchy by default.
    53    123   
    54         -[enum] Extended the DSL for options with the ability to set a label
    55         -       for the option argument so that help can be more descriptive.
    56         -       The option name is used as fallback for options with no such
    57         -       label specified.
          124  +[enum] Modified the help system to exclude auto-added commands from
          125  +       the output generated by format [const by-category].
    58    126   
    59    127   [enum] ... A suite of bug fixes ... // TODO: list the details.
    60    128   
    61    129   [comment {- - -- --- ----- -------- ------------- ---------------------}]
    62    130   [list_end]

Changes to doc/parts/dev_dsl_officer.inc.

    13     13   
    14     14   [list_begin definitions]
    15     15   [def [cmd alias]]        [method Alias]
    16     16   [def [cmd common]]       [package cmdr::actor] [method set]
    17     17   [def [cmd default]]      [method Default]
    18     18   [def [cmd description]]  [package cmdr::actor] [method description:]
    19     19   [def [cmd ehandler]]     [method ehandler]
           20  +[def [cmd shandler]]     [method shandler]
    20     21   [def [cmd officer]]      [method Officer], forward to [method DefineAction]
    21     22   [def [cmd private]]      [method Private], forward to [method DefineAction]
    22     23   [def [cmd undocumented]] [package cmdr::actor] [method undocumented]
    23     24   [list_end]

Changes to doc/parts/dsl_officer.inc.

    27     27   The name of the alias.
    28     28   
    29     29   [arg_def string name'...]
    30     30   The path to the actor, as list of names.
    31     31   [list_end]
    32     32   
    33     33   [comment {- - -- --- ----- -------- -------------}]
    34         -[call [cmd common] [arg name] [arg text]]
           34  +[call [cmd common] [arg name] [option -extend] [option --] [arg text]]
    35     35   
    36     36   This is another structuring command, for structuring the specification
    37     37   itself instead of the command tree it declares.
    38     38   
    39     39   [para] It creates named values, usually code blocks, which can be
    40     40   shared between specifications. Note that while each block is visible
    41     41   in the current [term officer] and its subordinates, parents and
................................................................................
    69     69   the [term option] in the example, as it makes the debug setup
    70     70   available to all privates without having to explicitly include the
    71     71   block, and possibly forgetting such.
    72     72   
    73     73   [para] Generally speaking, the framework reserves all blocks whose
    74     74   name begins with a star, i.e [const *], for its own use.
    75     75   
           76  +[para] Using option [option -extend] will change the behaviour to
           77  +       extend inherited content instead of writing over it.
           78  +
           79  +[para] Using option [option --] will prevent misinterpretation of the
           80  +       following argument as option, even if it begins with a dash.
           81  +
    76     82   [list_begin arguments]
    77     83   [arg_def string name]
    78     84   The name of the common block.
    79     85   
    80     86   [arg_def string text]
    81     87   The text of the block.
    82     88   [list_end]
................................................................................
   128    134   This is especially important if the interactive command line shells of
   129    135   the framework are enabled. Without such a handler and its bespoke
   130    136   cleanup code transient state [emph will] leak between multiple
   131    137   commands run from such a shell, something which is definitely not
   132    138   wanted.
   133    139   
   134    140   [list_end]
          141  +
          142  +[comment {- - -- --- ----- -------- -------------}]
          143  +[call [cmd shandler] [arg cmdprefix]]
          144  +
          145  +This is an advanced command which should normally only be specified at
          146  +the top of the whole hierarchy (from which its value will
          147  +automatically propagate to all subordinates).
          148  +
          149  +[para] At runtime the framework will call the specified command prefix
          150  +with a single argument, the command of the actor we wish to
          151  +initialize.
          152  +
          153  +The command prefix is then allowed to modify that actor as it sees
          154  +fit. The common use case will be the extension of the object with
          155  +additional subordinates.
          156  +
          157  +An example of this is the package [package cmdr::history] which
          158  +provides a command [cmd cmdr::history::attach] to add the history
          159  +management commands to the actor in question.
   135    160   
   136    161   [comment {- - -- --- ----- -------- -------------}]
   137    162   [call [cmd officer] [arg name] [arg script]]
   138    163   
   139    164   This command creates a named subordinate [term officer] with its
   140    165   specification [arg script] of officer commands as described here.
   141    166   

Changes to embedded/man/files/cmdr_actor.n.

   311    311   .sp
   312    312   \fB<actor>\fR \fBname:\fR \fIname\fR
   313    313   .sp
   314    314   \fB<actor>\fR \fBparse-line\fR \fIline\fR
   315    315   .sp
   316    316   \fB<actor>\fR \fBroot\fR
   317    317   .sp
   318         -\fB<actor>\fR \fBset\fR \fIkey\fR \fIdata\fR
          318  +\fB<actor>\fR \fBset\fR \fIkey\fR \fB-extend\fR \fB--\fR \fIdata\fR
   319    319   .sp
   320    320   \fB<actor>\fR \fBsuper\fR
   321    321   .sp
   322    322   \fB<actor>\fR \fBsuper:\fR \fIobj\fR
   323    323   .sp
   324    324   \fB<actor>\fR \fBundocumented\fR
   325    325   .sp
................................................................................
   497    497   The command line\&.
   498    498   .RE
   499    499   .TP
   500    500   \fB<actor>\fR \fBroot\fR
   501    501   This accessor method returns the root actor instance the actor belongs
   502    502   to\&.
   503    503   .TP
   504         -\fB<actor>\fR \fBset\fR \fIkey\fR \fIdata\fR
          504  +\fB<actor>\fR \fBset\fR \fIkey\fR \fB-extend\fR \fB--\fR \fIdata\fR
   505    505   This method sets the contents of the common block named by \fIkey\fR
   506    506   to \fIdata\fR\&. If the block does not exist it is created\&. Otherwise
   507    507   its existing content is written over\&.
          508  +.sp
          509  +Using option \fB-extend\fR will change the behaviour to
          510  +extend inherited content instead of writing over it\&.
          511  +.sp
          512  +Using option \fB--\fR will prevent misinterpretation of the
          513  +following argument as option, even if it begins with a dash\&.
   508    514   .RS
   509    515   .TP
   510    516   string \fIkey\fR
   511    517   The name of the common block to write\&.
   512    518   .TP
   513    519   any \fIdata\fR
   514    520   The data to store in the block\&.

Changes to embedded/man/files/cmdr_changes.n.

   279    279   Welcome to the Cmdr project, written by Andreas Kupries\&.
   280    280   .PP
   281    281   For availability please read \fICmdr - How To Get The Sources\fR\&.
   282    282   .PP
   283    283   This document provides an overview of the changes \fBcmdr\fR
   284    284   underwent from version to version\&.
   285    285   .SH CHANGES
          286  +.SS "CHANGES FOR VERSION 1\&.2"
          287  +.IP [1]
          288  +Added many new standard validation types to package
          289  +\fBcmdr::validate\fR:
          290  +.RS
          291  +.IP [1]
          292  +Double
          293  +.IP [2]
          294  +Percent
          295  +.IP [3]
          296  +Posint (positive integers, > 0)
          297  +.IP [4]
          298  +Paths and channels
          299  +.RS
          300  +.IP [1]
          301  +Readable file
          302  +.IP [2]
          303  +Writable file
          304  +.IP [3]
          305  +Read/writable file
          306  +.IP [4]
          307  +Readable directory
          308  +.IP [5]
          309  +Read/writeable directory
          310  +.IP [6]
          311  +readable path
          312  +.IP [7]
          313  +Read/writable path
          314  +.IP [8]
          315  +Readable path, as channel
          316  +.IP [9]
          317  +Writable path, as channel
          318  +.IP [10]
          319  +Read/writable path, as channel
          320  +.RE
          321  +.IP [5]
          322  +Date and time related:
          323  +.RS
          324  +.IP [1]
          325  +iso8601 date/time,
          326  +.IP [2]
          327  +year
          328  +.IP [3]
          329  +weekday,
          330  +.IP [4]
          331  +hour:minute
          332  +.RE
          333  +.RE
          334  +.IP [2]
          335  +Added more helper commands for validation failure messages to
          336  +package \fBcmdr::validate::common\fR\&.
          337  +.RS
          338  +.IP [1]
          339  +\fBfail-unknown-thing\fR
          340  +.IP [2]
          341  +\fBfail-unknown-thing-msg\fR
          342  +.IP [3]
          343  +\fBfail-unknown-simple\fR
          344  +.IP [4]
          345  +\fBfail-unknown-simple-msg\fR
          346  +.IP [5]
          347  +\fBfail-known-thing\fR
          348  +.IP [6]
          349  +\fBfail-known-thing-msg\fR
          350  +.IP [7]
          351  +\fBfail-known-simple\fR
          352  +.IP [8]
          353  +\fBfail-known-simple-msg\fR
          354  +-- TODO -- document --
          355  +.RE
          356  +.IP [3]
          357  +Modified integer validation to have a proper internal
          358  +representation: decimal\&. Octal, hex, etc\&. input is now
          359  +normalized to this\&.
          360  +.IP [4]
          361  +Various new supporting packages:
          362  +.RS
          363  +.TP
          364  +\fBcmdr::tty\fR
          365  +Test for terminal\&.
          366  +.TP
          367  +\fBcmdr::color\fR
          368  +Color management, ansi control sequences\&.
          369  +.TP
          370  +\fBcmdr::ask\fR
          371  +User interaction commands\&.
          372  +.TP
          373  +\fBcmdr::pager\fR
          374  +Text display with automatic invokation of
          375  +a pager for tall output\&.
          376  +.TP
          377  +\fBcmdr::history\fR
          378  +Pluggable management of command history\&.
          379  +.TP
          380  +\fBcmdr::table\fR
          381  +Table formatting, simplified interface to
          382  +\fITcllib\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/toc\&.html]'s
          383  +\fBstruct::matrix\fR and
          384  +\fBreport\fR packages\&.
          385  +.TP
          386  +\fBcmdr::validate::valtype-support\fR
          387  +Even more validation types\&.
          388  +Wrappers around the validation commands provided by
          389  +\fITcllib\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/toc\&.html]:
          390  +.RS
          391  +.IP [1]
          392  +\fIvaltype::creditcard::amex\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/cc_amex\&.html]
          393  +.IP [2]
          394  +\fIvaltype::creditcard::discover\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/cc_discover\&.html]
          395  +.IP [3]
          396  +\fIvaltype::creditcard::mastercard\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/cc_mastercard\&.html]
          397  +.IP [4]
          398  +\fIvaltype::creditcard::visa\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/cc_visa\&.html]
          399  +.IP [5]
          400  +\fIvaltype::gs1::ean13\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/ean13\&.html]
          401  +.IP [6]
          402  +\fIvaltype::iban\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/iban\&.html]
          403  +.IP [7]
          404  +\fIvaltype::imei\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/imei\&.html]
          405  +.IP [8]
          406  +\fIvaltype::isbn\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/isbn\&.html]
          407  +.IP [9]
          408  +\fIvaltype::luhn\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/luhn\&.html]
          409  +.IP [10]
          410  +\fIvaltype::luhn5\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/luhn5\&.html]
          411  +.IP [11]
          412  +\fIvaltype::usnpi\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/usnpi\&.html]
          413  +.IP [12]
          414  +\fIvaltype::verhoeff\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/verhoeff\&.html]
          415  +.RE
          416  +.RE
          417  +.IP [5]
          418  +Added support for per-officer options\&. The most common use case
          419  +will likely be the declaration of global options in the root
          420  +officer\&.
          421  +.sp
          422  +Related to this, a new common block \fB*config*\fR is set to
          423  +the active \fBconfig\fR instance, which will be different
          424  +from the defining instance, , for per-officer options\&. This
          425  +gives the per-officer options access to the arguments (and
          426  +options) of the current command, instead of only their own
          427  +sibling options\&.
          428  +.IP [6]
          429  +Added support for an option \fB-extend\fR for common blocks,
          430  +allowing their extension in a subordinate instead of just
          431  +replacing the entire content\&.
          432  +.IP [7]
          433  +Extended boolean options to allow the specification of negative
          434  +aliases, i\&.e\&. representing the inverted option\&. See the DSL
          435  +commands \fBneg-alias\fR and \fB!alias\fR in
          436  +\fICmdr - Parameter Specification Language\fR\&.
          437  +.IP [8]
          438  +Extended the DSL for options in general with the ability to set
          439  +a label for the option argument so that the generated help can
          440  +be more descriptive\&. The option name is used as fallback for
          441  +options for which no such label was specified\&.
          442  +See DSL command \fBlabel\fR in
          443  +\fICmdr - Parameter Specification Language\fR\&.
          444  +.IP [9]
          445  +Extended officers to accept all unique command prefixes of
          446  +their subordinates for dispatch\&.
          447  +.IP [10]
          448  +Modified the help system to use the \fBshort\fR format for
          449  +interior nodes of the command hierarchy by default\&.
          450  +.IP [11]
          451  +Modified the help system to exclude auto-added commands from
          452  +the output generated by format \fBby-category\fR\&.
          453  +.IP [12]
          454  +\&.\&.\&. A suite of bug fixes \&.\&.\&. // TODO: list the details\&.
          455  +.PP
   286    456   .SS "CHANGES FOR VERSION 1\&.1"
   287    457   .IP [1]
   288    458   Fixed broken requirement references in the meta data of packages
   289    459   \fBcmdr::help::json\fR and \fBcmdr::help::sql\fR\&.
   290    460   .IP [2]
   291    461   Fixed initialization issues in the help generator\&.
   292    462   .IP [3]
   293    463   Fixed generated help, added the application name to the output
   294    464   when in a cmdr shell\&.
   295    465   .IP [4]
   296         -Fixed the generation of help format by-categorized, when
          466  +Fixed the generation of help format \fBby-categorized\fR, when
   297    467   encountering sections with sub-sections and no commands of their
   298    468   own\&.
   299    469   .IP [5]
   300    470   Fixed bad method scoping in method \fBextend\fR of officers\&.
   301    471   .IP [6]
   302    472   Extended officer method \fBextend\fR to return the created
   303    473   private, for immediate post-creation re-configuration\&.

Changes to embedded/man/files/cmdr_dev_dsl.n.

   314    314   \fBDefault\fR
   315    315   .TP
   316    316   \fBdescription\fR
   317    317   \fBcmdr::actor\fR \fBdescription:\fR
   318    318   .TP
   319    319   \fBehandler\fR
   320    320   \fBehandler\fR
          321  +.TP
          322  +\fBshandler\fR
          323  +\fBshandler\fR
   321    324   .TP
   322    325   \fBofficer\fR
   323    326   \fBOfficer\fR, forward to \fBDefineAction\fR
   324    327   .TP
   325    328   \fBprivate\fR
   326    329   \fBPrivate\fR, forward to \fBDefineAction\fR
   327    330   .TP

Changes to embedded/man/files/cmdr_dsl_officer.n.

   275    275   .SH NAME
   276    276   cmdr-spec-dsl-officer \- Cmdr - Officer Specification Language
   277    277   .SH SYNOPSIS
   278    278   \fBalias\fR \fIname\fR \fB=\fR \fIname'\fR\&.\&.\&.
   279    279   .sp
   280    280   \fBalias\fR \fIname\fR
   281    281   .sp
   282         -\fBcommon\fR \fIname\fR \fItext\fR
          282  +\fBcommon\fR \fIname\fR \fB-extend\fR \fB--\fR \fItext\fR
   283    283   .sp
   284    284   \fBdefault\fR
   285    285   .sp
   286    286   \fBdescription\fR \fItext\fR
   287    287   .sp
   288    288   \fBehandler\fR \fIcmdprefix\fR
          289  +.sp
          290  +\fBshandler\fR \fIcmdprefix\fR
   289    291   .sp
   290    292   \fBofficer\fR \fIname\fR \fIscript\fR
   291    293   .sp
   292    294   \fBprivate\fR \fIname\fR \fIscript\fR \fIcmdprefix\fR
   293    295   .sp
   294    296   \fBundocumented\fR
   295    297   .sp
................................................................................
   340    342   string \fIname\fR
   341    343   The name of the alias\&.
   342    344   .TP
   343    345   string \fIname'\&.\&.\&.\fR
   344    346   The path to the actor, as list of names\&.
   345    347   .RE
   346    348   .TP
   347         -\fBcommon\fR \fIname\fR \fItext\fR
          349  +\fBcommon\fR \fIname\fR \fB-extend\fR \fB--\fR \fItext\fR
   348    350   This is another structuring command, for structuring the specification
   349    351   itself instead of the command tree it declares\&.
   350    352   .sp
   351    353   It creates named values, usually code blocks, which can be
   352    354   shared between specifications\&. Note that while each block is visible
   353    355   in the current \fIofficer\fR and its subordinates, parents and
   354    356   siblings have no access\&.
................................................................................
   380    382   specified underneath this \fIofficer\fR\&. A very important trait for
   381    383   the \fIoption\fR in the example, as it makes the debug setup
   382    384   available to all privates without having to explicitly include the
   383    385   block, and possibly forgetting such\&.
   384    386   .sp
   385    387   Generally speaking, the framework reserves all blocks whose
   386    388   name begins with a star, i\&.e \fB*\fR, for its own use\&.
          389  +.sp
          390  +Using option \fB-extend\fR will change the behaviour to
          391  +extend inherited content instead of writing over it\&.
          392  +.sp
          393  +Using option \fB--\fR will prevent misinterpretation of the
          394  +following argument as option, even if it begins with a dash\&.
   387    395   .RS
   388    396   .TP
   389    397   string \fIname\fR
   390    398   The name of the common block\&.
   391    399   .TP
   392    400   string \fItext\fR
   393    401   The text of the block\&.
................................................................................
   429    437   This is especially important if the interactive command line shells of
   430    438   the framework are enabled\&. Without such a handler and its bespoke
   431    439   cleanup code transient state \fIwill\fR leak between multiple
   432    440   commands run from such a shell, something which is definitely not
   433    441   wanted\&.
   434    442   .RE
   435    443   .TP
          444  +\fBshandler\fR \fIcmdprefix\fR
          445  +This is an advanced command which should normally only be specified at
          446  +the top of the whole hierarchy (from which its value will
          447  +automatically propagate to all subordinates)\&.
          448  +.sp
          449  +At runtime the framework will call the specified command prefix
          450  +with a single argument, the command of the actor we wish to
          451  +initialize\&.
          452  +The command prefix is then allowed to modify that actor as it sees
          453  +fit\&. The common use case will be the extension of the object with
          454  +additional subordinates\&.
          455  +An example of this is the package \fBcmdr::history\fR which
          456  +provides a command \fBcmdr::history::attach\fR to add the history
          457  +management commands to the actor in question\&.
          458  +.TP
   436    459   \fBofficer\fR \fIname\fR \fIscript\fR
   437    460   This command creates a named subordinate \fIofficer\fR with its
   438    461   specification \fIscript\fR of officer commands as described here\&.
   439    462   .TP
   440    463   \fBprivate\fR \fIname\fR \fIscript\fR \fIcmdprefix\fR
   441    464   This command creates a named subordinate \fIprivate\fR with its
   442    465   specification \fIscript\fR of private commands

Changes to embedded/man/files/cmdr_history.n.

   314    314   
   315    315   
   316    316       history list ?n?  - Show last n history entries\&. Defaults to all\&.
   317    317       history clear     - Drop all history entries
   318    318       history limit ?n? - Limit history to 'n' entries (n >= 0)\&. Unlimited for n < 0\&.
   319    319   
   320    320   .CE
          321  +.IP
          322  +Under most circumstances the attachment is handled through the
          323  +\fBshandler\fR method of officers\&. See \fBcmdr::officer\fR, and
          324  +the \fBExample\fR for more information\&.
   321    325   .TP
   322    326   \fB::cmdr::history\fR \fBsave-to\fR \fIpath\fR
   323    327   When invoked this command sets the package-wide history save file used
   324    328   by the commands to the \fIpath\fR\&.
   325    329   .sp
   326    330   The result of the command is the empty string\&.
   327    331   .TP
   328    332   \fB::cmdr::history\fR \fBinitial-limit\fR \fIlimit\fR
   329    333   When invoked this command sets the package-wide limit on history size
   330    334   to \fIlimit\fR\&. A value less than zero means "no limit"\&.
   331    335   .sp
   332    336   The result of the command is the empty string\&.
   333    337   .PP
          338  +.SH EXAMPLE
          339  +Below an example on how to activate history for an officer\&.
          340  +The example was taken from the \fBfx\fR application extending the
          341  +\fBfossil\fR DVCS\&.
          342  +.CS
          343  +
          344  +
          345  +cmdr history initial-limit 20
          346  +cmdr history save-to       ~/\&.fx_history
          347  +
          348  +cmdr create fx::fx [file tail $::argv0] {
          349  +    shandler ::cmdr::history::attach
          350  +
          351  +    [\&.\&.\&.]
          352  +}
          353  +
          354  +.CE
   334    355   .SH "BUGS, IDEAS, FEEDBACK"
   335    356   Both the package(s) and this documentation will undoubtedly contain
   336    357   bugs and other problems\&.
   337    358   Please report such at
   338    359   \fICmdr Tickets\fR [https:/core\&.tcl\&.tk/akupries/cmdr]\&.
   339    360   .PP
   340    361   Please also report any ideas you may have for enhancements of

Changes to embedded/man/files/cmdr_pager.n.

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

Changes to embedded/man/files/cmdr_vt_time.n.

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

Changes to embedded/www/doc/files/cmdr_actor.html.

   143    143   <li><a href="#13"><b class="cmd">&lt;actor&gt;</b> <b class="method">keys</b></a></li>
   144    144   <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>
   145    145   <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>
   146    146   <li><a href="#16"><b class="cmd">&lt;actor&gt;</b> <b class="method">name</b></a></li>
   147    147   <li><a href="#17"><b class="cmd">&lt;actor&gt;</b> <b class="method">name:</b> <i class="arg">name</i></a></li>
   148    148   <li><a href="#18"><b class="cmd">&lt;actor&gt;</b> <b class="method">parse-line</b> <i class="arg">line</i></a></li>
   149    149   <li><a href="#19"><b class="cmd">&lt;actor&gt;</b> <b class="method">root</b></a></li>
   150         -<li><a href="#20"><b class="cmd">&lt;actor&gt;</b> <b class="method">set</b> <i class="arg">key</i> <i class="arg">data</i></a></li>
          150  +<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>
   151    151   <li><a href="#21"><b class="cmd">&lt;actor&gt;</b> <b class="method">super</b></a></li>
   152    152   <li><a href="#22"><b class="cmd">&lt;actor&gt;</b> <b class="method">super:</b> <i class="arg">obj</i></a></li>
   153    153   <li><a href="#23"><b class="cmd">&lt;actor&gt;</b> <b class="method">undocumented</b></a></li>
   154    154   <li><a href="#24"><b class="cmd">&lt;actor&gt;</b> <b class="method">unset</b> <i class="arg">key</i></a></li>
   155    155   </ul>
   156    156   </div>
   157    157   </div>
................................................................................
   290    290   <dl class="arguments">
   291    291   <dt>string <i class="arg">line</i></dt>
   292    292   <dd><p>The command line.</p></dd>
   293    293   </dl></dd>
   294    294   <dt><a name="19"><b class="cmd">&lt;actor&gt;</b> <b class="method">root</b></a></dt>
   295    295   <dd><p>This accessor method returns the root actor instance the actor belongs
   296    296   to.</p></dd>
   297         -<dt><a name="20"><b class="cmd">&lt;actor&gt;</b> <b class="method">set</b> <i class="arg">key</i> <i class="arg">data</i></a></dt>
          297  +<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>
   298    298   <dd><p>This method sets the contents of the common block named by <i class="arg">key</i>
   299    299   to <i class="arg">data</i>. If the block does not exist it is created. Otherwise
   300    300   its existing content is written over.</p>
          301  +<p>Using option <b class="option">-extend</b> will change the behaviour to
          302  +       extend inherited content instead of writing over it.</p>
          303  +<p>Using option <b class="option">--</b> will prevent misinterpretation of the
          304  +       following argument as option, even if it begins with a dash.</p>
   301    305   <dl class="arguments">
   302    306   <dt>string <i class="arg">key</i></dt>
   303    307   <dd><p>The name of the common block to write.</p></dd>
   304    308   <dt>any <i class="arg">data</i></dt>
   305    309   <dd><p>The data to store in the block.</p></dd>
   306    310   </dl></dd>
   307    311   <dt><a name="21"><b class="cmd">&lt;actor&gt;</b> <b class="method">super</b></a></dt>

Changes to embedded/www/doc/files/cmdr_changes.html.

   111    111   </div>
   112    112   <div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
   113    113   <ul class="toc">
   114    114   <li class="section"><a href="#toc">Table Of Contents</a></li>
   115    115   <li class="section"><a href="#section1">Description</a></li>
   116    116   <li class="section"><a href="#section2">Changes</a>
   117    117   <ul>
   118         -<li class="subsection"><a href="#subsection1">Changes for version 1.1</a></li>
   119         -<li class="subsection"><a href="#subsection2">Changes for version 1</a></li>
          118  +<li class="subsection"><a href="#subsection1">Changes for version 1.2</a></li>
          119  +<li class="subsection"><a href="#subsection2">Changes for version 1.1</a></li>
          120  +<li class="subsection"><a href="#subsection3">Changes for version 1</a></li>
   120    121   </ul>
   121    122   </li>
   122    123   <li class="section"><a href="#section3">Related Documents</a></li>
   123    124   <li class="section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
   124    125   <li class="section"><a href="#keywords">Keywords</a></li>
   125    126   <li class="section"><a href="#copyright">Copyright</a></li>
   126    127   </ul>
................................................................................
   128    129   <div id="section1" class="section"><h2><a name="section1">Description</a></h2>
   129    130   <p>Welcome to the Cmdr project, written by Andreas Kupries.</p>
   130    131   <p>For availability please read <i class="term"><a href="cmdr_howto_get_sources.html">Cmdr - How To Get The Sources</a></i>.</p>
   131    132   <p>This document provides an overview of the changes <b class="package"><a href="cmdr.html">cmdr</a></b>
   132    133   underwent from version to version.</p>
   133    134   </div>
   134    135   <div id="section2" class="section"><h2><a name="section2">Changes</a></h2>
   135         -<div id="subsection1" class="subsection"><h3><a name="subsection1">Changes for version 1.1</a></h3>
          136  +<div id="subsection1" class="subsection"><h3><a name="subsection1">Changes for version 1.2</a></h3>
          137  +<ol class="enumerated">
          138  +<li><p>Added many new standard validation types to package
          139  +       <b class="package"><a href="cmdr_validate.html">cmdr::validate</a></b>:</p>
          140  +<ol class="enumerated">
          141  +<li><p>Double</p></li>
          142  +<li><p>Percent</p></li>
          143  +<li><p>Posint (positive integers, &gt; 0)</p></li>
          144  +<li><p>Paths and channels</p>
          145  +<ol class="enumerated">
          146  +       
          147  +<li><p>Readable file</p></li>
          148  +<li><p>Writable file</p></li>
          149  +<li><p>Read/writable file</p></li>
          150  +<li><p>Readable directory</p></li>
          151  +<li><p>Read/writeable directory</p></li>
          152  +<li><p>readable path</p></li>
          153  +<li><p>Read/writable path</p></li>
          154  +<li><p>Readable path, as channel</p></li>
          155  +<li><p>Writable path, as channel</p></li>
          156  +<li><p>Read/writable path, as channel</p></li>
          157  +</ol>
          158  +</li>
          159  +<li><p>Date and time related:</p>
          160  +<ol class="enumerated">
          161  +       
          162  +<li><p>iso8601 date/time,</p></li>
          163  +<li><p>year</p></li>
          164  +<li><p>weekday,</p></li>
          165  +<li><p>hour:minute</p></li>
          166  +</ol>
          167  +</li>
          168  +</ol>
          169  +</li>
          170  +<li><p>Added more helper commands for validation failure messages to
          171  +       package <b class="package"><a href="cmdr_vcommon.html">cmdr::validate::common</a></b>.</p>
          172  +<ol class="enumerated">
          173  +       
          174  +<li><p><b class="cmd">fail-unknown-thing</b></p></li>
          175  +<li><p><b class="cmd">fail-unknown-thing-msg</b></p></li>
          176  +<li><p><b class="cmd">fail-unknown-simple</b></p></li>
          177  +<li><p><b class="cmd">fail-unknown-simple-msg</b></p></li>
          178  +<li><p><b class="cmd">fail-known-thing</b></p></li>
          179  +<li><p><b class="cmd">fail-known-thing-msg</b></p></li>
          180  +<li><p><b class="cmd">fail-known-simple</b></p></li>
          181  +<li><p><b class="cmd">fail-known-simple-msg</b>
          182  +-- TODO -- document --</p></li>
          183  +</ol>
          184  +</li>
          185  +<li><p>Modified integer validation to have a proper internal
          186  +       representation: decimal. Octal, hex, etc. input is now
          187  +       normalized to this.</p></li>
          188  +<li><p>Various new supporting packages:</p>
          189  +<dl class="definitions">
          190  +<dt><b class="package"><a href="cmdr_tty.html">cmdr::tty</a></b></dt>
          191  +<dd><p>Test for terminal.</p></dd>
          192  +<dt><b class="package"><a href="cmdr_color.html">cmdr::color</a></b></dt>
          193  +<dd><p>Color management, ansi control sequences.</p></dd>
          194  +<dt><b class="package"><a href="cmdr_ask.html">cmdr::ask</a></b></dt>
          195  +<dd><p>User interaction commands.</p></dd>
          196  +<dt><b class="package"><a href="cmdr_pager.html">cmdr::pager</a></b></dt>
          197  +<dd><p>Text display with automatic invokation of
          198  +     	      		    a pager for tall output.</p></dd>
          199  +<dt><b class="package"><a href="cmdr_history.html">cmdr::history</a></b></dt>
          200  +<dd><p>Pluggable management of command history.</p></dd>
          201  +<dt><b class="package">cmdr::table</b></dt>
          202  +<dd><p>Table formatting, simplified interface to
          203  +      		            <a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/toc.html">Tcllib</a>'s
          204  +      		            <b class="package">struct::matrix</b> and
          205  +			    <b class="package">report</b> packages.</p></dd>
          206  +<dt><b class="package">cmdr::validate::valtype-support</b></dt>
          207  +<dd><p>Even more validation types.
          208  +     Wrappers around the validation commands provided by
          209  +       <a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/toc.html">Tcllib</a>:</p>
          210  +<ol class="enumerated">
          211  +       
          212  +<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>
          213  +<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>
          214  +<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>
          215  +<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>
          216  +<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>
          217  +<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/iban.html">valtype::iban</a></p></li>
          218  +<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/imei.html">valtype::imei</a></p></li>
          219  +<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/isbn.html">valtype::isbn</a></p></li>
          220  +<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/luhn.html">valtype::luhn</a></p></li>
          221  +<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/luhn5.html">valtype::luhn5</a></p></li>
          222  +<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/usnpi.html">valtype::usnpi</a></p></li>
          223  +<li><p><a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/verhoeff.html">valtype::verhoeff</a></p></li>
          224  +</ol></dd>
          225  +</dl>
          226  +</li>
          227  +<li><p>Added support for per-officer options. The most common use case
          228  +       will likely be the declaration of global options in the root
          229  +       officer.</p>
          230  +<p>Related to this, a new common block <b class="const">*config*</b> is set to
          231  +       the active <b class="package">config</b> instance, which will be different
          232  +       from the defining instance, , for per-officer options. This
          233  +       gives the per-officer options access to the arguments (and
          234  +       options) of the current command, instead of only their own
          235  +       sibling options.</p></li>
          236  +<li><p>Added support for an option <b class="option">-extend</b> for common blocks,
          237  +       allowing their extension in a subordinate instead of just
          238  +       replacing the entire content.</p></li>
          239  +<li><p>Extended boolean options to allow the specification of negative
          240  +       aliases, i.e. representing the inverted option. See the DSL
          241  +       commands <b class="cmd">neg-alias</b> and <b class="cmd">!alias</b> in
          242  +       <i class="term"><a href="cmdr_dsl_parameter.html">Cmdr - Parameter Specification Language</a></i>.</p></li>
          243  +<li><p>Extended the DSL for options in general with the ability to set
          244  +       a label for the option argument so that the generated help can
          245  +       be more descriptive. The option name is used as fallback for
          246  +       options for which no such label was specified.
          247  +       See DSL command <b class="cmd">label</b> in
          248  +       <i class="term"><a href="cmdr_dsl_parameter.html">Cmdr - Parameter Specification Language</a></i>.</p></li>
          249  +<li><p>Extended officers to accept all unique command prefixes of
          250  +       their subordinates for dispatch.</p></li>
          251  +<li><p>Modified the help system to use the <b class="const">short</b> format for
          252  +       interior nodes of the command hierarchy by default.</p></li>
          253  +<li><p>Modified the help system to exclude auto-added commands from
          254  +       the output generated by format <b class="const">by-category</b>.</p></li>
          255  +<li><p>... A suite of bug fixes ... // TODO: list the details.</p></li>
          256  +</ol>
          257  +</div>
          258  +<div id="subsection2" class="subsection"><h3><a name="subsection2">Changes for version 1.1</a></h3>
   136    259   <ol class="enumerated">
   137    260   <li><p>Fixed broken requirement references in the meta data of packages
   138    261          <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>
   139    262   <li><p>Fixed initialization issues in the help generator.</p></li>
   140    263   <li><p>Fixed generated help, added the application name to the output
   141    264          when in a cmdr shell.</p></li>
   142         -<li><p>Fixed the generation of help format by-categorized, when
          265  +<li><p>Fixed the generation of help format <b class="const">by-categorized</b>, when
   143    266          encountering sections with sub-sections and no commands of their
   144    267          own.</p></li>
   145    268   <li><p>Fixed bad method scoping in method <b class="method">extend</b> of officers.</p></li>
   146    269   <li><p>Extended officer method <b class="method">extend</b> to return the created
   147    270          private, for immediate post-creation re-configuration.</p></li>
   148    271   <li><p>Extended system with new help format <i class="term">tcl</i>, and associated
   149    272          package <b class="package"><a href="cmdr_help_tcl.html">cmdr::help::tcl</a></b>. Similar to format <i class="term">json</i>
   150    273          the help is printed as a nested data structure, just using Tcl
   151    274          syntax.</p></li>
   152    275   <li><p>Extended officers and privates with method <b class="method">find</b> for
   153    276          path lookup of sub-ordinates.</p></li>
   154    277   </ol>
   155    278   </div>
   156         -<div id="subsection2" class="subsection"><h3><a name="subsection2">Changes for version 1</a></h3>
          279  +<div id="subsection3" class="subsection"><h3><a name="subsection3">Changes for version 1</a></h3>
   157    280   <p>This is the first release of cmdr.
   158    281   The changes therefore describe the initial features of the system.</p>
   159    282   <p>In detail:</p>
   160    283   <ol class="enumerated">
   161    284   <li><p>cmdr requires Tcl 8.5 or higher.
   162    285          Tcl 8.4 or less is not supported.</p></li>
   163    286   <li><p>The framework provides a DSL for the declaration of a hierarchy

Changes to embedded/www/doc/files/cmdr_dev_dsl.html.

   154    154   <dd><p><b class="package"><a href="cmdr_actor.html">cmdr::actor</a></b> <b class="method">set</b></p></dd>
   155    155   <dt><b class="cmd">default</b></dt>
   156    156   <dd><p><b class="method">Default</b></p></dd>
   157    157   <dt><b class="cmd">description</b></dt>
   158    158   <dd><p><b class="package"><a href="cmdr_actor.html">cmdr::actor</a></b> <b class="method">description:</b></p></dd>
   159    159   <dt><b class="cmd">ehandler</b></dt>
   160    160   <dd><p><b class="method">ehandler</b></p></dd>
          161  +<dt><b class="cmd">shandler</b></dt>
          162  +<dd><p><b class="method">shandler</b></p></dd>
   161    163   <dt><b class="cmd">officer</b></dt>
   162    164   <dd><p><b class="method">Officer</b>, forward to <b class="method">DefineAction</b></p></dd>
   163    165   <dt><b class="cmd">private</b></dt>
   164    166   <dd><p><b class="method">Private</b>, forward to <b class="method">DefineAction</b></p></dd>
   165    167   <dt><b class="cmd">undocumented</b></dt>
   166    168   <dd><p><b class="package"><a href="cmdr_actor.html">cmdr::actor</a></b> <b class="method">undocumented</b></p></dd>
   167    169   </dl>

Changes to embedded/www/doc/files/cmdr_dsl_officer.html.

   123    123   </ul>
   124    124   </div>
   125    125   <div id="synopsis" class="section"><h2><a name="synopsis">Synopsis</a></h2>
   126    126   <div class="synopsis">
   127    127   <ul class="syntax">
   128    128   <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>
   129    129   <li><a href="#2"><b class="cmd">alias</b> <i class="arg">name</i></a></li>
   130         -<li><a href="#3"><b class="cmd">common</b> <i class="arg">name</i> <i class="arg">text</i></a></li>
          130  +<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>
   131    131   <li><a href="#4"><b class="cmd">default</b></a></li>
   132    132   <li><a href="#5"><b class="cmd">description</b> <i class="arg">text</i></a></li>
   133    133   <li><a href="#6"><b class="cmd">ehandler</b> <i class="arg">cmdprefix</i></a></li>
   134         -<li><a href="#7"><b class="cmd">officer</b> <i class="arg">name</i> <i class="arg">script</i></a></li>
   135         -<li><a href="#8"><b class="cmd">private</b> <i class="arg">name</i> <i class="arg">script</i> <i class="arg">cmdprefix</i></a></li>
   136         -<li><a href="#9"><b class="cmd">undocumented</b></a></li>
          134  +<li><a href="#7"><b class="cmd">shandler</b> <i class="arg">cmdprefix</i></a></li>
          135  +<li><a href="#8"><b class="cmd">officer</b> <i class="arg">name</i> <i class="arg">script</i></a></li>
          136  +<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>
          137  +<li><a href="#10"><b class="cmd">undocumented</b></a></li>
   137    138   </ul>
   138    139   </div>
   139    140   </div>
   140    141   <div id="section1" class="section"><h2><a name="section1">Description</a></h2>
   141    142   <p>Welcome to the Cmdr project, written by Andreas Kupries.</p>
   142    143   <p>For availability please read <i class="term"><a href="cmdr_howto_get_sources.html">Cmdr - How To Get The Sources</a></i>.</p>
   143    144   <p>This document is for users of the cmdr framework. It introduces the
................................................................................
   173    174   command.</p>
   174    175   <dl class="arguments">
   175    176   <dt>string <i class="arg">name</i></dt>
   176    177   <dd><p>The name of the alias.</p></dd>
   177    178   <dt>string <i class="arg">name'...</i></dt>
   178    179   <dd><p>The path to the actor, as list of names.</p></dd>
   179    180   </dl></dd>
   180         -<dt><a name="3"><b class="cmd">common</b> <i class="arg">name</i> <i class="arg">text</i></a></dt>
          181  +<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>
   181    182   <dd><p>This is another structuring command, for structuring the specification
   182    183   itself instead of the command tree it declares.</p>
   183    184   <p>It creates named values, usually code blocks, which can be
   184    185   shared between specifications. Note that while each block is visible
   185    186   in the current <i class="term">officer</i> and its subordinates, parents and
   186    187   siblings have no access.</p>
   187    188   <p>An example of such a block would be</p>
................................................................................
   206    207   <i class="term">private</i> specifications, i.e. shared across all the privates
   207    208   specified underneath this <i class="term">officer</i>. A very important trait for
   208    209   the <i class="term">option</i> in the example, as it makes the debug setup
   209    210   available to all privates without having to explicitly include the
   210    211   block, and possibly forgetting such.</p>
   211    212   <p>Generally speaking, the framework reserves all blocks whose
   212    213   name begins with a star, i.e <b class="const">*</b>, for its own use.</p>
          214  +<p>Using option <b class="option">-extend</b> will change the behaviour to
          215  +       extend inherited content instead of writing over it.</p>
          216  +<p>Using option <b class="option">--</b> will prevent misinterpretation of the
          217  +       following argument as option, even if it begins with a dash.</p>
   213    218   <dl class="arguments">
   214    219   <dt>string <i class="arg">name</i></dt>
   215    220   <dd><p>The name of the common block.</p></dd>
   216    221   <dt>string <i class="arg">text</i></dt>
   217    222   <dd><p>The text of the block.</p></dd>
   218    223   </dl></dd>
   219    224   <dt><a name="4"><b class="cmd">default</b></a></dt>
................................................................................
   245    250   and/or actions may have set during their execution.
   246    251   This is especially important if the interactive command line shells of
   247    252   the framework are enabled. Without such a handler and its bespoke
   248    253   cleanup code transient state <em>will</em> leak between multiple
   249    254   commands run from such a shell, something which is definitely not
   250    255   wanted.</p></li>
   251    256   </ol></dd>
   252         -<dt><a name="7"><b class="cmd">officer</b> <i class="arg">name</i> <i class="arg">script</i></a></dt>
          257  +<dt><a name="7"><b class="cmd">shandler</b> <i class="arg">cmdprefix</i></a></dt>
          258  +<dd><p>This is an advanced command which should normally only be specified at
          259  +the top of the whole hierarchy (from which its value will
          260  +automatically propagate to all subordinates).</p>
          261  +<p>At runtime the framework will call the specified command prefix
          262  +with a single argument, the command of the actor we wish to
          263  +initialize.
          264  +The command prefix is then allowed to modify that actor as it sees
          265  +fit. The common use case will be the extension of the object with
          266  +additional subordinates.
          267  +An example of this is the package <b class="package"><a href="cmdr_history.html">cmdr::history</a></b> which
          268  +provides a command <b class="cmd">cmdr::history::attach</b> to add the history
          269  +management commands to the actor in question.</p></dd>
          270  +<dt><a name="8"><b class="cmd">officer</b> <i class="arg">name</i> <i class="arg">script</i></a></dt>
   253    271   <dd><p>This command creates a named subordinate <i class="term">officer</i> with its
   254    272   specification <i class="arg">script</i> of officer commands as described here.</p></dd>
   255         -<dt><a name="8"><b class="cmd">private</b> <i class="arg">name</i> <i class="arg">script</i> <i class="arg">cmdprefix</i></a></dt>
          273  +<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>
   256    274   <dd><p>This command creates a named subordinate <i class="term">private</i> with its
   257    275   specification <i class="arg">script</i> of private commands
   258    276   (See <i class="term"><a href="cmdr_dsl_private.html">Cmdr - Private Specification Language</a></i>), and a command prefix to invoke
   259    277   when it is chosen.</p>
   260    278   <p>This command prefix is called with a single argument, the
   261    279   <b class="package"><a href="cmdr_config.html">cmdr::config</a></b> instance holding the <i class="term">parameter</i>s of the
   262    280   private.</p>
   263    281   <p>For an example see section <i class="term">Simple backend</i>
   264    282   of <i class="term"><a href="cmdr_dsl.html">Cmdr - Introduction to the Specification Language</a></i>.</p></dd>
   265         -<dt><a name="9"><b class="cmd">undocumented</b></a></dt>
          283  +<dt><a name="10"><b class="cmd">undocumented</b></a></dt>
   266    284   <dd><p>This command excludes the <i class="term">officer</i> (and its subordinates) from
   267    285   the generated help.
   268    286   Note that subordinates reachable through aliases may be included,
   269    287   under the alias name, if they are not explicitly excluded themselves.</p></dd>
   270    288   </dl>
   271    289   <p>Please continue reading with <i class="term"><a href="cmdr_dsl_private.html">Cmdr - Private Specification Language</a></i>.</p>
   272    290   </div>

Changes to embedded/www/doc/files/cmdr_history.html.

   111    111   </div>
   112    112   <div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
   113    113   <ul class="toc">
   114    114   <li class="section"><a href="#toc">Table Of Contents</a></li>
   115    115   <li class="section"><a href="#synopsis">Synopsis</a></li>
   116    116   <li class="section"><a href="#section1">Description</a></li>
   117    117   <li class="section"><a href="#section2">API</a></li>
   118         -<li class="section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
          118  +<li class="section"><a href="#section3">Example</a></li>
          119  +<li class="section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
   119    120   <li class="section"><a href="#keywords">Keywords</a></li>
   120    121   <li class="section"><a href="#copyright">Copyright</a></li>
   121    122   </ul>
   122    123   </div>
   123    124   <div id="synopsis" class="section"><h2><a name="synopsis">Synopsis</a></h2>
   124    125   <div class="synopsis">
   125    126   <ul class="requirements">
................................................................................
   153    154   </dl>
   154    155   <p>After attachment the actor will accept the following 3 commands:</p>
   155    156   <pre class="example">
   156    157       history list ?n?  - Show last n history entries. Defaults to all.
   157    158       history clear     - Drop all history entries
   158    159       history limit ?n? - Limit history to 'n' entries (n &gt;= 0). Unlimited for n &lt; 0.
   159    160   </pre>
   160         -</dd>
          161  +<p>Under most circumstances the attachment is handled through the
          162  +<b class="cmd">shandler</b> method of officers. See <b class="package"><a href="cmdr_officer.html">cmdr::officer</a></b>, and
          163  +the <span class="sectref"><a href="#section3">Example</a></span> for more information.</p></dd>
   161    164   <dt><a name="2"><b class="cmd">::cmdr::history</b> <b class="method">save-to</b> <i class="arg">path</i></a></dt>
   162    165   <dd><p>When invoked this command sets the package-wide history save file used
   163    166   by the commands to the <i class="arg">path</i>.</p>
   164    167   <p>The result of the command is the empty string.</p></dd>
   165    168   <dt><a name="3"><b class="cmd">::cmdr::history</b> <b class="method">initial-limit</b> <i class="arg">limit</i></a></dt>
   166    169   <dd><p>When invoked this command sets the package-wide limit on history size
   167    170   to <i class="arg">limit</i>. A value less than zero means &quot;no limit&quot;.</p>
   168    171   <p>The result of the command is the empty string.</p></dd>
   169    172   </dl>
   170    173   </div>
   171         -<div id="section3" class="section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
          174  +<div id="section3" class="section"><h2><a name="section3">Example</a></h2>
          175  +<p>Below an example on how to activate history for an officer.
          176  +The example was taken from the <b class="cmd">fx</b> application extending the
          177  +<b class="cmd">fossil</b> DVCS.</p>
          178  +<pre class="example">
          179  +cmdr history initial-limit 20
          180  +cmdr history save-to       ~/.fx_history
          181  +cmdr create fx::fx [file tail $::argv0] {
          182  +    shandler ::cmdr::history::attach
          183  +    [...]
          184  +}
          185  +</pre>
          186  +</div>
          187  +<div id="section4" class="section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
   172    188   <p>Both the package(s) and this documentation will undoubtedly contain
   173    189   bugs and other problems.
   174    190   Please report such at
   175    191   <a href="https:/core.tcl.tk/akupries/cmdr">Cmdr Tickets</a>.</p>
   176    192   <p>Please also report any ideas you may have for enhancements of
   177    193   either package(s) and/or documentation.</p>
   178    194   </div>

Changes to embedded/www/doc/files/cmdr_pager.html.

   132    132   </ul>
   133    133   </div>
   134    134   </div>
   135    135   <div id="section1" class="section"><h2><a name="section1">Description</a></h2>
   136    136   <p>Welcome to the Cmdr project, written by Andreas Kupries.</p>
   137    137   <p>For availability please read <i class="term"><a href="cmdr_howto_get_sources.html">Cmdr - How To Get The Sources</a></i>.</p>
   138    138   <p>This package provides a single utility command to manage the automatic
   139         -paging of long output, like cmdr's automatic help.</p>
          139  +paging of long output, like it is done cmdr's automatic help.</p>
   140    140   </div>
   141    141   <div id="section2" class="section"><h2><a name="section2">API</a></h2>
   142    142   <dl class="definitions">
   143    143   <dt><a name="1"><b class="cmd">::cmdr::pager</b> <b class="method">text</b></a></dt>
   144    144   <dd><p>When invoked this command either simply prints the <i class="arg">text</i> to stdout,
   145    145   or invokes an external pager application to manage the output.</p>
   146    146   <p>The pager is only invoked when</p>

Changes to embedded/www/doc/files/cmdr_vt_time.html.

   132    132   </ul>
   133    133   </div>
   134    134   </div>
   135    135   <div id="section1" class="section"><h2><a name="section1">Description</a></h2>
   136    136   <p>Welcome to the Cmdr project, written by Andreas Kupries.</p>
   137    137   <p>For availability please read <i class="term"><a href="cmdr_howto_get_sources.html">Cmdr - How To Get The Sources</a></i>.</p>
   138    138   <p>This package provides the validation type
   139         -<b class="cmd">::cmdr::validate::time</b> which accepts timestamps in ISO 8601
   140         -syntax.</p>
   141         -<p>The internal representation is the epoch for the validated
   142         -input.</p>
          139  +<b class="cmd">::cmdr::validate::time</b> which accepts timestamps in both ISO 8601
          140  +syntax and as epoch values, i.e. positive integer seconds since the
          141  +beginning of unix time.</p>
          142  +<p>The internal, canonical representation is the epoch for the
          143  +validated input.</p>
   143    144   <p>The type has no input completion.</p>
   144    145   <p>The details of the exported standard API can be found in
   145    146   <i class="term"><a href="cmdr_vtypes.html">Cmdr - Writing custom validation types</a></i>. The chosen default is &quot;now&quot;.</p>
   146    147   <p>A single non-standard method is provided:</p>
   147    148   <dl class="definitions">
   148    149   <dt><a name="1"><b class="cmd">::cmdr::validate::time</b> <b class="method">2external</b> <i class="arg">epoch</i></a></dt>
   149         -<dd><p>This method converts the epoch of a time to the form %H:%M:%S and
   150         -returns the conversion result as its own.</p></dd>
          150  +<dd><p>This method converts the epoch of a time to the form
          151  +<b class="const">%Y-%m-%dT%H:%M:%S</b> and returns the conversion result as its own.</p></dd>
   151    152   </dl>
   152    153   </div>
   153    154   <div id="section2" class="section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
   154    155   <p>Both the package(s) and this documentation will undoubtedly contain
   155    156   bugs and other problems.
   156    157   Please report such at
   157    158   <a href="https:/core.tcl.tk/akupries/cmdr">Cmdr Tickets</a>.</p>

Changes to pager.tcl.

    99     99       # can still disable paging, when nothing is found. We look for the
   100    100       # user's choice first.
   101    101   
   102    102       global env
   103    103       if {[info exists env(PAGER)]} {
   104    104   	lappend pager $env(PAGER)
   105    105       }
   106         -    lappend pager {less -R -f -F}
          106  +    lappend pager {less -R -f}
   107    107       # -R Show ANSI colors
   108    108       # -f do not prompt when thinking that file is binary
   109    109       #    (for example due to ANSI colors)
   110         -    # -F quit immediately if the entire text can be shown
   111         -    #    on the screen
   112    110       lappend pager more
   113    111   
   114    112       foreach p $pager {
   115    113   	debug.cmdr/pager {Looking for cmd ($p)}
   116    114   	set cmd [auto_execok [lindex $p 0]]
   117    115   	if {[llength $cmd]} {
   118    116   	    lappend cmd {*}[lrange $p 1 end]