toml-parser-2.0.2.0: TOML 1.1.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 Source #

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

Minimal complete definition

fromValue

Methods

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

Convert a `Value` or report an error message

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

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

#### Instances

Instances details

FromValue Int16 Source # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Int16 Source # listFromValue :: Value' l -> Matcher l [Int16] Source #
FromValue Int32 Source # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Int32 Source # listFromValue :: Value' l -> Matcher l [Int32] Source #
FromValue Int64 Source # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Int64 Source # listFromValue :: Value' l -> Matcher l [Int64] Source #
FromValue Int8 Source # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Int8 Source # listFromValue :: Value' l -> Matcher l [Int8] Source #
FromValue Word16 Source # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Word16 Source # listFromValue :: Value' l -> Matcher l [Word16] Source #
FromValue Word32 Source # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Word32 Source # listFromValue :: Value' l -> Matcher l [Word32] Source #
FromValue Word64 Source # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Word64 Source # listFromValue :: Value' l -> Matcher l [Word64] Source #
FromValue Word8 Source # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Word8 Source # listFromValue :: Value' l -> Matcher l [Word8] Source #
FromValue Text Source # | Matches string literals
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Text Source # listFromValue :: Value' l -> Matcher l [Text] Source #
FromValue Text Source # | Matches string literals
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Text Source # listFromValue :: Value' l -> Matcher l [Text] Source #
FromValue Day Source # | Matches local date literals
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Day Source # listFromValue :: Value' l -> Matcher l [Day] Source #
FromValue UTCTime Source # | Matches offset date-time literals and converts to UTC
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l UTCTime Source # listFromValue :: Value' l -> Matcher l [UTCTime] Source #
FromValue LocalTime Source # | Matches local date-time literals
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l LocalTime Source # listFromValue :: Value' l -> Matcher l [LocalTime] Source #
FromValue TimeOfDay Source # | Matches local time literals
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l TimeOfDay Source # listFromValue :: Value' l -> Matcher l [TimeOfDay] Source #
FromValue ZonedTime Source # | Matches offset date-time literals
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l ZonedTime Source # listFromValue :: Value' l -> Matcher l [ZonedTime] Source #
FromValue Table Source # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Table Source # listFromValue :: Value' l -> Matcher l [Table] Source #
FromValue Value Source # | Matches all values, used for pass-through
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Value Source # listFromValue :: Value' l -> Matcher l [Value] Source #
FromValue Integer Source # | Matches integer values
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Integer Source # listFromValue :: Value' l -> Matcher l [Integer] Source #
FromValue Natural Source # | Matches non-negative integer values
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Natural Source # listFromValue :: Value' l -> Matcher l [Natural] Source #
FromValue Bool Source # | Matches `true` and `false`
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Bool Source # listFromValue :: Value' l -> Matcher l [Bool] Source #
FromValue Char Source # | 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 Source # listFromValue :: Value' l -> Matcher l [Char] Source #
FromValue Double Source # | Matches floating-point and integer values
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Double Source # listFromValue :: Value' l -> Matcher l [Double] Source #
FromValue Float Source # | Matches floating-point and integer values
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Float Source # listFromValue :: Value' l -> Matcher l [Float] Source #
FromValue Int Source # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Int Source # listFromValue :: Value' l -> Matcher l [Int] Source #
FromValue Word Source # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Word Source # listFromValue :: Value' l -> Matcher l [Word] Source #
FromValue a => FromValue (Seq a) Source # | Matches arrays
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l (Seq a) Source # listFromValue :: Value' l -> Matcher l [Seq a] Source #
FromValue a => FromValue (NonEmpty a) Source # | Matches non-empty arrays or reports an error.
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l (NonEmpty a) Source # listFromValue :: Value' l -> Matcher l [NonEmpty a] Source #
Integral a => FromValue (Ratio a) Source # | 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) Source # listFromValue :: Value' l -> Matcher l [Ratio a] Source #
(Generic a, GFromArray (Rep a)) => FromValue (GenericTomlArray a) Source # | Instance derived using `genericFromArray`
Instance details Defined in Toml.Schema.Generic Methods fromValue :: Value' l -> Matcher l (GenericTomlArray a) Source # listFromValue :: Value' l -> Matcher l [GenericTomlArray a] Source #
(Generic a, GParseTable (Rep a)) => FromValue (GenericTomlTable a) Source # | Instance derived using `genericParseTable`
Instance details Defined in Toml.Schema.Generic Methods fromValue :: Value' l -> Matcher l (GenericTomlTable a) Source # listFromValue :: Value' l -> Matcher l [GenericTomlTable a] Source #
FromValue a => FromValue [a] Source # | Implemented in terms of `listFromValue`
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l [a] Source # listFromValue :: Value' l -> Matcher l [[a]] Source #
(Ord k, FromKey k, FromValue v) => FromValue (Map k v) Source # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l (Map k v) Source # listFromValue :: Value' l -> Matcher l [Map k v] Source #

class FromKey a where Source #

Convert from a table key

Methods

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

#### Instances

Instances details

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

# Containers

mapOf Source #

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] Source #

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 Source #

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

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

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

    reqKey key = reqKeyOf key fromValue

reqKeyOf Source #

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) Source #

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

    optKey key = optKeyOf key fromValue

optKeyOf Source #

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 Source #

Arguments

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

Report a type error