Struct Commander

pub struct Commander<R> { /* private fields */ }

A constructed command tree.

Most of the time a user will want to use run() which will handle all the parsing and navigating of the tree. Alternatively, parse_line can be used to simulate a read input and update the command tree position.

To construct a command tree, look at the builder module.

Implementations

impl<'r, R> Commander<R>

pub fn run_with_completion<C: 'static + Completer<DefaultTerminal>, F: Fn(&Self) -> C>( self, completer_fn: F, )

Run the Commander interactively, with a completer constructed on every loop. Consumes the instance, and blocks the thread until the loop is exited.

See examples for how to construct a completer.

impl<R> Commander<R>

pub fn parse_line<W: Write>( &mut self, line: &str, colourise: bool, writer: &mut W, ) -> LineResult<R>

Parse a line of commands and updates the Commander state.

Parsing a line is akin to sending an input line to the commander in the run loop. Commands are space separated, and executed within this function, any actions that are specified will be invoked.

Most branches result in a LineResult::Continue apart from an exit command which will result in a LineResult::Exit. It is up to the developer to decide on the behaviour.

Example

use cmdtree::*;
let mut cmder = Builder::default_config("base")
       .begin_class("one", "")
       .begin_class("two", "")
    .add_action("echo", "", |_wtr, args| println!("{}", args.join(" ")))
       .into_commander().unwrap();

   assert_eq!(cmder.path(), "base");
   cmder.parse_line("one two", true,  &mut std::io::sink());
   assert_eq!(cmder.path(), "base.one.two");
cmder.parse_line("echo Hello, world!", true, &mut std::io::sink());    // should print "Hello, world!"

impl<R> Commander<R>

pub fn root_name(&self) -> &str

Return the root name.

Example

let mut cmder = Builder::default_config("base")
       .begin_class("one", "")
       .begin_class("two", "")
       .into_commander().unwrap();

assert_eq!(cmder.root_name(), "base");

pub fn path(&self) -> &str

Return the path of the current class, separated by ..

Example

let mut cmder = Builder::default_config("base")
       .begin_class("one", "")
       .begin_class("two", "")
       .into_commander().unwrap();

assert_eq!(cmder.path(), "base");
cmder.parse_line("one two", true,  &mut std::io::sink());
assert_eq!(cmder.path(), "base.one.two");

pub fn at_root(&self) -> bool

Returns if the commander is sitting at the root class.

Example

let mut cmder = Builder::default_config("base")
       .begin_class("one", "")
       .begin_class("two", "")
       .into_commander().unwrap();

assert!(cmder.at_root());
cmder.parse_line("one two", true,  &mut std::io::sink());
assert_eq!(cmder.at_root(), false);

pub fn run(self)

Run the Commander interactively. Consumes the instance, and blocks the thread until the loop is exited.

This is the most simple way of using a Commander.

pub fn structure(&self, from_root: bool) -> BTreeSet<StructureInfo>

Returns the command structure as a sorted set.

Can return from the the current class or the root.

Each item is a dot separated path, except for actions which are separated by a double dot.

Examples

let cmder = Builder::default_config("base")
       .begin_class("one", "")
       .begin_class("two", "")
    .end_class()
    .add_action("action", "", |_,_| ())
    .end_class()
    .add_action("action", "", |_,_| ())
       .into_commander().unwrap();

let structure = cmder.structure(true);

assert_eq!(structure.iter().map(|x| x.path.as_str()).collect::<Vec<_>>(), vec![
    "..action",
    "one",
    "one..action",
    "one.two",
]);