add install-includes: field
[packages/pretty.git] / Debug / Trace.hs
1 -----------------------------------------------------------------------------
2 -- |
3 -- Module : Debug.Trace
4 -- Copyright : (c) The University of Glasgow 2001
5 -- License : BSD-style (see the file libraries/base/LICENSE)
6 --
7 -- Maintainer : libraries@haskell.org
8 -- Stability : provisional
9 -- Portability : portable
10 --
11 -- The 'trace' function.
12 --
13 -----------------------------------------------------------------------------
14
15 module Debug.Trace (
16 -- * Tracing
17 putTraceMsg, -- :: String -> IO ()
18 trace -- :: String -> a -> a
19 ) where
20
21 import Prelude
22 import System.IO.Unsafe
23
24 #ifdef __GLASGOW_HASKELL__
25 import Foreign.C.String
26 #else
27 import System.IO (hPutStrLn,stderr)
28 #endif
29
30 -- | 'putTraceMsg' function outputs the trace message from IO monad.
31 -- Usually the output stream is 'System.IO.stderr' but if the function is called
32 -- from Windows GUI application then the output will be directed to the Windows
33 -- debug console.
34 putTraceMsg :: String -> IO ()
35 putTraceMsg msg = do
36 #ifndef __GLASGOW_HASKELL__
37 hPutStrLn stderr msg
38 #else
39 withCString "%s\n" $ \cfmt ->
40 withCString msg $ \cmsg ->
41 debugBelch cfmt cmsg
42
43 foreign import ccall unsafe "RtsMessages.h debugBelch"
44 debugBelch :: CString -> CString -> IO ()
45 #endif
46
47 {-# NOINLINE trace #-}
48 {-|
49 When called, 'trace' outputs the string in its first argument, before
50 returning the second argument as its result. The 'trace' function is not
51 referentially transparent, and should only be used for debugging, or for
52 monitoring execution. Some implementations of 'trace' may decorate the string
53 that\'s output to indicate that you\'re tracing. The function is implemented on
54 top of 'putTraceMsg'.
55 -}
56 trace :: String -> a -> a
57 trace string expr = unsafePerformIO $ do
58 putTraceMsg string
59 return expr
60
61 {-|
62 Like 'trace', but uses 'show' on the argument to convert it to a 'String'.
63
64 > traceShow = trace . show
65 -}
66 traceShow :: (Show a) => a -> b -> b
67 traceShow = trace . show