README.md

koi

Bashful argument parsing

Quick Examples

Easily add command line arguments for Bash functions! Inspired by Python's argparse.

function sendrequest {
    __addarg "-h" "--help" "help" "optional" "" "Send an HTTP request"
    __addarg "-m" "--method" "storevalue" "optional" "GET" "The HTTP method"
    __addarg "-u" "--url" "storevalue" "required" "" "The url of the HTTP request"
    __parseargs "$@"
    curl -X "$method" "$url"
}

function checkstockprice {
    __addarg "-h" "--help" "help" "optional" "" "Check a stock's price"
    __addarg "" "symbol" "positionalarray" "required" "" "The ticker symbol(s) to check"
    __addarg "-e" "--exchange" "storevalue" "optional" "NYSE" "The exchange to use"
    __addarg "-p" "--port" "storevalue" "required" "" "The port to use"
    __addarg "-q" "--quiet" "flag" "optional" "" "If included, run in quiet mode"
    __parseargs "$@"
    # check the stock price
}

For more examples, check the Examples section in the documentation.

For documentation, see the full documentation.

Installation

Install via Homebrew:

brew install wcarhart/tools/koi

For other installation options, see the Installation section in the documentation.

Documentation

Please visit the documentation site for full documentation.

Setup

To start using koi, simply source it at the top of your Bash script.

#!/bin/bash
source koi

Also at the top of your script, but below sourcing koi, you should override the koiname and koidescription variables. The values of koiname and koidescription get printed in error messages and help text. Koi ships with default values if they are not set.

#!/bin/bash
source koi
koiname=nameofyourscript.sh
koidescription="A longer description of your script"

Examples

Positional Arguments

myscript.sh arg0 arg1 arg2

Short Options and Long Options

myscript.sh -a foo -b bar --longoption baz

Array Options

myscript.sh -a arg0 -a arg1 -a arg2

Flags (options without an argument)

myscript.sh -f -q

Joint Options

myscript.sh -ab       # resolves to: myscript.sh -a -b

Autogenerated Help Menus

myscript.sh --help    # show autogenerated help menu

Subcommands

myscript.sh subcommand -a foo --longoption baz arg0 arg1

Mutually Exclusive Groups

myscript.sh (-a | -b)

For more examples, check the Examples section in the documentation.

Nomenclature

You may ask, why the name koi? Well, the original working name of the library was Bashful Arg Parser, which is a mouthful. This was shortened to Bashful, to which coy is a synonym. Koi is a homophone of coy and thus was chosen as the name.