feedjira 2.1.0 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7962491408ccbd8bbb0574f66ea50ba074171688
-  data.tar.gz: 9b5ad12bb4e13a32dd38bbb5f63c4b84328eea29
+  metadata.gz: ea1e60152e0f43269fa66fcf0c3ca99c90696dc7
+  data.tar.gz: cf08a79575466cbc8dde079ed0fbad6920f9fd3a
 SHA512:
-  metadata.gz: 7b6aed4014dd8e47d3f694dc8d02e0553ca2f30c3769cba409288d6541f23d2b7ff13ba6284c9815f0eaf14c4657ec55b5c89dbf0c4ca736a6d2c9cc5d0970ec
-  data.tar.gz: 8a6675eab97c9e0bb71823f1aa75033d0560c6a78dd359be6962d1c72816ad178aa74ea422ae72b8109e5a58e2b9705cbfe890d91e39726bbcee3f994c8fb166
+  metadata.gz: 4a6ef2e92c41f2f483f4cdfbb63a3bca09789b725291a02f971b6fbc5fc088c6133928c9a5cbf5d61f9c5faf13eedc1d4246252b8db6b12892fe3ac3bce260a3
+  data.tar.gz: 5ec6ff54c6e43b11701974152e4066458090e5c0beddf16657d861dd35f10f99f67eff68b722467c69e4f1e67774cfe92ee1f42b69ea0dedbd876cf7ef914a4c

data/.gitignore

@@ -4,5 +4,6 @@
 .ruby-version
 Gemfile.lock
 doc/
+.yardoc/
 pkg/
 rdoc/

data/.rubocop.yml

@@ -1,8 +1,15 @@
 AllCops:
   TargetRubyVersion: 2.1
 
-Documentation:
-  Enabled: false
+Style/Documentation:
+  Enabled: true
+  Exclude:
+    - 'spec/**/*'
+
+Style/DocumentationMethod: 
+  Enabled: true
+  Exclude:
+    - 'spec/**/*'
 
 Style/ClassAndModuleChildren:
   Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Feedjira Changelog
 
+## 2.1.1
+
+configurable logging and parsing
+
 ## 2.1.0
 
 * Enhancements

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2009-2014:
+Copyright (c) 2009-2016:
 
 - Paul Dix
 - Julien Kirch

data/README.md

@@ -1,14 +1,217 @@
-# Feedjira [![Build Status][travis-badge]][travis] [![Code Climate][code-climate-badge]][code-climate]
+# Feedjira
 
-[travis-badge]: https://travis-ci.org/feedjira/feedjira.png
+[![Build Status][travis-badge]][travis] [![Code Climate][code-climate-badge]][code-climate] [![Gitter][gitter-badge]][gitter]
+
+[travis-badge]: https://travis-ci.org/feedjira/feedjira.svg?branch=master
 [travis]: http://travis-ci.org/feedjira/feedjira
-[code-climate-badge]: https://codeclimate.com/github/feedjira/feedjira.png
+[code-climate-badge]: https://codeclimate.com/github/feedjira/feedjira/badges/gpa.svg
 [code-climate]: https://codeclimate.com/github/feedjira/feedjira
+[gitter-badge]: https://badges.gitter.im/feedjira/feedjira.svg
+[gitter]: https://gitter.im/feedjira/feedjira?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge
 
 Feedjira (formerly Feedzirra) is a Ruby library designed to fetch and parse
