[−][src]Module clapme::guide

A user's guide for clapme.

ClapMe allows you to parse command line arguments by defining a struct. It combines clap with custom derive.

The basic idea is that you define a type that represents the information you want on the command-line from the person running your program, and derive(ClapMe) on that type, and then call YourType::from_args() to find out what your user gave you. To begin with, let's look at an example of how you might actually use ClapMe in a real program.

#[macro_use]
extern crate clapme;
 
use std::path::PathBuf;
use clapme::ClapMe;
 
#[derive(Debug, ClapMe)]
struct Opt {
/// Filling fraction
filling_fraction: f64,
/// Number of atoms
N: u32,
/// Output directory, working directory if not present
dir: Option<PathBuf>,
/// Activate verbose printing
verbose: bool,
}
 
fn main() {
let opt = Opt::from_args();
println!("{:?}", opt);
}

The remainder of this guide will give examples of how the command-line flags are constructed from your type, starting with simple cases and moving gradually to more complex ones. In no case does your code involve more than defining a type, deriving ClapMe and calling the from_args method of your type. I want to note that ClapMe almost always produces long flags. This is because I feel that long flags are generally the easiest to use. If you want to fine-tune your command-line interface, ClapMe may not be for you.

Just a flag

Most often, you will define a struct as your type. We'll start out with the simplest case, which is a single boolean field within that struct.

struct Foo {
    foo: bool,
}

This gives the following usage.

ⓘThis example is not tested
foo 
 
USAGE:
    foo [FLAGS]
 
FLAGS:
        --foo

A single boolean flag is treated as an optional flag.

Adding help information

We add help information simply by adding ordinary doc comments to our struct.

struct Help {
    /// Print excess messages.
    verbose: bool,
    /// The temperature.
    T: bool,
}

This gives the following usage.

ⓘThis example is not tested
help 
 
USAGE:
    help [FLAGS]
 
FLAGS:
        --T          The temperature.
        --verbose    Print excess messages.

I would always documentation for actual projects, so I'll try to model that here, even though these examples are all fictitious.

How the flag is determined

We saw above that the flag just had -- prepended to the field name. The rule in general is only slightly more complicated: every underscore is replaced with a -.

struct Flags {
    /// a simple word has "--" prepended to it.
    verbose: bool,
    /// Underscores are replaced with "-" ...
    blue_is_nice_: bool,
    /// and capital letters are preserved.
    min_T: bool,
}

This gives the following usage.

ⓘThis example is not tested
flags 
 
USAGE:
    flags [FLAGS]
 
FLAGS:
        --blue-is-nice-    Underscores are replaced with "-" ...
        --min-T            and capital letters are preserved.
        --verbose          a simple word has "--" prepended to it.

Thus you can create most any flag name you care for, and it is easy to tell which flag corresponds to which field in your struct.

Other types

You can add most standard library types to your struct, basically anything that can be read or parsed from a &str. I'd recommend sticking to owned types.

struct Types {
    /// The name of the type
    name: String,
    /// The temperature of the type
    T: f64,
    /// The place where it is
    directory: std::path::PathBuf,
}

This gives the following usage.

ⓘThis example is not tested
types 
 
USAGE:
    types --T <FLOAT> --directory <PATH> --name <STRING>
 
OPTIONS:
        --T <FLOAT>           The temperature of the type
        --directory <PATH>    The place where it is
        --name <STRING>       The name of the type

I should note that integer types do allow their value to be specified using scientific notation, as in 1e6 rather than 1000000. This is in different from rust's FromStr implementation. ClapMe does reject floating point values that cannot be reversibly converted to the integer type that is requested.

Furthermore, when providing numerical user input, users may specify an expression such as 1/3 or sqrt(2). This is most useful for floating point input where makes it easier to give high-precision input when needed, but may also be helpful for integers.

Optional flags

In the previous examples, every flag (except a bool flag) was required to be specified by the user. If you want a flag to be optional, you just use the standard Option type.

struct Optional {
    /// The name is an optional argument.
    name: Option<String>,
}

This gives the following usage.

ⓘThis example is not tested
optional 
 
USAGE:
    optional [OPTIONS]
 
OPTIONS:
        --name <STRING>    The name is an optional argument.

