# This is a combination of 7 commits.

# This is the 1st commit message:
Added core logging functionality (feedjira#312)
Added core configuration functionality (feedjira#340)

# This is the commit message #2:

Add convenience Methods for logging Messages (feedjira#312)

# This is the commit message feedjira#3:

Replace warn with logger (feedjira#312)

# This is the commit message feedjira#4:

Add logger messages for shadowed exceptions (feedjira#312)

# This is the commit message feedjira#5:

Enhaced Documentation for LogLevel (feedjira#312)

# This is the commit message feedjira#6:

Fixed some Logger related issues (feedjira#312)

# This is the commit message feedjira#7:

Added local DEFAULTS configuration (feedjira#312,feedjira#340)

README.md

@@ -12,3 +12,32 @@ feeds as quickly as possible. Version 1.0 was recently released and with it an
 [f]: http://feedjira.com
 
 There you'll find documentation, examples, announcements and more.
+
+## Usage
+
+### Configuration
+
+Feedjira Configuration Options could be set either by calling them directly via
+
+```ruby
+Feedjira::Config.logger = Logger.new('foo.log')
+```
+
+or using a block
+
+```ruby
+Feedjira.configure do |config|
+  config.logger = Logger.new('foo.log')
+end
+```
+
+#### Logger
+
+Per default Feedjira will log all messages to STDOUT. If you are using Feedjira in your own app you could pass your logger instance to Feedjira to use a single logger for the whole application.
+Feedjira will always use 'Feedjira' as ProgName so you can identify specific Feedjira log entries.
+
+The [level](http://ruby-doc.org/stdlib-2.1.0/libdoc/logger/rdoc/Logger.html) of logger can be set as follows
+
+```ruby
+Feedjira::Config.logger.level = Logger::DEBUG
+```

lib/feedjira.rb

@@ -3,7 +3,9 @@
 require 'faraday_middleware'
 require 'sax-machine'
 require 'loofah'
+require 'logger'
 
+require 'feedjira/config'
 require 'feedjira/core_ext'
 require 'feedjira/date_time_utilities/date_time_pattern_parser'
 require 'feedjira/date_time_utilities/date_time_language_parser'
@@ -12,6 +14,7 @@
 require 'feedjira/feed_entry_utilities'
 require 'feedjira/feed_utilities'
 require 'feedjira/feed'
+require 'feedjira/logger'
 require 'feedjira/parser'
 require 'feedjira/parser/rss_entry'
 require 'feedjira/parser/rss'

lib/feedjira/config.rb

@@ -0,0 +1,27 @@
+module Feedjira
+  # Set configuration options by block
+  # Feedjira.configure do |config|
+  #   config.logger = my_logger_instance
+  # end
+
+  def self.configure
+    yield Config
+  end
+
+  module Config
+    DEFAULTS = {
+      logger_io: STDOUT,
+      logger_level: Logger::WARN
+    }.freeze
+
+    class << self
+      def logger=(logger)
+        Feedjira.logger = logger
+      end
+
+      def logger
+        Feedjira.logger
+      end
+    end
+  end
+end

lib/feedjira/core_ext/time.rb

@@ -18,7 +18,8 @@ def self.parse_safely(dt)
     elsif dt.respond_to? :to_s
       parse_string_safely dt.to_s
     end
-  rescue StandardError
+  rescue StandardError => e
+    Feedjira::Logger.exception(e) { "Failed to parse time #{dt}" }
     nil
   end
 

lib/feedjira/date_time_utilities.rb

@@ -11,14 +11,16 @@ module DateTimeUtilities
     # Parse the given string starting with the most common parser (default ruby)
     # and going over all other available parsers
     def parse_datetime(string)
-      DATE_PARSERS.find do |parser|
+      res = DATE_PARSERS.find do |parser|
         begin
           return parser.parse(string).feed_utils_to_gm_time
-        rescue
+        rescue StandardError => e
+          Feedjira::Logger.exception(e) { "Failed to parse date #{string}" }
           nil
         end
       end
-      warn "Failed to parse date #{string.inspect}"
+      Feedjira::Logger.warn { "Failed to parse date #{string}" } if res.nil?
+      res
     end
   end
 end

lib/feedjira/date_time_utilities/date_time_pattern_parser.rb

@@ -12,7 +12,8 @@ def self.parse(string)
           begin
             datetime = DateTime.strptime(prepare(string), p)
             return datetime
-          rescue
+          rescue StandardError => e
+            Feedjira::Logger.exception(e) { "Failed to parse date #{string}" }
             nil
           end
         end

lib/feedjira/feed.rb

@@ -86,8 +86,11 @@ def self.connection(url)
     end
 
     def self.parse_last_modified(response)
-      DateTime.parse(response.headers['last-modified']).to_time
-    rescue
+      lm = response.headers['last-modified']
+      DateTime.parse(lm).to_time
+    rescue StandardError => e
+      Feedjira::Logger.warn { "Failed to parse last modified '#{lm}'" }
+      Feedjira::Logger.exception(e)
       nil
     end
     private_class_method :parse_last_modified

lib/feedjira/feed_entry_utilities.rb

@@ -9,8 +9,9 @@ def published
 
     def parse_datetime(string)
       DateTime.parse(string).feed_utils_to_gm_time
-    rescue
-      warn "Failed to parse date #{string.inspect}"
+    rescue StandardError => e
+      Feedjira::Logger.warn { "Failed to parse date #{string.inspect}" }
+      Feedjira::Logger.exception(e)
       nil
     end
 

lib/feedjira/logger.rb

@@ -0,0 +1,51 @@
+module Feedjira
+  class << self
+    attr_writer :logger
+
+    # Provides a global logger instance for Feedjira
+    # If no logger is set by the user, a logger using STDOUT is provided
+    def logger
+      return @logger unless @logger.nil?
+      @logger = ::Logger.new(Feedjira::Config::DEFAULTS[:logger_io])
+      @logger.level = Feedjira::Config::DEFAULTS[:logger_level]
+      @logger
+    end
+  end
+
+  # Provide some convenience methods for logging
+  # So the Progname mustn't be passed on every call
+  # @example
+  #   Feedjira::Logger.info { "My Info Message" }
+  module Logger
+    class << self
+      def debug
+        Feedjira.logger.debug('Feedjira') { yield }
+      end
+
+      def info
+        Feedjira.logger.info('Feedjira') { yield }
+      end
+
+      def warn
+        Feedjira.logger.warn('Feedjira') { yield }
+      end
+
+      def error
+        Feedjira.logger.error('Feedjira') { yield }
+      end
+
+      def fatal
+        Feedjira.logger.fatal('Feedjira') { yield }
+      end
+
+      # Log exceptions with message and backtrace in a common way
+      # Exceptions will only be logged when severity level 'debug' is set
+      def exception(e)
+        Feedjira.logger.debug('Feedjira') do
+          msg = block_given? ? "#{yield}\n" : ''
+          msg + "Message: #{e.message}\n#{e.backtrace.join("\n ")}"
+        end
+      end
+    end
+  end
+end