root/trunk/tango/scrapple/io/Logout.d

/*******************************************************************************

        Copyright:      Copyright (c) 2007 Tim Burrell. All rights reserved.

        License:        BSD style: $(LICENSE)

        Version:        Aug 29 2007: Initial release

        Author:         Tim Burrell [tim <dot> burrell <at> gmail <dot> com]
        
        Logging module for quick and easy logging to console and log files

*******************************************************************************/

module  tango.scrapple.io.Logout;

import  tango.io.FilePath;
import  tango.io.Stdout;
import  tango.util.log.ConsoleAppender;
import  tango.util.log.RollingFileAppender;
import  tango.util.log.DateLayout;
import  tango.util.log.EventLayout;
import  tango.util.log.Log;
import  tango.util.log.Logger;
import  tango.util.log.Event;
import  tango.util.log.EventLayout;

////////////////////////////////////////////////////////////////////////////
// Typedef's / Enums
///////////////////////////////////////

/*******************************************************************************
 
  LoggingLevel states that define how much output gets printed / logged
 
  Valid Levels are as follows:
  ---
  TraceTrivial
  TraceDebug
  Trace
  Info
  Warn
  Error
  Fatal
  Quiet
  ---
 
*******************************************************************************/

enum LoggingLevel {
        TraceTrivial,
        TraceDebug,
        Trace,
        Info,
        Warn,
        Error,
        Fatal,
        Quiet,
}

////////////////////////////////////////////////////////////////////////////
// Logging Definition
///////////////////////////////////////

/*******************************************************************************

  The Logging class wraps the tango logging API into a package that provides
  some useful default behavior that may be suitable for easy inclusion into
  projects that want quick and easy access to file / console logging, with 
  a minimum amount of hassle.
 
  The default behavior is to log data to both the console and a file if a
  custom log name is set with Logging.logger.  If no logger is set then
  (by default) data will only be output to the console.
 
  The Logging class also provides some additional output levels beyond
  the ones provided by Tango's logging API, for additional control.
 
  The output routines are lazily evaulated so if the current output 
  verbosity is higher than the data being outputted there is a relatively
  low amount of overhead.
 
  Examples:
 
  In order to use the Logging class you can use the globally instantiated
  Logout object.  All you need to do is (optionally) first set the log name:
  ---
  Logout.logger = "LogName"
  ---
  This will create "LogNameX.log" where X is a number.  The default file log
  format is to use RollingFileAppender so that the log files do not get too
  large on disk.  There will only ever be a maximum of two 1 MB log files
  created by default.
 
  In order to set the current logging level use the following methods:
  ---
  Logout.level = LoggingLevel.TraceDebug;
  ---
  This will set the logging level to TraceDebug.  Note that the default level 
  is LoggingLevel.info.
 
  In order to actually produce some log output the following can be done:
  ---
  Logout("test");                      // Log text using the default output level (Info)
  Logout.trivial("test");              // Log text using the TraceTrivial output level
  Logout.dbg("test");                  // Log text using the TraceDebug output level
  Logout.trace("test");                // Log text using the Trace output level
  Logout.info("test");                 // Log text using the Info output level
  Logout.warn("test");                 // Log text using the Warn output level
  Logout.error("test");                // Log text using the Error output level
  Logout.fatal("test");                // Log text using the Fatal output level
  ---
  Text can also be formatted using the Logging class:
  ---
  Logout.format("test {0}", var);      // Log text using the default output level (Info)
  Logout.dbg.format("test {0}", var);  // Log text using the TraceTrivial output level
  ---
  
*******************************************************************************/

class Logging 
{
        ////////////////////////////////////////////////////////////////////
        // Constants
        ///////////////////////////////
        
        const ubyte             DEFAULT_NUM_FILE_LOGS = 2;              /// Default number of logs to rotate between
        const ulong             DEFAULT_LOG_SIZE = 1024;                /// Default size of each log
        const char []           DEFAULT_LOGGER_NAME = "DefaultLogger";  /// Default logger name
        
        ////////////////////////////////////////////////////////////////////
        // Public members
        ///////////////////////////////
        
        public alias  log        opCall;                                /// Alias opCall
        
        ////////////////////////////////////////////////////////////////////
        // Construction
        ///////////////////////////////
        
        /**
         * Default Constructor
        **/
        this () {
                mNumFileLogs = DEFAULT_NUM_FILE_LOGS;
                mLastLevel = LoggingLevel.Info;
                mLogPath = null;
                mLogSize = DEFAULT_LOG_SIZE * 1024;
                layoutConsole = new LoggingConsoleLayout();
                layoutFile = new LoggingFileLayout();
                logger(DEFAULT_LOGGER_NAME, true, false);
                level(LoggingLevel.Info);
        }
        
        /**
         * Destructor
        **/
        ~this () {
        }
        
        ////////////////////////////////////////////////////////////////////
        // Public Functions
        ///////////////////////////////
        
        /**
         * Format a string and output via the logger
         *
         * Params:         Fmt =           Formatting string
         *                 ... =           Parameters
         * Returns:                        Self
        **/
        final Logging format(lazy char [] Fmt, ...) {
                return log(Stdout.layout().convert(_arguments, _argptr, Fmt));
        }
        
        /**
         * Set the console output layout
         *
         * Params:        ConsoleLayout =  Set the layout of the console output
        **/
        void layoutConsole(LoggingConsoleLayout LayoutConsole) {
                mLayoutConsole = LayoutConsole;
        }
        
        /**
         * Set the file output layout
         *
         * Params:        FileLayout =     Set the layout of the file output
        **/
        void layoutFile(LoggingFileLayout LayoutFile) {
                mLayoutFile = LayoutFile;
        }
        
        /**
         * Set the logger name
         *
         * Params:        LogLevel =       Set the level of the logger
         * Returns:                        Current level of the logging class
        **/
        LoggingLevel level(LoggingLevel LogLevel) {
                mLevel = LogLevel;
                mLogger.setLevel(convertLevel(LogLevel));
                return level();
        }
        
        /**
         * Get the logger name
         *
         * Returns:                        Current level of the logging class
        **/
        LoggingLevel level() {
                return mLevel;
        }
        
        /**
         * Log some text
         *
         * Params:        Output =         Text to log
        **/
        final Logging log(lazy char [] Output) {
                return log(Output, mLastLevel);
        }
        
        /**
         * Log some text
         *
         * Params:        LogLevel =       Level of output
         *                Output =         Text to log
         * Returns:                        Self
        **/
        final Logging log(lazy char [] Output, LoggingLevel LogLevel) {
                mLastLevel = LogLevel;
                // evaluate Output last so lazy can avoid processing it if there's
                // no need!
                if ((LogLevel >= mLevel) && Output)
                        mLogger.append(convertLevel(LogLevel), Output);
                return this;
        }
        
        /**
         * Set the logger name
         *
         * Params:        LoggerName =     Name of the logger
         *                ConsoleOutput =  Should output go to the console?
         *                FileOutput =     Should output go to the log files?
         *                LogPath =        Path to log file
         * Returns:                        Logger name
        **/
        char [] logger(char [] LoggerName, bool ConsoleOutput = true, bool FileOutput = true, char [] LogPath = null) {
                mConsoleOutput = ConsoleOutput;
                mFileOutput = FileOutput;
                mLogger = Log.getLogger(LoggerName);
                mLogger.clearAppenders();
                mLogPath = LogPath;
                if (ConsoleOutput)
                        mLogger.addAppender(new ConsoleAppender(mLayoutConsole));
                if (FileOutput)
                        if (mLogPath is null)
                                mLogger.addAppender(new RollingFileAppender(LoggerName ~ ".log", mNumFileLogs, mLogSize, mLayoutFile));
                        else {
                                FilePath dir = new FilePath(mLogPath);
                                try {
                                        dir.create();
                                        mLogger.addAppender(new RollingFileAppender(mLogPath ~ "/" ~ LoggerName ~ ".log", mNumFileLogs, mLogSize, mLayoutFile));
                                } catch (Exception e) {
                                        warn.format("Unable to create logfile [{0}/{1}.log]", mLogPath, LoggerName);
                                }
                        }
                return logger();
        }
        
        /**
         * Get the logger name
         *
         * Returns:                        Name of the logger
        **/
        char [] logger() {
                return mLogger.name;
        }
        
        /**
         * Set the logfile path
         *
         * Send null (or no parameter) to remove the log path
         *
         * Params:        Path =           Directory that will contain the log file
        **/
        void logPath(char [] Path = null) {
                mLogPath = Path;
                logger(mLogger.name, mConsoleOutput, mFileOutput);
        }
        
        /**
         * Output a newline
         *
         * Params:        Output =         Text to output
         * Returns:                        Self
        **/
        final Logging newline() {
                mLayoutFile.SkipNextHeader = true;
                       return log("", mLastLevel);
        }
        
        /**
         * Output data using the Debug.Trivial setting
         *
         * Params:        Output =         Text to output
         * Returns:                        Self
        **/
        final Logging trivial(lazy char [] Output = null) {
                return log(Output, LoggingLevel.TraceTrivial);
        }
                
        /**
         * Output data using the Debug.Trace setting
         *
         * Params:        Output =         Text to output
         * Returns:                        Self
        **/
        final Logging dbg(lazy char [] Output = null) {
                return log(Output, LoggingLevel.TraceDebug);
        }
        
        /**
         * Output data using the Debug setting
         *
         * Params:        Output =         Text to output
         * Returns:                        Self
        **/
        final Logging trace(lazy char [] Output = null) {
                return log(Output, LoggingLevel.Trace);
        }
        
        /**
         * Output data using the Info setting
         *
         * Params:        Output =         Text to output
         * Returns:                        Self
        **/
        final Logging info(lazy char [] Output = null) {
                return log(Output, LoggingLevel.Info);
        }
        
        /**
         * Output data using the Warn setting
         *
         * Params:        Output =         Text to output
         * Returns:                        Self
        **/
        final Logging warn(lazy char [] Output = null) {
                return log(Output, LoggingLevel.Warn);
        }
        
        /**
         * Output data using the Error setting
         *
         * Params:        Output =         Text to output
         * Returns:                        Self
        **/
        final Logging error(lazy char [] Output = null) {
                return log(Output, LoggingLevel.Error);
        }
        
        /**
         * Output data using the Fatal setting
         *
         * Params:        Output =         Text to output
         * Returns:                        Self
        **/
        final Logging fatal(lazy char [] Output = null) {
                return log(Output, LoggingLevel.Fatal);
        }
        
        ////////////////////////////////////////////////////////////////////
        
private:
        
        ////////////////////////////////////////////////////////////////////
        // Private Functions
        ///////////////////////////////        
        
        /**
         * Convert LoggingLevel to Logger.Level
         *
         *
         * Params:        Level =          Logging.Level
         * Returns:                        Logger.Level
        **/
        Logger.Level convertLevel(LoggingLevel Level) {
                switch (Level) {
                case LoggingLevel.TraceTrivial:
                case LoggingLevel.TraceDebug:
                case LoggingLevel.Trace:
                        return Logger.Level.Trace;
                default:
                case LoggingLevel.Info:
                        return Logger.Level.Info;
                case LoggingLevel.Warn:
                        return Logger.Level.Warn;
                case LoggingLevel.Error:
                        return Logger.Level.Error;
                case LoggingLevel.Fatal:
                        return Logger.Level.Fatal;
                case LoggingLevel.Quiet:
                        return Logger.Level.None;
                }
                return Logger.Level.Info;
        }
        
        ////////////////////////////////////////////////////////////////////
        // Private Members
        ///////////////////////////////        
        
        bool                    mConsoleOutput;                         /// Write to the console?
        bool                    mFileOutput;                            /// Write to logfile?
        LoggingLevel            mLastLevel;                             /// LoggingLevel of last output
        LoggingLevel            mLevel;                                 /// Debugging level
        Logger                  mLogger;                                /// Is the thing constructed?
        char []                 mLogPath;                               /// Path of the log file
        LoggingConsoleLayout    mLayoutConsole;                         /// The log output console format 
        LoggingFileLayout       mLayoutFile;                            /// The log output file format
        ulong                   mLogSize;                               /// Size in KB of each log
        ubyte                   mNumFileLogs;                           /// Number of file logs to rotate between
}

////////////////////////////////////////////////////////////////////////////
// LoggingLayout
///////////////////////////////////////

/*******************************************************************************

  LoggingConsoleLayout Class
 
  This is the default layout for Console output.
 
  If you want to change this layout simply create a new class
  that inherits this one and pass it in using:
  ---
  Logout.layoutConsole = NewLayout;
  ---
  See the tango <a href="http://www.dsource.org/projects/tango/docs/current/tango.util.log.EventLayout.html">EventLayout docs</a> for more information on this
 
*******************************************************************************/

class LoggingConsoleLayout : EventLayout 
{
        ////////////////////////////////////////////////////////////////////
        // Public Functions
        ///////////////////////////////
        
        /**
         * Set the layout header
         *
         * Params:        Event =          The log event
         * Returns:                        The formatted header
        **/
        char[] header(Event Event) {
                switch (Event.getLevel()) {
                case Logger.Level.Trace:
                default:
                case Logger.Level.Info:
                break;
                case Logger.Level.Warn:
                case Logger.Level.Error:
                        Event.append(Event.getLevelName()).append(" - ");
                        break;
                case Logger.Level.Fatal:
                        Event.append("FATAL - ");
                        break;
                }
                
                return Event.getContent();
        }
}

/*******************************************************************************

  LoggingFileLayout Class
 
  This is the default layout for File output.
 
  If you want to change this layout simply create a new class
  that inherits this one and pass it in using:
  ---
  Logout.layoutFile = NewLayout;
  ---
  See the tango <a href="http://www.dsource.org/projects/tango/docs/current/tango.util.log.EventLayout.html">EventLayout docs</a> for more information on this
  
*******************************************************************************/

class LoggingFileLayout : DateLayout 
{
        ////////////////////////////////////////////////////////////////////
        // Public members
        ///////////////////////////////
        
        bool                    SkipNextHeader;                         /// Skip the next header output?
        
        ////////////////////////////////////////////////////////////////////
        // Construction 
        ///////////////////////////////
        
        /**
         * Default Constructor
        **/
        this() {
                SkipNextHeader = false;
        }
        
        ////////////////////////////////////////////////////////////////////
        // Public Functions
        ///////////////////////////////
        
        /**
         * Set the layout header
         *
         * Params:        Event =          The log event
         * Returns:                        The formatted header
        **/
        char[] header(Event Event) {
                if (SkipNextHeader) 
                        SkipNextHeader = false;
                else 
                        Event.append(super.header(Event));
                
                return Event.getContent();
        }
}

////////////////////////////////////////////////////////////////////////////
// Globals
///////////////////////////////////////

static this() {
        Logout = new Logging();
}

public static Logging Logout;                                           /// Global Logout object