catamaran 0.2.0

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/

data/README.md

@@ -0,0 +1,67 @@
+Catamaran
+=========
+
+I think logging is a powerful and often undervalued tool in software development.  When done right, it's a great way to document code, and it provides a simple & effective way to solve problems when things go awry.  All an important part of maintainable code.
+
+Gemfile
+-------
+
+    gem 'catamaran', :git => 'git://github.com/jgithub/catamaran.git'
+
+Rails-related setup:
+
+    rails g catamaran:install
+
+Now modify `development.rb` as needed
+
+Quickstart coding
+-----------------
+
+    class WelcomeController < ApplicationController
+      LOGGER = CatLogger.MyCompany.MyAppName.App.Controller.WelcomeController
+
+      def index
+        # LOGGER.io methods are reserved for logs related to entering and returning from methods
+        LOGGER.io "Entering with params = #{params}" if LOGGER.io?
+
+        LOGGER.trace "This is my TRACE log" if LOGGER.trace?
+        LOGGER.debug "This is my DEBUG log" if LOGGER.debug?
+        LOGGER.info "This is my INFO log" if LOGGER.info?
+        LOGGER.warn "This is my WARN log" if LOGGER.warn?
+        LOGGER.error "This is my ERROR log" if LOGGER.error?
+
+        LOGGER.io "Returning" if LOGGER.io?        
+      end
+    end
+
+Load the `index` page and check out your `development.log` file
+
+Sample log entry (in your development.log file)
+-----------------------------------------------
+    IO pid-86000 [2013-12-17 17:26:39:176] MyAppName.App.Controller.WelcomeController - Entering with params = {"controller"=>"welcome", "action"=>"index"} (`/my_rails_project/app/controllers/welcome_controller.rb:7`:in `index`)
+
+Inspiration
+-----------
+I'm looking for a logging utility that:
+
+* records granular timestamps with each log entry
+* records the process ID with each log entry
+* captures from where each log entry was generated
+* works equally well with classes that do and do *not* extend Rails base classes
+* supports the TRACE log level (or other log level less critical than DEBUG). 
+* is capable of capturing logs at different log level thresholds from different parts of the app simultaneously
+* readily works with Rails
+
+Ideas around what's next
+------------------------
+
+* Make it easier to change the formatting pattern
+* Another iteration of improvements on logger.io
+* Consider capturing log messages beyond stderr, stdout, and local files
+* Ongoing performance considerations
+* Something like `filter_parameter_logging`
+* Optional backtrace support for certain logs
+* Color support
+
+
+

data/catamaran.gemspec

@@ -0,0 +1,14 @@
+require File.dirname(__FILE__) + "/lib/catamaran/version"
+
+Gem::Specification.new do |s|
+  s.name             = "catamaran"
+  s.version          = Catamaran::VERSION
+  s.authors          = ["Jeano"]
+  s.email            = ["catamaran@jeano.net"]
+  s.summary          = "Catamaran Logger"
+  s.description      = "A logging utility"
+  s.homepage         = "http://github.com/jgithub/catamaran"
+  s.files            = `git ls-files`.split("\n")
+end
+
+

data/init.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + '/lib/catamaran'

data/lib/catamaran/formatter/caller_formatter.rb

@@ -0,0 +1,33 @@
+module Catamaran
+  module Formatter
+    ##
+    # Construct a properly formatted log message based
+
+    class CallerFormatter
+      def self.construct_formatted_message( log_level, path, msg, opts )
+        
+        ##
+        # If the client has specified a __FILE__ or a __LINE__ in the log opts, make use of them
+
+        if opts 
+          if opts[:file] && opts[:line]
+            path = path + " (#{opts[:file]}:#{opts[:line]})" 
+          end
+        end
+
+        # Truncate on the left
+        if path.length > 42
+          updated_path = path.dup[-42,42]
+        else
+          updated_path = path
+        end
+
+        # Making use of the caller here is slow.   
+        # TODO:  Abstract out the logger so that it's easy to use different formats
+        # Implicit return
+        sprintf( "%6s pid-#{Process.pid} [#{Time.now.strftime( "%G-%m-%d %H:%M:%S:%L" )}] %42s - #{msg} (#{caller(3)[0]})", LogLevel.to_s(log_level), updated_path  )
+      end
+    end
+  end
+end
+      

data/lib/catamaran/formatter/no_caller_formatter.rb

