README.md
1## pico-args
2
3[](https://crates.io/crates/pico-args)
4[](https://docs.rs/pico-args)
5[](https://www.rust-lang.org)
6
7
8An ultra simple CLI arguments parser.
9
10If you think that this library doesn't support some feature, it's probably intentional.
11
12- No help generation.
13- Only flags, options, free arguments and subcommands are supported.
14- Options can be separated by a space, `=` or nothing. See build features.
15- Arguments can be in any order.
16- Non UTF-8 arguments are supported.
17
18### Build features
19
20- `eq-separator`
21
22 Allows parsing arguments separated by `=`. Enabled by default.<br/>
23 This feature adds about 1KiB to the resulting binary.
24
25- `short-space-opt`
26
27 Makes the space between short keys and their values optional (e.g. `-w10`).<br/>
28 If `eq-separator` is enabled, then it takes precedence and the '=' is not included.<br/>
29 If `eq-separator` is disabled, then `-K=value` gives an error instead of returning `"=value"`.<br/>
30 The optional space is only applicable for short keys because `--keyvalue` would be ambiguous.
31
32- `combined-flags`
33
34 Allows combination of flags, e.g. `-abc` instead of `-a -b -c`. If `short-space-opt` or `eq-separator` are enabled, you must parse flags after values, to prevent ambiguities.
35
36### Alternatives
37
38The core idea of `pico-args` is to provide some "sugar" for arguments parsing without
39a lot of overhead (binary or compilation time wise).
40There are no point in comparing parsing features since `pico-args` supports
41only the bare minimum. So we will compare only the size overhead and compilation time.
42
43There are a lot of arguments parsing implementations, but we will use only these one:
44
45- [clap](https://crates.io/crates/clap) - is the most popular and complete one
46- [gumdrop](https://crates.io/crates/gumdrop) - a simple parser that uses procedural macros
47- [structopt](https://crates.io/crates/structopt) - a two above combined
48- [argh](https://crates.io/crates/argh) - similar to gumdrop
49
50| | null | `pico-args` | `clap` | `gumdrop` | `structopt` | `argh` |
51|------------------------|---------|-------------|----------|-----------|-------------|---------|
52| Binary overhead | 0KiB | **14.3KiB** | 373.0KiB | 19.8KiB | 371.4KiB | 17.6KiB |
53| Build time | 0.4s | **0.7s** | 5.6s | 4.1s | 6.2s | 4.0s |
54| Number of dependencies | 0 | **0** | 8 | 5 | 20 | 8 |
55| Tested version | - | 0.4.0 | 2.33.3 | 0.8.0 | 0.3.21 | 0.1.4 |
56
57- Binary size overhead was measured by subtracting the `.text` section size of an app with
58 arguments parsing and a hello world app.
59- Build time was measured using `hyperfine 'cargo clean; cargo build --release'`.
60- Test projects can be found in `test-apps/`.
61
62### License
63
64MIT
65
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}