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

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

## Name

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

## Table Of Contents

## Synopsis

- alias name = name'...
- alias name
- common name -extend -- text
- default
- description text
- intercept cmdprefix
- ehandler cmdprefix
- custom-setup cmdprefix
- officer name script
- private name script cmdprefix
- undocumented

## 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 -extend -- 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.

  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.

  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.

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

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

  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

  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

## Copyright

Copyright © 2013-2016 Andreas Kupries
Copyright © 2013-2016 Documentation, Andreas Kupries