hatchet 0.0.1 → 0.0.2

data/lib/hatchet/configuration.rb

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+
+module Hatchet
+
+  # Public: Class for configuring Hatchet.
+  #
+  class Configuration
+    include LevelManager
+
+    # Public: The Array of configured appenders.
+    #
+    attr_reader :appenders
+
+    # Internal: Creates a new configuration.
+    #
+    # Creates the levels Hash with a default logging level of info.
+    #
+    def initialize
+      @levels = { nil => :info }
+      @appenders = []
+    end
+
+  end
+
+end
+

data/lib/hatchet/level_manager.rb

@@ -0,0 +1,58 @@
+# -*- encoding: utf-8 -*-
+
+module Hatchet
+
+  # Public: Module for managing the configuration of log levels on a class or
+  # module level. Useful when you are creating custom appenders.
+  #
+  module LevelManager
+
+    # Private: All the possible levels of log filter in order of severity.
+    #
+    LEVELS = [:debug, :info, :warn, :error, :fatal, :off]
+
+    # Public: The Hash containing the log level configuration.
+    #
+    attr_accessor :levels
+
+    # Public: Set the lowest level of message to log for the given context.
+    #
+    # level   - The lowest level of message to log for the given context.
+    # context - The context that level applies to (default: nil).
+    #
+    # Setting a level for nil set the default level for all contexts that have
+    # not been specified.
+    #
+    # Returns nothing.
+    def level(level, context = nil)
+      context = context.to_s unless context.nil?
+      self.levels[context] = level
+    end
+
+    # Internal: Returns true if the appender is configured to log messages of
+    # the given level within the given context, otherwise returns false.
+    #
+    # level   - The level of the message.
+    # context - The context of the message.
+    #
+    # Returns true if the appender is configured to log messages of the given
+    # level within the given context, otherwise returns false.
+    #
+    def enabled?(level, context)
+      unless self.levels.key? context
+        lvl = self.levels[nil]
+        root = []
+        context.to_s.split('::').each do |part|
+          root << part
+          path = root.join '::'
+          lvl = self.levels[path] if self.levels.key? path
+        end
+        self.levels[context] = lvl
+      end
+      LEVELS.index(level) >= LEVELS.index(self.levels[context])
+    end
+
+  end
+
+end
+

data/lib/hatchet/logger.rb

@@ -0,0 +1,102 @@
+# -*- encoding: utf-8 -*-
+
+module Hatchet
+
+  # Internal: Class that handles logging calls and distributes them to all its
+  # appenders.
+  #
+  # Each logger has 6 methods. Those are, in decreasing order of severity:
+  #
+  #  * fatal
+  #  * error
+  #  * warn
+  #  * info
+  #  * debug
+  #  * trace
+  #
+  # All the methods have the same signature. You can either provide a message as
+  # a direct string, or as a block to the method is lazily evaluated (this is
+  # the recommended option).
+  #
+  # Examples
+  #
+  #   logger.info "Informational message"
+  #   logger.info { "Informational message #{potentially_expensive}" }
+  #
+  # Log messages are sent to each appender where they will be filtered and
+  # invoked as configured.
+  #
+  class Logger
+
+    # Internal: Creates a new logger.
+    #
+    # host      - The object the logger gains its context from.
+    # appenders - The appenders the logger delegates its messages to.
+    #
+    def initialize(host, appenders)
+      @context = context host
+      @appenders = appenders
+    end
+
+    # Public: Logs a message at the given level.
+    #
+    # message - An already evaluated message, usually a String (default: nil).
+    # block   - An optional block which will provide a message when invoked.
+    #
+    # One of message or block must be provided. If both are provided then the
+    # block is preferred as it is assumed to provide more detail.
+    #
+    # Returns nothing.
+    #
+    [:trace, :debug, :info, :warn, :error, :fatal].each do |level|
+      define_method level do |message = nil, &block|
+        return unless message or block
+        add level, Message.new(message, &block)
+      end
+    end
+
+    private
+
+    # Private: Adds a message to each appender at the specified level.
+    #
+    # level   - The level of the message. One of, in decreasing order of
+    #           severity:
+    #
+    #             * fatal
+    #             * error
+    #             * warn
+    #             * info
+    #             * debug
+    #             * trace
+    #
+    # message - The message that will be logged by an appender when it is
+    #           configured to log at the given level or lower.
+    #
+    # Returns nothing.
+    #
+    def add(level, message)
+      @appenders.each { |appender| appender.add(level, @context, message) }
+    end
+
+    # Private: Determines the contextual name of the host object.
+    #
+    # host - The object hosting this logger.
+    #
+    # Returns the String 'main' if this is the initial execution context of
+    # Ruby, the host itself when the host is a module, otherwise the object's
+    # class.
+    #
+    def context(host)
+      if host.inspect == 'main'
+        'main'
+      elsif host.class == Module
+        host
+      else
+        host.class
+      end
+    end
+
+  end
+
+end
+

