optional_logger 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 354caeb0cca2eda91b7927e823369b519733d69d
-  data.tar.gz: 07589eb6bdf45bf32ac43bf27b1c5141dcbf67d6
+  metadata.gz: 9053d81db875e3d007c47d17c61f451d2c5373ba
+  data.tar.gz: aec324fa8c19728d07ceee530a1dcc88a10a9b5a
 SHA512:
-  metadata.gz: 8ca684990bc9d4015ecf21204ae0819d08ccbb4803aff29a45ff102dcb63cf598cb29c5704d046b9a9710f23b12b264c78fe8afaaca04124df9b8a29844b460f
-  data.tar.gz: 07f03c04e2aa3eb55c8e5bf111d5100c8b494dbc26e95833535226f0adc2618cf8a857e9732e39ceb0b7fd6ef0b8a1c8b5abef5af8f2befa43f616df0f9257d8
+  metadata.gz: 000d11c38ffefad76fb1a7f3829ad21ffa359a58baea45d2c698ecf844857428de7cd761a918ae01c0d5fbf7b6715df6e451e03e4b6f99fcd5f4fcb12503d6c7
+  data.tar.gz: 85c300ccc030a4324224b8b7b89d8c0b0fb8815deeb4e67548ceecf9430df23ad6586db9e8c8d86b7c61d380a62d4fd25b2656121ca5544a3e758b0dc102a7cd

data/.codeclimate.yml

