Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
Synopsis
- newtype Tracer m a = Tracer {
- runTracer :: a -> m ()
- silent :: Applicative m => Tracer m a
- traceIf :: Applicative m => (a -> Bool) -> Tracer m a -> Tracer m a
- traceBoth :: Applicative m => Tracer m a -> Tracer m a -> Tracer m a
- tracePrint :: (MonadIO m, Show a) => Tracer m a
- traceHPrint :: (MonadIO m, Show a) => Handle -> Tracer m a
- traceHPut :: MonadIO m => Handle -> Tracer m ByteString
- encodeJSON :: ToJSON a => Tracer m ByteString -> Tracer m a
- pulls :: Monad m => (c -> m b) -> Tracer m b -> Tracer m c
- class Contravariant (f :: Type -> Type) where
- class Contravariant f => Divisible (f :: Type -> Type) where
- class Divisible f => Decidable (f :: Type -> Type) where
Documentation
Instances
Contravariant (Tracer m) Source # | |
Applicative m => Decidable (Tracer m) Source # | |
Applicative m => Divisible (Tracer m) Source # | |
silent :: Applicative m => Tracer m a Source #
Disable Tracing.
traceIf :: Applicative m => (a -> Bool) -> Tracer m a -> Tracer m a Source #
Filter by dynamically testing values.
traceBoth :: Applicative m => Tracer m a -> Tracer m a -> Tracer m a Source #
If you are given two tracers and want to pass both. Composition occurs in sequence.
common utilities
traceHPrint :: (MonadIO m, Show a) => Handle -> Tracer m a Source #
A tracer that prints emitted to some handle.
traceHPut :: MonadIO m => Handle -> Tracer m ByteString Source #
A tracer that puts some ByteString to some handle.
encodeJSON :: ToJSON a => Tracer m ByteString -> Tracer m a Source #
A conversion encoding values to JSON.
pulls :: Monad m => (c -> m b) -> Tracer m b -> Tracer m c Source #
Pulls a value to complete a trace when a trace occurs.
This function allows to combines pushed values with pulled values. Hence, performing some scheduling between behaviours. Typical usage would be to annotate a trace with a background value, or perform data augmentation in a pipelines of traces.
Note that if you rely on this function you need to pay attention of the
blocking effect of pulls
: the traced value c is not forwarded until a
value b is available.
re-exports
class Contravariant (f :: Type -> Type) where #
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:
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.
Instances
class Contravariant f => Divisible (f :: Type -> Type) where #
A Divisible
contravariant functor is the contravariant analogue of Applicative
.
Continuing the intuition that Contravariant
functors consume input, a Divisible
contravariant functor also has the ability to be composed "beside" another contravariant
functor.
Serializers provide a good example of Divisible
contravariant functors. To begin
let's start with the type of serializers for specific types:
newtype Serializer a = Serializer { runSerializer :: a -> ByteString }
This is a contravariant functor:
instance Contravariant Serializer where contramap f s = Serializer (runSerializer s . f)
That is, given a serializer for a
(s :: Serializer a
), and a way to turn
b
s into a
s (a mapping f :: b -> a
), we have a serializer for b
:
contramap f s :: Serializer b
.
Divisible gives us a way to combine two serializers that focus on different
parts of a structure. If we postulate the existance of two primitive
serializers - string :: Serializer String
and int :: Serializer Int
, we
would like to be able to combine these into a serializer for pairs of
String
s and Int
s. How can we do this? Simply run both serializers and
combine their output!
data StringAndInt = StringAndInt String Int stringAndInt :: Serializer StringAndInt stringAndInt = Serializer $ \(StringAndInt s i) -> let sBytes = runSerializer string s iBytes = runSerializer int i in sBytes <> iBytes
divide
is a generalization by also taking a contramap
like function to
split any a
into a pair. This conveniently allows you to target fields of
a record, for instance, by extracting the values under two fields and
combining them into a tuple.
To complete the example, here is how to write stringAndInt
using a
Divisible
instance:
instance Divisible Serializer where conquer = Serializer (const mempty) divide toBC bSerializer cSerializer = Serializer $ \a -> case toBC a of (b, c) -> let bBytes = runSerializer bSerializer b cBytes = runSerializer cSerializer c in bBytes <> cBytes stringAndInt :: Serializer StringAndInt stringAndInt = divide (\(StringAndInt s i) -> (s, i)) string int
divide :: (a -> (b, c)) -> f b -> f c -> f a #
Conquer acts as an identity for combining Divisible
functors.
Instances
class Divisible f => Decidable (f :: Type -> Type) where #
A Decidable
contravariant functor is the contravariant analogue of Alternative
.
Noting the superclass constraint that f
must also be Divisible
, a Decidable
functor has the ability to "fan out" input, under the intuition that contravariant
functors consume input.
In the discussion for Divisible
, an example was demonstrated with Serializer
s,
that turn a
s into ByteString
s. Divisible
allowed us to serialize the product
of multiple values by concatenation. By making our Serializer
also Decidable
-
we now have the ability to serialize the sum of multiple values - for example
different constructors in an ADT.
Consider serializing arbitrary identifiers that can be either String
s or Int
s:
data Identifier = StringId String | IntId Int
We know we have serializers for String
s and Int
s, but how do we combine them
into a Serializer
for Identifier
? Essentially, our Serializer
needs to
scrutinise the incoming value and choose how to serialize it:
identifier :: Serializer Identifier identifier = Serializer $ \identifier -> case identifier of StringId s -> runSerializer string s IntId i -> runSerializer int i
It is exactly this notion of choice that Decidable
encodes. Hence if we add
an instance of Decidable
for Serializer
...
instance Decidable Serializer where lose f = Serializer $ \a -> absurd (f a) choose split l r = Serializer $ \a -> either (runSerializer l) (runSerializer r) (split a)
Then our identifier
Serializer
is
identifier :: Serializer Identifier identifier = choose toEither string int where toEither (StringId s) = Left s toEither (IntId i) = Right i
Acts as identity to choose
.