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


-- | Composable Contravariant Comonadic Logging Library
--   
--   This package provides core types and functions to work with the
--   <tt>LogAction</tt> data type which is both simple and powerful.
--   
--   <pre>
--   <b>newtype</b> LogAction m msg = LogAction
--       { unLogAction :: msg -&gt; m ()
--       }
--   </pre>
--   
--   The ideas behind this package are described in the following blog
--   post:
--   
--   <ul>
--   <li><a>co-log: Composable Contravariant Combinatorial Comonadic
--   Configurable Convenient Logging</a></li>
--   </ul>
--   
--   See the following packages for different implementations based on
--   <tt>co-log-core</tt>:
--   
--   <ul>
--   <li><a>co-log</a>: taggless final implementations.</li>
--   <li><a>co-log-polysemy</a>: extensible effects implementation based on
--   <tt>polysemy</tt>.</li>
--   </ul>
@package co-log-core
@version 0.3.2.5


-- | Implements core data types and combinators for logging actions.
module Colog.Core.Action

-- | Polymorphic and very general logging action type.
--   
--   <ul>
--   <li><tt><b>msg</b></tt> type variables is an input for logger. It can
--   be <a>Text</a> or custom logging messsage with different fields that
--   you want to format in future.</li>
--   <li><tt><b>m</b></tt> type variable is for monadic action inside which
--   logging is happening. It can be either <a>IO</a> or some custom pure
--   monad.</li>
--   </ul>
--   
--   Key design point here is that <a>LogAction</a> is:
--   
--   <ul>
--   <li><a>Semigroup</a></li>
--   <li><a>Monoid</a></li>
--   <li><a>Contravariant</a></li>
--   <li><a>Divisible</a></li>
--   <li><a>Decidable</a></li>
--   <li><a>Comonad</a></li>
--   </ul>
newtype LogAction (m :: Type -> Type) msg
LogAction :: (msg -> m ()) -> LogAction (m :: Type -> Type) msg
[unLogAction] :: LogAction (m :: Type -> Type) msg -> msg -> m ()

-- | Operator version of <a>unLogAction</a>. Note that because of the
--   types, something like:
--   
--   <pre>
--   action &lt;&amp; msg1 &lt;&amp; msg2
--   </pre>
--   
--   doesn't make sense. Instead you want:
--   
--   <pre>
--   action &lt;&amp; msg1 &gt;&gt; action &lt;&amp; msg2
--   </pre>
--   
--   In addition, because <a>&lt;&amp;</a> has higher precedence than the
--   other operators in this module, the following:
--   
--   <pre>
--   f &gt;$&lt; action &lt;&amp; msg
--   </pre>
--   
--   is equivalent to:
--   
--   <pre>
--   (f &gt;$&lt; action) &lt;&amp; msg
--   </pre>
(<&) :: LogAction m msg -> msg -> m ()
infix 5 <&

-- | A flipped version of <a>&lt;&amp;</a>.
--   
--   It shares the same precedence as <a>&lt;&amp;</a>, so make sure to
--   surround lower precedence operators in parentheses:
--   
--   <pre>
--   msg &amp;&gt; (f &gt;$&lt; action)
--   </pre>
(&>) :: msg -> LogAction m msg -> m ()
infix 5 &>

-- | Joins some <a>Foldable</a> of <a>LogAction</a>s into single
--   <a>LogAction</a> using <a>Semigroup</a> instance for <a>LogAction</a>.
--   This is basically specialized version of <a>fold</a> function.
foldActions :: forall t (m :: Type -> Type) a. (Foldable t, Applicative m) => t (LogAction m a) -> LogAction m a

-- | Takes predicate and performs given logging action only if predicate
--   returns <a>True</a> on input logging message.
cfilter :: forall (m :: Type -> Type) msg. Applicative m => (msg -> Bool) -> LogAction m msg -> LogAction m msg

-- | 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.
--   
--   <pre>
--   isWeekendM :: MessageWithTimestamp -&gt; IO Bool
--   </pre>
--   
--   And use it with <a>cfilterM</a> like this
--   
--   <pre>
--   logMessageAction :: <a>LogAction</a> m MessageWithTimestamp
--   
--   logWeekendAction :: <a>LogAction</a> m MessageWithTimestamp
--   logWeekendAction = cfilterM isWeekendM logMessageAction
--   </pre>
cfilterM :: Monad m => (msg -> m Bool) -> LogAction m msg -> LogAction m msg

-- | This combinator is <tt>contramap</tt> from contravariant functor. It
--   is useful when you have something like
--   
--   <pre>
--   <b>data</b> LogRecord = LR
--       { lrName    :: LoggerName
--       , lrMessage :: Text
--       }
--   </pre>
--   
--   and you need to provide <a>LogAction</a> which consumes
--   <tt>LogRecord</tt>
--   
--   <pre>
--   logRecordAction :: <a>LogAction</a> m LogRecord
--   </pre>
--   
--   when you only have action that consumes <a>Text</a>
--   
--   <pre>
--   logTextAction :: <a>LogAction</a> m Text
--   </pre>
--   
--   With <a>cmap</a> you can do the following:
--   
--   <pre>
--   logRecordAction :: <a>LogAction</a> m LogRecord
--   logRecordAction = <a>cmap</a> lrMesssage logTextAction
--   </pre>
--   
--   This action will print only <tt>lrMessage</tt> from
--   <tt>LogRecord</tt>. But if you have formatting function like this:
--   
--   <pre>
--   formatLogRecord :: LogRecord -&gt; Text
--   </pre>
--   
--   you can apply it instead of <tt>lrMessage</tt> to log formatted
--   <tt>LogRecord</tt> as <a>Text</a>.
cmap :: forall a b (m :: Type -> Type). (a -> b) -> LogAction m b -> LogAction m a

-- | Operator version of <a>cmap</a>.
--   
--   <pre>
--   &gt;&gt;&gt; 1 &amp;&gt; (show &gt;$&lt; logStringStdout)
--   1
--   </pre>
(>$<) :: forall a b (m :: Type -> Type). (a -> b) -> LogAction m b -> LogAction m a
infixr 3 >$<

-- | <a>cmap</a> for convertions that may fail
cmapMaybe :: forall (m :: Type -> Type) a b. Applicative m => (a -> Maybe b) -> LogAction m b -> LogAction m a

-- | Similar to <a>cmapMaybe</a> but for convertions that may fail inside a
--   monadic context.
cmapMaybeM :: Monad m => (a -> m (Maybe b)) -> LogAction m b -> LogAction m a

-- | This combinator is <tt>&gt;$</tt> from contravariant functor. Replaces
--   all locations in the output with the same value. The default
--   definition is <tt>contramap . const</tt>, so this is a more efficient
--   version.
--   
--   <pre>
--   &gt;&gt;&gt; "Hello?" &amp;&gt; ("OUT OF SERVICE" &gt;$ logStringStdout)
--   OUT OF SERVICE
--   
--   &gt;&gt;&gt; ("OUT OF SERVICE" &gt;$ logStringStdout) &lt;&amp; 42
--   OUT OF SERVICE
--   </pre>
(>$) :: forall b (m :: Type -> Type) a. b -> LogAction m b -> LogAction m a
infixl 4 >$

-- | <a>cmapM</a> combinator is similar to <a>cmap</a> but allows to call
--   monadic functions (functions that require extra context) to extend
--   consumed value. Consider the following example.
--   
--   You have this logging record:
--   
--   <pre>
--   <b>data</b> LogRecord = LR
--       { lrTime    :: UTCTime
--       , lrMessage :: Text
--       }
--   </pre>
--   
--   and you also have logging consumer inside <a>IO</a> for such record:
--   
--   <pre>
--   logRecordAction :: <a>LogAction</a> IO LogRecord
--   </pre>
--   
--   But you need to return consumer only for <a>Text</a> messages:
--   
--   <pre>
--   logTextAction :: <a>LogAction</a> IO Text
--   </pre>
--   
--   If you have function that can extend <a>Text</a> to <tt>LogRecord</tt>
--   like the function below:
--   
--   <pre>
--   withTime :: <a>Text</a> -&gt; <a>IO</a> LogRecord
--   withTime msg = <b>do</b>
--       time &lt;- getCurrentTime
--       pure (LR time msg)
--   </pre>
--   
--   you can achieve desired behavior with <a>cmapM</a> in the following
--   way:
--   
--   <pre>
--   logTextAction :: <a>LogAction</a> IO Text
--   logTextAction = <a>cmapM</a> withTime myAction
--   </pre>
cmapM :: Monad m => (a -> m b) -> LogAction m b -> LogAction m a

-- | <tt>divide</tt> combinator from <tt>Divisible</tt> type class.
--   
--   <pre>
--   &gt;&gt;&gt; logInt = LogAction print
--   
--   &gt;&gt;&gt; "ABC" &amp;&gt; divide (\s -&gt; (s, length s)) logStringStdout logInt
--   ABC
--   3
--   </pre>
divide :: forall (m :: Type -> Type) a b c. Applicative m => (a -> (b, c)) -> LogAction m b -> LogAction m c -> LogAction m a

-- | Monadic version of <a>divide</a>.
divideM :: Monad m => (a -> m (b, c)) -> LogAction m b -> LogAction m c -> LogAction m a

-- | <tt>conquer</tt> combinator from <tt>Divisible</tt> type class.
--   
--   Concretely, this is a <a>LogAction</a> that does nothing:
--   
--   <pre>
--   &gt;&gt;&gt; conquer &lt;&amp; "hello?"
--   
--   &gt;&gt;&gt; "hello?" &amp;&gt; conquer
--   </pre>
conquer :: forall (m :: Type -> Type) a. Applicative m => LogAction m a

-- | Operator version of <tt><a>divide</a> <a>id</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; logInt = LogAction print
--   
--   &gt;&gt;&gt; (logStringStdout &gt;*&lt; logInt) &lt;&amp; ("foo", 1)
--   foo
--   1
--   
--   &gt;&gt;&gt; (logInt &gt;*&lt; logStringStdout) &lt;&amp; (1, "foo")
--   1
--   foo
--   </pre>
(>*<) :: forall (m :: Type -> Type) a b. Applicative m => LogAction m a -> LogAction m b -> LogAction m (a, b)
infixr 4 >*<

-- | Perform a constant log action after another.
--   
--   <pre>
--   &gt;&gt;&gt; logHello = LogAction (const (putStrLn "Hello!"))
--   
--   &gt;&gt;&gt; "Greetings!" &amp;&gt; (logStringStdout &gt;* logHello)
--   Greetings!
--   Hello!
--   </pre>
(>*) :: forall (m :: Type -> Type) a. Applicative m => LogAction m a -> LogAction m () -> LogAction m a
infixr 4 >*

-- | A flipped version of <a>&gt;*</a>
(*<) :: forall (m :: Type -> Type) a. Applicative m => LogAction m () -> LogAction m a -> LogAction m a
infixr 4 *<

-- | <tt>lose</tt> combinator from <tt>Decidable</tt> type class.
lose :: forall a (m :: Type -> Type). (a -> Void) -> LogAction m a

-- | <tt>choose</tt> combinator from <tt>Decidable</tt> type class.
--   
--   <pre>
--   &gt;&gt;&gt; logInt = LogAction print
--   
--   &gt;&gt;&gt; f = choose (\a -&gt; if a &lt; 0 then Left "Negative" else Right a)
--   
--   &gt;&gt;&gt; f logStringStdout logInt &lt;&amp; 1
--   1
--   
--   &gt;&gt;&gt; f logStringStdout logInt &lt;&amp; (-1)
--   Negative
--   </pre>
choose :: forall a b c (m :: Type -> Type). (a -> Either b c) -> LogAction m b -> LogAction m c -> LogAction m a

-- | Monadic version of <a>choose</a>.
chooseM :: Monad m => (a -> m (Either b c)) -> LogAction m b -> LogAction m c -> LogAction m a

-- | Operator version of <tt><a>choose</a> <a>id</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; dontPrintInt = LogAction (const (putStrLn "Not printing Int"))
--   
--   &gt;&gt;&gt; Left 1 &amp;&gt; (dontPrintInt &gt;|&lt; logStringStdout)
--   Not printing Int
--   
--   &gt;&gt;&gt; (dontPrintInt &gt;|&lt; logStringStdout) &lt;&amp; Right ":)"
--   :)
--   </pre>
(>|<) :: forall (m :: Type -> Type) a b. LogAction m a -> LogAction m b -> LogAction m (Either a b)
infixr 3 >|<

-- | If <tt>msg</tt> is <a>Monoid</a> then <a>extract</a> performs given
--   log action by passing <a>mempty</a> to it.
--   
--   <pre>
--   &gt;&gt;&gt; logPrint :: LogAction IO [Int]; logPrint = LogAction print
--   
--   &gt;&gt;&gt; extract logPrint
--   []
--   </pre>
extract :: Monoid msg => LogAction m msg -> m ()