The value is then None if the user did not specify that flag.

Exclusive flags

If you want to make certain flags/values mutually exclusive, you use an enum (just as always, in rust).

enum Exclusive {
    /// In this context, the doc comment for the variant is not
    /// used by clapme.
    First {
        /// This is the "a" value
        a: String,
        /// This is the "b" value, which you cannot specify unless
        /// you also specify the "a" value.
        /// Only one line of comment shows up in the help.
        b: String,
    },
    /// A string that cannot be used with any other flag
    SecondFlag(String),
    /// A flag with no value, and with a capital letter.
    Third_,
}

This gives the following usage.

ⓘThis example is not tested
exclusive 
 
USAGE:
    exclusive [FLAGS] --Third --first-a <STRING> --first-b <STRING> --second-flag <STRING>
 
FLAGS:
        --Third    A flag with no value, and with a capital letter.
 
OPTIONS:
        --first-a <STRING>        This is the "a" value
        --first-b <STRING>        Only one line of comment shows up in the help.
        --second-flag <STRING>    A string that cannot be used with any other flag

This example illustrates the three kinds of enum variants. Sadly, the help message does not indicate that these flags are exlusive. However, if a user tries to specify both --third and --second FOO, however, they will get a nice error message. Note that you cannot use a tuple variant with more than one field. Note that the rules for constructing flags from enum variants are more complicated than for struct fields. This is because by convention variants are given CamelCase names, which aren't suitable as flags. If a variant name contains an underscore, then it is treated like a field name (as described above), with any trailing underscores removed. Otherwise the name is converted from CamelCase to kebab-case.

Nesting types

You can use any ClapMe type as a field within a struct or enum. Doing so will give flag names that combine the nested field names.

ⓘThis example is not tested
#[derive(ClapMe)]
/// I'm not putting doc-comments on `x` and `y`, because clapme
/// would give the same help message for `--position-x` as for
/// `--velocity-x`, which would be pretty useless.
struct Vec2d {
    x: f64, y: f64,
}
#[derive(ClapMe)]
struct Nested {
    /// We would like for this to be the help for both components
    /// of the position, but clapme is not that clever.  Ideally
    /// the help should read something like: the x component of
    /// the position/velocity, but that would require combining
    /// information at multiple levels and sounds hard.
    position: Vec2d,
    velocity: Vec2d,
}

This gives the following usage.

ⓘThis example is not tested
nested 
 
USAGE:
    nested --position-x <FLOAT> --position-y <FLOAT> --velocity-x <FLOAT> --velocity-y <FLOAT>
 
OPTIONS:
        --position-x <FLOAT>    
        --position-y <FLOAT>    
        --velocity-x <FLOAT>    
        --velocity-y <FLOAT>

Flattened nesting types

As you say in the last example, nesting types allows you to make your own complex types that can be reused. Sometimes, however, you would like to nest structs for a different reason: to separate concerns in the code. In this case, you may not want the nesting to be visible in the user interface. This can be acheived with a leading underscore on a field name. The catch is that when you do this, you could run into a runtime error if you have duplicate field names.

ⓘThis example is not tested
#[derive(ClapMe)]
struct MyConfig {
    /// The user's name
    name: String,
}
#[derive(ClapMe)]
struct YourConfig {
    /// The user's address
    address: String,
}
#[derive(ClapMe)]
struct Flattened {
    _mine: MyConfig,
    _yours: YourConfig,
}

This gives the following usage.

ⓘThis example is not tested
flattened 
 
USAGE:
    flattened --address <STRING> --name <STRING>
 
OPTIONS:
        --address <STRING>    The user's address
        --name <STRING>       The user's name

This may be a good idea if MyConfig and YourConfig are implementation details that your user need not be aware of.

Other possibilities

There may be a few other features that clapme has, for which I have not bothered to create an entire example. I will list them here when they come to mind.

  1. You can use a Vec<T> for many values of T to create an option that can be specified more than once.

Conclusion

There is more that could be said and more possible examples, but I think this is enough to get you started using ClapMe. The intent is that any reasonable type that can be obtained from one or more strings should work with clapme. Please fill an issue on github if there is a type that you would like to have supported by clapme. Pull requests are most welcome.