Test.Cleveland.Internal.Exceptions.Annotated

This module defines annotated exceptions and machinery to work with them.

Documentation

data Key ann where

Constructors

Key :: ExceptionAnnotation a => Key a

Instances

GCompare Key

Defined in Test.Cleveland.Internal.Exceptions.Annotated

Methods

gcompare :: forall (a :: k) (b :: k). Key a -> Key b -> GOrdering a b

GEq Key

Defined in Test.Cleveland.Internal.Exceptions.Annotated

Methods

geq :: forall (a :: k) (b :: k). Key a -> Key b -> Maybe (a :~: b)

data AnnotatedException

SomeException augmented with arbitrary annotations.

Constructors

AnnotatedException AnnotationMap SomeException

Instances

Exception AnnotatedException

Defined in Test.Cleveland.Internal.Exceptions.Annotated

Methods

toException :: AnnotatedException -> SomeException

fromException :: SomeException -> Maybe AnnotatedException

displayException :: AnnotatedException -> String

Show AnnotatedException

Defined in Test.Cleveland.Internal.Exceptions.Annotated

Methods

showsPrec :: Int -> AnnotatedException -> ShowS

show :: AnnotatedException -> String

showList :: [AnnotatedException] -> ShowS

newtype AnnotationMap

A map from Key to corresponding annotation.

Constructors

AnnotationMap

Fields

• unAnnotationMap :: DMap Key Identity

Instances

Show AnnotationMap

Defined in Test.Cleveland.Internal.Exceptions.Annotated

Methods

showsPrec :: Int -> AnnotationMap -> ShowS

show :: AnnotationMap -> String

showList :: [AnnotationMap] -> ShowS

class (Show ann, Typeable ann) => ExceptionAnnotation ann where

Type class for exception annotations.

Minimal complete definition

displayAnnotation

Methods

displayAnnotation :: ann -> Doc -> Doc

Given an annotation and the error message (as Doc), produce the text annotated with the annotation.

annotationPriority :: Int

Relative priority for sorting annotations. Annotations with higher priority will be applied first. Default is 0.

Instances

ExceptionAnnotation CallStackAnnotation

Defined in Test.Cleveland.Internal.Exceptions.CallStack

Methods

displayAnnotation :: CallStackAnnotation -> Doc -> Doc

annotationPriority :: Int

ExceptionAnnotation ErrorsClarification

Defined in Test.Cleveland.Internal.Exceptions.ErrorsClarification

Methods

displayAnnotation :: ErrorsClarification -> Doc -> Doc

annotationPriority :: Int

ExceptionAnnotation ScenarioBranchName

Defined in Test.Cleveland.Internal.Exceptions.ScenarioBranchName

Methods

displayAnnotation :: ScenarioBranchName -> Doc -> Doc

annotationPriority :: Int

fromPossiblyAnnotatedException :: Exception e => SomeException -> Maybe e

Try to extract a given exception type, skipping over annotations. This essentially makes AnnotatedException transparent for this function.

This is intended to be used as the default implementation of fromException for exception types that are expected to be annotated, as to make AnnotatedException transparent for catch, try, etc.

For example:

instance Exception GenericTestError where
  displayException = pretty
  fromException = fromPossiblyAnnotatedException

Now, when catching GenericTestError, it'll work even if wrapped in AnnotatedException:

>>> try @_ @GenericTestError (addCallStack $ throwM UnexpectedSuccess)
Left UnexpectedSuccess

When catching exceptions not explicitly set up like this, this trick unfortunately won't work, so using this function explicitly is required:

>>> data ExceptionToCatch = ExceptionToCatch deriving stock Show
>>> instance Exception ExceptionToCatch
>>> action = addCallStack $ throwM ExceptionToCatch
>>> try @_ @ExceptionToCatch action
*** Exception: AnnotatedException ...
...ExceptionToCatch
>>> :{
action `catch` \(err :: SomeException) -> case fromPossiblyAnnotatedException err of
  Just (err' :: ExceptionToCatch) -> pass
  Nothing -> throwM err
:}

printAnnotations :: Buildable a => AnnotationMap -> a -> Doc

Print all annotations from an AnnotationMap, given the initial message.

Essentially right-fold using displayAnnotation.

insertAnnEx' :: (Semigroup ann, ExceptionAnnotation ann) => ann -> AnnotatedException -> AnnotatedException

Insert a new annotation into AnnotatedException.

insertAnn :: (Semigroup t, ExceptionAnnotation t) => t -> AnnotationMap -> AnnotationMap

Insert a new annotation into an AnnotationMap. If an annotation of this type already exists, merge the annotations using the Semigroup instance.

insertAnnEx :: (Semigroup ann, ExceptionAnnotation ann) => ann -> SomeException -> SomeException

Insert a new annotation into SomeException.

If it's already an AnnotatedException, simply adds a new annotation. Otherwise, wraps the exception into AnnotatedException first.

singletonAnn :: ExceptionAnnotation t => t -> AnnotationMap

Construct a singleton AnnotationMap.

removeAnnEx' :: forall ann. ExceptionAnnotation ann => AnnotatedException -> AnnotatedException

Remove an annotation of the given type from AnnotatedException.

removeAnn :: forall t. ExceptionAnnotation t => AnnotationMap -> AnnotationMap

Remove an annotation of a given type t from AnnotationMap.

removeAnnEx :: forall ann. ExceptionAnnotation ann => SomeException -> SomeException

Remove an annotation of the given type from SomeException. If it's not an AnnotatedException, this is a no-op.

lookupAnnEx' :: forall ann. ExceptionAnnotation ann => AnnotatedException -> Maybe ann

Extract the given annotation type from AnnotatedException if possible.

lookupAnn :: ExceptionAnnotation t => AnnotationMap -> Maybe t

Try to find the given type t in an AnnotationMap.

lookupAnnEx :: forall ann. ExceptionAnnotation ann => SomeException -> Maybe ann

Extract the given annotation type from SomeException if possible.

annotateExceptions :: forall m a ann. (MonadCatch m, Semigroup ann, ExceptionAnnotation ann) => ann -> m a -> m a

Add an annotation to exceptions thrown by a monadic action.