Skip to content
CLI options parser for the fish shell—alternative to argparse
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
test fish-getopts 1.0 — Higher, faster, further! Feb 13, 2019
.travis.yml
LICENSE.md fish-getopts 1.0 — Higher, faster, further! Feb 13, 2019
README.md
getopts.fish fish-getopts 1.0 — Higher, faster, further! Feb 13, 2019

README.md

fish-getopts

Build Status Releases

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 Fisher (recommended):

fisher add jorgebucaran/fish-getopts
Not using a package manager?

Copy getopts.fish to any directory on your function path.

set -q XDG_CONFIG_HOME; or set XDG_CONFIG_HOME ~/.config
curl https://git.io/getopts.fish --create-dirs -sLo $XDG_CONFIG_HOME/fish/functions/getopts.fish

To uninstall, remove the file.

System Requirements

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

You can’t perform that action at this time.