Toml.Codec.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.0.0

Documentation

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

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

Since: 1.1.0.0

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

Generic codec with options for arbitrary data types.

Since: 1.1.0.0

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

Generic codec that uses stripTypeNameOptions.

Since: 1.1.0.0

Options

data TomlOptions a

Options to configure various parameters of generic encoding. Specifically:

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

Since: 1.1.0.0

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.

Since: 1.1.0.0

Constructors

GenericOptions

Fields

• genericOptionsFieldModifier :: String -> String

stripTypeNameOptions :: Typeable a => TomlOptions a

Options that use stripTypeNamePrefix as tomlOptionsFieldModifier.

Since: 1.1.0.0

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"

Since: 1.1.0.0

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.

Since: 1.1.0.0

Methods

hasCodec :: Key -> TomlCodec a

Instances

HasCodec Bool

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec Bool

HasCodec Double

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec Double

HasCodec Float

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec Float

HasCodec Int

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec Int

HasCodec Integer

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec Integer

HasCodec Natural

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec Natural

HasCodec Word

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec Word

HasCodec Word8

Since: 1.2.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec Word8

HasCodec All

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec All

HasCodec Any

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec Any

HasCodec Text

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec Text

HasCodec IntSet

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec IntSet

HasCodec Text

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec Text

HasCodec ZonedTime

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec ZonedTime

HasCodec LocalTime

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec LocalTime

HasCodec TimeOfDay

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec TimeOfDay

HasCodec Day

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec Day

HasCodec LByteStringAsBytes

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec LByteStringAsBytes

HasCodec LByteStringAsText

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec LByteStringAsText

HasCodec ByteStringAsBytes

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec ByteStringAsBytes

HasCodec ByteStringAsText

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec ByteStringAsText

HasItemCodec a => HasCodec [a]

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec [a]

HasCodec a => HasCodec (Maybe a)

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec (Maybe a)

HasCodec a => HasCodec (First a)

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec (First a)

HasCodec a => HasCodec (Last a)

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec (Last a)

(Num a, HasCodec a) => HasCodec (Sum a)

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec (Sum a)

(Num a, HasCodec a) => HasCodec (Product a)

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec (Product a)

HasItemCodec a => HasCodec (NonEmpty a)

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec (NonEmpty a)

HasCodec v => HasCodec (IntMap v)

Encodes IntMap as array of tables with the key and val TOML key names for IntMap keys and values. E.g. if you have a type IntMap Text, the HasCodec instance for Generic deriving will work with the following TOML representation:

fieldName =
    [ { key = 10, val = "foo" }
    , { key = 42, val = "bar" }
    ]

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec (IntMap v)

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

Since: 1.2.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec (Set a)

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

Since: 1.2.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec (HashSet a)

(Generic a, GenericCodec (Rep a)) => HasCodec (TomlTable a)

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec (TomlTable a)

(Ord k, HasCodec k, HasCodec v) => HasCodec (Map k v)

Encodes Map as array of tables with the key and val TOML key names for Map keys and values. E.g. if you have a type Map Int Text, the HasCodec instance for Generic deriving will work with the following TOML representation:

fieldName =
    [ { key = 10, val = "book" }
    , { key = 42, val = "food" }
    ]

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec (Map k v)

(Hashable k, Eq k, HasCodec k, HasCodec v) => HasCodec (HashMap k v)

Encodes HashMap as array of tables with the key and val TOML key names for HashMap keys and values. E.g. if you have a type HashMap Text Int, the HasCodec instance for Generic deriving will work with the following TOML representation:

fieldName =
    [ { key = "foo", val = 15 }
    , { key = "bar", val = 7  }
    ]

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec (HashMap k v)

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.

Since: 1.1.0.0

Methods

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

Instances

HasItemCodec Bool

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec Double

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec Float

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec Int

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec Integer

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec Natural

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec Word

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec Word8

Since: 1.2.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec Text

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec IntSet

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec Text

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec ZonedTime

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec LocalTime

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec TimeOfDay

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec Day

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec LByteStringAsBytes

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec LByteStringAsText

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec ByteStringAsBytes

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

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

HasItemCodec ByteStringAsText

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

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

