Hackage :: [Package]

htoml: Parser for TOML files

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

TOML is an obvious and minimal format for config files.

This package provides a TOML parser, build with the Parsec library, and providing 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
Change log CHANGES.md
Dependencies aeson (>=0.8 && <1.6), base (>=4.3 && <4.8), bytestring (>=0.9), Cabal (>=1.16.0), containers (>=0.5), file-embed (>=0.0.5), htoml, old-locale, parsec (>=3.1.2 && <4), tasty (>=0.10), tasty-hspec (>=0.2 && <1.2), tasty-hunit (>=0.9), text (>=1.0 && <2), time (<1.5), unordered-containers (>=0.2), vector (>=0.10) [details]
License BSD-3-Clause
Copyright (c) 2013-2014 Cies Breijs
Author Cies Breijs
Maintainer Cies Breijs <cies % kde ! nl>
Revised Revision 1 made by Bodigrim at 2021-10-19T22:07:02Z
Category Data, Text, Parser, Configuration, JSON, Language
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-08T10:41:07Z
Distributions Fedora:1.0.0.3
Reverse Dependencies 7 direct, 2 indirect [details]
Executables tests
Downloads 11724 total (37 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-11 [all 1 reports]

Readme for htoml-0.1.0.2

[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

Installing htoml is easy.

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.

To quickly show some features of htoml we start GHCi from the root of the repository so it picks up configuration from the .ghci file that lives there.

git clone https://github.com/cies/htoml.git
cd htoml
cabal repl  ;# this starts GHCi

We can immediately start exploring from the GHCi prompt.

> 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

Notice that some outputs are truncated, indicated by [...].

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.

I will try to have htoml included in Stackage as soon as it is reviewed by the community. Stackage provides a very attractive solution to most (dependency) version conflicts.

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
  • Fails on mix-type arrays (as per spec)
  • Provides a benchmark suite
  • Tries to be well documented (please raise an issue if you find documentation lacking)

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.

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, and are distributed under the BSD3 license as found in the LICENSE file.