Typo
[packages/base.git] / Debug / Trace.hs
index 94568d2..eedacfa 100644 (file)
@@ -1,5 +1,5 @@
 {-# LANGUAGE Unsafe #-}
-{-# LANGUAGE CPP, ForeignFunctionInterface, MagicHash, UnboxedTuples #-}
+{-# LANGUAGE MagicHash, UnboxedTuples #-}
 
 -----------------------------------------------------------------------------
 -- |
@@ -22,9 +22,13 @@ module Debug.Trace (
         -- * Tracing
         -- $tracing
         trace,
+        traceId,
         traceShow,
+        traceShowId,
         traceStack,
         traceIO,
+        traceM,
+        traceShowM,
         putTraceMsg,
 
         -- * Eventlog tracing
@@ -42,16 +46,12 @@ import Prelude
 import System.IO.Unsafe
 import Control.Monad
 
-#ifdef __GLASGOW_HASKELL__
 import Foreign.C.String
 import GHC.Base
 import qualified GHC.Foreign
 import GHC.IO.Encoding
 import GHC.Ptr
 import GHC.Stack
-#else
-import System.IO (hPutStrLn,stderr)
-#endif
 
 -- $tracing
 --
@@ -67,11 +67,9 @@ import System.IO (hPutStrLn,stderr)
 -- | The 'traceIO' function outputs the trace message from the IO monad.
 -- This sequences the output with respect to other IO actions.
 --
+-- /Since: 4.5.0.0/
 traceIO :: String -> IO ()
 traceIO msg = do
-#ifndef __GLASGOW_HASKELL__
-    hPutStrLn stderr msg
-#else
     withCString "%s\n" $ \cfmt ->
      withCString msg  $ \cmsg ->
       debugBelch cfmt cmsg
@@ -80,13 +78,11 @@ traceIO msg = do
 -- using the FFI.
 foreign import ccall unsafe "HsBase.h debugBelch2"
    debugBelch :: CString -> CString -> IO ()
-#endif
 
-
--- | Deprecated. Use 'traceIO'.
+-- |
 putTraceMsg :: String -> IO ()
 putTraceMsg = traceIO
-{-# DEPRECATED putTraceMsg "Use Debug.Trace.traceIO" #-} -- deprecated in 7.4
+{-# DEPRECATED putTraceMsg "Use 'Debug.Trace.traceIO'" #-} -- deprecated in 7.4
 
 
 {-# NOINLINE trace #-}
@@ -109,6 +105,14 @@ trace string expr = unsafePerformIO $ do
     return expr
 
 {-|
+Like 'trace' but returns the message instead of a third value.
+
+/Since: 4.7.0.0/
+-}
+traceId :: String -> String
+traceId a = trace a a
+
+{-|
 Like 'trace', but uses 'show' on the argument to convert it to a 'String'.
 
 This makes it convenient for printing the values of interesting variables or
@@ -124,6 +128,44 @@ variables @x@ and @z@:
 traceShow :: (Show a) => a -> b -> b
 traceShow = trace . show
 
+{-|
+Like 'traceShow' but returns the shown value instead of a third value.
+
+/Since: 4.7.0.0/
+-}
+traceShowId :: (Show a) => a -> a
+traceShowId a = trace (show a) a
+
+{-|
+Like 'trace' but returning unit in an arbitrary monad. Allows for convenient
+use in do-notation. Note that the application of 'trace' is not an action in the
+monad, as 'traceIO' is in the 'IO' monad.
+
+> ... = do
+>   x <- ...
+>   traceM $ "x: " ++ show x
+>   y <- ...
+>   traceM $ "y: " ++ show y
+
+/Since: 4.7.0.0/
+-}
+traceM :: (Monad m) => String -> m ()
+traceM string = trace string $ return ()
+
+{-|
+Like 'traceM', but uses 'show' on the argument to convert it to a 'String'.
+
+> ... = do
+>   x <- ...
+>   traceMShow $ x
+>   y <- ...
+>   traceMShow $ x + y
+
+/Since: 4.7.0.0/
+-}
+traceShowM :: (Show a, Monad m) => a -> m ()
+traceShowM = traceM . show
+
 -- | like 'trace', but additionally prints a call stack if one is
 -- available.
 --
@@ -133,6 +175,7 @@ traceShow = trace . show
 -- stack correspond to @SCC@ annotations, so it is a good idea to use
 -- @-fprof-auto@ or @-fprof-auto-calls@ to add SCC annotations automatically.
 --
+-- /Since: 4.5.0.0/
 traceStack :: String -> a -> a
 traceStack str expr = unsafePerformIO $ do
    traceIO str
@@ -165,6 +208,7 @@ traceStack str expr = unsafePerformIO $ do
 -- duplicate events emitted if two CPUs simultaneously evaluate the same thunk
 -- that uses 'traceEvent'.
 --
+-- /Since: 4.5.0.0/
 traceEvent :: String -> a -> a
 traceEvent msg expr = unsafeDupablePerformIO $ do
     traceEventIO msg
@@ -176,15 +220,11 @@ traceEvent msg expr = unsafeDupablePerformIO $ do
 -- Compared to 'traceEvent', 'traceEventIO' sequences the event with respect to
 -- other IO actions.
 --
+-- /Since: 4.5.0.0/
 traceEventIO :: String -> IO ()
-#ifdef __GLASGOW_HASKELL__
 traceEventIO msg =
   GHC.Foreign.withCString utf8 msg $ \(Ptr p) -> IO $ \s ->
     case traceEvent# p s of s' -> (# s', () #)
-#else
-traceEventIO msg = (return $! length msg) >> return ()
-#endif
-
 
 -- $markers
 --
@@ -218,6 +258,7 @@ traceEventIO msg = (return $! length msg) >> return ()
 -- duplicate events emitted if two CPUs simultaneously evaluate the same thunk
 -- that uses 'traceMarker'.
 --
+-- /Since: 4.7.0.0/
 traceMarker :: String -> a -> a
 traceMarker msg expr = unsafeDupablePerformIO $ do
     traceMarkerIO msg
@@ -229,12 +270,8 @@ traceMarker msg expr = unsafeDupablePerformIO $ do
 -- Compared to 'traceMarker', 'traceMarkerIO' sequences the event with respect to
 -- other IO actions.
 --
+-- /Since: 4.7.0.0/
 traceMarkerIO :: String -> IO ()
-#ifdef __GLASGOW_HASKELL__
 traceMarkerIO msg =
   GHC.Foreign.withCString utf8 msg $ \(Ptr p) -> IO $ \s ->
     case traceMarker# p s of s' -> (# s', () #)
-#else
-traceMarkerIO msg = (return $! length msg) >> return ()
-#endif
-