logjam 0.0.1

data/README

@@ -0,0 +1,265 @@
+LogJam
+======
+LogJam is a library that attempts to allow for the aggregation the distributing
+logger facilities across a range of classes. Goals in creating this library
+were...
+
+   * Easy of use. Fall back on defaults as much as possible and allow the
+     functionality to be integrated and used with the least amount of work.
+     
+   * Flexibility. After easy of use is taken into consideration it should be
+     possible to use the library in a more advanced fashion if that is called
+     for.
+     
+   * Minimize the code to use it. It shouldn't require a great deal of code to
+     deploy or use the facilities and there should be no code required to pass
+     entities such as loggers around.
+     
+   * Usable in libraries. I found myself writing a lot of common logging code
+     when writing libraries and application and wanted to abstract that out. I
+     wanted to minimize the burden this placed on library users at the same
+     time.
+
+Configuration & Setup
+---------------------
+The LogJam library is configured through a call to the configure() method on the
+LogJam module. This method accepts a single parameter that may be either a
+String, a Hash, an IO object or nil.
+
+If you pass a String in this is expected to contain the path and name of a file
+that contains the logging configuration. Logging configuration files can be
+provided in either YAML or JSON format. If you pass an IO object this is
+expected to be the source of the configuration and, again, this configuration
+should be in either YAML or JSON format. In either case, where a String or IO
+is specified, the data read must be translatable into a Hash, which brings us
+to the other type that the configure() method accepts as a parameter.
+
+A Hash passed to the configure() method is expected to contain a set of values
+that can be converted into a logging set up. Passing an empty Hash will result
+in set up containing a single, universal logger attached to the standard output
+stream being created and used by all classes that have LogJam functionality.
+
+The Hash passed to the configure() method can contain two keys that the library
+will recognise and use. The first of these is 'loggers', in either Symbol or
+String form. The value under the loggers key is expected to be an Array
+containing zero or more logger definitions. A logger definition is a Hash in
+which the following keys are recognised (either as Strings or Symbols)...
+
+   Key                       Description
+   -----------------------   --------------------------------------------------
+   default                   A boolean indicating whether this logger is the
+                             default (i.e. the one to be used when no other
+                             fits the bill).
+   datetime_format           The date/time format to be used by the logger. See
+                             the documentation for the standard Ruby Logger
+                             class for more details.
+   file                      The path and name of the file that logging details
+                             will be written to. Two special values are
+                             recognised in this value. STDOUT and STDERR are
+                             translated to mean the standard output or error
+                             streams respectively.
+   level                     The logging level to set on the logger.
+   max_size                  When rotation is set to an integer value this value
+                             can be set to indicate the maximum permitted file
+                             size for a log file.
+   name                      The name to associate with the logger. This allows
+                             loggers to be tied to classes or for the creation
+                             of aliases that tie multiple names to a single
+                             logger.
+   rotation                  The frequency with which the log file is rotated.
+                             This may be an integer to indicate how many old log
+                             files are retained or may be a String such as
+                             "daily", "weekly" or "monthly".
+
+A note on logger names. Logger names (including alias names) aren't hierarchical
+and should be unique.
+
+The second key recognised in the configuration Hash is 'aliases', again as
+either a String or Symbol. The value under the aliases key is expected to be a
+Hash that maps String keys to String values. The key values are expected to be
+alias names and the mapped values are expected to be the name of a logger
+declared in the logger section. An entry in the aliases Hash creates an alias
+for an existing logger under a different name.
+
+If you pass nil to the configure method it behaves in a slightly different
+fashion. In this case the method searches for a configuration file that it can
+use given a default set of files names (basically logging.yaml, logging.yml and
+logging.json in the current working directory and in a subdirectory of the
+current working directory called config). The first of these files that it finds
+it attempts to use as configuration for the logging set up.
+
+See the end of this document for some example configurations.
+
+Logging With The Library
+------------------------
+The stated goals of the LogJam library are to avoid the need to pass Logger
+instances around while still allowing potentially complex configuration with a
+minimum of code. The first step in this process has been covered in the
+Configuration & Setup section in which it's explained how to configure logging
+from a single Hash or file. This section will provide details on how to deploy
+loggers to various classes.
+
+The LogJam library works by providing an extension to any class that uses it
+that provides access to the logger to be used by the class. To make use of this
+functionality a class must call the apply() method of the LogJam module. A
+typical call to this method might look like...
+
+   LogJam.apply(self, "my_logger")
+   
+This line would appear somewhere inside the definition for the class that will
+use logging. The first parameter to the call is the class that is to be extended
+with the LogJam functionality. The second parameter is the name of the logger
+that the class will use. Note that this parameter is optional and, if not
+specified or if a matching logger does not exist, the class will fall back in
+using the default logger.
+
+Once this line has been added to the class definition it will cause the class to
+be extended with two methods - one called log() and one called log=(). The first
+of these retrieves the Logger instance to be used by the class instances. The
+second allows the Logger instance associated with a class to be altered.
+
+The following complete (although contrived) example gives an overview of how
+this would work...
+
+   require 'rubygems'
+   require 'logjam'
+   
+   class Writer
+      LogJam.apply(self, "echo")
+      
+      def initialize(stream=STDOUT)
+         @stream = stream
+      end
+      
+      def echo(message)
+         Writer.log.debug("Echoed: #{message}")
+         @stream.puts message
+      end
+   end
+   
+   begin
+      LogJam.configure({:loggers => [{:name => "echo",
+                                      :file => "echo.log"}]})
+                                      
+      writer = Writer.new
+      writer.echo "This is a string containing my message."
+   rescue => error
+      puts "ERROR: #{error}\n" + error.backtrace.join("\n")
+   end
+
+In this example we create a Writer class that can echo a String on a stream. In
+doing this it also logs the message echoed at the debug level. We use the
+LogJam.apply() method to extend this class with logging capabilities so that, in
+the echo() method, we can simply call Writer.log() to get the class logger.
+
+In the later section of the code we configure the LogJam system to have a single
+Logger that writes to the echo.log file. We then create a Writer instance and
+use it to write a simple message. This message should appear on the standard
+output stream and be logged to the echo.log file.
+
+Advanced Usage
+--------------
+The hope would be that this library can be used in the creation of other
+libraries and allow for control of the logging generated by those libraries
+without having to dig into the workings of the library or to pass around Logger
+instances are constructor parameters or static data. In this case I recommend
+explicitly declaring logger names when using the apply() method and making the
+name that the library uses available with the library documentation so that the
+libraries logging can be switched off or on as needed.
+
+It's intended that, in general, the configure() method on the LogJam module
+should only be called once. Calling it a second time will clear all existing
+logging configuration and set up. This may or may not be an issue depending on
+whether you decide to cache logger inside class instances instead of always
+accessing them through the class level accessor.
+
+The Logger instance returned from a LogJam are intended to be fully compatible
+with the class defined within the standard Ruby Logger library. If you need to
+change elements, such as the formatter, you should just do so on the logger in
+the normal fashion. If you define multiple Logger instances then you will have
+to change each individually.
+
+Using the log=() method that is added to each class by the LogJam facilities it
+is possible to change the Logger being used. If you want to use this method
+please note that changing a Logger that is created via an alias will change the
+original Logger and thereby affect all classes that make use of that Logger (and
+not necessarily just the one making the change). If you want to do this give the
+class it's own logger instance.
+
+Finally, any logger can be fetched from the library using it's name and making
+a call to the LogJam.get_logger() method. Note if you omit the name or pass in
+nil you will retrieve the libraries default logger.
+
+Example Configurations
+----------------------
+This section contains some example configurations. A short explanation is given
+for each configuration and then the configuration itself in Hash, YAML and JSON
+formats is provided.
+
+This represents the most basic configuration possible. In passing an empty Hash
+to the configure method the system creates a single, default logger that writes
+everything on the standard output stream...
+
+Hash
+   {}
+   
+YAML
+   ---
+   {}
+
+JSON
+   {}
+
+The following simple configuration writes all logging output to a file called
+application.log in the current working directory. If a logging level is not
+explicitly specified then DEBUG is the default...
+
+Hash
+   {:loggers => [{:default => true, :file => "application.log"}]}
+
+YAML
+   --- 
+   :loggers: 
+   - :default: true
+     :file: application.log
+
+JSON
+   {"loggers": {"default": true, "file": "application.log"}}
+   
+This configuration declares two loggers. The first is called 'silent' and will
+log nothing. The silent logger is the default and so will be used for any class
+that doesn't have an explicitly named logger. The second is called 'verbose' and
+logs everything from the debug level up on the standard output stream. The
+configuration also declares an alias pointing the name 'database' to refer to
+the verbose logger. An class that declares it uses the 'database' logger will
+generate output while all others will be silenced.
+
+Hash
+   {:loggers => [{:default => true,
+                  :file    => "STDOUT",
+                  :level   => "UNKNOWN",
+                  :name    => "silent"},
+                 {:file    => "STDOUT",
+                  :name    => "verbose"}],
+    :aliases => {"database" => "verbose"}}
+
+YAML
+   --- 
+   :loggers: 
+   - :default: true
+     :file: STDOUT
+     :level: UNKNOWN
+     :name: silent
+   - :file: STDOUT
+     :name: verbose
+   :aliases: 
+     database: verbose
+
+JSON
+   {"loggers": [{"default":true,
+                 "file": "STDOUT",
+                 "level": "UNKNOWN",
+                 "name": "silent"},
+                {"file": "STDOUT",
+                 "name": "verbose"}],
+    "aliases": {"database":"verbose"}}

