polylog 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 30bf99c4368b2308581792e2f887e75e2533b1ef
+  data.tar.gz: 59f9b5c104970d4d73244db7381c9a197358271c
+SHA512:
+  metadata.gz: 29508ecd47dd8b423e799f8a7c71b8dc7bb8a8ed8de2120b15563f06e44bd126421ef342cedf615fc8f02967a839d9a13321d4641311f59823ca874d8bfda15d
+  data.tar.gz: d00c98550192a44ce783f61bd61c5c087a9c669e643921dee8efbe4a39c1bb6ac24d446049d1c63b3f1ffcd1337565f59133614b6c75d10dc698751efd3a1bae

data/.gitignore

@@ -0,0 +1,19 @@
+# The list of files that should be ignored by Mr Bones.
+# Lines that start with '#' are comments.
+#
+# A .gitignore file can be used instead by setting it as the ignore
+# file in your Rakefile:
+#
+#   Bones {
+#     ignore_file  '.gitignore'
+#   }
+#
+# For a project with a C extension, the following would be a good set of
+# exclude patterns (uncomment them if you want to use them):
+# *.[oa]
+# *~
+announcement.txt
+coverage
+doc
+pkg
+vendor

data/History.txt

@@ -0,0 +1,4 @@
+== 0.1.0 / 2013-10-14
+
+* 1 major enhancement
+  * Birthday!

data/LICENSE.md

@@ -0,0 +1,22 @@
+The MIT License
+
+Copyright (c) 2012-2013 by Tim Pease
+
+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