-- | This is a <i>comonadic extend</i>. It allows you to chain different
--   transformations on messages.
--   
--   <pre>
--   &gt;&gt;&gt; f (LogAction l) = l ".f1" *&gt; l ".f2"
--   
--   &gt;&gt;&gt; g (LogAction l) = l ".g"
--   
--   &gt;&gt;&gt; logStringStdout &lt;&amp; "foo"
--   foo
--   
--   &gt;&gt;&gt; extend f logStringStdout &lt;&amp; "foo"
--   foo.f1
--   foo.f2
--   
--   &gt;&gt;&gt; (extend g $ extend f logStringStdout) &lt;&amp; "foo"
--   foo.g.f1
--   foo.g.f2
--   
--   &gt;&gt;&gt; (logStringStdout =&gt;&gt; f =&gt;&gt; g) &lt;&amp; "foo"
--   foo.g.f1
--   foo.g.f2
--   </pre>
extend :: Semigroup msg => (LogAction m msg -> m ()) -> LogAction m msg -> LogAction m msg

-- | <a>extend</a> with the arguments swapped. Dual to <a>&gt;&gt;=</a> for
--   a <a>Monad</a>.
(=>>) :: Semigroup msg => LogAction m msg -> (LogAction m msg -> m ()) -> LogAction m msg
infixl 1 =>>

-- | <a>extend</a> in operator form.
(<<=) :: Semigroup msg => (LogAction m msg -> m ()) -> LogAction m msg -> LogAction m msg
infixr 1 <<=

-- | Converts any <a>LogAction</a> that can log single message to the
--   <a>LogAction</a> that can log two messages. The new <a>LogAction</a>
--   behaves in the following way:
--   
--   <ol>
--   <li>Joins two messages of type <tt>msg</tt> using <a>&lt;&gt;</a>
--   operator from <a>Semigroup</a>.</li>
--   <li>Passes resulted message to the given <a>LogAction</a>.</li>
--   </ol>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let logger :: LogAction IO [Int]
--       logger = logPrint
--   in duplicate logger &lt;&amp; ([3, 4], [42, 10])
--   :}
--   [3,4,42,10]
--   </pre>
--   
--   <b>Implementation note:</b>
--   
--   True and fair translation of the <tt>duplicate</tt> function from the
--   <a>Comonad</a> interface should result in the <a>LogAction</a> of the
--   following form:
--   
--   <pre>
--   msg -&gt; msg -&gt; m ()
--   </pre>
--   
--   In order to capture this behavior, <a>duplicate</a> should have the
--   following type:
--   
--   <pre>
--   duplicate :: Semigroup msg =&gt; LogAction m msg -&gt; LogAction (Compose ((-&gt;) msg) m) msg
--   </pre>
--   
--   However, it's quite awkward to work with such type. It's a known fact
--   that the following two types are isomorphic (see functions
--   <a>curry</a> and <a>uncurry</a>):
--   
--   <pre>
--   a -&gt; b -&gt; c
--   (a, b) -&gt; c
--   </pre>
--   
--   So using this fact we can come up with the simpler interface.
duplicate :: forall msg (m :: Type -> Type). Semigroup msg => LogAction m msg -> LogAction m (msg, msg)

-- | Like <a>duplicate</a> but why stop on a pair of two messages if you
--   can log any <a>Foldable</a> of messages?
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let logger :: LogAction IO [Int]
--       logger = logPrint
--   in multiplicate logger &lt;&amp; replicate 5 [1..3]
--   :}
--   [1,2,3,1,2,3,1,2,3,1,2,3,1,2,3]
--   </pre>
multiplicate :: forall f msg (m :: Type -> Type). (Foldable f, Monoid msg) => LogAction m msg -> LogAction m (f msg)

-- | Like <a>multiplicate</a> but instead of logging a batch of messages it
--   logs each of them separately.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let logger :: LogAction IO Int
--       logger = logPrint
--   in separate logger &lt;&amp; [1..5]
--   :}
--   1
--   2
--   3
--   4
--   5
--   </pre>
separate :: forall f msg (m :: Type -> Type). (Traversable f, Applicative m) => LogAction m msg -> LogAction m (f msg)

-- | Allows changing the internal monadic action.
--   
--   Let's say we have a pure logger action using <tt>PureLogger</tt> and
--   we want to log all messages into <a>IO</a> instead.
--   
--   If we provide the following function:
--   
--   <pre>
--   performPureLogsInIO :: PureLogger a -&gt; IO a
--   </pre>
--   
--   then we can convert a logger action that uses a pure monad to a one
--   that performs the logging in the <a>IO</a> monad using:
--   
--   <pre>
--   hoistLogAction performPureLogsInIO :: LogAction (PureLogger a) a -&gt; LogAction IO a
--   </pre>
hoistLogAction :: (forall x. () => m x -> n x) -> LogAction m a -> LogAction n a
instance Data.Functor.Contravariant.Contravariant (Colog.Core.Action.LogAction m)
instance Colog.Core.Action.UnrepresentableClass => GHC.Internal.Base.Functor (Colog.Core.Action.LogAction m)
instance GHC.Internal.Base.Applicative m => GHC.Internal.Base.Monoid (Colog.Core.Action.LogAction m a)
instance GHC.Internal.Base.Applicative m => GHC.Internal.Base.Semigroup (Colog.Core.Action.LogAction m a)


-- | Provides type class for values that has access to <a>LogAction</a>.
module Colog.Core.Class

-- | This types class contains simple pair of getter-setter and related
--   functions. It also provides the useful lens <a>logActionL</a> with the
--   default implementation using type class methods. The default one could
--   be easily overritten under your instances.
--   
--   Every instance of the this typeclass should satisfy the following
--   laws:
--   
--   <ol>
--   <li><b>Set-Get:</b> <tt><a>getLogAction</a> (<a>setLogAction</a> l
--   env) ≡ l</tt></li>
--   <li><b>Get-Set:</b> <tt><a>setLogAction</a> (<a>getLogAction</a> env)
--   env ≡ env</tt></li>
--   <li><b>Set-Set:</b> <tt><a>setLogAction</a> l2 (<a>setLogAction</a> l1
--   env) ≡ <a>setLogAction</a> l2 env</tt></li>
--   <li><b>Set-Over:</b> <tt><a>overLogAction</a> f env ≡
--   <a>setLogAction</a> (f $ <a>getLogAction</a> env) env</tt></li>
--   </ol>
class HasLog env msg (m :: Type -> Type)

-- | Extracts <a>LogAction</a> from the environment.
getLogAction :: HasLog env msg m => env -> LogAction m msg

-- | Sets <a>LogAction</a> to the given one inside the environment.
setLogAction :: HasLog env msg m => LogAction m msg -> env -> env

-- | Applies function to the <a>LogAction</a> inside the environment.
overLogAction :: HasLog env msg m => (LogAction m msg -> LogAction m msg) -> env -> env

-- | Lens for <a>LogAction</a> inside the environment.
logActionL :: HasLog env msg m => Lens' env (LogAction m msg)

-- | The monomorphic lenses which don't change the type of the container
--   (or of the value inside).
type Lens' s a = forall (f :: Type -> Type). Functor f => a -> f a -> s -> f s
instance Colog.Core.Class.HasLog (Colog.Core.Action.LogAction m msg) msg m


-- | Introduces logging actions working in <a>MonadIO</a>. These actions
--   are very basic and inefficient because they use the <a>String</a> data
--   type. If you don't want to have extra dependencies and performance of
--   logging is not the bottleneck of your application, then these
--   functions should be enough. Otherwise use functions from the
--   <a>Colog.Actions</a> module from the <tt>co-log</tt> package.
module Colog.Core.IO

-- | Action that prints <a>String</a> to stdout. This action does not flush
--   the output buffer. If buffering mode is block buffering, the effect of
--   this action can be delayed.
--   
--   <pre>
--   &gt;&gt;&gt; logStringStdout &lt;&amp; "foo"
--   foo
--   </pre>
logStringStdout :: forall (m :: Type -> Type). MonadIO m => LogAction m String

-- | Action that prints <a>String</a> to stderr. This action does not flush
--   the output buffer. If buffering mode is block buffering, the effect of
--   this action can be delayed.
--   
--   <pre>
--   &gt;&gt;&gt; logStringStderr &lt;&amp; "foo"
--   foo
--   </pre>
logStringStderr :: forall (m :: Type -> Type). MonadIO m => LogAction m String

-- | Action that prints <a>String</a> to <a>Handle</a>. This action does
--   not flush the output buffer. If buffering mode is block buffering, the
--   effect of this action can be delayed.
--   
--   <pre>
--   &gt;&gt;&gt; logStringHandle stderr &lt;&amp; "foo"
--   foo
--   </pre>
logStringHandle :: forall (m :: Type -> Type). MonadIO m => Handle -> LogAction m String

-- | Action that prints <a>String</a> to file. Instead of returning
--   <a>LogAction</a> it's implemented in continuation-passing style
--   because it's more efficient to open file only once at the start of the
--   application and write to <a>Handle</a> instead of opening file each
--   time we need to write to it.
--   
--   Opens file in <a>AppendMode</a>. Automatically flushes the output
--   buffer.
--   
--   <pre>
--   &gt;&gt;&gt; logger action = action &lt;&amp; "foo"
--   
--   &gt;&gt;&gt; withLogStringFile "/dev/stdout" logger
--   foo
--   </pre>
withLogStringFile :: forall (m :: Type -> Type) r. MonadIO m => FilePath -> (LogAction m String -> IO r) -> IO r

-- | Action that prints to stdout using <a>Show</a>. This action does not
--   flush the output buffer. If buffering mode is block buffering, the
--   effect of this action can be delayed.
--   
--   <pre>
--   &gt;&gt;&gt; logPrint &lt;&amp; 5
--   5
--   </pre>
logPrint :: forall a (m :: Type -> Type). (Show a, MonadIO m) => LogAction m a

-- | Action that prints to stderr using <a>Show</a>. This action does not
--   flush the output buffer. If buffering mode is block buffering, the
--   effect of this action can be delayed.
--   
--   <pre>
--   &gt;&gt;&gt; logPrintStderr &lt;&amp; 5
--   5
--   </pre>
logPrintStderr :: forall a (m :: Type -> Type). (Show a, MonadIO m) => LogAction m a

-- | Action that prints to a <a>Handle</a> using <a>Show</a>. This action
--   does not flush the output buffer. If buffering mode is block
--   buffering, the effect of this action can be delayed.
--   
--   <pre>
--   &gt;&gt;&gt; logPrintHandle stderr &lt;&amp; 5
--   5
--   </pre>
logPrintHandle :: forall a (m :: Type -> Type). (Show a, MonadIO m) => Handle -> LogAction m a

-- | Action that prints to a file using <a>Show</a>. See
--   <a>withLogStringFile</a> for details.
withLogPrintFile :: forall a (m :: Type -> Type) r. (Show a, MonadIO m) => FilePath -> (LogAction m a -> IO r) -> IO r

-- | Lifts a LogAction over IO into a more general Monad.
--   
--   <pre>
--   &gt;&gt;&gt; logToStdout = LogAction putStrLn
--   
--   &gt;&gt;&gt; liftLogIO logToStdout &lt;&amp; "foo"
--   foo
--   </pre>
liftLogIO :: forall (m :: Type -> Type) msg. MonadIO m => LogAction IO msg -> LogAction m msg

-- | This action can be used in combination with other actions to flush a
--   handle every time you log anything.
logFlush :: forall (m :: Type -> Type) a. MonadIO m => Handle -> LogAction m a


-- | This module introduces <a>Severity</a> data type for expressing how
--   severe the message is. Also, it contains useful functions and patterns
--   for work with <a>Severity</a>.
--   
--   TODO: table
module Colog.Core.Severity

-- | Severity for the log messages.
data Severity

-- | Information useful for debug purposes.
--   
--   E.g. output of the function that is important for the internal
--   development, not for users. Like, the result of SQL query.
Debug :: Severity

-- | Normal operational information.
--   
--   E.g. describing general steps: starting application, finished
--   downloading.
Info :: Severity

-- | General warnings, non-critical failures.
--   
--   E.g. couldn't download icon from some service to display.
Warning :: Severity

-- | General errors/severe errors.
--   
--   E.g. exceptional situations: couldn't syncronize accounts.
Error :: Severity
pattern D :: Severity
pattern I :: Severity
pattern W :: Severity
pattern E :: Severity

-- | Filters messages by the given <a>Severity</a>.
filterBySeverity :: forall (m :: Type -> Type) a. Applicative m => Severity -> (a -> Severity) -> LogAction m a -> LogAction m a