data/lib/logjam/exceptions.rb

@@ -0,0 +1,40 @@
+#! /usr/bin/env ruby
+#
+# Copyright (c), 2012 Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+require 'stringio'
+
+module LogJam
+   # This class provides the exception class used by the LogJam library.
+   class LogJamError < StandardError
+      # Attribute accessor/mutator declarations.
+      attr_accessor :verbose
+
+      # Constructor for the LogJamError class.
+      #
+      # ==== Parameters
+      # message::  The message to be associated with the error.
+      # cause::    Any underlying exception to be associated with the error.
+      #            Defaults to nil.
+      def initialize(message, cause=nil, verbose=true)
+         super(message)
+         @cause   = cause
+         @verbose = verbose
+      end
+
+      # This method fetches a stringified interpretation of an exception.
+      def to_s()
+         text = StringIO.new
+         text << super
+         if @verbose
+            text << "\n" + self.backtrace.join("\n")
+            if !@cause.nil?
+               text << "\n\nCause: #{@cause}"
+               text << "\n" + @cause.backtrace.join("\n")
+            end
+         end
+         text.string
+      end
+   end
+end

data/lib/logjam/logjam-original.rb

@@ -0,0 +1,129 @@
+#! /usr/bin/env ruby
+#
+# Copyright (c), 2012 Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+require 'logger'
+
+# This module defines the name space to be used by all code within the
+# LogJam library.
+module LogJam
+   # Module constants.
+   LOG_FILE  = :log_file
+   LOG_ROLL  = :log_roll_period
+   LOG_LEVEL = :log_level
+
+   # Module wide property declarations.
+   @@logjam_logger = nil
+   
+   # This method fetches the module logger, initializing it and creating it if
+   # it doesn't yet exist.
+   #
+   # ==== Parameters
+   # configuration::  The configuration to use in setting up the logging.
+   #                  Defaults to nil to indicate the creation of a logger based
+   #                  on STDOUT.
+   def log(configuration=nil)
+      LogJam.configure(configuration) if !configuration.nil? || @@logjam_logger.nil?
+      @@logjam_logger
+   end
+   
+   # This method updates the logger associated with the module.
+   #
+   # ==== Parameters
+   # logger::  The new logger for the module.
+   def log=(logger)
+      LogJam.log = logger
+   end
+
+   # This method updates the logger associated with the module.
+   #
+   # ==== Parameters
+   # logger::  The new logger for the module.
+   def self.log=(logger)
+      @@logjam_logger.logger = logger
+   end
+   
+   # This method is used to install the LogJam capabilities into a target class.
+   #
+   # ==== Parameters
+   # target:: The class that is to be 'logified'.
+   def self.logify(target)
+      target.extend(self)
+   end
+   
+   # This method sets up the module logging from configuration.
+   #
+   # ==== Parameters
+   # configuration::  The configuration to use when setting up logging.
+   def self.configure(configuration)
+      if !configuration.nil?
+         if @@logjam_logger.nil?
+            # Create the logger.
+            if LogJam.is_configured?(configuration, LOG_FILE)
+               file_name       = LogJam.get_value(configuration, LOG_FILE)
+               period          = LogJam.get_value(configuration, LOG_ROLL)
+               @@logjam_logger = LogJamLogger.new(file_name, period)
+            else
+               @@logjam_logger = LogJamLogger.new(STDOUT)
+            end
+         else
+            # Change the internally held logger.
+            if LogJam.is_configured?(configuration, LOG_FILE)
+               file_name              = LogJam.get_value(configuration, LOG_FILE)
+               period                 = LogJam.get_value(configuration, LOG_ROLL)
+               @@logjam_logger.logger = Logger.new(file_name, period)
+            else
+               @@logjam_logger.logger = Logger.new(STDOUT)
+            end
+         end
+      else
+         if @@logjam_logger.nil?
+            @@logjam_logger = LogJamLogger.new(STDOUT)
+         else
+            @@logjam_logger.logger = Logger.new(STDOUT)
+         end
+      end
+
+      # Set the logger level.
+      level = LogJam.get_value(configuration, LOG_LEVEL, "DEBUG")
+      case level.downcase
+         when "info"
+            level = Logger::INFO
+         when "warn"
+            level = Logger::WARN
+         when "error"
+            level = Logger::ERROR
+         when "fatal"
+            level = Logger::FATAL
+         when "unknown"
+            level = Logger::UNKNOWN
+         else
+            level = Logger::DEBUG
+      end
+      @@logjam_logger.level = level
+      @@logjam_logger
+   end
+   
+   private
+   
+   # This method encapsulates the functionality for extracting named value from
+   # a Hash given a key.
+   def self.get_value(configuration, name, default=nil)
+      value = default
+      if !configuration.nil?
+         if configuration.include?(name)
+            value = configuration[name]
+         elsif configuration.include?(name.to_s)
+            value = configuration[name.to_s]
+         end
+      end
+      value
+   end
+   
+   # This method is used internally by the module to determine whether a
+   # configuration setting has been provided.
+   def self.is_configured?(configuration, name)
+      configuration.include?(name) || configuration.include?(name.to_s)
+   end
+end

