logeasy 0.0.4

data/lib/example/example.rb

@@ -0,0 +1,52 @@
+#
+# Suraj Vijayakumar
+# 19-02-2011
+#
+
+require "logeasy"
+
+# Configuring the self logger. The self logger will log internal logger messages.
+
+file_appender_1 = LogEasy::FileAppender.new("easylog_self.log") # Simple file logger.
+self_logger = LogEasy::Logger.self_logger # Get the handle to the self logger.
+self_logger.change_min_level(LogEasy::Level::ALL) # Change the minimum level, since the default level for the self logger is OFF.
+self_logger.add_appender(file_appender_1) # Add the appenders to the self logger. New appenders are assigned the logger's level.
+
+
+# Using a custom formatter. Takes a log item (instance of EasyLog::Log) as an argument. Return the formatted message.
+timestamp_format = "%d-%m-%Y %H:%M:%S.%L"
+custom_formatter = proc do |log_item|
+  logger_name = log_item.logger.name # By default the to_s method returns the logger's full name.
+  level = log_item.level # By default the to_s method returns the level's name.
+  message = log_item.message
+  timestamp = log_item.timestamp.strftime(timestamp_format)
+
+  "%-5s [#{timestamp}] -- (%s) - %s\n" % [level, logger_name, message]
+end
+
+
+# Configuring the root logger.
+
+file_appender_2 = LogEasy::FileAppender.new("easylog_example.log") # Simple file logger.
+file_appender_2.min_level = LogEasy::Level::INFO # Specific level of INFO for the appender. The logger's level will not be applied to this appender now.
+console_appender_2 = LogEasy::ConsoleAppender.new # Simple console appender.
+console_appender_2.formatter = custom_formatter
+root_logger = LogEasy::Logger.root_logger # Get the handle to the root logger. The root logger's default level is ALL.
+root_logger.add_appender(console_appender_2) # Add the appenders to the root logger.
+root_logger.add_appender(file_appender_2)
+
+# Logging to a child logger, sends messages to the parent loggers too (by default).
+custom_logger = LogEasy::Logger.get_logger("Parent::Child") # Creates a logger. The '::' or '.' characters can be used to separate logger names.
+custom_logger.fine("FINE message")
+custom_logger.trace("TRACE message")
+custom_logger.debug("DEBUG message")
+custom_logger.conf("CONF message")
+custom_logger.info("INFO message")
+custom_logger.warn("WARN message")
+custom_logger.error("ERROR message")
+custom_logger.fatal("FATAL message")
+custom_logger << "UNFORMATTED message"
+
+# Adding a custom level.
+custom_level = LogEasy::Level.new("FINER", 500) # ALL < FINER < FINE
+custom_logger.log(custom_level, "Custom level message")

data/lib/logeasy.rb

@@ -0,0 +1,39 @@
+#
+# Suraj Vijayakumar
+# 18-02-2011
+#
+
+# Easy logger module.
+# This module is not thread safe.
+#
+# Usage:
+#
+# To create a new logger:
+# LogEasy::Logger.get_logger(<logger_name>)
+#   logger_name - this should be a '.' separated or '::' separated hierarchy of loggers.
+#   eg. LogEasy::Logger.get_logger("ModuleName::SubModule::ClassName")
+#
+# To change the level of a logger.
+# LogEasy::Logger.get_logger(<logger_name>).change_min_level(<new_level>) # Recursively changes this logger and all child loggers.
+# LogEasy::Logger.get_logger(<logger_name>).min_level = <new_level> # Only change this logger's level.
+#   logger_name - the logger name.
+#   new_level - the new level to set (instance of LogEasy::Level).
+#   eg. LogEasy::Logger.get_logger("ModuleName::SubModule::ClassName").change_min_level(LogEasy::Level::INFO)
+#
+# To add an appender to a logger.
+# LogEasy::Logger.get_logger(<logger_name>).add_appender(<appender>)
+#   logger_name - the logger name.
+#   appender - the appender to add (instance of LogEasy::Appender).
+#   eg. LogEasy::Logger.get_logger("ModuleName::SubModule::ClassName").add_appender(LogEasy::ConsoleAppender.new)
+#
+# By default all sub-loggers will also use this appender. A logger can be told not to use a parent's appender using the
+#   'use_parent_logger' flag. So by adding an appender to the root logger, logs sent to any logger will, by default,
+#   be logged by the root logger's appender(s) also.
+#
+# Right now the only way to configure the loggers is using code. Look at example/example.rb for how to do that.
+#
+module LogEasy
+
+  require "logeasy/logger"
+
+end

