Toml.Generic

This module contains implementation of the Generic TOML codec. If your data types are big and nested, and you want to have codecs for them without writing a lot of boilerplate code, you can find this module helpful. Below you can find the detailed explanation on how the Generic codecs work.

Consider the following Haskell data types:

data User = User
    { age     :: Int
    , address :: Address
    , socials :: [Social]
    } deriving (Generic)

data Address = Address
    { street :: Text
    , house  :: Int
    } deriving (Generic)

data Social = Social
    { name :: Text
    , link :: Text
    } deriving (Generic)

Value of the User type represents the following TOML:

age = 27

[address]
  street = "Miami Beach"
  house  = 42

[[socials]]
  name = "Twitter"
  link = "https://twitter.com/foo"

[[socials]]
  name = "GitHub"
  link = "https://github.com/bar"

Normally you would write TomlCodec for this data type like this:

userCodec :: TomlCodec User
userCodec = User
    <$> Toml.int "age" .= age
    <*> Toml.table addressCodec "address" .= address
    <*> Toml.list  socialCodec  "socials" .= socials

addressCodec :: TomlCodec Address
addressCodec = Address
    <$> Toml.text "street" .= street
    <*> Toml.int  "house"  .= house

socialCodec :: TomlCodec Social
socialCodec = Social
    <$> Toml.text "name" .= name
    <*> Toml.text "link" .= link

However, if you derive Generic instance for your data types (as we do in the example), you can write your codecs in a simpler way.

userCodec :: TomlCodec User
userCodec = genericCodec

instance HasCodec Address where
    hasCodec = Toml.table genericCodec

instance HasItemCodec Social where
    hasItemCodec = Right genericCodec

Several notes about the interface:

1. Your top-level data types are always implemented as genericCodec (or other generic codecs).
2. If you have a custom data type as a field of another type, you need to implement the instance of the HasCodec typeclass.
3. If the data type appears as an element of a list, you need to implement the instance of the HasItemCodec typeclass.

Since: 1.1.1.0

Documentation

genericCodec :: (Generic a, GenericCodec (Rep a)) => TomlCodec a

Generic codec for arbitrary data types. Uses field names as keys.

genericCodecWithOptions :: forall a. (Generic a, GenericCodec (Rep a), Typeable a) => TomlOptions a -> TomlCodec a

Generic codec with options for arbitrary data types.

stripTypeNameCodec :: forall a. (Generic a, GenericCodec (Rep a), Typeable a) => TomlCodec a

Generic codec that uses stripTypeNameOptions.

Options

data TomlOptions a

Options to configure various parameters of generic encoding. Specifically:

• tomlOptionsFieldModifier: how to translate field names to TOML keys?

Constructors

TomlOptions

Fields

• tomlOptionsFieldModifier :: Typeable a => Proxy a -> String -> String

newtype GenericOptions

Same as TomlOptions but with all data type information erased. This data type is used internally. Define your options using TomlOptions data type.

Constructors

GenericOptions

Fields

• genericOptionsFieldModifier :: String -> String

stripTypeNameOptions :: Typeable a => TomlOptions a

Options that use stripTypeNamePrefix as tomlOptionsFieldModifier.

stripTypeNamePrefix :: forall a. Typeable a => Proxy a -> String -> String

Strips name of the type name from field name prefix.

>>> data UserData = UserData { userDataId :: Int, userDataShortInfo :: Text }
>>> stripTypeNamePrefix (Proxy @UserData) "userDataId"
"id"
>>> stripTypeNamePrefix (Proxy @UserData) "userDataShortInfo"
"shortInfo"
>>> stripTypeNamePrefix (Proxy @UserData) "udStats"
"stats"
>>> stripTypeNamePrefix (Proxy @UserData) "fooBar"
"bar"
>>> stripTypeNamePrefix (Proxy @UserData) "name"
"name"

Core generic typeclass

class HasCodec a where

Helper typeclass for generic deriving. This instance tells how the data type should be coded if it's a field of another data type.

NOTE: If you implement TOML codecs for your data types manually, prefer more explicit Toml.int or Toml.text instead of implicit Toml.hasCodec. Implement instances of this typeclass only when using genericCodec and when your custom data types are not covered here.

Methods

hasCodec :: Key -> TomlCodec a

Instances

HasCodec Bool

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec Bool

HasCodec Double

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec Double

HasCodec Float

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec Float

HasCodec Int

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec Int

HasCodec Integer

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec Integer

HasCodec Natural

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec Natural

HasCodec Word

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec Word

HasCodec Word8

Since: 1.2.0.0

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec Word8

HasCodec IntSet

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec IntSet

HasCodec Text

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec Text

HasCodec Text

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec Text

HasCodec ZonedTime

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec ZonedTime

HasCodec LocalTime

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec LocalTime

HasCodec TimeOfDay

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec TimeOfDay

HasCodec Day

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec Day

HasItemCodec a => HasCodec [a]

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec [a]

HasCodec a => HasCodec (Maybe a)

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec (Maybe a)

