catamaran 0.2.0 → 0.3.0

data/README.md

@@ -6,7 +6,7 @@ I think logging is a powerful and often undervalued tool in software development
 Gemfile
 -------
 
-    gem 'catamaran', :git => 'git://github.com/jgithub/catamaran.git'
+    gem 'catamaran', '~> 0.2.0'
 
 Rails-related setup:
 
@@ -14,11 +14,56 @@ Rails-related setup:
 
 Now modify `development.rb` as needed
 
-Quickstart coding
------------------
+Ruby Quickstart
+-------------------------------
+    Catamaran::Manager.stderr = true
+    Catamaran::LogLevel.default_log_level = Catamaran::LogLevel::DEBUG 
+    Catamaran::Manager.formatter_class = Catamaran::Formatter::NoCallerFormatter
 
-    class WelcomeController < ApplicationController
-      LOGGER = CatLogger.MyCompany.MyAppName.App.Controller.WelcomeController
+    class FirstRubyDemo
+      LOGGER = Catamaran.logger( "FirstRubyDemo" )
+
+      def run
+        LOGGER.debug( "Note that DEBUG messages are getting logged" ) if LOGGER.debug?
+        LOGGER.trace( "Note that TRACE messages are NOT getting logged" ) if LOGGER.trace?
+      end
+    end
+
+    class SecondRubyDemo
+      LOGGER = Catamaran.logger( { :class => name(), :file => __FILE__ } )
+
+      def run
+        LOGGER.debug( "Sample DEBUG statement", { :line => __LINE__, :method => 'run'} ) if LOGGER.debug?
+      end
+    end 
+
+    class ThirdRubyDemo
+      LOGGER = Catamaran.logger( "com.mycompany.ThirdRubyDemo", { :class => name(), :file => __FILE__ } )
+
+      def run
+        LOGGER.debug( "Sample DEBUG statement", { :line => __LINE__, :method => 'run'} ) if LOGGER.debug?
+      end
+    end   
+
+
+    puts "Catamaran VERSION = #{Catamaran::VERSION}"
+    FirstRubyDemo.new.run
+    SecondRubyDemo.new.run
+    ThirdRubyDemo.new.run
+
+And the output
+
+     Catamaran VERSION = 0.3.0
+     DEBUG pid-2729 [2013-12-23 19:35:35:732]                                   FirstRubyDemo - Note that DEBUG messages are getting logged
+     DEBUG pid-2729 [2013-12-23 19:35:35:732]                                                 - Sample DEBUG statement (catmaran_ruby_demos.rb:21:in `SecondRubyDemo.run')
+     DEBUG pid-2729 [2013-12-23 19:35:35:732]                     com.mycompany.ThirdRubyDemo - Sample DEBUG statement (catmaran_ruby_demos.rb:29:in `ThirdRubyDemo.run')
+
+
+Rails Quickstart
+--------------------------------
+
+    class PagesController < ApplicationController
+      LOGGER = Catamaran.logger.com.mycompany.myrailsapp.app.controllers.PagesController
 
       def index
         # LOGGER.io methods are reserved for logs related to entering and returning from methods
@@ -36,9 +81,10 @@ Quickstart coding
 
 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`)
+### Sample log entry (in your development.log file)
+    IO pid-86000 [2013-12-17 17:26:39:176] pany.myrailsapp.app.controllers.PagesController - Entering with params = {"controller"=>"pages", "action"=>"index"} (`/myrailsapp/app/controllers/pages_controller.rb:7`:in `index`)
+
+
 
 Inspiration
 -----------

data/lib/catamaran/formatter/base_formatter.rb

@@ -0,0 +1,68 @@
+module Catamaran
+  module Formatter
+    ##
+    # Construct a properly formatted log message based
+
+    class BaseFormatter
+      def self.base_construct_formatted_message( log_level, path, msg, opts )
+        # Truncate on the left
+        if path.length > 47
+          updated_path = path.dup[-47,47]
+        else
+          updated_path = path
+        end
+
+        # TODO:  Abstract out the logger so that it's easy to use different formats
+        # Implicit return
+        retval = sprintf( "%6s pid-#{Process.pid} [#{Time.now.strftime( "%G-%m-%d %H:%M:%S:%L" )}] %47s - #{msg}", LogLevel.to_s(log_level), updated_path  )
+      end
+
+
+      def self.contruct_suffix_info( opts )
+        msg = ''
+
+        if opts
+          if opts[:file]
+            msg << "(#{opts[:file]}"
+
+            if opts[:line]
+              msg << ":#{opts[:line]}"
+            end
+
+            if opts[:class] || opts[:method]
+              msg << ":in `"
+            
+              msg << construct_class_method_info( opts )
+
+              msg << "'"
+            end
+
+            msg << ')'
+          end
+        end
+
+        # Implicit return
+        msg        
+      end
+
+
+      def self.construct_class_method_info( opts )
+        msg = ''
+        if opts
+          if opts[:class] || opts[:method]
+            if opts[:class] 
+              msg << "#{opts[:class]}."
+            end
+
+            msg << "#{opts[:method]}" if opts[:method]
+          end
+        end
+
+        # Implicit Return
+        msg
+      end
+
+    end
+  end
+end
+      

data/lib/catamaran/formatter/caller_formatter.rb

@@ -3,29 +3,9 @@ module Catamaran
     ##
     # Construct a properly formatted log message based
 
-    class CallerFormatter
+    class CallerFormatter < BaseFormatter
       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  )
