injectedlogger 0.0.9 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b04855c6aefc41105ceeada8201cac74438e5e16
-  data.tar.gz: 3b7d0be8ad3bf7f468428df6e852791239a6cbe6
+  metadata.gz: f16981ff8dc874e0d132b20da815f7d11b5ccd17
+  data.tar.gz: b10b69e4c143ab00dfb5195bcbefb2e646eafdd9
 SHA512:
-  metadata.gz: a23d4e70e17d8d57bc1b7da07c5a411bfa16ab37cefe365038eeaf3ae81bfd51954831d68e828834f8c9d42314be3cb8a3ded4b67c2b740c25916026dd098ba6
-  data.tar.gz: 361cb12199df9325047e336f21bce4544d0f1ccecf46c40078d0d9ef431fb7ef31540523db268885a787c26c16a1172f721d1b96d08a2cf81626f42fced6818a
+  metadata.gz: a8a3682add57e43dd21f8f76211b0181aaec5c9b6680667f10ca26cfd2195c61d647014c31de52721a7fb4429dbfea4aaaabb1e0675b23d1b9d65ac8751329eb
+  data.tar.gz: 020bf6172f45482b1c0e2e69ecc04a10248659d18521f1e6832a4c2b204e9799861739fa9abdca50f151806838da552e0b9cf11b93e2f592c9c04ccc7a081a84

data/README.md