data/lib/hatchet/logger_appender.rb

@@ -0,0 +1,71 @@
+# -*- encoding: utf-8 -*-
+
+require 'logger'
+
+module Hatchet
+
+  # Public: Class for wrapping a standard Logger with Hatchet's class/module
+  # level log filtering.
+  #
+  class LoggerAppender
+    include LevelManager
+
+    # Public: The Logger the appender encapsulates.
+    #
+    attr_accessor :logger
+
+    # Public: The formatter used to format the message before they are sent to
+    # the logger.
+    #
+    attr_accessor :formatter
+
+    # Public: Creates a new Logger appender.
+    #
+    # options - The Hash options used to setup the appender (default: {}).
+    #           :formatter - The formatter used to format log messages.
+    #           :levels    - The configuration of logging levels to the
+    #                        class/module level.
+    #           :logger    - The Logger messages are sent to. It will have its
+    #                        formatter changed to delegate entirely to the
+    #                        appender's formatter and its level set to debug so
+    #                        that it does not filter out any messages it is
+    #                        sent.
+    # block  - Optional block that can be used to customize the appender. The
+    #          appender itself is passed to the block.
+    #
+    # Once the values from the options Hash have been applied and any
+    # modifications are made within the block the appender should have its
+    # levels, logger, and formatter set.
+    #
+    def initialize(options = {})
+      @formatter = options[:formatter]
+      @logger = options[:logger]
+      @levels = options[:levels] || {}
+
+      yield self if block_given?
+
+      @logger.level = ::Logger::DEBUG
+      @logger.formatter = proc do |severity, datetime, progname, msg|
+        "#{msg}\n"
+      end
+    end
+
+    # Internal: Adds a message to the appender if the appender is configured to
+    # log messages at the given level for the given context.
+    #
+    # level   - The level of the message.
+    # context - The context of the message.
+    # message - The message to add to the appender if it is configured to log
+    #           messages at the given level for the given context.
+    #
+    # Returns nothing.
+    #
+    def add(level, context, message)
+      return unless enabled? level, context
+      @logger.send level, @formatter.format(level, context, message)
+    end
+
+  end
+
+end
+

data/lib/hatchet/message.rb

@@ -0,0 +1,39 @@
+# -*- encoding: utf-8 -*-
+
+module Hatchet
+
+  # Internal: Class for wrapping message strings and blocks in a way that means
+  # they can be treated identically.
+  #
+  # Blocks will be lazily evaluated once for all appenders when required.
+  #
+  class Message
+
+    # Internal: Creates a new message.
+    #
+    # message - An already evaluated message, usually a String (default: nil).
+    # block   - An optional block which will provide a message when invoked.
+    #
+    # One of message or block must be provided. If both are provided then the
+    # block is preferred as it is assumed to provide more detail.
+    #
+    # Examples
+    #
+    #   Message.new "Evaluated message"
+    #   Message.new { "Lazily evaluated message" }
+    #
+    def initialize(message = nil, &block)
+      @block = block
+      @message = message unless @block
+    end
+
+    # Internal: Returns the String representation of the message.
+    #
+    def to_s
+      @message ||= @block.call
+    end
+
+  end
+
+end
+

data/lib/hatchet/standard_formatter.rb

