Cardano.Logging

This is an infix alias for contramap.

Inverse of use.

Trace strings using traceM. This will use stderr. See documentation in Debug.Trace for more details.

Make an emitting tracer from a callback.

Use a natural transformation to change the m type. This is useful, for instance, to use concrete IO tracers in monad transformer stacks that have IO as their base.

Uses traceMaybe to give a tracer which emits only if a predicate is true.

A monadic version of squelchUnless.

Trace strings to stdout. Output could be jumbled when this is used from multiple threads. Consider debugTracer instead.

Run a tracer only for the Just variant of a Maybe. If it's Nothing, the nullTracer is used (no output).

The arrow representation allows for proper laziness: if the tracer parameter does not produce any tracing effects, then the predicate won't even be evaluated. Contrast with the simple contravariant representation as a -> m (), in which the predicate _must_ be forced no matter what, because it's impossible to know a priori whether that function will not produce any tracing effects.

It's written out explicitly for demonstration. Could also use arrow notation:

traceMaybe p tr = Tracer $ proc a -> do
  case k a of
    Just b  -> use tr        -< b
    Nothing -> Arrow.squelch -< ()

A monadic version of traceMaybe.

Inverse of arrow. Useful when writing arrow tracers which use a contravariant tracer (the newtype in this module).

Do a non-emitting effect. This effect will only be run if some part of the tracer downstream emits (see emit).

Do an emitting effect. Contrast with effect which does not make the tracer an emitting tracer.

Use a natural transformation to change the underlying monad.

Ignore the input and do not emit. The name is intended to lead to clear and suggestive arrow expressions.

The class of contravariant functors.

Whereas in Haskell, one can think of a Functor as containing or producing values, a contravariant functor is a functor that can be thought of as consuming values.

As an example, consider the type of predicate functions a -> Bool. One such predicate might be negative x = x < 0, 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 to integers. For instance, we can use the negative predicate on a person's bank balance to work out if they are currently overdrawn:

newtype Predicate a = Predicate { getPredicate :: a -> Bool }

instance Contravariant Predicate where
  contramap :: (a' -> a) -> (Predicate a -> Predicate a')
  contramap f (Predicate p) = Predicate (p . f)
                                         |   `- First, map the input...
                                         `----- then apply the predicate.

overdrawn :: Predicate Person
overdrawn = contramap personBankBalance negative

Any instance should be subject to the following laws:

Identity

contramap id = id

Composition

contramap (g . f) = contramap f . contramap g

Note, that the second law follows from the free theorem of the type of contramap and the first law, so you need only check that the former condition holds.