getopt3 - cli parser with GNU extension for Rust

Version 2.3.0 MIT Licensed

Features

1. GNU argument parsing rules. Options can be anywhere in command line before --
2. double dash -- support. Anything after -- is not treated as options.
3. Multiple options not requiring argument can be chained together. -abc is the same as -a -b -c
4. Last chained option can have an argument.
5. 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. 66 unit tests + 1 quick check test + 8 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 utility function which strips first argument.
2. optstring is a anything providing AsRef<str>. optstring is containing the legitimate option characters. Valid option characters are alphanumeric plus '?'. 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 correct options were provided

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

  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.
3. OpenBSD getopt
4. FreeBSD getopt

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.
3. nostd support
4. there is an extension in the getopt function specified in POSIX where the argument string specification can start with a colon (:). When the option string begins with a colon, it modifies the behavior of getopt to handle error cases differently. Specifically, it suppresses the default error messages that getopt prints when it encounters an unrecognized option or a missing argument, and it returns : instead of ? for these error cases. This allows using ? as option because its possible to spot difference unknown option / -? option.
5. In GNU getopt, if the option string (optstring) begins with a + character, it triggers POSIX-compatible parsing. This means that the first non-option argument will stop option parsing, similar to how setting the POSIXLY_CORRECT environment variable behaves.