pico-args

An ultra simple CLI arguments parser.

• Only flags, options, free arguments and subcommands are supported.
• Arguments can be separated by a space or =.
• Non UTF-8 arguments are supported.
• No help generation.
• No combined flags (like -vvv, -abc or -j1).
• Arguments are parsed in a linear order. From first to last.

Example

```rust struct Args { help: bool, version: bool, number: u32, opt_number: Option, width: u32, free: Vec, }

fn parsewidth(s: &str) -> Result { s.parse().maperr(|| "not a number".tostring()) }

fn main() -> Result<(), Box> { let mut args = picoargs::Arguments::fromenv(); // Arguments can be parsed in any order. let args = Args { // You can use a slice for multiple commands help: args.contains(["-h", "--help"]), // or just a string for a single one. version: args.contains("-V"), // Parses an optional value that implements FromStr. number: args.optvaluefromstr("--number")?.unwrapor(5), // Parses an optional value that implements FromStr. optnumber: args.optvaluefromstr("--opt-number")?, // Parses an optional value using a specified function. width: args.optvaluefromfn("--width", parsewidth)?.unwrap_or(10), // Will return all free arguments or an error if any flags are left. free: args.free()?, };

Ok(())

} ```

Build features

• eq-separator

  Allows parsing arguments separated by =. Enabled by default.
  This feature adds about 1KiB to the resulting binary.

Alternatives

The core idea of pico-args is to provide some "sugar" for arguments parsing without a lot of overhead (binary or compilation time wise). There are no point in comparing parsing features since pico-args supports only the bare minimum. So we will compare only the size overhead and compilation time.

There are a lot of arguments parsing implementations, but we will use only these one:

• clap - is the most popular and complete one
• gumdrop - a simple parser that uses procedural macros
• structopt - a two above combined
• argh - similar to gumdrop

| | null | pico-args | clap | gumdrop | structopt | argh | |------------------------|---------|-------------|----------|-----------|-------------|-------------| | Binary overhead | 0KiB | 18.6KiB | 379.8KiB | 21.9KiB | 379.6KiB | 17.1KiB | | Build time | 0.1s | 0.5s | 5.4s | 7.7s | 15.3s | 6.0s | | Number of dependencies | 0 | 0 | 12 | 5 | 25 | 12 | | Tested version | - | 0.3.3 | 2.33.1 | 0.8.0 | 0.3.14 | 0.1.3 |

• Binary size overhead was measured by subtracting the .text section size of an app with arguments parsing and a hello world app.
• Build time was measured using hyperfine 'cargo clean; cargo build --release'.
• Test projects can be found in test-apps/.

License

MIT