HasItemCodec a => HasCodec (NonEmpty a)

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec (NonEmpty a)

(Ord a, HasItemCodec a) => HasCodec (Set a)

Since: 1.2.0.0

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec (Set a)

(Hashable a, Eq a, HasItemCodec a) => HasCodec (HashSet a)

Since: 1.2.0.0

Defined in Toml.Generic

Methods

hasCodec :: Key -> TomlCodec (HashSet a)

class HasItemCodec a where

This typeclass tells how the data type should be coded as an item of a list. Lists in TOML can have two types: primitive and table of arrays.

• If hasItemCodec returns Left: primitive arrays codec is used.
• If hasItemCodec returns 'Right:' table of arrays codec is used.

Methods

hasItemCodec :: Either (TomlBiMap a AnyValue) (TomlCodec a)

Instances

HasItemCodec Bool

Defined in Toml.Generic

Methods

hasItemCodec :: Either (TomlBiMap Bool AnyValue) (TomlCodec Bool)

HasItemCodec Double

Defined in Toml.Generic

Methods

hasItemCodec :: Either (TomlBiMap Double AnyValue) (TomlCodec Double)

HasItemCodec Float

Defined in Toml.Generic

Methods

hasItemCodec :: Either (TomlBiMap Float AnyValue) (TomlCodec Float)

HasItemCodec Int

Defined in Toml.Generic

Methods

hasItemCodec :: Either (TomlBiMap Int AnyValue) (TomlCodec Int)

HasItemCodec Integer

Defined in Toml.Generic

Methods

hasItemCodec :: Either (TomlBiMap Integer AnyValue) (TomlCodec Integer)

HasItemCodec Natural

Defined in Toml.Generic

Methods

hasItemCodec :: Either (TomlBiMap Natural AnyValue) (TomlCodec Natural)

HasItemCodec Word

Defined in Toml.Generic

Methods

hasItemCodec :: Either (TomlBiMap Word AnyValue) (TomlCodec Word)

HasItemCodec Word8

Since: 1.2.0.0

Defined in Toml.Generic

Methods

hasItemCodec :: Either (TomlBiMap Word8 AnyValue) (TomlCodec Word8)

HasItemCodec IntSet

Defined in Toml.Generic

Methods

hasItemCodec :: Either (TomlBiMap IntSet AnyValue) (TomlCodec IntSet)

HasItemCodec Text

Defined in Toml.Generic

Methods

hasItemCodec :: Either (TomlBiMap Text AnyValue) (TomlCodec Text)

HasItemCodec Text

Defined in Toml.Generic

Methods

hasItemCodec :: Either (TomlBiMap Text AnyValue) (TomlCodec Text)

HasItemCodec ZonedTime

Defined in Toml.Generic

Methods

hasItemCodec :: Either (TomlBiMap ZonedTime AnyValue) (TomlCodec ZonedTime)

HasItemCodec LocalTime

Defined in Toml.Generic

Methods

hasItemCodec :: Either (TomlBiMap LocalTime AnyValue) (TomlCodec LocalTime)

HasItemCodec TimeOfDay

Defined in Toml.Generic

Methods

hasItemCodec :: Either (TomlBiMap TimeOfDay AnyValue) (TomlCodec TimeOfDay)

HasItemCodec Day

Defined in Toml.Generic

Methods

hasItemCodec :: Either (TomlBiMap Day AnyValue) (TomlCodec Day)

(HasItemCodec a, Typeable a) => HasItemCodec [a]

If data type a is not primitive then this instance returns codec for list under key equal to a type name.

Defined in Toml.Generic

Methods

hasItemCodec :: Either (TomlBiMap [a] AnyValue) (TomlCodec [a])

class GenericCodec (f :: k -> Type) where

Helper class to derive TOML codecs generically.

Methods

genericTomlCodec :: GenericOptions -> TomlCodec (f p)

Instances

(GenericCodec f, GenericCodec g) => GenericCodec (f :*: g :: k -> Type)

Defined in Toml.Generic

Methods

genericTomlCodec :: forall (p :: k0). GenericOptions -> TomlCodec ((f :*: g) p)

GenericCodec f => GenericCodec (C1 c f :: k -> Type)

Defined in Toml.Generic

Methods

genericTomlCodec :: forall (p :: k0). GenericOptions -> TomlCodec (C1 c f p)

GenericCodec f => GenericCodec (D1 d f :: k -> Type)

Defined in Toml.Generic

Methods

genericTomlCodec :: forall (p :: k0). GenericOptions -> TomlCodec (D1 d f p)

(TypeError GenericSumTomlNotSupported :: Constraint) => GenericCodec (f :+: g :: k -> Type)

Defined in Toml.Generic

Methods

genericTomlCodec :: forall (p :: k0). GenericOptions -> TomlCodec ((f :+: g) p)

(Selector s, HasCodec a) => GenericCodec (S1 s (Rec0 a) :: k -> Type)

Defined in Toml.Generic

Methods

genericTomlCodec :: forall (p :: k0). GenericOptions -> TomlCodec (S1 s (Rec0 a) p)