Hackage :: [Package]

coalpit: Command-line options and DSV parsing and printing

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

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 CLIs via a shared library, while being suitable for scripting and as user interfaces.

[Skip to Readme]

Properties

Versions 0.1.1.0, 0.1.1.1, 0.1.1.1
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 2019-04-14T11:07:35Z

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Readme for coalpit-0.1.1.1

[back to package description]

Coalpit

Coalpit is a library for building command-line interfaces: the goal is to get interfaces 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)