README.md

fish-getopts

Getopts is a CLI options parser for the fish shell. You can use it as an alternative to the argparse builtin to process the command line arguments passed to your programs without learning a domain specific language. No implicit variables, complex option spec, or companion commands.

Installation

Install with Fundle:

fundle plugin 'hunter-richardson/fish-getops'

System Requirements

• fish 2.0+

Usage

The getopts command splits your arguments into key-value records you can read into variables. The command line arguments passed to a function or a script can be found in the special variable $argv. If getopts is run without any arguments, it will exit with status 1.

$ engage --quadrant=delta -w9 <coordinates

function engage -d "activate the warp drive"
    set -l warp 1
    set -l quadrant alpha
    set -l coordinates

    getopts $argv | while read -l key value
        switch $key
            case _
                while read -l target
                    set coordinates $coordinates $target
                end < $value
            case q quadrant
                set quadrant $value
            case w warp
                set warp $value
            case h help
                _engage_help >&2
                return
            case v version
                _engage_version >&2
                return
        end
    end

    if not set -q coordinates[3]
        echo "engage: invalid coordinates" >&2
        return 1
    end

    _engage_activate $warp $quadrant $coordinates
end

Parsing Rules

Getopts follows the POSIX Utility Syntax Guidelines. This section defines short and long options, operands, and the rules that determine parsing behavior with examples.

Short Options

• A short option consists of a hyphen - followed by a single alphabetic character. Multiple short options can be clustered together without spaces. A short option will be true unless followed by an operand or if immediately adjacent to one or more non-alphabetic characters matching the regular expression /!-@[-`{-~/.

  $ getopts -ab -c
  a true
  b true
  c true

  $ getopts -a alpha
  a alpha

• The argument following a short or a long option (which is not an option itself) will be parsed as its value. That means only the last character in a cluster of options can receive a value other than true.

  $ getopts -ab1 -c -d
  a true
  b 1
  c true
  d true

• Symbols, numbers and other non-alphabetic characters can be used as an option if they're the first character after a hyphen.

  $ getopts -9 -@10 -/0.01
  9 true
  @ 10
  / 0.01

Long Options

• A long option consists of two hyphens -- followed by one or more characters. Any character, including symbols, and numbers can be used to create a long option except for the = symbol, which separates the option's key and value.

  $ getopts --turbo --warp=10
  turbo true
  warp 10

  $ getopts --warp=e=mc\^2
  warp e=mc^2

  $ getopts ---- alpha
  -- alpha

Operands

• Every non-option standalone argument will be treated as an operand, and its key will be an underscore _.

  $ getopts alpha -w9
  _ alpha
  w 9

  $ getopts --code=alpha beta
  code alpha
  _ beta

• Every argument after the first double-hyphen sequence -- will be treated as an operand.

  $ getopts --alpha -- --beta gamma
  alpha true
  _ --beta
  _ gamma

• A single hyphen - is always an operand.

  $ getopts --alpha -
  alpha true
  _ -

License

MIT