Debug.Trace.LocationTH

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.

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)