Expand description
Fcla lets you create a “functional” command line argument parser in minutes.
Simply start by creating an Args
type, then annotate your types with #[derive(FromArgs)]
, before finally using the parse_cla
function to parse your arguments.
Ideal for small projects and rapid development.
§Example
The following example shows off most of what fcla
can do:
use fcla::FromArgs;
#[derive(Debug, FromArgs)]
enum Args {
Simple { first: Box<str>, second: i32 },
Nested { nested: Nested },
Optional { optional: Option<Box<str>> },
Sequence { sequence: Vec<i32> },
Mapping { map: std::collections::HashMap<i32, Box<str>> },
Range { range: fcla::RangeDynamic<i32> },
Custom { tree: Tree<Box<str>> },
Complex { sequence: Vec<Tree<Box<str>>> },
}
#[derive(Debug, FromArgs)]
struct Nested {
small: u8,
medium: u16,
large: u32,
}
#[derive(Debug, FromArgs)]
enum Tree<T> {
Root(T),
Branch { left: Box<Self>, right: Box<Self> },
}
fn main() -> fcla::MainResult<()> {
let args = fcla::parse_cla::<Args>()?.args;
println!("{:?}", args);
Ok(())
}
You can run it with the following arguments:
Simple 'hello world' -1
Nested 128 32768 2147483648
Optional , word
Optional .
Sequence , 1 , -1 , 1E3 , -0.1E4 .
Mapping , 4 four , 3 three , 2 two , 1 one .
Range ,, 0 10
Range .,= 10
Custom Branch Branch Root hello Root world Branch Root from Branch Root fcla Root .
Complex , Branch Root nested Root types , Root example .
§Grammar
Fcla’s grammar can be broken into four main parts.
§Derives
Derived structs are parsed by parsing their fields in the order that they’re declared in.
Derived enums are parsed by matching the first argument against the enum’s variant names and then parsing the rest of the arguments into the corresponding variant struct.
§Collections
Collections are parsed as a sequence of Option<T>
s with zero or more Some
s terminated by a None
.
Some
is parsed as ,
and None
is parsed as .
.
Lists and sets are composed of T
s whilst mappings are composed of KeyValue<K, V>
.
See the Args::as_iter
method for more details.
§Numbers
Numbers are parsed using the same grammar as floats FromStr
implementation but with the removal of the infinity and NaN cases.
This means that 0.1e1
will successfully parse into a u32
.
See the num
module for more details.
§Bespoke
Bespoke types (such as IpAddr
) are parsed according to some external grammar (for standard library types this is usually their FromStr
implementations).
Modules§
- Utilities for parsing numeric types.
Structs§
- Remaining unparsed arguments.
- Wrapper around command line arguments.
- Error parsing command line arguments.
- Error parsing a specific argument.
- Key value pair.
- Error parsing an unparsed argument into a type.
Enums§
- Struct field identifier.
- Error returned from
main
. - Error parsing environment.
- Dynamically bounded range.
Traits§
- Types that can be parsed from types that can be parsed from
Args
. - Types that can be parsed from
Args
. - Types that can be used as a source for
Args
.
Functions§
- Convenience function for calling
FromArgs::from_args
. - Parse arguments.
- Parse arguments from the environment assuming that they’re from the command line.
- Parse arguments from the environment.
Type Aliases§
- Alias for
Result<T, FromArgsError>
. - Alias for
Result<(), MainError<E>>
. - Alias for
Result<T, ParseError>
.
Derive Macros§
FromArgs
derive macro.