toml-parser-1.3.0.0: TOML 1.0.0 parser
Copyright(c) Eric Mertens 2023
LicenseISC
Maintaineremertens@gmail.com
Safe HaskellSafe-Inferred
LanguageHaskell2010

Toml.FromValue

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

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

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

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

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

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

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.