README.md in feedjira-2.2.0 vs README.md in feedjira-3.0.0.beta1

- old
+ new

@@ -7,108 +7,47 @@ [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. +Feedjira is a Ruby library designed to parse feeds. -## Getting Started +## Installation -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: +Add this line to your application's Gemfile: -``` -$ gem install feedjira -``` - -Or add it to your Gemfile: - ```ruby gem "feedjira" ``` -## Fetching and Parsing +## 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: +An example of parsing a feed with Feedjira: ```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 +xml = HTTParty.get(url).body +feed = Feedjira.parse(xml) feed.entries.first.title -# => "Announcing verison 1.0" +# => "Announcing verison 3.0" ``` -## Adding a feed parsing class +## Specifying parser -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`: +can specify that using `parse` with the parser option: ```ruby -Feedjira::Feed.parse_with(MyAwesomeParser, xml) +Feedjira.parse(xml, parser: MyAwesomeParser) ``` ## 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 +xml = HTTParty.get("http://www.pauldix.net/atom.xml").body +Feedjira.parse(xml).generator # => "TypePad" ``` ## Adding attributes to only one class @@ -121,63 +60,62 @@ 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| +xml = HTTParty.get(url).body +Feedjira.parse(xml).entries.each do |entry| puts "Elevation: #{entry.elevation}" end ``` ## Configuration -#### Stripping whitespace from XML +### Parsers -Feedjira can be configured to strip all whitespace but defaults to lstrip only: +#### Adding a custom parser -```ruby -Feedjira.configure do |config| - config.strip_whitespace = true -end -``` +You can insert your own parser at the front of the available parser list by: -#### 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 + config.parsers.unshift(MyAwesomeParser) end ``` -#### Request timeout +Now when you call `Feedjira.parse`, `MyAwesomeParser` will be the first one to +get a chance to parse the feed. -The request timeout defaults to 30 but can be set: +#### Explicitly set all available parsers +Feedjira can be configured to use a specific set of parsers and in a specific order: + ```ruby Feedjira.configure do |config| - config.request_timeout = 45 + config.parsers = [ + Feedjira::Parser::ITunesRSS, + MyAwesomeParser, + Feedjira::Parser::RSS + ] end ``` -#### User agent +#### Stripping whitespace from XML -The default user agent is "Feedjira #{Version}" but can be set: +Feedjira can be configured to strip all whitespace but defaults to lstrip only: ```ruby Feedjira.configure do |config| - config.user_agent = "Awesome Feed Reader" + config.strip_whitespace = true end ``` -## Testing +## Contributing -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 +Bug reports and pull requests are welcome on GitHub at +https://github.com/feedjira/feedjira. This project is intended to be a safe, +welcoming space for collaboration, and contributors are expected to adhere to +the [Contributor Covenant](http://contributor-covenant.org) code of conduct. ## 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: