Toml.Schema.FromValue

toml-parser-2.0.1.0: TOML 1.0.0 parser

Copyright | (c) Eric Mertens 2023
License | ISC
Maintainer | emertens@gmail.com
Safe Haskell | None
Language | Haskell2010

Toml.Schema.FromValue

Contents

- Deserialization classes
- Containers
- Tables
- Errors

Description

Use `FromValue` to define a transformation from some `Value` to an application domain type.

Use `ParseTable` to help build `FromValue` instances that match tables. It will make it easy to track which table keys have been used and which are left over.

Warnings can be emitted using `warn` and `warnTable` (depending on what) context you're in. These warnings can provide useful feedback about problematic values or keys that might be unused now but were perhaps meaningful in an old version of a configuration file.

Toml.Schema.FromValue.Generic can be used to derive instances of `FromValue` automatically for record types.

Synopsis

- class FromValue a where
  - fromValue :: Value' l -> Matcher l a
  - listFromValue :: Value' l -> Matcher l [a]
- class FromKey a where
  - fromKey :: l -> Text -> Matcher l a
- mapOf :: Ord k => (l -> Text -> Matcher l k) -> (Text -> Value' l -> Matcher l v) -> Value' l -> Matcher l (Map k v)
- listOf :: (Int -> Value' l -> Matcher l a) -> Value' l -> Matcher l [a]
- parseTableFromValue :: ParseTable l a -> Value' l -> Matcher l a
- reqKey :: FromValue a => Text -> ParseTable l a
- reqKeyOf :: Text -> (Value' l -> Matcher l a) -> ParseTable l a
- optKey :: FromValue a => Text -> ParseTable l (Maybe a)
- optKeyOf :: Text -> (Value' l -> Matcher l a) -> ParseTable l (Maybe a)
- typeError :: String -> Value' l -> Matcher l a

# Deserialization classes

class FromValue a where #

Class for types that can be decoded from a TOML value.

Minimal complete definition

fromValue

Methods

fromValue :: Value' l -> Matcher l a #

Convert a `Value` or report an error message

listFromValue :: Value' l -> Matcher l [a] #

Used to implement instance for `[]`. Most implementations rely on the default implementation.

#### Instances

Instances details

FromValue Int16 # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Int16 # listFromValue :: Value' l -> Matcher l [Int16] #
FromValue Int32 # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Int32 # listFromValue :: Value' l -> Matcher l [Int32] #
FromValue Int64 # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Int64 # listFromValue :: Value' l -> Matcher l [Int64] #
FromValue Int8 # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Int8 # listFromValue :: Value' l -> Matcher l [Int8] #
FromValue Word16 # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Word16 # listFromValue :: Value' l -> Matcher l [Word16] #
FromValue Word32 # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Word32 # listFromValue :: Value' l -> Matcher l [Word32] #
FromValue Word64 # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Word64 # listFromValue :: Value' l -> Matcher l [Word64] #
FromValue Word8 # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Word8 # listFromValue :: Value' l -> Matcher l [Word8] #
FromValue Text # | Matches string literals
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Text # listFromValue :: Value' l -> Matcher l [Text] #
FromValue Text # | Matches string literals
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Text # listFromValue :: Value' l -> Matcher l [Text] #
FromValue Day # | Matches local date literals
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Day # listFromValue :: Value' l -> Matcher l [Day] #
FromValue UTCTime # | Matches offset date-time literals and converts to UTC
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l UTCTime # listFromValue :: Value' l -> Matcher l [UTCTime] #
FromValue LocalTime # | Matches local date-time literals
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l LocalTime # listFromValue :: Value' l -> Matcher l [LocalTime] #
FromValue TimeOfDay # | Matches local time literals
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l TimeOfDay # listFromValue :: Value' l -> Matcher l [TimeOfDay] #
FromValue ZonedTime # | Matches offset date-time literals
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l ZonedTime # listFromValue :: Value' l -> Matcher l [ZonedTime] #
FromValue Table # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Table # listFromValue :: Value' l -> Matcher l [Table] #
FromValue Value # | Matches all values, used for pass-through
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Value # listFromValue :: Value' l -> Matcher l [Value] #
FromValue Integer # | Matches integer values
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Integer # listFromValue :: Value' l -> Matcher l [Integer] #
FromValue Natural # | Matches non-negative integer values
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Natural # listFromValue :: Value' l -> Matcher l [Natural] #
FromValue Bool # | Matches `true` and `false`
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Bool # listFromValue :: Value' l -> Matcher l [Bool] #
FromValue Char # | Matches single-character strings with `fromValue` and arbitrary strings with `listFromValue` to support `String`
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Char # listFromValue :: Value' l -> Matcher l [Char] #
FromValue Double # | Matches floating-point and integer values
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Double # listFromValue :: Value' l -> Matcher l [Double] #
FromValue Float # | Matches floating-point and integer values
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Float # listFromValue :: Value' l -> Matcher l [Float] #
FromValue Int # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Int # listFromValue :: Value' l -> Matcher l [Int] #
FromValue Word # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Word # listFromValue :: Value' l -> Matcher l [Word] #
FromValue a => FromValue (Seq a) # | Matches arrays
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l (Seq a) # listFromValue :: Value' l -> Matcher l [Seq a] #
FromValue a => FromValue (NonEmpty a) # | Matches non-empty arrays or reports an error.
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l (NonEmpty a) # listFromValue :: Value' l -> Matcher l [NonEmpty a] #
Integral a => FromValue (Ratio a) # | Matches floating-point and integer values. TOML specifies `Floats should be implemented as IEEE 754 binary64 values.` so note that the given `Rational` will be converted from a double representation and will often be an approximation rather than the exact value.
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l (Ratio a) # listFromValue :: Value' l -> Matcher l [Ratio a] #
(Generic a, GFromArray (Rep a)) => FromValue (GenericTomlArray a) # | Instance derived using `genericFromArray`
Instance details Defined in Toml.Schema.Generic Methods fromValue :: Value' l -> Matcher l (GenericTomlArray a) # listFromValue :: Value' l -> Matcher l [GenericTomlArray a] #
(Generic a, GParseTable (Rep a)) => FromValue (GenericTomlTable a) # | Instance derived using `genericParseTable`
Instance details Defined in Toml.Schema.Generic Methods fromValue :: Value' l -> Matcher l (GenericTomlTable a) # listFromValue :: Value' l -> Matcher l [GenericTomlTable a] #
FromValue a => FromValue [a] # | Implemented in terms of `listFromValue`
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l [a] # listFromValue :: Value' l -> Matcher l [[a]] #
(Ord k, FromKey k, FromValue v) => FromValue (Map k v) # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l (Map k v) # listFromValue :: Value' l -> Matcher l [Map k v] #

class FromKey a where #

Convert from a table key

Methods

fromKey :: l -> Text -> Matcher l a #

#### Instances

Instances details

FromKey Text # | Matches all strings
Instance details Defined in Toml.Schema.FromValue Methods fromKey :: l -> Text -> Matcher l Text #
FromKey Text # | Matches all strings
Instance details Defined in Toml.Schema.FromValue Methods fromKey :: l -> Text -> Matcher l Text #
a ~ Char => FromKey [a] # | Matches all strings
Instance details Defined in Toml.Schema.FromValue Methods fromKey :: l -> Text -> Matcher l [a] #

# Containers

mapOf #

Arguments

:: Ord k |
=> (l -> Text -> Matcher l k) | key matcher
-> (Text -> Value' l -> Matcher l v) | value matcher
-> Value' l |
-> Matcher l (Map k v) |

Table matching function used to help implement `fromValue` for tables. Key matching function is given the annotation of the key for error reporting. Value matching function is given the key in case values can depend on their keys.

listOf :: (Int -> Value' l -> Matcher l a) -> Value' l -> Matcher l [a] #

List matching function used to help implemented `fromValue` for arrays. The element matching function is given the list index in case values can depend on their index.

# Tables

parseTableFromValue :: ParseTable l a -> Value' l -> Matcher l a #

Used to derive a `fromValue` implementation from a `ParseTable` matcher.

reqKey :: FromValue a => Text -> ParseTable l a #

Convenience function for matching a required key with a `FromValue` instance.

    reqKey key = reqKeyOf key fromValue

reqKeyOf #

Arguments

:: Text | key
-> (Value' l -> Matcher l a) | value matcher
-> ParseTable l a |

Match a table entry by key or report an error if missing.

See `pickKey` for more complex cases.

optKey :: FromValue a => Text -> ParseTable l (Maybe a) #

Convenience function for matching an optional key with a `FromValue` instance.

    optKey key = optKeyOf key fromValue

optKeyOf #

Arguments

:: Text | key
-> (Value' l -> Matcher l a) | value matcher
-> ParseTable l (Maybe a) |

Match a table entry by key if it exists or return `Nothing` if not. If the key is defined, it is matched by the given function.

See `pickKey` for more complex cases.

# Errors

typeError #

Arguments

:: String | expected type
-> Value' l | actual value
-> Matcher l a |

Report a type error