hydrogen-cli-args-0.17: README.md

hydrogen-cli-args
=================

[![Build Status](https://travis-ci.org/scravy/hydrogen-cli-args.svg?branch=master)](https://travis-ci.org/scravy/hydrogen-cli-args)

An easy to use command line arguments parser.

    main = do

        (options, switches, args) <- getOpts [
            'V' ~: switch "version"
          , 'h' ~: switch "help"
          ,        optarg "inFile"
          ,        optarg "outFile"
          , 'v' ~: switch "verbose"
          , 'f' ~: optarg "flag"
          , 'D' ~: optarg "config"
          ]

        when (switches ? "version") $ println "Example v1.0"

        when (switches ? "help") showManual

        let flags  = options ! "flag"
            config = options ! "config"

        ...

This program will accept arguments like that:

    -h --version -DHELLLO --config=SOME_CONFIG -f flagvalue

+ `options` in the above example is a `MultiMap String String`
+ `switches` is a `Set String`
+ `args` contains the remaining arguments as a `[String]`.

If an optional argument, defined by `optarg` is given (by its short alias or by
its long name) it will show up in the `options` `MultiMap`. Note that you can check
for a key beings set with `(?)` and retrieve all associated values with `(!)`.
Also note that `(!)` will always return a list, but possibly en empty one (if no option
was given).

Long options can be given as `--key value` or as `--key=value`.

Short options can be given as `-D value` as well as `-Dvalue`.

If a switch, defined by `switch` is given, it will show up in the `switches` `Set`.
You can query for whether a switch is set or not with `(?)`.

Switches can be combined, i.e. `-hv` is the same as `-h -v`.

If `--` is supplied as an argument, no options are evaluated beyond this point.
Any unknown or malformed option (`-x`, `--xxxx`) will be treated as an argument.


API
---

### Define options

#### `switch :: String -> Option`

Defines a command line switch with the given long name.


#### `optarg :: String -> Option`

Defines a command line option with the given long name.


#### `alias  ~: option :: Char -> Option -> Option`

Defines a shorthand for the given option.


#### `option ~? check :: Option -> (String -> Bool) -> Option`

Defines a check which the optional arguments' value has to pass.


#### `option ~= pattern :: Option -> String -> Option`

Defines a pattern which the optional arguments' value must match.


### Get options and arguments

#### `type OptArgs = (MultiMap String String, Set String, [String])`

#### `getOpts :: [Options] -> IO OptArgs`

#### `getOpts' :: [Options] -> [String] -> OptArgs`


### Query MultiMaps / Sets

Part of [hydrogen-prelude](http://github.com/scravy/hydrogen-prelude).