toml package:tomland

This module reexports all functionality of the tomland package. It's recommended to import this module qualified, like this:

import Toml (TomlCodec, (.=))
import qualified Toml

Simple TomlCodec for a Haskell value, that can be decoded from TOML or encoded as TOML, could be written in the following way:

data User = User
{ userName :: Text
, userAge  :: Int
}

userCodec :: TomlCodec User
userCodec = User
<$> Toml.text "name" .= userName
<*> Toml.int  "age"  .= userAge

A value of such type will look in TOML like this:

name = Alice
age  = 27

For more detailed examples see README.md in the repository:

• tomland/README.md

For the details of the library implementation see blog post:

• tomland: Bidirectional TOML serialization

Type of TOML AST. This is intermediate representation of TOML parsed from text.

Represents TOML configuration value. For example, if we have the following TOML file:

server.port        = 8080
server.codes       = [ 5, 10, 42 ]
server.description = "This is production server."

[mail]
host = "smtp.gmail.com"
send-if-inactive = false

[[user]]
id = 42

[[user]]
name = "Foo Bar"

corresponding TOML looks like:

TOML
{ tomlPairs = fromList
[ ( "server" :| [ "port" ] , Integer 8080)
, ( "server" :| [ "codes" ] , Array [ Integer 5 , Integer 10 , Integer 42])
, ( "server" :| [ "description" ] , Text "This is production server.")
]
, tomlTables = fromList
[ ( "mail"
, Leaf ( "mail" :| [] )
( TOML
{ tomlPairs = fromList
[ ( "host" :| [] , Text "smtp.gmail.com")
, ( "send-if-inactive" :| [] , Bool False)
]
, tomlTables = fromList []
, tomlTableArrays = fromList []
}
)
)
]
, tomlTableArrays = fromList
[ ( "user" :| []
, TOML
{ tomlPairs = fromList [( "id" :| [] , Integer 42)]
, tomlTables = fromList []
, tomlTableArrays = fromList []
} :|
[ TOML
{ tomlPairs = fromList [( "name" :| [] , Text "Foo Bar")]
, tomlTables = fromList []
, tomlTableArrays = fromList []
}
]
)
]
}

Bidirectional TOML serialization Implementation of bidirectional TOML serialization. Simple codecs look like this:

data User = User
{ userName :: Text
, userAge  :: Int
}

userCodec :: TomlCodec User
userCodec = User
<$> Toml.text "name" .= userName
<*> Toml.int  "age"  .= userAge

The following blog post has more details about library design:

• tomland: Bidirectional TOML serialization

Parser for the full content of the .toml file.

Difference of two TOMLs. Returns elements of the first TOML that are not existing in the second one.

BiMap specialized to TOML error.

Type of errors for TOML BiMap.

Type of exception for converting from TOML to user custom data type.

Options to configure various parameters of generic encoding. Specifically:

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

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

newtype for generic deriving of HasCodec typeclass for custom data types that should be wrapped into a separate table. Similar to TomlTable but also strips the data type name prefix from TOML keys. personCodec from the TomlTable comment corresponds to the TOML of the following structure:

name = "foo"
[address]
street = "Bar"
house = 42

Specialied Codec type alias for bidirectional TOML serialization. Keeps TOML object as both environment and state.

Immutable environment for TOML conversion.

Mutable context for TOML conversion. We are introducing our own implemetation of state with MonadState instance due to some limitation in the design connected to the usage of State. This newtype is equivalent to the following transformer:

MaybeT (State TOML)

Pretty parse exception for parsing toml.