[ 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

- package require cmdr::actor

- ::cmdr::actor new
- ::cmdr::actor create obj
- <actor> completions parse cmdlist
- <actor> description
- <actor> description: text
- <actor> dname
- <actor> do ?word...?
- <actor> documented
- <actor> exists key
- <actor> fullname
- <actor> get key
- <actor> help
- <actor> keys
- <actor> lappend key data
- <actor> match parse cmdlist
- <actor> name
- <actor> name: name
- <actor> parse-line line
- <actor> root
- <actor> set key -extend -- data
- <actor> super
- <actor> super: obj
- <actor> undocumented
- <actor> unset key

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

## Copyright

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