-- | A message tagged with a <a>Severity</a>.
--   
--   It is common to want to log various types of messages tagged with a
--   severity. <a>WithSeverity</a> provides a standard way to do so while
--   allowing the messages to be processed independently of the severity.
--   
--   It is easy to <tt>cmap</tt> over a 'LogAction m (WithSeverity a)', or
--   to filter based on the severity.
--   
--   <pre>
--   logSomething :: <a>LogAction</a> m (<a>WithSeverity</a> <a>String</a>) -&gt; m ()
--   logSomething logger = logger &lt;&amp; "hello" `WithSeverity` <a>Info</a>
--   
--   cmap' :: (b -&gt; a) -&gt; <a>LogAction</a> m (<a>WithSeverity</a> a) -&gt; <a>LogAction</a> m (<a>WithSeverity</a> b)
--   cmap' f action = <tt>cmap</tt> (<a>fmap</a> f) action
--   
--   filterBySeverity' :: (<a>Applicative</a> m) =&gt; <a>Severity</a> -&gt; <a>LogAction</a> m (<a>WithSeverity</a> a) -&gt; <a>LogAction</a> m (<a>WithSeverity</a> a)
--   filterBySeverity' threshold action = <a>filterBySeverity</a> threshold <a>getSeverity</a> action
--   </pre>
data WithSeverity msg
WithSeverity :: msg -> Severity -> WithSeverity msg
[getMsg] :: WithSeverity msg -> msg
[getSeverity] :: WithSeverity msg -> Severity

-- | Map the given function over the severity of a <a>WithSeverity</a>.
--   
--   This can be useful to operate generically over the severity, for
--   example:
--   
--   <pre>
--   suppressErrors :: <a>LogAction</a> m (<a>WithSeverity</a> msg) -&gt; <a>LogAction</a> m (<a>WithSeverity</a> msg)
--   suppressErrors = <tt>cmap</tt> (<a>mapSeverity</a> (s -&gt; if s == <a>Error</a> then <a>Warning</a> else s))
--   </pre>
mapSeverity :: (Severity -> Severity) -> WithSeverity msg -> WithSeverity msg
instance GHC.Internal.Enum.Bounded Colog.Core.Severity.Severity
instance GHC.Internal.Enum.Enum Colog.Core.Severity.Severity
instance GHC.Classes.Eq Colog.Core.Severity.Severity
instance GHC.Classes.Eq msg => GHC.Classes.Eq (Colog.Core.Severity.WithSeverity msg)
instance GHC.Internal.Data.Foldable.Foldable Colog.Core.Severity.WithSeverity
instance GHC.Internal.Base.Functor Colog.Core.Severity.WithSeverity
instance GHC.Internal.Ix.Ix Colog.Core.Severity.Severity
instance GHC.Classes.Ord Colog.Core.Severity.Severity
instance GHC.Classes.Ord msg => GHC.Classes.Ord (Colog.Core.Severity.WithSeverity msg)
instance GHC.Internal.Read.Read Colog.Core.Severity.Severity
instance GHC.Internal.Show.Show Colog.Core.Severity.Severity
instance GHC.Internal.Show.Show msg => GHC.Internal.Show.Show (Colog.Core.Severity.WithSeverity msg)
instance GHC.Internal.Data.Traversable.Traversable Colog.Core.Severity.WithSeverity


-- | Exports all core functionality. <tt>co-log-core</tt> is a lightweight
--   package that defines only core data type and various combinators to
--   work with it.
--   
--   Fundamentals of <tt>co-log-core</tt> are based on the following data
--   type:
--   
--   <pre>
--   <b>newtype</b> LogAction m msg = LogAction
--       { unLogAction :: msg -&gt; m ()
--       }
--   </pre>
--   
--   This data type provides extremely composable and flexible interface by
--   having many instances of the standard algebraic data types.
--   
--   The package has the following structure:
--   
--   <ul>
--   <li><b><a>Colog.Core.Action</a>:</b> definition of the main data type
--   and its combinators.</li>
--   <li><b><a>Colog.Core.Class</a>:</b> <a>HasLog</a> typeclass that
--   describes how different values (e.g. application environment) can
--   store and modify <a>LogAction</a>.</li>
--   <li><b><a>Colog.Core.IO</a>:</b> basic loggers that work with
--   <a>MonadIO</a> and <a>String</a>.</li>
--   <li><b><a>Colog.Core.Severity</a>:</b> logger severity.</li>
--   </ul>
module Colog.Core
