getopt3 - command line argument parser for Rust

Version 2.6.1 MIT Licensed

Features

1. GNU argument parsing rules: Options can be anywhere on the 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. -abcpasta is the same as -a -b -c pasta
5. Argument does not require space. -wfile is the same as -w file
6. Parsing fails only if optstring is invalid.

Code quality

1. Low MSRV 1.56, compatible with the entire Rust 2021 Edition.
2. Rust port of the well tested Scala getopt code.
3. Small code footprint: only 228 LOC.
4. Zero dependencies.
5. No unsafe Rust.
6. 70 unit tests, 8 integration tests, and 8 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 that can be converted to Iterator over String. You can use std::env::args() but you need to skip the first argument because it's the executable name. It can be done manually by .skip(1) or by calling hideBin utility function which strips the first argument.
2. optstring is 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.
4. If required argument is missing function new() won't fail. Call validate() on parsed result for optional argument checking.

2. Check parsed options

getopt structure returned by constructor has following public members:

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

Structure getopt supports IntoIterator and can transform itself into Iterator over supplied command line arguments. It supports consuming itself or use self immutable reference for enumerating arguments.

getopt.iter() returns Iterator command line arguments without consuming itself. It is a convenience shortcut for getopt.arguments.iter().

getopt.len() returns number of command line arguments. It is a convenience shortcut for getopt.arguments.len().

getopt.get() returns value of command line option. It is a convenience shortcut for getopt.options.get().

getopt.has() returns if option got supplied on command line. It is a convenience shortcut for getopt.options.contains_key().

getopt[usize] returns nth command line argument. It is a convenience shortcut for getopt.arguments.index().

getopt.is_empty() returns if any arguments were supplied on command line. It is a convenience shortcut for getopt.arguments.is_empty().

3. Optional - Check if correct options were provided

You can run strict parse checks 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 were encountered or required arguments are missing.

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 function.
4. FreeBSD getopt function.
5. NetBSD getopt function.

Known getopt extensions

Fully implemented

1. GNU getopt parsing rules.
   1. Options can be anywhere in command line before --
   2. double dash -- support. Anything after -- is not treated as options.
2. POSIX extension in the getopt function where the argument string specification can start with a colon (:).
   1. 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 an option because it's possible to spot the difference between an unknown option and the -? option.
   2. The extension is implemented in a way that '?' as option is always supported. ':' at start of option string is fully optional and have no effect on activating this extension.
   3. We never print any error messages during parsing even if option string is invalid and parsing fails.

Not 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. 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.
3. If the first character of optstring is a '-', non-option parameters are outputted at the place where they are found. In normal operation, they are all collected at the end of output after a '--' parameter has been generated. Note that this '--' parameter is still generated, but it will always be the last parameter in this mode.

Possible future developments

Some code for these features exists, but development is paused.

Partially implemented code is not compiled in during normal build and can't be enabled in stock crate using features.

1. no_std Rust version in development.
2. posix strict mode. First non option stops option parsing. This is needed for parsing nested command lines.