coalpit: Command-line options and DSV parsing and printing

[ bsd3, console, library ] [ Propose Tags ]

This library generates parsers and printers for given data types, in the form of command-line arguments or DSVs – so that they can be used to quickly get program interfaces via a shared library, while being suitable for scripting and as user interfaces.


[Skip to Readme]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.1.0, 0.1.1.1, 0.2.0.0
Change log ChangeLog.md
Dependencies base (>=4.9 && <5), megaparsec (>=6.2 && <7), network-uri (>=2.6 && <3), scientific (>=0.3 && <1), time (>=1.6 && <2) [details]
License BSD-3-Clause
Author defanor
Maintainer defanor@uberspace.net
Category Console
Bug tracker https://github.com/defanor/coalpit/issues
Source repo head: git clone https://git.uberspace.net/coalpit
Uploaded by defanor at 2018-01-03T18:49:42Z
Distributions
Reverse Dependencies 1 direct, 0 indirect [details]
Downloads 1375 total (12 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2018-01-03 [all 1 reports]

Readme for coalpit-0.1.1.0

[back to package description]

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)