data/lib/logjam/logjam.rb

@@ -0,0 +1,382 @@
+#! /usr/bin/env ruby
+#
+# Copyright (c), 2012 Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+require 'json'
+require 'logger'
+require 'stringio'
+require 'yaml'
+
+# This module defines the name space to be used by all code within the
+# LogJam library.
+module LogJam
+   # Module constants.
+   LOGGER_NAME               = :name
+   LOGGER_FILE               = :file
+   LOGGER_ROTATION           = :rotation
+   LOGGER_MAX_SIZE           = :max_size
+   LOGGER_LEVEL              = :level
+   LOGGER_DEFAULT            = :default
+   LOGGER_DATETIME_FORMAT    = :datetime_format
+   DEFAULT_FILE_NAMES        = [".#{File::SEPARATOR}logging.yaml",
+                                ".#{File::SEPARATOR}logging.yml",
+                                ".#{File::SEPARATOR}logging.json",
+                                ".#{File::SEPARATOR}config#{File::SEPARATOR}logging.yaml",
+                                ".#{File::SEPARATOR}config#{File::SEPARATOR}logging.yml",
+                                ".#{File::SEPARATOR}config#{File::SEPARATOR}logging.json"]
+
+   # Module static properties.
+   @@logjam_modules = {}
+   @@logjam_loggers = {}
+   
+   # This method is used to configure the LogJam module with the various loggers
+   # it will use.
+   #
+   # ==== Parameters
+   # source::  Either a String containing the path and name of the configuration
+   #           file containing the logging set up, an IO object from which the
+   #           configuration details can be read, a Hash containing a logging
+   #           configuration or nil.
+   def self.configure(source)
+      @@logjam_modules = {}
+      @@logjam_loggers = {}
+      
+      # Check for default files if nil was passed in.
+      source = LogJam.find_default_file if source.nil?
+
+      if !source.kind_of?(Hash) && !source.nil?
+         io            = source.kind_of?(String) ? File.new(source) : source
+         type          = source.kind_of?(String) ? LogJam.guess_format(source) : nil
+         LogJam.process_configuration(LogJam.load_configuration(io, type))
+      elsif source.nil?
+         LogJam.process_configuration({})
+      else
+         LogJam.process_configuration(source)
+      end
+   end
+   
+   # This method is used to install logging facilities at the class level for a
+   # given class. Once 'logified' a class will possess two new methods. The
+   # first, #log(), retrieves the logger associated with the class. The second,
+   # #log=(), allows the assignment of the logger associated with the class.
+   # Note that changing the logger associated with a class will impact all other
+   # classes that use the same logger.
+   #
+   # ==== Parameters
+   # target::  The target class that is to be extended.
+   # name::    The name of the logger to be used by the class. Defaults to nil
+   #           to indicate use of the default logger.
+   def self.apply(target, name=nil)
+      target.extend(LogJam.get_module(name))
+   end
+
+   # This method attempts to fetch the logger for a specified name. If this
+   # logger does not exist then a default logger will be returned instead.
+   #
+   # ==== Parameters
+   # name::  The name of the logger to retrieve.
+   def self.get_logger(name=nil)
+      LogJam.process_configuration(nil) if @@logjam_loggers.empty?
+      @@logjam_loggers.fetch(name, @@logjam_loggers[nil])
+   end
+
+   # This method fetches a list of the names currently defined within the LogJam
+   # internal settings.
+   def self.names
+      @@logjam_loggers.keys.compact
+   end
+   
+   private
+   
+   # This method fetches the module associated with a name. If the module does
+   # not exist the default module is returned instead.
+   #
+   # ==== Parameters
+   # name:: The name associated with the module to return.
+   def self.get_module(name)
+      LogJam.create_module(name)
+   end
+
+   # This method attempts to load a LogJam configuration from an IO object.
+   #
+   # ==== Parameters
+   # source::  The IO object to read the configuration details from.
+   # type::    An indicator of the format being used for the configuration. This
+   #           should be :yaml, :json or nil. Nil indicates that the library
+   #           will try to load the file in various formats.
+   def self.load_configuration(source, type)
+      configuration = nil
+      if ![:yaml, :json].include?(type)
+         begin
+            # Read in the full details of the configuration.
+            details = source.read
+            
+            # Try YAML format first.
+            begin
+               configuration = LogJam.load_yaml_configuration(StringIO.new(details))
+            rescue LogJamError
+               # Assume wrong format and ignore.
+               configuration = nil
+            end
+            
+            if configuration.nil?
+               # Try JSON format second.
+               begin
+                  configuration = LogJam.load_json_configuration(StringIO.new(details))
+               rescue LogJamError
+                  # Assume wrong format and ignore.
+                  configuration = nil
+               end
+            end
+         rescue => error
+            raise LogJamError.new("Exception raised loading the LogJam "\
+                                  "configuration.\nCause: #{error}", error)
+         end
+         
+         # Check if the load was successful.
+         if configuration.nil?
+            raise LogJamError.new("Error loading the LogJam configuration. The "\
+                                  "configuration is not in a recognised format "\
+                                  "or contains errors. The configuration must "\
+                                  "be in either YAML or JSON format.")
+         end
+      elsif type == :json
+         configuration = LogJam.load_json_configuration(source)
+      elsif type == :yaml
+         configuration = LogJam.load_yaml_configuration(source)
+      end
+      configuration
+   end
+
+   # This method attempts to load a configuration for the LogJam library from
+   # a file. The configuration is expected to be in YAML format.
+   #
+   # ==== Parameters
+   # source::  An IO object from which the configuration will be read.
+   def self.load_yaml_configuration(source)
+      begin
+         YAML.load(source)
+      rescue => error
+         raise LogJamError.new("Error loading LogJam configuration from YAML "\
+                               "source.\nCause: #{error}", error)
+      end
+   end
+
+   # This method attempts to load a configuration for the LogJam library from
+   # a file. The configuration is expected to be in JSON format.
+   #
+   # ==== Parameters
+   # source::  An IO object from which the configuration will be read.
+   def self.load_json_configuration(source)
+      begin
+         JSON.parse(source.read)
+      rescue => error
+         raise LogJamError.new("Error loading LogJam configuration from JSON "\
+                               "source.\nCause: #{error}", error)
+      end
+   end
+   
+   # This method processes a logger configuration and generates the appropriate
+   # set of loggers and internal objects from it.
+   #
+   # ==== Parameters
+   # configuration::  The configuration to be processed. If this is nil or empty
+   # then a single default logger is generated that writes to the standard
+   # output stream.
+   def self.process_configuration(configuration)
+      if !configuration.nil? && !configuration.empty?
+         key = (configuration.include?(:loggers) ? :loggers : "loggers")
+         if configuration.include?(key)
+            loggers = configuration[key]
+            if loggers.kind_of?(Array)
+               configuration[key].each do |definition|
+                  LogJam.create_logger(definition)
+               end
+            elsif loggers.kind_of?(Hash)
+               LogJam.create_logger(loggers)
+            else
+               raise LogJamError.new("The loggers configuration entry is in "\
+                                     "an unrecognised format. Must be either "\
+                                     "a Hash or an Array.")
+            end
+         end
+      end
+
+      # Set up any aliases that have been specified.
+      if !@@logjam_loggers.empty? && !configuration.nil? && !configuration.empty?
+         key = (configuration.include?(:loggers) ? :aliases : "aliases")
+         if configuration.include?(key)
+            configuration[key].each do |name, equivalent|
+               @@logjam_loggers[name] = LogJam.get_logger(equivalent)
+               @@logjam_modules[name] = LogJam.get_module(equivalent)
+            end
+         end
+      end
+
+      # Create a default logger if one hasn't been specified.
+      if @@logjam_loggers[nil].nil?
+         LogJam.create_logger({LOGGER_FILE => "STDOUT"})
+      end
+   end
+
+   # This method is used to create an anonymous module under a given name (if it
+   # doesn't already exist) and return it to the caller.
+   #
+   # ==== Parameters
+   # name::  The name to create the module under.
+   def self.create_module(name)
+      if !@@logjam_modules.include?(name)
+         # Create the anonymous module and add methods to it.
+         @@logjam_modules[name] = Module.new
+         @@logjam_modules[name].send(:define_method, :log) do
+            LogJam.get_logger(name)
+         end
+         @@logjam_modules[name].send(:define_method, :log=) do |logger|
+            LogJam.get_logger(name).logger = logger
+         end
+      end
+      @@logjam_modules[name]
+   end
+
+   # This method extends a specified class with a named module.
+   #
+   # ==== Parameters
+   # target::  The class that is to be extended.
+   # name::    The name of the module to extend the class with.
+   def self.extend_class(target, name)
+      target.extend(LogJam.get_module(name))
+   end
+   
+   # This method attempts to guess the format that configuration details will be
+   # in given a file name. Guessing is done by looking at the file's extension.
+   # Files ending in '.yaml' or '.yml' are considered YAML. Files ending '.json'
+   # are considered JSON. The method returns nil if the path passed in has
+   # neither of these extensions.
+   #
+   # ==== Parameters
+   # path::  The path and name of the file to make the guess from.
+   def self.guess_format(path)
+      type = nil
+      if path.nil? && path.include?(".")
+         offset    = path.length - path.reverse.index(".")
+         extension = path[offset, path.length - offset].downcase
+         case extension
+            when 'yaml', 'yml'
+               type = :yaml
+
+            when 'json'
+               type = :json
+         end
+      end
+      type
+   end
+   
+   # This method creates a logger from a given definition. A definition should
+   # be a Hash containing the values that are used to configure the Logger with.
+   #
+   # ==== Parameters
+   # definition::  A Hash containing the configuration details for the logger.
+   def self.create_logger(definition)
+      # Fetch the configuration values.
+      name     = LogJam.get_value(definition, LOGGER_NAME)
+      path     = LogJam.get_value(definition, LOGGER_FILE)
+      rotation = LogJam.get_value(definition, LOGGER_ROTATION)
+      max_size = LogJam.get_value(definition, LOGGER_MAX_SIZE)
+      level    = LogJam.get_value(definition, LOGGER_LEVEL)
+      default  = LogJam.get_value(definition, LOGGER_DEFAULT)
+      
+      device = nil
+      if ["STDOUT", "STDERR"].include?(path)
+         device = (path == "STDOUT" ? STDOUT : STDERR)
+      else
+         device = path
+      end
+
+      if rotation.kind_of?(String) && /^\s*\d+\s*$/ =~ rotation
+         rotation = rotation.to_i
+         rotation = 0 if rotation < 0
+      end
+
+      if !max_size.nil? && max_size.kind_of?(String)
+         max_size = max_size.to_i
+      end
+      max_size = 1048576 if !max_size.nil? && max_size < 1024
+
+      if !level.nil?
+         case level.downcase
+            when 'info'
+               level = Logger::INFO
+   
+            when 'warn'
+               level = Logger::WARN
+   
+            when 'error'
+               level = Logger::ERROR
+   
+            when 'fatal'
+               level = Logger::FATAL
+   
+            when 'unknown'
+               level = Logger::UNKNOWN
+   
+            else
+               level = Logger::DEBUG
+         end
+      else
+         level = Logger::DEBUG
+      end
+
+      if default != true
+         if default.kind_of?(String)
+            default = ["true", "yes", "on", "1"].include?(default.downcase)
+         else
+            default = false
+         end
+      end
+
+      # Create the actual logger and associated module.
+      logger                 = LogJamLogger.new(device, rotation, max_size)
+      logger.level           = level
+      logger.name            = name
+      @@logjam_loggers[name] = logger
+      logger_module          = LogJam.create_module(name)
+      if default
+         @@logjam_loggers[nil]  = logger
+         @@logjam_modules[nil]  = logger_module
+      end
+      logger
+   end
+   
+   # This method attempts to fetch a value from a Hash. The key passed to the
+   # method should be a symbol and this will be checked for first. If this is
+   # not found then a check is made for the string equivalent. The first of
+   # these that is present in the Hash generates the value returned. If neither
+   # is present in the Hash then nil is returned.
+   #
+   # ==== Parameters
+   # source::  The Hash that will be checked for the value.
+   # key::     A symbol that will be checked as the key for the value.
+   def self.get_value(source, key)
+      if source.include?(key)
+         source[key]
+      elsif source.include?(key.to_s)
+         source[key.to_s]
+      else
+         nil
+      end
+   end
+   
+   # This module level method is used to check for the existence of a
+   # configuration file under one or a standard set of names. This method is
+   # only used whenever the configure method is called and either passed nil
+   # or no parameter.
+   def self.find_default_file
+      file_name = nil
+      DEFAULT_FILE_NAMES.each do |name|
+         file_name = name if File.exists?(name) && File.readable?(name)
+         break if !file_name.nil?
+      end
+      file_name
+   end
+end

