Index: core/officer.tcl
==================================================================
--- core/officer.tcl
+++ core/officer.tcl
@@ -77,37 +77,40 @@
next
my super: $super
my name: $name
- set myactions $actions ; # Action spec for future initialization
- set myinit no ; # Dispatch map will be initialized lazily
- set mymap {} ; # Action map starts knowing nothing
- set mypmap {} ; # Ditto for the map of action abbreviations.
- set mycommands {} ; # Ditto
- set myccommands {} ; # Ditto, derived cache, see method CCommands.
- set mychildren {} ; # List of created subordinates.
- set myhandler {} ; # Handler around cmd parsing and execution.
- set myshandler {} ; # Setup handler, run after regular object
- # # initialization from its definition.
+ set myactions $actions ; # Action spec for future initialization
+ set myinit no ; # Dispatch map will be initialized lazily
+ set mymap {} ; # Action map starts knowing nothing
+ set mypmap {} ; # Ditto for the map of action abbreviations.
+ set mycommands {} ; # Ditto
+ set myccommands {} ; # Ditto, derived cache, see method CCommands.
+ set mychildren {} ; # List of created subordinates.
+ set myintercept {} ; # Handler around cmd parsing and execution.
+ set mycustomsetup {} ; # List of setup handlers, run after regular object
+ # # initialization from its definition.
set myconfig {}
return
}
# # ## ### ##### ######## #############
- method ehandler {cmd} {
- debug.cmdr/officer {[self] $cmd}
- set myhandler $cmd
- return
- }
-
- method shandler {cmd} {
- debug.cmdr/officer {[self] $cmd}
- set myshandler $cmd
- return
- }
+ method intercept {cmd} {
+ debug.cmdr/officer {[self] $cmd}
+ set myintercept $cmd
+ return
+ }
+
+ method custom-setup {cmd} {
+ debug.cmdr/officer {[self] $cmd}
+ lappend mycustomsetup $cmd
+ return
+ }
+
+ forward ehandler my intercept
+ forward shandler my custom-setup
# # ## ### ##### ######## #############
## Public API. (Introspection, mostly).
## - Determine set of known actions.
## - Determine default action.
@@ -252,13 +255,13 @@
} [mymethod shell-exit]
}
# Invoke the user-specified hook for extending a newly-made
# officer, if any.
- debug.cmdr/officer {[debug caller] | call shandler}
- if {[llength $myshandler]} {
- {*}$myshandler [self]
+ debug.cmdr/officer {[debug caller] | call custom-setup}
+ foreach cmd $mycustomsetup {
+ {*}$cmd [self]
}
debug.cmdr/officer {[debug caller] | /done}
return
}
@@ -269,12 +272,16 @@
# "description:" and "common" are superclass methods, and
# renamed to their DSL counterparts. The others are unexported
# instance methods of this class.
link \
- {ehandler ehandler} \
- {shandler shandler} \
+ {intercept intercept} \
+ {ehandler intercept} \
+ \
+ {custom-setup custom-setup} \
+ {shandler custom-setup} \
+ \
{private Private} \
{officer Officer} \
{default Default} \
{alias Alias} \
{description description:} \
@@ -375,13 +382,15 @@
# officer itself. No special code for cleanup required.
set handler [self namespace]::${what}_$name
cmdr::$what create $handler [self] $name {*}$args
- # Propagate error and setup handlers.
- $handler ehandler $myhandler
- $handler shandler $myshandler
+ # Propagate error (interceptor) and custom setup handlers.
+ $handler intercept $myintercept
+ foreach cmd $mycustomsetup {
+ $handler custom-setup $cmd
+ }
lappend mychildren $handler
my Def $name $handler
return $handler
@@ -503,13 +512,14 @@
# Delegate to the handler for a known command.
if {[my Known $cmd]} {
debug.cmdr/officer {[debug caller] | /known $cmd}
- my lappend *prefix* $cmd
- [my lookup $cmd] do {*}$remainder
+ [my root] lappend *prefix* $cmd
+ debug.cmdr/officer {[debug caller] | /prefix [my root] ([my get *prefix*])}
+ [my lookup $cmd] do {*}$remainder
debug.cmdr/officer {[debug caller] | /done known}
return
}
# The command word is not known. Delegate the full command to
@@ -773,13 +783,13 @@
}
# # ## ### ##### ######## #############
variable myinit myactions mymap mycommands myccommands mychildren \
- myreplexit myhandler mypmap myshandler myconfig
+ myreplexit myintercept mypmap mycustomsetup myconfig
# # ## ### ##### ######## #############
}
# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::officer 1.4.1
Index: core/private.tcl
==================================================================
--- core/private.tcl
+++ core/private.tcl
@@ -62,11 +62,11 @@
my name: $name
set myarguments $arguments
set mycmd $cmdprefix
set myinit 0
- set myhandler {}
+ set myintercept {}
return
}
# # ## ### ##### ######## #############
@@ -91,22 +91,25 @@
"The command \"$prefix\" has no sub-commands, unexpected word \"$word\""
}
# # ## ### ##### ######## #############
- method ehandler {cmd} {
+ method intercept {cmd} {
+ debug.cmdr/private {}
+ set myintercept $cmd
+ return
+ }
+
+ method custom-setup {cmd} {
debug.cmdr/private {}
- set myhandler $cmd
+ # Privates have no hook/handler for custom setup.
+ # Ignore the inherited definition.
return
}
- method shandler {cmd} {
- debug.cmdr/private {}
- # Privates have no setup handler/hook.
- # Ignoring the inherited definition.
- return
- }
+ forward ehandler my intercept
+ forward shandler my custom-setup
# # ## ### ##### ######## #############
## Internal. Argument processing. Defered until required.
## Core setup code runs only once.
@@ -137,14 +140,14 @@
debug.cmdr/private {}
my Setup
my history-add [my FullCmd $args]
- if {[llength $myhandler]} {
+ if {[llength $myintercept]} {
# The handler is expected to have a try/finally construct
- # which captures all of interest.
- {*}$myhandler {
+ # which captures everything of interest to it.
+ {*}$myintercept {
my Run $args
}
} else {
my Run $args
}
@@ -209,13 +212,13 @@
config $m {*}$args
}
# # ## ### ##### ######## #############
- variable myarguments mycmd myinit myconfig myhandler
+ variable myarguments mycmd myinit myconfig myintercept
# # ## ### ##### ######## #############
}
# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::private 1.3.1
Index: doc/cmdr_history.man
==================================================================
--- doc/cmdr_history.man
+++ doc/cmdr_history.man
@@ -35,11 +35,11 @@
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
+method [cmd custom-setup] of officers. See [package cmdr::officer], and
the [sectref Example] for more information.
[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::history] [method save-to] [arg path]]
@@ -67,13 +67,13 @@
[example {
cmdr history initial-limit 20
cmdr history save-to ~/.fx_history
cmdr create fx::fx [file tail $::argv0] {
- shandler ::cmdr::history::attach
+ custom-setup ::cmdr::history::attach
[...]
}
}]
[include parts/feedback.inc]
[manpage_end]
Index: doc/cmdr_officer.man
==================================================================
--- doc/cmdr_officer.man
+++ doc/cmdr_officer.man
@@ -145,11 +145,15 @@
[arg_def string word]
The words of the command line to parse and match to parameters.
[list_end][comment arguments]
[comment {- - -- --- ----- -------- -------------}]
+[call [cmd ] [method intercept] [arg cmd]]
[call [cmd ] [method ehandler] [arg cmd]]
+
+[emph Note:] While the form [method ehandler] is still usable, it is
+deprecated and will be removed in a future release.
This method specifies a command prefix to wrap around the parsing of
the command line for the officer, and the execution of its action.
[list_begin arguments]
@@ -160,10 +164,34 @@
prefix then has the responsbility to perform any custom cleanup action
required by the application using the framework to prevent leakage of
data between multiple commands executed one after the other (i.e. in
an interactive shell run by the framework).
[list_end][comment arguments]
+
+[comment {- - -- --- ----- -------- -------------}]
+[call [cmd ] [method custom-setup] [arg cmd]]
+
+This method specifies a command prefix which will be run all the
+regular setup of the officer from its specification is done, to
+perform customizations.
+
+[para] An example of this can be seen in the package
+[package cmdr::history]. It provides a command
+[cmd cmdr::history::attach] to add the history management commands to
+the actor in question, suitable as argument to this method.
+
+[para] When called multiple times, the specified commands
+accumulate. This makes it easy to specify several indepedent
+customizations.
+
+[list_begin arguments]
+[arg_def cmd-prefix cmd]
+A command prefix taking a single argument, the instance command of an
+[package cmd::actor]. The command prefix has full access to this actor
+and can modify it as it sees fit. The common use case will be the
+extension of the actor with additional subordinates.
+[list_end][comment arguments]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd ] [method exit]]
This hook-method for the main shell returns a boolean value indicating
Index: doc/cmdr_private.man
==================================================================
--- doc/cmdr_private.man
+++ doc/cmdr_private.man
@@ -103,11 +103,15 @@
[arg_def string word]
The words of the command line to parse and match to parameters.
[list_end][comment arguments]
[comment {- - -- --- ----- -------- -------------}]
+[call [cmd ] [method intercept] [arg cmd]]
[call [cmd ] [method ehandler] [arg cmd]]
+
+[emph Note:] While the form [method ehandler] is still usable, it is
+deprecated and will be removed in a future release.
This method specifies a command prefix to wrap around the parsing of
the command line for the private, and the execution of its action.
[list_begin arguments]
@@ -119,10 +123,22 @@
required by the application using the framework to prevent leakage of
data between multiple commands executed one after the other (i.e. in
an interactive shell run by the framework).
[list_end][comment arguments]
+[comment {- - -- --- ----- -------- -------------}]
+[call [cmd ] [method custom-setup] [arg cmd]]
+
+This method specifies a command prefix which will be run all the
+regular setup of an officer from its specification is done, to perform
+customizations.
+
+[para] The [cmd ] here ignores such calls.
+
+[para] The method exists only to avoid having to special-case code the
+places propagating these commands down the hierarchy.
+
[comment {- - -- --- ----- -------- -------------}]
[call [cmd ] [method find] [arg path]]
This method returns the instance command of the sub-ordinate with the
given [arg path] of names. An error is thrown if such a sub-ordinate
Index: doc/parts/changes1.2.inc
==================================================================
--- doc/parts/changes1.2.inc
+++ doc/parts/changes1.2.inc
@@ -3,125 +3,193 @@
[vset tm [vset tcllib]/tcllib/files/modules]
[list_begin enumerated]
[comment {- - -- --- ----- -------- ------------- ---------------------}]
-[enum] Added many new standard validation types to package
- [package cmdr::validate]:
-
-[list_begin enumerated]
-[enum] Double
-[enum] Percent
-[enum] Posint (positive integers, > 0)
-[enum] Paths and channels
- [list_begin enumerated]
- [enum] Readable file
- [enum] Writable file
- [enum] Read/writable file
- [enum] Readable directory
- [enum] Read/writeable directory
- [enum] readable path
- [enum] Read/writable path
- [enum] Readable path, as channel
- [enum] Writable path, as channel
- [enum] Read/writable path, as channel
- [list_end]
-[enum] Date and time related:
- [list_begin enumerated]
- [enum] iso8601 date/time,
- [enum] year
- [enum] weekday,
- [enum] hour:minute
- [list_end]
-[list_end]
-
-[enum] Added more helper commands for validation failure messages to
- package [package cmdr::validate::common].
-
- [list_begin enumerated]
- [enum] [cmd fail-unknown-thing]
+[enum] Extended the package [package cmdr::validate] with many new
+ standard validation types:
+
+ [list_begin enumerated]
+ [enum] Double
+ [enum] Percent
+ [enum] Posint (positive integers, > 0)
+ [enum] Paths and channels
+ [list_begin enumerated]
+ [enum] Readable file
+ [enum] Writable file
+ [enum] Read/writable file
+ [enum] Readable directory
+ [enum] Read/writeable directory
+ [enum] readable path
+ [enum] Read/writable path
+ [enum] Readable path, as channel
+ [enum] Writable path, as channel
+ [enum] Read/writable path, as channel
+ [list_end]
+ [enum] Date and time related:
+ [list_begin enumerated]
+ [enum] ISO-8601 date/time,
+ [enum] year
+ [enum] weekday,
+ [enum] hour:minute
+ [list_end]
+ [list_end]
+
+[enum] In package [package cmdr::validate], modified the integer
+ validation type to have a proper internal representation:
+ decimal. Input in octal, hex, etc. is now normalized to this.
+
+[enum] Extended package [package cmdr::validate::common] with more
+ helper commands for the generation of validation failure
+ messages
+
+ [list_begin enumerated]
[enum] [cmd fail-unknown-thing-msg]
[enum] [cmd fail-unknown-simple]
[enum] [cmd fail-unknown-simple-msg]
- [enum] [cmd fail-known-thing]
[enum] [cmd fail-known-thing-msg]
[enum] [cmd fail-known-simple]
[enum] [cmd fail-known-simple-msg]
[list_end]
-[enum] Modified integer validation to have a proper internal
- representation: decimal. Octal, hex, etc. input is now
- normalized to this.
-
-[enum] Various new supporting packages:
-[list_begin definitions]
-[def [package cmdr::tty]] Test for terminal.
-[def [package cmdr::color]] Color management, ansi control sequences.
-[def [package cmdr::ask]] User interaction commands.
-[def [package cmdr::pager]] Text display with automatic invokation of
- a pager for tall output.
-[def [package cmdr::history]] Pluggable management of command history.
-[def [package cmdr::table]] Table formatting, simplified interface to
- [uri [vset tcllib]/toc.html Tcllib]'s
- [package struct::matrix] and
- [package report] packages.
-[def [package cmdr::validate::valtype-support]] Even more validation types.
- Wrappers around the validation commands provided by
- [uri [vset tcllib]/toc.html Tcllib]:
- [list_begin enumerated]
- [enum] [uri [vset tm]/valtype/cc_amex.html valtype::creditcard::amex]
- [enum] [uri [vset tm]/valtype/cc_discover.html valtype::creditcard::discover]
- [enum] [uri [vset tm]/valtype/cc_mastercard.html valtype::creditcard::mastercard]
- [enum] [uri [vset tm]/valtype/cc_visa.html valtype::creditcard::visa]
- [enum] [uri [vset tm]/valtype/ean13.html valtype::gs1::ean13]
- [enum] [uri [vset tm]/valtype/iban.html valtype::iban]
- [enum] [uri [vset tm]/valtype/imei.html valtype::imei]
- [enum] [uri [vset tm]/valtype/isbn.html valtype::isbn]
- [enum] [uri [vset tm]/valtype/luhn.html valtype::luhn]
- [enum] [uri [vset tm]/valtype/luhn5.html valtype::luhn5]
- [enum] [uri [vset tm]/valtype/usnpi.html valtype::usnpi]
- [enum] [uri [vset tm]/valtype/verhoeff.html valtype::verhoeff]
- [list_end]
-
-[list_end]
-
-[enum] Added support for per-officer options. The most common use case
- will likely be the declaration of global options in the root
- officer.
-
-[para] Related to this, a new common block [const *config*] is set to
- the active [package config] instance, which will be different
- from the defining instance, , for per-officer options. This
- gives the per-officer options access to the arguments (and
- options) of the current command, instead of only their own
- sibling options.
-
-[enum] Added support for an option [option -extend] for common blocks,
- allowing their extension in a subordinate instead of just
- replacing the entire content.
-
-[enum] Extended boolean options to allow the specification of negative
- aliases, i.e. representing the inverted option. See the DSL
- commands [cmd neg-alias] and [cmd !alias] in
- [term {Cmdr - Parameter Specification Language}].
-
-[enum] Extended the DSL for options in general with the ability to set
- a label for the option argument so that the generated help can
- be more descriptive. The option name is used as fallback for
- options for which no such label was specified.
-
- See DSL command [cmd label] in
- [term {Cmdr - Parameter Specification Language}].
-
-[enum] Extended officers to accept all unique command prefixes of
- their subordinates for dispatch.
-
-[enum] Modified the help system to use the [const short] format for
- interior nodes of the command hierarchy by default.
-
-[enum] Modified the help system to exclude auto-added commands from
- the output generated by format [const by-category].
-
-[enum] ... A suite of bug fixes ... // TODO: list the details.
+[enum] Added various new supporting packages:
+
+ [list_begin definitions]
+ [def [package cmdr::tty]]
+ Test for terminal.
+
+ [def [package cmdr::color]]
+ Color management, ansi control sequences.
+
+ [def [package cmdr::ask]]
+ User interaction commands.
+
+ [def [package cmdr::pager]]
+ Text display with automatic invokation of a pager for tall
+ output.
+
+ [def [package cmdr::history]]
+ Pluggable management of command history.
+
+ [def [package cmdr::table]]
+ Table formatting, a simplified interface to
+ [uri [vset tcllib]/toc.html Tcllib]'s
+ [package struct::matrix] and [package report] packages.
+
+ [def [package cmdr::validate::valtype-support]]
+
+ Even more validation types, now as wrappers around the
+ validation commands provided by
+ [uri [vset tcllib]/toc.html Tcllib]:
+
+ [list_begin enumerated]
+ [enum] [uri [vset tm]/valtype/cc_amex.html valtype::creditcard::amex]
+ [enum] [uri [vset tm]/valtype/cc_discover.html valtype::creditcard::discover]
+ [enum] [uri [vset tm]/valtype/cc_mastercard.html valtype::creditcard::mastercard]
+ [enum] [uri [vset tm]/valtype/cc_visa.html valtype::creditcard::visa]
+ [enum] [uri [vset tm]/valtype/ean13.html valtype::gs1::ean13]
+ [enum] [uri [vset tm]/valtype/iban.html valtype::iban]
+ [enum] [uri [vset tm]/valtype/imei.html valtype::imei]
+ [enum] [uri [vset tm]/valtype/isbn.html valtype::isbn]
+ [enum] [uri [vset tm]/valtype/luhn.html valtype::luhn]
+ [enum] [uri [vset tm]/valtype/luhn5.html valtype::luhn5]
+ [enum] [uri [vset tm]/valtype/usnpi.html valtype::usnpi]
+ [enum] [uri [vset tm]/valtype/verhoeff.html valtype::verhoeff]
+ [list_end]
+ [list_end]
+
+[enum] Extended package [package cmdr::officer] with
+ [list_begin enumerated]
+ [enum] Support for per-officer options. The most common use
+ case will likely be the declaration of global options in
+ the root officer.
+
+ [para] Related to this, a new common block [const *config*] is
+ set to the active [package config] instance, which will
+ be different from the defining instance, for per-officer
+ options. This gives the per-officer options access to
+ the arguments (and options) of the current command,
+ instead of only their own sibling options.
+
+ [enum] Support for an option [option -extend] for common
+ blocks, allowing their extension in a subordinate
+ instead of just replacing the entire content.
+
+ [enum] Support to accept all unique command prefixes of an
+ officer's subordinates for dispatch.
+ [list_end]
+
+[enum] Extended package [package cmdr::parameter] with
+ [list_begin enumerated]
+ [enum] Support for the specification of negative aliases for
+ boolean options, i.e. representing the inverted option.
+
+ [para] See the DSL commands [cmd neg-alias] and [cmd !alias] in
+ [term {Cmdr - Parameter Specification Language}].
+
+ [enum] Support for option labeling, for use in the generated
+ help, to make it more descriptive. Options for which no
+ label is specified will use their name as fallback.
+
+ [para] See DSL command [cmd label] in
+ [term {Cmdr - Parameter Specification Language}].
+ [list_end]
+
+[enum] Help system changes
+ [list_begin enumerated]
+
+ [enum] Modified it to use the [const short] format for interior
+ nodes of the command hierarchy by default.
+
+ [enum] Modified it to exclude auto-added commands from the
+ output generated by format [const by-category].
+
+ [enum] Modified the format [const full] to show the option
+ arguments for those which have such. See also the
+ extension of package [package cmdr::parameter] with
+ support for option labels, this is what is used here.
+
+ [enum] Modified it to declare a standard global option
+ [option --help] (with aliases [option -h] and
+ [option -?]). Using the option invokes the standard help
+ (command) on the current command, if any, or the global
+ help if there is no command.
+
+ [enum] Modified to use a minimum width of 10 characters for
+ descriptions. If the user narrowed the terminal this far
+ then having the text either cut off at the right edge,
+ or wrapped around is not worse then the help trying to
+ wrap the sentence with word boundaries, etc. Also,
+ trying to use negative width threw Tcl errors.
+ [list_end]
+
+[enum] Fixed the handling of common block [const *all*] in package
+ [package cmdr::officer]. While it was ok trapping and ignoring
+ a missing definition of this block, trapping everything which
+ could go wrong was not.
+
+ [para][uri http://core.tcl.tk/akupries/cmdr/info/9159f68bc35d9747 Details].
+
+[enum] Fixed a long-standing bug of package [package cmdr::config] in
+ the forced calculation of parameter values in method
+ [method Force]). Any error in the calculations left an internal
+ flag set, causing future invokations to believe to be in a
+ recursive call and thus do nothing.
+
+ [para] While this had no effect on regular operation, i.e.
+ with the application exiting after each command, in interactive
+ mode this misbehaviour disabled all checks and validations for
+ the command in question, and also retained old parameter
+ values.
+
+ [para][uri http://core.tcl.tk/akupries/cmdr/info/f74095b252d4c9df Details]
+
+[enum] Modified the formatting of [package cmdr::config] state when
+ interactively entering it for a private. Parameter names now
+ are shown as declared, and an additional flag character
+ indicates if it is inherited from above, or not.
+
+[enum] General fixes to testsuite, code comments, bogus variable
+ names, typos in error messages, etc.
[comment {- - -- --- ----- -------- ------------- ---------------------}]
[list_end]
Index: doc/parts/dev_dsl_officer.inc
==================================================================
--- doc/parts/dev_dsl_officer.inc
+++ doc/parts/dev_dsl_officer.inc
@@ -12,13 +12,14 @@
[para] The DSL commands map to instance methods as shown below:
[list_begin definitions]
[def [cmd alias]] [method Alias]
[def [cmd common]] [package cmdr::actor] [method set]
+[def [cmd custom-setup]] [method custom-setup]
[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 ehandler]] See [cmd intercept]. [emph Deprecated].
+[def [cmd intercept]] [method intercept]
[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
@@ -104,11 +104,15 @@
[call [cmd description] [arg text]]
This command declares the help text of the [term officer].
[comment {- - -- --- ----- -------- -------------}]
+[call [cmd intercept] [arg cmdprefix]]
[call [cmd ehandler] [arg cmdprefix]]
+
+[emph Note:] While the form [cmd ehandler] is still usable, it is
+deprecated and will be removed in a future release.
This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates).
@@ -138,19 +142,22 @@
wanted.
[list_end]
[comment {- - -- --- ----- -------- -------------}]
-[call [cmd shandler] [arg cmdprefix]]
+[call [cmd custom-setup] [arg cmdprefix]]
This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates).
-[para] At runtime the framework will call the specified command prefix
-with a single argument, the command of the actor we wish to
-initialize.
+[para] When called multiple times, the specified commands
+accumulate. This makes it easy to specify several indepedent
+customizations.
+
+[para] At runtime the framework will invoke all the specified commands
+with a single argument, the command of the actor to initialize.
The command prefix is then allowed to modify that actor as it sees
fit. The common use case will be the extension of the object with
additional subordinates.
Index: doc/parts/dsl_para_support.inc
==================================================================
--- doc/parts/dsl_para_support.inc
+++ doc/parts/dsl_para_support.inc
@@ -23,11 +23,11 @@
specified [arg value]. A simple method of communication between
parameters of a command.
[para] Useful for use with [cmd when-set] and/or [cmd when-complete]
-[call [cmd touch] [arg name] [arg value]]
+[call [cmd touch?] [arg name] [arg value]]
The returned callback sets the [arg name]d sibling parameter to the
specified [arg value], if and only if that parameter exists. A simple
method of communication between parameters of a command, where the
sibling may not exists, depending on usage context.
Index: embedded/man/files/cmdr_changes.n
==================================================================
--- embedded/man/files/cmdr_changes.n
+++ embedded/man/files/cmdr_changes.n
@@ -283,12 +283,12 @@
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:
+Extended the package \fBcmdr::validate\fR with many new
+standard validation types:
.RS
.IP [1]
Double
.IP [2]
Percent
@@ -320,46 +320,43 @@
.RE
.IP [5]
Date and time related:
.RS
.IP [1]
-iso8601 date/time,
+ISO-8601 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\&.
+In package \fBcmdr::validate\fR, modified the integer
+validation type to have a proper internal representation:
+decimal\&. Input in octal, hex, etc\&. is now normalized to this\&.
+.IP [3]
+Extended package \fBcmdr::validate::common\fR with more
+helper commands for the generation of validation failure
+messages
.RS
.IP [1]
-\fBfail-unknown-thing\fR
-.IP [2]
\fBfail-unknown-thing-msg\fR
-.IP [3]
+.IP [2]
\fBfail-unknown-simple\fR
-.IP [4]
+.IP [3]
\fBfail-unknown-simple-msg\fR
-.IP [5]
-\fBfail-known-thing\fR
-.IP [6]
+.IP [4]
\fBfail-known-thing-msg\fR
-.IP [7]
+.IP [5]
\fBfail-known-simple\fR
-.IP [8]
+.IP [6]
\fBfail-known-simple-msg\fR
.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:
+Added various new supporting packages:
.RS
.TP
\fBcmdr::tty\fR
Test for terminal\&.
.TP
@@ -368,25 +365,24 @@
.TP
\fBcmdr::ask\fR
User interaction commands\&.
.TP
\fBcmdr::pager\fR
-Text display with automatic invokation of
-a pager for tall output\&.
+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
+Table formatting, a simplified interface to
\fITcllib\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/toc\&.html]'s
-\fBstruct::matrix\fR and
-\fBreport\fR packages\&.
+\fBstruct::matrix\fR and \fBreport\fR packages\&.
.TP
\fBcmdr::validate::valtype-support\fR
-Even more validation types\&.
-Wrappers around the validation commands provided by
+Even more validation types, now as wrappers around the
+validation commands provided by
\fITcllib\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/toc\&.html]:
.RS
.IP [1]
\fIvaltype::creditcard::amex\fR [http://core\&.tcl\&.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/valtype/cc_amex\&.html]
.IP [2]
@@ -412,47 +408,105 @@
.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\&.
+Extended package \fBcmdr::officer\fR with
+.RS
+.IP [1]
+Support for per-officer options\&. The most common use
+case will likely be the declaration of global options in
+the root officer\&.
.sp
-Related to this, a new common block \fB*config*\fR is set to
-the active \fBconfig\fR instance, which will be different
-from the defining instance, , for per-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\&.
+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 [2]
+Support for an option \fB-extend\fR for common
+blocks, allowing their extension in a subordinate
+instead of just replacing the entire content\&.
+.IP [3]
+Support to accept all unique command prefixes of an
+officer's subordinates for dispatch\&.
+.RE
.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
+Extended package \fBcmdr::parameter\fR with
+.RS
+.IP [1]
+Support for the specification of negative aliases for
+boolean options, i\&.e\&. representing the inverted option\&.
+.sp
+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\&.
+.IP [2]
+Support for option labeling, for use in the generated
+help, to make it more descriptive\&. Options for which no
+label is specified will use their name as fallback\&.
+.sp
See DSL command \fBlabel\fR in
\fICmdr - Parameter Specification Language\fR\&.
+.RE
+.IP [7]
+Help system changes
+.RS
+.IP [1]
+Modified it to use the \fBshort\fR format for interior
+nodes of the command hierarchy by default\&.
+.IP [2]
+Modified it to exclude auto-added commands from the
+output generated by format \fBby-category\fR\&.
+.IP [3]
+Modified the format \fBfull\fR to show the option
+arguments for those which have such\&. See also the
+extension of package \fBcmdr::parameter\fR with
+support for option labels, this is what is used here\&.
+.IP [4]
+Modified it to declare a standard global option
+\fB--help\fR (with aliases \fB-h\fR and
+\fB-?\fR)\&. Using the option invokes the standard help
+(command) on the current command, if any, or the global
+help if there is no command\&.
+.IP [5]
+Modified to use a minimum width of 10 characters for
+descriptions\&. If the user narrowed the terminal this far
+then having the text either cut off at the right edge,
+or wrapped around is not worse then the help trying to
+wrap the sentence with word boundaries, etc\&. Also,
+trying to use negative width threw Tcl errors\&.
+.RE
+.IP [8]
+Fixed the handling of common block \fB*all*\fR in package
+\fBcmdr::officer\fR\&. While it was ok trapping and ignoring
+a missing definition of this block, trapping everything which
+could go wrong was not\&.
+.sp
+\fIDetails\fR [http://core\&.tcl\&.tk/akupries/cmdr/info/9159f68bc35d9747]\&.
.IP [9]
-Extended officers to accept all unique command prefixes of
-their subordinates for dispatch\&.
+Fixed a long-standing bug of package \fBcmdr::config\fR in
+the forced calculation of parameter values in method
+\fBForce\fR)\&. Any error in the calculations left an internal
+flag set, causing future invokations to believe to be in a
+recursive call and thus do nothing\&.
+.sp
+While this had no effect on regular operation, i\&.e\&.
+with the application exiting after each command, in interactive
+mode this misbehaviour disabled all checks and validations for
+the command in question, and also retained old parameter
+values\&.
+.sp
+\fIDetails\fR [http://core\&.tcl\&.tk/akupries/cmdr/info/f74095b252d4c9df]
.IP [10]
-Modified the help system to use the \fBshort\fR format for
-interior nodes of the command hierarchy by default\&.
+Modified the formatting of \fBcmdr::config\fR state when
+interactively entering it for a private\&. Parameter names now
+are shown as declared, and an additional flag character
+indicates if it is inherited from above, or not\&.
.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\&.
+General fixes to testsuite, code comments, bogus variable
+names, typos in error messages, etc\&.
.PP
.SS "CHANGES FOR VERSION 1\&.1"
.IP [1]
Fixed broken requirement references in the meta data of packages
\fBcmdr::help::json\fR and \fBcmdr::help::sql\fR\&.
Index: embedded/man/files/cmdr_color.n
==================================================================
--- embedded/man/files/cmdr_color.n
+++ embedded/man/files/cmdr_color.n
@@ -1,7 +1,7 @@
'\"
-'\" Generated from file 'cmdr_color\&.man' by tcllib/doctools with format 'nroff'
+'\" Generated from file 'cmdr_color\&.man~' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2013-2016 Andreas Kupries
'\" Copyright (c) 2013-2016 Documentation, Andreas Kupries
'\"
.TH "cmdr::color" n 1\&.0\&.2 doc "Cmdr, a framework for command line parsing and dispatch"
.\" The -*- nroff -*- definitions below are for supplemental macros used
Index: embedded/man/files/cmdr_dev_dsl.n
==================================================================
--- embedded/man/files/cmdr_dev_dsl.n
+++ embedded/man/files/cmdr_dev_dsl.n
@@ -308,21 +308,24 @@
\fBAlias\fR
.TP
\fBcommon\fR
\fBcmdr::actor\fR \fBset\fR
.TP
+\fBcustom-setup\fR
+\fBcustom-setup\fR
+.TP
\fBdefault\fR
\fBDefault\fR
.TP
\fBdescription\fR
\fBcmdr::actor\fR \fBdescription:\fR
.TP
\fBehandler\fR
-\fBehandler\fR
+See \fBintercept\fR\&. \fIDeprecated\fR\&.
.TP
-\fBshandler\fR
-\fBshandler\fR
+\fBintercept\fR
+\fBintercept\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
@@ -283,13 +283,15 @@
.sp
\fBdefault\fR
.sp
\fBdescription\fR \fItext\fR
.sp
+\fBintercept\fR \fIcmdprefix\fR
+.sp
\fBehandler\fR \fIcmdprefix\fR
.sp
-\fBshandler\fR \fIcmdprefix\fR
+\fBcustom-setup\fR \fIcmdprefix\fR
.sp
\fBofficer\fR \fIname\fR \fIscript\fR
.sp
\fBprivate\fR \fIname\fR \fIscript\fR \fIcmdprefix\fR
.sp
@@ -411,11 +413,15 @@
thrown instead\&.
.TP
\fBdescription\fR \fItext\fR
This command declares the help text of the \fIofficer\fR\&.
.TP
+\fBintercept\fR \fIcmdprefix\fR
+.TP
\fBehandler\fR \fIcmdprefix\fR
+\fINote:\fR While the form \fBehandler\fR is still usable, it is
+deprecated and will be removed in a future release\&.
This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates)\&.
.sp
At runtime the framework will call the specified command prefix
@@ -439,18 +445,21 @@
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
+\fBcustom-setup\fR \fIcmdprefix\fR
This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates)\&.
.sp
-At runtime the framework will call the specified command prefix
-with a single argument, the command of the actor we wish to
-initialize\&.
+When called multiple times, the specified commands
+accumulate\&. This makes it easy to specify several indepedent
+customizations\&.
+.sp
+At runtime the framework will invoke all the specified commands
+with a single argument, the command of the actor to initialize\&.
The command prefix is then allowed to modify that actor as it sees
fit\&. The common use case will be the extension of the object with
additional subordinates\&.
An example of this is the package \fBcmdr::history\fR which
provides a command \fBcmdr::history::attach\fR to add the history
Index: embedded/man/files/cmdr_dsl_parameter.n
==================================================================
--- embedded/man/files/cmdr_dsl_parameter.n
+++ embedded/man/files/cmdr_dsl_parameter.n
@@ -313,11 +313,11 @@
.sp
\fBstop!\fR
.sp
\fBtouch\fR \fIname\fR \fIvalue\fR
.sp
-\fBtouch\fR \fIname\fR \fIvalue\fR
+\fBtouch?\fR \fIname\fR \fIvalue\fR
.sp
\fBdisallow\fR \fIname\fR
.sp
.BE
.SH DESCRIPTION
@@ -757,11 +757,11 @@
specified \fIvalue\fR\&. A simple method of communication between
parameters of a command\&.
.sp
Useful for use with \fBwhen-set\fR and/or \fBwhen-complete\fR
.TP
-\fBtouch\fR \fIname\fR \fIvalue\fR
+\fBtouch?\fR \fIname\fR \fIvalue\fR
The returned callback sets the \fIname\fRd sibling parameter to the
specified \fIvalue\fR, if and only if that parameter exists\&. A simple
method of communication between parameters of a command, where the
sibling may not exists, depending on usage context\&.
.sp
Index: embedded/man/files/cmdr_history.n
==================================================================
--- embedded/man/files/cmdr_history.n
+++ embedded/man/files/cmdr_history.n
@@ -318,11 +318,11 @@
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
+method \fBcustom-setup\fR of officers\&. See \fBcmdr::officer\fR, and
the \fBExample\fR for more information\&.
.TP
\fB::cmdr::history\fR \fBsave-to\fR \fIpath\fR
When invoked this command sets the package-wide history save file used
by the commands to the \fIpath\fR\&.
@@ -344,11 +344,11 @@
cmdr history initial-limit 20
cmdr history save-to ~/\&.fx_history
cmdr create fx::fx [file tail $::argv0] {
- shandler ::cmdr::history::attach
+ custom-setup ::cmdr::history::attach
[\&.\&.\&.]
}
.CE
Index: embedded/man/files/cmdr_officer.n
==================================================================
--- embedded/man/files/cmdr_officer.n
+++ embedded/man/files/cmdr_officer.n
@@ -293,11 +293,15 @@
.sp
\fB\fR \fBdispatch\fR \fIcmd\fR
.sp
\fB\fR \fBdo\fR ?\fIword\fR\&.\&.\&.?
.sp
+\fB\fR \fBintercept\fR \fIcmd\fR
+.sp
\fB\fR \fBehandler\fR \fIcmd\fR
+.sp
+\fB\fR \fBcustom-setup\fR \fIcmd\fR
.sp
\fB\fR \fBexit\fR
.sp
\fB\fR \fBextend\fR \fIpath\fR \fIarguments\fR \fIaction\fR
.sp
@@ -439,11 +443,15 @@
.TP
string \fIword\fR
The words of the command line to parse and match to parameters\&.
.RE
.TP
+\fB\fR \fBintercept\fR \fIcmd\fR
+.TP
\fB\fR \fBehandler\fR \fIcmd\fR
+\fINote:\fR While the form \fBehandler\fR is still usable, it is
+deprecated and will be removed in a future release\&.
This method specifies a command prefix to wrap around the parsing of
the command line for the officer, and the execution of its action\&.
.RS
.TP
cmd-prefix \fIcmd\fR
@@ -453,10 +461,32 @@
prefix then has the responsbility to perform any custom cleanup action
required by the application using the framework to prevent leakage of
data between multiple commands executed one after the other (i\&.e\&. in
an interactive shell run by the framework)\&.
.RE
+.TP
+\fB\fR \fBcustom-setup\fR \fIcmd\fR
+This method specifies a command prefix which will be run all the
+regular setup of the officer from its specification is done, to
+perform customizations\&.
+.sp
+An example of this can be seen in the package
+\fBcmdr::history\fR\&. It provides a command
+\fBcmdr::history::attach\fR to add the history management commands to
+the actor in question, suitable as argument to this method\&.
+.sp
+When called multiple times, the specified commands
+accumulate\&. This makes it easy to specify several indepedent
+customizations\&.
+.RS
+.TP
+cmd-prefix \fIcmd\fR
+A command prefix taking a single argument, the instance command of an
+\fBcmd::actor\fR\&. The command prefix has full access to this actor
+and can modify it as it sees fit\&. The common use case will be the
+extension of the actor with additional subordinates\&.
+.RE
.TP
\fB\fR \fBexit\fR
This hook-method for the main shell returns a boolean value indicating
whether the main shell was stopped and has to exit (\fBtrue\fR), or
not (\fBfalse\fR)\&.
Index: embedded/man/files/cmdr_private.n
==================================================================
--- embedded/man/files/cmdr_private.n
+++ embedded/man/files/cmdr_private.n
@@ -283,11 +283,15 @@
.sp
\fB\fR \fBcomplete-words\fR \fIparse\fR
.sp
\fB\fR \fBdo\fR ?\fIword\fR\&.\&.\&.?
.sp
+\fB\fR \fBintercept\fR \fIcmd\fR
+.sp
\fB\fR \fBehandler\fR \fIcmd\fR
+.sp
+\fB\fR \fBcustom-setup\fR \fIcmd\fR
.sp
\fB\fR \fBfind\fR \fIpath\fR
.sp
\fB\fR \fBhelp\fR ?\fIprefix\fR?
.sp
@@ -378,11 +382,15 @@
.TP
string \fIword\fR
The words of the command line to parse and match to parameters\&.
.RE
.TP
+\fB\fR \fBintercept\fR \fIcmd\fR
+.TP
\fB\fR \fBehandler\fR \fIcmd\fR
+\fINote:\fR While the form \fBehandler\fR is still usable, it is
+deprecated and will be removed in a future release\&.
This method specifies a command prefix to wrap around the parsing of
the command line for the private, and the execution of its action\&.
.RS
.TP
cmd-prefix \fIcmd\fR
@@ -393,10 +401,20 @@
required by the application using the framework to prevent leakage of
data between multiple commands executed one after the other (i\&.e\&. in
an interactive shell run by the framework)\&.
.RE
.TP
+\fB\fR \fBcustom-setup\fR \fIcmd\fR
+This method specifies a command prefix which will be run all the
+regular setup of an officer from its specification is done, to perform
+customizations\&.
+.sp
+The \fB\fR here ignores such calls\&.
+.sp
+The method exists only to avoid having to special-case code the
+places propagating these commands down the hierarchy\&.
+.TP
\fB\fR \fBfind\fR \fIpath\fR
This method returns the instance command of the sub-ordinate with the
given \fIpath\fR of names\&. An error is thrown if such a sub-ordinate
does not exist, i\&.e\&. whenever \fIpath\fR is not empty, as a private
has no sub-ordinates, ever\&.
ADDED embedded/man/files/cmdr_table.n
Index: embedded/man/files/cmdr_table.n
==================================================================
--- /dev/null
+++ embedded/man/files/cmdr_table.n
@@ -0,0 +1,483 @@
+'\"
+'\" Generated from file 'cmdr_table\&.man' by tcllib/doctools with format 'nroff'
+'\" Copyright (c) 2013-2016 Andreas Kupries
+'\" Copyright (c) 2013-2016 Documentation, Andreas Kupries
+'\"
+.TH "cmdr::table" n 0\&.1 doc "Cmdr, a framework for command line parsing and dispatch"
+.\" The -*- nroff -*- definitions below are for supplemental macros used
+.\" in Tcl/Tk manual entries.
+.\"
+.\" .AP type name in/out ?indent?
+.\" Start paragraph describing an argument to a library procedure.
+.\" type is type of argument (int, etc.), in/out is either "in", "out",
+.\" or "in/out" to describe whether procedure reads or modifies arg,
+.\" and indent is equivalent to second arg of .IP (shouldn't ever be
+.\" needed; use .AS below instead)
+.\"
+.\" .AS ?type? ?name?
+.\" Give maximum sizes of arguments for setting tab stops. Type and
+.\" name are examples of largest possible arguments that will be passed
+.\" to .AP later. If args are omitted, default tab stops are used.
+.\"
+.\" .BS
+.\" Start box enclosure. From here until next .BE, everything will be
+.\" enclosed in one large box.
+.\"
+.\" .BE
+.\" End of box enclosure.
+.\"
+.\" .CS
+.\" Begin code excerpt.
+.\"
+.\" .CE
+.\" End code excerpt.
+.\"
+.\" .VS ?version? ?br?
+.\" Begin vertical sidebar, for use in marking newly-changed parts
+.\" of man pages. The first argument is ignored and used for recording
+.\" the version when the .VS was added, so that the sidebars can be
+.\" found and removed when they reach a certain age. If another argument
+.\" is present, then a line break is forced before starting the sidebar.
+.\"
+.\" .VE
+.\" End of vertical sidebar.
+.\"
+.\" .DS
+.\" Begin an indented unfilled display.
+.\"
+.\" .DE
+.\" End of indented unfilled display.
+.\"
+.\" .SO ?manpage?
+.\" Start of list of standard options for a Tk widget. The manpage
+.\" argument defines where to look up the standard options; if
+.\" omitted, defaults to "options". The options follow on successive
+.\" lines, in three columns separated by tabs.
+.\"
+.\" .SE
+.\" End of list of standard options for a Tk widget.
+.\"
+.\" .OP cmdName dbName dbClass
+.\" Start of description of a specific option. cmdName gives the
+.\" option's name as specified in the class command, dbName gives
+.\" the option's name in the option database, and dbClass gives
+.\" the option's class in the option database.
+.\"
+.\" .UL arg1 arg2
+.\" Print arg1 underlined, then print arg2 normally.
+.\"
+.\" .QW arg1 ?arg2?
+.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
+.\"
+.\" .PQ arg1 ?arg2?
+.\" Print an open parenthesis, arg1 in quotes, then arg2 normally
+.\" (for trailing punctuation) and then a closing parenthesis.
+.\"
+.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
+.if t .wh -1.3i ^B
+.nr ^l \n(.l
+.ad b
+.\" # Start an argument description
+.de AP
+.ie !"\\$4"" .TP \\$4
+.el \{\
+. ie !"\\$2"" .TP \\n()Cu
+. el .TP 15
+.\}
+.ta \\n()Au \\n()Bu
+.ie !"\\$3"" \{\
+\&\\$1 \\fI\\$2\\fP (\\$3)
+.\".b
+.\}
+.el \{\
+.br
+.ie !"\\$2"" \{\
+\&\\$1 \\fI\\$2\\fP
+.\}
+.el \{\
+\&\\fI\\$1\\fP
+.\}
+.\}
+..
+.\" # define tabbing values for .AP
+.de AS
+.nr )A 10n
+.if !"\\$1"" .nr )A \\w'\\$1'u+3n
+.nr )B \\n()Au+15n
+.\"
+.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
+.nr )C \\n()Bu+\\w'(in/out)'u+2n
+..
+.AS Tcl_Interp Tcl_CreateInterp in/out
+.\" # BS - start boxed text
+.\" # ^y = starting y location
+.\" # ^b = 1
+.de BS
+.br
+.mk ^y
+.nr ^b 1u
+.if n .nf
+.if n .ti 0
+.if n \l'\\n(.lu\(ul'
+.if n .fi
+..
+.\" # BE - end boxed text (draw box now)
+.de BE
+.nf
+.ti 0
+.mk ^t
+.ie n \l'\\n(^lu\(ul'
+.el \{\
+.\" Draw four-sided box normally, but don't draw top of
+.\" box if the box started on an earlier page.
+.ie !\\n(^b-1 \{\
+\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
+.\}
+.el \}\
+\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
+.\}
+.\}
+.fi
+.br
+.nr ^b 0
+..
+.\" # VS - start vertical sidebar
+.\" # ^Y = starting y location
+.\" # ^v = 1 (for troff; for nroff this doesn't matter)
+.de VS
+.if !"\\$2"" .br
+.mk ^Y
+.ie n 'mc \s12\(br\s0
+.el .nr ^v 1u
+..
+.\" # VE - end of vertical sidebar
+.de VE
+.ie n 'mc
+.el \{\
+.ev 2
+.nf
+.ti 0
+.mk ^t
+\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
+.sp -1
+.fi
+.ev
+.\}
+.nr ^v 0
+..
+.\" # Special macro to handle page bottom: finish off current
+.\" # box/sidebar if in box/sidebar mode, then invoked standard
+.\" # page bottom macro.
+.de ^B
+.ev 2
+'ti 0
+'nf
+.mk ^t
+.if \\n(^b \{\
+.\" Draw three-sided box if this is the box's first page,
+.\" draw two sides but no top otherwise.
+.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
+.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
+.\}
+.if \\n(^v \{\
+.nr ^x \\n(^tu+1v-\\n(^Yu
+\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
+.\}
+.bp
+'fi
+.ev
+.if \\n(^b \{\
+.mk ^y
+.nr ^b 2
+.\}
+.if \\n(^v \{\
+.mk ^Y
+.\}
+..
+.\" # DS - begin display
+.de DS
+.RS
+.nf
+.sp
+..
+.\" # DE - end display
+.de DE
+.fi
+.RE
+.sp
+..
+.\" # SO - start of list of standard options
+.de SO
+'ie '\\$1'' .ds So \\fBoptions\\fR
+'el .ds So \\fB\\$1\\fR
+.SH "STANDARD OPTIONS"
+.LP
+.nf
+.ta 5.5c 11c
+.ft B
+..
+.\" # SE - end of list of standard options
+.de SE
+.fi
+.ft R
+.LP
+See the \\*(So manual entry for details on the standard options.
+..
+.\" # OP - start of full description for a single option
+.de OP
+.LP
+.nf
+.ta 4c
+Command-Line Name: \\fB\\$1\\fR
+Database Name: \\fB\\$2\\fR
+Database Class: \\fB\\$3\\fR
+.fi
+.IP
+..
+.\" # CS - begin code excerpt
+.de CS
+.RS
+.nf
+.ta .25i .5i .75i 1i
+..
+.\" # CE - end code excerpt
+.de CE
+.fi
+.RE
+..
+.\" # UL - underline word
+.de UL
+\\$1\l'|0\(ul'\\$2
+..
+.\" # QW - apply quotation marks to word
+.de QW
+.ie '\\*(lq'"' ``\\$1''\\$2
+.\"" fix emacs highlighting
+.el \\*(lq\\$1\\*(rq\\$2
+..
+.\" # PQ - apply parens and quotation marks to word
+.de PQ
+.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
+.\"" fix emacs highlighting
+.el (\\*(lq\\$1\\*(rq\\$2)\\$3
+..
+.\" # QR - quoted range
+.de QR
+.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
+.\"" fix emacs highlighting
+.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
+..
+.\" # MT - "empty" string
+.de MT
+.QW ""
+..
+.BS
+.SH NAME
+cmdr::table \- Cmdr - Simple Table creation
+.SH SYNOPSIS
+package require \fBcmdr::util \fR
+.sp
+\fB::cmdr::table\fR \fBgeneral\fR \fIvar\fR \fIheaders\fR \fIscript\fR
+.sp
+\fB::cmdr::table\fR \fBdict\fR \fIvar\fR \fIscript\fR
+.sp
+\fB::cmdr::table\fR \fBborders\fR ?\fIenable\fR?
+.sp
+\fB::cmdr::table\fR \fBshow\fR ?\fIcmd\fR\&.\&.\&.?
+.sp
+\fBt\fR \fBborders\fR ?\fIenable\fR?
+.sp
+\fBt\fR \fBheaders\fR ?\fIenable\fR?
+.sp
+\fBt\fR \fBstyle\fR ?\fIstyle\fR?
+.sp
+\fBt\fR \fBadd\fR \fIword\fR\&.\&.\&.
+.sp
+\fBt\fR \fB+\fR \fIword\fR\&.\&.\&.
+.sp
+\fBt\fR \fB+=\fR \fIword\fR\&.\&.\&.
+.sp
+\fBt\fR \fB<<\fR \fIword\fR\&.\&.\&.
+.sp
+\fBt\fR \fB<=\fR \fIword\fR\&.\&.\&.
+.sp
+\fBt\fR \fBshow*\fR ?\fIcmd\fR?
+.sp
+\fBt\fR \fBshow\fR ?\fIcmd\fR?
+.sp
+.BE
+.SH DESCRIPTION
+.PP
+Welcome to the Cmdr project, written by Andreas Kupries\&.
+.PP
+For availability please read \fICmdr - How To Get The Sources\fR\&.
+.PP
+This package provides convenience commands for the easy creation of
+simple tables\&.
+.SH API
+.TP
+\fB::cmdr::table\fR \fBgeneral\fR \fIvar\fR \fIheaders\fR \fIscript\fR
+This command creates a new table with the words found in the list of
+\fIheaders\fR as the top row\&.
+The \fIscript\fR is run in the calling context to configure and
+populate the table\&.
+The table's object command is stored in the named \fIvar\fR for access
+by the \fIscript\fR\&.
+The result of the command is the table's object command\&.
+.RS
+.TP
+varname \fIvar\fR
+The name of the variable in the calling scope the new table's object
+command will be stored into\&.
+.TP
+list \fIheaders\fR
+The list of words to user as column headers\&.
+.TP
+string \fIscript\fR
+The tcl script to be run to configure and populate the table\&.
+.RE
+.TP
+\fB::cmdr::table\fR \fBdict\fR \fIvar\fR \fIscript\fR
+This command creates a new table intended for the display of a Tcl
+dictionary\&.
+It will have two columns titled \fBKey\fR and \fBValue\fR\&.
+The \fIscript\fR is run in the calling context to configure and
+populate the table\&.
+The table's object command is stored in the named \fIvar\fR for access
+by the \fIscript\fR\&.
+The result of the command is the table's object command\&.
+.RS
+.TP
+varname \fIvar\fR
+The name of the variable in the calling scope the new table's object
+command will be stored into\&.
+.TP
+string \fIscript\fR
+The tcl script to be run to configure and populate the table\&.
+.RE
+.TP
+\fB::cmdr::table\fR \fBborders\fR ?\fIenable\fR?
+This command configures the global \fIborder\fR setting, which
+indicates the (non)use of borders by the tables of this package\&. Note
+that changes to this setting influence only the tables created after
+the change\&. Existing tables are not modified\&.
+.sp
+The result of the command is the new state of the setting\&.
+.sp
+If the command is called without an argument it simply returns the
+current state of the setting, without making changes\&.
+.sp
+The default value for the setting is \fByes\fR\&.
+Individual tables can override the global settings via their
+\fBborders\fR method, see \fBTable API\fR\&.
+.RS
+.TP
+boolean \fIenable\fR
+The new value of the setting\&. Optional\&.
+.RE
+.TP
+\fB::cmdr::table\fR \fBshow\fR ?\fIcmd\fR\&.\&.\&.?
+This command configures the global \fIshow\fR setting, which is the
+command prefix to use to print a table, if the table is not given a
+specific command to use\&. Note that changes to this setting influence
+only the tables created after the change\&. Existing tables are not
+modified\&.
+.sp
+The result of the command is the new state of the setting
+.sp
+If the command is called without any arguments it simply
+returns the current state of the setting, without making changes\&.
+.sp
+The default value for the setting is \fBputs\fR\&.
+.RS
+.TP
+word \fIcmd\fR
+The command prefix to use for printing a table, as varargs\&.
+The prefix will be invoked with a single argument, the string
+representation of the table\&.
+.RE
+.PP
+.SH "TABLE API"
+This section lists the methods available for configuration and
+population of the tables created by this package\&.
+.TP
+\fBt\fR \fBborders\fR ?\fIenable\fR?
+This is the table-level \fIborders\fR setting\&. On creation a table
+inherits the global setting (See \fB::cmdr::table borders\fR)\&. If
+that is not to suit then this method can be used to override it\&.
+.sp
+The result of the method is the new state of the setting\&. When
+called without argument no change is made and the result is the
+current state of the setting\&.
+.TP
+\fBt\fR \fBheaders\fR ?\fIenable\fR?
+This method controls the visibility of the header row\&. By default
+general tables have the header row visisble, while for dict tables the
+header is suppressed\&. This method allows the user to override these
+defaults\&.
+.sp
+The result of the method is the new state of the setting\&. When
+called without argument no change is made and the result is the
+current state of the setting\&.
+.TP
+\fBt\fR \fBstyle\fR ?\fIstyle\fR?
+This method allows the user to force the use of a completely custom
+style\&.
+Please see the documentation for the Tcllib package \fBreport\fR
+on how to define table styles\&.
+.sp
+The package defines four styles of its own, all using the
+common prefix \fBcmdr/table/\fR in their names\&.
+When no custom style is set the table chooses between these based on
+its \fIborders\fR and \fIheaders\fR settings\&.
+.sp
+The result of the method is the new state of the setting\&. When
+called without argument then no change is made and the result is the
+current state of the setting\&.
+.sp
+To revert from a custom style to the automatic choice invoke
+this method with the empty string as the name of the style\&.
+.TP
+\fBt\fR \fBadd\fR \fIword\fR\&.\&.\&.
+.TP
+\fBt\fR \fB+\fR \fIword\fR\&.\&.\&.
+.TP
+\fBt\fR \fB+=\fR \fIword\fR\&.\&.\&.
+.TP
+\fBt\fR \fB<<\fR \fIword\fR\&.\&.\&.
+.TP
+\fBt\fR \fB<=\fR \fIword\fR\&.\&.\&.
+This method adds a new row to the table, containing the given words\&.
+If less words than headers are specified the row is padded with empty columns\&.
+If too many words are specified the superfluous words are ignored\&.
+.sp
+The result of the method is the empty string\&.
+.TP
+\fBt\fR \fBshow*\fR ?\fIcmd\fR?
+This method formats the table into a string and then invokes the
+command prefix \fIcmd\fR to print that string\&. The command prefix is
+run at the global namespace and level\&. If the \fIcmd\fR is not
+specified the global \fIshow\fR setting is used instead\&.
+.sp
+The result of the method is the empty string\&.
+.TP
+\fBt\fR \fBshow\fR ?\fIcmd\fR?
+This is a variant of method \fBshow*\fR above which not only prints
+the table as above, but also destroys it\&.
+.PP
+.SH "BUGS, IDEAS, FEEDBACK"
+Both the package(s) and this documentation will undoubtedly contain
+bugs and other problems\&.
+Please report such at
+\fICmdr Tickets\fR [https:/core\&.tcl\&.tk/akupries/cmdr]\&.
+.PP
+Please also report any ideas you may have for enhancements of
+either package(s) and/or documentation\&.
+.SH KEYWORDS
+arguments, command hierarchy, command line completion, command line handling, command tree, editing command line, help for command line, hierarchy of commands, interactive command shell, optional arguments, options, parameters, processing command line, tree of commands
+.SH COPYRIGHT
+.nf
+Copyright (c) 2013-2016 Andreas Kupries
+Copyright (c) 2013-2016 Documentation, Andreas Kupries
+
+.fi
Index: embedded/man/index.n
==================================================================
--- embedded/man/index.n
+++ embedded/man/index.n
@@ -350,10 +350,13 @@
\fBfiles/cmdr_parameter\&.n\fR
cmdr::parameter
.TP
\fBfiles/cmdr_private\&.n\fR
cmdr::private
+.TP
+\fBfiles/cmdr_table\&.n\fR
+cmdr::table
.TP
\fBfiles/cmdr_tty\&.n\fR
cmdr::tty
.TP
\fBfiles/cmdr_util\&.n\fR
@@ -506,10 +509,13 @@
\fBfiles/cmdr_parameter\&.n\fR
cmdr::parameter
.TP
\fBfiles/cmdr_private\&.n\fR
cmdr::private
+.TP
+\fBfiles/cmdr_table\&.n\fR
+cmdr::table
.TP
\fBfiles/cmdr_tty\&.n\fR
cmdr::tty
.TP
\fBfiles/cmdr_util\&.n\fR
@@ -662,10 +668,13 @@
\fBfiles/cmdr_parameter\&.n\fR
cmdr::parameter
.TP
\fBfiles/cmdr_private\&.n\fR
cmdr::private
+.TP
+\fBfiles/cmdr_table\&.n\fR
+cmdr::table
.TP
\fBfiles/cmdr_tty\&.n\fR
cmdr::tty
.TP
\fBfiles/cmdr_util\&.n\fR
@@ -818,10 +827,13 @@
\fBfiles/cmdr_parameter\&.n\fR
cmdr::parameter
.TP
\fBfiles/cmdr_private\&.n\fR
cmdr::private
+.TP
+\fBfiles/cmdr_table\&.n\fR
+cmdr::table
.TP
\fBfiles/cmdr_tty\&.n\fR
cmdr::tty
.TP
\fBfiles/cmdr_util\&.n\fR
@@ -974,10 +986,13 @@
\fBfiles/cmdr_parameter\&.n\fR
cmdr::parameter
.TP
\fBfiles/cmdr_private\&.n\fR
cmdr::private
+.TP
+\fBfiles/cmdr_table\&.n\fR
+cmdr::table
.TP
\fBfiles/cmdr_tty\&.n\fR
cmdr::tty
.TP
\fBfiles/cmdr_util\&.n\fR
@@ -1130,10 +1145,13 @@
\fBfiles/cmdr_parameter\&.n\fR
cmdr::parameter
.TP
\fBfiles/cmdr_private\&.n\fR
cmdr::private
+.TP
+\fBfiles/cmdr_table\&.n\fR
+cmdr::table
.TP
\fBfiles/cmdr_tty\&.n\fR
cmdr::tty
.TP
\fBfiles/cmdr_util\&.n\fR
@@ -1286,10 +1304,13 @@
\fBfiles/cmdr_parameter\&.n\fR
cmdr::parameter
.TP
\fBfiles/cmdr_private\&.n\fR
cmdr::private
+.TP
+\fBfiles/cmdr_table\&.n\fR
+cmdr::table
.TP
\fBfiles/cmdr_tty\&.n\fR
cmdr::tty
.TP
\fBfiles/cmdr_util\&.n\fR
@@ -1442,10 +1463,13 @@
\fBfiles/cmdr_parameter\&.n\fR
cmdr::parameter
.TP
\fBfiles/cmdr_private\&.n\fR
cmdr::private
+.TP
+\fBfiles/cmdr_table\&.n\fR
+cmdr::table
.TP
\fBfiles/cmdr_tty\&.n\fR
cmdr::tty
.TP
\fBfiles/cmdr_util\&.n\fR
@@ -1598,10 +1622,13 @@
\fBfiles/cmdr_parameter\&.n\fR
cmdr::parameter
.TP
\fBfiles/cmdr_private\&.n\fR
cmdr::private
+.TP
+\fBfiles/cmdr_table\&.n\fR
+cmdr::table
.TP
\fBfiles/cmdr_tty\&.n\fR
cmdr::tty
.TP
\fBfiles/cmdr_util\&.n\fR
@@ -1754,10 +1781,13 @@
\fBfiles/cmdr_parameter\&.n\fR
cmdr::parameter
.TP
\fBfiles/cmdr_private\&.n\fR
cmdr::private
+.TP
+\fBfiles/cmdr_table\&.n\fR
+cmdr::table
.TP
\fBfiles/cmdr_tty\&.n\fR
cmdr::tty
.TP
\fBfiles/cmdr_util\&.n\fR
@@ -1910,10 +1940,13 @@
\fBfiles/cmdr_parameter\&.n\fR
cmdr::parameter
.TP
\fBfiles/cmdr_private\&.n\fR
cmdr::private
+.TP
+\fBfiles/cmdr_table\&.n\fR
+cmdr::table
.TP
\fBfiles/cmdr_tty\&.n\fR
cmdr::tty
.TP
\fBfiles/cmdr_util\&.n\fR
@@ -2066,10 +2099,13 @@
\fBfiles/cmdr_parameter\&.n\fR
cmdr::parameter
.TP
\fBfiles/cmdr_private\&.n\fR
cmdr::private
+.TP
+\fBfiles/cmdr_table\&.n\fR
+cmdr::table
.TP
\fBfiles/cmdr_tty\&.n\fR
cmdr::tty
.TP
\fBfiles/cmdr_util\&.n\fR
@@ -2222,10 +2258,13 @@
\fBfiles/cmdr_parameter\&.n\fR
cmdr::parameter
.TP
\fBfiles/cmdr_private\&.n\fR
cmdr::private
+.TP
+\fBfiles/cmdr_table\&.n\fR
+cmdr::table
.TP
\fBfiles/cmdr_tty\&.n\fR
cmdr::tty
.TP
\fBfiles/cmdr_util\&.n\fR
@@ -2378,10 +2417,13 @@
\fBfiles/cmdr_parameter\&.n\fR
cmdr::parameter
.TP
\fBfiles/cmdr_private\&.n\fR
cmdr::private
+.TP
+\fBfiles/cmdr_table\&.n\fR
+cmdr::table
.TP
\fBfiles/cmdr_tty\&.n\fR
cmdr::tty
.TP
\fBfiles/cmdr_util\&.n\fR
Index: embedded/man/toc.n
==================================================================
--- embedded/man/toc.n
+++ embedded/man/toc.n
@@ -349,10 +349,13 @@
\fIfiles/cmdr_parameter\&.n\fR: Cmdr - (Partially internal) Command parameters
.TP
\fBcmdr::private\fR
\fIfiles/cmdr_private\&.n\fR: Cmdr - (Internal) Single command handling, options, and arguments
.TP
+\fBcmdr::table\fR
+\fIfiles/cmdr_table\&.n\fR: Cmdr - Simple Table creation
+.TP
\fBcmdr::tty\fR
\fIfiles/cmdr_tty\&.n\fR: Cmdr - Check if stdin is a tty, i\&.e\&. terminal
.TP
\fBcmdr::util\fR
\fIfiles/cmdr_util\&.n\fR: Cmdr - (Internal) General Utilities
Index: embedded/www/doc/files/cmdr_changes.html
==================================================================
--- embedded/www/doc/files/cmdr_changes.html
+++ embedded/www/doc/files/cmdr_changes.html
@@ -133,19 +133,20 @@
underwent from version to version.
-Added many new standard validation types to package
- cmdr::validate:
+Extended the package cmdr::validate with many new
+ standard validation types:
+
Double
Percent
Posint (positive integers, > 0)
Paths and channels
-
+
Readable file
Writable file
Read/writable file
Readable directory
Read/writeable directory
@@ -156,60 +157,59 @@
Read/writable path, as channel
Date and time related:
-
-iso8601 date/time,
+
+ISO-8601 date/time,
year
weekday,
hour:minute
-Added more helper commands for validation failure messages to
- package cmdr::validate::common.
+In package cmdr::validate, modified the integer
+ validation type to have a proper internal representation:
+ decimal. Input in octal, hex, etc. is now normalized to this.
+Extended package cmdr::validate::common with more
+ helper commands for the generation of validation failure
+ messages
-fail-unknown-thing
fail-unknown-thing-msg
fail-unknown-simple
fail-unknown-simple-msg
-fail-known-thing
fail-known-thing-msg
fail-known-simple
fail-known-simple-msg
-Modified integer validation to have a proper internal
- representation: decimal. Octal, hex, etc. input is now
- normalized to this.
-Various new supporting packages:
+Added 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.
+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::table
+Table formatting, a 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:
+Even more validation types, now as wrappers around the
+ validation commands provided by
+ Tcllib:
-
+
valtype::creditcard::amex
valtype::creditcard::discover
valtype::creditcard::mastercard
valtype::creditcard::visa
valtype::gs1::ean13
@@ -221,39 +221,89 @@
valtype::usnpi
valtype::verhoeff
-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.
-Added support for an option -extend for common blocks,
- allowing their extension in a subordinate instead of just
- replacing the entire content.
-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.
-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.
-Extended officers to accept all unique command prefixes of
- their subordinates for dispatch.
-Modified the help system to use the short format for
- interior nodes of the command hierarchy by default.
-Modified the help system to exclude auto-added commands from
- the output generated by format by-category.
-... A suite of bug fixes ... // TODO: list the details.
+Extended package cmdr::officer with
+
+
+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.
+Support for an option -extend for common
+ blocks, allowing their extension in a subordinate
+ instead of just replacing the entire content.
+Support to accept all unique command prefixes of an
+ officer's subordinates for dispatch.
+
+
+Extended package cmdr::parameter with
+
+
+Support for the specification of negative aliases for
+ boolean options, i.e. representing the inverted option.
+See the DSL commands neg-alias and !alias in
+ Cmdr - Parameter Specification Language.
+Support for option labeling, for use in the generated
+ help, to make it more descriptive. Options for which no
+ label is specified will use their name as fallback.
+See DSL command label in
+ Cmdr - Parameter Specification Language.
+
+
+Help system changes
+
+
+Modified it to use the short format for interior
+ nodes of the command hierarchy by default.
+Modified it to exclude auto-added commands from the
+ output generated by format by-category.
+Modified the format full to show the option
+ arguments for those which have such. See also the
+ extension of package cmdr::parameter with
+ support for option labels, this is what is used here.
+Modified it to declare a standard global option
+ --help (with aliases -h and
+ -?). Using the option invokes the standard help
+ (command) on the current command, if any, or the global
+ help if there is no command.
+Modified to use a minimum width of 10 characters for
+ descriptions. If the user narrowed the terminal this far
+ then having the text either cut off at the right edge,
+ or wrapped around is not worse then the help trying to
+ wrap the sentence with word boundaries, etc. Also,
+ trying to use negative width threw Tcl errors.
+
+
+Fixed the handling of common block *all* in package
+ cmdr::officer. While it was ok trapping and ignoring
+ a missing definition of this block, trapping everything which
+ could go wrong was not.
+Details.
+Fixed a long-standing bug of package cmdr::config in
+ the forced calculation of parameter values in method
+ Force). Any error in the calculations left an internal
+ flag set, causing future invokations to believe to be in a
+ recursive call and thus do nothing.
+While this had no effect on regular operation, i.e.
+ with the application exiting after each command, in interactive
+ mode this misbehaviour disabled all checks and validations for
+ the command in question, and also retained old parameter
+ values.
+Details
+Modified the formatting of cmdr::config state when
+ interactively entering it for a private. Parameter names now
+ are shown as declared, and an additional flag character
+ indicates if it is inherited from above, or not.
+General fixes to testsuite, code comments, bogus variable
+ names, typos in error messages, etc.
Welcome to the Cmdr project, written by Andreas Kupries.
@@ -229,12 +230,16 @@
word does not match any of the commands known to this
officer
this default is used. If no default is specified an error will be
thrown instead.
description text
This command declares the help text of the officer.
-
ehandler cmdprefix
-
This is an advanced command which should normally only be specified at
+
intercept cmdprefix
+
+
ehandler cmdprefix
+
Note: While the form ehandler is still usable, it is
+deprecated and will be removed in a future release.
+This is an advanced command which should normally only be specified at
the top of the whole hierarchy (from which its value will
automatically propagate to all subordinates).
At runtime the framework will call the specified command prefix
with a single argument, a script whose execution is equivalent to the
phases Parsing, Completion, and Execution of the
@@ -252,37 +257,39 @@
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.
-
shandler cmdprefix
+
custom-setup 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.
+
When called multiple times, the specified commands
+accumulate. This makes it easy to specify several indepedent
+customizations.
+At runtime the framework will invoke all the specified commands
+with a single argument, the command of the actor to initialize.
The command prefix is then allowed to modify that actor as it sees
fit. The common use case will be the extension of the object with
additional subordinates.
An example of this is the package cmdr::history which
provides a command cmdr::history::attach to add the history
management commands to the actor in question.
-
officer name script
+
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_dsl_parameter.html
==================================================================
--- embedded/www/doc/files/cmdr_dsl_parameter.html
+++ embedded/www/doc/files/cmdr_dsl_parameter.html
@@ -152,11 +152,11 @@
presence
when-complete cmdprefix
when-set cmdprefix
stop!
touch name value
-
touch name value
+
touch? name value
disallow name
@@ -525,11 +525,11 @@
touch name value
The returned callback sets the named sibling parameter to the
specified value. A simple method of communication between
parameters of a command.
Useful for use with when-set and/or when-complete
-
touch name value
+
touch? name value
The returned callback sets the named sibling parameter to the
specified value, if and only if that parameter exists. A simple
method of communication between parameters of a command, where the
sibling may not exists, depending on usage context.
Useful for use with when-set and/or when-complete
Index: embedded/www/doc/files/cmdr_history.html
==================================================================
--- embedded/www/doc/files/cmdr_history.html
+++ embedded/www/doc/files/cmdr_history.html
@@ -157,11 +157,11 @@
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
+method custom-setup 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.
@@ -177,11 +177,11 @@
fossil DVCS.
cmdr history initial-limit 20
cmdr history save-to ~/.fx_history
cmdr create fx::fx [file tail $::argv0] {
- shandler ::cmdr::history::attach
+ custom-setup ::cmdr::history::attach
[...]
}
Welcome to the Cmdr project, written by Andreas Kupries.
@@ -247,12 +249,16 @@
This represents the "Dispatch" phase of command line processing.
- string word
The words of the command line to parse and match to parameters.
-
<officer> ehandler cmd
-
This method specifies a command prefix to wrap around the parsing of
+
<officer> intercept cmd
+
+
<officer> ehandler cmd
+
Note: While the form ehandler is still usable, it is
+deprecated and will be removed in a future release.
+This method specifies a command prefix to wrap around the parsing of
the command line for the officer, and the execution of its action.
- cmd-prefix cmd
A command prefix taking a single argument, a script. The command
prefix has to execute this script in its caller's context. The script
@@ -260,15 +266,33 @@
prefix then has the responsbility to perform any custom cleanup action
required by the application using the framework to prevent leakage of
data between multiple commands executed one after the other (i.e. in
an interactive shell run by the framework).
-
<officer> exit
+
<officer> custom-setup cmd
+
This method specifies a command prefix which will be run all the
+regular setup of the officer from its specification is done, to
+perform customizations.
+An example of this can be seen in the package
+cmdr::history. It provides a command
+cmdr::history::attach to add the history management commands to
+the actor in question, suitable as argument to this method.
+When called multiple times, the specified commands
+accumulate. This makes it easy to specify several indepedent
+customizations.
+
+- cmd-prefix cmd
+A command prefix taking a single argument, the instance command of an
+cmd::actor. The command prefix has full access to this actor
+and can modify it as it sees fit. The common use case will be the
+extension of the actor with additional subordinates.
+
+
<officer> exit
This hook-method for the main shell returns a boolean value indicating
whether the main shell was stopped and has to exit (true), or
not (false).
-
<officer> extend path arguments action
+
<officer> extend path arguments action
A convenience method to create a "private" command underneath this
officer, with the command name path (a list of names). Any
intermediate officers are created as needed. An error is thrown if any
of the intermediates already exist as a (non-extensible) private, or
if the last command already exists.
@@ -287,84 +311,84 @@
execution. It takes a single argument, the instance command of the
hidden cmdr::config container holding the private's
parameters. The result of the action, if there is any, is ignored by
the framework.
-
<officer> find path
+
<officer> find path
This method returns the instance command of the sub-ordinate with the
given path (a list) of names. An error is thrown if such a sub-ordinate
does not exist. This is an extension of lookup to paths of names.
An empty path is allowed and refers to the officer itself.
- string path
The path of names to the sub-ordinate to look for.
-
<officer> has name
+
<officer> has name
This method returns a boolean value indicating if this officer has a
sub-ordinate of the given name (true), or not
(false). See also method lookup.
- string name
The name of the sub-ordinate to look for.
-
<officer> hasdefault
+
<officer> hasdefault
This method returns a boolean value indicating if this officer has a
default sub-ordinate (true), or not (false). See also
method default.
-
<officer> help ?prefix?
+
<officer> help ?prefix?
This method returns the help information for the officer and its
subordinates. The prefix, if specified provides the name of the
officer within the help data. It defaults to the empty string.
The result of the command is a structure of the form
described in section Help Information.
- string prefix
The name to use for the officer within the generated help.
-
<officer> known
+
<officer> known
This method returns a list containing the names of the subordinate
actors managed by this officer.
See also method children which returns a list of instance
commands.
See also method lookup to map names to instance commands.
-
<officer> learn script
+
<officer> learn script
This method takes a regular specification script and uses it to extend
the set of subordinates known to this officer. This is the same type
of script as used during construction, except here we dynamically
extend the officer.
- script actions
The specification of the officer's additional subordinates.
Please read Cmdr - Officer Specification Language for the details.
-
<officer> lookup name
+
<officer> lookup name
This method returns the instance command of the sub-ordinate with the
given name. An error is thrown if such a sub-ordinate does not
exist. See also method has.
- string name
The name of the sub-ordinate to look for.
-
<officer> prompt1
+
<officer> prompt1
This hook-method for the main shell returns the primary prompt string
to use.
-
<officer> prompt2
+
<officer> prompt2
This hook-method for the main shell returns the secondary prompt
string for use within a continuation. As the main shell does not
support continuation lines it should not be invoked ever, and thus
always throws an error should it be invoked.
-
<officer> report what data
+
<officer> report what data
This hook-method for the main shell is responsible for the reporting
of the command results.
Its result is the empty string.
- enum what
The result code of the command, one of ok, or fail.
- any data
The result of the command, or an error message in case of failure.
-
<officer> shell-exit config
+
<officer> shell-exit config
This is the backend for a private ending the main shell,
be it automatically created by the pacge, or by a user.
The argument is the cmdr::config
instance holding the parameters. The method does not
expect any and ignore it.
Index: embedded/www/doc/files/cmdr_private.html
==================================================================
--- embedded/www/doc/files/cmdr_private.html
+++ embedded/www/doc/files/cmdr_private.html
@@ -130,14 +130,16 @@
Welcome to the Cmdr project, written by Andreas Kupries.
@@ -208,12 +210,16 @@
filled container of parameters.
- string word
The words of the command line to parse and match to parameters.
-
<private> ehandler cmd
-
This method specifies a command prefix to wrap around the parsing of
+
<private> intercept cmd
+
+
<private> ehandler cmd
+
Note: While the form ehandler is still usable, it is
+deprecated and will be removed in a future release.
+This method specifies a command prefix to wrap around the parsing of
the command line for the private, and the execution of its action.
- cmd-prefix cmd
A command prefix taking a single argument, a script. The command
prefix has to execute this script in its caller's context. The script
@@ -221,11 +227,18 @@
prefix then has the responsbility to perform any custom cleanup action
required by the application using the framework to prevent leakage of
data between multiple commands executed one after the other (i.e. in
an interactive shell run by the framework).
-
<private> find path
+
<private> custom-setup cmd
+
This method specifies a command prefix which will be run all the
+regular setup of an officer from its specification is done, to perform
+customizations.
+The <private> here ignores such calls.
+The method exists only to avoid having to special-case code the
+places propagating these commands down the hierarchy.
+
<private> find path
This method returns the instance command of the sub-ordinate with the
given path of names. An error is thrown if such a sub-ordinate
does not exist, i.e. whenever path is not empty, as a private
has no sub-ordinates, ever.
Note, as implied above, an empty path is allowed and
@@ -234,21 +247,21 @@
high-end of the recursion which may end in this method.
- string path
The path of names to the sub-ordinate to look for.
-
<private> help ?prefix?
+
<private> help ?prefix?
This method returns the help information for the private and its
parameters. The prefix, if specified provides the name of the
private within the help data. It defaults to the empty string.
The result of the command is a structure of the form
described in section Help Information.
- string prefix
The name to use for the private within the generated help.
-
<private> unknown m ?word...?
+
<private> unknown m ?word...?
This method overrides the standard behaviour for unknown methods.
Instead of throwing an error they are routed to the hidden container
of the private's parameters, of class cmdr::config.
- string m
ADDED embedded/www/doc/files/cmdr_table.html
Index: embedded/www/doc/files/cmdr_table.html
==================================================================
--- /dev/null
+++ embedded/www/doc/files/cmdr_table.html
@@ -0,0 +1,293 @@
+
+
+cmdr::table - Cmdr, a framework for command line parsing and dispatch
+
+
+
+
+
+
Index: embedded/www/doc/toc.html
==================================================================
--- embedded/www/doc/toc.html
+++ embedded/www/doc/toc.html
@@ -116,106 +116,110 @@
cmdr::private |
Cmdr - (Internal) Single command handling, options, and arguments |
+cmdr::table |
+Cmdr - Simple Table creation |
+
+
cmdr::tty |
Cmdr - Check if stdin is a tty, i.e. terminal |
-
+
cmdr::util |
Cmdr - (Internal) General Utilities |
-
+
cmdr::validate |
Cmdr - Standard validation types for parameters |
-
+
cmdr::validate::common |
Cmdr - Utilities for Validation Types |
-
+
cmdr::validate::date |
Cmdr - Validation type for dates |
-
+
cmdr::validate::posint |
Cmdr - Validation type for positive integers |
-
+
cmdr::validate::time |
Cmdr - Validation type for times (to the second) |
-
+
cmdr::validate::time::minute |
Cmdr - Validation type for times to the minute |
-
+
cmdr::validate::valtype::cc::amex |
Cmdr - Validation type facade for Tcllib valtype::cc::amex |
-
+
cmdr::validate::valtype::cc::discover |
Cmdr - Validation type facade for Tcllib valtype::cc::discover |
-
+
cmdr::validate::valtype::cc::mastercard |
Cmdr - Validation type facade for Tcllib valtype::cc::mastercard |
-
+
cmdr::validate::valtype::cc::visa |
Cmdr - Validation type facade for Tcllib valtype::cc::visa |
-
+
cmdr::validate::valtype::gs1::ean13 |
Cmdr - Validation type facade for Tcllib valtype::gs1::ean13 |
-
+
cmdr::validate::valtype::iban |
Cmdr - Validation type facade for Tcllib valtype::iban |
-
+
cmdr::validate::valtype::imei |
Cmdr - Validation type facade for Tcllib valtype::imei |
-
+
cmdr::validate::valtype::isbn |
Cmdr - Validation type facade for Tcllib valtype::isbn |
-
+
cmdr::validate::valtype::luhn |
Cmdr - Validation type facade for Tcllib valtype::luhn |
-
+
cmdr::validate::valtype::luhn5 |
Cmdr - Validation type facade for Tcllib valtype::luhn5 |
-
+
cmdr::validate::valtype::usnpi |
Cmdr - Validation type facade for Tcllib valtype::usnpi |
-
+
cmdr::validate::valtype::verhoeff |
Cmdr - Validation type facade for Tcllib valtype::verhoeff |
-
+
cmdr::validate::weekday |
Cmdr - Validation type for weekday names |
-
+
cmdr::validate::year |
Cmdr - Validation type for years |
-
+
cmdr_development |
Cmdr - The Developer's Guide |
-
+
cmdr_dev~completion |
Cmdr - Internals of command line completion |
-
+
cmdr_dev~dsl |
Cmdr - Internals of DSL handling |