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


-- | A simple interface for logging, tracing or monitoring.
--   
--   A simple interface for logging, tracing or monitoring.
@package contra-tracer
@version 0.1.0.0


-- | <a>Tracer</a> is a contravariant functor to thread observable values
--   through a number of transformers, possibly annotating them with
--   additional information, or filtering them based on evaluating
--   predicates.
module Control.Tracer

-- | example: simply output a message on the console
--   
--   <pre>
--   let logTrace = traceWith $ showTracing $ stdoutTracer
--   in  logTrace "hello world"
--   </pre>
--   
--   example: calling a function and passing in a <a>Tracer</a>
--   
--   <pre>
--   example1 :: IO ()
--   example1 = do
--       let logTrace a = traceWith (showTracing (contramap ("Debug: " ++) stdoutTracer)) a
--       void $ callFun1 logTrace
--   </pre>
--   
--   <pre>
--   callFun1 :: (String -&gt; IO ()) -&gt; IO Int
--   callFun1 logTrace = do
--       logTrace "in function 1"
--       return 42
--   </pre>
--   
--   <a>runTracer</a> evaluates a <a>Tracer</a> (i.e. consumes its
--   argument)
newtype Tracer m a
Tracer :: (a -> m ()) -> Tracer m a
[runTracer] :: Tracer m a -> a -> m ()

-- | The class of contravariant functors.
--   
--   Whereas in Haskell, one can think of a <a>Functor</a> as containing or
--   producing values, a contravariant functor is a functor that can be
--   thought of as <i>consuming</i> values.
--   
--   As an example, consider the type of predicate functions <tt>a -&gt;
--   Bool</tt>. One such predicate might be <tt>negative x = x &lt; 0</tt>,
--   which classifies integers as to whether they are negative. However,
--   given this predicate, we can re-use it in other situations, providing
--   we have a way to map values <i>to</i> integers. For instance, we can
--   use the <tt>negative</tt> predicate on a person's bank balance to work
--   out if they are currently overdrawn:
--   
--   <pre>
--   newtype Predicate a = Predicate { getPredicate :: a -&gt; Bool }
--   
--   instance Contravariant Predicate where
--     contramap f (Predicate p) = Predicate (p . f)
--                                            |   `- First, map the input...
--                                            `----- then apply the predicate.
--   
--   overdrawn :: Predicate Person
--   overdrawn = contramap personBankBalance negative
--   </pre>
--   
--   Any instance should be subject to the following laws:
--   
--   <ul>
--   <li><i>Identity</i> <tt><a>contramap</a> <a>id</a> =
--   <a>id</a></tt></li>
--   <li><i>Composition</i> <tt><a>contramap</a> (g . f) = <a>contramap</a>
--   f . <a>contramap</a> g</tt></li>
--   </ul>
--   
--   Note, that the second law follows from the free theorem of the type of
--   <a>contramap</a> and the first law, so you need only check that the
--   former condition holds.
class Contravariant (f :: Type -> Type)
contramap :: Contravariant f => (a -> b) -> f b -> f a

-- | Replace all locations in the output with the same value. The default
--   definition is <tt><a>contramap</a> . <a>const</a></tt>, but this may
--   be overridden with a more efficient version.
(>$) :: Contravariant f => b -> f b -> f a
infixl 4 >$

-- | trace an observable value with a <a>Tracer</a>
traceWith :: Tracer m a -> a -> m ()

-- | this <a>Tracer</a> forgets about all arguments
nullTracer :: Applicative m => Tracer m a

-- | Output a traced <a>String</a> to <tt>stdout</tt>
stdoutTracer :: MonadIO m => Tracer m String

-- | Output a traced <a>String</a> using <a>Trace</a>
debugTracer :: Applicative m => Tracer m String

-- | Transform a tracer using a Kleisli map.
contramapM :: Monad m => (a -> m b) -> Tracer m b -> Tracer m a

-- | transform a traced value to a showable instance.
showTracing :: Show a => Tracer m String -> Tracer m a

-- | conditionally trace an observable given the evaluation of a predicate.
condTracing :: Monad m => (a -> Bool) -> Tracer m a -> Tracer m a

-- | conditionally trace an observable given the evaluation of a predicate
--   in a monadic context.
condTracingM :: Monad m => m (a -> Bool) -> Tracer m a -> Tracer m a

-- | natural transformation from monad <tt>m</tt> to monad <tt>n</tt>.
natTracer :: (forall x. m x -> n x) -> Tracer m s -> Tracer n s
instance Data.Functor.Contravariant.Contravariant (Control.Tracer.Tracer m)
instance GHC.Base.Applicative m => GHC.Base.Semigroup (Control.Tracer.Tracer m s)
instance GHC.Base.Applicative m => GHC.Base.Monoid (Control.Tracer.Tracer m s)


-- | Functions useful for observing and measuring actions.
module Control.Tracer.Observe
data ObserveIndicator
ObserveBefore :: ObserveIndicator
ObserveAfter :: ObserveIndicator
data Observable s e d
OStart :: s -> Observable s e d
OEnd :: e -> Maybe d -> Observable s e d
matchObservations :: Monad m => m (Maybe s) -> (s -> m ()) -> (s -> e -> d) -> Tracer m (Observable s e d) -> Tracer m (Observable s e d)
instance GHC.Show.Show Control.Tracer.Observe.ObserveIndicator
