coalpit

Command-line options and DSV parsing and printing

Latest on Hackage:0.1.1.0

This package is not currently in any snapshots. If you're interested in using it, we recommend adding it to Stackage Nightly. Doing so will make builds more reliable, and allow stackage.org to host generated Haddocks.

BSD3 licensed by defanor
Maintained by defanor@uberspace.net

Coalpit

Coalpit is a library for building command-line program interfaces: the goal is to get interfaces between programs quickly and easily, while keeping them language-agnostic and more user- and shell scripting-friendly than JSON and similar formats.

Given a type, it derives instances to print and parse it as command-line arguments or DSVs, as well as to compose usage instructions. The resulting deserialization wouldn’t be as nice as that of e.g. optparse-generic, but the aim here is to handle more or less arbitrary types.

Warning: it is possible to run into ambiguity by defining a recursive structure with optional named elements while using default options. omitNamedOptions can be disabled to avoid that.

Example

An example is available in examples/Basic.hs. Given the following Haskell value:

Input { something = Nothing
      , fooBar = Just (Foo (FooArgs { arg1 = 1
                                    , arg2 = "a string"}))
      , fooBar2 = Bar}

With the default options, its serialized version should look like this:

["--foobar","foo","1","a string","bar"]

What would look like this in a shell:

--foobar foo 1 'a string' bar

And its usage string – like this:

[--something STRING] [--foobar (foo INT STRING | bar)] (foo INT STRING | bar)

More verbose versions can be produced and parsed with alwaysUseSelName = True and/or omitNamedOptions = False:

--foobar foo --arg1 1 --arg2 'a string' --foobar2 bar
nothing just foo 1 'a string' bar
--something nothing --foobar just foo --arg1 1 --arg2 'a string' --foobar2 bar

And here is output of the help function from the same file, with all the (alwaysUseSelName, omitNamedOptions) combinations:

(True,True)
--foo : 1 : 2 : 3 [] --bar "a string"
--foo ([] | : INT ([] | :...)) [--bar STRING]
(True,True)
--foo : 1 : 2 : 3 []
--foo ([] | : INT ([] | :...)) [--bar STRING]
(True,False)
--foo : 1 : 2 : 3 [] --bar just "a string"
--foo ([] | : INT ([] | :...)) --bar (nothing | just STRING)
(True,False)
--foo : 1 : 2 : 3 [] --bar nothing
--foo ([] | : INT ([] | :...)) --bar (nothing | just STRING)
(False,True)
: 1 : 2 : 3 [] --bar "a string"
([] | : INT ([] | :...)) [--bar STRING]
(False,True)
: 1 : 2 : 3 []
([] | : INT ([] | :...)) [--bar STRING]
(False,False)
: 1 : 2 : 3 [] just "a string"
([] | : INT ([] | :...)) (nothing | just STRING)
(False,False)
: 1 : 2 : 3 [] nothing
([] | : INT ([] | :...)) (nothing | just STRING)

Changes

Revision history for coalpit

0.1.1.0 – 2018-01-03

Complete rewriting and first Hackage release.

0.1.0.0 – 2016-11-24

A prototype.

Depends on 5 packages:
comments powered byDisqus