@@ -0,0 +1,43 @@
+# -*- encoding: utf-8 -*-
+
+module Hatchet
+
+  # Public: Standard formatter class.
+  #
+  class StandardFormatter
+
+    # Public: Returns the formatted message.
+    #
+    # level   - The severity of the log message.
+    # context - The context of the log message.
+    # message - The message provided by the log caller.
+    #
+    # Returns the context and message separated by a hypen.
+    #
+    def format(level, context, message)
+      "#{timestamp} [#{thread_name}] #{level.to_s.upcase.ljust 5} #{message}"
+    end
+
+    private
+
+    # Private: Returns the current time as a String.
+    #
+    def timestamp
+      Time.now.strftime('%Y-%m-%d %H:%M:%S.%L')
+    end
+
+    # Private: Returns the name of the current thread from the processes pid and
+    # the threads object_id when it is not the main thread for the process.
+    #
+    def thread_name
+      if Thread.current == Thread.main
+        Process.pid
+      else
+        "#{Process.pid}##{Thread.current.object_id}"
+      end
+    end
+
+  end
+
+end
+

data/lib/hatchet/version.rb

@@ -1,3 +1,9 @@
+# -*- encoding: utf-8 -*-
+
 module Hatchet
-  VERSION = "0.0.1"
+
+  # Public: The version of Hatchet.
+  #
+  VERSION = "0.0.2"
+
 end

data/lib/hatchet.rb

@@ -1,22 +1,119 @@
+# -*- encoding: utf-8 -*-
+
+require_relative 'hatchet/level_manager'
+require_relative 'hatchet/configuration'
+require_relative 'hatchet/logger'
+require_relative 'hatchet/logger_appender'
+require_relative 'hatchet/message'
+require_relative 'hatchet/standard_formatter'
 require_relative 'hatchet/version'
 
+# Public: Hatchet is a library for providing logging facilities whose levels are
+# configurable to the class and module level.
+#
+# It also provides the facility to have several appenders added to from a single
+# log call with each appender capable of being configured to log at different
+# levels.
+#
+# Hatchet provides no logging implementations of its own. Instead it delegates
+# to the standard Logger within the reference LoggerAppender implementation.
+#
 module Hatchet
 
+  # Public: Returns a Logger for the object.
+  #
+  # The returned logger has 5 methods. Those are, in decreasing order of
+  # severity:
+  #
+  #  * fatal
+  #  * error
+  #  * warn
+  #  * info
+  #  * debug
+  #
+  # All the methods have the same signature. You can either provide a message as
+  # a direct string, or as a block to the method is lazily evaluated (this is
+  # the recommended option).
+  #
+  # Examples
+  #
+  #   logger.info "Informational message"
+  #   logger.info { "Informational message #{potentially_expensive}" }
+  #
+  # Log messages are sent to appender where they will be filtered and invoked as
+  # configured.
+  #
+  # Returns a Logger for the object.
+  #
   def logger
     @_hatchet_logger ||= Logger.new self, Hatchet.appenders
   end
 
+  # Public: Returns a logger for the object.
+  #
+  # The returned logger has 5 methods. Those are, in decreasing order of
+  # severity:
+  #
+  #  * fatal
+  #  * error
+  #  * warn
+  #  * info
+  #  * debug
+  #
+  # All the methods have the same signature. You can either provide a message as
+  # a direct string, or as a block to the method is lazily evaluated (this is
+  # the recommended option).
+  #
+  # Examples
+  #
+  #   log.info "Informational message"
+  #   log.info { "Informational message #{potentially_expensive}" }
+  #
+  # Log messages are sent to appender where they will be filtered and invoked as
+  # configured.
+  #
+  # Returns a Logger for the object.
+  #
   alias_method :log, :logger
 
