1## pico-args 2[![Build Status](https://travis-ci.org/RazrFalcon/pico-args.svg?branch=master)](https://travis-ci.org/RazrFalcon/pico-args) 3[![Crates.io](https://img.shields.io/crates/v/pico-args.svg)](https://crates.io/crates/pico-args) 4[![Documentation](https://docs.rs/pico-args/badge.svg)](https://docs.rs/pico-args) 5[![Rust 1.31+](https://img.shields.io/badge/rust-1.31+-orange.svg)](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