No description
Find a file
2015-03-20 14:11:19 -04:00
docs Inc'ed version after PR #15 and #16 - fixed formatting error in examples 2015-03-18 22:00:01 -04:00
examples Added SubCommand examples 2015-03-20 15:06:44 -04:00
src Remove assertion on multi args. 2015-03-19 00:26:50 -04:00
.gitignore Updated readme and removed Cargo.lock from git 2015-02-28 19:31:24 -05:00
.travis.yml Adding .travis.yml file 2015-03-01 15:46:46 -05:00
Cargo.toml Excluded examples/ 2015-03-20 14:11:19 -04:00
index.html Added redirect for base gh-pages url to real docs url 2015-03-15 21:55:24 -04:00
LICENSE-MIT Re-release under MIT license 2015-03-02 10:10:23 -05:00
Makefile Inc'ed version after PR #21 - doc copy commands to Makefile 2015-03-19 07:55:33 -04:00
README.md Add build instructions 2015-03-19 00:45:30 +01:00

clap

Travis-CI

Command Line Argument Parser written in Rust

A simply library for parsing command line arguments and subcommands when writing command line and console applications.

You can use clap to lay out a list of possible valid command line arguments and subcommands, then let clap parse the string given by the user at runtime.

When using clap you define a set of parameters and rules for your arguments and subcommands, then at runtime clap will determine their validity.

clap also provides the traditional version and help switches 'for free' by parsing the list of possible valid arguments lazily at runtime, and if not already defined by the developer clap will autogenerate all applicable "help" and "version" switches (as well as a "help" subcommand if other subcommands are defined as well).

After defining a list of possible valid arguments and subcommands, clap gives you a list of valid matches that the user supplied at runtime, or informs the user of their error and exits gracefully. You can use this list to determine the functioning of your program.

Quick Example

// (Full example with comments in examples/myapp.rs)
extern crate clap;
use clap::{Arg, App, SubCommand};

fn main() {
    let matches = App::new("MyApp")
                          .version("1.0")
                          .author("Kevin K. <kbknapp@gmail.com>")
                          .about("Does awesome things")
                          .arg(Arg::new("config")
                               .short("c")
                               .long("config")
                               .help("Sets a custom config file")
                               .takes_value(true))
                          .arg(Arg::new("output")
                               .help("Sets an optional output file")
                               .index(1))
                          .arg(Arg::new("debug")
                               .short("d")
                               .multiple(true)
                               .help("Turn debugging information on"))
                          .subcommand(SubCommand::new("test")
                                      .about("controls testing features")
                                      .arg(Arg::new("verbose")
                                          .short("v")
                                          .help("print test information verbosely")))
                          .get_matches();

    if let Some(o) = matches.value_of("output") {
        println!("Value for output: {}", o);
    }

    if let Some(c) = matches.value_of("config") {
        println!("Value for config: {}", c);
    }

    match matches.occurrences_of("debug") {
        0 => println!("Debug mode is off"),
        1 => println!("Debug mode is kind of on"),
        2 => println!("Debug mode is on"),
        3 | _ => println!("Don't be crazy"),
    }

    if let Some(ref matches) = matches.subcommand_matches("test") {
        if matches.is_present("verbose") {
            println!("Printing verbosely...");
        } else {
            println!("Printing normally...");
        }
    }

    // more porgram logic goes here...
}

If you were to compile the above program and run it with the flag --help or -h (or help subcommand, since we defined test as a subcommand) the following output woud be presented

$ myprog --help
MyApp 1.0
Kevin K. <kbknapp@gmail.com>
Does awesome things

USAGE:
    MyApp [FLAGS] [OPTIONS] [POSITIONAL] [SUBCOMMANDS]

FLAGS:
    -d               Turn debugging information on
    -h,--help        Prints this message
    -v,--version     Prints version information
 
OPTIONS:
    -c,--config <config>        Sets a custom config file

POSITIONAL ARGUMENTS:
    output            Sets an optional output file

SUBCOMMANDS:
    help            Prints this message
    test            Controls testing features

Installation

Add clap as a dependecy in your Cargo.toml file to use from crates.io:

[dependencies]
clap = "*"

Or track the latest on the master branch at github:

[dependencies.clap]
git = "https://github.com/kbknapp/clap-rs.git"

Then run cargo build or cargo update for your project.

Usage

Add extern crate clap; to your crate root.

More Information

You can find complete documentation on the github-pages site for this project.

How to build

Running the tests

cargo test

Building the documentation

Run this instead of cargo doc to generate the proper module docstring:

make doc