getopt2/

getopt2.rs

/*
 * Copyright (c) Radim Kolar 2013, 2018, 2023, 2025.
 * SPDX-License-Identifier: MIT
 *
 * getopt2 library is licensed under MIT license:
 *   https://spdx.org/licenses/MIT.html
*/

//!  # getopt2 command line parser
//!
//!  ### Command line argument parser with GNU parsing rules and double dash '--' support.
//!
//!  `getopt2::`[`new`] parses the command line elements and isolates arguments from options.
//!  It returns a [`getopt`] structure where you can query options and use isolated arguments.
//!
//!  An element that starts with '-' (and is not exactly "-" or "--") is an option element.
//!  The characters of this element (aside from the initial '-') are option characters.
//!  A double dash `--` can be used to indicate the end of options; any arguments following
//!  it are treated as positional arguments.
//!
//!  #### Example
//!  ```rust
//!  use std::env::args;
//!  use getopt2::hideBin;
//!  let rc = getopt2::new(hideBin(args()), "ab:c");
//!  if let Ok(g) = rc {
//!     // command line options parsed sucessfully
//!     if let Some(str) = g.options.get(&'b') {
//!        // handle b argument
//!        println!("option -b have {} argument", str);
//!     };
//!  };
//!  ```
//!  #### 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.
//!
//!  [`new`]: ./fn.new.html
//!  [`getopt`]: ./struct.getopt.html

#![forbid(unsafe_code)]
#![forbid(missing_docs)]
#![allow(non_camel_case_types)]
#![allow(unused_parens)]
#![allow(non_snake_case)]
#![allow(unused_doc_comments)]
#![deny(rustdoc::bare_urls)]
#![deny(rustdoc::broken_intra_doc_links)]
#![deny(rustdoc::missing_crate_level_docs)]
#![deny(rustdoc::invalid_codeblock_attributes)]
#![deny(rustdoc::invalid_rust_codeblocks)]

use std::io::Result;
use std::io::Error;
use std::io::ErrorKind;
use std::collections::HashMap;

/**
Parsed command line options.

Created by [`new`] function. Structure contains isolated command line
arguments and collected options with their optional values.

Structure can contain options which are not listed in *optstring*
passed to [`new`] function. For strict parse mode pass this
structure to [`validate`] function.

[`new`]: ./fn.new.html
[`validate`]: ./fn.validate.html
*/
pub struct getopt {
   /**
   Map of command line options and their optional values extracted from command line arguments.

   If an option does not have a value, an empty String "" is stored.
   */
   pub options: HashMap<char, String>,
   /** Isolated command line arguments without options. */
   pub arguments: Vec<String>,
   /** Map indicating whether an option has a required argument.

   This map contains all recognized options.
   Inclusion of an option in this map does not mean that the option must always be present
   or supplied as a command line argument. */
   pub option_has_arg: HashMap<char, argument>,
}

/**
  Information if option have an argument
*/
#[derive(PartialEq, Eq, Debug, Clone, Copy)]
pub enum argument {
   /** No argument */
   NO,
   /** Has argument */
   YES,
   /** Optional argument */
   OPTIONAL,
}

impl getopt {
   /**
      Return number of command line arguments.

      Its convience shortcut for getopt.arguments.len()

     #### Example
     ```rust
     use std::env::args;
     use getopt2::hideBin;

     let getopt_rc = getopt2::new(hideBin(args()), "ab:c");
     if let Ok(g) = getopt_rc {
        println!("Number of command line arguments is {}", g.len());
     };
     ```
   */
   pub fn len(&self) -> usize {
      self.arguments.len()
   }

   /**
      Returns Iterator over command line arguments.

      #### Example
      ```rust
      use std::env::args;
      use getopt2::hideBin;

      let getopt_rc = getopt2::new(hideBin(args()), "abc");
      if let Ok(my_getopt) = getopt_rc {
         for arg in my_getopt.iter() {
            println!("Argument: {}", arg);
         }
      }
      ```
   */
   pub fn iter(&self) -> std::slice::Iter<'_, String> {
      self.arguments.iter()
   }

   /**
      Return command line option value.

      Its convience shortcut for getopt.options.get()

      #### Return value
      1. If option were supplied on command line returned value is `Some`.
      1. If option doesn't have argument or argument is
         missing, reference to empty `String` is returned.
      1. If option were not supplied by user returned value is `None`.

      #### Example
      ```rust
      use std::env::args;
      use getopt2::hideBin;

      let getopt_rc = getopt2::new(hideBin(args()), "ab:c");
      if let Ok(my_getopt) = getopt_rc {
         if let Some(b_value) = my_getopt.get('b') {
            println!("-b argument is: {}", b_value);
         }
      }
      ```
   */
   pub fn get(&self, option: char) -> Option<&String> {
      self.options.get(&option)
   }

   /**
      Check if command line option were supplied on command line.

      Its convience shortcut for getopt.options.contains_key()

      #### Return value
      1. If option were supplied on command line returned value is `true`.
      1. If option were not supplied by user returned value is `false`.

      #### Example
      ```rust
      use std::env::args;
      use getopt2::hideBin;

      let getopt_rc = getopt2::new(hideBin(args()), "ab:c");
      if let Ok(my_getopt) = getopt_rc {
         if my_getopt.has('b') {
            println!("-b argument is: {}", my_getopt.get('b').unwrap());
         }
      }
      ```
   */
   pub fn has(&self, option: char) -> bool {
      self.options.contains_key(&option)
   }

   /**
      Check if any non option arguments were supplied.

      It is a convenience shortcut for *getopt.arguments.is_empty()*.

      #### Return value
      1. If any arguments were supplied on the command line returned value is `true`.
      1. If no arguments were supplied on the command line returned value is `false`.

      #### Example
      ```rust
      use std::env::args;
      use getopt2::hideBin;

      let getopt_rc = getopt2::new(hideBin(args()), "ab:c");
      if let Ok(my_getopt) = getopt_rc {
         if !my_getopt.is_empty() {
            println!("Arguments were supplied on command line");
         }
      }
      ```
   */
   pub fn is_empty(&self) -> bool {
      self.arguments.is_empty()
   }
}

/**
  Access to positional arguments by index.
*/
impl std::ops::Index<usize> for getopt {
    type Output = String;

    fn index(&self, index: usize) -> &Self::Output {
        self.arguments.index(index)
    }
}

impl IntoIterator for getopt {
   type Item = String;
   type IntoIter = std::vec::IntoIter<String>;

   fn into_iter(self) -> Self::IntoIter {
      self.arguments.into_iter()
   }
}

impl<'a> IntoIterator for &'a getopt {
   type Item = &'a String;
   type IntoIter = std::slice::Iter<'a, String>;

   fn into_iter(self) -> Self::IntoIter {
      self.arguments.iter()
   }
}

