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


-- | Logging effect to plug into the simple-effects framework
--   
--   Logging effect to plug into the simple-effects framework
@package simple-logging
@version 0.2.0.2


-- | Use this module to add logging to your monad. A log is a structured
--   value that can hold information like severity, log message, timestamp,
--   callstack, etc.
--   
--   Logging is treated like a stream of logs comming from your application
--   and functions that transform the logs take a stream and output a
--   stream. Functions like <a>logInfo</a> push a new log into the stream
--   and functions like <a>setTimestampToNow</a> take a stream of logs and
--   attach extra info onto each log (current time in this case).
--   
--   Read the documentation of individual functions to get a feel for what
--   you can do.
module Control.Effects.Logging

-- | The logging effect.
data Logging
Logging :: Logging

-- | Arbitrary piece of text. Logs contain a list of these.
newtype Tag
Tag :: Text -> Tag

-- | A name for a "layer" of your application. Typically, a log will
--   contain a stack of contexts. Think of it as a call stack specific for
--   your application.
newtype Context
Context :: Text -> Context
[getContext] :: Context -> Text

-- | The severity of the log.
data Level
Debug :: Level
Info :: Level
Warning :: Level
Error :: Level
Fatal :: Level

-- | If a notion of a user exists for your application, you can add this
--   information to your logs.
data LogUser
LogUser :: Text -> Maybe Text -> Maybe Text -> LogUser
[logUserId] :: LogUser -> Text
[logUserEmail] :: LogUser -> Maybe Text
[logUserUsername] :: LogUser -> Maybe Text
addIfExists :: Text -> Maybe Value -> [(Text, Value)] -> [(Text, Value)]

-- | Breadcrumbs are the steps that happened before a log.
data Crumb
Crumb :: UTCTime -> Maybe Text -> Text -> CrumbData -> Crumb
[crumbTimestamp] :: Crumb -> UTCTime
[crumbMessage] :: Crumb -> Maybe Text
[crumbCategory] :: Crumb -> Text
[crumbData] :: Crumb -> CrumbData

-- | Crumbs come in two varieties. A normal crumb is a list of key-value
--   pairs. There's also a <a>HttpCrumb</a> where you can put more specific
--   information about the processed HTTP request (if your application is a
--   web server).
data CrumbData
DefaultCrumb :: [(Text, Value)] -> CrumbData
HttpCrumb :: Text -> Text -> Int -> Text -> CrumbData
[crumbUrl] :: CrumbData -> Text
[crumbMethod] :: CrumbData -> Text
[crumbStatusCode] :: CrumbData -> Int
[crumbReason] :: CrumbData -> Text

-- | Logs can hold arbitrary data serialized as a <a>ByteString</a>.
--   Additionally, a summary can be provided which is intended to be
--   displayed fully in log summaries.
data LogData
LogData :: ByteString -> Text -> LogData
[dataPayload] :: LogData -> ByteString
[dataSummary] :: LogData -> Text
data Log
Log :: Text -> Level -> [Tag] -> [Context] -> Maybe LogUser -> [Crumb] -> LogData -> Maybe UTCTime -> CallStack -> Log
[logMessage] :: Log -> Text
[logLevel] :: Log -> Level
[logTags] :: Log -> [Tag]
[logContext] :: Log -> [Context]
[logUser] :: Log -> Maybe LogUser
[logCrumbs] :: Log -> [Crumb]
[logData] :: Log -> LogData
[logTimestamp] :: Log -> Maybe UTCTime
[logCallStack] :: Log -> CallStack

-- | A generic exception holding only a piece of text.
newtype GenericException
GenericException :: Text -> GenericException

-- | Send a single log into the stream.
logEffect :: MonadEffect Logging m => Log -> m ()

-- | A generic handler for logs. Since it's polymorphic in <tt>m</tt> you
--   can choose to emit more logs and make it a log transformer instead.
handleLogging :: Functor m => (Log -> m ()) -> EffectHandler Logging m a -> m a

-- | Add a new context on top of every log that comes from the given
--   computation.
layerLogs :: (HasCallStack, MonadEffect Logging m) => Context -> EffectHandler Logging m a -> m a

