homepage: https://github.com/parsonsmatt/annotated-exception#readme
changelog-type: markdown
hash: 20226fc85b6949651ae875969ac88a982a7574c1bc675d3e6d4aa23c5e2b4174
test-bench-deps:
  base: '>=4.7 && <5'
  hspec: -any
  text: -any
  safe-exceptions: -any
  containers: -any
  annotated-exception: -any
maintainer: parsonsmatt@gmail.com
synopsis: Exceptions, with checkpoints and context.
changelog: |
  # Changelog for located-exception

  ## Unreleased changes

  ## 0.1.0.0

  - Initial Release
basic-deps:
  base: '>=4.7 && <5'
  text: -any
  safe-exceptions: -any
  containers: -any
all-versions:
- 0.1.0.0
author: Matt Parsons
latest: 0.1.0.0
description-type: markdown
description: |
  # `annotated-exception`

  This library provides a special `AnnotatedException` type which allows you to decorate Haskell exceptions with additional information.
  This decoration is totally transparent, and even works with exceptions thrown outside of your application code.

  To provide an annotation, you'd use the function `checkpoint`.
  This will attach the provided value to any exception that bubbles up through it.

  ```haskell
  import Control.Exception.Annotated

  data MyException = MyException
      deriving (Show, Exception)

  main :: IO ()
  main = do
      checkpoint "Foo" $ do
          throw MyException
  ```

  When this program crashes, it will crash with an `AnnotatedException` that contains the annotation `"Foo"`.

  ```
  λ> checkpoint "Foo" $ throw MyException
  *** Exception: AnnotatedException {annotations = ["Foo"], exception = MyException}
  ```

  These annotations survive, even if you catch and rethrow with a different exception.

  ```haskell
  data OtherException = OtherException
      deriving (Show, Exception)

  woah :: IO ()
  woah = do
      let
          checkpointed =
              checkpoint "Foo" (throw MyException)
          handler MyException =
              throw OtherException

      checkpointed
          `catch`
              handler

  ```

  Notice how the `checkpoint` call doesn't cover the `throw OtherException` - the exception `[Annotation]` lives on the thrown exception itself, and this library's `catch` function ensures that we don't lose that context.

  ```
  λ> (checkpoint "Foo" (throw MyException)) `catch` \MyException -> throw OtherException
  *** Exception: AnnotatedException {annotations = ["Foo"], exception = OtherException}
  ```

  You can also attach a `CallStack` to any exception using `throwWithCallStack`.

  Now, you're about to report your exceptions, up near `main`.
  We can use `try` in this module to always get the annotations.

  ```haskell
  main = do
      eresult <- try $ myProgram
      case eresult of
          Left (AnnotatedException annotations exception) ->
              reportException annotations exception
          Right a ->
              pure a
  ```
license-name: BSD-3-Clause

Update from Hackage at 2022-03-09T01:12:20Z
Update from Hackage at 2022-03-09T01:12:20Z
