[ Home | Main Table Of Contents | Table Of Contents | Keyword Index ]

cmdr-spec-dsl-officer(n) 1.1 doc "Cmdr, a framework for command line parsing and dispatch"

Name

cmdr-spec-dsl-officer - Cmdr - Officer Specification Language

Table Of Contents

Synopsis

Description

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.

Related Specification Documents

  1. Cmdr - Introduction to the Specification Language

  2. Cmdr - Officer Specification Language

  3. Cmdr - Private Specification Language

  4. Cmdr - Parameter Specification Language

  5. Cmdr - Runtime Processing Flow

Language Reference

alias name = name'...
alias name

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.

string name

The name of the alias.

string name'...

The path to the actor, as list of names.

common name text

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

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

string name

The name of the common block.

string text

The text of the block.

default

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.

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 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:

  1. Capture and hande application-specific errors which should not abort the application, nor shown as Tcl stacktrace.

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

officer name script

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

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

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.

Related Documents

  1. Cmdr - Introduction to the project

  2. Cmdr - License

  3. Cmdr - Log of Changes

  4. Cmdr - How To Get The Sources

  5. Cmdr - The Installer's Guide

  6. Cmdr - The Developer's Guide

Bugs, Ideas, Feedback

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

Please also report any ideas you may have for enhancements of either package(s) and/or documentation.

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