README.md
1## pico-args
2[](https://travis-ci.org/RazrFalcon/pico-args)
3[](https://crates.io/crates/pico-args)
4[](https://docs.rs/pico-args)
5[](https://www.rust-lang.org)
6
7An ultra simple CLI arguments parser.
8
9- Only flags, options, free arguments and subcommands are supported.
10- Arguments can be separated by a space or `=`.
11- Non UTF-8 arguments are supported.
12- No help generation.
13- No combined flags (like `-vvv`, `-abc` or `-j1`).
14- Arguments are parsed in a linear order. From first to last.
15
16### Example
17
18```rust
19struct Args {
20 help: bool,
21 version: bool,
22 number: u32,
23 opt_number: Option<u32>,
24 width: u32,
25 free: Vec<String>,
26}
27
28fn parse_width(s: &str) -> Result<u32, String> {
29 s.parse().map_err(|_| "not a number".to_string())
30}
31
32fn main() -> Result<(), Box<dyn std::error::Error>> {
33 let mut args = pico_args::Arguments::from_env();
34 // Arguments can be parsed in any order.
35 let args = Args {
36 // You can use a slice for multiple commands
37 help: args.contains(["-h", "--help"]),
38 // or just a string for a single one.
39 version: args.contains("-V"),
40 // Parses an optional value that implements `FromStr`.
41 number: args.opt_value_from_str("--number")?.unwrap_or(5),
42 // Parses an optional value that implements `FromStr`.
43 opt_number: args.opt_value_from_str("--opt-number")?,
44 // Parses an optional value using a specified function.
45 width: args.opt_value_from_fn("--width", parse_width)?.unwrap_or(10),
46 // Will return all free arguments or an error if any flags are left.
47 free: args.free()?,
48 };
49
50 Ok(())
51}
52```
53
54### Build features
55
56- `eq-separator`
57
58 Allows parsing arguments separated by `=`. Enabled by default.<br/>
59 This feature adds about 1KiB to the resulting binary.
60
61### Alternatives
62
63The core idea of `pico-args` is to provide some "sugar" for arguments parsing without
64a lot of overhead (binary or compilation time wise).
65There are no point in comparing parsing features since `pico-args` supports
66only the bare minimum. So we will compare only the size overhead and compilation time.
67
68There are a lot of arguments parsing implementations, but we will use only these one:
69
70- [clap](https://crates.io/crates/clap) - is the most popular and complete one
71- [gumdrop](https://crates.io/crates/gumdrop) - a simple parser that uses procedural macros
72- [structopt](https://crates.io/crates/structopt) - a two above combined
73- [argh](https://crates.io/crates/argh) - similar to gumdrop
74
75| | null | `pico-args` | `clap` | `gumdrop` | `structopt` | `argh` |
76|------------------------|---------|-------------|----------|-----------|-------------|-------------|
77| Binary overhead | 0KiB | 18.6KiB | 379.8KiB | 21.9KiB | 379.6KiB | **17.1KiB** |
78| Build time | 0.1s | **0.5s** | 5.4s | 7.7s | 15.3s | 6.0s |
79| Number of dependencies | 0 | **0** | 12 | 5 | 25 | 12 |
80| Tested version | - | 0.3.3 | 2.33.1 | 0.8.0 | 0.3.14 | 0.1.3 |
81
82- Binary size overhead was measured by subtracting the `.text` section size of an app with
83 arguments parsing and a hello world app.
84- Build time was measured using `hyperfine 'cargo clean; cargo build --release'`.
85- Test projects can be found in `test-apps/`.
86
87### License
88
89MIT
90
){kind=link}
){kind=link}
){kind=link}
){kind=link}