Parse CLI options in Fish.

Getopts is a CLI options parser for Fish based on the POSIX Utility Syntax Guidelines. Think argparse without the domain specific language, implicit variables, complex option spec, or companion commands.

Install with Fisher:

fisher install jorgebucaran/getopts.fish

The getopts command splits your arguments into key-value records that can be read into variables.

$ engage --quadrant=delta -w9 <coordinates.dat

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

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 alppha
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

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

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
_ -

MIT