lager 0.2.0.3 → 0.2.0.4

data/README.md

@@ -1,6 +1,6 @@
 Lager
 =====
-Lager is a logging mixin.  It is designed to add class methods for logging, via extend.  It aims to provide a unified logging interface that you can use in both class and instance methods.  Only one Logger instance is used for this.  You are able to set the log destination and log level from within the class, via instantiation, or from outside.
+Lager is a logging mixin.  It is designed to add class methods for logging, via `extend Lager`.  It provides a unified logging instance that you can use in both class and instance methods.  It is implemented with the familiar [Logger class](http://ruby-doc.org/stdlib-2.0/libdoc/logger/rdoc/Logger.html) from ruby's [stdlib](http://ruby-doc.org/stdlib/).  Only one Logger instance is used for the class.  Use #log_to to set the log destination and log level from inside or outside the class.
 
 Usage
 -----
@@ -45,13 +45,18 @@ Right now, Foo is spewing debug messages everywhere:
     f = Foo.new
     f.do_something_complicated
 
+    [2013-07-05 15:14:52] DEBUG: baz 15 is a Fixnum, not a string
+    [2013-07-05 15:14:52] DEBUG: about to do something complicated
+    [2013-07-05 15:14:52] DEBUG: whew! we made it!
+
+
 This is because we set the default logging to :debug level, above:
 
     class Foo
       extend Lager
       log_to $stdout, :debug  # sets up @lager at the class layer
 
-Now let's calm things down:
+Let's calm things down a bit, shall we?
 
     Foo.log_level :warn
     Foo.new.do_something_complicated
@@ -60,25 +65,25 @@ We can tell Foo to log to a file:
 
     Foo.log_to '/tmp/foo.log'
 
-Note that this will create a new Logger instance.  The old log level will be maintained unless you specify a new one.
+Note that this will replace the class's Logger instance.  The old log level will be maintained unless you specify a new one.
 
 Best practices
 --------------
-* Set default logging inside the class definition by calling log_to
+* Set default logging inside the class definition by calling log_to just after extend Lager
 * Set the instance layer's @lager within #initialize
 * Only call message methods (debug, info, warn, error, fatal) on @lager in your class and instance methods.
 * Beyond the class default, let the log destination and log level be managed from the outside, by the users of your class.
 
-Use block invocation of message methods
+For Logger, generally: use block invocation of message methods.
 
-    debug { "hi" }
+    @lager.debug { "hi" }
     # rather than
-    debug "hi"
+    @lager.debug "hi"
 
     # By using the first form, the block will not be evaluated unless we
     # are logging at DEBUG level.
     # If using the second form, the message is evaluated no matter the current
-    # log level.
+    # log level.  This can be significant when logging complicated messages.
 
 Artifacts
 ---------
@@ -92,3 +97,26 @@ Artifacts
 Now you have a unified interface for logging at both class and instance layers.
 
     @lager.info { "So happy right now!" }
+
+Use an existing Logger instance
+-------------------------------
+If your project already has an existing Logger, then you can set your class to use that Logger:
+
+    class Foo
+      extend Lager
+      log_to $LOG # the global Logger instance
+      # ...
+    end
+
+Of course, $LOG will have to have already been defined at requiretime.  You can set it the same way at runtime:
+
+    class Foo
+      extend Lager
+      log_to $stderr
+      # ...
+    end
+
+    # now, in an irb session or another file
+    # where Project.log is your project's Logger:
+
+    Foo.log_to Project.log

data/VERSION

@@ -1 +1 @@
-0.2.0.3
+0.2.0.4

data/lib/lager.rb

@@ -8,16 +8,19 @@ require 'logger'
 #   ...
 # end
 #
-# It provides the class instance variable @lager, which may be used in class methods
+# It provides the class instance variable @lager, which may be used in class
+# methods, e.g.
 #
-# e.g. @lager.debug { "example log message" }
+# def self.foo
+#   @lager.debug { "example log message" }
+# end
 #
 # Note that using the block invocation means that the block contents are
 # not evaluated if the log level is above the message level.
 #
 # Make sure to call log_to within the class definition, so that class methods
-# will already have @lager defined.
-
+# will already have @lager defined at requiretime.
+#
 # For instance methods, you need to set @lager directly, within initialize
 # Note: the instance layer and class layer each have their own independent
 #       @lager
@@ -40,11 +43,16 @@ module Lager
   end
 
   # create @lager
+  # if passed a Logger instance, set @lager to that instance and return
   # supports IO and String (filename, presumably) for log destination
   # (passed straight through to Logger.new)
   # supports symbols, strings, and integers for log level
   #
   def log_to(dest = $stderr, level = nil)
+    if dest.is_a?(Logger)
+      @lager = dest
+      return
+    end
     # use the old @lager's level by default, as appropriate
     level ||= (defined?(@lager) ? @lager.level : :warn)
     @lager = Logger.new dest

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lager
 version: !ruby/object:Gem::Version
-  version: 0.2.0.3
+  version: 0.2.0.4
   prerelease: 
 platform: ruby
 authors: