This module provides utilities for implementing and using bidirectional TOML codecs. The concept of bidirectional conversion in tomland has two parts: TomlBiMap and TomlCodec.

General TOML description

In the following TOML

name = "foo"

we call name as key and "foo" as value.

TomlBiMap

TomlBiMap provides a bidirectional conversion between TOML values and Haskell primitive values. TOML specification defines some primitive values you can use in key-value pairs (e.g. integer, string, local time). TomlBiMap provides a way to convert between TOML primitives and Haskell values. TomlBiMap doesn't know anything about TOML keys.

TomlCodec

TomlCodec describes how to convert in both ways between a single or multiple key-value pairs and Haskell types. tomland provides basic primitives for decoding and encoding single key-value pairs, but also a way to compose multiple TomlCodecs into a single one. So, if you have a custom data type, that has several fields or several constructors, you need to define TomlCodec for your data type.

Encoding and decoding

If you have a type like User then userCodec :: TomlCodec User is an object that describes how to encode a value of type User to TOML and decode TOML to a value of type User.

• To TOML: encode userCodec someUser
• From TOML: decode userCodec someToml

Naming conventions

tomland uses the following naming conventions (and encourages library users to follow them as well):

• _SomeName: for TomlBiMap (e.g. _Int, _Text, _Array)
• someName: for basic TomlCodecs (e.g. int, text, arrayOf)
• someNameCodec: for user defined codecs for custom types (e.g. userCodec, configCodec, serverCodec)

Since: 1.3.0.0

Core codec types, including Toml specialised ones: TomlCodec, TomlState and TomlEnv.

Core error types, including TomlDecodeError and LoadTomlException.

Contains TOML-specific combinators for converting between TOML and user data types.

Forward and backward mapping functions and combinators (similar to profunctors).

Contains TOML-specific combinators and codecs for converting between TOML and user data types.

Automatic TOML codecs using Generic.

BiMap type that represents Tagged Partial Bidirectional Conversion between TOML primitives and Haskell types.

Specific implementations of BiMap between Haskell types and TOML values.