Tested : GHC 6.4.2, GHCi, Hugs 2005

This module provides a lightweight, pure Haskell mechanism to tag failures with the location of the failure call. The location message includes the file name, line and column numbers. All functions are passed the special symbol assert as an argument, which is expanded by the compiler into a location string.

Usage:

 import Debug.Trace.Location

 failure assert "no such thing"

Also provided is a located trace for debugging purposes, and generic wrappers for pure and IO code, to tag location messages to exceptions:

 check assert (head [])

Produces:

 a.out: A.hs:18:10-15: Prelude.head: empty list

Or for IO functions:

 do x <- checkIO assert $ readFile "/f"

Resulting in:

 $ ./a.out        
 a.out: A.hs:18:20-25: /f: openFile: does not exist

While this code will run in Hugs, the Hugs assert token is not expanded usefully, producing:

 Debug.Trace.Location> trace assert "works in hugs" (1+2)
 assertion works in hugs
 3

A location-emitting error call. It behaves like error, but takes an assert token as an argument, producing a located error message.

 failure assert "no such thing."

From GHCi:

 *** Exception: <interactive>:1:8-13: no such thing.

Or compiled:

 a.out: A.hs:18:12-17: no such thing.

A location-emitting trace call. It returns its third argument, emitting a located trace message to stderr as a side effect.

For example:

 trace assert "made it here" (1+2)

Will produce:

 <interactive>:1:21-26: made it here
 3

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 assert $ head []

Will produce:

 *** Exception: <interactive>:1:6-11: Prelude.head: empty list

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.

 do x <- checkIO assert (readFile "/foo")
    x

Will produce:

 "*** Exception: <interactive>:1:13-18: /foo: openFile: does not exist