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

Portabilitynon-portable (requires Template haskell)
Stabilityexperimental
Maintainertomi@nomi.cz

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

Documentation

__LOCATION__ :: Q ExpSource

Get the location of current splice as a String.

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

assert :: Q Exp -> Q ExpSource

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 ExpSource

A location-emitting error call.

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

undef :: Q ExpSource

A location-emitting undefined.

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

check :: Q ExpSource

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
>>> $check $ join deepseq $ Just $ head ""
*** Exception: <interactive>:1:1-6: Prelude.head: empty list

checkIO :: Q ExpSource

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)