@@ -0,0 +1,200 @@
+## polylog
+
+Decoupling the logging layer since 2012
+
+### Description
+
+Logging provides a simple mechanism for observing the state of a running
+application, and most ruby gems and applications use some sort of logging.
+This is great! Setting up a logging infrastructure across various gems and
+applications is the not so great part.
+
+In a Rails application it is assumed that all gems will use the `Rails.logger`
+and that's the end of it. So as a gem developer you can just grab the Rails
+logger and be done. The downside of that choice is your gem is now locked to
+Rails and cannot be used elsewhere. Another option is to provide a
+`setup( options = {} )` method (or something similar) and the application can
+provide you with a logger. The downside of that choice is that applications
+need to configure your gem and every other gem that adopts the same
+convention.
+
+A third option is to be clever and see if the Rails module exists when your
+gem is loaded and then just grab the Rails logger. This makes testing
+difficult and can lead to unintended side effects. Eschew clever code.
+
+Polylog is an agreement between the gem developer and the application
+developer on how logging is configured. For the gem developer, instead of
+assuming the Rails environment or providing a `setup` method you ask Polylog
+for a logger instance. For the application developer, instead of configuring
+logging for multiple gems you configure Polylog with the logging
+infrastructure you plan on using.
+
+The gem developer no longer needs to worry what the application is going to
+do. The logging for the gem does not need to be configured by the application.
+Conversely, the application does not have to configure logging for every gem.
+The application provides the logging infrastructure once to Polylog.
+
+Let's see what this looks like in practice.
+
+### Usage
+
+The two primary use cases for Polylog are:
+
+* obtaining a logger
+* configuring the logging provider
+
+Obtaining a logger is the domain of the gem developer (or supporting
+application code). Configuring the logging provider is the domain of the
+application.
+
+#### Obtaining a Logger
+
+Obtaining a logger is simple:
+
+```ruby
+Polylog.logger self
+```
+
+Passing `self` is optional but recommended. It provides context to Polylog and
+allows object specific loggers to be returned (actually, they are class
+specific). The application can configure different logger instances to be
+returned depending upon the requesting class. This is useful if you want to
+enable debugging for just one portion of the application.
+
+In practice, you can create a module and include it where you want a `logger`
+method to be available:
+
+```ruby
+module MyGem::Logger
+  def logger
+    Polylog.logger self
+  end
+end
+
+class MyGem::SomeClass
+  include MyGem::Logger
+end
+```
+
+In this example each class in `MyGem` can obtain its own unique logger if
+Polylog is configured to do so. But you can also develop your gem to use a
+single logger instance, too.
+
+```ruby
+module MyGem::Logger
+  def logger
+    Polylog.logger 'MyGem'
+  end
+end
+```
+
+Instead of passing `self` the top level namespace of the gem is used. Anywhere
+this logger module is included the returned logger will be the same.
+
+#### Configuring the Logging Provider
+
+Without any configuration Polylog with provide a null logger for all requests.
+This logger implements all the methods of the Ruby `Logger` class, but all the
+methods do nothing. Not very useful except for preventing exceptions.
+
+So lets log everything to standard out (a useful start):
+
+```ruby
+provider = Polylog::SoloProvider.new(Logger.new(STDOUT))
+Polylog.register_provider 'stdout', provider
+
+Polylog.use_provider 'stdout'
+```
+
+Yikes! That looks pretty complicated. The three lines of code are the three
+steps to configuring a logging provider.
+
+The first line creates the provider we are going to use. The `SoloProvider`
+provides exactly one logger. In the example it is providing a standard Ruby
+`Logger` configured to log everything to `STDOUT`.
+
+The second line registers the provider we created with Polylog. Multiple
+providers can be registered but only one will be used. Each provider is
+registered with a unique name. Logging frameworks like
+[Log4r](https://github.com/colbygk/log4r), [Logging](https://github.com/twp/logging),
+and [Scrolls](https://github.com/asenchi/scrolls) can register themselves with
+Polylog. In this case, applications can skip the provider creation and just use
+one that is already registered.
+
+The third line tells Polylog to use the 'stdout' provider. All calls to
+`Polylog.logger()` will lookup this provider and then call the `logger()`
+method implemented by the provider. In this case, it is the solo-provider
+which returns a STDOUT logger instance for all requests.
+
+Lets register a few more providers:
+
+```ruby
+Polylog.register_provider 'stdout', Polylog::SoloProvider.new(Logger.new(STDOUT))
+Polylog.register_provider 'stderr', Polylog::SoloProvider.new(Logger.new(STDERR))
+Polylog.register_provider 'file',   Polylog::SoloProvider.new(Logger.new('app.log'))
+
+Polylog.use_provider 'file'
+```
+
+Even though we have providers for logging to `STDOUT` and `STDERR`, we have
+chosen to send all our logs to a file instead. It is easy enough to swap
+providers now. Because we are using the solo-provider all log messages will
+end up going to the same destination.
+
+We can send log messages to multiple destinations by using a multi-provider.
+
+```ruby
+provider = Polylog::MultiProvider.new(Logger.new(STDOUT))
+provider['MyClass'] = Logger.new('my_class.log')
+
+Polylog.register_provider 'my_class', provider
+Polylog.use_provider 'my_class'
+
+Polylog.logger             # STDOUT logger
+Polylog.logger(MyClass)    # 'my_class.log' logger
+```
+
+The multi-provider can return more than one logger instance. It is configured
+to return a default logger for all requests. However, a different logger can
+be returned based on the Class of the object passed to the `Polylog.logger()`
+method. In the example we are passing in `MyClass` to get the specific logger
+for that class; instances of `MyClass` would also return the same logger.
+
+If you want to get more creative with your logging configuration, I highly
+recommend checking out the [Logging](https://github.com/twp/logging)
+framework. It is designed to provide unique loggers and logging destinations.
+
+#### Integrating With Rails
+
+It would be wonderful if Polylog were integrated directly with Rails. This
+would require Rails to adopt the `Polylog.logger()` style of acquiring a
+logger instance. However, until that time happens, Polylog needs to be
+configured with a provider that returns the `Rails.logger` instance.
+
+```ruby
+Polylog.register_provider 'rails', Polylog::SoloProvider.new(Rails.logger)
+Polylog.use_provider 'rails'
+```
+
+And that's pretty much it.
+
+### Developing
+
+Polylog makes use of Mr Bones to handle general project tasks such as running
+tests, generating a gem file, interacting with GitHub, and publishing
+to rubygems.org. A `script/bootstrap` script is provided to setup the
+development environment:
+
+```shell
+script/bootstrap
+```
+
+After this is run, you can use `rake` normally to run tests. You can view all
+the available rake tasks via `rake -T`.
+
+```shell
+rake -T
+rake spec
+```
+
+Thank you for reading! Any contributions are greatly appreciated.

data/Rakefile

@@ -0,0 +1,26 @@
+
+begin
+  require 'bones'
+rescue LoadError
+  abort '### Please install the "bones" gem ###'
+end
+
+task :default => 'spec:run'
+task 'gem:release' => 'spec:run'
+
+
+Bones {
+  name     'polylog'
+  authors  'Tim Pease'
+  email    'tim.pease@gmail.com'
+  url      'http://rubygems.org/gems/polylog'
+
+  spec.opts << '--color' << '--format documentation'
+
+  use_gmail
+
+  depend_on  'bones-rspec',  :development => true
+  depend_on  'bones-git',    :development => true
+  depend_on  'rdoc',         :development => true
+}
+

data/lib/polylog.rb

@@ -0,0 +1,162 @@
+
+module Polylog
+  extend self
+
+  # Request a logger instance for the given object from the configured
+  # provider.
+  #
+  # object - Any ruby object
+  #
+  # Returns a logger instance from the provider.
+  def logger( object = nil )
+    name = logger_name object
+    provider.logger name
+  end
+
+  # Return the currently selected provider. If a provider has not yet been
+  # specified, then the "null" provider will be used.
+  #
+  # Returns a logger provider.
+  def provider
+    use_provider('null') unless defined? @provider
+    @provider
+  end
+
+  # Returns the list of available providers as an Array of Strings. These
+  # names are used to select which provider to use.
+  def providers
+    @providers.keys
+  end
+
+  # Configure the logger provider that will be used by Polylog. The provider
+  # must already be registered using the same `name`.
+  #
+  # name - The provider name as a String.
+  #
+  # Returns the logger provider.
+  # Raises a Polylog::UnknownProvider exception.
+  def use_provider( name )
+    name = name.to_s
+    raise Polylog::UnknownProvider, "unknown provider: #{name.inspect}" unless @providers.key? name
+
+    @provider = @providers[name]
+  end
+
+  # Register a logger provider under the given name. The provider can be any
+  # Ruby object that responds to the `logger` method and returns valid logger
+  # instances. An exception is raised if the provider does not respond to the
+  # `logger` method or the `logger` method does not have an arity of 1.
+  #
+  # name     - The provider name as a String.
+  # provider - The provider object that responds to the `logger` method.
+  #
+  # Returns the logger provider.
+  # Raises a Polylog::InvalidProvider exception.
+  def register_provider( name, provider )
+    @providers ||= Hash.new
+    name = name.to_s
+
+    unless provider.respond_to?(:logger)
+      raise Polylog::InvalidProvider, "`logger` method not found for provider #{name.inspect}"
+    end
+
+    arity = provider.method(:logger).arity
+    unless 1 == arity
+      raise Polylog::InvalidProvider, "`logger` method arity must be 1; arity is #{arity} for provider #{name.inspect}"
+    end
+
+    @providers[name] = provider
+  end
+
+  # Internal: Given any ruby object, try to construct a sensible logger name
+  # to use for looking up specific logger instances from a provider. For
+  # nearly every object passed in this will be the class name of the instance.
+  #
+  # If you pass in `nil` or a String then the original object is return.
+  # Symbols will be converted to Strings.
+  #
+  # The only objects we cannot generate a logger name for are anonymous
+  # modules. For these we just return `nil`.
+  #
+  # object - Any ruby object
+  #
+  # Returns the logger name String or nil.
+  def logger_name( object )
+    case object
+    when nil, String; object
+    when Symbol; object.to_s
+    when Module; logger_name_for_module(object)
+    when Object; logger_name_for_module(object.class)
+    end
+  end
+
+  # Internal: Generate logger names for classes, modules, singleton classes,
+  # and anonymous modules. For all of these we use the class name or the
+  # module name. For anonymous modules we return `nil`.
+  #
+  # mod - A Module or Class
+  #
+  # Returns the logger name String or nil.
+  def logger_name_for_module( mod )
+    return mod.name unless mod.name.nil? or mod.name.empty?
+
+    # check if we have a metaclass (or eigenclass)
+    if mod.ancestors.include? Class
+      mod.inspect =~ %r/#<Class:([^#>]+)>/
+      return $1
+    end
+
+    # see if we have a superclass
+    if mod.respond_to? :superclass
+      return logger_name_for_module(mod.superclass)
+    end
+
+    # we have an anonymous module
+    return nil
+  end
+
+  LIBPATH = ::File.expand_path('../', __FILE__)
+  PATH    = ::File.dirname(LIBPATH)
+
+  # Returns the version String for the library.
+  def version
+    @version ||= File.read(path('version.txt')).strip
+  end
+
+  # Internal: Returns the library path for the module. If any arguments are
+  # given, they will be joined to the end of the library path using
+  # `File.join`.
+  def libpath( *args )
+    rv =  args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+    if block_given?
+      begin
+        $LOAD_PATH.unshift LIBPATH
+        rv = yield
+      ensure
+        $LOAD_PATH.shift
+      end
+    end
+    return rv
+  end
+
+  # Internal: Returns the path for the module. If any arguments are given,
+  # they will be joined to the end of the path using `File.join`.
+  def path( *args )
+    rv = args.empty? ? PATH : ::File.join(PATH, args.flatten)
+    if block_given?
+      begin
+        $LOAD_PATH.unshift PATH
+        rv = yield
+      ensure
+        $LOAD_PATH.shift
+      end
+    end
+    return rv
+  end
+
+end
+
+require Polylog.libpath('polylog/errors')
+require Polylog.libpath('polylog/solo_provider')
+require Polylog.libpath('polylog/multi_provider')
+require Polylog.libpath('polylog/null_logger')

data/lib/polylog/errors.rb

@@ -0,0 +1,15 @@
+
+module Polylog
+
+  # Parent class for all Polylog errors.
+  Error = Class.new StandardError
+
+  # This is error is raised when an unknown provider is requested by the user.
+  UnknownProvider = Class.new Error
+
+  # This is error is raised when a provider is registered and it does not
+  # respond to the `logger` method or the `logger` method has an arity other
+  # than 1.
+  InvalidProvider = Class.new Error
+
+end

data/lib/polylog/multi_provider.rb

@@ -0,0 +1,80 @@
+
+module Polylog
+
+  # The purpose of a MultiProvider is to provide a default logger instance
+  # when requested. Other loggers can be provided by registering them with the
+  # provider under the appropriate logger name. So when this name is passed to
+  # the `logger` method the registered logger instance will be returned.
+  #
+  # The example below shows how to use the MultiProvider to send all log
+  # messages from all instances of a single class to a log file instead of
+  # STDOUT. You might want to do this when debugging the class; you can set
+  # the logger level to debug and capture lots of text to a single location.
+  #
+  # Examples
+  #
+  #     provider = Polylog::MultiProvider.new(Logger.new(STDOUT))
+  #     provider['MyClass'] = Logger.new('my_class.log')
+  #
+  #     Polylog.register_provider 'example', provider
+  #     Polylog.use_provider 'example'
+  #
+  #     logger          = Polylog.logger             # STDOUT logger
+  #     my_class_logger = Polylog.logger(MyClass)    # 'my_class.log' logger
+  #
+  class MultiProvider
+
+    # Create a new MultiProvider configured with the given logger as the
+    # default logger. Other loggers can be added to the provider. These will
+    # be returned by the provider (instead of the default logger) when their
+    # name is passed to the `logger` method.
+    #
+    # logger - The default logger to return.
+    def initialize( logger )
+      @hash = Hash.new
+      @default_logger = logger
+    end
+
+    # Accessor for getting and setting the default logger.
+    attr_accessor :default_logger
+
+    # Returns the named logger if it is present in the provider. If the named
+    # logger is not present then the default logger is returned.
+    #
+    # name - The logger name as a String.
+    def logger( name )
+      return default_logger if name.nil?
+      @hash.fetch(name, default_logger)
+    end
+
+    # Returns the logger or `nil` if the logger is not present.
+    #
+    # name - The logger name as a String.
+    def []( name )
+      @hash[name]
+    end
+
+    # Add a logger provider under the given name.
+    #
+    # name   - The logger name as a String.
+    # logger - The logger.
+    #
+    # Returns the logger.
+    def []=( name, logger )
+      @hash[name] = logger
+    end
+
+    # Returns an Array with the names of the loggers present in the provider.
+    def loggers
+      @hash.keys
+    end
+
+    # Returns `true` if the logger is present in the provider.
+    #
+    # name - The logger name as a String.
+    def logger?( name )
+      @hash.key? name
+    end
+
+  end
+end

data/lib/polylog/null_logger.rb

@@ -0,0 +1,28 @@
+
+module Polylog
+
+  # This is a no-op logger that implements the principal methods from the
+  # standard Ruby logger. All methods do nothing and return either `false`
+  # or `nil`.
+  class NullLogger
+    def <<(msg) nil end
+    def close() nil end
+
+    def debug?() false end
+    alias :info?  :debug?
+    alias :warn?  :debug?
+    alias :error? :debug?
+    alias :fatal? :debug?
+
+    def add(*args) false end
+    alias :debug   :add
+    alias :info    :add
+    alias :warn    :add
+    alias :error   :add
+    alias :fatal   :add
+    alias :unknown :add
+    alias :log     :add
+  end
+
+  register_provider('null', SoloProvider.new(NullLogger.new))
+end

data/lib/polylog/solo_provider.rb

@@ -0,0 +1,41 @@
+module Polylog
+
+  # The purpose of the SoloProvider is to return a single instance for all
+  # logger requests. You would use this provider to supply all parts of the
+  # application with the exact same logger.
+  #
+  # The NullLogger uses the SoloProvider to register itself under the "null"
+  # provider name.
+  #
+  # Examples
+  #
+  #     Polylog.register_provider 'stdout', Polylog::SoloProvider.new(Logger.new(STDOUT))
+  #     Polylog.register_provider 'stderr', Polylog::SoloProvider.new(Logger.new(STDERR))
+  #     Polylog.register_provider 'file',   Polylog::SoloProvider.new(Logger.new('app.log'))
+  #
+  #     Polylog.use_provider 'stderr'
+  #     logger = Polylog.logger     # returns a STDERR logger
+  #
+  #     Polylog.use_provider 'file'
+  #     logger = Polylog.logger     # returns an 'app.log' file logger
+  #
+  class SoloProvider
+
+    # Constructs a new SoloProvider that will provide the same instance for
+    # each request for a logger.
+    #
+    # logger - The logger instance that will be provided.
+    def initialize( logger )
+      @logger = logger
+    end
+
+    # Returns the same logger instance for all requests. The `name` is not
+    # used by this this method.
+    #
+    # name - The logger name as a String
+    def logger( name )
+      @logger
+    end
+
+  end
+end

data/script/bootstrap

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+
+gem list -i bones >/dev/null 2>&1
+rc=$?
+if [[ $rc != 0 ]]; then
+  gem install bones
+fi
+
+rake gem:install_dependencies

data/spec/polylog/multi_provider_spec.rb

@@ -0,0 +1,41 @@
+
+require File.expand_path('../../spec_helper', __FILE__)
+
+describe Polylog::SoloProvider do
+  attr_reader :provider
+
+  context 'with only a default logger' do
+    before(:all) { @provider = Polylog::MultiProvider.new 'Multipass' }
+
+    it 'provides the same default logger' do
+      default = provider.default_logger
+
+      expect(provider.logger 'foo').to equal default
+      expect(provider.logger 'bar').to equal default
+    end
+  end
+
+  context 'when configured with multiple loggers' do
+    before(:all) do
+      @provider = Polylog::MultiProvider.new 'Multipass'
+      @provider['foo'] = 'FooLogger'
+      @provider['bar'] = 'BarLogger'
+    end
+
+    it 'provides loggers based on name' do
+      expect(provider.logger 'foo').to equal provider['foo']
+      expect(provider.logger 'bar').to equal provider['bar']
+      expect(provider.logger 'baz').to equal provider.default_logger
+    end
+
+    it 'returns the list of available loggers' do
+      expect(provider.loggers).to match_array %w[foo bar]
+    end
+
+    it 'determines if a logger is present' do
+      expect(provider.logger? 'foo').to be_true
+      expect(provider.logger? 'bar').to be_true
+      expect(provider.logger? 'baz').to be_false
+    end
+  end
+end

data/spec/polylog/null_logger_spec.rb

@@ -0,0 +1,82 @@
+
+require File.expand_path('../../spec_helper', __FILE__)
+
+describe Polylog::NullLogger do
+  attr_reader :null_logger
+  before(:all) { @null_logger = Polylog::NullLogger.new }
+
+  it 'responds to `<<`' do
+    expect(null_logger).to respond_to :<<
+    expect(null_logger << 'foo').to be_nil
+  end
+
+  it 'responds to `close`' do
+    expect(null_logger).to respond_to :close
+    expect(null_logger.close).to be_nil
+  end
+
+  it 'responds to `debug?`' do
+    expect(null_logger).to respond_to :debug?
+    expect(null_logger.debug?).to be_false
+  end
+
+  it 'responds to `info?`' do
+    expect(null_logger).to respond_to :info?
+    expect(null_logger.info?).to be_false
+  end
+
+  it 'responds to `warn?`' do
+    expect(null_logger).to respond_to :warn?
+    expect(null_logger.warn?).to be_false
+  end
+
+  it 'responds to `error?`' do
+    expect(null_logger).to respond_to :error?
+    expect(null_logger.error?).to be_false
+  end
+
+  it 'responds to `fatal?`' do
+    expect(null_logger).to respond_to :fatal?
+    expect(null_logger.fatal?).to be_false
+  end
+
+  it 'responds to `add`' do
+    expect(null_logger).to respond_to :add
+    expect(null_logger.add 'foo').to be_false
+  end
+
+  it 'responds to `debug`' do
+    expect(null_logger).to respond_to :debug
+    expect(null_logger.debug 'foo').to be_false
+  end
+
+  it 'responds to `info`' do
+    expect(null_logger).to respond_to :info
+    expect(null_logger.info 'foo').to be_false
+  end
+
+  it 'responds to `warn`' do
+    expect(null_logger).to respond_to :warn
+    expect(null_logger.warn 'foo').to be_false
+  end
+
+  it 'responds to `error`' do
+    expect(null_logger).to respond_to :error
+    expect(null_logger.error 'foo').to be_false
+  end
+
+  it 'responds to `fatal`' do
+    expect(null_logger).to respond_to :fatal
+    expect(null_logger.fatal 'foo').to be_false
+  end
+
+  it 'responds to `unknown`' do
+    expect(null_logger).to respond_to :unknown
+    expect(null_logger.unknown 'foo').to be_false
+  end
+
+  it 'responds to `log`' do
+    expect(null_logger).to respond_to :log
+    expect(null_logger.log 'foo').to be_false
+  end
+end

data/spec/polylog/solo_provider_spec.rb

@@ -0,0 +1,14 @@
+
+require File.expand_path('../../spec_helper', __FILE__)
+
+describe Polylog::SoloProvider do
+  attr_reader :provider
+  before(:all) { @provider = Polylog::SoloProvider.new 'Han Solo' }
+
+  it 'always provides the same instance' do
+    str = provider.logger nil
+
+    expect(provider.logger 'foo').to equal str
+    expect(provider.logger 'bar').to equal str
+  end
+end

data/spec/polylog_spec.rb

@@ -0,0 +1,124 @@
+
+require File.expand_path('../spec_helper', __FILE__)
+
+describe Polylog do
+
+  it 'provides a canonical version string' do
+    expect(Polylog.version).to match %r/^\d+\.\d+\.\d+$/
+  end
+
+  context 'without any configuration' do
+    it 'provides a null logger' do
+      expect(Polylog.logger).to be_an_instance_of Polylog::NullLogger
+    end
+
+    it 'provides the smae null logger for all requests' do
+      null_logger = Polylog.logger
+
+      expect(Polylog.logger 'foo').to equal null_logger
+      expect(Polylog.logger 'bar').to equal null_logger
+    end
+
+    it 'only has the null provider registered' do
+      expect(Polylog.providers).to eq %w[null]
+    end
+  end
+
+  context 'when registering a provider' do
+    it 'raises an error for providers that have no `logger` method' do
+      expect {
+        Polylog.register_provider('nope', Object.new)
+      }.to raise_error(Polylog::InvalidProvider, /method not found for provider/)
+    end
+
+    it 'raises an error when the `logger` method has the wrong airty' do
+      provider = Object.new
+      class << provider
+        def logger() nil; end
+      end
+
+      expect {
+        Polylog.register_provider('nope', provider)
+      }.to raise_error(Polylog::InvalidProvider, /method arity must be 1/)
+    end
+
+    it 'adds the provider to the registry' do
+      expect(Polylog.providers).not_to include('test1')
+
+      provider = Polylog::SoloProvider.new(:test1)
+      Polylog.register_provider 'test1', provider
+
+      expect(Polylog.providers).to include('test1')
+    end
+
+    it 'overwrites existing providers' do
+      provider = Polylog::SoloProvider.new(:test2)
+      Polylog.register_provider 'test2', provider
+      expect(Polylog.providers).to include('test2')
+      Polylog.use_provider 'test2'
+
+      provider = Polylog::SoloProvider.new(:overwrite)
+      Polylog.register_provider 'test2', provider
+
+      expect(Polylog.logger).to equal :test2
+      Polylog.use_provider 'test2'
+      expect(Polylog.logger).to equal :overwrite
+    end
+  end
+
+  context 'when selecting a provider to use' do
+    it 'raises an error for unknown providers' do
+      expect {
+        Polylog.use_provider 'foo'
+      }.to raise_error(Polylog::UnknownProvider, 'unknown provider: "foo"')
+    end
+
+    it 'can use a registered provider' do
+      provider = Polylog::SoloProvider.new(:test3)
+      Polylog.register_provider 'test3', provider
+
+      expect(Polylog.providers).to include('test3')
+
+      Polylog.use_provider 'test3'
+      expect(Polylog.logger).to equal :test3
+    end
+  end
+
+  context 'when generating logger names' do
+    it 'uses nil as the default' do
+      expect(Polylog.logger_name nil).to be_nil
+    end
+
+    it 'uses String names as is' do
+      expect(Polylog.logger_name 'foo').to eql 'foo'
+    end
+
+    it 'converts Symbols to Strings' do
+      expect(Polylog.logger_name :foo).to eql 'foo'
+    end
+
+    it 'uses Module names' do
+      expect(Polylog.logger_name Enumerable).to eql 'Enumerable'
+    end
+
+    it 'uses Class names for instances' do
+      expect(Polylog.logger_name Object).to eql 'Object'
+      expect(Polylog.logger_name Object.new).to eql 'Object'
+      expect(Polylog.logger_name []).to eql 'Array'
+    end
+
+    it 'uses the orignal Class name for singletons (eigenclasses)' do
+      ary = []
+      eigen = class << ary; self; end
+
+      expect(Polylog.logger_name eigen).to eql 'Array'
+    end
+
+    it 'gives up when confronted with an anonymous module' do
+      m = Module.new { def foo() nil end }
+      expect(Polylog.logger_name m).to be_nil
+    end
+  end
+
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,31 @@
+
+require File.expand_path('../../lib/polylog', __FILE__)
+
+RSpec.configure do |config|
+  config.before(:all) { Polylog.reset! }
+
+  # == Mock Framework
+  #
+  # RSpec uses it's own mocking framework by default. If you prefer to
+  # use mocha, flexmock or RR, uncomment the appropriate line:
+  #
+  # config.mock_with :mocha
+  # config.mock_with :flexmock
+  # config.mock_with :rr
+end
+
+module Polylog
+  # Only used for testing. This resets the Polylog providers configuration to
+  # its uninitialized state.
+  def reset!
+    remove_instance_variable :@provider  if defined? @provider
+
+    @providers.keys.each do |key|
+      next if key == 'null'
+      @providers.delete key
+    end
+
+    self
+  end
+end
+

data/version.txt

@@ -0,0 +1 @@
+0.1.0

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: polylog
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tim Pease
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-10-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bones-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 2.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 2.0.1
+- !ruby/object:Gem::Dependency
+  name: bones-git
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 3.12.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 3.12.2
+- !ruby/object:Gem::Dependency
+  name: bones
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 3.8.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 3.8.1
+description: ''
+email: tim.pease@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- History.txt
+files:
+- .gitignore
+- History.txt
+- LICENSE.md
+- README.md
+- Rakefile
+- lib/polylog.rb
+- lib/polylog/errors.rb
+- lib/polylog/multi_provider.rb
+- lib/polylog/null_logger.rb
+- lib/polylog/solo_provider.rb
+- script/bootstrap
+- spec/polylog/multi_provider_spec.rb
+- spec/polylog/null_logger_spec.rb
+- spec/polylog/solo_provider_spec.rb
+- spec/polylog_spec.rb
+- spec/spec_helper.rb
+- version.txt
+homepage: http://rubygems.org/gems/polylog
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options:
+- --main
+- README.md
+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'
+requirements: []
+rubyforge_project: polylog
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: ''
+test_files: []