/**
  Parse command line arguments.

  Parses command line arguments using GNU getopt(3) parsing rules with
  double dash "--" support.
  Long arguments starting with double dash "--" are not supported.

  Parsing is done in non strict and non POSIX mode.
  Call [`validate`] on result to detect missing or unknown arguments.

  POSIX parsing mode is not yet supported.

  ## Arguments

  * `arg` - String Iterator with command line arguments. Can be empty.

  * `optstring` - List of legitimate alphanumeric plus '?' option characters.
                  If character is followed by colon, the option requires
                  an argument. Must not be empty.
  ## Parsing rules
  1. GNU argument parsing rules. It means that options can be anywhere in command line before --
  1. Double dash -- support. Everything after -- is not treated as options.
  1. Long options are not supported.
  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 same as -w file
  1. optional argument `::` GNU optstring extension is not implemented.
  1. Strict POSIX parse mode where first non option stops option parsing is not supported.
     This mode is triggered in GNU getopt by setting `POSIXLY_CORRECT` variable or by
     optstring starting with a plus sign `+`.
  1. The POSIX-specified extension for the *getopt* function, which allows the optstring to
     start with a colon (:), is always supported.
     This extension enables the use of the '?' character as a command-line option.
     We *always allow* use of the '?' as option without need to manually activate it using
     optstring.
     Starting optstring with ':' is possible and supported as valid syntax.

  ## Errors
  1. Parsing error **only happens** if optstring parameter is invalid or empty.
  1. If required argument is missing function _new()_ still returns succesfully and missing argument will
     be replaced by empty String.

  ### See also
  1. [GNU libc getopt](https://www.gnu.org/software/libc/manual/html_node/Using-Getopt.html) function.
  1. [POSIX getopt](https://pubs.opengroup.org/onlinepubs/9799919799/functions/getopt.html) function.

[`validate`]: ./fn.validate.html
*/
pub fn new(arg: impl IntoIterator<Item = impl AsRef<str>>, optstring: impl AsRef<str>) -> Result<getopt> {
   /** output options values */
   let mut opts = HashMap::new();
   /** output argument list */
   let mut args = Vec::new();
   /** option for previous loop iteration */
   let mut next_opt: Option<char> = None;
   /** are we still parsing or we just copying rest of arguments */
   let mut stop_parsing = false;
   /** map of options -> having an argument */
   let options_map: HashMap<char,argument> = build_options_map(validate_optstring(optstring.as_ref())?);
   /** is posix mode enabled */
   let posix: bool = optstring.as_ref().starts_with("+");

   for el in arg {
      let element = el.as_ref();
      if stop_parsing {
         // we do not parse options anymore all what's left
         // are arguments
         args.push(element.to_string());
      } else if let Some(next_opt_char) = next_opt {
         // option with possible parameter in previous loop iteration
         match options_map.get(&next_opt_char) {
            Some(argument::YES) => {
               // option with mandatory argument
               opts.insert(next_opt_char, element.to_string());
               next_opt = None;
            },
            Some(argument::OPTIONAL) => {
               // option with an optional argument
               if is_option(element, &options_map) {
                  // current element is an option
                  // push prev. option without an arg
                  opts.insert(next_opt_char, String::from(""));
                  next_opt = Some(element.as_bytes()[1] as char);
               } else if element.eq("--") {
                  // current element is a separator
                  // push prev. option without an arg
                  opts.insert(next_opt_char, String::from(""));
                  // and stop parsing
                  stop_parsing = true;
                  next_opt = None;
               } else {
                  // current element is an argument
                  opts.insert(next_opt_char, element.to_string());
                  next_opt = None;
               }
            },
            Some(argument::NO) => {
               // previous option have no argument
               // push it to opts
               opts.insert(next_opt_char, String::from(""));
               // is current element option or argument
               if is_option(element, &options_map) {
                  next_opt = Some(element.as_bytes()[1] as char);
               } else if element.eq("--") {
                  stop_parsing = true;
                  next_opt = None;
               } else {
                 args.push(element.to_string());
                 next_opt = None;
                 if ( posix ) { stop_parsing = true; };
               }
            }
            None => {
               // unknown option, should not happen
               let mut s = String::from("-");
               s.push(next_opt_char);
               args.push(s);
            }
         }
      } else if element.eq("--") {
         stop_parsing = true;
         next_opt = None;
      } else {
               // is current element option or argument
               if is_option(element, &options_map) {
                  next_opt = Some(element.as_bytes()[1] as char);
               } else {
                 args.push(element.to_string());
                 if ( posix ) { stop_parsing = true };
               }

      }
   }

   // HANDLE MISSING ARGUMENT FOR LAST OPTION
   if let Some(next_opt_char) = next_opt {
      match options_map.get(&next_opt_char) {
            Some(argument::YES) | None => {
               // option with mandatory argument
               // option argument is no more possible
               // push option as argument
               let mut s = String::from("-");
               s.push(next_opt_char);
               args.push(s);
            },
            Some(argument::NO) | Some(argument::OPTIONAL) => {
               // store option itself
               opts.insert(next_opt_char, String::from(""));
            }
      }
   }

   Ok(getopt {
      options: opts,
      arguments: args,
      option_has_arg: options_map,
   })
}

