Test.Cleveland.Internal.Exceptions.Annotated

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

Documentation

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

Type class for exception annotations.

Minimal complete definition

displayAnnotation

Methods

displayAnnotation :: ann -> Builder -> Builder

Given an annotation and the error message (as Builder), 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 -> Builder -> Builder

annotationPriority :: Int

ExceptionAnnotation ErrorsClarification

Defined in Test.Cleveland.Internal.Exceptions.ErrorsClarification

Methods

displayAnnotation :: ErrorsClarification -> Builder -> Builder

annotationPriority :: Int

ExceptionAnnotation ScenarioBranchName

Defined in Test.Cleveland.Internal.Exceptions.ScenarioBranchName

Methods

displayAnnotation :: ScenarioBranchName -> Builder -> Builder

annotationPriority :: Int

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

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

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

Insert a new annotation into AnnotatedException.

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.

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

Remove an annotation of the given type from AnnotatedException.

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.

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

Extract the given annotation type from SomeException if possible.

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

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

Essentially right-fold using displayAnnotation.

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

Try to find the given type t in an AnnotationMap.

singletonAnn :: ExceptionAnnotation t => t -> AnnotationMap

Construct a singleton AnnotationMap.

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.

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

Remove an annotation of a given type t from AnnotationMap.

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.