-feeds as quickly as possible. Version 1.0 was recently released and with it an
-[awesome new website][f].
+feeds as quickly as possible.
+
+## Getting Started
+
+Feedjira is tested with Ruby version 1.9.3 and 2.x so like any Ruby gem, the
+first step is to install the gem:
+
+```
+$ gem install feedjira
+```
+
+Or add it to your Gemfile:
+
+```ruby
+gem "feedjira"
+```
+
+## Fetching and Parsing
+
+For many users, the `fetch_and_parse` method is what they use Feedjira for. This
+method takes a url and returns a Parser object:
+
+```ruby
+url = "http://feedjira.com/blog/feed.xml"
+feed = Feedjira::Feed.fetch_and_parse(url)
+# => #<Feedjira::Parser::Atom...>
+```
+
+These feed objects have both the meta data for a feed and an `entries`
+collection that contains all the entries that were found:
+
+```ruby
+feed.title
+# => "Feedjira Blog"
+feed.url
+# => "http://feedjira.com/blog"
+feed.entries # returns an array of Entry objects
+# => [<Feedjira::Feed::Entry ...>, <Feedjira::Feed::Entry ...>, ...]
+```
+
+These entry objects contain the data parsed from the feed XML:
+
+```ruby
+entry = feed.entries.first
+entry.title
+# => "Announcing verison 1.0"
+entry.url
+# => "http://feedjira.com/blog/2014-02-12-announcing-version-10.html"
+```
+
+## Just Parsing
+
+The parsing functionality of Feedjira has been exposed so that it can be used in
+isolation:
+
+```ruby
+xml = Faraday.get(url).body
+feed = Feedjira::Feed.parse xml
+feed.entries.first.title
+# => "Announcing verison 1.0"
+```
+
+## Adding a feed parsing class
+
+When determining which parser to use for a given XML document, the following
+list of parser classes is used:
+
+* `Feedjira::Parser::RSSFeedBurner`
+* `Feedjira::Parser::GoogleDocsAtom`
+* `Feedjira::Parser::AtomFeedBurner`
+* `Feedjira::Parser::Atom`
+* `Feedjira::Parser::ITunesRSS`
+* `Feedjira::Parser::RSS`
+
+You can insert your own parser at the front of this stack by calling
+`add_feed_class`, like this:
+
+```ruby
+Feedjira::Feed.add_feed_class(MyAwesomeParser)
+```
+
+Now when you `fetch_and_parse`, `MyAwesomeParser` will be the first one to get a
+chance to parse the feed.
+
+If you have the XML and just want to provide a parser class for one parse, you
+can specify that using `parse_with`:
+
+```ruby
+Feedjira::Feed.parse_with(MyAwesomeParser, xml)
+```
+
+## Adding attributes to all feeds types / all entries types
+
+```ruby
+# Add the generator attribute to all feed types
+Feedjira::Feed.add_common_feed_element("generator")
+Feedjira::Feed.fetch_and_parse("http://www.pauldix.net/atom.xml").generator
+# => "TypePad"
+```
+
+## Adding attributes to only one class
+
+If you want to add attributes for only one class you simply have to declare them
+in the class
+
+```ruby
+# Add some GeoRss information
+class Feedjira::Parser::RSSEntry
+  element "georss:elevation", as: :elevation
+end
+
+# Fetch a feed containing GeoRss info and print them
+url = "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/significant_week.atom"
+Feedjira::Feed.fetch_and_parse(url).entries.each do |entry|
+  puts "Elevation: #{entry.elevation}"
+end
+```
+
+## Configuration
+
+#### Stripping whitespace from XML
+
+Feedjira can be configured to strip all whitespace but defaults to lstrip only:
+
+```ruby
+Feedjira.configure do |config|
+  config.strip_whitespace = true
+end
+```
+
+#### Follow redirect limit
+
+For fetching feeds, the follow redirect limit defaults to 3 but can be set:
+
+```ruby
+Feedjira.configure do |config|
+  config.follow_redirect_limit = 5
+end
+```
+
+#### Request timeout
+
+The request timeout defaults to 30 but can be set:
+
+```ruby
+Feedjira.configure do |config|
+  config.request_timeout = 45
+end
+```
+
+#### User agent
+
+The default user agent is "Feedjira #{Version}" but can be set:
+
+```ruby
+Feedjira.configure do |config|
+  config.user_agent = "Awesome Feed Reader"
+end
+```
+
+## Testing
+
+Feedjira uses [faraday][] to perform requests, so testing Feedjira is really
+about [stubbing out faraday requests][stub].
+
+[faraday]: https://github.com/lostisland/faraday
+[stub]: https://github.com/lostisland/faraday#using-faraday-for-testing
+
+## Projects that use Feedjira
+
+Feedjira is used in some awesome projects around the web - from RSS readers to
+add-ons and everything in between. Here are some of them:
+
+* [Feedbin][]: Feedbin bills itself as a fast, simple RSS reader that delivers a
+  great reading experience. It's a paid RSS reader that integrates with mobile
+  apps and it even has a fully featured API!
+
+* [Stringer][]: Stringer is a self-hosted, anti-social RSS reader. It's an
+  open-source project that's easy to deploy to any host, there's even a
+  one-click button to deploy on Heroku.
+
+* [BlogFeeder][]: BlogFeeder is a paid Shopify App that makes it easy for you to
+  import any external blog into your Shopify store. It helps improve your
+  store's SEO and keeps your blogs in sync, plus a lot more.
+
+* [Feedbunch][]: Feedbunch is an open source feed reader built to fill the hole
+  left by Google Reader. It aims to support all features of Google Reader and
+  actually improve on others.
+
+* [The Old Reader][old]: The Old Reader advertises as the ultimate social RSS
+  reader. It's free to start and also has a paid premium version. There's an API
+  and it integrates with many different mobile apps.
+
+* [Solve for All][solve]: Solve for All combines search engine and feed parsing
+  while protecting your privacy. It's even extendable by the community!
 