@@ -0,0 +1,9 @@
+---
+engines:
+  fixme:
+    enabled: true
+  rubcop:
+    enabled: true
+ratings:
+  paths:
+  - "lib/**/*"

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# ChangeLog
+
+The following are lists of the notable changes included with each release.
+This is intended to help keep people informed about notable changes between
+versions, as well as provide a rough history.
+
+#### Next Release
+
+#### v1.0.0
+
+* Added documentation around all the classes, modules, constants and methods
+* Added OptionalLogger::Logger level introspection methods (#debug?, #info?,
+  #warn?, #error?, #fatal?)
+* Added OptionalLogger::Logger level convenience methods (#debug, #info, #warn,
+  #error, #fatal, #unknown)
+* Added OptionalLogger::Logger#add and #log methods
+* Added OptionalLogger::Logger class and constructor
+* Added OptionalLogger module skeleton

data/Gemfile

@@ -1,4 +1,6 @@
 source 'https://rubygems.org'
 
+gem "codeclimate-test-reporter", group: :test, require: nil
+
 # Specify your gem's dependencies in optional_logger.gemspec
 gemspec

data/README.md

@@ -1,12 +1,13 @@
+[![Build Status](https://travis-ci.org/Acornsgrow/optional_logger.svg?branch=master)](https://travis-ci.org/Acornsgrow/optional_logger)
+[![Code Climate](https://codeclimate.com/github/Acornsgrow/optional_logger/badges/gpa.svg)](https://codeclimate.com/github/Acornsgrow/optional_logger)
+[![Test Coverage](https://codeclimate.com/github/Acornsgrow/optional_logger/badges/coverage.svg)](https://codeclimate.com/github/Acornsgrow/optional_logger/coverage)
+[![Issue Count](https://codeclimate.com/github/Acornsgrow/optional_logger/badges/issue_count.svg)](https://codeclimate.com/github/Acornsgrow/optional_logger)
+[![Inline docs](http://inch-ci.org/github/Acornsgrow/optional_logger.svg?branch=master)](http://inch-ci.org/github/Acornsgrow/optional_logger)
+
 # OptionalLogger
 
 Easily support application loggers in your gems.
 
-**Note:** At the moment the following is what is under HEAVY development. The
-Usage is currently written based on the planned usage. I will remove this notice
-and udpate the Usage documentation once we have finalized the API and release
-v1.0.0.
-
 ## Why?
 
 OptionalLogger was built out of the need to be able to easily support logging
@@ -35,7 +36,7 @@ accidentally altering the applications logger.
 Add this line to your gem's gemspec file:
 
 ```ruby
-spec.add_dependency 'optional_logger', '~> 0.1'
+spec.add_dependency 'optional_logger', '~> 1.0'
 ```
 
 Or install it yourself as:
@@ -55,7 +56,7 @@ instance as `received_logger`.
 ```ruby
 require 'optional_logger'
 
-logger = OptionalLogger.new(received_logger)
+logger = OptionalLogger::Logger.new(received_logger)
 
 logger.info("some info log message")
 logger.info("Program Name") { "some expensive info log message" }

data/lib/optional_logger/logger.rb

@@ -0,0 +1,189 @@
+require 'logger'
+
+module OptionalLogger
+  # Proxy logger to handle making the proxied logger optional
+  #
+  # The original intent for this optional proxy logger was specifically to be
+  # used inside of gems. This would enable them to receive a logger from the
+  # parenting application/gem and log within their gem without having to worry
+  # about spreading conditionals all over their gem.
+  class Logger
+    # Construct an instance of the proxy logger
+    #
+    # @param logger [#add,#info?,#warn?,#debug?,#fatal?,#error?] the ruby logger
+    #   to wrap
+    # @return the instance of the proxy logger
+    def initialize(logger)
+      @logger = logger
+    end
+
+    # Get the ruby logger instance this proxy logger wraps
+    #
+    # @return the wrapped ruby logger
+    def wrapped_logger
+      @logger
+    end
+
+    # Log a message at the given level if the logger is present
+    #
+    # This isn't generally a recommended method to use while logging in your
+    # libraries. Instead see {#debug}, {#info}, {#warn}, {#error}, {#fatal}, and
+    # {#unknown} as they simplify messaging considerably.
+    #
+    # If you don't want to use the recommended methods and want more control for
+    # some reason. There are a few ways to log a message depending on your usecase.
+    #
+    # The first is probably the most generally useful, which is logging messages
+    # that aren't costly to build. This is accomplished as follows:
+    #
+    #     add(::Logger::INFO, 'some message', nil)
+    #
+    # The second is for use cases in which it is costly to build the log message
+    # as it avoids executing the block until the logger knows that the message
+    # level will be displayed. If the message level would not be displayed then
+    # the block is not executed, saving the performance cost of building the
+    # message.
+    #
+    #     add(::Logger::INFO) { 'some expensive message' }
+    #
+    # The third gives you the benefits of preventing uneeded expensive messages
+    # but also allows you to override the program name that will be prefixed on
+    # that log message. This is accomplished as follows.
+    #
+    #     add(::Logger::INFO, nil, 'overridden progname') { 'some expensive message' }
+    #
+    # It is important to realize that if the wrapped logger is nil then this
+    # method will simply do nothing.
+    #
+    # @param severity ::Logger::DEBUG, ::Logger::INFO, ::Logger::WARN,
+    #   ::Logger::ERROR, ::Logger::FATAL, ::Logger::UNKNOWN
+    # @param message the optional message to log
+    # @param progname_or_message the optional program name or message, if
+    #   message is nil, and a block is NOT provided, then progname_or_message is
+    #   treated as a message rather than progname
+    # @param block the block to evaluate and yield a message, generally useful
+    #   preventing building of expensive messages when message of that level
+    #   aren't allowed
+    def add(severity, message = nil, progname_or_message = nil, &block)
+      @logger.add(severity, message, progname_or_message, &block) if @logger
+    end
+    alias log add
+
+    # Log a message at the info level if the logger is present
+    #
+    # There are a few ways to log a message depending on your usecase.
+    #
+    # The first is probably the most generally useful, which is logging messages
+    # that aren't costly to build. This is accomplished as follows:
+    #
+    #     info('some message')
+    #
+    # The second is for use cases in which it is costly to build the log message
+    # as it avoids executing the block until the logger knows that the message
+    # level will be displayed. If the message level would not be displayed then
+    # the block is not executed, saving the performance cost of building the
+    # message.
+    #
+    #     info { 'some expensive message' }
+    #
+    # The third gives you the benefits of preventing uneeded expensive messages
+    # but also allows you to override the program name that will be prefixed on
+    # that log message. This is accomplished as follows.
+    #
+    #     info('overridden progname') { 'some expensive message' }
+    #
+    # It is important to realize that if the wrapped logger is nil then this
+    # method will simply do nothing.
+    #
+    # @param progname_or_message the progname or message depending on scenario
+    # @param block the optional block depending on scenario
+    def info(progname_or_message = nil, &block)
+      add(::Logger::INFO, nil, progname_or_message, &block)
+    end
+
+    # Log a message at the warn level if the logger is present
+    #
+    # See {#info} for details on specifics around various scenarios
+    def warn(progname_or_message = nil, &block)
+      add(::Logger::WARN, nil, progname_or_message, &block)
+    end
+
+    # Log a message at the debug level if the logger is present
+    #
+    # See {#info} for details on specifics around various scenarios
+    def debug(progname_or_message = nil, &block)
+      add(::Logger::DEBUG, nil, progname_or_message, &block)
+    end
+
+    # Log a message at the error level if the logger is present
+    #
+    # See {#info} for details on specifics around various scenarios
+    def error(progname_or_message = nil, &block)
+      add(::Logger::ERROR, nil, progname_or_message, &block)
+    end
+
+    # Log a message at the fatal level if the logger is present
+    #
+    # See {#info} for details on specifics around various scenarios
+    def fatal(progname_or_message = nil, &block)
+      add(::Logger::FATAL, nil, progname_or_message, &block)
+    end
+
+    # Log a message at the unknown level if the logger is present
+    #
+    # See {#info} for details on specifics around various scenarios
+    def unknown(progname_or_message = nil, &block)
+      add(::Logger::UNKNOWN, nil, progname_or_message, &block)
+    end
+
+    # Check if info level messages are allowed by loggers current configuration
+    #
+    # @return [Boolean] true if the current severity level allows for the
+    #   printing of info messages and false otherwise. It will also return false
+    #   if there is no logger present.
+    def info?
+      return @logger.info? if @logger
+      false
+    end
+
+    # Check if warn level messages are allowed by loggers current configuration
+    #
+    # @return [Boolean] true if the current severity level allows for the
+    #   printing of warn messages and false otherwise. It will also return false
+    #   if there is no logger present.
+    def warn?
+      return @logger.warn? if @logger
+      false
+    end
+
+    # Check if debug level messages are allowed by loggers current configuration
+    #
+    # @return [Boolean] true if the current severity level allows for the
+    #   printing of debug messages and false otherwise. It will also return false
+    #   if there is no logger present.
+    def debug?
+      return @logger.debug? if @logger
+      false
+    end
+
+    # Check if fatal level messages are allowed by loggers current configuration
+    #
+    # @return [Boolean] true if the current severity level allows for the
+    #   printing of fatal messages and false otherwise. It will also return false
+    #   if there is no logger present.
+    def fatal?
+      return @logger.fatal? if @logger
+      false
+    end
+
+    # Check if error level messages are allowed by loggers current configuration
+    #
+    # @return [Boolean] true if the current severity level allows for the
+    #   printing of error messages and false otherwise. It will also return false
+    #   if there is no logger present.
+    def error?
+      return @logger.error? if @logger
+      false
+    end
+  end
+end

data/lib/optional_logger/version.rb

@@ -1,3 +1,4 @@
 module OptionalLogger
-  VERSION = "0.1.0"
+  # The version of the library
+  VERSION = "1.0.0"
 end

data/lib/optional_logger.rb

@@ -1,5 +1,7 @@
-require "optional_logger/version"
+require 'optional_logger/version'
+require 'optional_logger/logger'
 
+# Top-level namespace for a library providing an optional logger and supporting
+# functionality around it
 module OptionalLogger
-  # Your code goes here...
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: optional_logger
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Andrew De Ponte
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-10-08 00:00:00.000000000 Z
+date: 2016-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -59,9 +59,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".codeclimate.yml"
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -70,6 +72,7 @@ files:
 - bin/console
 - bin/setup
 - lib/optional_logger.rb
+- lib/optional_logger/logger.rb
 - lib/optional_logger/version.rb
 - optional_logger.gemspec
 homepage: http://github.com/Acornsgrow/optional_logger