clap

Fast. Configurable. Argument Parsing for Rust



About


clap or Command Line Argument Parser

Is a simple-to-use, efficient, and fully-configurable library for parsing command line arguments.

clap supports advanced features like argument relationships, subcommands, and much, much more.


A Quick Taste

The following Rust code is all it takes to get started:

    extern crate clap;
    use clap::App;

    fn main() {
        App::new("myapp")
            .version("1.0")
            .about("Does great things!")
            .author("Kevin K.")
            .get_matches();
    }

If the user runs $ myapp --help the following would be printed

myapp 1.0
Kevin K.
Does great things!

USAGE:
    myapp [FLAGS]

FLAGS:
    -h, --help       Prints this message
    -V, --version    Prints version information

Fast

clap aims to be extremely fast and efficient. Arguments will be parsed without wasting CPU cycles or hogging memory.

Because let’s face it, your application is the star of the show!

Configurable

clap is fully configurable, yet still has common defaults for those applications that simply want be up and running in no time.

Utilizing clap gives you ability to have a truly custom experience, an extremely simple solution, and anything in between.

Easy to Use

clap is extremely easy and intuitive to use.

In fact, it’s so intuitive that all you may need is a completer engine (such as racer), it’s really that simple! However, after a quick glance at our API documentation you’ll be up and running, even using advanced features in no time!

Here’s a quick example of an application that provides a single option (--config <file>) which requires a value, and must be used at runtime. (Note this simple example even handles automatic help generation, context sensitive errors, and more!)

App::new("myapp")
    .version("1.0")
    .author("Kevin K.")
    .about("Does awesome things!")
    .arg(Arg::with_name("cfg")
        .help("The configuration file to use")
        .long("config")
        .short("c")
        .takes_value(true)
        .required(true))
    .get_matches();

Standard Argument Types

clap supports all standard argument types, flags/switches, options, free/positional arguments, and even subcommands! Here’s some extra information about special features clap supports

  • Both short and long versions supported (-f and --flag respectively)
  • Combining short versions (-fBgoZ same as -f -B -g -o -Z)
  • Multiple occurrences (-vvv same as -v -v -v)
  • Multiple values ($ myprog <file>...)
  • Value parameters (i.e. minimum, maximum, or the exact number of values)
  • Default and specific value sets
  • All standard short and long versions of options (-o value, -ovalue, -o=value and --option value or --option=value respectively)
  • Argument relationships, such as requires, conflicts with, overrides, etc. This allows you to be absolutely certain the invocation is correct!
  • Fully configurable subcommands with their own sub-arguments, and sub-sub-commands independent of the parent
  • Their own auto-generated Help, Version, and Usage independent of parent

Auto-Generated Help

clap generates your help message and usage strings for you automatically from the list of valid arguments you provide, this includes the common --help and --version switches. This means no more out of sync help messages!

Full help message templating is also supported for the best of both worlds, where you want to stay up to date and provide a custom message.

Supports YAML

You can define your list of valid arguments in a YAML file, keeping your main.rs clean and tidy.

Auto-Generates Completions

clap can generate bash, fish, zsh and even PowerShell completion files at compile time! These can then be installed alongside your application giving full shell tab-completions of all flags, options, subcommands and even specific argument values!

Friendly Errors

clap generates friendly, and informative error messages. These messages kindly inform the end user of ways in which to correct the error. clap will even give a context sensitive usage string suggestion to the user!

Suggestions

If the end user has a typo, clap will gently suggest a correction based on the current context.

If the user enters --confg, but --config is most likely what they meant to type, clap will inform them and suggest the correct argument. This extends to subcommands and even specific argument values!

Argument Relationships

One can define argument relationships easily, and intuitively. This includes everything from requirements, conflicts, and overrides. For instance, if one argument requires another to be used, this can be specified. If another argument cannot be used any particular other, that can be defined as well.

These relationships can span from simply conflicts and requirements, to POSIX compatible overrides, to multiple grouped and nested layers of complexity. Each of these settings can even be applied conditionally!

Argument Groups

clap supports grouping arguments into logical groups, this can vastly assist with things such as complex relationships

Much, Much More!

clap supports much, much more than these short few bullet points. Delve into the many resources, or contact us to find out more!

Stay In Touch: