feedjira-podcast 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e920f641d84394882a25efd751ff461cd16bbf89
-  data.tar.gz: 5b93125bc0612379a7f1860522285ca6901d2f98
+  metadata.gz: 2ec26cc9fb4659fdd60822fe789156df198d5ad3
+  data.tar.gz: d85cf9221e5dfb231ca61cfc58474a3765a288ae
 SHA512:
-  metadata.gz: 0b76182e96816ea1ed6b189471610a8e34c26217f4c4150ebfb27614784c0dc0a89ec978a38f0493d55766740f6a038739321d23463ff567c85e01be8440c0f5
-  data.tar.gz: 2d41af05dcface90980736ba4deee0a7c7de7f1ce2eab0d1c4404a19a7ec3dca32a0234e967ce7b42dc0155c2a782e71149601dc414261fe4d971fc2ef29f382
+  metadata.gz: c7935ac9352a2716082dca3a0db6498a372ec2eb99dcf80682da312b640d1e5e87f727147ebdf40e6f27de9ddbbb58b11f511e0d3c37e515a286d152154482d8
+  data.tar.gz: 8b998f9898ef191a8ddc6e46699eb7dffb93eccd4d0825bd26934e3aabec487527b2ffed078e2f71f273a09c302a5c32583bf8964f4504c94979819d897bfcf8

data/.gitignore

@@ -8,3 +8,4 @@
 /spec/reports/
 /tmp/
 /vendor/bundle/