data/lib/logjam/logjam_logger.rb

@@ -0,0 +1,202 @@
+#! /usr/bin/env ruby
+#
+# Copyright (c), 2012 Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+module LogJam
+   # This class represents a specialization of the Ruby Logger class. The class
+   # retains a Ruby Logger instance within itself and delegates all standard
+   # logger calls to this instance. This allows for changes to the underlying
+   # logger without changing the containing one, thus bypassing people caching
+   # an instance.
+   class LogJamLogger < Logger
+      # Constructor for the LogJamLogger class. All parameters are passed
+      # straight through to create a standard Ruby Logger instance except
+      # when the first parameter is a Logger instance. In this case the
+      # Logger passed in is used rather than creating a new one.
+      #
+      # ==== Parameters
+      # logdev::      The log device to be used by the logger. This should
+      #               either be a String containing a file path/name or an IO
+      #               object that the logging details will be written to.
+      # shift_age::   The maximum number of old log files to retain or a String
+      #               containing the rotation frequency for the log.
+      # shift_size::  The maximum size that the loggin output will be allowed
+      #               to grow to before rotation occurs.
+      def initialize(logdev, shift_age=0, shift_size=1048576)
+         if logdev.kind_of?(Logger)
+            @log = logdev
+         else
+            @log = Logger.new(logdev, shift_age, shift_size)
+         end
+         @name = nil
+      end
+      
+      # Attribute accessor/mutator declaration.
+      attr_accessor :name
+
+      # Overload of the property fetcher provided by the contained Logger
+      # instance.
+      def formatter
+         @log.formatter
+      end
+
+      # Overload of the property updater provided by the contained Logger
+      # instance.
+      def formatter=(formatter)
+         @log.formatter = formatter
+      end
+
+      # Overload of the property fetcher provided by the contained Logger
+      # instance.
+      def level
+         @log.level
+      end
+
+      # Overload of the property updater provided by the contained Logger
+      # instance.
+      def level=(level)
+         @log.level = level
+      end
+
+      # Overload of the property fetcher provided by the contained Logger
+      # instance.
+      def progname
+         @log.progname
+      end
+
+      # Overload of the property updater provided by the contained Logger
+      # instance.
+      def progname=(name)
+         @log.progname = name
+      end
+
+      # Overload of the property fetcher provided by the contained Logger
+      # instance.
+      def sev_threshold
+         @log.sev_threshold
+      end
+
+      # Overload of the property updater provided by the contained Logger
+      # instance.
+      def sev_threshold=(threshold)
+         @log.sev_threshold = threshold
+      end
+
+      # Overload of the corresponding method on the Logger class to pass the
+      # call straight through to the contained logger.
+      def <<(message)
+         @log << message
+      end
+
+      # Overload of the corresponding method on the Logger class to pass the
+      # call straight through to the contained logger.
+      def add(severity, message=nil, program=nil, &block)
+         @log.add(severity, message, program, &block)
+      end
+
+      # Overload of the corresponding method on the Logger class to pass the
+      # call straight through to the contained logger.
+      def close
+         @log.close
+      end
+
+      # Overload of the corresponding method on the Logger class to pass the
+      # call straight through to the contained logger.
+      def datetime_format
+         @log.datetime_format
+      end
+
+      # Overload of the corresponding method on the Logger class to pass the
+      # call straight through to the contained logger.
+      def datetime_format=(format)
+         @log.datetime_format = format
+      end
+
+      # Overload of the corresponding method on the Logger class to pass the
+      # call straight through to the contained logger.
+      def debug(program=nil, &block)
+         @log.debug(program, &block)
+      end
+
+      # Overload of the corresponding method on the Logger class to pass the
+      # call straight through to the contained logger.
+      def debug?
+         @log.debug?
+      end
+
+      # Overload of the corresponding method on the Logger class to pass the
+      # call straight through to the contained logger.
+      def error(program=nil, &block)
+         @log.error(program, &block)
+      end
+
+      # Overload of the corresponding method on the Logger class to pass the
+      # call straight through to the contained logger.
+      def error?
+         @log.error?
+      end
+
+      # Overload of the corresponding method on the Logger class to pass the
+      # call straight through to the contained logger.
+      def fatal(program=nil, &block)
+         @log.fatal(program, &block)
+      end
+
+      # Overload of the corresponding method on the Logger class to pass the
+      # call straight through to the contained logger.
+      def fatal?
+         @log.fatal?
+      end
+
+      # Overload of the corresponding method on the Logger class to pass the
+      # call straight through to the contained logger.
+      def info(program=nil?, &block)
+         @log.info(program, &block)
+      end
+
+      # Overload of the corresponding method on the Logger class to pass the
+      # call straight through to the contained logger.
+      def info?
+         @log.info?
+      end
+
+      # Overload of the corresponding method on the Logger class to pass the
+      # call straight through to the contained logger.
+      def unknown(program=nil, &block)
+         @log.unknown(program, &block)
+      end
+
+      # Overload of the corresponding method on the Logger class to pass the
+      # call straight through to the contained logger.
+      def warn(program=nil, &block)
+         @log.warn(program, &block)
+      end
+
+      # Overload of the corresponding method on the Logger class to pass the
+      # call straight through to the contained logger.
+      def warn?
+         @log.warn?
+      end
+
+      # This method fetches the standard Ruby Logger instance contained within
+      # a LogJamLogger object.
+      def logger
+         @log
+      end
+      
+      # This method updates the logger instance contained within a LogJamLogger
+      # object.
+      #
+      # ==== Parameters
+      # logger::  The object to set as the contained logger. This should be an
+      #           instance of the standard Ruby Logger class or something
+      #           compatible with this.
+      def logger=(logger)
+         @log = logger
+      end
+
+      # Aliases
+      alias :log :add
+   end
+end

data/lib/logjam.rb

@@ -0,0 +1,10 @@
+#! /usr/bin/env ruby
+#
+# Copyright (c), 2012 Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+require 'logger'
+require 'logjam/exceptions'
+require 'logjam/logjam_logger'
+require 'logjam/logjam'
+

data/license.txt

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2011 Peter Wood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification 
+name: logjam
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Black North
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-02-10 00:00:00 +00:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+description: LogJam is a library to simplify the use of logging across libraries and applications.
+email: ruby@blacknorth.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/logjam/logjam-original.rb
+- lib/logjam/exceptions.rb
+- lib/logjam/logjam.rb
+- lib/logjam/logjam_logger.rb
+- lib/logjam.rb
+- license.txt
+- README
+has_rdoc: true
+homepage: 
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A library to aggregate logging.
+test_files: []
+