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

# cmdr::officer(n) 1.4.1 doc "Cmdr, a framework for command line parsing and dispatch"

## Name

cmdr::officer - Cmdr - (Internal) Aggregation of multiple commands for dispatch.

## Table Of Contents

## Synopsis

- package require cmdr::officer

- ::cmdr::officer new super name actions
- ::cmdr::officer create obj super name actions
- <officer> children
- <officer> complete line
- <officer> complete-words parse
- <officer> continued line
- <officer> default
- <officer> dispatch cmd
- <officer> do ?word...?
- <officer> intercept cmd
- <officer> ehandler cmd
- <officer> custom-setup cmd
- <officer> exit
- <officer> extend path arguments action
- <officer> find path
- <officer> has name
- <officer> hasdefault
- <officer> help ?prefix?
- <officer> known
- <officer> learn script
- <officer> lookup name
- <officer> prompt1
- <officer> prompt2
- <officer> report what data
- <officer> shell-exit config

## Description

Welcome to the Cmdr project, written by Andreas Kupries.

For availability please read Cmdr - How To Get The Sources.

This package implements officers, the inner nodes of command hierarchies. Each officer can execute many actions, by delegating them to their sub-ordinate actors, officers and privates.

This class is sub-class of cmdr::actor.

## Class API

The class API is not public. It is used internally by the framework when parsing a command hierarchy specification to create the necessary officer instances.

It is described here for use by developers maintaining, modifying and extending the framework itself. A user of the framework has no need for it.

::cmdr::officer new super name actions

  Create an auto-named instance of cmdr::officer.

  Not used.

::cmdr::officer create obj super name actions

  Create a new instance of cmdr::officer, named obj. Used by the DSL processing parts of the framework to instantiate officers.

  object super

    The instance command of the actor (officer actually) which contains the new officer.

  string name

    The user-visible name of the command.

  script actions

    The specification of the officer's subordinates. Please read Cmdr - Officer Specification Language for the details.

## Instance API

The instance API is not public. It is used internally by the framework during the parsing of a command hierarchy specification to configure the officer instances, and when processing a command line at runtime to manage navigation of the hierarchy, word-completion, etc.

It is described here for use by developers maintaining, modifying and extending the framework itself. A user of the framework has no need for it.

<officer> children

  This method returns a list containing the instance commands of the subordinate actors managed by this officer. See also method known which returns a list of names.

<officer> complete line

  This hook-method for the main shell is responsible for computing the set of completions for the entered line.

  string line

    The command line to complete.

<officer> complete-words parse

  This method is part of the main shell command line completion. For the details of its workings please read Cmdr - Internals of command line completion.

  Given the completion state parse of a partial command line it returns a list of strings which are the valid completions at this point.

  dict parse

    A dictionary holding the current completion state of a partial command line.

<officer> continued line

  This hook-method for the main shell is responsible for the detection of a continuation-line in the entered command line. It always returns the boolean value false as the main shell does not support continuation lines.

  list list
<officer> default

  This method returns the instance command of the subordinate to use during command line processing if the first word does not specify a known subordinate. An error is thrown if no such default was specified for this officer. See also method hasdefault.

<officer> dispatch cmd

  This hook-method for the main shell is responsible for the recognition and execution of the supported commands.

  string cmd

    The command line containing the command to run.

<officer> do ?word...?

  This method parses the words of the command line, matching them to the sub-ordinates of the officer. When done without error it recursively invokes the chosen sub-ordinate to continue processing.

  This represents the "Dispatch" phase of command line processing.

  string word

    The words of the command line to parse and match to parameters.

<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 will parse words for the officer,m and perform its action. The command 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> 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

  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.

  The arguments after the path match the constructor of privates in number and semantics.

  script path

    The list of names specifying the route from this officer to the new private. The last element is the name of the private command, while the preceding names specify the intermediate officers.

  script arguments

    The specification of the private's parameters. Please read Cmdr - Parameter Specification Language for the details.

  cmd-prefix action

    The command prefix to invoke when this private is selected for 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

  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

  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

  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?

  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

  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

  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

  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

  This hook-method for the main shell returns the primary prompt string to use.

<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

  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

  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.

## Help Information

The help information generated by various places of the framework is a dictionary containing the following keys:

arguments

  A list of strings, the names of the command arguments, in order. These names are keys into the parameters sub-dictionary.

desc

  The command's description, i.e. help text.

opt2para

  A dictionary mapping option flags to option names. These names are keys into the parameters sub-dictionary.

options

  A dictionary mapping option names to their descriptions.

parameters

  A dictionary mapping parameter names to their definition. Each definition is a dictionary containing the keys below. See also package cmdr::parameter.

  cmdline

    Output of method cmdline.

  code

    Output of method code.

  default

    Output of method default.

  defered

    Output of method defered.

  description

    Output of method description.

  documented

    Output of method documented.

  flags

    A dictionary mapping flag names to flag types, i.e. primary, alias, or inverted.

  generator

    Output of method generator.

  interactive

    Output of method interactive.

  isbool

    Output of method isbool.

  label

    Output of method label.

  list

    Output of method list.

  ordered

    Output of method ordered.

  presence

    Output of method presence.

  prompt

    Output of method prompt.

  required

    Output of method required.

  threshold

    Output of method threshold.

  type

    Output of method type.

  validator

    Output of method validator.

sections

  A list of sections the command belongs to. Each section name is a list itself, the path of the section and sub-sections.

states

  A list of strings, the names of the command's hidden state parameters. These names are keys into the parameters sub-dictionary.

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