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

-- | Versatile logging framework
--   
--   hslogger is a logging framework for Haskell, roughly similar
--   to Python's logging module.
--   
--   hslogger lets each log message have a priority and source be
--   associated with it. The programmer can then define global handlers
--   that route or filter messages based on the priority and source.
--   hslogger also has a Syslog handler built in.
@package hslogger
@version 1.3.2.0

-- | Haskell Logging Framework
--   
--   Written by John Goerzen, jgoerzen@complete.org
--   
--   This module defines basic types used for logging.
--   
--   Extensive documentation is available in System.Log.Logger.
module System.Log

-- | Priorities are used to define how important a log message is. Users
--   can filter log messages based on priorities.
--   
--   These have their roots on the traditional syslog system. The standard
--   definitions are given below, but you are free to interpret them
--   however you like. They are listed here in ascending importance order.
data Priority

-- | Debug messages
DEBUG :: Priority

-- | Information
INFO :: Priority

-- | Normal runtime conditions
NOTICE :: Priority

-- | General Warnings
WARNING :: Priority

-- | General Errors
ERROR :: Priority

-- | Severe situations
CRITICAL :: Priority

-- | Take immediate action
ALERT :: Priority

-- | System is unusable
EMERGENCY :: Priority

-- | Internal type of log records
type LogRecord = (Priority, String)
instance GHC.Internal.Enum.Bounded System.Log.Priority
instance GHC.Internal.Data.Data.Data System.Log.Priority
instance GHC.Internal.Enum.Enum System.Log.Priority
instance GHC.Classes.Eq System.Log.Priority
instance GHC.Internal.Generics.Generic System.Log.Priority
instance Control.DeepSeq.NFData System.Log.Priority
instance GHC.Classes.Ord System.Log.Priority
instance GHC.Internal.Read.Read System.Log.Priority
instance GHC.Internal.Show.Show System.Log.Priority

-- | Definition of log formatter support
--   
--   A few basic, and extendable formatters are defined.
--   
--   Please see System.Log.Logger for extensive documentation on the
--   logging system.
module System.Log.Formatter

-- | A LogFormatter is used to format log messages. Note that it is
--   paramterized on the Handler to allow the formatter to use
--   information specific to the handler (an example of can be seen in the
--   formatter used in Syslog)
type LogFormatter a = a -> LogRecord -> String -> IO String

-- | Returns the passed message as is, ie. no formatting is done.
nullFormatter :: LogFormatter a

-- | Takes a format string, and returns a formatter that may be used to
--   format log messages. The format string may contain variables prefixed
--   with a $-sign which will be replaced at runtime with corresponding
--   values. The currently supported variables are:
--   
--   
--   
- $msg - The actual log message
--   
- $loggername - The name of the logger
--   
- $prio - The priority level of the message
--   
- $tid - The thread ID
--   
- $pid - Process ID (Not available on windows)
--   
- $time - The current time
--   
- $utcTime - The current time in UTC Time
--   
simpleLogFormatter :: String -> LogFormatter a

-- | Like simpleLogFormatter but allow the time format to be
--   specified in the first parameter (this is passed to formatTime)
tfLogFormatter :: String -> String -> LogFormatter a

-- | An extensible formatter that allows new substition variables to
--   be defined. Each variable has an associated IO action that is used to
--   produce the string to substitute for the variable name. The predefined
--   variables are the same as for simpleLogFormatter
--   excluding $time and $utcTime.
varFormatter :: [(String, IO String)] -> String -> LogFormatter a

-- | Definition of log handler support
--   
--   For some handlers, check out System.Log.Handler.Simple and
--   System.Log.Handler.Syslog.
--   
--   Please see System.Log.Logger for extensive documentation on the
--   logging system.
--   
--   Written by John Goerzen, jgoerzen@complete.org
module System.Log.Handler

-- | All log handlers should adhere to this.
--   
--   This is the base class for the various log handlers. They should all
--   adhere to this class.
class LogHandler a

-- | Sets the log level. handle will drop items beneath this level.
setLevel :: LogHandler a => a -> Priority -> a

-- | Gets the current level.
getLevel :: LogHandler a => a -> Priority

-- | Set a log formatter to customize the log format for this Handler
setFormatter :: LogHandler a => a -> LogFormatter a -> a
getFormatter :: LogHandler a => a -> LogFormatter a

-- | Logs an event if it meets the requirements given by the most recent
--   call to setLevel.
handle :: LogHandler a => a -> LogRecord -> String -> IO ()

