-- 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.2.10


-- | Haskell Logging Framework
--   
--   Written by John Goerzen, jgoerzen@complete.org
--   
--   This module defines basic types used for logging.
--   
--   Extensive documentation is available in <a>System.Log.Logger</a>.
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.Read.Read System.Log.Priority
instance GHC.Show.Show System.Log.Priority
instance GHC.Enum.Bounded System.Log.Priority
instance GHC.Enum.Enum System.Log.Priority
instance GHC.Classes.Ord System.Log.Priority
instance GHC.Classes.Eq System.Log.Priority


-- | Definition of log formatter support
--   
--   A few basic, and extendable formatters are defined.
--   
--   Please see <a>System.Log.Logger</a> 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 <tt>Handler</tt> to allow the formatter to use
--   information specific to the handler (an example of can be seen in the
--   formatter used in <a>Syslog</a>)
type LogFormatter a = a  The LogHandler that the passed message came from  -> LogRecord  The log message and priority -> String  The logger name -> IO String  The formatted log message

-- | 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:
--   
--   <ul>
--   <li><tt>$msg</tt> - The actual log message</li>
--   <li><tt>$loggername</tt> - The name of the logger</li>
--   <li><tt>$prio</tt> - The priority level of the message</li>
--   <li><tt>$tid</tt> - The thread ID</li>
--   <li><tt>$pid</tt> - Process ID (Not available on windows)</li>
--   <li><tt>$time</tt> - The current time</li>
--   <li><tt>$utcTime</tt> - The current time in UTC Time</li>
--   </ul>
simpleLogFormatter :: String -> LogFormatter a

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

-- | An extensible formatter that allows new substition <i>variables</i> 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 <a>simpleLogFormatter</a>
--   <i>excluding</i> <tt>$time</tt> and <tt>$utcTime</tt>.
varFormatter :: [(String, IO String)] -> String -> LogFormatter a


-- | Definition of log handler support
--   
--   For some handlers, check out <a>System.Log.Handler.Simple</a> and
--   <a>System.Log.Handler.Syslog</a>.
--   
--   Please see <a>System.Log.Logger</a> 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 where getFormatter h = nullFormatter handle h (pri, msg) logname = if pri >= (getLevel h) then do { formattedMsg <- (getFormatter h) h (pri, msg) logname; emit h (pri, formattedMsg) logname } else return ()

-- | Sets the log level. <a>handle</a> 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 <a>setLevel</a>.
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 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


-- | 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 <a>close</a> 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 <a>close</a> 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 <a>streamHandler</a>, 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:
--   
--   <pre>
--   DEBUG                  -&gt; DEBUG
--   INFO, NOTICE           -&gt; INFO
--   WARNING                -&gt; WARN
--   ERROR, CRITICAL, ALERT -&gt; ERROR
--   EMERGENCY              -&gt; FATAL
--   </pre>
--   
--   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
--   <a>log4jStreamHandler'</a> for mappings).
log4jFileHandler' :: FilePath -> Priority -> IO (GenericHandler Handle)
instance GHC.Show.Show System.Log.Handler.Log4jXML.XML


-- | 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 <a>LogHandler</a> by calling
--   <a>openlog</a>.
--   
--   More information on the Haskell Logging Framework can be found at
--   <a>System.Log.Logger</a>. 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 <a>LogHandler</a>.
--   
--   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 <a>openlog_remote</a> 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 <a>openlog</a>.
data Option

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

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


