Copyright | (c) Eric Mertens 2023 |
---|---|
License | ISC |
Maintainer | emertens@gmail.com |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
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
- class FromValue a where
- class FromKey a where
- data Matcher a
- data MatchMessage = MatchMessage {
- matchPath :: [Scope]
- matchMessage :: String
- data Result 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
- pickKey :: [KeyAlt a] -> ParseTable a
- getTable :: ParseTable Table
- setTable :: Table -> ParseTable ()
- liftMatcher :: Matcher a -> ParseTable a
Deserialization classes
Class for types that can be decoded from a TOML value.
Minimal complete definition
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
FromValue Int16 # | |
Defined in Toml.FromValue | |
FromValue Int32 # | |
Defined in Toml.FromValue | |
FromValue Int64 # | |
Defined in Toml.FromValue | |
FromValue Int8 # | |
Defined in Toml.FromValue | |
FromValue Word16 # | |
Defined in Toml.FromValue | |
FromValue Word32 # | |
Defined in Toml.FromValue | |
FromValue Word64 # | |
Defined in Toml.FromValue | |
FromValue Word8 # | |
Defined in Toml.FromValue | |
FromValue Text # | Matches string literals Since: 1.2.1.0 |
Defined in Toml.FromValue | |
FromValue Text # | Matches string literals Since: 1.2.1.0 |
Defined in Toml.FromValue | |
FromValue Day # | Matches local date literals |
Defined in Toml.FromValue | |
FromValue LocalTime # | Matches local date-time literals |
Defined in Toml.FromValue | |
FromValue TimeOfDay # | Matches local time literals |
Defined in Toml.FromValue | |
FromValue ZonedTime # | Matches offset date-time literals |
Defined in Toml.FromValue | |
FromValue Value # | Matches all values, used for pass-through |
FromValue Integer # | Matches integer values |
Defined in Toml.FromValue | |
FromValue Natural # | Matches non-negative integer values |
Defined in Toml.FromValue | |
FromValue Bool # | Matches |
Defined in Toml.FromValue | |
FromValue Char # | Matches single-character strings with |
Defined in Toml.FromValue | |
FromValue Double # | Matches floating-point and integer values |
Defined in Toml.FromValue | |
FromValue Float # | Matches floating-point and integer values |
Defined in Toml.FromValue | |
FromValue Int # | |
Defined in Toml.FromValue | |
FromValue Word # | |
Defined in Toml.FromValue | |
FromValue a => FromValue (NonEmpty a) # | Matches non-empty arrays or reports an error. Since: 1.3.0.0 |
Defined in Toml.FromValue | |
Integral a => FromValue (Ratio a) # | Matches floating-point and integer values. TOML specifies Since: 1.3.0.0 |
Defined in Toml.FromValue | |
FromValue a => FromValue (Seq a) # | Matches arrays Since: 1.3.0.0 |
Defined in Toml.FromValue | |
FromValue a => FromValue [a] # | Implemented in terms of |
Defined in Toml.FromValue | |
(Ord k, FromKey k, FromValue v) => FromValue (Map k v) # | |
Defined in Toml.FromValue |
Convert from a table key
Since: 1.3.0.0
Instances
FromKey Text # | Matches all strings Since: 1.3.0.0 |
Defined in Toml.FromValue | |
FromKey Text # | Matches all strings Since: 1.3.0.0 |
Defined in Toml.FromValue | |
a ~ Char => FromKey [a] # | Matches all strings Since: 1.3.0.0 |
Defined in Toml.FromValue |
Matcher
Computations that result in a Result
and which track a list
of nested contexts to assist in generating warnings and error
messages.
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
Read MatchMessage # | Default instance |
Defined in Toml.FromValue.Matcher Methods readsPrec :: Int -> ReadS MatchMessage readList :: ReadS [MatchMessage] readPrec :: ReadPrec MatchMessage readListPrec :: ReadPrec [MatchMessage] | |
Show MatchMessage # | Default instance |
Defined in Toml.FromValue.Matcher Methods showsPrec :: Int -> MatchMessage -> ShowS show :: MatchMessage -> String showList :: [MatchMessage] -> ShowS | |
Eq MatchMessage # | Default instance |
Defined in Toml.FromValue.Matcher | |
Ord MatchMessage # | Default instance |
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 |
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
Instances
(Read e, Read a) => Read (Result e a) # | Default instance |
Defined in Toml.FromValue.Matcher | |
(Show e, Show a) => Show (Result e a) # | Default instance |
(Eq e, Eq a) => Eq (Result e a) # | Default instance |
(Ord e, Ord a) => Ord (Result e a) # | Default instance |
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
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 #
optKey :: FromValue a => String -> ParseTable (Maybe a) #
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.
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.
Key and value matching function
Since: 1.2.0.0
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.