toml-parser-1.3.0.0: TOML 1.0.0 parser

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

Toml.FromValue

Contents

- Deserialization classes
- Matcher
- Table matching
- Table matching primitives

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 `warning` and `warnTable` (depending on what) context you're in. These warnings can provide useful feedback about problematic decodings or keys that might be unused now but were perhaps meaningful in an old version of a configuration file.

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

Synopsis

- class FromValue a where
  - fromValue :: Value -> Matcher a
  - listFromValue :: Value -> Matcher [a]
- class FromKey a where
  - fromKey :: String -> Matcher a
- data Matcher a
- data MatchMessage = MatchMessage {
  - matchPath :: [Scope]
  - matchMessage :: String
  }
- data Result e a
  - = Failure [e]
  - | Success [e] a
- warning :: String -> Matcher ()
- data ParseTable a
- runParseTable :: ParseTable a -> Table -> Matcher a
- parseTableFromValue :: ParseTable a -> Value -> Matcher a
- reqKey :: FromValue a => String -> ParseTable a
- optKey :: FromValue a => String -> ParseTable (Maybe a)
- reqKeyOf :: String -> (Value -> Matcher a) -> ParseTable a
- optKeyOf :: String -> (Value -> Matcher a) -> ParseTable (Maybe a)
- warnTable :: String -> ParseTable ()
- data KeyAlt a
  - = Key String (Value -> Matcher a)
  - | Else (Matcher a)
- pickKey :: [KeyAlt a] -> ParseTable a
- getTable :: ParseTable Table
- setTable :: Table -> ParseTable ()
- liftMatcher :: Matcher a -> ParseTable 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 -> Matcher a #

Convert a `Value` or report an error message

listFromValue :: Value -> Matcher [a] #

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

#### Instances

Instances details

FromValue Int16 # |
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Int16 # listFromValue :: Value -> Matcher [Int16] #
FromValue Int32 # |
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Int32 # listFromValue :: Value -> Matcher [Int32] #
FromValue Int64 # |
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Int64 # listFromValue :: Value -> Matcher [Int64] #
FromValue Int8 # |
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Int8 # listFromValue :: Value -> Matcher [Int8] #
FromValue Word16 # |
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Word16 # listFromValue :: Value -> Matcher [Word16] #
FromValue Word32 # |
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Word32 # listFromValue :: Value -> Matcher [Word32] #
FromValue Word64 # |
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Word64 # listFromValue :: Value -> Matcher [Word64] #
FromValue Word8 # |
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Word8 # listFromValue :: Value -> Matcher [Word8] #
FromValue Text # | Matches string literals Since: 1.2.1.0
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Text # listFromValue :: Value -> Matcher [Text] #
FromValue Text # | Matches string literals Since: 1.2.1.0
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Text # listFromValue :: Value -> Matcher [Text] #
FromValue Day # | Matches local date literals
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Day # listFromValue :: Value -> Matcher [Day] #
FromValue LocalTime # | Matches local date-time literals
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher LocalTime # listFromValue :: Value -> Matcher [LocalTime] #
FromValue TimeOfDay # | Matches local time literals
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher TimeOfDay # listFromValue :: Value -> Matcher [TimeOfDay] #
FromValue ZonedTime # | Matches offset date-time literals
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher ZonedTime # listFromValue :: Value -> Matcher [ZonedTime] #
FromValue Value # | Matches all values, used for pass-through
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Value # listFromValue :: Value -> Matcher [Value] #
FromValue Integer # | Matches integer values
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Integer # listFromValue :: Value -> Matcher [Integer] #
FromValue Natural # | Matches non-negative integer values
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Natural # listFromValue :: Value -> Matcher [Natural] #
FromValue Bool # | Matches `true` and `false`
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Bool # listFromValue :: Value -> Matcher [Bool] #
FromValue Char # | Matches single-character strings with `fromValue` and arbitrary strings with `listFromValue` to support `String`
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Char # listFromValue :: Value -> Matcher [Char] #
FromValue Double # | Matches floating-point and integer values
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Double # listFromValue :: Value -> Matcher [Double] #
FromValue Float # | Matches floating-point and integer values
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Float # listFromValue :: Value -> Matcher [Float] #
FromValue Int # |
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Int # listFromValue :: Value -> Matcher [Int] #
FromValue Word # |
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher Word # listFromValue :: Value -> Matcher [Word] #
FromValue a => FromValue (NonEmpty a) # | Matches non-empty arrays or reports an error. Since: 1.3.0.0
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher (NonEmpty a) # listFromValue :: Value -> Matcher [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. Since: 1.3.0.0
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher (Ratio a) # listFromValue :: Value -> Matcher [Ratio a] #
FromValue a => FromValue (Seq a) # | Matches arrays Since: 1.3.0.0
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher (Seq a) # listFromValue :: Value -> Matcher [Seq a] #
FromValue a => FromValue [a] # | Implemented in terms of `listFromValue`
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher [a] # listFromValue :: Value -> Matcher [[a]] #
(Ord k, FromKey k, FromValue v) => FromValue (Map k v) # |
Instance details Defined in Toml.FromValue Methods fromValue :: Value -> Matcher (Map k v) # listFromValue :: Value -> Matcher [Map k v] #

class FromKey a where #

Convert from a table key

Since: 1.3.0.0

Methods

fromKey :: String -> Matcher a #

#### Instances

Instances details

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

# Matcher

data Matcher a #

Computations that result in a `Result` and which track a list of nested contexts to assist in generating warnings and error messages.

Use `withScope` to run a `Matcher` in a new, nested scope.

#### Instances

Instances details

MonadFail Matcher # | Fail with an error message annotated to the current location.
Instance details Defined in Toml.FromValue.Matcher Methods fail :: String -> Matcher a
Alternative Matcher # |
Instance details Defined in Toml.FromValue.Matcher Methods empty :: Matcher a (<|>) :: Matcher a -> Matcher a -> Matcher a some :: Matcher a -> Matcher [a] many :: Matcher a -> Matcher [a]
Applicative Matcher # |
Instance details Defined in Toml.FromValue.Matcher Methods pure :: a -> Matcher a (<*>) :: Matcher (a -> b) -> Matcher a -> Matcher b liftA2 :: (a -> b -> c) -> Matcher a -> Matcher b -> Matcher c (*>) :: Matcher a -> Matcher b -> Matcher b (<*) :: Matcher a -> Matcher b -> Matcher a
Functor Matcher # |
Instance details Defined in Toml.FromValue.Matcher Methods fmap :: (a -> b) -> Matcher a -> Matcher b (<$) :: a -> Matcher b -> Matcher a
Monad Matcher # |
Instance details Defined in Toml.FromValue.Matcher Methods (>>=) :: Matcher a -> (a -> Matcher b) -> Matcher b (>>) :: Matcher a -> Matcher b -> Matcher b return :: a -> Matcher a
MonadPlus Matcher # |
Instance details Defined in Toml.FromValue.Matcher Methods mzero :: Matcher a mplus :: Matcher a -> Matcher a -> Matcher a

data MatchMessage #

A message emitted while matching a TOML value. The message is paired with the path to the value that was in focus when the message was generated. These message get used for both warnings and errors.

Since: 1.3.0.0

Constructors

MatchMessage |

Fields

- matchPath :: [Scope]

  path to message location

- matchMessage :: String

  error and warning message body

#### Instances

Instances details

Read MatchMessage # | Default instance
Instance details Defined in Toml.FromValue.Matcher Methods readsPrec :: Int -> ReadS MatchMessage readList :: ReadS [MatchMessage] readPrec :: ReadPrec MatchMessage readListPrec :: ReadPrec [MatchMessage]
Show MatchMessage # | Default instance
Instance details Defined in Toml.FromValue.Matcher Methods showsPrec :: Int -> MatchMessage -> ShowS show :: MatchMessage -> String showList :: [MatchMessage] -> ShowS
Eq MatchMessage # | Default instance
Instance details Defined in Toml.FromValue.Matcher Methods (==) :: MatchMessage -> MatchMessage -> Bool (/=) :: MatchMessage -> MatchMessage -> Bool
Ord MatchMessage # | Default instance
Instance details Defined in Toml.FromValue.Matcher Methods compare :: MatchMessage -> MatchMessage -> Ordering (<) :: MatchMessage -> MatchMessage -> Bool (<=) :: MatchMessage -> MatchMessage -> Bool (>) :: MatchMessage -> MatchMessage -> Bool (>=) :: MatchMessage -> MatchMessage -> Bool max :: MatchMessage -> MatchMessage -> MatchMessage min :: MatchMessage -> MatchMessage -> MatchMessage

data Result e a #

Computation outcome with error and warning messages. Multiple error messages can occur when multiple alternatives all fail. Resolving any one of the error messages could allow the computation to succeed.

Since: 1.3.0.0

Constructors

Failure [e] | error messages
Success [e] a | warning messages and result

#### Instances

Instances details

(Read e, Read a) => Read (Result e a) # | Default instance
Instance details Defined in Toml.FromValue.Matcher Methods readsPrec :: Int -> ReadS (Result e a) readList :: ReadS [Result e a] readPrec :: ReadPrec (Result e a) readListPrec :: ReadPrec [Result e a]
(Show e, Show a) => Show (Result e a) # | Default instance
Instance details Defined in Toml.FromValue.Matcher Methods showsPrec :: Int -> Result e a -> ShowS show :: Result e a -> String showList :: [Result e a] -> ShowS
(Eq e, Eq a) => Eq (Result e a) # | Default instance
Instance details Defined in Toml.FromValue.Matcher Methods (==) :: Result e a -> Result e a -> Bool (/=) :: Result e a -> Result e a -> Bool
(Ord e, Ord a) => Ord (Result e a) # | Default instance
Instance details Defined in Toml.FromValue.Matcher Methods compare :: Result e a -> Result e a -> Ordering (<) :: Result e a -> Result e a -> Bool (<=) :: Result e a -> Result e a -> Bool (>) :: Result e a -> Result e a -> Bool (>=) :: Result e a -> Result e a -> Bool max :: Result e a -> Result e a -> Result e a min :: Result e a -> Result e a -> Result e a

warning :: String -> Matcher () #

Emit a warning mentioning the current scope.

# Table matching

data ParseTable a #

A `Matcher` that tracks a current set of unmatched key-value pairs from a table.

Use `optKey` and `reqKey` to extract keys.

Use `getTable` and `setTable` to override the table and implement other primitives.

#### Instances

Instances details

MonadFail ParseTable # | Implemented in terms of `fail` on `Matcher`
Instance details Defined in Toml.FromValue.ParseTable Methods fail :: String -> ParseTable a
Alternative ParseTable # |
Instance details Defined in Toml.FromValue.ParseTable Methods empty :: ParseTable a (<|>) :: ParseTable a -> ParseTable a -> ParseTable a some :: ParseTable a -> ParseTable [a] many :: ParseTable a -> ParseTable [a]
Applicative ParseTable # |
Instance details Defined in Toml.FromValue.ParseTable Methods pure :: a -> ParseTable a (<*>) :: ParseTable (a -> b) -> ParseTable a -> ParseTable b liftA2 :: (a -> b -> c) -> ParseTable a -> ParseTable b -> ParseTable c (*>) :: ParseTable a -> ParseTable b -> ParseTable b (<*) :: ParseTable a -> ParseTable b -> ParseTable a
Functor ParseTable # |
Instance details Defined in Toml.FromValue.ParseTable Methods fmap :: (a -> b) -> ParseTable a -> ParseTable b (<$) :: a -> ParseTable b -> ParseTable a
Monad ParseTable # |
Instance details Defined in Toml.FromValue.ParseTable Methods (>>=) :: ParseTable a -> (a -> ParseTable b) -> ParseTable b (>>) :: ParseTable a -> ParseTable b -> ParseTable b return :: a -> ParseTable a
MonadPlus ParseTable # |
Instance details Defined in Toml.FromValue.ParseTable Methods mzero :: ParseTable a mplus :: ParseTable a -> ParseTable a -> ParseTable a

runParseTable :: ParseTable a -> Table -> Matcher a #

Run a `ParseTable` computation with a given starting `Table`. Unused tables will generate a warning. To change this behavior `getTable` and `setTable` can be used to discard or generate error messages.

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

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

reqKey :: FromValue a => String -> ParseTable a #

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

    reqKey key = reqKeyOf key fromValue

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

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

    optKey key = optKeyOf key fromValue

reqKeyOf #

Arguments

:: String | key
-> (Value -> Matcher a) | value matcher
-> ParseTable a |

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

See `pickKey` for more complex cases.

optKeyOf #

Arguments

:: String | key
-> (Value -> Matcher a) | value matcher
-> ParseTable (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.

warnTable :: String -> ParseTable () #

Emit a warning at the current location.

data KeyAlt a #

Key and value matching function

Since: 1.2.0.0

Constructors

Key String (Value -> Matcher a) | pick alternative based on key match
Else (Matcher a) | default case when no previous cases matched

pickKey :: [KeyAlt a] -> ParseTable a #

Take the first option from a list of table keys and matcher functions. This operation will commit to the first table key that matches. If the associated matcher fails, only that error will be propagated and the other alternatives will not be matched.

If no keys match, an error message is generated explaining which keys would have been accepted.

This is provided as an alternative to chaining multiple `reqKey` cases together with `(`<|>`)` because that will generate one error message for each unmatched alternative as well as the error associate with the matched alternative.

Since: 1.2.0.0

# Table matching primitives

getTable :: ParseTable Table #

Return the remaining portion of the table being matched.

setTable :: Table -> ParseTable () #

Replace the remaining portion of the table being matched.

liftMatcher :: Matcher a -> ParseTable a #

Lift a matcher into the current table parsing context.