Toml.Codec.Combinator.List

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.Combinator.List

Contents

- Array lists
- Table lists

Description

TOML-specific combinators for converting between TOML and Haskell list-like data types.

There are two way to represent list-like structures with the `tomland` library.

- Ordinary array lists of primitives:

      foo = [100, 200, 300]

- Lists via tables:

      foo =
          [ {x = 100}
          , {x = 200}
          , {x = 300}
          ]

      OR

      [[foo]]
          x = 100
      [[foo]]
          x = 200
      [[foo]]
          x = 300

You can find both types of the codecs in this module for different list-like structures. See the following table for the better understanding:

Haskell Type | `TOML` | `TomlCodec`
--- | --- | ---
`[`Int`]` | `a = [1, 2, 3]` | ``arrayOf` `_Int` "a"`
``NonEmpty` `Int`` | `a = [11, 42]` | ``arrayNonEmptyOf` `_Int` "a"`
`[`Text`]` | `x = [{a = "foo"}, {a = "bar"}]` | ``list` (`text` "a") "x"`
``NonEmpty` `Text`` | `x = [{a = "foo"}, {a = "bar"}]` | ``nonEmpty` (`text` "a") "x"`

Since: 1.3.0.0

Synopsis

- arrayOf :: TomlBiMap a AnyValue -> Key -> TomlCodec [a]
- arrayNonEmptyOf :: TomlBiMap a AnyValue -> Key -> TomlCodec (NonEmpty a)
- list :: TomlCodec a -> Key -> TomlCodec [a]
- nonEmpty :: TomlCodec a -> Key -> TomlCodec (NonEmpty a)

# Array lists

arrayOf :: TomlBiMap a AnyValue -> Key -> TomlCodec [a] #

Codec for list of values. Takes converter for single value and returns a list of values.

Example:

Haskell `[`Int`]` can look like this in your `TOML` file:

    foo = [1, 2, 3]

If the key is not present in `TOML` the following decode error will be spotted:

    tomland decode error:  Key foo is not found

Since: 0.1.0

arrayNonEmptyOf :: TomlBiMap a AnyValue -> Key -> TomlCodec (NonEmpty a) #

Codec for non- empty lists of values. Takes converter for single value and returns a non-empty list of values.

Example:

Haskell ``NonEmpty` `Int`` can look like this in your `TOML` file:

    foo = [1, 2, 3]

If you try to decode an empty `TOML` list you will see the error:

    tomland decode error:  Empty array list, but expected NonEmpty

If the key is not present in `TOML` the following decode error will be spotted:

    tomland decode error:  Key foo is not found

Since: 0.5.0

# Table lists

list :: TomlCodec a -> Key -> TomlCodec [a] #

`Codec` for list of values. Represented in TOML as array of tables.

Example:

Haskell `[`Int`]` can look like this in your `TOML` file:

    foo =
      [ {a = 1}
      , {a = 2}
      , {a = 3}
      ]

Decodes to an empty list `[]` when the key is not present.

Since: 1.0.0

nonEmpty :: TomlCodec a -> Key -> TomlCodec (NonEmpty a) #

`Codec` for `NonEmpty` list of values. Represented in TOML as array of tables.

Example:

Haskell ``NonEmpty` `Int`` can look like this in your `TOML` file:

    foo =
      [ {a = 1}
      , {a = 2}
      , {a = 3}
      ]

If you try to decode an empty `TOML` list you will see the error:

    tomland decode error:  Table array [[foo]] is not found

or

    tomland decode error:  Key foo.a is not found

If the key is not present in `TOML` the following decode error will be spotted:

    tomland decode error:  Table array [[foo]] is not found

Since: 1.0.0