#!/usr/bin/bash

: << COMMENTS
Examples taken from https://zerotomastery.io/blog/bash-getopts/
COMMENTS


ExampleGroup 'getopts'

  Example 'getopts with options that require arguments'
    function eg1 {
      while getopts "u:p:" opt; do
        case $opt in
          u) echo "username=${OPTARG}" ;;
          p) echo "password=${OPTARG}" ;;
          *) echo "Error: Invalid option";;
        esac
      done
    }
    When call eg1 -u "Alice" -p "1234"
    The output line 1 should match pattern "username=Alice"
    The output line 2 should match pattern "password=1234"
  End

  Example 'getopts with option that requires no argument'
    function eg2 {
      while getopts "u:p:h" opt; do
        case $opt in
          u) echo "username=${OPTARG}" ;;
          p) echo "password=${OPTARG}" ;;
          h) echo "Help: This script accepts -u <username>, -p <password> and -h for help.";;
          *) echo "Error: Invalid option";;
        esac
      done
    }
    When call eg2 -h
    The output should match pattern "Help: This script accepts -u <username>, -p <password> and -h for help."
  End

  Example 'getopts with invalid option'
    function eg3 {
      while getopts "u:p:" opt; do
        case $opt in
          u) echo "username=${OPTARG}" ;;
          p) echo "password=${OPTARG}" ;;
          *) echo "Error: Invalid option";;
        esac
      done
    }
    When call eg3 -z
    The output should match pattern "Error: Invalid option"
    The error should include "illegal option -- z"
  End

  Example 'leading : supresses error and puts missing option into OPTARG'
    function eg4 {
      while getopts ":u:p:" opt; do
        case $opt in
          u) echo "username=${OPTARG}" ;;
          p) echo "password=${OPTARG}" ;;
          *) echo "Error: Invalid option -${OPTARG}";;
        esac
      done
    }
    When call eg4 -z
    The output should match pattern "Error: Invalid option -z"
  End

End

help getopts
getopts: getopts optstring name [arg ...]
    Parse option arguments.
    
    Getopts is used by shell procedures to parse positional parameters
    as options.
    
    OPTSTRING contains the option letters to be recognized; if a letter
    is followed by a colon, the option is expected to have an argument,
    which should be separated from it by white space.
    
    Each time it is invoked, getopts will place the next option in the
    shell variable $name, initializing name if it does not exist, and
    the index of the next argument to be processed into the shell
    variable OPTIND.  OPTIND is initialized to 1 each time the shell or
    a shell script is invoked.  When an option requires an argument,
    getopts places that argument into the shell variable OPTARG.
    
    getopts reports errors in one of two ways.  If the first character
    of OPTSTRING is a colon, getopts uses silent error reporting.  In
    this mode, no error messages are printed.  If an invalid option is
    seen, getopts places the option character found into OPTARG.  If a
    required argument is not found, getopts places a ':' into NAME and
    sets OPTARG to the option character found.  If getopts is not in
    silent mode, and an invalid option is seen, getopts places '?' into
    NAME and unsets OPTARG.  If a required argument is not found, a '?'
    is placed in NAME, OPTARG is unset, and a diagnostic message is
    printed.
    
    If the shell variable OPTERR has the value 0, getopts disables the
    printing of error messages, even if the first character of
    OPTSTRING is not a colon.  OPTERR has the value 1 by default.
    
    Getopts normally parses the positional parameters, but if arguments
    are supplied as ARG values, they are parsed instead.
    
    Exit Status:
    Returns success if an option is found; fails if the end of options is
    encountered or an error occurs.