Crate cmdr

Cmdr is a library for building line-oriented text-based user interfaces. It lets you focus on writing the implementations of your commands while it handles user interaction, parsing etc.

Out of the box CMDR gives you;

• Command line parsing
• Command history
• Help functions and discoverability
• Auto completion (not yet implemented)

To use CMDR you write the commands you want your user to interact with as functions on one or more Scope types. By implementing the scope trait cmdr can implement and execute your supplied commands. Implementing the Scope trait is as easy by using the supplied cmdr macro and annotating your commands with the cmd annotation to provide useful metadata on your commands. Doc strings in your command will be picked up automatically and used as help text.

use cmdr::*;

/// Example scope that implements two commands, greet and quit
struct GreeterScope {}

#[cmdr]
use cmdr::*;

/// Example scope that implements two commands, greet and quit
struct GreeterScope {}

#[cmdr]
impl GreeterScope {
    /// Cmdr command to greet someone. Takes one parameter and prints a greeting
    #[cmd]
    fn greet(&self, args: &[String]) -> CommandResult {
        println!("Hello {}", args[0]);
        Ok(Action::Done)
    }

    /// Cmdr command to quit the application by returning CommandResult::Quit
    #[cmd]
    fn quit(&self, _args: &[String]) -> CommandResult {
        println!("Quitting");
        Ok(Action::Quit)
    }
}

/// Main function that creates the scope and starts a command loop for it
fn main() -> cmdr::Result<()> {
    cmd_loop(&mut GreeterScope {})?;
    Ok(())
}

More information

• API documentation
• Github repository
• Crates.io
• Release notes

Re-exports

pub use crate::line_writer::LineWriter;

Modules

line_reader

Contains the LineReader trait and several implementations to read lines from several sources

line_writer

Contains the LineWriter trait and some implementations to write lines to several destinations

Structs

Line

A parsed line from the user

Runner

Wraps a LineReader and a Scope and allows using the scope to interpret commands from the LineReader

ScopeCmdDescription

All information about a command method in one handy struct

ScopeDescription

Metadata describing a scope, is used to return help text and the list of commands that this scope exposes.

Enums

Action

Returned by one of the client-implemented command methods to indicate what needs to happen next

Error

Specifies an error while parsing or executing a command

Traits

Scope

Trait for implementing a Scope object. This trait can be implemented directly but will most likely be implemented for you by the cmdr macro.

Functions

cmd_loop

This is the main entry-point to the cmdr library. Creates a LineReader and executes its command on the scope that is passed to it.

Type Aliases

CommandResult

Result type for returning from Command

Result

Default cmdr Result type

Attribute Macros

cmd

Use cmd attribute to mark methods as cmdr commands.

cmdr

Implements the cmdr::Scope trait on any impl block.