htoml
Parser for TOML files
Version on this page: | 1.0.0.3 |
LTS Haskell 18.28: | 1.0.0.3@rev:1 |
Stackage Nightly 2022-02-07: | 1.0.0.3@rev:1 |
Latest on Hackage: | 1.0.0.3@rev:1 |
htoml-1.0.0.3@sha256:2618469ff7cdd24f7ce1ea1076e668019dd856ff18fb9c445049e96fb068c13a,3648
Module documentation for 1.0.0.3
htoml
A TOML parser library in Haskell.
TOML is the obvious, minimal configuration language by Tom Preston-Werner. It is an alternative to the XML, YAML and INI formats mainly for the purpose of configuration files. Many will find that XML and YAML are too heavy for the purpose of configuration files prupose while INI is underspecified. TOML is to configuration files, like what Markdown is for rich-text.
This library aims to be compatible with the latest version of the
TOML spec.
Compatibility between htoml
version and TOML (as proven by
BurntSushi’s language agnostic TOML test suite)
is as follows:
- TOML v0.4.0
is implemented by
htoml >= 1.0.0.0
- (currently only one item in this mapping, more will follow)
Documentation
Apart from this README, documentation for this package may (or may not) be found on Hackage.
Quick start
Installing htoml
is easy. Either by using
Stack (recommended):
stack install htoml
Or by using Cabal:
cabal install htoml
In order to make your project depend on it you can add it as a
dependency in your project’s .cabal
file, and since it is not
yet on Stackage you will also have
to add it to the extra-deps
section of your stack.yaml
file
when using Stack.
To quickly show some features of htoml
we use Stack to start a
GHCi-based REPL. It picks up configuration from the .ghci
file
in the root of the repository.
git clone https://github.com/cies/htoml.git
cd htoml
stack init
stack --install-ghc ghci
Add a --resolver
flag to the stack init
command to specify
a specific package snapshot, e.g.: --resolver lts-4.1
.
In case you have missing dependencies (possibly file-embed
),
they can be added to the extra-deps
in stack.yaml
automatically with:
stack solver --update-config
We can now start exploring htoml
from a GHCi REPL. From the
root of this repository run:
stack ghci
Now read a .toml
file from the benchmark suite, with:
txt <- readFile "benchmarks/example.toml"
let r = parseTomlDoc "" txt
r
…which prints:
Right (fromList [("database",VTable (fromList [("enabled",VBoolean True),("po [...]
Then convert it to Aeson (JSON), with:
let Right toml = r
toJSON toml
…which prints:
Object (fromList [("database",Object (fromList [("enabled",Bool True),("po [...]
Finally trigger a parse error, with:
let Left err = parseTomlDoc "" "== invalid toml =="
err
…it errors out (as it should), showing:
(line 1, column 1):
unexpected '='
expecting "#", "\n", "\r\n", letter or digit, "_", "-", "\"", "'", "[" or end of input
Note: Some of the above outputs are truncated, indicated by [...]
.
How to pull data from a TOML file after parsing it
Once you have sucessfully parsed a TOML file you most likely want to pull some piecces of data out of the resulting data structure.
To do so you have two main options. The first is to use pattern matching.
For example let’s consider the following parseResult
:
Right (fromList [("server",VTable (fromList [("enabled",VBoolean True)] ) )] )
Which could be pattern matched with:
case parseResult of
Left _ -> "Could not parse file"
Right m -> case m ! "server" of
VTable mm -> case mm ! "enabled" of
VBoolean b -> "Server is " ++ (if b then "enabled" else "disabled")
_ -> "Could not parse server status (Boolean)"
_ -> "TOML file does not contain the 'server' key"
The second main option is to use the toJSON
function to transform the data
to an Aeson data structure,
after which you can use your Aeson toolbelt to tackle the problem. Since
TOML is intended to be a close cousin of JSON this is a very practical
approach.
Other ways to pull data from a parsed TOML document will most likely
exist; possible using the lens
library as
documented here.
Compatibility
Currently we are testing against several versions of GHC with
Travis CI as defined in the env
section of our
.travis.yml
.
lts-2
implies GHC 7.8.4, lts-3
implies GHC 7.10.2, lts-4
/lts-5
imply GHC 7.10.3, and nightly
is build with a regularly updated version of GHC.
Version contraints of htoml
’s dependencies
If you encounter any problems because htoml
’s dependecies are
constrained either too much or too little, please
file a issue for that.
Or off even better submit a PR.
Tests and benchmarks
Tests are build and run with:
stack test
BurntSushi’s language agnostic test suite
is embedded in the test suite executable. Using a shell script (that
lives in test/BurntSushi
) the latest tests can be fetched from
its Github repository.
The benchmarks, that use the amazing criterion
library, are build and run with:
stack build :benchmarks
Contributions
Most welcome! Please raise issues, start discussions, give comments or submit pull-requests. This is one of the first Haskell libraries I wrote, feedback is much appreciated.
Features
- Compatibility to the TOML spec is proven by an extensive test suite
- Incorporates BurntSushi’s language agnostic test suite
- Has an internal representation that easily maps to JSON
- Provides an Aeson-style JSON interface (suggested by Greg Weber)
- Useful error messages (thanks to using Parsec over Attoparsec)
- Understands arrays as described in this issue
- Fails on mix-type arrays (as per spec)
- Comes with a benchmark suite to make performance gains/regressions measurable
- Tries to be well documented (please raise an issue if you find documentation lacking)
- Available on Stackage (see top of this README for badges indicating TOMLs inclusion in Stackage status)
Todo
- More documentation and start to use the proper Haddock idioms
- Add property tests with QuickCheck (the internet says it’s possible for parsers)
- Extensively test error cases (probably improving error reporting along the way)
- See how lenses may (or may not) fit into this package, or an additional package
- Consider moving to one of the more modern parser combinators
in Haskell (
megaparsec
maybe?) – possibly wait until a clear winner shows
Do you see todo that looks like fun thing to implement and you can spare the time? Please knoe that PRs are welcome :)
Acknowledgements
Originally this project started off by improving the toml
package by
Spiros Eliopoulos.
HuwCampbell helped a lot by making tests pass and implementing “explicitness tracking” in Parsec’s parser state.
Copyright and licensing
This package includes BurntSushi’s language agnostic TOML tests, which are WTFPL licensed.
The TOML examples that are used as part of the benchmarks are copied from Tom Preston-Werner’s TOML spec which is MIT licensed.
For all other files in this project the copyrights are specified in the
htoml.cabal
file, they are distributed under the BSD3 license as found
in the LICENSE
file.
Changes
Change log
dev
- …
1.0.0.1
- Improve docs
1.0.0.0
- Use
Vector
overList
internally, as per discussion in issue 13
0.2.0.1
- Expose
ToJSON
implementation - Remove unused .cabal dependency (thanks @tmcgilchrist)
0.2.0.0
- Compatible with TOML 0.4.0
- Improve test suite (all test now pass – thanks @HuwCampbell)
- Slight API breakage (therefore major version bump)
- Use Parsec’s parser state to track explicitness of table definitions (thanks @HuwCampbell)
- Clean up docs and code
0.1.0.3
- GHC 7.10 compatibility fix (thanks @erebe)
- Allow time >= 1.5.0, by using some CPP trickery
- Improve README based on feedback on Reddit
0.1.0.2
- Update the REAMDE
- Add/relax dependency version contraints where applicable
- Fix all warnings
- Add
CHANGES.md
0.1.0.1
- Fix
cabal configure
error in cabal file
0.1.0.0
- Initial upload to Hackage