clap-validators

Linux: Windows:

Command Line Argument Parser for Rust

It is a simple to use, efficient, and full featured library for parsing command line arguments and subcommands when writing console, or terminal applications.

documentation

Table of Contents

• What's New
• About
• Validators
• Quick Example
• Try it!
  • BYOB (Build Your Own Binary)
• Usage
  • More Information
• How to Contribute
  • Running the tests
• License
• Deprecations

Created by gh-md-toc

What's New

In v0.0.1

New Features

• Default Values: Initial Release!

For full details, see CHANGELOG.md

About

clap-validators are pre-defined functions which can be dropped in to clap argument declarations to perform simple value validations.

Validators

Below are the validators which are included with clap-validators; full descriptions and usage can be found in the documentation and examples/ directory

• clap_validators::numeric
• is_number - Valid i64 or f64

Quick Example

The following examples show a quick example of using clap-validators in combination with clap to perform some basic validation of arguments.

extern crate clap;
extern crate clap_validators;

use clap::{Arg, App};
use clap_validators;

fn main() {
   let matches = App::new("My Super Program")
                         .arg(Arg::with_name("infile")
                              .short("i")
                              .value_name("FILE")
                              .help("Some file to read")
                              .takes_value(true)
                              .validator(clap_validators::fs::is_file))
                         .get_matches();
   // program logic goes here, and we can make the assumption that "infile" is a valid file...
}

If you were to compile any of the above programs and run them with the flag -i <file> where <file> wasn't actually a valid file, one would see the graceful exit of:

$ myprog -i not-a-file
error: not-a-file isn't a valid file

Try it!

To test out clap-validators:

• Create a new cargo project $ cargo new fake --bin && cd fake
• Add clap-validators and clap to your Cargo.toml

[dependencies]
clap = "2"
clap-validators = "0"

• Add the following to your src/main.rs

extern crate clap;
extern crate clap_validators;

use clap::{App, Arg};
use clap_validators;

fn main() {
  let m = App::new("fake")
    .arg(Arg::with_name("infile")
        .required(true)
        .validator(clap_validators::fs::is_file))
    .get_matches();

    println!("success!");
}

• Build your program $ cargo build --release
• Create a file, since we'll be testing if something is a file or not touch myfile
• Run with help or version $ ./target/release/fake myfile
• Or to see this fail, run again with something that is not a file, such as a directory mkdir mydir, ./target/release/fake mydir

Usage

For full usage, add clap-validators as a dependency in your Cargo.toml file to use from crates.io:

[dependencies]
clap_validators = "0"

Or track the latest on the master branch at github:

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

Add extern crate clap_validators; to your crate root.

More Information

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

You can also find usage examples in the examples/ directory of this repo.

How to Contribute

Contributions are always welcome! And there is a multitude of ways in which you can help depending on what you like to do, or are good at. Anything from adding validators, documentation, code cleanup, issue completion, new features, you name it, even filing issues is contributing and greatly appreciated!

Another really great way to help is if you find an interesting, or helpful way in which to use clap-validators. You can either add it to the examples/ directory, or file an issue and tell me. I'm all about giving credit where credit is due :)

Please read CONTRIBUTING.md before you start contributing.

Running the tests

If contributing, you can run the tests as follows (assuming you're in the clap-validators directory)

$ cargo test

# Only on nightly compiler:
$ cargo build --features lints

License

clap-validators is primarily distributed under the terms of both the MIT license and the Apache License (Version 2.0), with portions covered by various BSD-like licenses.

See LICENSE-APACHE, LICENSE-MIT, and COPYRIGHT for details.

Deprecations

Old method names will be left around for several minor version bumps, or one major version bump.

As of 0.0.1:

• None!