cmdr-spec-dsl-officer - Cmdr - Officer Specification Language
Welcome to the Cmdr project, written by Andreas Kupries.
For availability please read Cmdr - How To Get The Sources.
This document is for users of the cmdr framework. It introduces the domain-specific language for the specification of officers in detail.
Cmdr - Officer Specification Language
This is a structuring command, for the command hierarchy. Its main uses are the creation of alternate command names, and of shortcuts through the command hierarchy.
For example, stackato's command specification for alias management is written using deep nesting and uses aliases to provide the look of a flat namespace to application users.
In the first form the name is given the explicit path to the actor the name is an alias for. In the second form the alias implicitly refers to the immediately preceding officer or private. Note that "immediately" is interpreted at the current level. The system is not looking into a nested specification for its last command.
The name of the alias.
The path to the actor, as list of names.
This is another structuring command, for structuring the specification itself instead of the command tree it declares.
It creates named values, usually code blocks, which can be shared between specifications. Note that while each block is visible in the current officer and its subordinates, parents and siblings have no access.
An example of such a block would be
common *all* { option debug { Activate client internal tracing. } { undocumented list when-complete [lambda {p tags} { foreach t $tags { debug on $t } }] } }
This example defines an option to access the subsystem for debug narative (See package Tcllib). The example is actually special, as the block named *all* is reserved by the framework. This block, if defined, is automatically included at the front of all private specifications, i.e. shared across all the privates specified underneath this officer. A very important trait for the option in the example, as it makes the debug setup available to all privates without having to explicitly include the block, and possibly forgetting such.
Generally speaking, the framework reserves all blocks whose name begins with a star, i.e *, for its own use.
Using option -extend will change the behaviour to extend inherited content instead of writing over it.
Using option -- will prevent misinterpretation of the following argument as option, even if it begins with a dash.
The name of the common block.
The text of the block.
This command sets up a special kind of alias. The last private or officer is set as the default command to use at runtime. This means that if during "Dispatch" phase the currently processed 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.
This command declares the help text of the officer.
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 framework, as described in Cmdr - Runtime Processing Flow. The handler must call this script, and can perform any application-specific actions before and after.
This handler's main uses are two-fold:
Capture and hande application-specific errors which should not abort the application, nor shown as Tcl stacktrace.
Cleanup of application-specific transient state the parameter callbacks (See Cmdr - Parameter Specification Language) and/or actions may have set during their execution. This is especially important if the interactive command line shells of the framework are enabled. Without such a handler and its bespoke cleanup code transient state will leak between multiple commands run from such a shell, something which is definitely not wanted.
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).
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.
This command creates a named subordinate officer with its specification script of officer commands as described here.
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.
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.
Please continue reading with Cmdr - Private Specification Language.
Both the package(s) and this documentation will undoubtedly contain bugs and other problems. Please report such at Cmdr Tickets.
Please also report any ideas you may have for enhancements of either package(s) and/or documentation.
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
Copyright © 2013-2016 Andreas Kupries
Copyright © 2013-2016 Documentation, Andreas Kupries