/**
  Check if string reference is an option.

  To pass check following conditions must be true:
  1. string is exactly 2 characters long
  1. string must start with a '-'
  1. second char must be in options map
*/
fn is_option(opt: &str, options_map: &HashMap<char, argument>) -> bool {
  if ( opt.chars().count() == 2 ) {
    if ( opt.starts_with('-') ) {
      let second_char: char = opt.chars().nth(1).unwrap();
      options_map.contains_key(&second_char)
    } else {
      // not starts with a '-'
      false
   }
  } else {
    // length not 2
    false
  }
}

/**
  Check if string reference can be an option.

  To pass check following conditions must be true:
  1. string reference is exactly 2 characters long
  1. string must start with a '-'
  1. opstring validation must pass
*/
fn is_possible_option(opt: &str) -> bool {
  if ( opt.chars().count() == 2 ) {
    if ( opt.starts_with('-') ) {
      let possible_optstring: String = opt.chars().skip(1).collect();
      validate_optstring(&possible_optstring).is_ok()
    } else {
      // not starts with a '-'
      false
   }
  } else {
    // length not 2
    false
  }
}


/**
  Checks if optstring is valid.

  ### Validation rules
  1. optstring can't contain triple ':::'
  1. optstring can't be empty
  1. allowed option characters are a-z A-Z 0-9 and '?'

  ### Implemented extensions
  1. if optstring starts with ':' then use of '?' is allowed.
     This extension is always active; You do not need to start
     optstring with ':' to enable '?'.
  1. optional arguments. If two semicolons '::' follows argument, it is an
     optional argument.
  1. POSIX mode. If string *starts with* '+' then parser will run in
     strict POSIX mode. In this case ':' extension can be second character
     '+:'. If '+' appears at any other position validation fails.
*/
fn validate_optstring(optstring: &str) -> Result<&str> {
   if optstring.is_empty() {
      Err(Error::new(ErrorKind::UnexpectedEof, "optstring can't be empty"))
   } else {
      // check for valid optstring characters
      for c in optstring.chars() {
         match c {
            'a'..='z' => Ok(()),
            'A'..='Z' => Ok(()),
            '0'..='9' => Ok(()),
            '?' => Ok(()),
            ':' => Ok(()),
            '+' => Ok(()),
            _ => Err(Error::new(
               ErrorKind::InvalidInput,
               "unsupported character in optstring. Only a-z A-Z 0-9 and ?:+ are allowed",
            )),
         }?
      }
      let plus = optstring.rfind("+");
      if plus.unwrap_or(0) > 0 {
         Err(Error::new(ErrorKind::InvalidInput, "plus sign '+' must be first character"))
      } else if optstring.contains(":::") {
         Err(Error::new(ErrorKind::InvalidInput, "triple ':' are not permited in optstring"))
      } else if optstring.starts_with("::") {
         Err(Error::new(ErrorKind::InvalidInput, "optstring can't start with '::'"))
      } else if optstring.starts_with("+::") {
         Err(Error::new(ErrorKind::InvalidInput, "optstring can't start with '+::'"))
      } else {
         Ok(optstring)
      }
   }
}