-- | Forces an event to be logged regardless of the configured level.
emit :: LogHandler a => a -> LogRecord -> String -> IO ()

-- | Closes the logging system, causing it to close any open files, etc.
close :: LogHandler a => a -> IO ()

-- | Simple log handlers
--   
--   Written by John Goerzen, jgoerzen@complete.org
module System.Log.Handler.Simple

-- | Create a stream log handler. Log messages sent to this handler will be
--   sent to the stream used initially. Note that the close method
--   will have no effect on stream handlers; it does not actually close the
--   underlying stream.
streamHandler :: Handle -> Priority -> IO (GenericHandler Handle)

-- | Create a file log handler. Log messages sent to this handler will be
--   sent to the filename specified, which will be opened in Append mode.
--   Calling close on the handler will close the file.
fileHandler :: FilePath -> Priority -> IO (GenericHandler Handle)

-- | A helper data type.
data GenericHandler a
GenericHandler :: Priority -> LogFormatter (GenericHandler a) -> a -> (a -> String -> IO ()) -> (a -> IO ()) -> GenericHandler a
[priority] :: GenericHandler a -> Priority
[formatter] :: GenericHandler a -> LogFormatter (GenericHandler a)
[privData] :: GenericHandler a -> a
[writeFunc] :: GenericHandler a -> a -> String -> IO ()
[closeFunc] :: GenericHandler a -> a -> IO ()

-- | Like streamHandler, but note the priority and logger name along
--   with each message.
verboseStreamHandler :: Handle -> Priority -> IO (GenericHandler Handle)
instance System.Log.Handler.LogHandler (System.Log.Handler.Simple.GenericHandler a)

-- | log4j[1] XMLLayout log handlers.
--   
--   Written by Bjorn Buckwalter, bjorn.buckwalter@gmail.com
module System.Log.Handler.Log4jXML

-- | Create a stream log handler that uses hslogger priorities.
log4jStreamHandler :: Handle -> Priority -> IO (GenericHandler Handle)

-- | Create a file log handler that uses hslogger priorities.
log4jFileHandler :: FilePath -> Priority -> IO (GenericHandler Handle)

-- | Create a stream log handler that uses log4j levels (priorities). The
--   priorities of messages are shoehorned into log4j levels as follows:
--   
--   
--   DEBUG                  -> DEBUG
--   INFO, NOTICE           -> INFO
--   WARNING                -> WARN
--   ERROR, CRITICAL, ALERT -> ERROR
--   EMERGENCY              -> FATAL
--   
--   
--   This is useful when the log will only be consumed by log4j tools and
--   you don't want to go out of your way transforming the log or
--   configuring the tools.
log4jStreamHandler' :: Handle -> Priority -> IO (GenericHandler Handle)

