cmdr-changes(n) 1.2 doc "Cmdr, a framework for command line parsing and dispatch"

Changes for version 1.2

1. Extended the package cmdr::validate with many new standard validation types:

   1. Double

   2. Percent

   3. Posint (positive integers, > 0)

   4. Paths and channels

      1. Readable file

      2. Writable file

      3. Read/writable file

      4. Readable directory

      5. Read/writeable directory

      6. readable path

      7. Read/writable path

      8. Readable path, as channel

      9. Writable path, as channel

      10. Read/writable path, as channel

   5. Date and time related:

      1. ISO-8601 date/time,

      2. year

      3. weekday,

      4. hour:minute

2. 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.

3. Extended package cmdr::validate::common with more helper commands for the generation of validation failure messages

   1. fail-unknown-thing-msg

   2. fail-unknown-simple

   3. fail-unknown-simple-msg

   4. fail-known-thing-msg

   5. fail-known-simple

   6. fail-known-simple-msg

4. 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.

   cmdr::history

   Pluggable management of command history.

   cmdr::table

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

   cmdr::validate::valtype-support

   Even more validation types, now as wrappers around the validation commands provided by Tcllib:

   1. valtype::creditcard::amex

   2. valtype::creditcard::discover

   3. valtype::creditcard::mastercard

   4. valtype::creditcard::visa

   5. valtype::gs1::ean13

   6. valtype::iban

   7. valtype::imei

   8. valtype::isbn

   9. valtype::luhn

   10. valtype::luhn5

   11. valtype::usnpi

   12. valtype::verhoeff

5. Extended package cmdr::officer with

   1. 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.

   2. Support for an option -extend for common blocks, allowing their extension in a subordinate instead of just replacing the entire content.

   3. Support to accept all unique command prefixes of an officer's subordinates for dispatch.

6. Extended package cmdr::parameter with

   1. 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.

   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.

      See DSL command label in Cmdr - Parameter Specification Language.

7. Help system changes

   1. Modified it to use the short format for interior nodes of the command hierarchy by default.

   2. Modified it to exclude auto-added commands from the output generated by format by-category.

   3. 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.

   4. 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.

   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.

8. 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.

9. 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

10. 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.

11. General fixes to testsuite, code comments, bogus variable names, typos in error messages, etc.

Changes for version 1.1

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

2. Fixed initialization issues in the help generator.

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

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

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

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

7. Extended system with new help format tcl, and associated package cmdr::help::tcl. Similar to format json the help is printed as a nested data structure, just using Tcl syntax.

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

Changes for version 1

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

In detail:

1. cmdr requires Tcl 8.5 or higher. Tcl 8.4 or less is not supported.

2. The framework provides a DSL for the declaration of a hierarchy of commands and their parameters (named options, positional arguments, hidden state), with help texts, type information, and various callbacks (command actions, parameter definition, parameter completion, type validation, command completion, etc.)

3. At runtime the framework provides parsing and processing of command lines per specifications written in that DSL, determining the command to run, and the mapping from command line words to its parameters.

4. The framework also provides shells for the interactive entry of commands and parameters, with command line completion.

5. Last, but not least is the automatic generation of command line help for commands and parameters, based on the information provided in a specification.