-- | Get the bottom-most context if it exists.
originContext :: Log -> Maybe Context
logWithLevel :: (HasCallStack, MonadEffect Logging m) => Level -> Text -> m ()
logInfo :: (HasCallStack, MonadEffect Logging m) => Text -> m ()
logWarning :: (HasCallStack, MonadEffect Logging m) => Text -> m ()
logError :: (HasCallStack, MonadEffect Logging m) => Text -> m ()
logDebug :: (HasCallStack, MonadEffect Logging m) => Text -> m ()
logFatal :: (HasCallStack, MonadEffect Logging m) => Text -> m ()

-- | Log an error and then throw the given exception.
logAndError :: (Exception e, MonadEffect Logging m, MonadThrow m, HasCallStack) => Text -> e -> m a

-- | Log an error and then throw a checked exception. Read about checked
--   exceptions in <a>Signal</a>.
logAndThrowsErr :: (MonadEffect Logging m, Throws e m, HasCallStack) => Text -> e -> m a

-- | Log an error and throw a generic exception containing the text of the
--   error message.
logAndThrowGeneric :: (MonadEffect Logging m, MonadThrow m, HasCallStack) => Text -> m a

-- | Log a stripped-down version of the logs to the console. Only contains
--   the message and the severity.
logMessagesToStdout :: MonadIO m => EffectHandler Logging m a -> m a

-- | Log everything to the console. Uses the <a>Show</a> instance for
--   <a>Log</a>.
logRawToStdout :: MonadIO m => EffectHandler Logging m a -> m a

-- | Discard the logs.
muteLogs :: Monad m => EffectHandler Logging m a -> m a

-- | Use the given function to transform and possibly discard logs.
witherLogs :: MonadEffect Logging m => (Log -> m (Maybe Log)) -> EffectHandler Logging m a -> m a

-- | Only let through logs that satisfy the given predicate.
filterLogs :: MonadEffect Logging m => (Log -> Bool) -> EffectHandler Logging m a -> m a

-- | Transform logs with the given function.
mapLogs :: MonadEffect Logging m => (Log -> m Log) -> EffectHandler Logging m a -> m a

-- | Filter out logs that are comming from below a certain depth.
logIfDepthLessThan :: MonadEffect Logging m => Int -> EffectHandler Logging m a -> m a

-- | Filter logs whose depth satisfies the given predicate.
logIfDepth :: MonadEffect Logging m => (Int -> Bool) -> EffectHandler Logging m a -> m a

-- | For each log, add it's message to the logs breadcrumb list. This is
--   useful so you don't have to manually add crumbs.
messagesToCrumbs :: (MonadIO m, MonadEffect Logging m) => EffectHandler Logging m a -> m a

-- | Each log that passes through will get all of the crumbs of the
--   previous logs added. If, for example, you're writing a web server, you
--   might want to have this handler over the request handler so that if an
--   error occurs you can see all the steps that happened before it, during
--   the handling of that request.
collectCrumbs :: MonadEffect Logging m => EffectHandler Logging (StateT [Crumb] m) a -> m a

-- | Add a user to every log.
addUserToLogs :: MonadEffect Logging m => LogUser -> EffectHandler Logging m a -> m a

-- | Add a crumb to every log.
addCrumbToLogs :: MonadEffect Logging m => Crumb -> EffectHandler Logging m a -> m a

-- | Attach arbitrary data to every log. Typically you want to use this
--   handler on <tt>logX</tt> functions directly like
--   <tt>setDataWithSummary "some data" (logInfo "some info")</tt>
setDataWithSummary :: MonadEffect Logging m => LogData -> EffectHandler Logging m a -> m a

-- | Attach an arbitrary <a>ByteString</a> to every log. Typically you want
--   to use this handler on <tt>logX</tt> functions directly like
--   <tt>setDataTo "some data" (logInfo "some info")</tt>
setDataTo :: MonadEffect Logging m => ByteString -> EffectHandler Logging m a -> m a

