Skip to content
Option parser for sh with support for long options
Perl Shell Roff Makefile Perl 6
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
m
p
s
t
.gitignore
GNUmakefile
INSTALL.rest
LICENSE
README.rest

README.rest

NAME
    haveopt — Option parser for sh

SYNOPSIS
    . haveopt.sh

    haveopt -h|--help
    haveopt OPTIND OPTNAME OPTARG [OPTSPEC...] -- "$@"
    haveopt OPTIND OPTNAME OPTARG [OPTSPEC...] -- [ARG...]

DESCRIPTION
    haveopt is a sh(1)-compatible argument parser similar to getopts
    with added support for long options, as in GNU getopt(1).  Like the
    POSIX getopts, haveopt allows for options requiring option-
    arguments.  Unlike GNU getopt(1), haveopt does not permit optional
    option-arguments.

    Each time haveopt is invoked, it shall place the name of the next
    option in the shell parameter named in the OPTNAME operand and
    the count of arguments processed so far in the shell parameter named
    in OPTIND.

    If the name reported in OPTNAME requires an option-argument
    according to the OPTSPEC... list, the shell parameter named in the
    OPTARG operand shall contain according value.
    Otherwise, the shell parameter named in OPTARG shall be unset.

    If an option not contained in the OPTSPEC... list is found where
    an option is expected, the shell parameter specified by OPTNAME
    shall be set to the <question-mark> ('?') character.
    Shell parameter given in OPTARG shall be set to the option found.

    When the end of options is encountered, the haveopt utility shall
    exit with a return value greater than zero; the shell parameter named
    in OPTIND shall be set to the index of the last option or option-
    argument, or 0 if there are no such arguments;
    the parameter given in OPTNAME shall be set to the <question-mark>
    character. Any of the following shall identify the end of options: the
    first "--" argument that is not an option-argument, finding an argument
    that is not an option-argument and does not begin with a '-', or
    encountering an error.

    Note: the shell parameter named in OPTIND assumes values that are
    one less than what getopts would set OPTIND to.  This is for two
    reasons.  First, there's no way a non-privileged shell script could
    fulfill this promise:

      Whenever the shell is invoked, OPTIND shall be initialized to 1.

    Second, the client code is not forced into funky Arithmetic Expansion
    syntax, plain shift $OPTIND will suffice to remove all options and
    option-arguments from $@.

    haveopt is implemented as a sh(1) function, loaded into a shell
    process with

      . haveopt.sh

    haveopt.sh must be in $PATH for this to work.

  Options
    -h, --help
        Display usage string.

  Operands
    OPTIND
      Name of the shell parameter used to communicate the number of
      options and option-arguments processed so far.
    OPTNAME
       Name of the shell parameter used to communicate the option
       extracted.
    OPTARG
       Name of the shell parameter used to communicate the option-argument
       extracted.
    OPTSPEC
       A valid option name without the leading dashes.  If the option
       requires an option-argument, OPTSPEC should end with “=”.

    Applications shall make sure that parameter names passed in the OPTIND,
    OPTNAME and OPTARG operands do not begin with "haveopt_".

EXIT STATUS
    The haveopt utility exits 0 on success, and >0 if an error occurs.

EXAMPLES
    This example demonstrates both short and long options, each with
    and without an option-argument::

      o_compression=gzip
      o_filesfrom=
      i=0
      while haveopt i opt arg J xz T= files-from= -- "$@"
      do
        case $opt in
        J|xz)
          o_compression=xz
        ;;
        T|files-from)
          o_filesfrom="$arg"
        ;;
        ?)
          printf "Usage: %s: [-J|--xz] [-T FILE|--files-from=FILE] operands\n" $0
          exit 2
        ;;
        esac
      done
      printf "Use %s (de)compression\n" "$o_compression"
      if [ ! -z "$o_filesfrom" ]; then
        printf 'Get pathnames to extract from "%s"\n' "$o_filesfrom"
      fi
      shift $i
      printf "Remaining arguments are: %s\n" "$*"

SEE ALSO
    getopt(1), getopts(1), sh(1).

STANDARDS
    “IEEE Std 1003.1-2008/Cor 1-2013” aka “POSIX.1-2008”
    aka “SUSv4TC1” aka “The Open Group Base Specifications Issue 7”.

    haveopt is aligned with the definitions laid out in
    “XBD Utility Syntax Guidelines”, namely guidelines 4-7,9-11,14,
    with modifications as noted:

      Guideline 4:
        Short options must be preceded by the '-' delimiter character.
        Long options must be preceded by the '--' delimiter string.
      Guideline 5:
        One or more short options without option-arguments, followed
        by at most one short option that takes an option-argument,
        should be accepted when grouped behind one '-' delimiter.
      Guideline 6:
        Each short option and option-argument should be a separate
        argument, haveopt also permits applications to specify the
        option and option-argument in the same argument string without
        intervening <blank> characters.
      Guideline 7:
        Option-arguments cannot not be optional.
      Guideline 9:
        All options must precede operands on the command line.  Option
        processing stops at the first argument that is neither an option
        nor an option-argument.
      Guideline 10:
        The first -- argument that is not an option-argument is
        accepted as a delimiter indicating the end of options.
        Any following arguments are treated as operands, even if they
        begin with the '-' character.
      Guideline 11:
        The order of different options relative to one another does not
        matter to haveopt.  Applications are free to ascribe meaning
        to option ordering.
      Guideline 14:
        If an argument can be identified according to Guidelines 3
        through 10 as an option, or as a group of options without
        option-arguments behind one '-' delimiter, then it is treated
        as such.

COMPATIBILITY
    haveopt is tested with bash(1), dash(1), mksh(1), posh(1).

LICENSE
    MIT
        https://github.com/roman-neuhauser/haveopt/blob/master/LICENSE

AUTHORS
    Roman Neuhauser <neuhauser+haveopt@sigpipe.cz>
        https://github.com/roman-neuhauser/haveopt/

BUGS
    No doubt plentiful.  Please report them at
        https://github.com/roman-neuhauser/haveopt/issues
You can’t perform that action at this time.