+/*.gem

data/README.md

@@ -4,4 +4,64 @@
 [![Dependency Status](https://gemnasium.com/scour/feedjira-podcast.svg)](https://gemnasium.com/scour/feedjira-podcast)
 [![Build Status](https://travis-ci.org/scour/feedjira-podcast.svg)](https://travis-ci.org/scour/feedjira-podcast)
 [![Code Climate](https://codeclimate.com/github/scour/feedjira-podcast/badges/gpa.svg)](https://codeclimate.com/github/scour/feedjira-podcast)
-[![Coverage Status](https://coveralls.io/repos/scour/feedjira-podcast/badge.svg)](https://coveralls.io/r/scour/feedjira-podcast)
+[![Coverage Status](https://coveralls.io/repos/scour/feedjira-podcast/badge.svg?branch=master)](https://coveralls.io/r/scour/feedjira-podcast?branch=master)
+
+This is a highly opinionated RSS parser designed for working with podcast feeds. It is built on top of [Feedjira](http://feedjira.com/), but is not compatible with the parsers that ship with Feedjira and are normalized across a variety of feed formats. Feedjira::Podcast provides a number of features beyond basic feed parsing, including analysis of podcast feed best practices.
+
+## Usage
+
+The Feedjira::Podcast gem tries to strike a balance between standard Ruby idioms, the RSS and podcast specs, and needing to deal with real-world feeds that may not behave as expected. For the most part, interacting with a parsed podcast feed should be straight forward.
+
+This gem registers the podcast parser class with Feedjira, so `Feedjira::Feed.parse` and the other standard fetch/parse methods are generally the easiest ways to ingest feeds. For more information, see Feedjira's documentation.
+
+### Common Behaviors
+
+#### Grouping
+
+In nearly all cases, items, properties, etc can be accessed in a predictable way, according to familiar Ruby patterns. Any logical groupings (namespaces, multiple attributes on a single element, etc) that exist within the feeds are abstracted by the parser.
+
+The parser creates nested `Struct` objects whenever necessary, allowing application code to read attributes at any depth without having to check for the existence of objects at each level.
+
+**Examples**
+
+```ruby
+@feed.itunes.image.href
+@feed.feedburner.info.uri
+@item.enclosure.type
+```
+
+*(One exception to this is the `<atom:link rel="self">` element. Standard access would be `atom.link.self.href`, for example. In order to avoid using `self`, this can be accessed through `atom.link[:self].href`. This may be unnecessary, but it's an option if you would like to use it.)*
+
+Regardless of the inclusion of those specific attributes, or even their parent elements, you can safely access those properties without needing `&&` or `.try`. This is true for all values that are exposed by the parser.
+
+#### Naming
+
+Most names either match their counterpart in the feed exactly (e.g. `description`, `author`), convert camel case to snake case (e.g. `pubDate` becomes `pub_date`), or transpose boolean attributes to question-mark-notation (e.g. `isPermaLink` becomes `perma_link?`, and `itunes:block` becomes `itunes.block?`).
+
+In cases where an element can repeat in a given context, the accessor will be pluralized (e.g. `<category>` becomes `categories`) and the value is an array, even if only a single element exists in a given feed.
+
+#### Typecasting
+
+In nearly all cases the value types of podcast feed data is predictable. As such, the parser will cast values appropriately. In cases where a feed is malformed, the result of the type cast may be somewhat unpredictable, but no more so than the original data was. A bad value should never prevent parsing of the rest of the document, but it bust a specific value (e.g. a date that is human-readable but not parseable will end up as `nil` rather than fallback to an ambiguous `String` value).
+
+Date values are parsed as `Time` objects, number values become `Float` objects, hrefs, URIs and URLs are parsed using [Addressable](https://github.com/sporkmonger/addressable), and boolean values will return `true` or `false.`
+
+In the case of the `<itunes:explicit>` tag, there are three mutually exclusive options, `"yes"`, `"clean"`, and any other value (representing `"no"`). This element gets expanded to two properties through parsing, `explicit?` and `clean?`, allowing both to be simple boolean values.
+
+The spec for the item `<guid>` indicates that the default value if no value is given for the `isPermaLink` attribute is `true`. It also states that when `isPermaLink` is true, the value of `<guid>` represents a URI (and that the client can choose to treat it that way or not). As such, whenever a `<guid>` is acting as a `permaLink`, whether implicitly or explicitly, the `guid` value will return an `Addressable::URI`. Only if `isPermaLink` has a value of `"false"` with `guid` return a string.
+
+#### Validation
+
+The parser will try its best to parse whatever data it has available, with a strong preference for data that meets the specs commonly used for podcast feeds. The library will provide additional information that you can use to decide how to handle the data produced by the parser, but the parser itself will never refuse a document based on deficiencies or invalid data.
+
+Besides standard typecasting, the parser won't try to clean up any data. For example, many elements (such as `<description>`) explicitly allow only plaintext, but it is common for them to include markup in the wild. The parser will assume that markup to be plaintext, according to the spec. If you want to sanitize those parts of feeds, you should handle that on your end.
+
+### More Information
+
+For more detailed information about specific aspects of feeds, how they are spec'd, and how they are handled by the parser, see the [wiki](https://github.com/scour/feedjira-podcast/wiki).
+
+## In Progress
+
+Coverage of RSS, iTunes, and the other common constituents of podcast feeds is very high, but there are some bits that need to be addressed. Several rarely-used RSS elements (`<cloud>`, `<rating>`, etc) are not supported. Due to how they can be nested `<itunes:category>` is also a work in progress. Currently only top-level categories are available. More esoteric elements, such a host-specific tags, or various parts of Dublin Core, are added based on their prevalence in real world feeds.
+
+Experimental feed elements may be added over time, but they should be used with caution until they reach a critical mass or become standardized.

data/lib/feedjira/parser/podcast.rb

@@ -13,7 +13,8 @@ module Feedjira
       elements :item, as: :items, class: PodcastItem
 
       def self.able_to_parse?(xml)
-        # TODO Look for something podcast-specific
+        # TODO Look several something podcast-specific matches, especially
+        # to cover feeds that may not have any items yet
         (/\<rss|\<rdf/ =~ xml) && (/enclosure/ =~ xml)
       end
     end

data/lib/feedjira/podcast/channel/apple.rb

@@ -10,7 +10,7 @@ module Feedjira
             block == 'yes'
           end
 
-          # base.element :"itunes:category", as: :itunes_author
+          base.elements :"itunes:category", as: :itunes_categories, class: AppleCategory
 
           base.element :"itunes:image", as: :itunes_image_href, value: :href do |href|
             Addressable::URI.parse(href)
@@ -34,7 +34,7 @@ module Feedjira
             @itunes ||= Struct.new(
               :author,
               :block?,
-              # :category,
+              :categories,
               :image,
               :explicit?,
               :clean?,
@@ -46,7 +46,7 @@ module Feedjira
             ).new(
               itunes_author,
               itunes_block,
-              # itunes_category,
+              itunes_categories,
               itunes_image,
               itunes_explicit,
               itunes_clean,

data/lib/feedjira/podcast/channel/apple_category.rb

@@ -0,0 +1,15 @@
+module Feedjira
+  module Podcast
+    module Channel
+      class AppleCategory
+        include SAXMachine
+        include FeedUtilities
+
+        attribute :text
+
+        element :"itunes:category", as: :subcategory, class: AppleSubcategory
+
+      end
+    end
+  end
+end

data/lib/feedjira/podcast/channel/apple_subcategory.rb

@@ -0,0 +1,13 @@
+module Feedjira
+  module Podcast
+    module Channel
+      class AppleSubcategory
+        include SAXMachine
+        include FeedUtilities
+
+        attribute :text
+
+      end
+    end
+  end
+end

data/lib/feedjira/podcast/channel/optional.rb

@@ -38,6 +38,12 @@ module Feedjira
           end
 
           # base.element :cloud
+          # A has five required attributes: domain is the domain name or IP
+          # address of the cloud, port is the TCP port that the cloud is running
+          # on, path is the location of its responder, registerProcedure is the
+          # name of the procedure to call to request notification, and protocol
+          # is xml-rpc, soap or http-post (case-sensitive), indicating which
+          # protocol is to be used.
 
           base.element :ttl do |ttl|
             ttl.to_f
@@ -57,8 +63,16 @@ module Feedjira
           end
 
           # base.element :rating
-          # base.element :skipHours
-          # base.element :skipDays
+          base.element :textInput, as: :text_input, class: TextInput, default: Struct.new(:title, :description, :name, :link).new
+          base.element :skipHours, as: :skip_hours, class: SkipHours
+          base.element :skipDays, as: :skip_days, class: SkipDays
+
+          def skip
+            @skip ||= Struct.new(:hours, :days).new(
+              skip_hours.hours,
+              skip_days.days
+            )
+          end
 
         end
       end

data/lib/feedjira/podcast/channel/skip_days.rb

@@ -0,0 +1,18 @@
+module Feedjira
+  module Podcast
+    module Channel
+      class SkipDays
+        include SAXMachine
+        include FeedUtilities
+
+        elements :day, as: :day do |day|
+          day.to_sym
+        end
+
+        def days
+          @days ||= day ? day : []
+        end
+      end
+    end
+  end
+end

data/lib/feedjira/podcast/channel/skip_hours.rb

@@ -0,0 +1,18 @@
+module Feedjira
+  module Podcast
+    module Channel
+      class SkipHours
+        include SAXMachine
+        include FeedUtilities
+
+        elements :hour, as: :hour do |hour|
+          hour.to_f
+        end
+
+        def hours
+          @hours ||= hour ? hour : []
+        end
+      end
+    end
+  end
+end

data/lib/feedjira/podcast/channel/text_input.rb

@@ -0,0 +1,18 @@
+module Feedjira
+  module Podcast
+    module Channel
+      class TextInput
+        include SAXMachine
+        include FeedUtilities
+
+        element :title
+        element :description
+        element :name
+
+        element :link do |link|
+          Addressable::URI.parse(link)
+        end
+      end
+    end
+  end
+end

data/lib/feedjira/podcast/version.rb

@@ -1,5 +1,5 @@
 module Feedjira
   module Podcast
-    VERSION = "0.9.0"
+    VERSION = "0.9.1"
   end
 end

data/lib/feedjira/podcast.rb

@@ -4,7 +4,12 @@ require 'addressable/uri'
 require 'feedjira/podcast/version'
 
 require 'feedjira/podcast/channel/image'
+require 'feedjira/podcast/channel/skip_hours'
+require 'feedjira/podcast/channel/skip_days'
+require 'feedjira/podcast/channel/text_input'
 require 'feedjira/podcast/channel/apple_owner'
+require 'feedjira/podcast/channel/apple_subcategory'
+require 'feedjira/podcast/channel/apple_category'
 
 require 'feedjira/podcast/channel/required'
 require 'feedjira/podcast/channel/optional'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: feedjira-podcast
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Chris Kalafarski
@@ -114,12 +114,17 @@ files:
 - lib/feedjira/parser/podcast_item.rb
 - lib/feedjira/podcast.rb
 - lib/feedjira/podcast/channel/apple.rb
+- lib/feedjira/podcast/channel/apple_category.rb
 - lib/feedjira/podcast/channel/apple_owner.rb
+- lib/feedjira/podcast/channel/apple_subcategory.rb
 - lib/feedjira/podcast/channel/atom.rb
 - lib/feedjira/podcast/channel/feedburner.rb
 - lib/feedjira/podcast/channel/image.rb
 - lib/feedjira/podcast/channel/optional.rb
 - lib/feedjira/podcast/channel/required.rb
+- lib/feedjira/podcast/channel/skip_days.rb
+- lib/feedjira/podcast/channel/skip_hours.rb
+- lib/feedjira/podcast/channel/text_input.rb
 - lib/feedjira/podcast/error.rb
 - lib/feedjira/podcast/item/apple.rb
 - lib/feedjira/podcast/item/content.rb