Toml.FromValue.Matcher

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

Contents

- Types
- Operations
- 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 a
- data Result e a
  - = Failure [e]
  - | Success [e] a
- data MatchMessage = MatchMessage {
  - matchPath :: [Scope]
  - matchMessage :: String
  }
- runMatcher :: Matcher a -> Result MatchMessage a
- withScope :: Scope -> Matcher a -> Matcher a
- getScope :: Matcher [Scope]
- warning :: String -> Matcher ()
- data Scope
  - = ScopeIndex Int
  - | ScopeKey String
- inKey :: String -> Matcher a -> Matcher a
- inIndex :: Int -> Matcher a -> Matcher a

# Types

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

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

# Operations

runMatcher :: Matcher a -> Result MatchMessage a #

Run a `Matcher` with an empty scope.

Since: 1.3.0.0

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

Run a `Matcher` with a locally extended scope.

Since: 1.3.0.0

getScope :: Matcher [Scope] #

Get the current list of scopes.

Since: 1.3.0.0

warning :: String -> Matcher () #

Emit a warning mentioning the current scope.

# Scope helpers

data Scope #

Scopes for TOML message.

Since: 1.3.0.0

Constructors

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

#### Instances

Instances details

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

inKey :: String -> Matcher a -> Matcher a #

Update the scope with the message corresponding to a table key

Since: 1.3.0.0

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

Update the scope with the message corresponding to an array index

Since: 1.3.0.0