-- | Attach an arbitrary value to every log using it's <a>ToJSON</a>
--   instance. Typically you want to use this handler on <tt>logX</tt>
--   functions directly like <tt>setDataToJsonOf 123 (logInfo "some
--   info")</tt>
setDataToJsonOf :: (MonadEffect Logging m, ToJSON v) => v -> EffectHandler Logging m a -> m a

-- | Attach an arbitrary value to every log using it's <a>Show</a>
--   instance. Typically you want to use this handler on <tt>logX</tt>
--   functions directly like <tt>setDataToShowOf 123 (logInfo "some
--   info")</tt>
setDataToShowOf :: (MonadEffect Logging m, Show v) => v -> EffectHandler Logging m a -> m a

-- | Add the current time to every log.
setTimestampToNow :: (MonadEffect Logging m, MonadIO m) => EffectHandler Logging m a -> m a
highlightT :: [Highlight] -> Text -> Text
yellow :: Text -> Text
colorFromLevel :: Level -> [Highlight]

-- | Puts data of each log into a separate file inside of a given
--   directory. Replaces the data of the logs with the path to the files.
writeDataToFiles :: (MonadEffect Logging m, MonadIO m) => FilePath -> EffectHandler Logging m a -> m a
truncate :: Int -> Text -> Text
manyLines :: Int -> Text -> Text

-- | Print out the logs in rich format. Truncates at the given length. Logs
--   will contain: message, timestamp, data, user and the call stack.
prettyPrintSummary :: MonadIO m => Int -> EffectHandler Logging m a -> m a

-- | Catches all IO exceptions, logs them and throws them back. The
--   callstack in the log is <b>not</b> the callstack of the exception.
logIOExceptions :: (MonadEffect Logging m, MonadCatch m) => m a -> m a
instance GHC.Show.Show Control.Effects.Logging.GenericException
instance GHC.Read.Read Control.Effects.Logging.GenericException
instance GHC.Classes.Ord Control.Effects.Logging.GenericException
instance GHC.Classes.Eq Control.Effects.Logging.GenericException
instance GHC.Show.Show Control.Effects.Logging.Log
instance GHC.Show.Show Control.Effects.Logging.LogData
instance GHC.Read.Read Control.Effects.Logging.LogData
instance GHC.Classes.Ord Control.Effects.Logging.LogData
instance GHC.Classes.Eq Control.Effects.Logging.LogData
instance GHC.Show.Show Control.Effects.Logging.Crumb
instance GHC.Read.Read Control.Effects.Logging.Crumb
instance GHC.Classes.Eq Control.Effects.Logging.Crumb
instance GHC.Show.Show Control.Effects.Logging.CrumbData
instance GHC.Read.Read Control.Effects.Logging.CrumbData
instance GHC.Classes.Eq Control.Effects.Logging.CrumbData
instance GHC.Show.Show Control.Effects.Logging.LogUser
instance GHC.Read.Read Control.Effects.Logging.LogUser
instance GHC.Classes.Ord Control.Effects.Logging.LogUser
instance GHC.Classes.Eq Control.Effects.Logging.LogUser
instance GHC.Show.Show Control.Effects.Logging.Level
instance GHC.Read.Read Control.Effects.Logging.Level
instance GHC.Classes.Ord Control.Effects.Logging.Level
instance GHC.Classes.Eq Control.Effects.Logging.Level
instance GHC.Show.Show Control.Effects.Logging.Context
instance GHC.Read.Read Control.Effects.Logging.Context
instance GHC.Classes.Ord Control.Effects.Logging.Context
instance GHC.Classes.Eq Control.Effects.Logging.Context
instance GHC.Show.Show Control.Effects.Logging.Tag
instance GHC.Read.Read Control.Effects.Logging.Tag
instance GHC.Classes.Ord Control.Effects.Logging.Tag
instance GHC.Classes.Eq Control.Effects.Logging.Tag
instance Data.Aeson.Types.ToJSON.ToJSON Control.Effects.Logging.LogUser
instance Data.Aeson.Types.ToJSON.ToJSON Control.Effects.Logging.CrumbData
instance Data.Aeson.Types.ToJSON.ToJSON Control.Effects.Logging.Crumb
instance Data.String.IsString Control.Effects.Logging.LogData
instance GHC.Exception.Exception Control.Effects.Logging.GenericException