Knit.Effect.Logger

Polysemy logger effect, using pretty-printing and severity based on logging-effect. Adds a Prefixing effect so that it's easy to wrap entire functions, etc. in logging prefixes and thus to distinguish where things are being logged from more easily. Also allows filtering by severity.

Logging Types

data LogSeverity

Severity of message. Based on monad-logger.

Constructors

Diagnostic

Info

Warning

Error

Instances

Bounded LogSeverity

Defined in Knit.Effect.Logger

Methods

minBound :: LogSeverity

maxBound :: LogSeverity

Enum LogSeverity

Defined in Knit.Effect.Logger

Methods

succ :: LogSeverity -> LogSeverity

pred :: LogSeverity -> LogSeverity

toEnum :: Int -> LogSeverity

fromEnum :: LogSeverity -> Int

enumFrom :: LogSeverity -> [LogSeverity]

enumFromThen :: LogSeverity -> LogSeverity -> [LogSeverity]

enumFromTo :: LogSeverity -> LogSeverity -> [LogSeverity]

enumFromThenTo :: LogSeverity -> LogSeverity -> LogSeverity -> [LogSeverity]

Eq LogSeverity

Defined in Knit.Effect.Logger

Methods

(==) :: LogSeverity -> LogSeverity -> Bool

(/=) :: LogSeverity -> LogSeverity -> Bool

Ord LogSeverity

Defined in Knit.Effect.Logger

Methods

compare :: LogSeverity -> LogSeverity -> Ordering

(<) :: LogSeverity -> LogSeverity -> Bool

(<=) :: LogSeverity -> LogSeverity -> Bool

(>) :: LogSeverity -> LogSeverity -> Bool

(>=) :: LogSeverity -> LogSeverity -> Bool

max :: LogSeverity -> LogSeverity -> LogSeverity

min :: LogSeverity -> LogSeverity -> LogSeverity

Show LogSeverity

Defined in Knit.Effect.Logger

Methods

showsPrec :: Int -> LogSeverity -> ShowS

show :: LogSeverity -> String

showList :: [LogSeverity] -> ShowS

data LogEntry

A basic LogEntry with a severity and a (Text) message

Constructors

LogEntry

Fields

• severity :: LogSeverity
• message :: Text

Effects

data Logger a m r where

The Logger effect

Constructors

Log :: a -> Logger a m ()

data PrefixLog m r

Prefix Effect

Actions

log :: Member (Logger a) effs => a -> Sem effs ()

Add one log entry of arbitrary type. If you want to log with another type besides @LogEntry.

logLE :: Member (Logger LogEntry) effs => LogSeverity -> Text -> Sem effs ()

Add one log-entry of the LogEntry type.

wrapPrefix :: Member PrefixLog effs => Text -> Sem effs a -> Sem effs a

Add a prefix for the block of code.

Interpreters

filteredLogEntriesToIO :: MonadIO (Sem effs) => [LogSeverity] -> Sem (Logger LogEntry ': (PrefixLog ': effs)) x -> Sem effs x

Run the Logger and PrefixLog effects using the preferred handler and filter output in any Polysemy monad with IO in the union.

Subsets for filtering

logAll :: [LogSeverity]

LogSeverity list used in order to output everything.

nonDiagnostic :: [LogSeverity]

LogSeverity list used to output all but Diagnostic. Diagnostic messages are sometimes useful for debugging but can get noisy depending on how you use it.

Constraints for convenience

type LogWithPrefixes a effs = (Member PrefixLog effs, Member (Logger a) effs)

Constraint helper for logging with prefixes

type LogWithPrefixesLE effs = LogWithPrefixes LogEntry effs

Constraint helper for LogEntry type with prefixes

Re-Exports

data Sem (r :: [(Type -> Type) -> Type -> Type]) a

The Sem monad handles computations of arbitrary extensible effects. A value of type Sem r describes a program with the capabilities of r. For best results, r should always be kept polymorphic, but you can add capabilities via the Member constraint.

The value of the Sem monad is that it allows you to write programs against a set of effects without a predefined meaning, and provide that meaning later. For example, unlike with mtl, you can decide to interpret an Error effect tradtionally as an Either, or instead significantly faster as an IO Exception. These interpretations (and others that you might add) may be used interchangably without needing to write any newtypes or Monad instances. The only change needed to swap interpretations is to change a call from runError to runErrorInIO.

The effect stack r can contain arbitrary other monads inside of it. These monads are lifted into effects via the Lift effect. Monadic values can be lifted into a Sem via sendM.

A Sem can be interpreted as a pure value (via run) or as any traditional Monad (via runM). Each effect E comes equipped with some interpreters of the form:

