Module commands::parser

Command Parser

The command parser deals with interpreting textual input (like a command line) and executing a command with the provided parameters.

Each command has a name which is typically a series of words. Some examples might be:

• show directory /bin
• show struct
• thread step in
• thread step out
• show process list

Don't worry about commands being long. Ideally, it will be rare that that the entire command would be typed by applying intelligent and interactive autocompletion.

Commands can take parameters. Parameters can be marked as required or repeatable. Repeatable parameters generate a list of values rather than a single value.

There are three kinds of parameters:

• Simple: Just a value that is present in the command line. For example: show interface eth0 where eth0 is a simple parameter name which will have the value eth0.
• Named: A name that precedes the value in the command line. For example: show route src <ip> dst <ip> where src <ip> and dst <ip> are both named parameters to a command show route.
• Flag: Signify a true value when present. For example: show log verbose where verbose is a flag parameter that results in value of true when present and false when not.

The command parser does not assume anything about the implementation of the textual interface. It provides a mechanism for parsing tokens that have been tokenized from an input and a method for communicating with the embedding application for errors and autocompletion by way of using structured data rather than printing to an output device (like stdout).

The command parser consists of two important things:

• A tree that represents the available commands and their arguments. This tree consists of instances of implementations of Node like CommandNode, ParameterNode and RootNode. Construction of this tree is done with the help of CommandTree, Command and Parameter.
• A Parser that handles input and matches it against the command tree. This parser is intended to be short-lived and to just live for the duration of parsing and evaluating a single command line input.

Building A Command Tree

The commands handled by a Parser are represented by a tree based the words in the commands. For example, with commands show directory, show class, help, and thread step, there are 3 leaf nodes from the root and the tree is arranged like:

• show
  • directory
  • class
• help
• thread
  • step

Building a tree of nodes for use with the parser is best done with the CommandTree in conjunction with Command and Parameter.

Start by creating a mutable CommandTree instance:

use commands::parser::{CommandTree, Parser};

let mut tree = CommandTree::new();

Then, add your commands and arguments, and finally, call finalize on the tree to get back a RootNode that can use be used with a Parser.

use commands::parser::{Command, CommandTree, Parameter, Parser};

let mut tree = CommandTree::new();
tree.command(Command::new("again")
                 .hidden(false)
                 .parameter(Parameter::new("test")
                                .required(false)
                                .help("This is just a test parameter.")));
let root = tree.finalize();
let mut parser = Parser::new(root);

Structs

Command	Description of a command to be added to the CommandTree.
CommandNode	A node representing a command. Constructed via Command and CommandTree.
CommandTree	Store a command tree while populating it. This is used to construct a RootNode to be used with the Parser.
Completion	Represents the result of completing a node. Each valid completion is represented by a CompletionOption.
CompletionOption	Represents a single option returned by complete.
Parameter	Description of a parameter to be added to the Command.
ParameterNameNode	A node that represented the name portion of a named parameter.
ParameterNode	A node representing a parameter for a command.
Parser	Command parser
RootNode	The root of a command tree.
TreeNode	A parse tree node.

Enums

Node	Enumeration of node types used to have vectors of Node and so on.
ParameterKind	Indicate the type of parameter, so that the correct class and node structures are created.
ParseError	Errors that calling parse on the Parser can raise.
VerifyError	Errors that calling verify on the Parser can raise.

Constants

PRIORITY_DEFAULT	The default priority.
PRIORITY_MINIMUM	Minimum priority.
PRIORITY_PARAMETER	The default priority for a parameter.

Traits

NodeOps

The operations that every node must implement.