getopt3 - cli parser with GNU extension for Rust

Version 2.2.0 MIT Licensed

Features

1. GNU argument parsing rules. Options can be anywhere in command line before --
2. GNU -- extension. Everything after -- is not treated as options.
3. Multiple options not requiring argument can be grouped together. -abc is the same as -a -b -c
4. Argument does not require space. -wfile is same as -w file

Code quality

1. Rust port of well tested Scala getopt code.
2. Small code size.
3. Zero dependencies.
4. No unsafe Rust.
5. Runs on stable Rust.
6. no_std Rust version in development.
7. 52 unit tests + 1 quick check test + 7 integration tests + 2 doc tests.

Usage

1. Create getopt instance

let g = getopt3::new(arguments, optstring)

getopt3::new constructor arguments:

1. arguments command line arguments. Can be anything what can be converted to Iterator over String. You can use std::env::args() but you need to skip first argument because its executable name. It can be done manually or by calling hideBin.
2. optstring is a anything providing AsRef<str>. optstring is containing the legitimate option characters. If such a character is followed by a colon, the option requires an argument.

Returned value:

1. Function returns Result <getopt>.
2. Result wraps parsing errors and getopt structure.
3. Parsing can fail only if optstring is invalid.

2. Check parsed options

getopt structure returned by constructor has following members:

1. arguments : Vec <String> command line arguments with options removed
2. options_map : HashMap <char, bool> map of recognized options. option -> have_argument
3. options : HashMap <char, String> options parsed. If option do not have argument, it is mapped to "" String, otherwise it is mapped to its argument as String.

3. Optional - Check if options are parsed strictly

You can run strictness check by calling validate(getopt) function. This function returns back Result with supplied getopt instance on success or error as String. It can detect if unknown options are encountered or required argument is missing and signal error.

Example usage

  use std::env::args;
  use getopt3::hideBin;

  let rc = getopt3::new(hideBin(args()), "ab:c");
  if let Ok(g) = rc {
     // command line options parsed sucessfully
     if let Some(arg) = g.options.get(&'b') {
        // handle b argument stored in arg
     };
  };

Reference

1. POSIX getopt function.
2. GNU libc getopt function.

To be implemented

1. Two colons in optstring indicates that the argument is optional - this is an extension not covered by POSIX. This will change only validate function because we do not report errors in getopt3::new if required argument is missing.
2. POSIX strict mode. First non option stops option parsing. This is needed for parsing nested command lines.