runE :: Sem (E ': r) a -> Sem r a

which is responsible for removing the effect E from the effect stack. It is the order in which you call the interpreters that determines the monomorphic representation of the r parameter.

After all of your effects are handled, you'll be left with either a Sem '[] a or a Sem '[ Lift m ] a value, which can be consumed respectively by run and runM.

Examples

As an example of keeping r polymorphic, we can consider the type

Member (State String) r => Sem r ()

to be a program with access to

get :: Sem r String
put :: String -> Sem r ()

methods.

By also adding a

Member (Error Bool) r

constraint on r, we gain access to the

throw :: Bool -> Sem r a
catch :: Sem r a -> (Bool -> Sem r a) -> Sem r a

functions as well.

In this sense, a Member (State s) r constraint is analogous to mtl's MonadState s m and should be thought of as such. However, unlike mtl, a Sem monad may have an arbitrary number of the same effect.

For example, we can write a Sem program which can output either Ints or Bools:

foo :: ( Member (Output Int) r
       , Member (Output Bool) r
       )
    => Sem r ()
foo = do
  output @Int  5
  output True

Notice that we must use -XTypeApplications to specify that we'd like to use the (Output Int) effect.

Since: polysemy-0.1.2.0

Instances

Member (Error PandocError :: (Type -> Type) -> Type -> Type) effs => MonadError PandocError (Sem effs)

Split off the error piece. We will handle directly with the polysemy Error effect

Defined in Knit.Effect.PandocMonad

Methods

throwError :: PandocError -> Sem effs a

catchError :: Sem effs a -> (PandocError -> Sem effs a) -> Sem effs a

Monad (Sem f)

Defined in Polysemy.Internal

Methods

(>>=) :: Sem f a -> (a -> Sem f b) -> Sem f b

(>>) :: Sem f a -> Sem f b -> Sem f b

return :: a -> Sem f a

fail :: String -> Sem f a

Functor (Sem f)

Defined in Polysemy.Internal

Methods

fmap :: (a -> b) -> Sem f a -> Sem f b

(<$) :: a -> Sem f b -> Sem f a

Member Fixpoint r => MonadFix (Sem r)

Defined in Polysemy.Internal

Methods

mfix :: (a -> Sem r a) -> Sem r a

Applicative (Sem f)

Defined in Polysemy.Internal

Methods

pure :: a -> Sem f a

(<*>) :: Sem f (a -> b) -> Sem f a -> Sem f b

liftA2 :: (a -> b -> c) -> Sem f a -> Sem f b -> Sem f c

(*>) :: Sem f a -> Sem f b -> Sem f b

(<*) :: Sem f a -> Sem f b -> Sem f a

Member NonDet r => Alternative (Sem r)

Defined in Polysemy.Internal

Methods

empty :: Sem r a

(<|>) :: Sem r a -> Sem r a -> Sem r a

some :: Sem r a -> Sem r [a]

many :: Sem r a -> Sem r [a]

Member (Lift IO) r => MonadIO (Sem r)

This instance will only lift IO actions. If you want to lift into some other MonadIO type, use this instance, and handle it via the runIO interpretation.

Defined in Polysemy.Internal

Methods

liftIO :: IO a -> Sem r a

PandocEffects effs => PandocMonad (Sem effs)

PandocMonad instance so that pandoc functions can be run in the polysemy union effect

Defined in Knit.Effect.PandocMonad

Methods

lookupEnv :: String -> Sem effs (Maybe String)

getCurrentTime :: Sem effs UTCTime

getCurrentTimeZone :: Sem effs TimeZone

newStdGen :: Sem effs StdGen

newUniqueHash :: Sem effs Int

openURL :: String -> Sem effs (ByteString, Maybe MimeType)

readFileLazy :: FilePath -> Sem effs ByteString

readFileStrict :: FilePath -> Sem effs ByteString

glob :: String -> Sem effs [FilePath]

fileExists :: FilePath -> Sem effs Bool

getDataFileName :: FilePath -> Sem effs FilePath

getModificationTime :: FilePath -> Sem effs UTCTime

getCommonState :: Sem effs CommonState

putCommonState :: CommonState -> Sem effs ()

getsCommonState :: (CommonState -> a) -> Sem effs a

modifyCommonState :: (CommonState -> CommonState) -> Sem effs ()

logOutput :: LogMessage -> Sem effs ()

trace :: String -> Sem effs ()

Member (Random :: (Type -> Type) -> Type -> Type) effs => MonadRandom (Sem effs)

supply instance of MonadRandom for functions which require it

Defined in Knit.Effect.RandomFu

Methods

getRandomPrim :: Prim t -> Sem effs t

getRandomWord8 :: Sem effs Word8

getRandomWord16 :: Sem effs Word16

getRandomWord32 :: Sem effs Word32

getRandomWord64 :: Sem effs Word64

getRandomDouble :: Sem effs Double

getRandomNByteInteger :: Int -> Sem effs Integer

type Member (e :: (Type -> Type) -> Type -> Type) (r :: [(Type -> Type) -> Type -> Type]) = Member' e r

A proof that the effect e is available somewhere inside of the effect stack r.

type Handler (m :: Type -> Type) message = message -> m ()

Handlers are mechanisms to interpret the meaning of logging as an action in the underlying monad. They are simply functions from log messages to m-actions.