/**
 * Build options map from *validated* optstring.
 *
 * returns map <option,argument>
*/
fn build_options_map(optstring: &str) -> HashMap<char, argument> {
   let mut rc: HashMap<char, argument> = HashMap::with_capacity(optstring.len());
   let mut previous1: char = ':';
   let mut previous2: char = ':';
   let mut insert_one = |c: char| -> () {
      match c {
         ':' if previous1 != ':' && previous1 != '+' => rc.insert(*&previous1, argument::YES),
         ':' if previous1 == ':' && previous2 != ':' => rc.insert(*&previous2, argument::OPTIONAL),
         '+' => None,
         _ if previous1 != ':' && previous1 != '+' => rc.insert(*&previous1, argument::NO),
         _ => None,
      };
      previous2 = previous1;
      previous1 = c;
   };

   for c in optstring.chars() {
      insert_one(c);
   }
   // re-run option map building logic on last character in optstring if it is not ':'
   // if last character is ':', it has been already inserted to map and running it
   // again would cause insertion of ':' into options map because it is previous character
   optstring.chars().last().filter(|c| *c != ':').into_iter().for_each(|c| insert_one(c));
   rc
}

/**
* Validate parsed options in strict mode.
*
* ## Success
*
*   If strict mode validation passes, unchanged argument wrapped in [`Result`]
*   is returned.
*
* ## Errors
*
*   Returns [`Err`] if option not listed in optstring is encountered or
*   required argument for an option is missing.
**/
pub fn validate(getopt: getopt) -> Result<getopt> {
   // validate missing required arguments
   for (opt, _) in getopt.option_has_arg.iter().filter(|(_, arg)| **arg == argument::YES) {
      let mut opt_string = String::from("-");
      opt_string.push(*opt);
      if getopt.arguments.contains(&opt_string) {
            return Err(Error::new(
               ErrorKind::InvalidInput,
               format!("Option -{} does not have required argument", opt),
            ));
      }
   }

   // validate unknown options
   for opt in getopt.arguments.iter() {
      if is_possible_option(&opt) {
         return Err(Error::new(ErrorKind::InvalidInput, format!("Unknown option -{}", opt)));
      }
   }

   Ok(getopt)
}

/**
 * Removes first element from the IntoIterator.
 *
 * This utility function is supposed to be used on value returned by
 * `std::env::args()` before passing it to [`new`].
 *
 * First argument returned by `args()` corresponds to the program
 * executable name and its undesirable to have program name included
 * between parsed arguments.
 *
 * This function exists for making code more readable and because
 * widely used [yargs npm](https://www.npmjs.com/package/yargs) argument
 * parser have same function.
 *
 * `hideBin` function can be replaced by calling `.skip(1)`
 * on `Iterator` before passing it to [`new`]. Choose what is more
 * readable for you.
 *
 * #### Example
 * ```rust
 * use std::env::args;
 * use getopt2::hideBin;
 *
 * let rc = getopt2::new(hideBin(args()), "ab:c");
 * if let Ok(g) = rc {
 *    // command line options parsed sucessfully
 *    if let Some(_) = g.options.get(&'a') {
 *       // -a option found on command line
 *    };
 *  };
 * ```
 * [`new`]: ./fn.new.html
*/
pub fn hideBin(argv: impl IntoIterator<Item = String>) -> impl IntoIterator<Item = String> {
   argv.into_iter().skip(1)
}

// unit tests

#[cfg(test)]
#[path = "getopt_helpers_tests.rs"]
mod helpers;

#[cfg(test)]
#[path = "getopt_tests.rs"]
mod tests;

#[cfg(test)]
#[path = "getopt_posix_tests.rs"]
mod posix_tests;

#[cfg(test)]
#[path = "getopt_validate_api_tests.rs"]
mod validateapi;

#[cfg(test)]
#[path = "getopt_hidebin_tests.rs"]
mod hidebin;

#[cfg(test)]
#[path = "getopt_doubledash_tests.rs"]
mod doubledash;

#[cfg(test)]
#[path = "getopt_iterator_tests.rs"]
mod it;

#[cfg(test)]
#[path = "getopt_index_tests.rs"]
mod index;