+        "#{base_construct_formatted_message( log_level, path, msg, opts )} (#{caller(3)[0]})"
       end
     end
   end

data/lib/catamaran/formatter/no_caller_formatter.rb

@@ -3,28 +3,14 @@ module Catamaran
     ##
     # 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]
+    class NoCallerFormatter < BaseFormatter
+      def self.construct_formatted_message( log_level, path, msg, opts )        
+        suffix_info = contruct_suffix_info( opts )
+        if suffix_info && suffix_info.length > 0 
+          base_construct_formatted_message( log_level, path, msg, opts ) + ' ' + suffix_info
         else
-          updated_path = path
+          base_construct_formatted_message( log_level, path, msg, opts )
         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

data/lib/catamaran/logger.rb

@@ -3,6 +3,8 @@ module Catamaran
     attr_accessor :name
     attr_accessor :path
     attr_reader :parent
+    attr_reader :specified_file
+    attr_reader :specified_class
 
     ## 
     # The getter associated with retrieving the current log level for this logger.
@@ -190,8 +192,13 @@ module Catamaran
     ##
     # Usually get_logger is a reference to self, unless a path has been specified as a parameter
 
-    def get_logger( path = nil )
+    def get_logger( *args )        
       current_logger = self
+
+      path, opts = determine_path_and_opts_arguments( *args )
+      Catamaran.debugging( "Catamaran::Logger#get_logger() - path = '#{path}'  opts = #{opts} from args = #{args}" ) if Catamaran.debugging?        
+
+        
       if path
         method_names = path.split(/\./)
 
@@ -200,6 +207,16 @@ module Catamaran
         end
       end
 
+      if opts
+        if opts[:file]
+          current_logger.instance_variable_set( :@specified_file, opts[:file] )
+        end
+
+        if opts[:class]
+          current_logger.instance_variable_set( :@specified_class, opts[:class] )
+        end
+      end
+
       # Implicit return
       current_logger
     end
@@ -247,7 +264,7 @@ module Catamaran
       _path = self.path
       if _path
         # Implicit return
-        _path.join( delimiter )
+        _path.join( Catamaran::Manager.delimiter )
       else
         # Implicit return
         nil
@@ -294,6 +311,38 @@ module Catamaran
       "#<#{self.class}:0x#{object_id.to_s(16)}>[name=#{self.name},path=#{path_to_s},depth=#{self.depth},log_level=#{@log_level}]"
     end
 
+    protected
+
+    def determine_path_and_opts_arguments( *args )
+      Catamaran.debugging( "Catamaran::Logger#reset() - Entering with args = #{args}" )  if Catamaran.debugging?
+
+      if ( args.length == 0 )
+        opts = nil
+        path = nil
+      elsif ( args.length == 1 )
+        argument1 = args[0]
+
+        if ( argument1.nil? )
+          path = nil
+          opts = nil
+        elsif ( argument1.kind_of?( String ) )
+          path = argument1
+          opts = nil
+        elsif ( argument1.kind_of?( Hash ) )
+          path = nil
+          opts = argument1
+        else
+          raise ArgumentError.new "Unsupported argument type"
+        end
+      elsif ( args.length == 2 )
+        path, opts = *args
+      else
+        raise ArgumentError.new "Unexpected number of arguments: #{args.length}"
+      end 
+
+      [ path, opts ]
+    end   
+
     private
 
     ##
