getopt3 - command line argument parser for Rust
===============================================
*Version 2.6.1* [MIT Licensed](https://spdx.org/licenses/MIT.html)
[](https://spdx.org/licenses/MIT.html)
[](https://crates.io/crates/getopt3)
[](https://blog.rust-lang.org/2021/10/21/Rust-1.56.0.html)
[](https://doc.rust-lang.org/nomicon/meet-safe-and-unsafe.html)
[](https://deps.rs/repo/gitlab/hsn10/getopt3)
[](https://docs.rs/getopt3)
[](https://crates.io/crates/getopt3/versions)
[](https://github.com/XAMPPRocky/tokei)
Features
--------
1. GNU argument parsing rules. Options can be anywhere on the command line before --
1. Double dash -- support. Anything after -- is not treated as options.
1. Multiple options not requiring argument can be chained together.
-abc is the same as -a -b -c
1. Last chained option can have an argument.
-abcpasta is the same as -a -b -c pasta
1. Argument does not require space. -wfile is the same as -w file
1. Parsing fails only if *optstring* is invalid.
### Code quality
1. [MSRV 1.56](https://blog.rust-lang.org/2021/10/21/Rust-1.56.0/), compatible with the entire *Rust 2021 Edition*.
1. Rust port of the well tested [Scala getopt](https://gitlab.com/hsn10/getopt) code.
1. Small code footprint: only 228 LOC.
1. Zero dependencies.
1. No `unsafe` Rust.
1. Runs on entire *stable 2021 Edition Rust*.
1. 70 unit tests, 7 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
-------
```rust
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](https://pubs.opengroup.org/onlinepubs/9799919799/functions/getopt.html) function.
1. [GNU libc getopt](https://www.gnu.org/software/libc/manual/html_node/Using-Getopt.html) function.
1. [OpenBSD getopt](https://man.openbsd.org/getopt.3)
1. [FreeBSD getopt](https://man.freebsd.org/cgi/man.cgi?query=getopt&apropos=0&sektion=3&arch=default&format=html)
#### Known getopt extensions
##### Fully implemented
1. GNU getopt parsing rules.
1. Options can be anywhere in command line before --
1. double dash -- support. Anything after -- is not treated as options.
1. POSIX extension in the *getopt* function 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
an option because it's possible to spot the difference between an unknown option and the -? option.
1. 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.
##### 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.
1. 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.
1. 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.
1. `posix` strict mode. First non option stops option parsing. This is needed for parsing nested command lines.