-- | Create a file log handler that uses log4j levels (see
--   log4jStreamHandler' for mappings).
log4jFileHandler' :: FilePath -> Priority -> IO (GenericHandler Handle)
instance GHC.Internal.Show.Show System.Log.Handler.Log4jXML.XML

-- | Haskell Logging Framework, Primary Interface
--   
--   Written by John Goerzen, jgoerzen@complete.org
--   
--   Welcome to the error and information logging system for Haskell.
--   
--   This system is patterned after Python's logging module,
--   http://www.python.org/doc/current/lib/module-logging.html and
--   some of the documentation here was based on documentation there.
--   
--   To log a message, you perform operations on Loggers. Each
--   Logger has a name, and they are arranged hierarchically.
--   Periods serve as separators. Therefore, a Logger named "foo" is
--   the parent of loggers "foo.printing", "foo.html", and "foo.io". These
--   names can be anything you want. They're used to indicate the area of
--   an application or library in which a logged message originates. Later
--   you will see how you can use this concept to fine-tune logging
--   behaviors based on specific application areas.
--   
--   You can also tune logging behaviors based upon how important a message
--   is. Each message you log will have an importance associated with it.
--   The different importance levels are given by the Priority type.
--   I've also provided some convenient functions that correspond to these
--   importance levels: debugM through emergencyM log
--   messages with the specified importance.
--   
--   Now, an importance level (or Priority) is associated not just
--   with a particular message but also with a Logger. If the
--   Priority of a given log message is lower than the
--   Priority configured in the Logger, that message is
--   ignored. This way, you can globally control how verbose your logging
--   output is.
--   
--   Now, let's follow what happens under the hood when you log a message.
--   We'll assume for the moment that you are logging something with a high
--   enough Priority that it passes the test in your Logger.
--   In your code, you'll call logM or something like debugM
--   to log the message. Your Logger decides to accept the message.
--   What next?
--   
--   Well, we also have a notion of handlers (LogHandlers, to
--   be precise). A LogHandler is a thing that takes a message and
--   sends it somewhere. That "somewhere" may be your screen (via standard
--   error), your system's logging infrastructure (via syslog), a file, or
--   other things. Each Logger can have zero or more
--   LogHandlers associated with it. When your Logger has a
--   message to log, it passes it to every LogHandler it knows of to
--   process. What's more, it is also passed to /all handlers of all
--   ancestors of the Logger/, regardless of whether those Loggers
--   would normally have passed on the message.
--   
--   Each Logger can optionally store a Priority. If a
--   given Logger does not have a Priority, and you log a message to that
--   logger, the system will use the priority of the parent of the
--   destination logger to find out whether to log the message. If the
--   parent has no priority associated with it, the system continues
--   walking up the tree to figure out a priority until it hits the root
--   logger. In this way, you can easily adjust the priority of an entire
--   subtree of loggers. When a new logger is created, it has no priority
--   by default. The exception is the root logger, which has a WARNING
--   priority by default.
--   
--   To give you one extra little knob to turn, LogHandlers can also
--   have importance levels (Priority) associated with them in the
--   same way that Loggers do. They act just like the
--   Priority value in the Loggers -- as a filter. It's
--   useful, for instance, to make sure that under no circumstances will a
--   mere DEBUG message show up in your syslog.
--   
--   There are three built-in handlers given in two built-in modules:
--   System.Log.Handler.Simple and System.Log.Handler.Syslog.
--   
--   There is a special logger known as the root logger that sits at
--   the top of the logger hierarchy. It is always present, and handlers
--   attached there will be called for every message. You can use
--   getRootLogger to get it or rootLoggerName to work with
--   it by name.
--   
--   The formatting of log messages may be customized by setting a
--   LogFormatter on the desired LogHandler. There are a
--   number of simple formatters defined in System.Log.Formatter,
--   which may be used directly, or extend to create your own formatter.
--   
--   Here's an example to illustrate some of these concepts:
--   
--   
--   import System.Log.Logger
--   import System.Log.Handler.Syslog
--   import System.Log.Handler.Simple
--   import System.Log.Handler (setFormatter)
--   import System.Log.Formatter
--   
--   -- By default, all messages of level WARNING and above are sent to stderr.
--   -- Everything else is ignored.
--   
--   -- "MyApp.Component" is an arbitrary string; you can tune
--   -- logging behavior based on it later.
--   main = do
--          logger1 <- getLogger "MyApp.Component"
--          logger2 <- getLogger "MyApp.Component2"
--          loggerB <- getLogger "MyApp.BuggyComponent"
--          loggerW <- getLogger "MyApp.WorkingComponent"
--   
--          logL logger1 DEBUG "This is a debug message -- never to be seen"
--          logL logger2 WARNING "Something Bad is about to happen."
--   
--          -- Copy everything to syslog from here on out.
--          s <- openlog "SyslogStuff" [PID] USER DEBUG
--          saveGlobalLogger =<< addHandler s <$> getRootLogger
--   
--          logL logger1 ERROR "This is going to stderr and syslog."
--   
--          -- Now we'd like to see everything from BuggyComponent
--          -- at DEBUG or higher go to syslog and stderr.
--          -- Also, we'd like to still ignore things less than
--          -- WARNING in other areas.
--          --
--          -- So, we adjust the Logger for MyApp.BuggyComponent.
--   
--          let loggerB' = setLevel DEBUG loggerB
--          saveGlobalLogger loggerB'
--   
--          -- This message will go to syslog and stderr
--          logL loggerB' DEBUG "This buggy component is buggy"
--   
--          -- This message will go to syslog and stderr too.
--          logL loggerB' WARNING "Still Buggy"
--   
--          -- This message goes nowhere.
--          logL loggerW DEBUG "Hello"
--   
--          -- Now we decide we'd also like to log everything from BuggyComponent at DEBUG
--          -- or higher to a file for later diagnostics.  We'd also like to customize the
--          -- format of the log message, so we use a 'simpleLogFormatter'
--   
--          h <- fileHandler "debug.log" DEBUG >>= \lh -> return $
--                   setFormatter lh (simpleLogFormatter "[$time : $loggername : $prio] $msg")
--          let loggerB'' = addHandler h loggerB'
--          saveGlobalLogger loggerB''
--   
--          -- This message will go to syslog and stderr,
--          -- and to the file "debug.log" with a format like :
--          -- [2010-05-23 16:47:28 : MyApp.BuggyComponent : DEBUG] Some useful diagnostics...
--          logL loggerB'' DEBUG "Some useful diagnostics..."
--   
module System.Log.Logger
data Logger

-- | Priorities are used to define how important a log message is. Users
--   can filter log messages based on priorities.
--   
--   These have their roots on the traditional syslog system. The standard
--   definitions are given below, but you are free to interpret them
--   however you like. They are listed here in ascending importance order.
data Priority

-- | Debug messages
DEBUG :: Priority

-- | Information
INFO :: Priority

-- | Normal runtime conditions
NOTICE :: Priority

-- | General Warnings
WARNING :: Priority

-- | General Errors
ERROR :: Priority

-- | Severe situations
CRITICAL :: Priority

-- | Take immediate action
ALERT :: Priority

-- | System is unusable
EMERGENCY :: Priority

-- | Log a message using the given logger at a given priority.
logM :: String -> Priority -> String -> IO ()

-- | Log a message at DEBUG priority
debugM :: String -> String -> IO ()

-- | Log a message at INFO priority
infoM :: String -> String -> IO ()

-- | Log a message at NOTICE priority
noticeM :: String -> String -> IO ()

-- | Log a message at WARNING priority
warningM :: String -> String -> IO ()

-- | Log a message at ERROR priority
errorM :: String -> String -> IO ()

-- | Log a message at CRITICAL priority
criticalM :: String -> String -> IO ()

-- | Log a message at ALERT priority
alertM :: String -> String -> IO ()

-- | Log a message at EMERGENCY priority
emergencyM :: String -> String -> IO ()

-- | Allow graceful shutdown. Release all opened files, handlers, etc.
removeAllHandlers :: IO ()

-- | Traps exceptions that may occur, logging them, then passing them on.
--   
--   Takes a logger name, priority, leading description text (you can set
--   it to "" if you don't want any), and action to run.
traplogging :: String -> Priority -> String -> IO a -> IO a

-- | Log a message, assuming the current logger's level permits it.
logL :: Logger -> Priority -> String -> IO ()

-- | Returns the logger for the given name. If no logger with that name
--   exists, creates new loggers and any necessary parent loggers, with no
--   connected handlers.
getLogger :: String -> IO Logger

-- | Returns the root logger.
getRootLogger :: IO Logger

-- | This is the base class for the various log handlers. They should all
--   adhere to this class.
--   
--   The name of the root logger, which is always defined and present on
--   the system.
rootLoggerName :: String

-- | Add handler to Logger. Returns a new Logger.
addHandler :: LogHandler a => a -> Logger -> Logger

-- | Remove a handler from the Logger. Handlers are removed in the
--   reverse order they were added, so the following property holds for any
--   LogHandler h:
--   
--   
--   removeHandler . addHandler h = id
--   
--   
--   If no handlers are associated with the Logger, it is returned
--   unchanged.
--   
--   The root logger's default handler that writes every message to stderr
--   can be removed by using this function before any handlers have been
--   added to the root logger:
--   
--   
--   updateGlobalLogger rootLoggerName removeHandler
--   
removeHandler :: Logger -> Logger

-- | Set the Logger's list of handlers to the list supplied. All
--   existing handlers are removed first.
setHandlers :: LogHandler a => [a] -> Logger -> Logger

-- | Returns the "level" of the logger. Items beneath this level will be
--   ignored.
getLevel :: Logger -> Maybe Priority

-- | Sets the "level" of the Logger. Returns a new Logger
--   object with the new level.
setLevel :: Priority -> Logger -> Logger

-- | Clears the "level" of the Logger. It will now inherit the level
--   of | its parent.
clearLevel :: Logger -> Logger

-- | Updates the global record for the given logger to take into account
--   any changes you may have made.
saveGlobalLogger :: Logger -> IO ()

-- | Helps you make changes on the given logger. Takes a function that
--   makes changes and writes those changes back to the global database.
--   Here's an example from above ("s" is a LogHandler):
--   
--   
--   updateGlobalLogger "MyApp.BuggyComponent"
--                      (setLevel DEBUG . setHandlers [s])
--   
updateGlobalLogger :: String -> (Logger -> Logger) -> IO ()

-- | Syslog handler for the Haskell Logging Framework
--   
--   Written by John Goerzen, jgoerzen@complete.org
--   
--   This module implements an interface to the Syslog service commonly
--   found in Unix/Linux systems. This interface is primarily of interest
--   to developers of servers, as Syslog does not typically display
--   messages in an interactive fashion.
--   
--   This module is written in pure Haskell and is capable of logging to a
--   local or remote machine using the Syslog protocol.
--   
--   You can create a new Syslog LogHandler by calling
--   openlog.
--   
--   More information on the Haskell Logging Framework can be found at
--   System.Log.Logger. This module can also be used outside of the
--   rest of that framework for those interested in that.
module System.Log.Handler.Syslog
data SyslogHandler

-- | Initialize the Syslog system using the local system's default
--   interface, /dev/log. Will return a new LogHandler.
--   
--   On Windows, instead of using /dev/log, this will attempt to send UDP
--   messages to something listening on the syslog port (514) on localhost.
--   
--   Use openlog_remote if you need more control.
openlog :: String -> [Option] -> Facility -> Priority -> IO SyslogHandler

-- | Initialize the Syslog system using an arbitrary Unix socket (FIFO).
--   
--   Not supported under Windows.
openlog_local :: String -> String -> [Option] -> Facility -> Priority -> IO SyslogHandler

-- | Log to a remote server via UDP.
openlog_remote :: Family -> HostName -> PortNumber -> String -> [Option] -> Facility -> Priority -> IO SyslogHandler

-- | The most powerful initialization mechanism. Takes an open datagram
--   socket.
openlog_generic :: Socket -> SockAddr -> SocketType -> String -> [Option] -> Facility -> Priority -> IO SyslogHandler

-- | Facilities are used by the system to determine where messages are
--   sent.
data Facility

-- | Kernel messages; you should likely never use this in your programs
KERN :: Facility

-- | General userland messages. Use this if nothing else is appropriate
USER :: Facility

-- | E-Mail system
MAIL :: Facility

-- | Daemon (server process) messages
DAEMON :: Facility

-- | Authentication or security messages
AUTH :: Facility

-- | Internal syslog messages; you should likely never use this in your
--   programs
SYSLOG :: Facility

-- | Printer messages
LPR :: Facility

-- | Usenet news
NEWS :: Facility

-- | UUCP messages
UUCP :: Facility

-- | Cron messages
CRON :: Facility

-- | Private authentication messages
AUTHPRIV :: Facility

-- | FTP messages
FTP :: Facility

-- | LOCAL0 through LOCAL7 are reserved for you to customize as you wish
LOCAL0 :: Facility
LOCAL1 :: Facility
LOCAL2 :: Facility
LOCAL3 :: Facility
LOCAL4 :: Facility
LOCAL5 :: Facility
LOCAL6 :: Facility
LOCAL7 :: Facility

-- | Options for openlog.
data Option

-- | Automatically log process ID (PID) with each message
PID :: Option

-- | Send a copy of each message to stderr
PERROR :: Option
instance GHC.Classes.Eq System.Log.Handler.Syslog.Facility
instance GHC.Classes.Eq System.Log.Handler.Syslog.Option
instance System.Log.Handler.LogHandler System.Log.Handler.Syslog.SyslogHandler
instance GHC.Internal.Read.Read System.Log.Handler.Syslog.Facility
instance GHC.Internal.Read.Read System.Log.Handler.Syslog.Option
instance GHC.Internal.Show.Show System.Log.Handler.Syslog.Facility
instance GHC.Internal.Show.Show System.Log.Handler.Syslog.Option

-- | Simple log handlers
--   
--   Written by Richard M. Neswold, Jr. rich.neswold@gmail.com
module System.Log.Handler.Growl

-- | Adds a remote machine's address to the list of targets that will
--   receive log messages. Calling this function sends a registration
--   packet to the machine. This function will throw an exception if the
--   host name cannot be found.
addTarget :: HostName -> GrowlHandler -> IO GrowlHandler

-- | Creates a Growl handler. Once a Growl handler has been created,
--   machines that are to receive the message have to be specified.
growlHandler :: String -> Priority -> IO GrowlHandler
instance System.Log.Handler.LogHandler System.Log.Handler.Growl.GrowlHandler
