Colog.Core.Action

Polymorphic and very general logging action type.

• msg type variables is an input for logger. It can be Text or custom logging messsage with different fields that you want to format in future.

• m type variable is for monadic action inside which logging is happening. It can be either IO or some custom pure monad.

Key design point here is that LogAction is:

• Semigroup

• Monoid

• Contravariant

• Divisible

• Decidable

• Comonad

Operator version of unLogAction. Note that because of the types, something like:

action <& msg1 <& msg2

doesn't make sense. Instead you want:

action <& msg1 >> action <& msg2

In addition, because <& has higher precedence than the other operators in this module, the following:

f >$< action <& msg

is equivalent to:

(f >$< action) <& msg

A flipped version of <&.

It shares the same precedence as <&, so make sure to surround lower precedence operators in parentheses:

msg &> (f >$< action)

Joins some Foldable of LogActions into single LogAction using Semigroup instance for LogAction. This is basically specialized version of fold function.

Takes predicate and performs given logging action only if predicate returns True on input logging message.

Performs the given logging action only if satisfies the monadic predicate. Let's say you want to only to see logs that happened on weekends.

isWeekendM :: MessageWithTimestamp -> IO Bool

And use it with cfilterM like this

logMessageAction :: LogAction m MessageWithTimestamp

logWeekendAction :: LogAction m MessageWithTimestamp
logWeekendAction = cfilterM isWeekendM logMessageAction

This combinator is contramap from contravariant functor. It is useful when you have something like

data LogRecord = LR
    { lrName    :: LoggerName
    , lrMessage :: Text
    }

and you need to provide LogAction which consumes LogRecord

logRecordAction :: LogAction m LogRecord

when you only have action that consumes Text

logTextAction :: LogAction m Text

With cmap you can do the following:

logRecordAction :: LogAction m LogRecord
logRecordAction = cmap lrMesssage logTextAction

This action will print only lrMessage from LogRecord. But if you have formatting function like this:

formatLogRecord :: LogRecord -> Text

you can apply it instead of lrMessage to log formatted LogRecord as Text.

Operator version of cmap.

>>> 1 &> (show >$< logStringStdout)1

cmap for convertions that may fail

Similar to cmapMaybe but for convertions that may fail inside a monadic context.

This combinator is >$ from contravariant functor. Replaces all locations in the output with the same value. The default definition is contramap . const, so this is a more efficient version.

>>> "Hello?" &> ("OUT OF SERVICE" >$ logStringStdout)OUT OF SERVICE>>> ("OUT OF SERVICE" >$ logStringStdout) <& 42OUT OF SERVICE

cmapM combinator is similar to cmap but allows to call monadic functions (functions that require extra context) to extend consumed value. Consider the following example.

You have this logging record:

data LogRecord = LR
    { lrTime    :: UTCTime
    , lrMessage :: Text
    }

and you also have logging consumer inside IO for such record:

logRecordAction :: LogAction IO LogRecord

But you need to return consumer only for Text messages:

logTextAction :: LogAction IO Text

If you have function that can extend Text to LogRecord like the function below:

withTime :: Text -> IO LogRecord
withTime msg = do
    time <- getCurrentTime
    pure (LR time msg)

you can achieve desired behavior with cmapM in the following way:

logTextAction :: LogAction IO Text
logTextAction = cmapM withTime myAction

divide combinator from Divisible type class.

>>> logInt = LogAction print>>> "ABC" &> divide (\s -> (s, length s)) logStringStdout logIntABC3

Monadic version of divide.

conquer combinator from Divisible type class.

Concretely, this is a LogAction that does nothing:

>>> conquer <& "hello?">>> "hello?" &> conquer

Operator version of divide id.

>>> logInt = LogAction print>>> (logStringStdout >*< logInt) <& ("foo", 1)foo1>>> (logInt >*< logStringStdout) <& (1, "foo")1foo

Perform a constant log action after another.

>>> logHello = LogAction (const (putStrLn "Hello!"))>>> "Greetings!" &> (logStringStdout >* logHello)Greetings!Hello!

A flipped version of >*

lose combinator from Decidable type class.

choose combinator from Decidable type class.

>>> logInt = LogAction print>>> f = choose (\a -> if a < 0 then Left "Negative" else Right a)>>> f logStringStdout logInt <& 11>>> f logStringStdout logInt <& (-1)Negative

Monadic version of choose.

Operator version of choose id.

>>> dontPrintInt = LogAction (const (putStrLn "Not printing Int"))>>> Left 1 &> (dontPrintInt >|< logStringStdout)Not printing Int>>> (dontPrintInt >|< logStringStdout) <& Right ":)":)

If msg is Monoid then extract performs given log action by passing mempty to it.

>>> logPrint :: LogAction IO [Int]; logPrint = LogAction print>>> extract logPrint[]

This is a comonadic extend. It allows you to chain different transformations on messages.

>>> f (LogAction l) = l ".f1" *> l ".f2">>> g (LogAction l) = l ".g">>> logStringStdout <& "foo"foo>>> extend f logStringStdout <& "foo"foo.f1foo.f2>>> (extend g $ extend f logStringStdout) <& "foo"foo.g.f1foo.g.f2>>> (logStringStdout =>> f =>> g) <& "foo"foo.g.f1foo.g.f2

extend with the arguments swapped. Dual to >>= for a Monad.

extend in operator form.

Converts any LogAction that can log single message to the LogAction that can log two messages. The new LogAction behaves in the following way:

1. Joins two messages of type msg using <> operator from Semigroup.

2. Passes resulted message to the given LogAction.

>>> :{let logger :: LogAction IO [Int]    logger = logPrintin duplicate logger <& ([3, 4], [42, 10]):}[3,4,42,10]

Implementation note:

True and fair translation of the duplicate function from the Comonad interface should result in the LogAction of the following form:

msg -> msg -> m ()

In order to capture this behavior, duplicate should have the following type:

duplicate :: Semigroup msg => LogAction m msg -> LogAction (Compose ((->) msg) m) msg

However, it's quite awkward to work with such type. It's a known fact that the following two types are isomorphic (see functions curry and uncurry):

a -> b -> c
(a, b) -> c

So using this fact we can come up with the simpler interface.

Like duplicate but why stop on a pair of two messages if you can log any Foldable of messages?

>>> :{let logger :: LogAction IO [Int]    logger = logPrintin multiplicate logger <& replicate 5 [1..3]:}[1,2,3,1,2,3,1,2,3,1,2,3,1,2,3]

Like multiplicate but instead of logging a batch of messages it logs each of them separately.

>>> :{let logger :: LogAction IO Int    logger = logPrintin separate logger <& [1..5]:}12345

Allows changing the internal monadic action.

Let's say we have a pure logger action using PureLogger and we want to log all messages into IO instead.

If we provide the following function:

performPureLogsInIO :: PureLogger a -> IO a

then we can convert a logger action that uses a pure monad to a one that performs the logging in the IO monad using:

hoistLogAction performPureLogsInIO :: LogAction (PureLogger a) a -> LogAction IO a