-[f]: http://feedjira.com
+[Feedbin]: https://feedbin.com/
+[Stringer]: https://github.com/swanson/stringer
+[BlogFeeder]: https://apps.shopify.com/blogfeeder
+[Feedbunch]: https://github.com/amatriain/feedbunch
+[old]: http://theoldreader.com/
+[solve]: https://solveforall.com/
 
-There you'll find documentation, examples, announcements and more.
+Note: to get your project on this list, simply [send an email](mailto:feedjira@gmail.com)
+with your project's details.

data/Rakefile

@@ -1,5 +1,6 @@
 require 'rspec/core/rake_task'
 require 'rubocop/rake_task'
+require 'yard'
 
 RSpec::Core::RakeTask.new(:spec) do |t|
   t.verbose = false
@@ -9,4 +10,8 @@ RuboCop::RakeTask.new(:rubocop) do |t|
   t.options = ['--display-cop-names']
 end
 
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb', '-', 'LICENSE']
+end
+
 task default: [:spec, :rubocop]

data/feedjira.gemspec

@@ -25,6 +25,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'danger'
   s.add_development_dependency 'danger-commit_lint'
   s.add_development_dependency 'rspec'
-  s.add_development_dependency 'rubocop'
+  s.add_development_dependency 'rubocop', '0.46'
   s.add_development_dependency 'vcr'
+  s.add_development_dependency 'yard', '~> 0.9'
 end

data/lib/feedjira.rb

@@ -3,10 +3,13 @@ require 'faraday'
 require 'faraday_middleware'
 require 'sax-machine'
 require 'loofah'
+require 'logger'
 
 require 'feedjira/core_ext'
-require 'feedjira/date_time_utilities/date_time_pattern_parser'
+require 'feedjira/configuration'
+require 'feedjira/date_time_utilities/date_time_epoch_parser'
 require 'feedjira/date_time_utilities/date_time_language_parser'
+require 'feedjira/date_time_utilities/date_time_pattern_parser'
 require 'feedjira/date_time_utilities'
 require 'feedjira/date_time_utilities'
 require 'feedjira/feed_entry_utilities'
@@ -35,7 +38,10 @@ require 'feedjira/parser/google_docs_atom'
 require 'feedjira/parser/atom_youtube_entry'
 require 'feedjira/parser/atom_youtube'
 