data/lib/logeasy/appender.rb

@@ -0,0 +1,120 @@
+#
+# Suraj Vijayakumar
+# 19-02-2011
+#
+
+require "time"
+
+module LogEasy
+
+  # Appender super class. An instance of this class should not be created. It must be sub-classed.
+  # Sub-classes must provide a 'write' method that will output a message to the target device.
+  # A simple console logger and file logger are provided.
+  class Appender
+
+    # Timestamp format for use by log formatters.
+    LOG_TIMESTAMP = "%d-%m-%Y %H:%M:%S.%L %z"
+
+    # Default formatter that prints messages in the format [TIMESTAMP] [LEVEL] -- [LOGGER] - [MESSAGE]
+    DEFAULT_FORMATTER = proc do |log_item|
+      logger_name = log_item.logger.name
+      level = log_item.level
+      message = log_item.message
+      timestamp = log_item.timestamp.strftime(LOG_TIMESTAMP)
+
+      "[#{timestamp}] %-5s -- (%s) - %s\n" % [level, logger_name, message]
+    end
+
+    # Custom formatter that prints messages in the format [TIMESTAMP] [LEVEL] -- [LOGGER_FULL_NAME] - [MESSAGE]
+    FULL_LOGGER_NAME_FORMATTER = proc do |log_item|
+      logger_name = log_item.logger.full_name
+      level = log_item.level
+      message = log_item.message
+      timestamp = log_item.timestamp.strftime(LOG_TIMESTAMP)
+
+      "[#{timestamp}] %-5s -- (%s) - %s\n" % [level, logger_name, message]
+    end
+
+    attr_accessor :formatter
+    attr_accessor :logger
+    attr_accessor :min_level
+    attr_accessor :allow_unformatted_messages
+
+    # Write this log item.
+    # If this appender's level is higher than the log item's level, this method will return immediately.
+    #
+    # 'log_item' - The log to write.
+    def do_log(log_item)
+      return if log_item.level < min_level
+      # Format the message and log it.
+      # If the log item is marked as unformatted, then simple print, do not format.
+      message = log_item.unformatted ? log_item.message : formatter.call(log_item)
+      write(message)
+    end
+
+    private
+
+    # Creates a new appender.
+    def initialize
+      @formatter = DEFAULT_FORMATTER
+      @allow_unformatted_messages = true
+    end
+
+    # Override to_s to return the class name.
+    def to_s
+      self.class.name
+    end
+
+    # The write message place holder. This method should be provided by implementations.
+    def write(message)
+      raise "Error! The write method needs to be overridden."
+    end
+
+  end
+
+  # Console appender that writes all messages to the console (STDOUT).
+  class ConsoleAppender < Appender
+
+    private
+
+    # New console appender.
+    def initialize
+      super
+    end
+
+    # Writes the message to STDOUT.
+    def write(message)
+      puts message
+    end
+
+  end
+
+  # File appenders write messages to a file.
+  class FileAppender < Appender
+
+    private
+
+    attr_reader :file
+
+    # Creates a new file appender.
+    # If the specified file already exists, it is overwritten.
+    def initialize(file_path)
+      super()
+      @file = File.open(file_path, "w")
+    end
+
+    # Closes this appender. This will also remove the appender from its logger.
+    def close
+      file.close
+      logger.remove_appender(self) if not logger.nil?
+    end
+
+    # Writes the message to the file.
+    # If the appender has been closed, does nothing.
+    def write(message)
+      file.puts(message) if not file.closed?
+    end
+
+  end
+
+end

data/lib/logeasy/level.rb