(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.

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

(Generic a, GenericCodec (Rep a)) => HasItemCodec (TomlTable a)

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

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

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

Helper class to derive TOML codecs generically.

Since: 1.1.0.0

Methods

genericTomlCodec :: GenericOptions -> TomlCodec (f p)

Instances

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

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

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

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

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

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

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

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

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

Since: 1.1.0.0

Defined in Toml.Codec.Generic

Methods

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

ByteString newtypes

There are two ways to encode ByteString in TOML:

1. Via text.
2. Via an array of integers (aka array of bytes).

To handle all these cases, tomland provides helpful newtypes, specifically:

• ByteStringAsText
• ByteStringAsBytes
• LByteStringAsText
• LByteStringAsBytes

As a bonus, on GHC >= 8.6 you can use these newtypes with the DerivingVia extensions for your own ByteString types.

newtype MyByteString = MyByteString
    { unMyByteString :: ByteString
    } deriving HasCodec via ByteStringAsBytes

newtype ByteStringAsText

Newtype wrapper over ByteString to be used for text values.

Since: 1.3.0.0

Constructors

ByteStringAsText

Fields

• unByteStringAsText :: ByteString

Instances

Eq ByteStringAsText

Defined in Toml.Codec.Generic

Methods

(==) :: ByteStringAsText -> ByteStringAsText -> Bool

(/=) :: ByteStringAsText -> ByteStringAsText -> Bool

Show ByteStringAsText

Defined in Toml.Codec.Generic

Methods

showsPrec :: Int -> ByteStringAsText -> ShowS

show :: ByteStringAsText -> String

showList :: [ByteStringAsText] -> ShowS

HasCodec ByteStringAsText

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec ByteStringAsText

HasItemCodec ByteStringAsText

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

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

newtype ByteStringAsBytes

Newtype wrapper over ByteString to be used for array of integers representation.

Since: 1.3.0.0

Constructors

ByteStringAsBytes

Fields

• unByteStringAsBytes :: ByteString

Instances

Eq ByteStringAsBytes

Defined in Toml.Codec.Generic

Methods

(==) :: ByteStringAsBytes -> ByteStringAsBytes -> Bool

(/=) :: ByteStringAsBytes -> ByteStringAsBytes -> Bool

Show ByteStringAsBytes

Defined in Toml.Codec.Generic

Methods

showsPrec :: Int -> ByteStringAsBytes -> ShowS

show :: ByteStringAsBytes -> String

showList :: [ByteStringAsBytes] -> ShowS

HasCodec ByteStringAsBytes

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec ByteStringAsBytes

HasItemCodec ByteStringAsBytes

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

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

newtype LByteStringAsText

Newtype wrapper over lazy ByteString to be used for text values.

Since: 1.3.0.0

Constructors

LByteStringAsText

Fields

• unLByteStringAsText :: ByteString

Instances

Eq LByteStringAsText

Defined in Toml.Codec.Generic

Methods

(==) :: LByteStringAsText -> LByteStringAsText -> Bool

(/=) :: LByteStringAsText -> LByteStringAsText -> Bool

Show LByteStringAsText

Defined in Toml.Codec.Generic

Methods

showsPrec :: Int -> LByteStringAsText -> ShowS

show :: LByteStringAsText -> String

showList :: [LByteStringAsText] -> ShowS

HasCodec LByteStringAsText

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec LByteStringAsText

HasItemCodec LByteStringAsText

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

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

newtype LByteStringAsBytes

Newtype wrapper over lazy ByteString to be used for array of integers representation.

Since: 1.3.0.0

Constructors

LByteStringAsBytes

Fields

• unLByteStringAsBytes :: ByteString

Instances

Eq LByteStringAsBytes

Defined in Toml.Codec.Generic

Methods

(==) :: LByteStringAsBytes -> LByteStringAsBytes -> Bool

(/=) :: LByteStringAsBytes -> LByteStringAsBytes -> Bool

Show LByteStringAsBytes

Defined in Toml.Codec.Generic

Methods

showsPrec :: Int -> LByteStringAsBytes -> ShowS

show :: LByteStringAsBytes -> String

showList :: [LByteStringAsBytes] -> ShowS

HasCodec LByteStringAsBytes

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec LByteStringAsBytes

HasItemCodec LByteStringAsBytes

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

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

Deriving Via

newtype TomlTable a

newtype for generic deriving of HasCodec typeclass for custom data types that should we wrapped into separate table. Use it only for data types that are fields of another data types.

data Person = Person
    { personName    :: !Text
    , personAddress :: !Address
    } deriving (Generic)

data Address = Address
    { addressStreet :: !Text
    , addressHouse  :: !Int
    } deriving (Generic)
      deriving HasCodec via TomlTable Address

personCodec :: TomlCodec Person
personCodec = stripTypeNameCodec

personCodec corresponds to the TOML of the following structure:

name = "foo"
[address]
    addressStreet = "Bar"
    addressHouse = 42

Since: 1.3.0.0

Constructors

TomlTable

Fields

• unTomlTable :: a

Instances

(Generic a, GenericCodec (Rep a)) => HasCodec (TomlTable a)

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

hasCodec :: Key -> TomlCodec (TomlTable a)

(Generic a, GenericCodec (Rep a)) => HasItemCodec (TomlTable a)

Since: 1.3.0.0

Defined in Toml.Codec.Generic

Methods

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