cmdr::officer - Cmdr - (Internal) Aggregation of multiple commands for dispatch.
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.
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.
Create an auto-named instance of cmdr::officer.
Not used.
Create a new instance of cmdr::officer, named obj. Used by the DSL processing parts of the framework to instantiate officers.
The instance command of the actor (officer actually) which contains the new officer.
The user-visible name of the command.
The specification of the officer's subordinates. Please read Cmdr - Officer Specification Language for the details.
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.
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.
This hook-method for the main shell is responsible for computing the set of completions for the entered line.
The command line to complete.
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.
A dictionary holding the current completion state of a partial command 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.
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.
This hook-method for the main shell is responsible for the recognition and execution of the supported commands.
The command line containing the command to run.
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.
The words of the command line to parse and match to parameters.
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.
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).
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.
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.
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).
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.
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.
The specification of the private's parameters. Please read Cmdr - Parameter Specification Language for the details.
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.
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.
The path of names to the sub-ordinate to look for.
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.
The name of the sub-ordinate to look for.
This method returns a boolean value indicating if this officer has a default sub-ordinate (true), or not (false). See also method default.
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.
The name to use for the officer within the generated help.
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.
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.
The specification of the officer's additional subordinates. Please read Cmdr - Officer Specification Language for the details.
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.
The name of the sub-ordinate to look for.
This hook-method for the main shell returns the primary prompt string to use.
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.
This hook-method for the main shell is responsible for the reporting of the command results.
Its result is the empty string.
The result code of the command, one of ok, or fail.
The result of the command, or an error message in case of failure.
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.
The help information generated by various places of the framework is a dictionary containing the following keys:
A list of strings, the names of the command arguments, in order. These names are keys into the parameters sub-dictionary.
The command's description, i.e. help text.
A dictionary mapping option flags to option names. These names are keys into the parameters sub-dictionary.
A dictionary mapping option names to their descriptions.
A dictionary mapping parameter names to their definition. Each definition is a dictionary containing the keys below. See also package cmdr::parameter.
Output of method cmdline.
Output of method code.
Output of method default.
Output of method defered.
Output of method description.
Output of method documented.
A dictionary mapping flag names to flag types, i.e. primary, alias, or inverted.
Output of method generator.
Output of method interactive.
Output of method isbool.
Output of method label.
Output of method list.
Output of method ordered.
Output of method presence.
Output of method prompt.
Output of method required.
Output of method threshold.
Output of method type.
Output of method validator.
A list of sections the command belongs to. Each section name is a list itself, the path of the section and sub-sections.
A list of strings, the names of the command's hidden state parameters. These names are keys into the parameters sub-dictionary.
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.
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 © 2013-2016 Andreas Kupries
Copyright © 2013-2016 Documentation, Andreas Kupries