@@ -0,0 +1,78 @@
+#
+# Suraj Vijayakumar
+# 19-02-2011
+#
+
+module LogEasy
+
+  # A level represents the severity of a log message. The predefined levels are;
+  # ALL < FINE_TRACE < TRACE < DEBUG < CONFIG < INFO < WARN < ERROR < FATAL < UNFORMATTED < OFF
+  class Level
+
+    attr_reader :name
+    attr_reader :weight
+
+    # New logging level.
+    #
+    # 'name' - The name of the level. Formatted log messages will print this value.
+    # 'weight' - The severity of this level. The higher the value, the more severe.
+    def initialize(name, weight)
+      @name = name
+      @weight = weight
+    end
+
+    # Overload the > operator to compare the weights of the levels.
+    #
+    # 'other' - The level to compare this level with.
+    def >(other)
+      self.weight > other.weight
+    end
+
+    # Overload the >= operator to compare the weights of the levels.
+    #
+    # 'other' - The level to compare this level with.
+    def >=(other)
+      self.weight >= other.weight
+    end
+
+    # Overload the == operator to compare the weights of the levels.
+    #
+    # 'other' - The level to compare this level with.
+    def ==(other)
+      self.weight == other.weight
+    end
+
+    # Overload the < operator to compare the weights of the levels.
+    #
+    # 'other' - The level to compare this level with.
+    def <(other)
+      self.weight < other.weight
+    end
+
+    # Overload the <= operator to compare the weights of the levels.
+    #
+    # 'other' - The level to compare this level with.
+    def <=(other)
+      self.weight <= other.weight
+    end
+
+    # Overrides 'to_s' to return the name of the level.
+    def to_s
+      name
+    end
+
+    ALL = new("ALL", 0)
+    FINE_TRACE = new("FINE", 1000)
+    TRACE = new("TRACE", 2000)
+    DEBUG = new("DEBUG", 3000)
+    CONF = new("CONF", 4000)
+    INFO = new("INFO", 5000)
+    WARN = new("WARN", 6000)
+    ERROR = new("ERROR", 7000)
+    FATAL = new("FATAL", 8000)
+    UNFORMATTED = new("UNF", 9000)
+    OFF = new("OFF", 10000)
+
+  end
+
+end

data/lib/logeasy/log.rb

@@ -0,0 +1,33 @@
+#
+# Suraj Vijayakumar
+# 19-02-2011
+#
+
+module LogEasy
+
+  # Represents the actual log message. Simply a wrapper for the log information (i.e. level, logger, timestamp, message, etc...).
+  class Log
+
+    attr_reader :logger
+    attr_reader :level
+    attr_reader :message
+    attr_reader :timestamp
+    attr_reader :unformatted
+
+    # New log item.
+    #
+    # 'logger' - The logger that received this log message.
+    # 'level' - The severity of this log.
+    # 'message' - The message to log.
+    # 'unformatted' - Optional. Default is false, but if set to true, this log item will not be formatted.
+    def initialize(logger, level, message, unformatted = false)
+      @logger = logger
+      @level = level
+      @message = message
+      @timestamp = Time.now
+      @unformatted = unformatted
+    end
+
+  end
+
+end

data/lib/logeasy/logger.rb

