catamaran 2.1.0 → 2.2.0

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013
+
+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.

data/README.md

@@ -6,7 +6,7 @@ Logging is a powerful and often undervalued tool in software development.  When
 Gemfile
 -------
 
-    gem 'catamaran', '~> 2.1.0'
+    gem 'catamaran', '~> 2.2.0'
 
 Rails-related setup:
 
@@ -17,11 +17,12 @@ Now modify `config/initializers/catamaran/development.rb` as needed
 Ruby Quickstart
 ---------------
 ```ruby
+require 'catamaran'
 
-class WorkingWithCatamaran
-  LOGGER = Catamaran.logger( "com.mytld.WorkingWithCatamaran" )
+class QuickstartWithRuby
+  LOGGER = Catamaran.logger( "com.mytld.QuickstartWithRuby" )
   # or equivalently: 
-  # LOGGER = Catamaran.logger.com.mytld.WorkingWithCatamaran
+  # LOGGER = Catamaran.logger.com.mytld.QuickstartWithRuby
 
   def demonstrating_log_levels
     # Disabled by default
@@ -69,29 +70,29 @@ class WorkingWithCatamaran
   end
 end
 
-working_with_catamaran = WorkingWithCatamaran.new
-working_with_catamaran.demonstrating_log_levels
-working_with_catamaran.using_the_caller
-working_with_catamaran.changing_the_log_level
-working_with_catamaran.displaying_backtrace_information
+quickstart_with_ruby = QuickstartWithRuby.new
+quickstart_with_ruby.demonstrating_log_levels
+quickstart_with_ruby.using_the_caller
+quickstart_with_ruby.changing_the_log_level
+quickstart_with_ruby.displaying_backtrace_information
 ```
 
 And the output
 
 ```
-NOTICE pid-29665 [2014-01-05 08:30:24:213]                  com.mytld.WorkingWithCatamaran - NOTICE logs are captured by default
-  WARN pid-29665 [2014-01-05 08:30:24:213]                  com.mytld.WorkingWithCatamaran - WARN logs are captured by default
- ERROR pid-29665 [2014-01-05 08:30:24:213]                  com.mytld.WorkingWithCatamaran - ERROR logs are captured by default
-SEVERE pid-29665 [2014-01-05 08:30:24:213]                  com.mytld.WorkingWithCatamaran - SEVERE logs are captured by default
- FATAL pid-29665 [2014-01-05 08:30:24:213]                  com.mytld.WorkingWithCatamaran - FATAL logs are captured by default
-NOTICE pid-29665 [2014-01-05 08:30:24:213]                  com.mytld.WorkingWithCatamaran - The caller will append log location info to this message (working_with_catamaran.rb:27:in `using_the_caller')
-NOTICE pid-29665 [2014-01-05 08:30:24:213]                  com.mytld.WorkingWithCatamaran - If the user specifies the :file, :line, AND :method, the caller will NOT get invoked (working_with_catamaran.rb:28:in `run')
-NOTICE pid-29665 [2014-01-05 08:30:24:213]                  com.mytld.WorkingWithCatamaran - To prove the caller is not used, we can put dummy data in and see that it's being used instead (just_kidding.rb:123456789:in `whatever')
- DEBUG pid-29665 [2014-01-05 08:30:24:213]                  com.mytld.WorkingWithCatamaran - Now DEBUG messages should show up
-  WARN pid-29665 [2014-01-05 08:30:24:213]                  com.mytld.WorkingWithCatamaran - Sample WARN statement with backtrace requested
- ERROR pid-29665 [2014-01-05 08:30:24:213]                  com.mytld.WorkingWithCatamaran - Sample ERROR statement with backtrace requested from:
-working_with_catamaran.rb:51:in `displaying_backtrace_information'
-working_with_catamaran.rb:59:in `<main>'
+NOTICE pid-50247 [2014-01-07 13:22:28:516]                    com.mytld.QuickstartWithRuby - NOTICE logs are captured by default
+  WARN pid-50247 [2014-01-07 13:22:28:516]                    com.mytld.QuickstartWithRuby - WARN logs are captured by default
+ ERROR pid-50247 [2014-01-07 13:22:28:516]                    com.mytld.QuickstartWithRuby - ERROR logs are captured by default
+SEVERE pid-50247 [2014-01-07 13:22:28:516]                    com.mytld.QuickstartWithRuby - SEVERE logs are captured by default
+ FATAL pid-50247 [2014-01-07 13:22:28:516]                    com.mytld.QuickstartWithRuby - FATAL logs are captured by default
+NOTICE pid-50247 [2014-01-07 13:22:28:516]                    com.mytld.QuickstartWithRuby - The caller will append log location info to this message (quickstart_with_ruby.rb:27:in `using_the_caller')
+NOTICE pid-50247 [2014-01-07 13:22:28:516]                    com.mytld.QuickstartWithRuby - If the user specifies the :file, :line, AND :method, the caller will NOT get invoked (quickstart_with_ruby.rb:28:in `run')
+NOTICE pid-50247 [2014-01-07 13:22:28:517]                    com.mytld.QuickstartWithRuby - To prove the caller is not used, we can put dummy data in and see that it's being used instead (just_kidding.rb:123456789:in `whatever')
+ DEBUG pid-50247 [2014-01-07 13:22:28:517]                    com.mytld.QuickstartWithRuby - Now DEBUG messages should show up
+  WARN pid-50247 [2014-01-07 13:22:28:517]                    com.mytld.QuickstartWithRuby - Sample WARN statement with backtrace requested
+ ERROR pid-50247 [2014-01-07 13:22:28:517]                    com.mytld.QuickstartWithRuby - Sample ERROR statement with backtrace requested from:
+quickstart_with_ruby.rb:51:in `displaying_backtrace_information'
+quickstart_with_ruby.rb:59:in `<main>'
 ```
 
 
@@ -114,82 +115,83 @@ Load the `index` page and check out your `development.log` file
 
     DEBUG pid-86000 [2013-12-17 17:26:39:176] ld.myrailsapp.app.controllers.WidgetsController - "Handling a Widgets index request with params = {"controller"=>"widgets", "action"=>"index"} (`/myrailsapp/app/controllers/widgets_controller.rb:7`:in `index`)
 
+More Examples
+-------------
+See the [examples folder](https://github.com/jgithub/catamaran/tree/master/examples).
+
 Log Levels
 ----------
 Available log levels:  `TRACE` (verbose and trivial log messages), `DEBUG`, `INFO`, `NOTICE`, `WARN`, `ERROR`, `SEVERE` (logs related to very serious error conditions), `FATAL`
 
 The `NOTICE` log level severity is the default.   Any logs with `NOTICE` or higher severity will be captured.
 
-
 Inspiration
 -----------
+I always liked working with log4j.  Much of the inspriation comes from that.
+
+* Named Hierarchy
+* Level Inheritance
+* `TRACE`
+
 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 severity thresholds from different parts of the app simultaneously (I always liked the Named Hierarchy and Level Inheritance aspects of log4j)
+* supports the TRACE log level (or other log level less critical than DEBUG).
+* is capable of capturing logs at different severity thresholds from different parts of the app simultaneously 
 * readily works with Rails
-* http://stackoverflow.com/questions/462651/rails-logger-format-string-configuration
-* http://stackoverflow.com/questions/3654827/logging-in-rails-app
-* http://stackoverflow.com/questions/11991967/rails-log-too-verbose
-* http://www.ietf.org/rfc/rfc3164.txt
-* http://logging.apache.org/log4j/1.2
 
 Performance Considerations
 --------------------------
 
 ### With or without `if LOGGER.debug?`
 ```ruby
+$: << '../lib'
+
 require 'catamaran'
 require 'benchmark'
 
-Catamaran::LogLevel.default_log_level = Catamaran::LogLevel::INFO 
+Catamaran.logger.log_level = Catamaran::LogLevel::INFO 
 Catamaran::Manager.stderr = false
 
-class CatamaranConditionalLogStatementBenchmark
-  LOGGER = Catamaran.logger( "CatamaranConditionalLogStatementBenchmark" )
+class BenchmarkingConditionalLogStatements
+  LOGGER = Catamaran.logger( "BenchmarkingConditionalLogStatements" )
 
   # NOTE that the log level for this test is set to INFO, 
   # so 'warn' logs are enabled and 'debug' logs are disabled
 
   n = 500000
   Benchmark.bm(7) do |x|
-    x.report("warn WITHOUT if LOGGER.warn?  ") {
+    x.report("LOGGER.warn WITHOUT if LOGGER.warn?  ") {
       n.times do |i|
         LOGGER.warn "Based on the current log level, this log is being captured"
       end
     }
-    x.report("warn WITH if LOGGER.warn?     ") {
+    x.report("LOGGER.warn WITH if LOGGER.warn?     ") {
       n.times do |i|
         LOGGER.warn "Based on the current log level, this log is being captured" if LOGGER.warn?
       end
     }
-  end
-
-  Benchmark.bm(7) do |x|
-    x.report("debug WITHOUT if LOGGER.debug?") {
+    x.report("LOGGER.debug WITHOUT if LOGGER.debug?") {
       n.times do |i|
         LOGGER.debug "Based on the current log level, this log is NOT being captured"
       end
     }
-    x.report("debug WITH if LOGGER.debug?   ") {
+    x.report("LOGGER.debug WITH if LOGGER.debug?   ") {
       n.times do |i|
         LOGGER.debug "Based on the current log level, this log is NOT being captured" if LOGGER.debug?       
       end
     }
   end 
-
 end
 
-#                                     user     system      total        real
-# warn WITHOUT if LOGGER.warn?    6.940000   0.010000   6.950000 (  6.950691)
-# warn WITH if LOGGER.warn?       7.650000   0.000000   7.650000 (  7.658004)
-#                                     user     system      total        real
-# debug WITHOUT if LOGGER.debug?  0.660000   0.010000   0.670000 (  0.665775)
-# debug WITH if LOGGER.debug?     0.560000   0.010000   0.570000 (  0.574397)
+#                                            user     system      total        real
+# LOGGER.warn WITHOUT if LOGGER.warn?    6.440000   0.090000   6.530000 (  6.533838)
+# LOGGER.warn WITH if LOGGER.warn?       7.110000   0.120000   7.230000 (  7.242870)
+# LOGGER.debug WITHOUT if LOGGER.debug?  0.530000   0.020000   0.550000 (  0.548454)
+# LOGGER.debug WITH if LOGGER.debug?     0.450000   0.030000   0.480000 (  0.474419)
 ```
 
 #### Summary
@@ -275,8 +277,6 @@ require 'ruby-prof'
 
 class CatamaranProfilerTest
   LOGGER = Catamaran.logger( "com.mycompany.CatamaranProfilerTest" )
-  # or equivalently: 
-  # LOGGER = Catamaran.logger.com.mycompany.CatamaranProfilerTest
 
   def run
     # Disabled by default
@@ -296,7 +296,7 @@ end
 
 RubyProf.start
 
-demo = FirstRubyDemo.new
+catamaran_profiler_test = CatamaranProfilerTest.new
 1000.times do
   demo.run
 end
@@ -304,7 +304,6 @@ end
 result = RubyProf.stop
 
 printer = RubyProf::GraphPrinter.new(result)
-
 printer.print(STDOUT)
 ```
 
@@ -510,6 +509,15 @@ Ideas around what's next
 * Heroku support (https://blog.heroku.com/archives/2013/7/15/logging-on-heroku)
 * Buffered file I/O considerations
 
-
+See also
+--------
+* http://stackoverflow.com/questions/462651/rails-logger-format-string-configuration
+* http://stackoverflow.com/questions/3654827/logging-in-rails-app
+* http://stackoverflow.com/questions/11991967/rails-log-too-verbose
+* http://www.ietf.org/rfc/rfc3164.txt
+* http://logging.apache.org/log4j/1.2
+* https://github.com/TwP/logging
+* https://github.com/colbygk/log4r
+* http://guides.rubyonrails.org/debugging_rails_applications.html#the-logger
 
 

data/catamaran.gemspec

@@ -9,6 +9,7 @@ Gem::Specification.new do |s|
   s.description      = "A logging utility"
   s.homepage         = "http://github.com/jgithub/catamaran"
   s.files            = `git ls-files`.split("\n")
+  s.licenses         = ['MIT']
 end
 
 

data/examples/benchmarking_conditional_log_statements.rb

@@ -0,0 +1,44 @@
+$: << '../lib'
+
+require 'catamaran'
+require 'benchmark'
+
+Catamaran.logger.log_level = Catamaran::LogLevel::INFO 
+Catamaran::Manager.stderr = false
+
+class BenchmarkingConditionalLogStatements
+  LOGGER = Catamaran.logger( "BenchmarkingConditionalLogStatements" )
+
+  # NOTE that the log level for this test is set to INFO, 
+  # so 'warn' logs are enabled and 'debug' logs are disabled
+
+  n = 500000
+  Benchmark.bm(7) do |x|
+    x.report("LOGGER.warn WITHOUT if LOGGER.warn?  ") {
+      n.times do |i|
+        LOGGER.warn "Based on the current log level, this log is being captured"
+      end
+    }
+    x.report("LOGGER.warn WITH if LOGGER.warn?     ") {
+      n.times do |i|
+        LOGGER.warn "Based on the current log level, this log is being captured" if LOGGER.warn?
+      end
+    }
+    x.report("LOGGER.debug WITHOUT if LOGGER.debug?") {
+      n.times do |i|
+        LOGGER.debug "Based on the current log level, this log is NOT being captured"
+      end
+    }
+    x.report("LOGGER.debug WITH if LOGGER.debug?   ") {
+      n.times do |i|
+        LOGGER.debug "Based on the current log level, this log is NOT being captured" if LOGGER.debug?       
+      end
+    }
+  end 
+end
+
+#                                            user     system      total        real
+# LOGGER.warn WITHOUT if LOGGER.warn?    6.440000   0.090000   6.530000 (  6.533838)
+# LOGGER.warn WITH if LOGGER.warn?       7.110000   0.120000   7.230000 (  7.242870)
+# LOGGER.debug WITHOUT if LOGGER.debug?  0.530000   0.020000   0.550000 (  0.548454)
+# LOGGER.debug WITH if LOGGER.debug?     0.450000   0.030000   0.480000 (  0.474419)

data/examples/benchmarking_the_caller.rb

@@ -0,0 +1,34 @@
+$: << '../lib'
+require 'catamaran'
+require 'benchmark'
+
+Catamaran::Manager.stderr = false
+
+class CatamaranCallerBenchmark
+  LOGGER = Catamaran.logger( "CatamaranCallerBenchmark" )
+
+  n = 500000
+  Benchmark.bm(7) do |x|
+    Catamaran::Manager.formatter_caller_enabled = false
+    
+    x.report("Catamaran::Manager.formatter_caller_enabled = false") {
+      n.times do |i|
+        LOGGER.error "This is a ERROR log"
+      end
+    }   
+    
+    Catamaran::Manager.formatter_caller_enabled = true
+    
+    x.report("Catamaran::Manager.formatter_caller_enabled = true ") {
+      n.times do |i|
+        LOGGER.error "This is a ERROR log"
+      end
+    }
+  end
+end
+
+
+#                                                            user     system      total        real
+# Catamaran::Manager.formatter_caller_enabled = false    5.870000   0.060000   5.930000 (  5.943813)
+# Catamaran::Manager.formatter_caller_enabled = true    13.120000   0.350000  13.470000 ( 13.469126)
+

data/examples/quickstart_with_ruby.rb

@@ -0,0 +1,76 @@
+$: << '../lib'
+require 'catamaran'
+
+class QuickstartWithRuby
+  LOGGER = Catamaran.logger( "com.mytld.QuickstartWithRuby" )
+  # or equivalently: 
+  # LOGGER = Catamaran.logger.com.mytld.QuickstartWithRuby
+
+  def demonstrating_log_levels
+    # Disabled by default
+    LOGGER.trace( "TRACE logs are NOT captured by default" ) if LOGGER.trace?    
+    LOGGER.debug( "DEBUG logs are NOT captured by default" ) if LOGGER.debug?
+    LOGGER.info( "INFO logs are NOT captured by default" ) if LOGGER.info?
+
+    # Enabled by default
+    LOGGER.notice( "NOTICE logs are captured by default" )
+    LOGGER.warn( "WARN logs are captured by default" )    
+    LOGGER.error( "ERROR logs are captured by default" )
+    LOGGER.severe( "SEVERE logs are captured by default" )
+    LOGGER.fatal( "FATAL logs are captured by default" )
+  end
+
+  def using_the_caller
+    # Enable the caller (it's disabled by default)
+    Catamaran::Manager.formatter_caller_enabled = true
+
+    LOGGER.notice( "The caller will append log location info to this message" )
+    LOGGER.notice( "If the user specifies the :file, :line, AND :method, the caller will NOT get invoked", { :file => __FILE__, :line => __LINE__, :method => 'run' } )
+    LOGGER.notice( "To prove the caller is not used, we can put dummy data in and see that it's being used instead", { :file => 'just_kidding.rb', :line => 123456789, :method => 'whatever' } )    
+  
+    # Turn it back off
+    Catamaran::Manager.formatter_caller_enabled = false
+  end
+
+  def changing_the_log_level
+    # Note that the log level can be changed
+    Catamaran.logger.log_level = Catamaran::LogLevel::DEBUG
+    Catamaran::Manager.forget_cached_log_levels()
+
+    LOGGER.trace( "TRACE logs are STILL NOT captured" ) if LOGGER.trace?    
+    LOGGER.debug( "Now DEBUG messages should show up" ) if LOGGER.debug?
+  end
+
+  def displaying_backtrace_information
+    Catamaran.logger.log_level = Catamaran::LogLevel::NOTICE
+    Catamaran.logger.backtrace_log_level = Catamaran::LogLevel::ERROR 
+    Catamaran::Manager.forget_cached_log_levels()
+
+    LOGGER.debug( "Sample DEBUG statement with backtrace requested", { :backtrace => true } )
+    LOGGER.warn( "Sample WARN statement with backtrace requested", { :backtrace => true } )
+    LOGGER.error( "Sample ERROR statement with backtrace requested", { :backtrace => true } )
+  end
+end
+
+quickstart_with_ruby = QuickstartWithRuby.new
+quickstart_with_ruby.demonstrating_log_levels
+quickstart_with_ruby.using_the_caller
+quickstart_with_ruby.changing_the_log_level
+quickstart_with_ruby.displaying_backtrace_information
+
+
+
+# NOTICE pid-50247 [2014-01-07 13:22:28:516]                    com.mytld.QuickstartWithRuby - NOTICE logs are captured by default
+#   WARN pid-50247 [2014-01-07 13:22:28:516]                    com.mytld.QuickstartWithRuby - WARN logs are captured by default
+#  ERROR pid-50247 [2014-01-07 13:22:28:516]                    com.mytld.QuickstartWithRuby - ERROR logs are captured by default
+# SEVERE pid-50247 [2014-01-07 13:22:28:516]                    com.mytld.QuickstartWithRuby - SEVERE logs are captured by default
+#  FATAL pid-50247 [2014-01-07 13:22:28:516]                    com.mytld.QuickstartWithRuby - FATAL logs are captured by default
+# NOTICE pid-50247 [2014-01-07 13:22:28:516]                    com.mytld.QuickstartWithRuby - The caller will append log location info to this message (quickstart_with_ruby.rb:27:in `using_the_caller')
+# NOTICE pid-50247 [2014-01-07 13:22:28:516]                    com.mytld.QuickstartWithRuby - If the user specifies the :file, :line, AND :method, the caller will NOT get invoked (quickstart_with_ruby.rb:28:in `run')
+# NOTICE pid-50247 [2014-01-07 13:22:28:517]                    com.mytld.QuickstartWithRuby - To prove the caller is not used, we can put dummy data in and see that it's being used instead (just_kidding.rb:123456789:in `whatever')
+#  DEBUG pid-50247 [2014-01-07 13:22:28:517]                    com.mytld.QuickstartWithRuby - Now DEBUG messages should show up
+#   WARN pid-50247 [2014-01-07 13:22:28:517]                    com.mytld.QuickstartWithRuby - Sample WARN statement with backtrace requested
+#  ERROR pid-50247 [2014-01-07 13:22:28:517]                    com.mytld.QuickstartWithRuby - Sample ERROR statement with backtrace requested from:
+# quickstart_with_ruby.rb:51:in `displaying_backtrace_information'
+# quickstart_with_ruby.rb:59:in `<main>'
+

data/examples/with_double_colon_delimiter.rb

@@ -0,0 +1,25 @@
+$: << '../lib'
+require 'catamaran'
+
+Catamaran::Manager.delimiter = '::'
+Catamaran::logger.log_level = :debug
+
+module MyCoolModule
+  class WithDoubleColonDelimiter
+    LOGGER = Catamaran.logger( "MyCoolModule::WithDoubleColonDelimiter" )
+
+    def run
+      LOGGER.debug( "Does this look more like Ruby?", { :file => __FILE__, :line => __LINE__ } ) if LOGGER.debug?
+    end
+  end
+end
+
+with_double_colon_delimiter = MyCoolModule::WithDoubleColonDelimiter.new
+with_double_colon_delimiter.run
+
+
+
+#  DEBUG pid-829 [2014-01-08 13:55:09:979]          MyCoolModule::WithDoubleColonDelimiter - Does this look more like Ruby? (with_double_colon_delimiter.rb:12)
+
+
+

data/examples/with_the_ruby_profiler.rb

@@ -0,0 +1,33 @@
+$: << '../lib'
+require 'catamaran'
+require 'ruby-prof'
+
+class WithTheRubyProfiler
+  LOGGER = Catamaran.logger( "com.mycompany.WithTheRubyProfiler" )
+
+  def run
+    # Disabled by default
+    LOGGER.trace( "TRACE logs are NOT captured by default" ) if LOGGER.trace?
+    LOGGER.debug( "DEBUG logs are NOT captured by default" ) if LOGGER.debug?
+    LOGGER.info( "INFO logs are NOT captured by default" ) if LOGGER.info?
+
+    # Enabled by default
+    LOGGER.notice( "NOTICE logs are captured by default" )
+    LOGGER.warn( "WARN logs are captured by default" )
+    LOGGER.error( "ERROR logs are captured by default" )
+    LOGGER.severe( "SEVERE logs are captured by default" )
+    LOGGER.fatal( "FATAL logs are captured by default" )
+  end
+end
+
+RubyProf.start
+
+demo = WithTheRubyProfiler.new
+1000.times do
+  demo.run
+end
+
+result = RubyProf.stop
+
+printer = RubyProf::GraphPrinter.new(result)
+printer.print(STDOUT)

data/lib/catamaran/log_level.rb

@@ -41,6 +41,29 @@ module Catamaran
       IO_LESS_CRITICAL_THAN_DEBUG => 'IO'
     }
 
+    STRING_TO_SEVERITY_MAP = {
+      'TRACE' => TRACE,
+      'DEBUG' => DEBUG,
+      'INFO' => INFO,
+      'NOTICE' => NOTICE,
+      'WARN' => WARN,
+      'ERROR' => ERROR,
+      'SEVERE' => SEVERE,
+      'FATAL' => FATAL
+    }
+
+    SYMBOL_TO_SEVERITY_MAP = {
+      :trace => TRACE,
+      :debug => DEBUG,
+      :info => INFO,
+      :notice => NOTICE,
+      :warn => WARN,
+      :error => ERROR,
+      :severe => SEVERE,
+      :fatal => FATAL
+    }         
+
+
     def self.reset
       self.send( :remove_const, 'IO' ) if self.const_defined?( 'IO' )
       self.const_set( 'IO', IO_LESS_CRITICAL_THAN_INFO )            
@@ -53,7 +76,13 @@ module Catamaran
       SEVERITY_TO_STRING_MAP[severity] || ''
     end  
 
+    def self.string_to_severity( str )
+      str ? STRING_TO_SEVERITY_MAP[str.strip.upcase] : nil
+    end     
 
+    def self.symbol_to_severity( sym )
+      sym ? SYMBOL_TO_SEVERITY_MAP[sym] : nil
+    end 
 
     def self.log_level_io=( value )
       self.send( :remove_const, 'IO' ) if self.const_defined?( 'IO' )

data/lib/catamaran/logger.rb

@@ -16,9 +16,16 @@ module Catamaran
         @log_level
       elsif self.parent.nil?
         # No parent means this logger(self) is the root logger.  So use the default log level
-        
+        if !@memoized_log_level
+          if ENV['CATAMARAN_ROOT_LOGGER_LOG_LEVEL']
+            @memoized_log_level = LogLevel.string_to_severity( ENV['CATAMARAN_ROOT_LOGGER_LOG_LEVEL'] )
+          else
+            @memoized_log_level = Catamaran::LogLevel::NOTICE
+          end
+        end
+
         # Implicit return
-        Catamaran::LogLevel::NOTICE
+        @memoized_log_level
       else
         recursive = ( opts && ( opts[:recursive] == true || opts[:be_populated] == true ) )
         if recursive == true 
@@ -50,8 +57,21 @@ module Catamaran
     ##
     # Setter used to explicitly set the log level for this logger
 
+
+
     def log_level=( value )
-      @log_level = value
+      if value 
+        if value.kind_of?( Symbol )
+          @log_level = LogLevel.symbol_to_severity( value )
+        elsif value.kind_of?( String )
+          @log_level = LogLevel.string_to_severity( value )
+        else 
+          @log_level = value
+        end     
+      else
+        @log_level = nil
+      end
+      
       @memoized_log_level = nil      
     end
 
@@ -313,7 +333,7 @@ module Catamaran
 
         
       if path
-        method_names = path.split(/\./)
+        method_names = path.split(/\.|\:\:/)
 
         method_names.each do |method_name|
           current_logger = current_logger.send( method_name.to_sym ) 

data/lib/catamaran/version.rb

@@ -1,4 +1,4 @@
 module Catamaran
-  VERSION = '2.1.0'
+  VERSION = '2.2.0'
 end
 

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

@@ -11,6 +11,9 @@ Catamaran.logger.log_level = Catamaran::LogLevel::DEBUG
 # There is a performance hit for using the caller, but it generates more detailed logs
 Catamaran::Manager.formatter_caller_enabled = true
 
+# Uncomment if you'd prefer Ruby-style delimiters
+Catamaran::Manager.delimiter = '::'
+
 # Uncomment to enable Catamaran internal debugging
 # Catamaran::debugging = true
 

data/spec/catamaran_spec.rb

@@ -48,23 +48,75 @@ describe Catamaran do
     logger2.object_id.should == logger.object_id
   end
 
-  it "should create a new loggers for each point in the path" do
-    Catamaran.logger
-    Catamaran::Manager.num_loggers.should == 1
-    Catamaran.logger.com.mycompany.myrailsproject.app.models.User
-    Catamaran::Manager.num_loggers.should == 7    
-  end     
-
-  it "should be possible for the user to modify the log level of root logger" do
-    Catamaran.logger.log_level = Catamaran::LogLevel::TRACE
-    Catamaran.logger.log_level.should == Catamaran::LogLevel::TRACE
+  context "when using method_missing" do
+    it "should create a new loggers for each point in the path" do
+      Catamaran.logger
+      Catamaran::Manager.num_loggers.should == 1
+      Catamaran.logger.com.mycompany.myrailsproject.app.models.User
+      Catamaran::Manager.num_loggers.should == 7    
+    end 
+  end 
+
+  context "when using a specified string and period as the delimiter" do
+    it "should create a new loggers for each point in the path" do
+      Catamaran.logger
+      Catamaran::Manager.num_loggers.should == 1
+      Catamaran.logger( "com.mycompany.myrailsproject.app.models.User" )
+      Catamaran::Manager.num_loggers.should == 7    
+    end 
   end
 
-  it "should be possible for the user to modify the log level of non-root loggers" do
-    Catamaran.logger.whatever.log_level.should be_nil
-    Catamaran.logger.whatever.log_level = Catamaran::LogLevel::TRACE
-    Catamaran.logger.whatever.log_level.should == Catamaran::LogLevel::TRACE
-  end  
+  context "when using a specified string and double-colons as the delimiter" do
+    it "should create a new loggers for each point in the path" do
+      Catamaran.logger
+      Catamaran::Manager.num_loggers.should == 1
+      Catamaran.logger( "com::mycompany::myrailsproject::app::models::User" )
+      Catamaran::Manager.num_loggers.should == 7    
+    end 
+  end         
+
+  context "using log level constants" do
+    it "should be possible for the user to modify the log level of root logger" do
+      Catamaran.logger.log_level = Catamaran::LogLevel::TRACE
+      Catamaran.logger.log_level.should == Catamaran::LogLevel::TRACE
+    end
+
+    it "should be possible for the user to modify the log level of non-root loggers" do
+      Catamaran.logger.whatever.log_level.should be_nil
+      Catamaran.logger.whatever.log_level = Catamaran::LogLevel::TRACE
+      Catamaran.logger.whatever.log_level.should == Catamaran::LogLevel::TRACE
+    end  
+  end
+
+  context "using symbols" do
+    it "should be possible for the user to modify the log level of root logger" do
+      Catamaran.logger.log_level = :trace
+      Catamaran.logger.log_level.should == Catamaran::LogLevel::TRACE
+    end
+
+    it "should be possible for the user to modify the log level of non-root loggers" do
+      Catamaran.logger.whatever.log_level.should be_nil
+      Catamaran.logger.whatever.log_level = :trace
+      Catamaran.logger.whatever.log_level.should == Catamaran::LogLevel::TRACE
+    end  
+  end 
+
+  context "using strings" do
+    it "should be possible for the user to modify the log level of root logger" do
+      Catamaran.logger.log_level = 'trace'
+      Catamaran.logger.log_level.should == Catamaran::LogLevel::TRACE
+      Catamaran.logger.log_level = 'deBuG '
+      Catamaran.logger.log_level.should == Catamaran::LogLevel::DEBUG
+    end
+
+    it "should be possible for the user to modify the log level of non-root loggers" do
+      Catamaran.logger.whatever.log_level.should be_nil
+      Catamaran.logger.whatever.log_level = ' TRACe '
+      Catamaran.logger.whatever.log_level.should == Catamaran::LogLevel::TRACE
+      Catamaran.logger.whatever.log_level = ' INFO '
+      Catamaran.logger.whatever.log_level.should == Catamaran::LogLevel::INFO
+    end  
+  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
@@ -85,6 +137,25 @@ describe Catamaran do
         Catamaran.logger.log_level.should == Catamaran::LogLevel::NOTICE
       end
 
+      it "should make use of the environment variable when specified" do
+        initial_log_level = Catamaran.logger.log_level     
+
+        ENV['CATAMARAN_ROOT_LOGGER_LOG_LEVEL'] = 'ERROR'
+        Catamaran::Manager.forget_memoizations
+        Catamaran.logger.log_level.should == Catamaran::LogLevel::ERROR
+
+        ENV.delete( 'CATAMARAN_ROOT_LOGGER_LOG_LEVEL' )
+        Catamaran::Manager.forget_memoizations
+        initial_log_level.should == Catamaran::LogLevel::NOTICE     
+        
+        ENV['CATAMARAN_ROOT_LOGGER_LOG_LEVEL'] = ' error  '
+        Catamaran::Manager.forget_memoizations
+        Catamaran.logger.log_level.should == Catamaran::LogLevel::ERROR
+
+        ENV.delete( 'CATAMARAN_ROOT_LOGGER_LOG_LEVEL' )
+        Catamaran::Manager.forget_memoizations
+      end      
+
       it "should have a backtrace log level set to WARN" do
         Catamaran.logger.backtrace_log_level.should == Catamaran::LogLevel::WARN
       end      
@@ -325,6 +396,19 @@ describe Catamaran do
       Catamaran.logger.debug( "And INFO log should NOT be received" )
     end
 
+    describe "#path_to_s" do
+      it "should use a period as the default delimiter" do
+        logger = Catamaran.logger.com.mycompany.myrailsproject.app.models.User
+        logger.path_to_s.should == "com.mycompany.myrailsproject.app.models.User"    
+      end
+
+      it "should be capable of using a user-specified delimiter" do
+        Catamaran::Manager.delimiter = "::"
+        logger = Catamaran.logger.App.Model.User
+        logger.path_to_s.should == "App::Model::User"    
+      end      
+    end
+
     describe "#forget_memoizations" do
       it "should forget all the memoized log levels" do
         Catamaran.logger.log_level = Catamaran::LogLevel::ERROR

metadata

@@ -1,25 +1,37 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: catamaran
-version: !ruby/object:Gem::Version
-  version: 2.1.0
+version: !ruby/object:Gem::Version 
+  version: 2.2.0
 platform: ruby
-authors:
+authors: 
 - Jeano
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-05 00:00:00.000000000 Z
+
+date: 2014-01-08 00:00:00 -06:00
+default_executable: 
 dependencies: []
+
 description: A logging utility
-email:
+email: 
 - catamaran@jeano.net
 executables: []
+
 extensions: []
+
 extra_rdoc_files: []
-files:
+
+files: 
 - .gitignore
+- LICENSE
 - README.md
 - catamaran.gemspec
+- examples/benchmarking_conditional_log_statements.rb
+- examples/benchmarking_the_caller.rb
+- examples/quickstart_with_ruby.rb
+- examples/with_double_colon_delimiter.rb
+- examples/with_the_ruby_profiler.rb
 - init.rb
 - lib/catamaran.rb
 - lib/catamaran/formatter.rb
@@ -38,27 +50,33 @@ files:
 - 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: []
-metadata: {}
+licenses: 
+- MIT
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
-  requirements:
-  - - '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-required_rubygems_version: !ruby/object:Gem::Requirement
-  requirements:
-  - - '>='
-    - !ruby/object:Gem::Version
-      version: '0'
+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: 2.0.3
+rubygems_version: 1.3.5
 signing_key: 
-specification_version: 4
+specification_version: 3
 summary: Catamaran Logger
 test_files: []
+

checksums.yaml

@@ -1,7 +0,0 @@
----
-SHA1:
-  metadata.gz: b7cd46193a36dacdc5ed0f8c6ce8c95c0a81e256
-  data.tar.gz: 80e278d4ebd3d9c8640809aa0748e36ace294322
-SHA512:
-  metadata.gz: bbb1d0824624d9f21ccb207c27a05ec0dd20132a8a2bd7f77d34971a579aa6cd05cb53a4610500d2296047d535819d974872923ce0d5fcacf3f8bc6d848de12c
-  data.tar.gz: d51f7a5b1e9cb1295b431baec9280c701557ecdf550e942937a85694588e48dbfcc5a9f2d16fa9cba8f0683aa3e208f672c79a76a1f9e695991d0feb208d18b5