loch-th-0.2.1: Support for precise error locations in source files (Template Haskell version)

Copyright | (c) Tomas Janousek 2011
License | BSD-style
Maintainer | tomi@nomi.cz
Stability | experimental
Portability | non-portable (requires Template haskell)
Safe Haskell | None
Language | Haskell98

Debug.Trace.LocationTH

Description

Tested : GHC 7.0.3

This module provides a Template Haskell based mechanism to tag failures with the location of the failure call. The location message includes the file name, line and column numbers.

Synopsis

- __LOCATION__ :: Q Exp
- assert :: Q Exp -> Q Exp
- failure :: Q Exp
- undef :: Q Exp
- check :: Q Exp
- checkIO :: Q Exp
- checkTrace :: Q Exp
- checkTraceIO :: Q Exp

# Documentation

__LOCATION__ :: Q Exp #

Get the location of current splice as a `String`.

    $LOCATION :: String

    >>> $__LOCATION__
    "<interactive>:1:1-13"

assert :: Q Exp -> Q Exp #

If the first argument evaluates to `True`, then the result is the second argument. Otherwise an `AssertionFailed` exception is raised, containing a `String` with the source file and line number of the call to `assert`.

    $(assert [| False |]) :: a -> a

    >>> $(assert [| 5 + 5 == 9 |]) "foo"
    "*** Exception: <interactive>:1:3-25: Assertion `(5 GHC.Num.+ 5) GHC.Classes.== 9' failed

failure :: Q Exp #

A location-emitting `error` call.

    $failure :: String -> a

    >>> $failure "no such thing."
    *** Exception: <interactive>:1:1-8: no such thing.

undef :: Q Exp #

A location-emitting `undefined`.

    $undef :: a

    >>> $undef
    *** Exception: <interactive>:1:1-6: undefined

check :: Q Exp #

`check` wraps a pure, partial function in a location-emitting handler, should an exception be thrown. So instead of producing an anonymous call to `error`, a location will be tagged to the error message.

    $check :: c -> c

    >>> $check $ head []
    *** Exception: <interactive>:1:1-6: Prelude.head: empty list

Be careful with laziness as the argument is only evaluated to weak head normal form:

    >>> $check $ Just $ head ""
    Just *** Exception: Prelude.head: empty list
    >>> Just $ $check $ head ""
    Just *** Exception: <interactive>:9:8-13: Prelude.head: empty list
    >>> $check $ join deepseq $ Just $ head ""
    *** Exception: <interactive>:1:1-6: Prelude.head: empty list

checkIO :: Q Exp #

`checkIO` wraps an IO function in a location-emitting handler, should an exception be thrown. So instead of producing an anonymous call to `error`, a location will be tagged to the error message.

    $checkIO :: IO a -> IO a

    >>> $checkIO $ readFile "/foo"
    "*** Exception: <interactive>:1:1-8: /foo: openFile: does not exist (No such file or directory)

checkTrace :: Q Exp #

`checkTrace` extends `check` with the ability to add a custom string to the error message.

    $checkTrace :: String -> c -> c

    >>> $checkTrace "XXX" $ head []
    *** Exception: <interactive>:1:1-6 XXX: Prelude.head: empty list

checkTraceIO :: Q Exp #

`checkTraceIO` extends `checkIO` with the ability to add a custom string to the error message.

    $checkTraceIO :: String -> IO a -> IO a

    >>> $checkTraceIO "XXX" $ readFile "/foo"
    "*** Exception: <interactive>:1:1-8 XXX: /foo: openFile: does not exist (No such file or directory)