@@ -0,0 +1,256 @@
+#
+# Suraj Vijayakumar
+# 19-02-2011
+#
+
+require "logeasy/level"
+require "logeasy/log"
+require "logeasy/appender"
+
+module LogEasy
+
+  # The logger class. Use the 'get_logger' method to create and use loggers.
+  class Logger
+
+    # Get the logger identified by the specified name. If a logger does not exist, a new one is created and returned.
+    #
+    # 'logger_name' - The name of the logger. The name should be a hierarchy of logger names separated by the '.' or "::" characters.
+    def Logger.get_logger(logger_name)
+      # Return immediately if the logger was found.
+      return @@loggers[logger_name] if @@loggers.has_key?(logger_name)
+      # Logger does not exist. Create each part.
+      parent = root_logger
+      logger_name_parts = logger_name.split(/\.|::/)
+      logger_name_parts.each do |part|
+        # Each part must be at least one character long (i.e. 2 consecutive '.' are not allowed).
+        raise "Invalid logger name '#{logger_name}'!" if part.length == 0
+        # Add this part to the current parent. If the logger is already present in this parent, then nothing is done.
+        parent = parent.add_logger(part)
+      end
+      # Finally, the parent is the required logger.
+      parent
+    end
+
+    # Get the root logger. The root logger is special, since it does not have a parent.
+    #
+    # Returns => Logger
+    def Logger.root_logger
+      @@root_logger = new(nil, "Root") if @@root_logger.nil?
+      @@root_logger
+    end
+
+    # Get the internal logger. By default this logger is switched off.
+    # This logger is special too, since it has no parent.
+    #
+    # Returns => Logger
+    def Logger.self_logger
+      if @@self_logger.nil?
+        @@self_logger = new(nil, "EasyLog")
+        @@self_logger.min_level = Level::OFF
+      end
+      @@self_logger
+    end
+
+    attr_reader :parent
+    attr_reader :name
+    attr_reader :full_name
+    attr_accessor :min_level
+    attr_accessor :use_parent_logger
+
+    # Writes the specified log without any formatting to the output.
+    # This is treated as any other log message (i.e. the level restrictions apply), only the output is not formatted.
+    # By default the level is UNFORMATTED (higher than FATAL).
+    #
+    # 'message' - The message to print.
+    # 'level' - The level of the message. Default is UNFORMATTED.
+    def <<(message, level = Level::UNFORMATTED)
+      # The unformatted log item.
+      log_item = Log.new(self, level, message, true)
+      do_log(log_item)
+    end
+
+    # Adds an appender to this logger. Removes the appender from any other logger it was associated with.
+    #
+    # 'appender' - The appender to add.
+    def add_appender(appender)
+      # Remove the appender from its earlier logger, if it exists.
+      logger = appender.logger
+      logger.remove_appender(appender) if not logger.nil?
+      # Save the new logger and add it to the appender list.
+      # Update the min_level to this logger's min level, if the appender's min level was nil (i.e. a new appender).
+      appender.logger = self
+      appender.min_level = self.min_level if appender.min_level.nil?
+      appenders << appender
+      Logger.self_logger.fine("Added '#{appender}' to '#{self}'.")
+    end
+
+    # Adds a child logger of the specified name. If a child already exists then nothing is done.
+    # The method will always return the child logger (new or old).
+    # This method is used internally to create loggers. Users should use the 'get_logger' method instead to create logger.
+    #
+    # 'logger_name' - The name of the logger.
+    #
+    # Returns => Logger
+    def add_logger(logger_name)
+      if not children.has_key?(logger_name)
+        logger = Logger.new(self, logger_name)
+        children[logger_name] = logger
+        Logger.self_logger.fine("Created new logger '#{logger}'.")
+      end
+      # Return the logger.
+      children[logger_name]
+    end
+
+    # Logs a CONF level message.
+    #
+    # 'message' - The log's message.
+    def conf(message)
+      log(Level::CONF, message)
+    end
+
+    # Logs a DEBUG level message.
+    #
+    # 'message' - The log's message.
+    def debug(message)
+      log(Level::DEBUG, message)
+    end
+
+    # Logs a ERROR level message.
+    #
+    # 'message' - The log's message.
+    def error(message)
+      log(Level::ERROR, message)
+    end
+
+    # Logs a FATAL level message.
+    #
+    # 'message' - The log's message.
+    def fatal(message)
+      log(Level::FATAL, message)
+    end
+
+    # Logs a FINE_TRACE level message.
+    #
+    # 'message' - The log's message.
+    def fine(message)
+      log(Level::FINE_TRACE, message)
+    end
+
+    # Logs a INFO level message.
+    #
+    # 'message' - The log's message.
+    def info(message)
+      log(Level::INFO, message)
+    end
+
+    # Creates a new log and dispatches it.
+    # If this logger's level is higher than the specified level, this method will return immediately.
+    #
+    # 'level'  - The level to log the message at.
+    # 'message' - The log's message.
+    def log(level, message)
+      return if level < min_level
+      log_item = Log.new(self, level, message)
+      do_log_no_check(log_item)
+    end
+
+    # Recursively change the level of this logger and all child loggers.
+    # Use min_level= to limit the change to this logger only.
+    #
+    # 'new_level' - The new level to set.
+    def change_min_level(new_level)
+      self.min_level = new_level
+      Logger.self_logger.fine("Changed minimum level for '#{self}' to '#{new_level}'.")
+      # Cascade to all children.
+      children.each_value { |child| child.change_min_level(new_level) }
+    end
+
+    # Remove the specified appender from the list of appenders for this logger.
+    #
+    # 'appender' - The appender to remove.
+    def remove_appender(appender)
+      @appenders.reject! { |item| appender.eql?(item) }
+      appender.logger = nil
+      Logger.self_logger.fine("Removed '#{appender}' from '#{self}'.")
+    end
+
+    # Override to_s to return the full name of this logger.
+    def to_s
+      full_name
+    end
+
+    # Logs a TRACE level message.
+    #
+    # 'message' - The log's message.
+    def trace(message)
+      log(Level::TRACE, message)
+    end
+
+    # Logs a WARN level message.
+    #
+    # 'message' - The log's message.
+    def warn(message)
+      log(Level::WARN, message)
+    end
+
+    protected
+
+    # Dispatch the log to all registered appenders.
+    # If the 'use_parent_logger' flag is true, then the log is dispatched to the parent also.
+    # A check of the logger's level is not done. This method is called by the 'log' method after it has performed that check.
+    #
+    # 'log_item' - The log object.
+    def do_log_no_check(log_item)
+      # Dispatch it.
+      appenders.each { |appender| appender.do_log(log_item) }
+      # If the 'use_parent_logger' flag is true then dispatch the log to the parent.
+      # The root logger and self logger are exceptions, since they do not have a parent.
+      parent.do_log(log_item) if use_parent_logger and not parent.nil?
+    end
+
+    # Dispatch the log to all registered appenders.
+    # If the 'use_parent_logger' flag is true, then the log is dispatched to the parent also.
+    # If the log's level is less than the minimum level of this logger, the method will return immediately.
+    #
+    # 'log_item' - The log object.
+    def do_log(log_item)
+      return if log_item.level < self.min_level
+      # Needs to be logged. Dispatch it.
+      appenders.each { |appender| appender.do_log(log_item) }
+      # If the 'use_parent_logger' flag is true then dispatch the log to the parent.
+      # The root logger and self logger are exceptions, since they do not have a parent.
+      parent.do_log(log_item) if use_parent_logger and not parent.nil?
+    end
+
+    private
+
+    @@loggers = {}
+    @@root_logger = nil
+    @@self_logger = nil
+
+    attr_reader :appenders
+    attr_reader :children
+
+    # Create a new logger.
+    #
+    # 'parent_logger' - The parent logger of this logger. Only the root logger is created with this value as nil.
+    # 'name' - The name of this logger.
+    # 'initial_level' - Optional, if omitted the parent's minimum level is used.
+    #
+    # Returns => Logger
+    def initialize(parent_logger, name, initial_level = nil)
+      @appenders = []
+      @children = {}
+      @use_parent_logger = true
+
+      @parent = parent_logger
+      @name = name
+      @full_name = @parent.nil? ? @name : "#{@parent.full_name}.#{@name}"
+      # The minimum value. If omitted, it is taken from the parent, for the root logger / self logger it will default to ALL.
+      # The self logger's level is immediately turned OFF after this.
+      @min_level = initial_level.nil? ? (@parent.nil? ? Level::ALL : @parent.min_level) : initial_level
+    end
+
+  end
+
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: logeasy
+version: !ruby/object:Gem::Version
+  version: 0.0.4
+  prerelease: 
+platform: ruby
+authors:
+- Suraj Vijayakumar
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-02-19 00:00:00.000000000 +05:30
+default_executable: 
+dependencies: []
+description: Hierarchical logger for Ruby. The loggers are arranged in a tree. Output
+  can be controlled using Levels, Appenders and Formatters.
+email: vijayakumar.suraj@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/logeasy.rb
+- lib/logeasy/appender.rb
+- lib/logeasy/level.rb
+- lib/logeasy/log.rb
+- lib/logeasy/logger.rb
+- lib/example/example.rb
+has_rdoc: true
+homepage: http://rubyforge.org/projects/logeasy/
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: logeasy
+rubygems_version: 1.5.2
+signing_key: 
+specification_version: 3
+summary: A simple hierarchical logger.
+test_files: []