+# Feedjira
 module Feedjira
   class NoParserAvailable < StandardError; end
   class FetchFailure < StandardError; end
+
+  extend Configuration
 end

data/lib/feedjira/configuration.rb

@@ -0,0 +1,76 @@
+# Feedjira::Configuration
+module Feedjira
+  # Provides global configuration options for Feedjira
+  #
+  # @example Set configuration options using a block
+  #   Feedjira.configure do |config|
+  #     config.strip_whitespace = true
+  #   end
+  module Configuration
+    attr_accessor(
+      :follow_redirect_limit,
+      :logger,
+      :parsers,
+      :request_timeout,
+      :strip_whitespace,
+      :user_agent
+    )
+
+    # Modify Feedjira's current configuration
+    #
+    # @yieldparam [Feedjria] config current Feedjira config
+    # @example
+    #   Feedjira.configure do |config|
+    #     config.strip_whitespace = true
+    #   end
+    def configure
+      yield self
+    end
+
+    # Reset Feedjira's configuration to defaults
+    #
+    # @example
+    #   Feedjira.reset_configuration!
+    def reset_configuration!
+      set_default_configuration
+    end
+
+    # @private
+    def self.extended(base)
+      base.set_default_configuration
+    end
+
+    # @private
+    def set_default_configuration
+      self.follow_redirect_limit = 3
+      self.logger = default_logger
+      self.parsers = default_parsers
+      self.request_timeout = 30
+      self.strip_whitespace = false
+      self.user_agent = "Feedjira #{Feedjira::VERSION}"
+    end
+
+    private
+
+    # @private
+    def default_logger
+      Logger.new(STDOUT).tap do |logger|
+        logger.progname = 'Feedjira'
+        logger.level = Logger::WARN
+      end
+    end
+
+    # @private
+    def default_parsers
+      [
+        Feedjira::Parser::RSSFeedBurner,
+        Feedjira::Parser::GoogleDocsAtom,
+        Feedjira::Parser::AtomYoutube,
+        Feedjira::Parser::AtomFeedBurner,
+        Feedjira::Parser::Atom,
+        Feedjira::Parser::ITunesRSS,
+        Feedjira::Parser::RSS
+      ]
+    end
+  end
+end

data/lib/feedjira/core_ext/date.rb

@@ -2,6 +2,7 @@
 # Ruby Cookbook by Lucas Carlson and Leonard Richardson
 # Published by O'Reilly
 # ISBN: 0-596-52369-6
+# rubocop:disable Style/DocumentationMethod
 class Date
   def feed_utils_to_gm_time
     feed_utils_to_time(new_offset, :gm)

data/lib/feedjira/core_ext/string.rb

@@ -1,3 +1,4 @@
+# rubocop:disable Style/DocumentationMethod Style/Documentation
 class String
   def sanitize!
     replace(sanitize)

data/lib/feedjira/core_ext/time.rb

@@ -1,6 +1,7 @@
 require 'time'
 require 'date'
 
+# rubocop:disable Style/DocumentationMethod
 class Time
   # Parse a time string and convert it to UTC without raising errors.
   # Parses a flattened 14-digit time (YYYYmmddHHMMMSS) as UTC.
@@ -10,6 +11,7 @@ class Time
   #
   # === Returns
   # A Time instance in UTC or nil if there were errors while parsing.
+  # rubocop:disable Metrics/MethodLength
   def self.parse_safely(dt)
     if dt.is_a?(Time)
       dt.utc
@@ -18,7 +20,9 @@ class Time
     elsif dt.respond_to? :to_s
       parse_string_safely dt.to_s
     end
-  rescue StandardError
+  rescue StandardError => e
+    Feedjira.logger.debug { "Failed to parse time #{dt}" }
+    Feedjira.logger.debug(e)
     nil
   end