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

cmdr::private(n) 1.3.1 doc "Cmdr, a framework for command line parsing and dispatch"

Name

cmdr::private - Cmdr - (Internal) Single command handling, options, and arguments

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 package implements privates, the leaves of command hierarchies. While each private can execute only a single action they have parameters, i.e. arguments and options with which to configure the behaviour of their action.

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 private 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::private new super name arguments action

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

Not used.

::cmdr::private create obj super name arguments action

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

object super

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

string name

The user-visible name of the command.

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.

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 private instances, and when processing a command line at runtime to manage 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, although they have indirect access through parameters and their container.

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

<private> do ?word...?

This method parses the words of the command line, matching them to the parameters of the private, be they arguments, or options. When done without error it invokes the action of the private with the filled container of parameters.

string word

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

<private> intercept cmd
<private> 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 private, 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 private,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).

<private> custom-setup cmd

This method specifies a command prefix which will be run all the regular setup of an officer from its specification is done, to perform customizations.

The <private> here ignores such calls.

The method exists only to avoid having to special-case code the places propagating these commands down the hierarchy.

<private> find path

This method returns the instance command of the sub-ordinate with the given path of names. An error is thrown if such a sub-ordinate does not exist, i.e. whenever path is not empty, as a private has no sub-ordinates, ever.

Note, as implied above, an empty path is allowed and refers to the private itself.

See also method find of cdmr::officer for the high-end of the recursion which may end in this method.

string path

The path of names to the sub-ordinate to look for.

<private> help ?prefix?

This method returns the help information for the private and its parameters. The prefix, if specified provides the name of the private 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 private within the generated help.

<private> unknown m ?word...?

This method overrides the standard behaviour for unknown methods. Instead of throwing an error they are routed to the hidden container of the private's parameters, of class cmdr::config.

string m

The name of the unknown method.

string word

The argument (one or more) of the unknown method.

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