feedtools 0.2.22 → 0.2.23

data/lib/feed_tools/feed_structures.rb

@@ -0,0 +1,252 @@
+#--
+# Copyright (c) 2005 Robert Aman
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+
+module FeedTools
+  # Represents a feed/feed item's category
+  class Category
+  
+    # The category term value
+    attr_accessor :term
+    # The categorization scheme
+    attr_accessor :scheme
+    # A human-readable description of the category
+    attr_accessor :label
+  
+    alias_method :value, :term
+    alias_method :category, :term
+    alias_method :domain, :scheme
+  end
+
+  # Represents a feed/feed item's author
+  class Author
+
+    # The author's real name
+    attr_accessor :name
+    # The author's email address
+    attr_accessor :email
+    # The url of the author's homepage
+    attr_accessor :href
+    # The raw value of the author tag if present
+    attr_accessor :raw
+
+    alias_method :url, :href
+    alias_method :url=, :href=
+    alias_method :uri, :href
+    alias_method :uri=, :href=
+  end
+
+  # Represents a feed's image
+  class Image
+
+    # The image's title
+    attr_accessor :title
+    # The image's description
+    attr_accessor :description
+    # The url of the image that is being linked to
+    attr_accessor :href
+    # The url to link the image to
+    attr_accessor :link
+    # The width of the image
+    attr_accessor :width
+    # The height of the image
+    attr_accessor :height
+    # The style of the image
+    # Possible values are "icon", "image", or "image-wide"
+    attr_accessor :style
+
+    alias_method :url, :href
+    alias_method :url=, :href=
+  end
+
+  # Represents a feed's text input element.
+  # Be aware that this will be ignored for feed generation.  It's a
+  # pointless element that aggregators usually ignore and it doesn't have an
+  # equivalent in all feeds types.
+  class TextInput
+
+    # The label of the Submit button in the text input area.
+    attr_accessor :title
+    # The description explains the text input area.
+    attr_accessor :description
+    # The URL of the CGI script that processes text input requests.
+    attr_accessor :link
+    # The name of the text object in the text input area.
+    attr_accessor :name
+  end
+
+  # Represents a feed's cloud.
+  # Be aware that this will be ignored for feed generation.
+  class Cloud
+
+    # The domain of the cloud.
+    attr_accessor :domain
+    # The path for the cloud.
+    attr_accessor :path
+    # The port the cloud is listening on.
+    attr_accessor :port
+    # The web services protocol the cloud uses.
+    # Possible values are either "xml-rpc" or "soap".
+    attr_accessor :protocol
+    # The procedure to use to request notification.
+    attr_accessor :register_procedure
+  end
+
+  # Represents a simple hyperlink
+  class Link
+    # The url that is being linked to
+    attr_accessor :href
+    # The language of the resource being linked to
+    attr_accessor :hreflang
+    # The relation type of the link
+    attr_accessor :rel
+    # The mime type of the link
+    attr_accessor :type    
+    # The title of the hyperlink
+    attr_accessor :title
+    # The length of the resource being linked to in bytes
+    attr_accessor :length
+  
+    alias_method :url, :href
+    alias_method :url=, :href=
+  end
+  
+  # This class stores information about a feed item's file enclosures.
+  class Enclosure
+    # The url for the enclosure
+    attr_accessor :href
+    # The MIME type of the file referenced by the enclosure
+    attr_accessor :type
+    # The size of the file referenced by the enclosure
+    attr_accessor :file_size
+    # The total play time of the file referenced by the enclosure
+    attr_accessor :duration
+    # The height in pixels of the enclosed media
+    attr_accessor :height
+    # The width in pixels of the enclosed media
+    attr_accessor :width
+    # The bitrate of the enclosed media
+    attr_accessor :bitrate
+    # The framerate of the enclosed media
+    attr_accessor :framerate
+    # The thumbnail for this enclosure
+    attr_accessor :thumbnail
+    # The categories for this enclosure
+    attr_accessor :categories
+    # A hash of the enclosed file
+    attr_accessor :hash
+    # A website containing some kind of media player instead of a direct
+    # link to the media file.
+    attr_accessor :player
+    # A list of credits for the enclosed media
+    attr_accessor :credits
+    # A text rendition of the enclosed media
+    attr_accessor :text
+    # A list of alternate version of the enclosed media file
+    attr_accessor :versions
+    # The default version of the enclosed media file
+    attr_accessor :default_version
+  
+    alias_method :url, :href
+    alias_method :url=, :href=
+    alias_method :link, :href
+    alias_method :link=, :href=
+  
+    # Returns true if this is the default enclosure
+    def is_default?
+      return @is_default
+    end
+  
+    # Sets whether this is the default enclosure for the media group
+    def is_default=(new_is_default)
+      @is_default = new_is_default
+    end
+    
+    # Returns true if the enclosure contains explicit material
+    def explicit?
+      return @explicit
+    end
+  
+    # Sets the explicit attribute on the enclosure
+    def explicit=(new_explicit)
+      @explicit = new_explicit
+    end
+  
+    # Determines if the object is a sample, or the full version of the
+    # object, or if it is a stream.
+    # Possible values are 'sample', 'full', 'nonstop'.
+    def expression
+      return @expression
+    end
+  
+    # Sets the expression attribute on the enclosure.
+    # Allowed values are 'sample', 'full', 'nonstop'.
+    def expression=(new_expression)
+      unless ['sample', 'full', 'nonstop'].include? new_expression.downcase
+        raise ArgumentError,
+          "Permitted values are 'sample', 'full', 'nonstop'."
+      end
+      @expression = new_expression.downcase
+    end
+  
+    # Returns true if this enclosure contains audio content
+    def audio?
+      unless self.type.nil?
+        return true if (self.type =~ /^audio/) != nil
+      end
+      # TODO: create a more complete list
+      # =================================
+      audio_extensions = ['mp3', 'm4a', 'm4p', 'wav', 'ogg', 'wma']
+      audio_extensions.each do |extension|
+        if (url =~ /#{extension}$/) != nil
+          return true
+        end
+      end
+      return false
+    end
+
+    # Returns true if this enclosure contains video content
+    def video?
+      unless self.type.nil?
+        return true if (self.type =~ /^video/) != nil
+        return true if self.type == "image/mov"
+      end
+      # TODO: create a more complete list
+      # =================================
+      video_extensions = ['mov', 'mp4', 'avi', 'wmv', 'asf']
+      video_extensions.each do |extension|
+        if (url =~ /#{extension}$/) != nil
+          return true
+        end
+      end
+      return false
+    end
+  end
+
+  # TODO: Make these actual classes instead of structs
+  # ==================================================
+  EnclosureHash = Struct.new( "EnclosureHash", :hash, :type )
+  EnclosurePlayer = Struct.new( "EnclosurePlayer", :url, :height, :width )
+  EnclosureCredit = Struct.new( "EnclosureCredit", :name, :role )
+  EnclosureThumbnail = Struct.new( "EnclosureThumbnail", :url, :height,
+    :width )
+end

data/lib/feed_tools/helpers/feed_tools_helper.rb

@@ -31,8 +31,6 @@ require 'feed_tools/helpers/generic_helper'
 # the FeedTools library.
 module FeedTools
   module FeedToolsHelper
-    include FeedTools::GenericHelper
-    private :validate_options
   
     @@default_local_path = File.expand_path('.')
   
@@ -45,12 +43,15 @@ module FeedTools
     def self.default_local_path=(new_default_local_path)
       @@default_local_path = new_default_local_path
     end
-  
-  protected  
+
+  protected
     # Loads a feed within a block for more consistent syntax and control
     # over the FeedTools environment.
     def with_feed(options={})
-      validate_options([ :from_file, :from_url, :from_data, :feed_cache ],
+      FeedTools::GenericHelper.validate_options([ :from_file,
+                                                  :from_url,
+                                                  :from_data,
+                                                  :feed_cache ],
                        options.keys)
       options = { :feed_cache =>
         FeedTools.configurations[:feed_cache] }.merge(options)

data/lib/feed_tools/helpers/generic_helper.rb

@@ -22,179 +22,37 @@
 #++
 
 require 'feed_tools'
-require 'rexml/document'
 
 module FeedTools
   # Generic methods needed in numerous places throughout FeedTools
   module GenericHelper
     # Raises an exception if an invalid option has been specified to prevent
     # misspellings from slipping through 
-    def validate_options(valid_option_keys, supplied_option_keys)
+    def self.validate_options(valid_option_keys, supplied_option_keys)
       unknown_option_keys = supplied_option_keys - valid_option_keys
       unless unknown_option_keys.empty?
         raise "Unknown options: #{unknown_option_keys}"
       end
     end
     
-    # Selects the first non-blank result.
-    def select_not_blank(results, &block)
-      for result in results
-        blank_result = false
-        if !block.nil?
-          blank_result = block.call(result)
-        else
-          blank_result = result.to_s.blank?
-        end
-        unless result.nil? || blank_result
-          return result
-        end
-      end
-      return nil
-    end
-    
-    # Runs through a list of XPath queries on an element or document and
-    # returns the first non-blank result.  Subsequent XPath queries will
-    # not be evaluated.
-    def try_xpaths(element, xpath_list,
-        options={}, &block)
-      validate_options([ :select_result_value ],
-                       options.keys)
-      options = { :select_result_value => false }.merge(options)
-
-      result = nil
-      if element.nil?
+    # Nifty little method that takes a block and returns nil if recursion
+    # occurs or the block's result value if it doesn't.
+    def self.recursion_trap(lock_object, &block)
+      if @lock_ids.nil?
+        @lock_ids = []
+      end
+      if !@lock_ids.include?(lock_object.object_id)
+        @lock_ids << lock_object.object_id
+      else
         return nil
       end
-      for xpath in xpath_list
-        result = REXML::XPath.liberal_first(element, xpath,
-          FEED_TOOLS_NAMESPACES)
-        if options[:select_result_value] && !result.nil?
-          if result.respond_to?(:value)
-            result = result.value
-          else
-            result = result.to_s
-          end
-        end
-        blank_result = false
-        if block_given?
-          blank_result = yield(result)
-        else
-          blank_result = result.to_s.blank?
-        end
-        if !blank_result
-          if result.respond_to? :strip
-            result.strip!
-          end
-          return result
-        end
-      end
-      for xpath in xpath_list
-        result = REXML::XPath.liberal_first(element, xpath)
-        if options[:select_result_value] && !result.nil?
-          if result.respond_to?(:value)
-            result = result.value
-          else
-            result = result.to_s
-          end
-        end
-        blank_result = false
-        if block_given?
-          blank_result = yield(result)
-        else
-          blank_result = result.to_s.blank?
-        end
-        if !blank_result
-          if result.respond_to? :strip
-            result.strip!
-          end
-          return result
-        end
-      end
-      for xpath in xpath_list
-        if xpath =~ /^\w+$/
-          for child in element.children
-            if child.class == REXML::Element
-              if child.name.downcase == xpath.downcase
-                result = child
-              end
-            end
-          end
-          if options[:select_result_value] && !result.nil?
-            if result.respond_to?(:value)
-              result = result.value
-            else
-              result = result.to_s
-            end
-          end
-          blank_result = false
-          if block_given?
-            blank_result = yield(result)
-          else
-            blank_result = result.to_s.blank?
-          end
-          if !blank_result
-            if result.respond_to? :strip
-              result.strip!
-            end
-            return result
-          end
-        end
-      end
-      return nil
-    end
-    
-    # Runs through a list of XPath queries on an element or document and
-    # returns the first non-empty result.  Subsequent XPath queries will
-    # not be evaluated.
-    def try_xpaths_all(element, xpath_list, options={})
-      validate_options([ :select_result_value ],
-                       options.keys)
-      options = { :select_result_value => false }.merge(options)
-
-      results = []
-      if element.nil?
-        return []
-      end
-      for xpath in xpath_list
-        results = REXML::XPath.liberal_match(element, xpath,
-          FEED_TOOLS_NAMESPACES)
-        if options[:select_result_value] && !results.nil? && !results.empty?
-          results =
-            results.map { |x| x.respond_to?(:value) ? x.value : x.to_s }
-        end
-        if results.blank?
-          results = REXML::XPath.liberal_match(element, xpath)
-        else
-          return results
-        end
-        if options[:select_result_value] && !results.nil? && !results.empty?
-          results =
-            results.map { |x| x.respond_to?(:value) ? x.value : x.to_s }
-        end
-        if !results.blank?
-          return results
-        end
-      end
-      for xpath in xpath_list
-        if xpath =~ /^\w+$/
-          results = []
-          for child in element.children
-            if child.class == REXML::Element
-              if child.name.downcase == xpath.downcase
-                results << child
-              end
-            end
-          end
-          if options[:select_result_value] && !results.nil? && !results.empty?
-            results =
-              results.map { |x| x.inner_xml }
-          end
-          if !results.blank?
-            return results
-          end
-        end
+      begin
+        result = block.call
+      rescue SystemStackError
+        result = nil
       end
-      return []
+      @lock_ids.delete(lock_object.object_id)
+      return result
     end
   end
 end