Crate cmder

A simple, lighweight crate to parse command line arguments. Inspired by its javascript equivalent, commander.js.

This crate is relatively similar in syntax to the said library and is easy to get started with. It presents a builder interface to work with and can easily be extended to suit your needs. The crate only offers a builder interface, no derive features, if you’re looking such features or something more powerful, you should probably check out clap.

Constructs used within the crate include:

• Command, which is exactly what it sounds like
• Program which is a command marked as the entrypoint
• Flags and Options(flags that take arguments)
• Themes that control the color choices used in the program
• Patterns which control how output is formatted on the terminal

The following is a full-fleged example on crate usage:

use cmder::{Program, Event, Setting, Pattern, PredefinedThemes};

let mut program = Program::new();

program
    .author("vndaba")
    .description("An example CLI")
    .version("0.1.0")
    .bin_name("example");

// Subcommands
program
    .subcommand("demo")
    .argument("<value>", "Some required value")
    .alias("d")
    .option("-f", "Some flag")
    .option("-n --name <value>", "Some option")
    .description("A demo subcommand")
    .action(|matches|{dbg!(matches);});

// ...

// Event listeners
program.before_all(|cfg| {
    let p_ref = cfg.get_program();
    println!("This program was authored by: {}", p_ref.get_author())
});

// ...

// Program settings
program.set(Setting::ShowHelpOnAllErrors(true));
program.set(Setting::ChoosePredefinedTheme(PredefinedThemes::Colorful));
program.set(Setting::SetProgramPattern(Pattern::Standard));
program.set(Setting::OverrideAllDefaultListeners(true));

program.parse();

While themes control the color palette used by the program, patterns on the hand control how the output is formatted as shown below:

The default pattern used is the Legacy pattern which is how many CLIs act by default. This is how the output is formatted.

$ cargo r -q --example subcommands -- -h
An example of a program with subcommands

USAGE:
    docker [OPTIONS] <SUBCOMMAND>

FLAGS:
   -v, --version        Print out version information
   -h, --help           Print out help information

SUB-COMMANDS:
   image                A command housing all the subcommands for image functionality
   container            A command housing all subcommands for containers
   help                 A subcommand used for printing out help

This is the default pattern used by the program but can easily be changed by setting the program pattern to a different value.

This will cause output to be formatted as follows:

$ cargo r -q --example subcommands -- -h
An example of a program with subcommands

USAGE:
    docker [OPTIONS] <SUBCOMMAND>

FLAGS:
    -v, --version
      Print out version information
    -h, --help
      Print out help information

SUB-COMMANDS:
    image
      A command housing all the subcommands for image functionality
    container
      A command housing all subcommands for containers
    help
      A subcommand used for printing out help

You can also create your own custom-defined pattern. Refer to the custom_pattern example to see how this can be achieved.

Macros

construct_theme

This macro eases the work of creating a new theme, instead of creating the theme struct yourself, you can use the macro to do so. The macro receives all the desired colors. Do note that the order in which you place your colors is important.

Structs

Argument

CmderFlag

CmderOption

Command

The gist of the crate. Create instances of the program struct to chain to them all available methods. Event the program created is itself a command.

CustomPattern

EventEmitter

The event emitter struct simply contains a listeners field which is a vector containing a tuple with the structure: (EventListener, index_of_execution).

Formatter

ParserMatches

Program

Similar to the Command struct except commands created via the Program::new() method are marked as the root command and also contain the version flag automatically. Exists due to maintain some familiarity with earlier versions of the crate

Theme

A simple struct containing the color palette to be used by the formatter when writing to standard output. It contains various fields each referring to a color variant to be used to print a specific value. Each of these values can be mapped to values in the Designation struct which is simply a fancy way of referring to what role a string value is assigned to.

Enums

Color

The set of available colors for the terminal foreground/background.

Designation

Event

Pattern

PredefinedThemes

Contains a few predefined themes that can be set to the program

Setting