config-schema-1.3.0.0: Schema definitions for the config-value package

Copyright | (c) Eric Mertens 2019
License | ISC
Maintainer | emertens@gmail.com
Safe Haskell | None
Language | Haskell2010

Config.Schema.Load.Error

Contents

- Error types
- Detailed rendering
- Summaries

Description

This module provides a complete skeleton of the failures that occurred when trying to match a `Value` against a `ValueSpec` allowing custom error rendering to be implemented.

The structure is you get a single value and a list of one-or-more primitive specifications that it failed to match along with an enumeration of why that specification failed to match. Some failures are due to failures in nested specifications, so the whole error structure can form a tree.

Synopsis

- data ValueSpecMismatch p = ValueSpecMismatch p Text (NonEmpty (PrimMismatch p))
- data PrimMismatch p = PrimMismatch Text (Problem p)
- data Problem p
  - = MissingSection Text
  - | UnusedSections (NonEmpty Text)
  - | SubkeyProblem Text (ValueSpecMismatch p)
  - | ListElementProblem Int (ValueSpecMismatch p)
  - | NestedProblem (ValueSpecMismatch p)
  - | TypeMismatch
  - | CustomProblem Text
  - | WrongExact
- class (Typeable a, Show a) => ErrorAnnotation a where
  - displayAnnotation :: a -> Doc
- prettyValueSpecMismatch :: ErrorAnnotation p => ValueSpecMismatch p -> Doc
- prettyPrimMismatch :: ErrorAnnotation p => PrimMismatch p -> Doc
- prettyProblem :: ErrorAnnotation p => Problem p -> (Doc, Doc)
- describeSpec :: PrimValueSpec a -> Text
- describeValue :: Value p -> Text
- simplifyValueSpecMismatch :: ValueSpecMismatch p -> ValueSpecMismatch p

# Error types

data ValueSpecMismatch p Source #

Newtype wrapper for schema load errors.

Since: 1.2.0.0

Constructors

ValueSpecMismatch p Text (NonEmpty (PrimMismatch p)) | Problem value and list of specification failures

#### Instances

Instances details

ErrorAnnotation p => Exception (ValueSpecMismatch p) Source # | `displayException` implemented with `prettyValueSpecMismatch` and `simplifyValueSpecMismatch`. Since: 1.2.0.0
Instance details Defined in Config.Schema.Load.Error Methods toException :: ValueSpecMismatch p -> SomeException Source # fromException :: SomeException -> Maybe (ValueSpecMismatch p) Source # displayException :: ValueSpecMismatch p -> String Source # backtraceDesired :: ValueSpecMismatch p -> Bool Source #
Show p => Show (ValueSpecMismatch p) Source # |
Instance details Defined in Config.Schema.Load.Error Methods showsPrec :: Int -> ValueSpecMismatch p -> ShowS Source # show :: ValueSpecMismatch p -> String Source # showList :: [ValueSpecMismatch p] -> ShowS Source #

data PrimMismatch p Source #

Type for errors that can be encountered while decoding a value according to a specification. The error includes a key path indicating where in the configuration file the error occurred.

Since: 1.2.0.0

Constructors

PrimMismatch Text (Problem p) | spec description and problem

#### Instances

Instances details

Show p => Show (PrimMismatch p) Source # |
Instance details Defined in Config.Schema.Load.Error Methods showsPrec :: Int -> PrimMismatch p -> ShowS Source # show :: PrimMismatch p -> String Source # showList :: [PrimMismatch p] -> ShowS Source #

data Problem p Source #

Problems that can be encountered when matching a `Value` against a `ValueSpec`.

Since: 1.2.0.0

Constructors

MissingSection Text | missing section name
UnusedSections (NonEmpty Text) | unused section names
SubkeyProblem Text (ValueSpecMismatch p) | nested error in given section
ListElementProblem Int (ValueSpecMismatch p) | nested error in given list element
NestedProblem (ValueSpecMismatch p) | generic nested error
TypeMismatch | value and spec type mismatch
CustomProblem Text | custom spec error message
WrongExact | values didn't match

#### Instances

Instances details

Show p => Show (Problem p) Source # |
Instance details Defined in Config.Schema.Load.Error Methods showsPrec :: Int -> Problem p -> ShowS Source # show :: Problem p -> String Source # showList :: [Problem p] -> ShowS Source #

class (Typeable a, Show a) => ErrorAnnotation a where Source #

Class for rendering position annotations within the `prettyValueSpecMismatch`

Since: 1.2.0.0

Methods

displayAnnotation :: a -> Doc Source #

#### Instances

Instances details

ErrorAnnotation FilePosition Source # |
Instance details Defined in Config.Schema.Load.Error Methods displayAnnotation :: FilePosition -> Doc Source #
ErrorAnnotation Position Source # | Renders a `Position` as `line:column:` Since: 1.2.0.0
Instance details Defined in Config.Schema.Load.Error Methods displayAnnotation :: Position -> Doc Source #
ErrorAnnotation () Source # | Renders as an empty document Since: 1.2.0.0
Instance details Defined in Config.Schema.Load.Error Methods displayAnnotation :: () -> Doc Source #

# Detailed rendering

prettyValueSpecMismatch :: ErrorAnnotation p => ValueSpecMismatch p -> Doc Source #

Pretty-printer for `ValueSpecMismatch` showing the position and type of value that failed to match along with details about each specification that it didn't match.

Since: 1.2.0.0

prettyPrimMismatch :: ErrorAnnotation p => PrimMismatch p -> Doc Source #

Pretty-printer for `PrimMismatch` showing a summary of the primitive specification that didn't match followed by a more detailed error when appropriate.

Since: 1.2.0.0

prettyProblem Source #

Arguments

:: ErrorAnnotation p |
=> Problem p |
-> (Doc, Doc) | summary, detailed

Pretty-printer for `Problem` that generates a summary line as well as a detailed description (depending on the error)

Since: 1.2.0.0

# Summaries

describeSpec :: PrimValueSpec a -> Text Source #

Describe outermost shape of a `PrimValueSpec`

Since: 1.2.0.0

describeValue :: Value p -> Text Source #

Describe outermost shape of a `Value`

simplifyValueSpecMismatch :: ValueSpecMismatch p -> ValueSpecMismatch p Source #

Simplify a `ValueSpecMismatch` by collapsing long nested error cases and by assuming that if a type matched that the other mismatched type alternatives are uninteresting. This is used in the implementation of `displayException`.

Since: 1.2.1.0