Toml.Codec

tomland-1.3.3.3: Bidirectional TOML serialization

Copyright | (c) 2018-2022 Kowainik
License | MPL-2.0
Maintainer | Kowainik <xrom.xkov@gmail.com>
Stability | Stable
Portability | Portable
Safe Haskell | None
Language | Haskell2010

Toml.Codec

Description

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 `TomlCodec`s 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 `TomlCodec`s (e.g. `int`, `text`, `arrayOf`)
- someNameCodec: for user defined codecs for custom types (e.g. `userCodec`, `configCodec`, `serverCodec`)

Since: 1.3.0.0

Synopsis

- module Toml.Codec.Types
- module Toml.Codec.Error
- module Toml.Codec.Code
- module Toml.Codec.Di
- module Toml.Codec.Combinator
- module Toml.Codec.Generic
- module Toml.Codec.BiMap
- module Toml.Codec.BiMap.Conversion

# Documentation

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

module Toml.Codec.Types

Core error types, including `TomlDecodeError` and `LoadTomlException`.

module Toml.Codec.Error

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

module Toml.Codec.Code

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

module Toml.Codec.Di

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

module Toml.Codec.Combinator

Automatic TOML codecs using `Generic`.

module Toml.Codec.Generic

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

module Toml.Codec.BiMap

Specific implementations of `BiMap` between Haskell types and TOML values.

module Toml.Codec.BiMap.Conversion