@@ -0,0 +1,32 @@
+module Catamaran
+  module Formatter
+    ##
+    # Construct a properly formatted log message based
+
+    class NoCallerFormatter
+      def self.construct_formatted_message( log_level, path, msg, opts )
+        
+        ##
+        # If the client has specified a __FILE__ or a __LINE__ in the log opts, make use of them
+
+        if opts 
+          if opts[:file] && opts[:line]
+            path = path + " (#{opts[:file]}:#{opts[:line]})" 
+          end
+        end
+
+        # Truncate on the left
+        if path.length > 42
+          updated_path = path.dup[-42,42]
+        else
+          updated_path = path
+        end
+
+        # TODO:  Abstract out the logger so that it's easy to use different formats
+        # Implicit return
+        sprintf( "%6s pid-#{Process.pid} [#{Time.now.strftime( "%G-%m-%d %H:%M:%S:%L" )}] %42s - #{msg}", LogLevel.to_s(log_level), updated_path  )
+      end
+    end
+  end
+end
+      

data/lib/catamaran/integration/rails.rb

@@ -0,0 +1,24 @@
+##
+# Ties Rails to Catamaran
+
+module Catamaran
+  module Integration
+    module Rails3
+      if defined?( Rails::Railtie )
+        class Railtie < Rails::Railtie
+          initializer :load_base_catamaran do
+            initializer = Rails.root.join( "config", "initializers", "catamaran.rb" )
+            require initializer if File.exist?( initializer )
+
+            Catamaran::Manager.add_output_file(  Catamaran::OutputFile.new( Rails.root.join( "log", "#{Rails.env}.log" ) ) )
+          end
+
+          initializer :load_environment_specific_catamaran do
+            initializer = Rails.root.join( "config", "initializers", "catamaran", "#{Rails.env}.rb" )
+            require initializer if File.exist?( initializer )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/catamaran/log_level.rb

@@ -0,0 +1,73 @@
+module Catamaran
+  class LogLevel
+    TRACE = 1000 
+    DEBUG = 2000
+    INFO = 3000
+    WARN = 4000
+    ERROR = 5000
+    SEVERE = 6000
+    FATAL = 7000
+
+    # By default, logger.io messages will be captured when the log level is DEBUG (IO_LESS_CRITICAL_THAN_INFO)
+    # If that's too verbose, the level can be changed to IO_LESS_CRITICAL_THAN_DEBUG and logger.io messages won't be
+    # visible unless the log level is set to TRACE.  
+    # See development.rb for an example of this
+    IO_LESS_CRITICAL_THAN_DEBUG = 1080
+    IO_LESS_CRITICAL_THAN_INFO = 2080
+
+    IO = IO_LESS_CRITICAL_THAN_INFO
+
+    def self.reset
+      @@default_log_level = INFO
+
+      self.send( :remove_const, 'IO' ) if self.const_defined?( 'IO' )
+      self.const_set( 'IO', IO_LESS_CRITICAL_THAN_INFO )      
+    end
+
+    self.reset()
+    
+
+    def self.to_s( log_level )
+      case log_level
+      when TRACE
+        retval = 'TRACE'
+      when DEBUG
+        retval = 'DEBUG'
+      when INFO
+        retval = 'INFO'
+      when WARN
+        retval = 'WARN'
+      when ERROR
+        retval =  'ERROR'
+      when SEVERE
+        retval =  'SEVERE'
+      when FATAL
+        retval =  'FATAL'
+      when IO_LESS_CRITICAL_THAN_INFO
+        retval =  'IO'
+      when IO_LESS_CRITICAL_THAN_DEBUG
+        retval =  'IO'
+      end
+
+      retval
+    end
+
+    def self.default_log_level
+      @@default_log_level
+    end    
+
+    def self.default_log_level=( value )
+      Catamaran.debugging( "Catamaran::LogLevel#default_log_level=() - Switching the default log level to #{value}" ) if Catamaran.debugging?            
+      @@default_log_level = value
+    end
+
+    def self.log_level_io=( value )
+      self.send( :remove_const, 'IO' ) if self.const_defined?( 'IO' )
+      self.const_set( 'IO', value )
+    end
+
+    def self.log_level_io
+      IO
+    end    
+  end
+end

data/lib/catamaran/logger.rb

