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.Matcher

Contents

- Types
- Operations
- Run helpers
- Scope helpers

Description

This type helps to build up computations that can validate a TOML value and compute some application-specific representation.

It supports warning messages which can be used to deprecate old configuration options and to detect unused table keys.

It supports tracking multiple error messages when you have more than one decoding option and all of them have failed.

Use `prettyMatchMessage` for an easy way to make human readable strings from matcher outputs.

Synopsis

- data Matcher l a
- data Result e a
  - = Failure [e]
  - | Success [e] a
- data MatchMessage a = MatchMessage {
  - matchAnn :: Maybe a
  - matchPath :: [Scope]
  - matchMessage :: String
  }
- runMatcher :: Matcher l a -> Result (MatchMessage l) a
- withScope :: Scope -> Matcher l a -> Matcher l a
- getScope :: Matcher a [Scope]
- warn :: String -> Matcher a ()
- warnAt :: l -> String -> Matcher l ()
- failAt :: l -> String -> Matcher l a
- runMatcherIgnoreWarn :: Matcher l a -> Either [MatchMessage l] a
- runMatcherFatalWarn :: Matcher l a -> Either [MatchMessage l] a
- data Scope
  - = ScopeIndex Int
  - | ScopeKey Text
- inKey :: Text -> Matcher l a -> Matcher l a
- inIndex :: Int -> Matcher l a -> Matcher l a

# Types

data Matcher l a Source #

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

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

data Result e a Source #

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.

Constructors

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

#### Instances

Instances details

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

Instance details

Defined in Toml.Schema.Matcher

Methods

compare :: Result e a -> Result e a -> Ordering Source #

(<) :: Result e a -> Result e a -> Bool Source #

(<=) :: Result e a -> Result e a -> Bool Source #

(>) :: Result e a -> Result e a -> Bool Source #

(>=) :: Result e a -> Result e a -> Bool Source #

max :: Result e a -> Result e a -> Result e a Source #

min :: Result e a -> Result e a -> Result e a Source #

data MatchMessage a Source #

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.

For a convenient way to render these to a string, see `prettyMatchMessage`.

Constructors

MatchMessage |

Fields

- matchAnn :: Maybe a
- matchPath :: [Scope]

  path to message location

- matchMessage :: String

  error and warning message body

#### Instances

Instances details

Functor MatchMessage Source # |
Instance details Defined in Toml.Schema.Matcher Methods fmap :: (a -> b) -> MatchMessage a -> MatchMessage b Source # (<$) :: a -> MatchMessage b -> MatchMessage a Source #
Foldable MatchMessage Source # |

Instance details

Defined in Toml.Schema.Matcher

Methods

fold :: Monoid m => MatchMessage m -> m Source #

foldMap :: Monoid m => (a -> m) -> MatchMessage a -> m Source #

foldMap' :: Monoid m => (a -> m) -> MatchMessage a -> m Source #

foldr :: (a -> b -> b) -> b -> MatchMessage a -> b Source #

foldr' :: (a -> b -> b) -> b -> MatchMessage a -> b Source #

foldl :: (b -> a -> b) -> b -> MatchMessage a -> b Source #

foldl' :: (b -> a -> b) -> b -> MatchMessage a -> b Source #

foldr1 :: (a -> a -> a) -> MatchMessage a -> a Source #

foldl1 :: (a -> a -> a) -> MatchMessage a -> a Source #

toList :: MatchMessage a -> [a] Source #

null :: MatchMessage a -> Bool Source #

length :: MatchMessage a -> Int Source #

elem :: Eq a => a -> MatchMessage a -> Bool Source #

maximum :: Ord a => MatchMessage a -> a Source #

minimum :: Ord a => MatchMessage a -> a Source #

sum :: Num a => MatchMessage a -> a Source #

product :: Num a => MatchMessage a -> a Source #

Traversable MatchMessage Source # |
Instance details Defined in Toml.Schema.Matcher Methods traverse :: Applicative f => (a -> f b) -> MatchMessage a -> f (MatchMessage b) Source # sequenceA :: Applicative f => MatchMessage (f a) -> f (MatchMessage a) Source # mapM :: Monad m => (a -> m b) -> MatchMessage a -> m (MatchMessage b) Source # sequence :: Monad m => MatchMessage (m a) -> m (MatchMessage a) Source #
Read a => Read (MatchMessage a) Source # | Default instance
Instance details Defined in Toml.Schema.Matcher Methods readsPrec :: Int -> ReadS (MatchMessage a) Source # readList :: ReadS [MatchMessage a] Source # readPrec :: ReadPrec (MatchMessage a) Source # readListPrec :: ReadPrec [MatchMessage a] Source #
Show a => Show (MatchMessage a) Source # | Default instance
Instance details Defined in Toml.Schema.Matcher Methods showsPrec :: Int -> MatchMessage a -> ShowS Source # show :: MatchMessage a -> String Source # showList :: [MatchMessage a] -> ShowS Source #
Eq a => Eq (MatchMessage a) Source # | Default instance
Instance details Defined in Toml.Schema.Matcher Methods (==) :: MatchMessage a -> MatchMessage a -> Bool Source # (/=) :: MatchMessage a -> MatchMessage a -> Bool Source #
Ord a => Ord (MatchMessage a) Source # | Default instance

Instance details

Defined in Toml.Schema.Matcher

Methods

compare :: MatchMessage a -> MatchMessage a -> Ordering Source #

(<) :: MatchMessage a -> MatchMessage a -> Bool Source #

(<=) :: MatchMessage a -> MatchMessage a -> Bool Source #

(>) :: MatchMessage a -> MatchMessage a -> Bool Source #

(>=) :: MatchMessage a -> MatchMessage a -> Bool Source #

max :: MatchMessage a -> MatchMessage a -> MatchMessage a Source #

min :: MatchMessage a -> MatchMessage a -> MatchMessage a Source #

# Operations

runMatcher :: Matcher l a -> Result (MatchMessage l) a Source #

Run a `Matcher` with an empty scope.

withScope :: Scope -> Matcher l a -> Matcher l a Source #

Run a `Matcher` with a locally extended scope.

getScope :: Matcher a [Scope] Source #

Get the current list of scopes.

warn :: String -> Matcher a () Source #

Emit a warning without an annotation.

warnAt :: l -> String -> Matcher l () Source #

Emit a warning mentioning the given annotation.

failAt :: l -> String -> Matcher l a Source #

Terminate the match with an error mentioning the given annotation.

# Run helpers

runMatcherIgnoreWarn :: Matcher l a -> Either [MatchMessage l] a Source #

Run `Matcher` and ignore warnings.

runMatcherFatalWarn :: Matcher l a -> Either [MatchMessage l] a Source #

Run `Matcher` and treat warnings as errors.

# Scope helpers

data Scope Source #

Scopes for TOML message.

Constructors

ScopeIndex Int | zero-based array index
ScopeKey Text | key in a table

#### Instances

Instances details

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

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

Update the scope with the message corresponding to a table key

inIndex :: Int -> Matcher l a -> Matcher l a Source #

Update the scope with the message corresponding to an array index