+  # Public: Method for configuring Hatchet.
+  #
+  # block - Mandatory block which receives a Configuration object that can be
+  #         used to setup Hatchet.
+  #
+  # Once the block returns each of the configured appenders has its formatter
+  # set as a StandardFormatter if one is not already set, and its levels Hash is
+  # set to the shared levels Hash if an explicit one has not been provided.
+  #
+  # Example
+  #
+  #   Hatchet.configure do |config|
+  #     # Set the level to use unless overridden (defaults to :info)
+  #     config.level :info
+  #     # Set the level for a specific class/module and its children (can be a
+  #     # string)
+  #     config.level :debug, Namespace::Something::Nested
+  #
+  #     # Add as many appenders as you like, Hatchet comes with one that formats
+  #     # the standard logger in the TTCC style of log4j.
+  #     config.appenders << Hatchet::LoggerAppender.new do |appender|
+  #       # Set the logger that this is wrapping (required)
+  #       appender.logger = Logger.new('log/test.log')
+  #     end
+  #   end
+  #
+  # Returns nothing.
   def self.configure
     @@config = Configuration.new
     yield @@config
     @@config.appenders.each do |appender|
       appender.formatter ||= StandardFormatter.new
-      appender.levels    ||= @@config.levels
+      appender.levels = @@config.levels if appender.levels.empty?
     end
   end
 
+  # Internal: Returns the Array of configured appenders.
+  #
   def self.appenders
     if @@config and @@config.appenders
       @@config.appenders
@@ -25,121 +122,5 @@ module Hatchet
     end
   end
 
-  class LoggerAppender
-
-    LEVELS = [:trace, :debug, :info, :warn, :error, :fatal, :off]
-
-    attr_accessor :levels
-
-    attr_accessor :logger
-
-    attr_accessor :formatter
-
-    def initialize(args = {})
-      @logger = args[:logger]
-      @formatter = args[:formatter]
-      yield self
-      @logger.formatter = proc do |severity, datetime, progname, msg|
-        "#{timestamp} [#{thread_name}] #{severity.ljust 5} #{msg}\n"
-      end
-    end
-
-    def add(level, context, msg)
-      return unless enabled? context, level
-      @logger.send level, @formatter.format(context, msg)
-    end
-
-    def enabled?(context, level)
-      unless self.levels.key? context
-        lvl = self.levels[nil]
-        root = []
-        context.to_s.split('::').each do |part|
-          root << part
-          path = root.join '::'
-          lvl = self.levels[path] if self.levels.key? path
-        end
-        self.levels[context] = lvl
-      end
-      LEVELS.index(level) >= LEVELS.index(self.levels[context])
-    end
-
-    private
-
-    def timestamp
-      Time.now.strftime('%Y-%m-%d %H:%M:%S.%L')
-    end
-
-    def thread_name
-      if Thread.current == Thread.main
-        Process.pid
-      else
-        "#{Process.pid}##{Thread.current.object_id}"
-      end
-    end
-
-  end
-
-  class StandardFormatter
-
-    def format(context, msg)
-      "#{context} - #{msg.call}"
-    end
-
-  end
-
-  class Configuration
-
-    attr_reader :levels
-
-    attr_reader :appenders
-
-    def initialize
-      @levels = {}
-      @levels[nil] = :info
-      @appenders = []
-      yield self if block_given?
-    end
-
-    def level(level, context = nil)
-      context = context.to_s unless context.nil?
-      @levels[context] = level
-    end
-
-  end
-
-  class Logger
-
-    def initialize(host, appenders)
-      @context = context host
-      @appenders = appenders
-    end
-
-    [:trace, :debug, :info, :warn, :error, :fatal].reverse.each do |level|
-      define_method level do |*args, &block|
-        msg = args[0]
-        block = Proc.new { msg } unless msg.nil? or block
-        return if block.nil?
-        add level, block
-      end
-    end
-
-    private
-
-    def add(level, msg)
-      @appenders.each { |appender| appender.add(level, @context, msg) }
-    end
-
-    def context(host)
-      if host.inspect == 'main'
-        'main'
-      elsif host.class == Module
-        host
-      else
-        host.class
-      end
-    end
-
-  end
-
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hatchet
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -19,6 +19,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/hatchet/configuration.rb
+- lib/hatchet/level_manager.rb
+- lib/hatchet/logger.rb
+- lib/hatchet/logger_appender.rb
+- lib/hatchet/message.rb
+- lib/hatchet/standard_formatter.rb
 - lib/hatchet/version.rb
 - lib/hatchet.rb
 - test/experiment.rb
@@ -37,7 +43,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2996924827001664983
+      hash: -2622354468754209643
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -46,7 +52,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2996924827001664983
+      hash: -2622354468754209643
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24