pub struct Parser<T> { /* private fields */ }
Expand description
Simple or composed argument parser
Implementations
sourceimpl<T> Parser<T>
impl<T> Parser<T>
sourcepub fn pure(val: T) -> Parser<T> where
T: 'static + Clone,
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);
sourcepub fn or_else(self, other: Parser<T>) -> Parser<T> where
T: 'static,
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
sourcepub fn fail<M>(msg: M) -> Parser<T> where
String: From<M>,
M: Clone + 'static,
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);
sourcepub fn many(self) -> Parser<Vec<T>> where
T: 'static,
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,
sourcepub fn guard<F>(self, m: F, message: &'static str) -> Parser<T> where
F: Fn(&T) -> bool + 'static,
T: 'static,
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!");
sourcepub fn some(self) -> Parser<Vec<T>> where
T: 'static,
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();
sourcepub fn optional(self) -> Parser<Option<T>> where
T: 'static + Clone,
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();
sourcepub fn map<F, B>(self, map: F) -> Parser<B> where
F: Fn(T) -> B + 'static,
T: 'static,
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);
sourcepub fn parse<F, B, E>(self, map: F) -> Parser<B> where
F: Fn(T) -> Result<B, E> + 'static,
T: 'static,
E: ToString,
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));
sourcepub fn fallback(self, val: T) -> Parser<T> where
T: Clone + 'static,
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);
sourcepub fn fallback_with<F, E>(self, val: F) -> Parser<T> where
F: Fn() -> Result<T, E> + Clone + 'static,
E: ToString,
T: Clone + 'static,
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));
sourcepub fn default(self) -> Parser<T> where
T: Default + 'static + Clone,
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();
sourcepub fn group_help(self, msg: &'static str) -> Parser<T>
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
Trait Implementations
Auto Trait Implementations
impl<T> !RefUnwindSafe for Parser<T>
impl<T> !Send for Parser<T>
impl<T> !Sync for Parser<T>
impl<T> Unpin for Parser<T>
impl<T> !UnwindSafe for Parser<T>
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more