@@ -0,0 +1,366 @@
+module Catamaran
+  class Logger
+    attr_accessor :name
+    attr_accessor :path
+    attr_reader :parent
+
+    ## 
+    # The getter associated with retrieving the current log level for this logger.
+    # Similar is the smart_log_level getter
+
+    def log_level( opts = {} )
+      if instance_variable_defined?( :@log_level ) && @log_level
+        retval = @log_level
+      elsif self.parent.nil?
+        # No parent means this logger(self) is the root logger.  So use the default log level
+        retval = Catamaran::LogLevel.default_log_level()
+      else
+        recursive = opts[:recursive]
+        if recursive == true 
+
+          # Remember the log level we found so we don't have to recursively look for it ever time
+          if !instance_variable_defined?( :@memoized_log_level ) || @memoized_log_level.nil?
+            @memoized_log_level = parent.log_level( opts ) if parent
+          end
+
+          retval = @memoized_log_level
+        else
+          Catamaran.debugging( "Catamaran::Logger#log_level() - non-recrusive request for log level.  And log level is nil.  This shouldn't happen too often." ) if Catamaran.debugging?        
+          retval = nil
+        end
+      end
+
+      # Implicit return
+      retval
+    end
+
+    ## 
+    # We usually want a logger to have a level.   The smart_log_level() reader determines a log level even if one isn't
+    # explicitly set on this logger instance by making use of recursion up to the root logger if needed
+
+    def smart_log_level
+      self.log_level( { :recursive => true } )
+    end
+
+    ##
+    # Setter used to explicitly set the log level for this logger
+
+    def log_level=( value )
+      @log_level = value
+      remove_instance_variable( :@memoized_log_level ) if instance_variable_defined?( :@memoized_log_level )      
+    end
+
+    ##
+    # Is trace-level logging currently enabled?
+
+    def trace?
+      if self.smart_log_level() <= LogLevel::TRACE
+        true
+      else
+        false
+      end
+    end
+
+    def trace( msg, opts = nil )
+      if trace?
+        _write_to_log( LogLevel::TRACE, msg, opts )
+      end
+    end
+
+    ##
+    # Is debug-level logging currently enabled?
+
+    def debug?
+      if self.smart_log_level() <= LogLevel::DEBUG
+        true
+      else
+        false
+      end
+    end
+
+    def debug( msg, opts = nil )
+      if debug?
+        _write_to_log( LogLevel::DEBUG, msg, opts )
+      end
+    end
+
+
+    ##
+    # Is io-level logging currently enabled?
+
+    def io?
+      if self.smart_log_level() <= LogLevel::IO
+        true
+      else
+        false
+      end
+    end
+
+    def io( msg, opts = nil )
+      if io?
+        _write_to_log( LogLevel::IO, msg, opts )
+      end
+    end
+
+    ##
+    # Is info-level logging currently enabled?
+
+    def info?
+      if self.smart_log_level() <= LogLevel::INFO
+        true
+      else
+        false
+      end
+    end
+
+    def info( msg, opts = nil )
+      if info?
+        _write_to_log( LogLevel::INFO, msg, opts )
+      end
+    end 
+
+    ##
+    # Is warn-level logging currently enabled?
+
+    def warn?
+      if self.smart_log_level() <= LogLevel::WARN
+        true
+      else
+        false
+      end
+    end
+
+    def warn( msg, opts = nil )
+      if warn?
+        _write_to_log( LogLevel::WARN, msg, opts )
+      end
+    end     
+
+    ##
+    # Is error-level logging currently enabled?
+
+    def error?
+      if self.smart_log_level() <= LogLevel::ERROR
+        true
+      else
+        false
+      end
+    end
+
+    def error( msg, opts = nil )
+      if error?
+        _write_to_log( LogLevel::ERROR, msg, opts )
+      end
+    end 
+
+    ##
+    # Is severe-level logging currently enabled?
+
+    def severe?
+      if self.smart_log_level() <= LogLevel::SEVERE
+        true
+      else
+        false
+      end
+    end
+
+    def severe( msg, opts = nil )
+      if severe?
+        _write_to_log( LogLevel::SEVERE, msg, opts )
+      end
+    end   
+
+    ##
+    # Is fatal-level logging currently enabled?
+
+    # def fatal?
+    #   if self.smart_log_level() <= LogLevel::FATAL
+    #     true
+    #   else
+    #     false
+    #   end
+    # end
+
+    # def fatal( msg, opts = nil )
+    #   if fatal?
+    #     _write_to_log( LogLevel::FATAL, msg, opts )
+    #   end
+    # end            
+
+    ##
+    # Usually get_logger is a reference to self, unless a path has been specified as a parameter
+
+    def get_logger( path = nil )
+      current_logger = self
+      if path
+        method_names = path.split(/\./)
+
+        method_names.each do |method_name|
+          current_logger = current_logger.send( method_name.to_sym ) 
+        end
+      end
+
+      # Implicit return
+      current_logger
+    end
+
+
+    ##
+    # method_missing provides a mechanism to create sub loggers.  
+    # Let's say I have a logger and I want to create a sub logger
+    #
+    #    root_logger = CatLogger
+    #    logger_reserved_for_app_stuff  = CatLogger.App   # App is a missing method
+    #    logger_reserved_just_for_controller_stuff = CatLogger.App.Controller  # Controller is a missing method
+
+
+    def method_missing( meth, *args, &block )
+      Catamaran.debugging( "Catamaran::Logger#method_missing() - meth = #{meth}" )            
+
+      if ( meth.to_sym == :define_method || meth.to_sym == :to_ary )
+        # Catamaran.debugging( "Catamaran::Logger#method_missing() - ERROR!  Ignoring method: #{meth}" ) 
+        _msg = "[CATAMARAN INTERNAL] Catamaran::Logger#method_missing() - ERROR!  Ignoring method: #{meth}"
+        $stderr.puts( _msg )
+        raise Exception.new _msg        
+      else
+        # Create a new logger object
+        logger_obj = Logger.new( meth.to_s, self.path, self )
+
+        # Keep track of this new sub-logger
+        @sub_loggers[meth.to_sym] = logger_obj
+
+        # Define a method so method_missing will not be called next time this method name is called
+        singleton = class << self; self end
+        singleton.send :define_method, meth.to_sym, lambda { 
+          @sub_loggers[meth.to_sym] 
+        } 
+      end
+
+      # Implicit return
+      logger_obj
+    end
+
+    ##
+    # Human-readable path
+
+    def path_to_s
+      _path = self.path
+      if _path
+        # Implicit return
+        _path.join( delimiter )
+      else
+        # Implicit return
+        nil
+      end
+    end
+
+    ##
+    # Forget any cached memoization log levels within this logger or within sub-loggers of this logger
+
+    def forget_memoizations
+      remove_instance_variable(:@memoized_log_level) if instance_variable_defined?( :@memoized_log_level )
+      @sub_loggers.values.each do |logger|
+        logger.forget_memoizations()
+      end
+    end
+
+
+    ##
+    # Number of loggers known about by this logger (including sub-loggers)
+
+    def num_loggers
+      retval = 1  # me!
+      @sub_loggers.values.each do |logger|
+        retval = retval + logger.num_loggers()
+      end
+
+      # Implicit return
+      Catamaran.debugging( "Catamaran::Logger#num_loggers() - Returning #{retval} from '#{path_to_s()}'" )  if Catamaran.debugging?                 
+
+      retval
+    end
+
+    def reset
+      _reset()
+      Catamaran.debugging( "Catamaran::Logger#reset() - Reset complete." )  if Catamaran.debugging?
+    end
+
+    def depth 
+      @depth
+    end
+
+    def to_s
+      # Implicit return
+      "#<#{self.class}:0x#{object_id.to_s(16)}>[name=#{self.name},path=#{path_to_s},depth=#{self.depth},log_level=#{@log_level}]"
+    end
+
+    private
+
+    ##
+    # I used to delete the root level logger, but now I reset it instead.  
+    # Among other reasons, the CatLogger constant now works
+
+    def _reset
+      remove_instance_variable(:@memoized_log_level) if instance_variable_defined?( :@memoized_log_level )      
+      remove_instance_variable(:@log_level) if instance_variable_defined?( :@log_level )      
+
+      self.name = @initialized_name
+      self.path = @initialized_path_so_far ? @initialized_path_so_far.dup : []
+
+      if @initialized_name && @initialized_name.length > 0  # Root logger has no name
+        self.path << @initialized_name
+      end
+
+      @parent = @initialized_parent
+
+      # @sub_loggers already exist, iterate through each and undefine the associated method missing
+      if @sub_loggers
+        @sub_loggers.keys.each do |method_name_as_symbol|
+          Catamaran.debugging( "Catamaran::Logger#_reset() - Attempting to remove dynamically created method: #{method_name_as_symbol}" )  if Catamaran.debugging?
+
+          singleton = class << self; self end
+          singleton.send :remove_method, method_name_as_symbol 
+        end
+      end
+
+      @sub_loggers = {}
+    end
+
+    ##
+    # All log statements eventually call _write_to_log
+
+    def _write_to_log( log_level, msg, opts )
+      formatted_msg = Manager.formatter_class.construct_formatted_message( log_level, self.path_to_s(), msg, opts )
+      Outputter.write( formatted_msg )
+    end
+
+    ##
+    # Initialize this logger.
+
+    def initialize( name, path_so_far, parent = nil )
+      Catamaran.debugging( "Catamaran::Logger#initialize() - Entering with name = #{name ? name : '<nil>'}, path_so_far = #{path_so_far}, parent = #{parent ? parent : '<nil>'}" )  if Catamaran.debugging?
+      
+      @initialized_name = name
+      @initialized_path_so_far = path_so_far ? path_so_far.dup : []
+      @initialized_parent = parent
+
+      if parent
+        @depth = parent.depth + 1
+      else
+        @depth = 0
+      end
+
+      _reset()
+
+      Catamaran.debugging( "Catamaran::Logger#initialize() - I am #{self.to_s}" )  if Catamaran.debugging?
+    end
+
+    ##
+    # The delimiter is a period
+
+    def delimiter
+      "."
+    end
+
+  end
+end 

data/lib/catamaran/manager.rb

@@ -0,0 +1,145 @@
+module Catamaran
+  class Manager
+    class << self; 
+      attr_accessor :_root_logger_instance; 
+      attr_accessor :_stdout_flag; 
+      attr_accessor :_stderr_flag;
+      attr_accessor :_output_files; 
+
+
+      ##
+      # Class that's going to be performing the message formatting
+
+      def formatter_class
+        # The NoCallerFormatter class is the default formatter.  
+        @formatter_class || Catamaran::Formatter::NoCallerFormatter
+      end
+
+      def formatter_class=( value )
+        @formatter_class = value
+      end
+    end
+
+
+    ##
+    # Used to reset Catamaran
+
+    def self.reset
+      Catamaran.debugging( "Catamaran::Manager#reset - Resetting Catamaran" ) if Catamaran.debugging?                  
+
+      # Old way.   I used to null-out the old logger.   But resetting it is better for using the CatLogger constant
+      # self.send( :_root_logger_instance=, nil )
+
+      # New way
+      root_logger = self.send( :_root_logger_instance )
+      root_logger.reset if root_logger
+
+      # Also reset the default log level
+      Catamaran::LogLevel::reset
+      
+      # Resetting Catamaran probably should not reset the output settings
+      # self.send( :_stdout_flag=, nil )
+      # self.send( :_stderr_flag=, nil )
+      # self.send( :_output_files=, nil )
+    end
+
+    ##
+    # Allow the client to access the root logger
+
+    def self.root_logger
+      logger = self.send( :_root_logger_instance )
+
+      unless logger
+        Catamaran.debugging( "Catamaran::Logger#root_logger() - Initializing new root logger" ) if Catamaran.debugging?                  
+
+        path_so_far = []
+        logger = Logger.new( nil, path_so_far )
+
+        self.send( :_root_logger_instance=, logger )
+
+        # Get the instance back as a double-confirm
+        logger = self.send( :_root_logger_instance )
+      end
+
+      if logger && logger.instance_of?( Catamaran::Logger ) 
+        Catamaran.debugging( "Catamaran::Logger#root_logger() - Returning #{logger}" ) if Catamaran.debugging?
+      else
+        Catamaran.debugging( "Catamaran::Logger#root_logger() - Error!  root logger is not an instance of Logger as would expect" ) if Catamaran.debugging?
+      end
+
+      logger
+    end
+
+    ##
+    # Specify a destination location for logs
+
+    def self.add_output_file( output_file )
+      unless self.send( :_output_files )
+        self.send( :_output_files=, [] )
+      end
+
+      self.send( :_output_files ).push( output_file )
+
+      Catamaran.debugging( "Catamaran::Logger#add_output_file() - Added output file: #{output_file}.   Number of _loggers is now #{self.send( :_output_files ).length}" ) if Catamaran.debugging?                 
+    end   
+
+    def self.output_files
+      self.send( :_output_files )
+    end 
+
+    ##
+    # Memoizations are used to cache log levels.  Used to clear out the memoization cache.
+
+    def self.forget_memoizations
+      self.root_logger().forget_memoizations()
+    end
+
+    ##
+    # How many loggers is Catamaran currently aware of
+
+    def self.num_loggers
+      self.root_logger().num_loggers()
+    end
+
+    ##
+    # Call this method with true if you'd like Catamaran to write logs to STDOUT
+
+    def self.stdout=( bool )
+      self.send( :_stdout_flag=, bool )
+    end
+
+    ##
+    # Is logging to STDOUT enabled?
+
+    def self.stdout?
+      if self.send( :_stdout_flag ) == true
+        true
+      else
+        false
+      end
+    end
+
+    ##
+    # Call this method with true if you'd like Catamaran to write logs to STDERR
+
+    def self.stderr=( bool )
+      self.send( :_stderr_flag=, bool )
+    end
+
+    ##
+    # Is logging to STDERR enabled?
+
+    def self.stderr?
+      if self.send( :_stderr_flag ) == true
+        true
+      else
+        false
+      end
+    end 
+
+    private_class_method :_root_logger_instance
+    private_class_method :_stdout_flag
+    private_class_method :_stderr_flag
+           
+  end
+end

data/lib/catamaran/output_file.rb

@@ -0,0 +1,18 @@
+module Catamaran
+  class OutputFile
+    attr_accessor :filename
+
+    def initialize( filename = nil ) 
+      self.filename = filename     
+    end     
+
+    def write( line )
+      unless @file_descriptor
+        @file_descriptor = File.open( self.filename, "a" )
+      end 
+
+      @file_descriptor.puts( line )
+      @file_descriptor.flush
+    end
+  end
+end

data/lib/catamaran/outputter.rb

@@ -0,0 +1,27 @@
+module Catamaran
+  class Outputter
+
+    ##
+    # Write the log message to the appropriate location.  Currently that could mean stdout, stderr, or output files.
+
+    def self.write( formatted_msg )
+      if Manager.stdout?
+        $stdout.puts( formatted_msg )
+      end
+
+      if Manager.stderr?
+        $stderr.puts( formatted_msg )
+      end 
+
+      _output_files = Manager._output_files
+      _output_files.each do |output_file|
+        begin
+          output_file.write( formatted_msg )
+        rescue Exception => e
+          $stderr.puts( "Catamaran is unable to write to logfile: #{output_file}" )
+        end
+      end if _output_files
+
+    end
+  end
+end

data/lib/catamaran/version.rb

@@ -0,0 +1,4 @@
+module Catamaran
+  VERSION = '0.2.0'
+end
+

