Struct bpaf::Parser

pub struct Parser<T> { /* private fields */ }

Simple or composed argument parser

Implementations

impl<T> Parser<T>

pub fn pure(val: T) -> Parser<T> where
    T: 'static + Clone, 

Wrap a value into a Parser

Parser will produce T without consuming anything from the command line, can be useful with construct!.

let a = long("flag-a").switch();
let b = Parser::pure(42u32);
let t: Parser<(bool, u32)> = construct!(a, b);

pub fn or_else(self, other: Parser<T>) -> Parser<T> where
    T: 'static, 

If first parser fails - try the second one

let a = short('a').switch();
let b = short('b').switch();

// Parser will accept either `-a` or `-b` on a command line but not both at once.
let a_or_b: Parser<bool> = a.or_else(b);

Performance

If first parser succeeds - second one will be called anyway to produce a better error message for combinations of mutually exclusive parsers:

Suppose program accepts one of two mutually exclusive switches -a and -b and both are present error message should point at the second flag

pub fn fail<M>(msg: M) -> Parser<T> where
    String: From<M>,
    M: Clone + 'static, 

Fail with a fixed error message

let a = short('a').switch();
let no_a = Parser::fail("Custom error message for missing -a");

// Parser will produce a custom error message if `-a` is not specified
let a_: Parser<bool> = a.or_else(no_a);

pub fn many(self) -> Parser<Vec<T>> where
    T: 'static, 

Consume zero or more items from a command line

// parser will accept multiple `-n` arguments:
// `-n 1, -n 2, -n 3`
// and return all of them as a vector which can be empty if no `-n` specified
let n: Parser<Vec<u32>> = short('n').argument("NUM").from_str::<u32>().many();

Panics

Panics if parser succeeds without consuming any input: any parser modified with many must consume something,

pub fn guard<F>(self, m: F, message: &'static str) -> Parser<T> where
    F: Fn(&T) -> bool + 'static,
    T: 'static, 

Validate or fail with a message

let n = short('n').argument("NUM").from_str::<u32>();
// Parser will reject values greater than 10
let n = n.guard(|v| *v <= 10, "Values greater than 10 are only available in the DLC pack!");

pub fn some(self) -> Parser<Vec<T>> where
    T: 'static, 

Consume one or more items from a command line

// parser will accept multiple `-n` arguments:
// `-n 1, -n 2, -n 3`
// and return all of them as a vector. At least one `-n` argument is required.
let n: Parser<Vec<u32>> = short('n').argument("NUM").from_str::<u32>().some();

pub fn optional(self) -> Parser<Option<T>> where
    T: 'static + Clone, 

Turn a required parser into optional

let n: Parser<u32> = short('n').argument("NUM").from_str();
// if `-n` is not specified - parser will return `None`
let n: Parser<Option<u32>> = n.optional();

pub fn map<F, B>(self, map: F) -> Parser<B> where
    F: Fn(T) -> B + 'static,
    T: 'static, 

Apply a pure transformation to a contained value

let n: Parser<u32> = short('n').argument("NUM").from_str();
// produced value is now twice as large
let n = n.map(|v| v * 2);

pub fn parse<F, B, E>(self, map: F) -> Parser<B> where
    F: Fn(T) -> Result<B, E> + 'static,
    T: 'static,
    E: ToString, 

Apply a failing transformation

See also from_str

let s: Parser<String> = short('n').argument("NUM");
// Try to parse String into u32 or fail during the parsing
use std::str::FromStr;
let n = s.map(|s| u32::from_str(&s));

pub fn fallback(self, val: T) -> Parser<T> where
    T: Clone + 'static, 

Use this value as default if value is not present on a command line

Would still fail if value is present but failure comes from some transformation

let n = short('n').argument("NUM").from_str::<u32>().fallback(42);

pub fn fallback_with<F, E>(self, val: F) -> Parser<T> where
    F: Fn() -> Result<T, E> + Clone + 'static,
    E: ToString,
    T: Clone + 'static, 

Use value produced by this function as default if value is not present

Would still fail if value is present but failure comes from some transformation

let n = short('n').argument("NUM").from_str::<u32>();
let n = n.fallback_with(|| Result::<u32, String>::Ok(42));

pub fn default(self) -> Parser<T> where
    T: Default + 'static + Clone, 

Parse T or fallback to T::default()

let n = short('n').argument("NUM").from_str::<u32>().default();

pub fn group_help(self, msg: &'static str) -> Parser<T>

Attach help message to a complex parser

let width = short('w').argument("PX").from_str::<u32>();
let height = short('h').argument("PX").from_str::<u32>();
let rect = construct!(width, height).group_help("take a rectangle");

See examples/rectangle.rs for a complete example

impl Parser<String>

pub fn from_str<T>(self) -> Parser<T> where
    T: FromStr,
    <T as FromStr>::Err: Display, 

Parse stored String using FromStr instance

let speed = short('s').argument("SPEED").from_str::<f64>();
// at this point program would accept things like "-s 3.1415"
// but reject "-s pi"

Trait Implementations

impl<T: Clone> Clone for Parser<T>

fn clone(&self) -> Parser<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.