@@ -330,6 +379,12 @@ module Catamaran
     # All log statements eventually call _write_to_log
 
     def _write_to_log( log_level, msg, opts )
+      if self.specified_file || self.specified_class
+        opts = {} unless opts
+        opts[:file] = self.specified_file if self.specified_file
+        opts[:class] = self.specified_class if self.specified_class
+      end
+
       formatted_msg = Manager.formatter_class.construct_formatted_message( log_level, self.path_to_s(), msg, opts )
       Outputter.write( formatted_msg )
     end
@@ -355,12 +410,5 @@ module Catamaran
       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

@@ -18,9 +18,22 @@ module Catamaran
       def formatter_class=( value )
         @formatter_class = value
       end
+
+      ##
+      # The default delimiter
+      #
+      def delimiter
+        @delimiter || '.' 
+      end      
+
+      def delimiter=( value )
+        @delimiter = value
+      end
     end
 
 
+
+
     ##
     # Used to reset Catamaran
 

data/lib/catamaran/version.rb

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

data/lib/catamaran.rb

@@ -1,5 +1,6 @@
 require 'catamaran/logger'
 require 'catamaran/manager'
+require 'catamaran/formatter/base_formatter'
 require 'catamaran/formatter/caller_formatter'
 require 'catamaran/formatter/no_caller_formatter'
 require 'catamaran/outputter'
@@ -22,8 +23,9 @@ module Catamaran
     @debugging = value
   end  
 
-  def self.logger( optional_string = nil )
-    Catamaran::Manager.root_logger().get_logger( optional_string )
+  def self.logger( *args )
+    Catamaran.debugging( "Catamaran.logger() - Entering with args = #{args}" ) if Catamaran.debugging?        
+    Catamaran::Manager.root_logger().get_logger( *args )
   end
 
   ##

data/spec/catamaran_spec.rb

@@ -13,8 +13,17 @@ describe Catamaran do
     Catamaran.logger.object_id.should == Catamaran.logger.object_id
   end
 
+  context "when working with a blank path" do
+    it "should reuse the same root logger instance" do
+      Catamaran.logger( '' ).object_id.should == Catamaran.logger.object_id
+    end
+  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
+  end  
+
+  it "should reuse the same logger instance when contextually the same regardless of if the logger was determined by a string or by sequential method calls" do
     Catamaran.logger( "Company.Product.App.Model.User" ).object_id.should == Catamaran.logger.Company.Product.App.Model.User.object_id        
   end  
 
@@ -169,6 +178,20 @@ describe Catamaran do
       Catamaran.logger.debug( "Testing a DEBUG log" )
     end
 
+    describe "#determine_path_and_opts_arguments" do
+      it "should return the correct path when one string parameter is specified" do
+        Catamaran.logger.send( :determine_path_and_opts_arguments, "Company.Product.App.Model.User" ).should == [ "Company.Product.App.Model.User", nil ]
+      end
+
+      it "should return the correct opts when one hash parameter is specified" do
+        Catamaran.logger.send( :determine_path_and_opts_arguments, {} ).should == [ nil, {} ]
+      end      
+
+      it "should return the correct path and opts when two parameters are specified" do
+        Catamaran.logger.send( :determine_path_and_opts_arguments, "Company.Product.App.Model.User", {} ).should == [ "Company.Product.App.Model.User", {} ]
+      end      
+    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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: catamaran
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Jeano
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-12-20 00:00:00 -06:00
+date: 2013-12-23 00:00:00 -06:00
 default_executable: 
 dependencies: []
 
@@ -28,6 +28,7 @@ files:
 - catamaran.gemspec
 - init.rb
 - lib/catamaran.rb
+- lib/catamaran/formatter/base_formatter.rb
 - lib/catamaran/formatter/caller_formatter.rb
 - lib/catamaran/formatter/no_caller_formatter.rb
 - lib/catamaran/integration/rails.rb