data/lib/catamaran.rb

@@ -0,0 +1,54 @@
+require 'catamaran/logger'
+require 'catamaran/manager'
+require 'catamaran/formatter/caller_formatter'
+require 'catamaran/formatter/no_caller_formatter'
+require 'catamaran/outputter'
+require 'catamaran/output_file'
+
+require 'catamaran/log_level'
+require 'catamaran/version'
+
+
+module Catamaran
+  def self.debugging?
+    @debugging || false
+  end
+  
+  def self.debugging( msg )
+    $stderr.puts( "[CATAMARAN DEBUGGING] #{msg}" ) if self.debugging?
+  end
+
+  def self.debugging=( value )
+    @debugging = value
+  end  
+
+  def self.logger( optional_string = nil )
+    Catamaran::Manager.root_logger().get_logger( optional_string )
+  end
+
+  ##
+  # get_logger() is an alias for logger()
+  class << self
+    alias_method :get_logger, :logger
+  end
+
+  LOG_LEVEL_TRACE = LogLevel::TRACE 
+  LOG_LEVEL_DEBUG = LogLevel::DEBUG
+  LOG_LEVEL_INFO = LogLevel::INFO
+  LOG_LEVEL_WARN = LogLevel::WARN
+  LOG_LEVEL_ERROR = LogLevel::ERROR
+  LOG_LEVEL_SEVERE = LogLevel::SEVERE
+  LOG_LEVEL_FATAL = LogLevel::FATAL  
+end
+
+# add rails integration
+require('catamaran/integration/rails') if defined?(Rails)
+
+# Catamaran::Manager.stderr = true
+# Catamaran::Manager.stdout = false
+
+##
+# Define the CatLogger alias for the Catamaran root logger
+Kernel.send( :remove_const, 'CatLogger' ) if Kernel.const_defined?( 'CatLogger' )
+Kernel.const_set( 'CatLogger', Catamaran.logger )
+

data/lib/generators/catamaran/install_generator.rb

@@ -0,0 +1,21 @@
+module Catamaran  
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      desc "Generates a custom Catamaran initializer file."
+
+      def self.source_root
+        @_rails_config_source_root ||= File.expand_path("../templates", __FILE__
+)
+      end
+
+      def copy_initializer
+        template "catamaran.rb", "config/initializers/catamaran.rb"
+      end
+
+      def copy_settings
+        directory "catamaran", "config/initializers/catamaran" 
+      end
+
+    end
+  end
+end

data/lib/generators/catamaran/templates/catamaran/development.rb

@@ -0,0 +1,15 @@
+## 
+# Custom settings for Catamaran in development
+
+# Enable logging to STDERR
+Catamaran::Manager.stderr = true
+
+# The default log level is INFO.  Switch to DEBUG in development
+Catamaran::LogLevel.default_log_level = Catamaran::LogLevel::DEBUG
+
+# By default, logger.io messages will be captured when the log level is DEBUG (IO_LESS_CRITICAL_THAN_INFO)
+# If that's too verbose, uncomment this
+# Catamaran::LogLevel.log_level_io = Catamaran::LogLevel::IO_LESS_CRITICAL_THAN_DEBUG
+
+# The NoCallerFormatter is the default.  
+Catamaran::Manager.formatter_class = Catamaran::Formatter::CallerFormatter

data/lib/generators/catamaran/templates/catamaran/production.rb

@@ -0,0 +1,2 @@
+## 
+# Custom settings for Catamaran in production

data/lib/generators/catamaran/templates/catamaran/staging.rb

@@ -0,0 +1,2 @@
+## 
+# Custom settings for Catamaran in staging

data/lib/generators/catamaran/templates/catamaran/test.rb

@@ -0,0 +1,2 @@
+## 
+# Custom settings for Catamaran in test

data/lib/generators/catamaran/templates/catamaran.rb

@@ -0,0 +1,5 @@
+## 
+# Custom settings for Catamaran in all Rails environments
+
+# Catamaran::Manager.stderr = true
+# Catamaran::Manager.stdout = false

data/spec/catamaran_spec.rb

@@ -0,0 +1,191 @@
+require 'spec_helper'
+
+describe Catamaran do
+  it "should define TRACE" do
+    Catamaran::LogLevel::TRACE.should > 0
+  end
+
+  it "should have a version" do
+    Catamaran::VERSION.length.should > 0
+  end
+
+  it "should reuse the same root logger instance" do
+    Catamaran.logger.object_id.should == Catamaran.logger.object_id
+  end
+
+  it "should reuse the same logger instance when contextually the same" do
+    Catamaran.logger.Company.Product.App.Model.User.object_id.should == Catamaran.logger.Company.Product.App.Model.User.object_id
+    Catamaran.logger( "Company.Product.App.Model.User" ).object_id.should == Catamaran.logger.Company.Product.App.Model.User.object_id        
+  end  
+
+  it "should provide access to the root logger through CatLogger" do
+    CatLogger.object_id.should == Catamaran::Manager.root_logger.object_id
+    Catamaran.logger.object_id.should == CatLogger.object_id
+  end
+
+  it "should define Catamaran.logger and Catamaran.get_logger methods.  They should be equivalent." do
+    Catamaran.logger.object_id.should == Catamaran::get_logger.object_id
+  end
+
+  it "should provide access to loggers after a reset" do
+    logger = Catamaran.logger.Company.Product.App.Model.User
+    Catamaran::Manager.reset
+    logger = Catamaran.logger.Company.Product.App.Model.User
+    logger.should be_instance_of( Catamaran::Logger )
+  end
+
+  it "should create a new loggers for each point in the path" do
+    Catamaran.logger
+    Catamaran::Manager.num_loggers.should == 1
+    Catamaran.logger.Company.Product.App.Model.User
+    Catamaran::Manager.num_loggers.should == 6    
+  end     
+
+  it "should be possible for the user to modify the default log level" do
+    Catamaran::LogLevel.default_log_level = Catamaran::LogLevel::TRACE
+    Catamaran.logger.smart_log_level.should == Catamaran::LogLevel::TRACE
+  end
+
+  it "should not provide the same object ID for different paths" do
+    Catamaran.logger.A.C.object_id.should_not == Catamaran.logger.B.C
+    Catamaran.logger.A.C.object_id.should_not == Catamaran.logger.A.B
+  end  
+
+  context "by default" do
+    it "should log INFO messages" do
+      logger = Catamaran.logger.Company.Product.App.Model.User
+    end
+
+    it "should NOT log DEBUG messages" do
+      logger = Catamaran.logger.Company.Product.App.Model.User
+    end
+
+    it "should have an INFO log level set for the root logger" do
+      Catamaran.logger.log_level.should == Catamaran::LogLevel::INFO
+    end
+
+    it "should have an UNSET log level for any non-root loggers" do
+      Catamaran.logger.log_level = Catamaran::LogLevel::ERROR
+      Catamaran.logger.Test.log_level.should be_nil
+    end
+
+    it "should have one logger configured" do
+      Catamaran::Manager.num_loggers.should == 1
+    end
+
+    it "should be that the IO log level is the same as IO_LESS_CRITICAL_THAN_INFO" do
+      Catamaran::LogLevel::IO.should == Catamaran::LogLevel::IO_LESS_CRITICAL_THAN_INFO
+    end
+  end
+
+  context "when the log level is set to INFO" do
+    Catamaran.logger.log_level = Catamaran::LogLevel::INFO
+    Catamaran.logger.Company.Product.App.Model.User
+  end
+
+  context "after a reset" do
+    it "should have a default log level of INFO" do
+      logger = Catamaran.logger
+      logger.log_level.should == Catamaran::LogLevel::INFO
+      logger.log_level = Catamaran::LogLevel::ERROR
+      logger.log_level.should == Catamaran::LogLevel::ERROR
+      Catamaran::Manager.reset
+      logger.log_level.should == Catamaran::LogLevel::INFO      
+    end
+
+    it "should return the number of loggers to 1" do
+      Catamaran.logger
+      Catamaran::Manager.num_loggers.should == 1
+      Catamaran.logger.Company.Product.App.Model.User
+      Catamaran::Manager.num_loggers.should == 6 
+      Catamaran::Manager.reset
+      Catamaran::Manager.num_loggers.should == 1      
+    end
+
+    it "should have the same root logger object before and after the reset" do
+      before_logger = Catamaran.logger
+      Catamaran::Manager.reset
+      Catamaran.logger.object_id.should == before_logger.object_id        
+    end
+  end
+
+  describe Catamaran.logger do
+    it "should be able to inherit it's parent's log level" do
+      Catamaran.logger.log_level = Catamaran::LogLevel::ERROR
+      Catamaran.logger.Test.smart_log_level.should == Catamaran::LogLevel::ERROR
+    end  
+  end
+
+  describe Catamaran::Manager do
+    describe "#reset" do
+      it "should reset Catamaran" do
+        before_reset_logger = Catamaran.logger.Company.Product.App.Model.User
+        Catamaran.logger.num_loggers.should == 6
+        Catamaran::Manager.reset
+        Catamaran.logger.num_loggers.should == 1
+        after_reset_logger = Catamaran.logger.Company.Product.App.Model.User
+        before_reset_logger.object_id.should_not == after_reset_logger.object_id        
+      end
+    end
+
+     describe "#forget_memoizations" do
+      it "should forget all the memoized log levels" do
+        Catamaran.logger.log_level = Catamaran::LogLevel::ERROR
+        Catamaran.logger.Test.smart_log_level.should == Catamaran::LogLevel::ERROR   
+        Catamaran.logger.log_level = Catamaran::LogLevel::INFO   
+        Catamaran.logger.Test.smart_log_level.should == Catamaran::LogLevel::ERROR  
+        Catamaran.logger.forget_memoizations
+        Catamaran.logger.Test.smart_log_level.should == Catamaran::LogLevel::INFO  
+      end
+    end   
+  end
+
+  describe Catamaran::Logger do
+    it "should inherit the log level from the root logger as needed" do
+      Catamaran.logger.smart_log_level.should == Catamaran::LogLevel::INFO
+      Catamaran.logger.Company.Product.App.Model.User.log_level.should be_nil     
+      Catamaran.logger.Company.Product.App.Model.User.smart_log_level.should == Catamaran::LogLevel::INFO
+    end
+
+    it "should have a nil log_level unless explicitly set" do
+      Catamaran.logger.Company.Product.App.Model.User.log_level.should be_nil     
+    end
+
+    it "should always have a smart_log_level set" do
+      Catamaran.logger.Company.Product.App.Model.User.log_level.should be_nil           
+      Catamaran.logger.Company.Product.App.Model.User.smart_log_level.should_not be_nil
+    end    
+
+    it "should write the log if the log has sufficient weight" do
+      Catamaran.logger.smart_log_level.should == Catamaran::LogLevel::INFO
+      Catamaran.logger.should_receive( :_write_to_log ).once
+      Catamaran.logger.info( "Testing an INFO log" )
+    end
+
+    it "should NOT write the log if the log does NOT have sufficient" do
+      Catamaran.logger.smart_log_level.should == Catamaran::LogLevel::INFO
+      # DEBUG is disabled
+      Catamaran.logger.should_not_receive( :_write_to_log )
+      Catamaran.logger.debug( "Testing a DEBUG log" )
+    end
+
+    context "when using smart_log_level" do
+      it "should inherit the log level from a parent" do
+        Catamaran::LogLevel.default_log_level = Catamaran::LogLevel::INFO
+        Catamaran.logger.Company.Product.App.Model.log_level = Catamaran::LogLevel::ERROR
+        Catamaran.logger.Company.Product.App.Controller.log_level = Catamaran::LogLevel::WARN
+        Catamaran.logger.Company.Product.App.Model.User.smart_log_level.should == Catamaran::LogLevel::ERROR
+        Catamaran.logger.Company.Product.App.Controller.UsersController.smart_log_level.should == Catamaran::LogLevel::WARN
+        Catamaran.logger.Company.Product.App.smart_log_level.should == Catamaran::LogLevel::INFO
+      end
+    end
+
+    context "when the log level is specified, the default is no longer used" do
+      it "should be " do
+        Catamaran.logger.smart_log_level.should == Catamaran::LogLevel::INFO
+        Catamaran.logger.log_level = Catamaran::LogLevel::ERROR
+        Catamaran.logger.smart_log_level.should == Catamaran::LogLevel::ERROR
+      end
+    end
+  end    
+end

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+require 'catamaran'
+
+RSpec.configure do |config|
+  config.before(:suite) do
+  end
+ 
+  config.before(:each) do
+    Catamaran::Manager.reset
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification 
+name: catamaran
+version: !ruby/object:Gem::Version 
+  version: 0.2.0
+platform: ruby
+authors: 
+- Jeano
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2013-12-20 00:00:00 -06:00
+default_executable: 
+dependencies: []
+
+description: A logging utility
+email: 
+- catamaran@jeano.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- README.md
+- catamaran.gemspec
+- init.rb
+- lib/catamaran.rb
+- lib/catamaran/formatter/caller_formatter.rb
+- lib/catamaran/formatter/no_caller_formatter.rb
+- lib/catamaran/integration/rails.rb
+- lib/catamaran/log_level.rb
+- lib/catamaran/logger.rb
+- lib/catamaran/manager.rb
+- lib/catamaran/output_file.rb
+- lib/catamaran/outputter.rb
+- lib/catamaran/version.rb
+- lib/generators/catamaran/install_generator.rb
+- lib/generators/catamaran/templates/catamaran.rb
+- lib/generators/catamaran/templates/catamaran/development.rb
+- lib/generators/catamaran/templates/catamaran/production.rb
+- lib/generators/catamaran/templates/catamaran/staging.rb
+- lib/generators/catamaran/templates/catamaran/test.rb
+- spec/catamaran_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/jgithub/catamaran
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Catamaran Logger
+test_files: []
+