@@ -1,54 +1,116 @@
+[![Gem Version](https://badge.fury.io/rb/injectedlogger.svg)](http://badge.fury.io/rb/injectedlogger)
+
 # A logger injection gem
 
 This gem can be used to inject several loggers in different parts of your Ruby project.
 
 It will try to support as many methods and levels as the underlying object supports, and fall back to a supported level in case some levels are not available
 
-## Usage examples
+## How to use it
+
+You have to declare the log levels that your code will be using, and
+InjectedLogger will make sure that the underlying object supports them.
+
+The user of your code will just pass the logger and refer to either a module of
+yours or a symbolic name or string.
+
+Suppose we have two projects, one of which has the other as dependency, and has
+a logger available. The other project wants to log whatever it does using a
+logger injected (provided) by the first project.
 
-### On your code, which receives a logger from some foreign caller:
+### On the code injecting the logger:
 
+Inject our logger on `Dependency::Logger`, which is the module used by Dependency
+for logging:
 ```ruby
-module MyLogger
-  InjectedLogger.use :debug, :info, :invented do
-    # this gets executed if no logger has been injected at use time
-    require 'logger'
-    { logger: Logger.new(STDERR) }
-  end
-  InjectedLogger.after_injection do |logger|
-    logger.prefix = '[myproject]'
+InjectedLogger.inject mylogger, on: Dependency::Logger
+```
+
+Inject our logger on whatever is identified by `'dependency-logger'`:
+```ruby
+InjectedLogger.inject mylogger, on: 'dependency-logger'
+```
+
+Inject our logger on `'dependency-logger'`, and have it provide `:debug`, `:info`
+and `:invented` log levels, with whatever of those being actually unsupported by
+`mylogger` emulated with `:info`:
+```ruby
+InjectedLogger.inject mylogger, levels: [:debug, :info, :invented], fallback: :info, on: 'dependency-logger'
+```
+
+Inject our logger on `Dependency::Logger` and prefix the messages with `'[logger-for-dep]'`:
+```ruby
+InjectedLogger.inject mylogger, prefix: '[logger-for-dep]', on: Dependency::Logger
+```
+
+### On the code where you want a logger injected:
+
+This sets up a module with a `logger` method identified as `'dependency-logger'`
+and declaring requirements of `:debug`, `:info`, and `:invented` log levels. In
+case no logger gets injected by the time `logger` is needed, the standard Ruby
+logger with output on `STDERR` will be used. After a logger is finally available,
+this also makes sure the prefix for each message is `'[dependency]'` (overriding
+what the injector set up):
+```ruby
+module Dependency
+  module Logger
+    InjectedLogger.use :debug, :info, :invented, as: 'dependency-logger' do
+      # this gets executed if no logger has been injected at use time
+      require 'logger'
+      { logger: Logger.new(STDERR) } # optionally add parameters for `inject`
+    end
+    InjectedLogger.after_injection on: 'dependency-logger' do |logger|
+      logger.prefix = '[dependency]'
+    end
   end
 end
+```
 
+Now you can use your module elsewhere in your project:
+```ruby
 class WantsLogging
-  include MyLogger
+  include Dependency::Logger
 
   def some_method_needing_logging
     logger.info 'some info'
+    # logger blocks are also supported
+    logger.invented do
+      find_answer_to_ultimate_question_of life, universe and ObjectSpace.each_object
+      'using the invented log level is computationally expensive so ' \
+      'I pass this computation as a block to avoid computing it in ' \
+      'case the logger filters this level'
+    end
   end
 end
+```
 
-class ThisAlsoWantsIt
-  include MyLogger
-
-  def some_other_method_with_invented_logging
-    logger.invented 'some invented info'
-  end
+If you write this inside `Dependency::Logger`, you will get a `mylogger` method in
+`Dependency::Logger` requiring the `:debug` and `:info` levels and falling back
+to the Ruby logger, identified for injection with `Dependency::Logger`:
+```ruby
+InjectedLogger.use :debug, :info, method_name: :mylogger do
+  require 'logger'
+  { logger: Logger.new(STDERR)
 end
 ```
 
-### On the code injecting a logger:
-
+You can also force the definition of the method elsewhere:
 ```ruby
-InjectedLogger.inject somelogger, on: MyLogger
+InjectedLogger.use :debug, :info, method_name: :mylogger, on: Dependency::OtherLogger do
+  [...]
+end
 ```
 
-### In case some other dependency needs a logger:
-
+If you omit the block, InjectedLogger will provide a default logger (note that
+we are forced to use the `:on` parameter if we have no block).
 ```ruby
-InjectedLogger.inject somelogger, prefix: '[other]', on: Other::Logger
+InjectedLogger.use :debug, :info, on: self
 ```
 
+Note that you do not need to specify the `:on` parameter for `InjectedLogger.use`
+nor `InjectedLogger.after_injection` IFF you provide a block to those methods
+and want to imply `on: self`.
+
 ## Generating the gem
 
 Both bundler and rspec are required to build the gem:

data/lib/injectedlogger/logger.rb

@@ -40,7 +40,7 @@ module InjectedLogger
       if logger and logger != logger_obj
         raise InUse, "#{self} was already using logger #{logger}"
       end
-      inject! logger_obj, levels: levels, fallback: fallback
+      inject! logger_obj, levels: levels, fallback: fallback, prefix: prefix
     end
 
     def inject!(logger_obj, levels: LOGLEVELS, fallback: UNKNOWN, prefix: nil)

data/lib/injectedlogger/version.rb

@@ -1,3 +1,3 @@
 module InjectedLogger
-  VERSION = '0.0.9'
+  VERSION = '0.0.10'
 end

data/lib/injectedlogger.rb

@@ -33,16 +33,18 @@ module InjectedLogger
   # logger method is called, so that it does not 'require' anything if it is not
   # needed. :)
 
-  def self.use(*required, on: nil, method_name: :logger, &blk)
+  def self.use(*required, on: nil, as: nil, method_name: :logger, &blk)
     if on.nil?
       raise InjectedLogger::DefaultInjectionBlockMissing if blk.nil?
       on = blk.binding.eval 'self'
     else
       on = on.singleton_class unless on.is_a? Module
     end
-    on.send :define_method, method_name do
+    target = on
+    on = as unless as.nil?
+    target.send :define_method, method_name do
       # avoid recursion if someone calls logger in the block
-      on.send :remove_method, method_name
+      target.send :remove_method, method_name
       unless InjectedLogger.injected? on: on
         args = blk ? blk.call : nil
         InjectedLogger.inject_logger args, required, on: on
@@ -55,7 +57,7 @@ module InjectedLogger
         required -= thislogger.level_info[:supported]
         raise InjectedLogger::UnsupportedLevels.new(required) unless required.empty?
       end
-      on.send :define_method, method_name do
+      target.send :define_method, method_name do
         thislogger
       end
       thislogger.after_hook.call(thislogger) if thislogger.after_hook
@@ -71,7 +73,7 @@ module InjectedLogger
     { logger: ::Logger.new(STDERR) }
   end
 
-  def self.inject_logger(args, required, on:)
+  def self.inject_logger(args, required, **options)
     args ||= {}
     args = default_logger.merge(args) unless args.has_key? :logger
     logger = args.delete :logger
@@ -80,7 +82,7 @@ module InjectedLogger
       args[:levels].push(required).flatten!
       args[:levels].uniq!
     end
-    args[:on] = on
+    args.merge!(**options)
     InjectedLogger.inject(logger, **args)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: injectedlogger
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.0.10
 platform: ruby
 authors:
 - Alejandro Martinez Ruiz
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-11 00:00:00.000000000 Z
+date: 2014-12-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler