getopt3 - cli parser with GNU extension for Rust
================================================
*Version 2.2.0* [MIT Licensed](https://spdx.org/licenses/MIT.html)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://spdx.org/licenses/MIT.html)
[![Crates.io Version](https://img.shields.io/crates/v/getopt3.svg)](https://crates.io/crates/getopt3)
[![Crates.io MSRV](https://img.shields.io/crates/msrv/getopt3?logo=rust&label=MSRV&labelColor=orange)](https://blog.rust-lang.org/2022/04/07/Rust-1.60.0.html)
[![Safe Rust](https://img.shields.io/badge/Rust-safe-brightgreen.svg)](https://www.rust-lang.org/policies/safety.html)
[![dependency status](https://deps.rs/repo/gitlab/hsn10/getopt3/status.svg)](https://deps.rs/repo/gitlab/hsn10/getopt3)
[![Documentation](https://docs.rs/getopt3/badge.svg)](https://docs.rs/getopt3)
[![Downloads](https://img.shields.io/crates/d/getopt3)](https://crates.io/crates/getopt3/versions)
[![](https://tokei.rs/b1/gitlab/hsn10/getopt3?category=code)](https://github.com/XAMPPRocky/tokei)

Features
--------

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

### Code quality

1. Rust port of well tested Scala getopt code.
1. Small code size.
1. Zero dependencies.
1. No `unsafe` Rust.
1. Runs on stable Rust. 
1. `no_std` Rust version in development.
1. 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

```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/9699919799/functions/getopt.html) function.
1. [GNU libc getopt](https://www.gnu.org/software/libc/manual/html_node/Using-Getopt.html) 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.
1. POSIX strict mode. First non option stops option parsing. This is needed for parsing nested command lines.