Hackage :: [Package]

htoml: A parser for TOML files.

[ bsd3, configuration, data, json, language, library, parser, text ] [ Propose Tags ]

TOML is a obvious and minimal format for config files.

This package provides a TOML parser, build with the Parsec library of parser combinators.

It provides a JSON interface using the Aeson library.

[Skip to Readme]

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0, 0.1.0.1, 0.1.0.2, 0.1.0.3, 0.2.0.0, 0.2.0.1, 1.0.0.0, 1.0.0.1, 1.0.0.2, 1.0.0.3
Dependencies aeson (<1.6), base (>=4.6 && <4.8), bytestring, Cabal (>=1.16.0), containers (>=0.5 && <0.6), file-embed, htoml, old-locale, parsec (>=3.1.5), tasty, tasty-hspec (<1.2), tasty-hunit, text, time (<1.5), unordered-containers, vector [details]
License BSD-3-Clause
Author Cies Breijs
Maintainer Cies Breijs
Revised Revision 1 made by Bodigrim at 2021-10-19T22:07:03Z
Category Text
Home page https://github.com/cies/htoml
Bug tracker https://github.com/cies/htoml/issues
Source repo head: git clone https://github.com/cies/htoml.git
Uploaded by cies at 2015-01-07T13:45:18Z
Distributions Fedora:1.0.0.3
Reverse Dependencies 7 direct, 2 indirect [details]
Executables tests
Downloads 11724 total (38 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2015-01-07 [all 1 reports]

Readme for htoml-0.1.0.1

[back to package description]

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 for the purpose of configuration files, as the first two are too heavy for that prupose, and the latter 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, currently that is v0.3.1.

The documentation for this package may (or may not) be found on Hackage.

Quick start

To quickly show some features of htoml we use GHCi, from the root of the repository run:

cabal repl

It picks up configuration from the .ghci file, so we can immediately start exploring:

> txt <- readFile "benchmarks/example.toml"
> let r = parseTomlDoc "" txt
> r
Right (fromList [("database",NTable (fromList [("enabled",NTValue (VBoolean True) [...]

> let Right toml = r
> toJSON toml
Object (fromList [("database",Object (fromList [("enabled",Bool True) [...]

> let Left error = parseTomlDoc "" "== invalid toml =="
> error
(line 1, column 1):
unexpected '='
expecting "#", "[" or end of input

First notice that some outputs are truncated.

Tests and benchmarks

The test suite is build by default, cabal configure --disable-tests disables them. The benchmark suite is not run by default, cabal configure --enable-benchmarks enables them.

With cabal build both of these suites are build as executables and put somewhere in dist/. Passing --help to them will reveal their options.

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 BurntSushi's repository.

Contributions

Most welcome! Please raise issues, start discussions, give comments or submit pull-requests. This is one of the first Haskell libraries I wrote, any feedback is much appreciated.

Features

  • Follows the latest version of the TOML spec, proven by an extensive test suite
  • Incorporates BurntSushi's language agnostic test suite
  • Has an internal representation that easily maps to JSON
  • Provides a JSON interface (suggested by Greg Weber)
  • Useful error messages (thanks to using Parsec over Attoparsec)
  • Understands arrays as described in this issue
  • Provides a benchmark suite
  • Fails on mix-type arrays (as per spec)
  • Haddock documentation

Todo

  • Release a stable 1.0 release and submit it to Stackage
  • More documentation
  • Moke all tests pass (currently some more obscure corner cases don't pass)
  • Add more tests (maybe find a more mature TOML parser and steal their tests)
  • Add property tests with QuickCheck (the internet says it's possible for parsers)
  • Extensively test error cases
  • Try using Vector instead of List (measure performance increase with the benchmarks)
  • See how lenses may (or may not) fit into this package

Acknoledgements

Originally this project started off by improving the toml package by Spiros Eliopoulos.

License

BSD3 as found in the LICENSE file.