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

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

Name

cmdr::actor - Cmdr - (Internal) Base class for officers and privates

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 internal package implements the base class containing functionality common to cmdr::officer and cmdr::private.

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 command 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::actor new

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

Not used.

::cmdr::actor create obj

Create a new instance of cmdr::actor, named obj.

Instance API

Most of the instance API is not public.

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.

<actor> completions parse cmdlist

This method is part of 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 and a list of completions at the end of the line it returns a list of strings which are the valid completions of the whole line, properly quoted.

dict parse

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

list cmdlist

List of valid completions.

<actor> description

This accessor method returns the human-readable description of the actor.

<actor> description: text

This method sets the description of the actor to the text.

string text

The description to remember.

<actor> dname

This accessor method returns the display name of the actor. This is the name of the actor prefixed with the contents of the reserved common block *prefix*, set during command line processing with the actual command path to reach the current actor.

<actor> do ?word...?

This method processes the command-line given as a list of words. Here in the bse class it does nothing. It is a virtual method expecting to be redefined by the derived classes.

list word
<actor> documented

This accessor method returns the "documented" flag of the actor.

<actor> exists key

This method returns a boolean value indicating whether the common block named by key exists in the actor and its parents (true), or not (false).

string key

The name of the common block to check for.

<actor> fullname

This method returns the full name of the actor. This is the name of the actor prefixed with the path to it in the specification, i.e. the names of all actors in the chain of supers.

<actor> get key

This method returns the content of the common block named by key. An error is thrown if the block is not known to the actor, nor its parents.

string key

The name of the common block to retrieve.

<actor> help

This accessor method returns the empty string. It is a virtual method expecting to be redefined by the derived classes.

<actor> keys

This accessor method returns a list of names for the set of common blocks known to this actor, and all of its parents.

<actor> lappend key data

This method extends the contents of the common block named by key with data. Conceptually this is a get/lappend/set operation, i.e. while the existing block content is taken from the actor or its parents, the new content is always stored in the actor.

string key

The name of the common block to extend.

any data

The data to add to the block.

<actor> match parse cmdlist

This method is part of 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 and a list of possible completions it returns a list of valid completions, filtered against the current word in the command line.

dict parse

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

list cmdlist

List of possible completions.

<actor> name

This accessor method returns the name of the actor.

<actor> name: name

This method sets the name of the actor.

string name

The name to remember.

<actor> parse-line line

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

Is the main helper to begin command completion. Given the entered command line it parses it into words and returns a parse structure as is taken by all other methods taking part in command completion.

string line

The command line.

<actor> root

This accessor method returns the root actor instance the actor belongs to.

<actor> set key -extend -- data

This method sets the contents of the common block named by key to data. If the block does not exist it is created. Otherwise its existing content is written over.

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 key

The name of the common block to write.

any data

The data to store in the block.

<actor> super

This accessor method returns the parent actor instance. For the root of the tree this is the empty string.

<actor> super: obj

This method links the actor to its parent actor.

cmdr::actor obj

The parent actor instance to remember.

<actor> undocumented

This method marks the actor as undocumented.

<actor> unset key

This method removes the common block named by key from the actor. Note that definitions in parents are not touched by this.

string key

The name of the common block to remove.

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