-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Support for precise error locations in source files (Template Haskell version)
--   
--   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.
@package loch-th
@version 0.2.1


-- | 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.
module Debug.Trace.LocationTH

-- | Get the location of current splice as a <a>String</a>.
--   
--   <pre>
--   $<b>LOCATION</b> :: <a>String</a>
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; $__LOCATION__
--   "&lt;interactive&gt;:1:1-13"
--   </pre>
__LOCATION__ :: Q Exp

-- | If the first argument evaluates to <a>True</a>, then the result is the
--   second argument. Otherwise an <a>AssertionFailed</a> exception is
--   raised, containing a <a>String</a> with the source file and line
--   number of the call to <a>assert</a>.
--   
--   <pre>
--   $(assert [| <a>False</a> |]) :: a -&gt; a
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; $(assert [| 5 + 5 == 9 |]) "foo"
--   "*** Exception: &lt;interactive&gt;:1:3-25: Assertion `(5 GHC.Num.+ 5) GHC.Classes.== 9' failed
--   </pre>
assert :: Q Exp -> Q Exp

-- | A location-emitting <a>error</a> call.
--   
--   <pre>
--   $failure :: <a>String</a> -&gt; a
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; $failure "no such thing."
--   *** Exception: &lt;interactive&gt;:1:1-8: no such thing.
--   </pre>
failure :: Q Exp

-- | A location-emitting <a>undefined</a>.
--   
--   <pre>
--   $undef :: a
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; $undef
--   *** Exception: &lt;interactive&gt;:1:1-6: undefined
--   </pre>
undef :: Q Exp

-- | <a>check</a> wraps a pure, partial function in a location-emitting
--   handler, should an exception be thrown. So instead of producing an
--   anonymous call to <a>error</a>, a location will be tagged to the error
--   message.
--   
--   <pre>
--   $check :: c -&gt; c
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; $check $ head []
--   *** Exception: &lt;interactive&gt;:1:1-6: Prelude.head: empty list
--   </pre>
--   
--   Be careful with laziness as the argument is only evaluated to weak
--   head normal form:
--   
--   <pre>
--   &gt;&gt;&gt; $check $ Just $ head ""
--   Just *** Exception: Prelude.head: empty list
--   
--   &gt;&gt;&gt; Just $ $check $ head ""
--   Just *** Exception: &lt;interactive&gt;:9:8-13: Prelude.head: empty list
--   
--   &gt;&gt;&gt; $check $ join deepseq $ Just $ head ""
--   *** Exception: &lt;interactive&gt;:1:1-6: Prelude.head: empty list
--   </pre>
check :: Q Exp

-- | <a>checkIO</a> wraps an IO function in a location-emitting handler,
--   should an exception be thrown. So instead of producing an anonymous
--   call to <a>error</a>, a location will be tagged to the error message.
--   
--   <pre>
--   $checkIO :: IO a -&gt; IO a
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; $checkIO $ readFile "/foo"
--   "*** Exception: &lt;interactive&gt;:1:1-8: /foo: openFile: does not exist (No such file or directory)
--   </pre>
checkIO :: Q Exp

-- | <a>checkTrace</a> extends <a>check</a> with the ability to add a
--   custom string to the error message.
--   
--   <pre>
--   $checkTrace :: String -&gt; c -&gt; c
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; $checkTrace "XXX" $ head []
--   *** Exception: &lt;interactive&gt;:1:1-6 XXX: Prelude.head: empty list
--   </pre>
checkTrace :: Q Exp

-- | <a>checkTraceIO</a> extends <a>checkIO</a> with the ability to add a
--   custom string to the error message.
--   
--   <pre>
--   $checkTraceIO :: String -&gt; IO a -&gt; IO a
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; $checkTraceIO "XXX" $ readFile "/foo"
--   "*** Exception: &lt;interactive&gt;:1:1-8 XXX: /foo: openFile: does not exist (No such file or directory)
--   </pre>
checkTraceIO :: Q Exp
