README.md

getopts.fish

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.

Installation

Install with Fisher:

fisher install jorgebucaran/getopts.fish

Quickstart

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

Parsing Rules

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

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