-- | 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 <tt>logging</tt> module,
--   <a>http://www.python.org/doc/current/lib/module-logging.html</a> and
--   some of the documentation here was based on documentation there.
--   
--   To log a message, you perform operations on <a>Logger</a>s. Each
--   <a>Logger</a> has a name, and they are arranged hierarchically.
--   Periods serve as separators. Therefore, a <a>Logger</a> 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 <a>Priority</a> type.
--   I've also provided some convenient functions that correspond to these
--   importance levels: <a>debugM</a> through <a>emergencyM</a> log
--   messages with the specified importance.
--   
--   Now, an importance level (or <a>Priority</a>) is associated not just
--   with a particular message but also with a <a>Logger</a>. If the
--   <a>Priority</a> of a given log message is lower than the
--   <a>Priority</a> configured in the <a>Logger</a>, 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 <a>Priority</a> that it passes the test in your <a>Logger</a>.
--   In your code, you'll call <a>logM</a> or something like <a>debugM</a>
--   to log the message. Your <a>Logger</a> decides to accept the message.
--   What next?
--   
--   Well, we also have a notion of <i>handlers</i> (<a>LogHandler</a>s, to
--   be precise). A <a>LogHandler</a> 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 <a>Logger</a> can have zero or more
--   <a>LogHandler</a>s associated with it. When your <a>Logger</a> has a
--   message to log, it passes it to every <a>LogHandler</a> 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 <a>Logger</a>s
--   would normally have passed on the message.
--   
--   Each <a>Logger</a> can <i>optionally</i> store a <a>Priority</a>. 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, <a>LogHandler</a>s can also
--   have importance levels (<a>Priority</a>) associated with them in the
--   same way that <a>Logger</a>s do. They act just like the
--   <a>Priority</a> value in the <a>Logger</a>s -- as a filter. It's
--   useful, for instance, to make sure that under no circumstances will a
--   mere <a>DEBUG</a> message show up in your syslog.
--   
--   There are three built-in handlers given in two built-in modules:
--   <a>System.Log.Handler.Simple</a> and <a>System.Log.Handler.Syslog</a>.
--   
--   There is a special logger known as the <i>root logger</i> 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
--   <a>getRootLogger</a> to get it or <a>rootLoggerName</a> to work with
--   it by name.
--   
--   The formatting of log messages may be customized by setting a
--   <a>LogFormatter</a> on the desired <a>LogHandler</a>. There are a
--   number of simple formatters defined in <a>System.Log.Formatter</a>,
--   which may be used directly, or extend to create your own formatter.
--   
--   Here's an example to illustrate some of these concepts:
--   
--   <pre>
--   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
--          debugM "MyApp.Component"  "This is a debug message -- never to be seen"
--          warningM "MyApp.Component2" "Something Bad is about to happen."
--   
--          -- Copy everything to syslog from here on out.
--          s &lt;- openlog "SyslogStuff" [PID] USER DEBUG
--          updateGlobalLogger rootLoggerName (addHandler s)
--         
--          errorM "MyApp.Component" "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.
--   
--          updateGlobalLogger "MyApp.BuggyComponent"
--                             (setLevel DEBUG)
--   
--          -- This message will go to syslog and stderr
--          debugM "MyApp.BuggyComponent" "This buggy component is buggy"
--   
--          -- This message will go to syslog and stderr too.
--          warningM "MyApp.BuggyComponent" "Still Buggy"
--   
--          -- This message goes nowhere.
--          debugM "MyApp.WorkingComponent" "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 &lt;- fileHandler "debug.log" DEBUG &gt;&gt;= \lh -&gt; return $
--                   setFormatter lh (simpleLogFormatter "[$time : $loggername : $prio] $msg")
--          updateGlobalLogger "MyApp.BuggyComponent" (addHandler h)
--         
--          -- 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...
--          debugM "MyApp.BuggyComponent" "Some useful diagnostics..."
--   </pre>
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 <a>DEBUG</a> priority
debugM :: String -> String -> IO ()

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

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

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

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

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

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

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

-- | Allow gracefull shutdown. Release all opened files<i>handlers</i>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 <tt>""</tt> 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 <a>Logger</a>. Returns a new <a>Logger</a>.
addHandler :: LogHandler a => a -> Logger -> Logger

-- | Remove a handler from the <a>Logger</a>. Handlers are removed in the
--   reverse order they were added, so the following property holds for any
--   <a>LogHandler</a> <tt>h</tt>:
--   
--   <pre>
--   removeHandler . addHandler h = id
--   </pre>
--   
--   If no handlers are associated with the <a>Logger</a>, 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:
--   
--   <pre>
--   updateGlobalLogger rootLoggerName removeHandler
--   </pre>
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 <a>Logger</a>. Returns a new <a>Logger</a>
--   object with the new level.
setLevel :: Priority -> Logger -> Logger

-- | Clears the "level" of the <a>Logger</a>. 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 <a>LogHandler</a>):
--   
--   <pre>
--   updateGlobalLogger "MyApp.BuggyComponent"
--                      (setLevel DEBUG . setHandlers [s])
--   </pre>
updateGlobalLogger :: String -> (Logger -> Logger) -> IO ()
