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