MPL-2.0 licensed by Kowainik
Maintained by [email protected]
This version can be pinned in stack with:tomland-1.0.0@sha256:a6eb99963469c3c047f7f6a54ccbadc87c2ec046eec82c6f22e535f7edfbc292,7374

tomland

palm Build status Hackage Stackage LTS Stackage Nightly MPL-2.0 license

“A library is like an island in the middle of a vast sea of ignorance, particularly if the library is very tall and the surrounding area has been flooded.”

― Lemony Snicket, Horseradish

Bidirectional TOML serialization. The following blog post has more details about library design:

This README contains a basic usage example of the tomland library. All code below can be compiled and run with the following command:

cabal new-run readme

Preamble: imports and language extensions

Since this is a literate haskell file, we need to specify all our language extensions and imports up front.

{-# OPTIONS -Wno-unused-top-binds #-}

{-# LANGUAGE LambdaCase        #-}
{-# LANGUAGE OverloadedStrings #-}

import Control.Applicative ((<|>))
import Control.Category ((>>>))
import Data.Text (Text)
import Toml (TomlBiMap, TomlCodec, (.=))

import qualified Data.Text.IO as TIO
import qualified Toml

tomland is mostly designed for qualified imports and intended to be imported as follows:

import Toml (TomlCodec, (.=))  -- add 'TomlBiMap' and 'Key' here optionally
import qualified Toml

Data type: parsing and printing

We’re going to parse TOML configuration from examples/readme.toml file.

This static configuration is captured by the following Haskell data type:

data Settings = Settings
    { settingsPort        :: !Port
    , settingsDescription :: !Text
    , settingsCodes       :: [Int]
    , settingsMail        :: !Mail
    , settingsUsers       :: ![User]
    }

data Mail = Mail
    { mailHost           :: !Host
    , mailSendIfInactive :: !Bool
    }

data User
    = Admin  Integer  -- id of admin
    | Client Text     -- name of the client
    deriving (Show)

newtype Port = Port Int
newtype Host = Host Text

Using tomland library, you can write bidirectional converters for these types using the following guidelines and helper functions:

  1. If your fields are some simple basic types like Int or Text you can just use standard codecs like Toml.int and Toml.text.
  2. If you want to parse newtypes, use Toml.diwrap to wrap parsers for underlying newtype representation.
  3. For parsing nested data types, use Toml.table. But this requires to specify this data type as TOML table in .toml file.
  4. If you have lists of custom data types, use Toml.list. Such lists are represented as array of tables in TOML. If you have lists of primitive types like Int, Bool, Double, Text or time types, that you can use Toml.arrayOf and parse arrays of values.
  5. tomland separates conversion between Haskell types and TOML values from matching values by keys. Converters between types and values have type TomlBiMap and are named with capital letter started with underscore. Main type for TOML codecs is called TomlCodec. To lift TomlBiMap to TomlCodec you need to use Toml.match function.
settingsCodec :: TomlCodec Settings
settingsCodec = Settings
    <$> Toml.diwrap (Toml.int  "server.port")       .= settingsPort
    <*> Toml.text              "server.description" .= settingsDescription
    <*> Toml.arrayOf Toml._Int "server.codes"       .= settingsCodes
    <*> Toml.table mailCodec   "mail"               .= settingsMail
    <*> Toml.list  userCodec   "user"               .= settingsUsers

mailCodec :: TomlCodec Mail
mailCodec = Mail
    <$> Toml.diwrap (Toml.text "host") .= mailHost
    <*> Toml.bool "send-if-inactive"   .= mailSendIfInactive

_Admin :: TomlBiMap User Integer
_Admin = Toml.prism Admin $ \case
    Admin i -> Right i
    other   -> Toml.wrongConstructor "Admin" other

_Client :: TomlBiMap User Text
_Client = Toml.prism Client $ \case
    Client n -> Right n
    other    -> Toml.wrongConstructor "Client" other

userCodec :: TomlCodec User
userCodec =
        Toml.match (_Admin >>> Toml._Integer) "id"
    <|> Toml.match (_Client >>> Toml._Text) "name"

And now we’re ready to parse our TOML and print the result back to see whether everything is okay.

main :: IO ()
main = do
    tomlExample <- TIO.readFile "examples/readme.toml"
    let res = Toml.decode settingsCodec tomlExample
    case res of
        Left err -> print err
        Right settings -> TIO.putStrLn $ Toml.encode settingsCodec settings

Benchmarks and comparison with other libraries

tomland is compared with other libraries. Since it uses 2-step approach with converting text to intermediate AST and only then decoding Haskell type from this AST, benchmarks are also implemented in a way to reflect this difference.

Library parse :: Text -> AST transform :: AST -> Haskell
tomland 387.5 μs 1.313 μs
htoml 801.2 μs 32.54 μs
htoml-megaparsec 318.7 μs 34.74 μs
toml-parser 157.2 μs 1.156 μs

You may see that tomland is not the fastest one (though still very fast). But performance hasn’t been optimized so far and:

  1. toml-parser doesn’t support the array of tables and because of that it’s hardly possible to specify the list of custom data types in TOML with this library.
  2. tomland supports latest TOML spec while htoml and htoml-megaparsec don’t have support for all types, values and formats.
  3. tomland is the only library that has pretty-printing.
  4. toml-parser doesn’t have ways to convert TOML AST to custom Haskell types and htoml* libraries use typeclasses-based approach via aeson library.
  5. tomland is bidirectional :slightly_smiling_face:

Acknowledgement

Icons made by Freepik from www.flaticon.com is licensed by CC 3.0 BY.

Changes

Changelog

tomland uses PVP Versioning. The changelog is available on GitHub.

1.0.0 — Jan 14, 2019

  • #13: Support array of tables.

    • #131: Uncommenting tomlTableArrays from TOML.
    • #134: Pretty printer arrays of tables and golden tests.
    • #143: Parser for arrays of tables.
    • #155: Add list and nonEmpty combinators for coding lists of custom user types.
    • #142: Adding EDSL support for arrays of tables.
    • #144: Added tests for arrays of tables.
  • #140: Breaking change: Replace wrapper by diwrap.

    Migration guide: change Toml.wrapper Toml.text "foo" to Toml.diwrap (Toml.text "foo").

  • #152: Breaking change: Removing mdimap.

    Migration guide: change Toml.mdimap showX parseX (Toml.text "foo") to Toml.textBy showX parseX "foo".

  • #137: Replace Maybe with Either in BiMap.

  • #174: Add _LText and lazyText codecs.

  • #163: Move all time data types from nested DateTime to Value.

  • #146: Allow underscores in floats.

  • #64: Integer parser doesn’t accept leading zeros.

  • #50: Add property-based tests for encoder and decoder.

  • #119: Add property-based tests for BiMap.

  • #149: Removing records syntax from PrefixTree.

0.5.0 — Nov 12, 2018

  • #81: Breaking change: Rename data types.

    Migration guide: rename Bijection to Codec, Bi to BiCodec and BiToml to TomlCodec.

  • #82: Breaking change: Remove maybeT. Add dioptional instead.

    Migration guide: replace Toml.maybeT Toml.int "foo" with Toml.dioptional (Toml.int "foo").

  • #95: Breaking change: Swap fields in BiMaps for consistency with lens package.

    Migration guide: reverse order of composition when using BiMaps.

  • #98: Implement benchmarks for tomland and compare with htoml and htoml-megaparsec libraries.

  • #130: Added combinators to Toml.Bi.Combinators.

  • #115: Added time combinators to Toml.BiMap and Toml.Bi.Combinators.

  • #99: Split Toml.Parser file into smaller files.

  • #22: Report proper type checking error during parsing.

  • #14: Add support for inline tables parsing.

  • #70: Add _TextBy and _Read combinators.

  • #11: Add PrintOptions (sorting, indentation) for pretty printer.

  • #17: Allow underscores in integers*.

  • #90: Migrate to megaparsec 7.0.

  • #85: Add Date generator for property-based tests.

  • #88: Add Array generator for property-based tests.

  • #86: Improve String generator for property-based tests.

  • #87: Improve Double generator for property-based tests.

  • Add support for GHC 8.6.1. Add support for GHC 8.4.4. Drop support for GHC 8.0.2.

  • #109: Add function decodeToml.

0.4.0

  • #54: Add support for sum types. Rename Prism to BiMap. Rename bijectionMaker to match. Add string codec.

0.3.1

  • #19: Add proper parsing of floating point numbers.
  • #15: Add parsing of multiline strings.
  • #40: Support full-featured string parser.
  • #18: Add dates parsing.
  • Add useful combinators for newtype wrappers.
  • #58: Add decodeFile function.

0.3

  • #60: Breaking change: Replace Valuer with Prism.

    Migration guide: replace any fooV with corresponding prism _Foo.

  • #66: Breaking change: Introduce consistent names according to Haskell types.

    Migration guide: see issue details to know which names to use.

  • #8: Create EDSL for easier TOML data type writing.

  • #10: Add Semigroup and Monoid instances for PrefixTree and TOML. Add property tests on laws.

  • #20: Add parsing of hexadecimal, octal, and binary integer numbers.

  • #26: Implement unit tests for TOML parsers. Allow terminating commas inside an array. Allow comments before and after any value inside an array. Allow keys to be literal strings.

0.2.1

  • Make table parser work with maybeP.
  • #39: Implement prettyException function for DecodeException.

0.2.0

  • Switch names for decode and encode functions.
  • #47: Rename dimapBijection to dimap. Introduce mdimap combinator.
  • #37: Add tables support for bidirectional conversion.

0.1.0

  • #16: Add parser for literal strings.
  • Add IsString instance for Key data type.
  • #38: Add bidirectional converter for array.
  • #21: Report expected vs. actual type error in parsing.
  • #44: Add bidirectional converter for Maybe.

0.0.0

  • #3: Implement basic TOML parser with megaparsec.
  • #7: Implement type safe version of Value type as GADT.
  • #4: Implement basic pretty-printer.
  • #1: Implement types representing TOML configuration.
  • Initially created.