simple-rss 2.0.0 → 2.2.0

data/lib/simple-rss.rb

@@ -3,15 +3,25 @@
 require "cgi"
 require "time"
 
-class SimpleRSS
-  VERSION = "2.0.0".freeze
+class SimpleRSS # rubocop:disable Metrics/ClassLength
+  # @rbs skip
+  include Enumerable
+
+  # @rbs!
+  #   include Enumerable[Hash[Symbol, untyped]]
+
+  VERSION = "2.2.0".freeze
 
   # @rbs @items: Array[Hash[Symbol, untyped]]
   # @rbs @source: String
   # @rbs @options: Hash[Symbol, untyped]
+  # @rbs @etag: String?
+  # @rbs @last_modified: String?
 
   attr_reader :items #: Array[Hash[Symbol, untyped]]
   attr_reader :source #: String
+  attr_reader :etag #: String?
+  attr_reader :last_modified #: String?
   alias entries items #: Array[Hash[Symbol, untyped]]
 
   @@feed_tags = %i[
@@ -42,6 +52,9 @@ class SimpleRSS
     media:title media:thumbnail#url media:thumbnail#height media:thumbnail#width
     media:credit media:credit#role
     media:category media:category#scheme
+    media:description
+    enclosure#url enclosure#type enclosure#length
+    itunes:duration itunes:image#href
   ]
 
   # @rbs (untyped, ?Hash[Symbol, untyped]) -> void
@@ -60,6 +73,159 @@ class SimpleRSS
   end
   alias feed channel
 
+  # Iterate over all items in the feed
+  #
+  # @rbs () { (Hash[Symbol, untyped]) -> void } -> self
+  #    | () -> Enumerator[Hash[Symbol, untyped], self]
+  def each(&block)
+    return enum_for(:each) unless block
+
+    items.each(&block)
+    self
+  end
+
+  # Access an item by index
+  #
+  # @rbs (Integer) -> Hash[Symbol, untyped]?
+  def [](index)
+    items[index]
+  end
+
+  # Get the n most recent items, sorted by date
+  #
+  # @rbs (?Integer) -> Array[Hash[Symbol, untyped]]
+  def latest(count = 10)
+    items.sort_by { |item| item[:pubDate] || item[:updated] || Time.at(0) }.reverse.first(count)
+  end
+
+  # @rbs () -> Symbol
+  def feed_type
+    atom_namespaced_feed = source.match?(/<(atom:)?feed\b[^>]*xmlns(:\w+)?=['"][^'"]*atom/i)
+    return :atom if atom_namespaced_feed
+    return :rss2 if source.match?(/<rss[^>]*version=['"]2/i)
+    return :rss1 if source.match?(/<rdf:RDF/i)
+    return :rss09 if source.match?(/<rss[^>]*version=['"]0\.9/i)
+
+    :unknown
+  end
+
+  # @rbs () -> bool
+  def valid?
+    return false if items.empty?
+
+    title_value = instance_variable_get(:@title)
+    link_value = instance_variable_get(:@link)
+    return true if title_value || link_value
+
+    false
+  end
+
+  # @rbs (Time) -> Array[Hash[Symbol, untyped]]
+  def items_since(time)
+    items.select do |item|
+      item_date = item[:pubDate] || item[:updated] || item[:published]
+      item_date.is_a?(Time) && item_date > time
+    end
+  end
+
+  # @rbs (String) -> Array[Hash[Symbol, untyped]]
+  def items_by_category(name)
+    query = name.to_s.downcase
+
+    items.select do |item|
+      category = item[:category]
+      next false if category.nil?
+
+      category_matches_query?(category, query)
+    end
+  end
+
+  # @rbs (String) -> Array[Hash[Symbol, untyped]]
+  def search(query)
+    pattern = Regexp.new(Regexp.escape(query.to_s), Regexp::IGNORECASE)
+
+    items.select do |item|
+      searchable_fields(item).any? { |field| field.to_s.match?(pattern) }
+    end
+  end
+
+  # @rbs (*SimpleRSS) -> Array[Hash[Symbol, untyped]]
+  def merge(*feeds)
+    all_items = [items, *feeds.map(&:items)].flatten
+    dedupe_items(sorted_items_by_date(all_items))
+  end
+
+  # @rbs (SimpleRSS) -> Hash[Symbol, Array[Hash[Symbol, untyped]]]
+  def diff(other)
+    other_keys = keyed_item_set(other.items)
+    current_keys = keyed_item_set(items)
+
+    {
+      added: select_new_keyed_items(other.items, current_keys),
+      removed: select_new_keyed_items(items, other_keys)
+    }
+  end
+
+  # @rbs () -> self
+  def dedupe
+    @items = dedupe_items(items)
+    self
+  end
+
+  # @rbs () -> Array[Hash[Symbol, untyped]]
+  def enclosures
+    items.filter_map do |item|
+      enclosure_url = item[:enclosure_url]
+      next if blank_value?(enclosure_url)
+
+      {
+        url: enclosure_url,
+        type: item[:enclosure_type],
+        length: item[:enclosure_length],
+        item: item
+      }
+    end
+  end
+
+  # @rbs () -> Array[String]
+  def images
+    items.flat_map { |item| item_image_urls(item) }.uniq
+  end
+
+  # @rbs (?Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def as_json(_options = {})
+    hash = {} #: Hash[Symbol, untyped]
+
+    @@feed_tags.each do |tag|
+      tag_cleaned = clean_tag(tag)
+      value = instance_variable_get("@#{tag_cleaned}")
+      hash[tag_cleaned] = serialize_value(value) if value
+    end
+
+    hash[:items] = items.map do |item|
+      item.transform_values { |v| serialize_value(v) }
+    end
+
+    hash
+  end
+
+  # @rbs (*untyped) -> String
+  def to_json(*)
+    require "json"
+    JSON.generate(as_json)
+  end
+
+  alias to_hash as_json
+
+  # @rbs (?format: Symbol) -> String
+  def to_xml(format: :rss2)
+    case format
+    when :rss2 then to_rss2_xml
+    when :atom then to_atom_xml
+    else raise ArgumentError, "Unknown format: #{format}. Supported: :rss2, :atom"
+    end
+  end
+
   class << self
     # @rbs () -> Array[Symbol]
     def feed_tags
@@ -87,6 +253,100 @@ class SimpleRSS
     def parse(source, options = {})
       new source, options
     end
+
+    # @rbs (untyped, ?Hash[Symbol, untyped]) -> bool
+    def valid?(source, options = {})
+      parse(source, options)
+      true
+    rescue StandardError
+      false
+    end
+
+    # @rbs (*SimpleRSS) -> Array[Hash[Symbol, untyped]]
+    def merge(*feeds)
+      first_feed = feeds.first
+      return [] if first_feed.nil?
+
+      first_feed.merge(*feeds.drop(1))
+    end
+
+    # Fetch and parse a feed from a URL
+    # Returns nil if conditional GET returns 304 Not Modified
+    #
+    # @rbs (String, ?Hash[Symbol, untyped]) -> SimpleRSS?
+    def fetch(url, options = {})
+      require "net/http"
+      require "uri"
+
+      uri = URI.parse(url)
+      response = perform_fetch(uri, options)
+
+      return nil if response.is_a?(Net::HTTPNotModified)
+
+      raise SimpleRSSError, "HTTP #{response.code}: #{response.message}" unless response.is_a?(Net::HTTPSuccess)
+
+      body = response.body.force_encoding(Encoding::UTF_8)
+      feed = parse(body, options)
+      feed.instance_variable_set(:@etag, response["ETag"])
+      feed.instance_variable_set(:@last_modified, response["Last-Modified"])
+      feed
+    end
+
+    private
+
+    # @rbs (untyped, Hash[Symbol, untyped]) -> untyped
+    def perform_fetch(uri, options)
+      http = build_http(uri, options)
+      request = build_request(uri, options)
+
+      response = http.request(request)
+      handle_redirect(response, options) || response
+    end
+
+    # @rbs (untyped, Hash[Symbol, untyped]) -> untyped
+    def build_http(uri, options)
+      host = uri.host || raise(SimpleRSSError, "Invalid URL: missing host")
+      http = Net::HTTP.new(host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+
+      timeout = options[:timeout]
+      if timeout
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+      end
+
+      http
+    end
+
+    # @rbs (untyped, Hash[Symbol, untyped]) -> untyped
+    def build_request(uri, options)
+      request = Net::HTTP::Get.new(uri)
+      request["User-Agent"] = "SimpleRSS/#{VERSION}"
+
+      # Conditional GET headers
+      request["If-None-Match"] = options[:etag] if options[:etag]
+      request["If-Modified-Since"] = options[:last_modified] if options[:last_modified]
+
+      # Custom headers
+      options[:headers]&.each { |key, value| request[key] = value }
+
+      request
+    end
+
+    # @rbs (untyped, Hash[Symbol, untyped]) -> untyped
+    def handle_redirect(response, options)
+      return nil unless response.is_a?(Net::HTTPRedirection)
+      return nil if options[:follow_redirects] == false
+
+      location = response["Location"]
+      return nil unless location
+
+      redirects = (options[:_redirects] || 0) + 1
+      raise SimpleRSSError, "Too many redirects" if redirects > 5
+
+      new_options = options.merge(_redirects: redirects)
+      perform_fetch(URI.parse(location), new_options)
+    end
   end
 
   DATE_TAGS = %i[pubDate lastBuildDate published updated expirationDate modified dc:date].freeze
@@ -143,11 +403,33 @@ class SimpleRSS
 
         parse_item_tag(item, tag, match[3], match[2])
       end
-      item.define_singleton_method(:method_missing) { |name, *| self[name] }
+      item.define_singleton_method(:method_missing) { |name, *_args| self[name] }
+      add_item_media_helpers(item)
       @items << item
     end
   end
 
+  # @rbs (Hash[Symbol, untyped]) -> void
+  def add_item_media_helpers(item)
+    item.define_singleton_method(:has_media?) do
+      [
+        self[:media_content_url],
+        self[:media_thumbnail_url],
+        self[:enclosure_url],
+        self[:itunes_image_href]
+      ].any? { |value| !value.nil? && !value.to_s.strip.empty? }
+    end
+
+    item.define_singleton_method(:media_url) do
+      [
+        self[:media_content_url],
+        self[:media_thumbnail_url],
+        self[:enclosure_url],
+        self[:itunes_image_href]
+      ].find { |value| !value.nil? && !value.to_s.strip.empty? }
+    end
+  end
+
   # @rbs (Hash[Symbol, untyped], Symbol, String?, String?) -> void
   def parse_item_tag(item, tag, content, item_attrs = nil)
     return if content.nil?
@@ -265,6 +547,210 @@ class SimpleRSS
     tag.to_s.tr(":", "_").intern
   end
 
+  # @rbs (untyped, String) -> bool
+  def category_matches_query?(category, query)
+    return category.any? { |value| value.to_s.downcase.include?(query) } if category.is_a?(Array)
+
+    category.to_s.downcase.include?(query)
+  end
+
+  # @rbs (Hash[Symbol, untyped]) -> Array[untyped]
+  def searchable_fields(item)
+    [item[:title], item[:description], item[:summary], item[:content]]
+  end
+
+  # @rbs (Array[Hash[Symbol, untyped]]) -> Set[String]
+  def keyed_item_set(item_list)
+    item_list.each_with_object(Set.new) do |item, keys|
+      key = item_key(item)
+      next if key.nil?
+
+      keys.add(key)
+    end
+  end
+
+  # @rbs (Array[Hash[Symbol, untyped]], Set[String]) -> Array[Hash[Symbol, untyped]]
+  def select_new_keyed_items(item_list, known_keys)
+    item_list.select do |item|
+      key = item_key(item)
+      !key.nil? && !known_keys.include?(key)
+    end
+  end
+
+  # @rbs (Array[Hash[Symbol, untyped]]) -> Array[Hash[Symbol, untyped]]
+  def sorted_items_by_date(item_list)
+    keyed_items, unkeyed_items = item_list.partition { |item| !item_key(item).nil? }
+    keyed_items.sort_by { |item| item_date(item) || Time.at(0) }.reverse + unkeyed_items
+  end
+
+  # @rbs (Array[Hash[Symbol, untyped]]) -> Array[Hash[Symbol, untyped]]
+  def dedupe_items(item_list)
+    seen_keys = Set.new
+
+    item_list.each_with_object([]) do |item, unique_items|
+      key = item_key(item)
+
+      if key.nil?
+        unique_items << item
+        next
+      end
+
+      next if seen_keys.include?(key)
+
+      seen_keys.add(key)
+      unique_items << item
+    end
+  end
+
+  # @rbs (Hash[Symbol, untyped]) -> String?
+  def item_key(item)
+    key = item[:guid] || item[:id] || item[:link]
+    return nil if key.nil?
+
+    key.to_s
+  end
+
+  # @rbs (Hash[Symbol, untyped]) -> Time?
+  def item_date(item)
+    date = item[:pubDate] || item[:updated] || item[:published]
+    return date if date.is_a?(Time)
+
+    nil
+  end
+
+  # @rbs (Hash[Symbol, untyped]) -> Array[String]
+  def item_image_urls(item)
+    [item[:media_thumbnail_url], item[:media_content_url], item[:itunes_image_href]]
+      .compact
+      .reject { |url| blank_value?(url) }
+  end
+
+  # @rbs (untyped) -> bool
+  def blank_value?(value)
+    value.to_s.strip.empty?
+  end
+
+  # @rbs (untyped) -> untyped
+  def serialize_value(value)
+    case value
+    when Time then value.iso8601
+    else value
+    end
+  end
+
+  # @rbs (String?) -> String
+  def escape_xml(text)
+    return "" if text.nil?
+
+    text.to_s
+        .gsub("&", "&amp;")
+        .gsub("<", "&lt;")
+        .gsub(">", "&gt;")
+        .gsub("'", "&apos;")
+        .gsub('"', "&quot;")
+  end
+
+  # @rbs (Array[String], String, untyped) -> void
+  def add_xml_element(elements, tag, value)
+    elements << "<#{tag}>#{escape_xml(value)}</#{tag}>" if value
+  end
+
+  # @rbs (Array[String], String, untyped, Symbol) -> void
+  def add_xml_time_element(elements, tag, value, format)
+    return unless value.is_a?(Time)
+
+    formatted = format == :rfc2822 ? value.rfc2822 : value.iso8601
+    elements << "<#{tag}>#{formatted}</#{tag}>"
+  end
+
+  # @rbs () -> String
+  def to_rss2_xml
+    xml = ['<?xml version="1.0" encoding="UTF-8"?>', '<rss version="2.0">', "<channel>"]
+    xml.concat(rss2_channel_elements)
+    items.each { |item| xml.concat(rss2_item_elements(item)) }
+    xml << "</channel>"
+    xml << "</rss>"
+    xml.join("\n")
+  end
+
+  # @rbs () -> Array[String]
+  def rss2_channel_elements
+    elements = [] #: Array[String]
+    add_xml_element(elements, "title", instance_variable_get(:@title))
+    add_xml_element(elements, "link", instance_variable_get(:@link))
+    add_xml_element(elements, "description", instance_variable_get(:@description))
+    add_xml_element(elements, "language", instance_variable_get(:@language))
+    add_xml_time_element(elements, "pubDate", instance_variable_get(:@pubDate), :rfc2822)
+    add_xml_time_element(elements, "lastBuildDate", instance_variable_get(:@lastBuildDate), :rfc2822)
+    add_xml_element(elements, "generator", instance_variable_get(:@generator))
+    elements
+  end
+
+  # @rbs (Hash[Symbol, untyped]) -> Array[String]
+  def rss2_item_elements(item)
+    elements = ["<item>"] #: Array[String]
+    elements << "<title>#{escape_xml(item[:title])}</title>" if item[:title]
+    elements << "<link>#{escape_xml(item[:link])}</link>" if item[:link]
+    elements << "<description><![CDATA[#{item[:description]}]]></description>" if item[:description]
+    elements << "<pubDate>#{item[:pubDate].rfc2822}</pubDate>" if item[:pubDate].is_a?(Time)
+    elements << "<guid>#{escape_xml(item[:guid])}</guid>" if item[:guid]
+    elements << "<author>#{escape_xml(item[:author])}</author>" if item[:author]
+    elements << "<category>#{escape_xml(item[:category])}</category>" if item[:category]
+    elements << "</item>"
+    elements
+  end
+
+  # @rbs () -> String
+  def to_atom_xml
+    xml = ['<?xml version="1.0" encoding="UTF-8"?>', '<feed xmlns="http://www.w3.org/2005/Atom">']
+    xml.concat(atom_feed_elements)
+    items.each { |item| xml.concat(atom_entry_elements(item)) }
+    xml << "</feed>"
+    xml.join("\n")
+  end
+
+  # @rbs () -> Array[String]
+  def atom_feed_elements
+    elements = [] #: Array[String]
+    title_val = instance_variable_get(:@title)
+    link_val = instance_variable_get(:@link)
+    id_val = instance_variable_get(:@id)
+    add_xml_element(elements, "title", title_val)
+    elements << "<link href=\"#{escape_xml(link_val)}\" rel=\"alternate\"/>" if link_val
+    elements << "<id>#{escape_xml(id_val || link_val)}</id>" if link_val
+    add_xml_time_element(elements, "updated", instance_variable_get(:@updated), :iso8601)
+    add_xml_element(elements, "subtitle", instance_variable_get(:@subtitle))
+    author_val = instance_variable_get(:@author)
+    elements << "<author><name>#{escape_xml(author_val)}</name></author>" if author_val
+    add_xml_element(elements, "generator", instance_variable_get(:@generator))
+    elements
+  end
+
+  # @rbs (Hash[Symbol, untyped]) -> Array[String]
+  def atom_entry_elements(item)
+    elements = ["<entry>"] #: Array[String]
+    elements << "<title>#{escape_xml(item[:title])}</title>" if item[:title]
+    elements << "<link href=\"#{escape_xml(item[:link])}\" rel=\"alternate\"/>" if item[:link]
+    elements << "<id>#{escape_xml(item[:id] || item[:guid] || item[:link])}</id>" if item[:id] || item[:guid] || item[:link]
+    elements << "<updated>#{item[:updated].iso8601}</updated>" if item[:updated].is_a?(Time)
+    atom_entry_published(elements, item)
+    elements << "<summary><![CDATA[#{item[:summary] || item[:description]}]]></summary>" if item[:summary] || item[:description]
+    elements << "<content><![CDATA[#{item[:content]}]]></content>" if item[:content]
+    elements << "<author><name>#{escape_xml(item[:author])}</name></author>" if item[:author]
+    elements << "<category term=\"#{escape_xml(item[:category])}\"/>" if item[:category]
+    elements << "</entry>"
+    elements
+  end
+
+  # @rbs (Array[String], Hash[Symbol, untyped]) -> void
+  def atom_entry_published(elements, item)
+    if item[:published].is_a?(Time)
+      elements << "<published>#{item[:published].iso8601}</published>"
+    elsif item[:pubDate].is_a?(Time)
+      elements << "<published>#{item[:pubDate].iso8601}</published>"
+    end
+  end
+
   # @rbs (String) -> String
   def unescape(content)
     result = if content =~ %r{([^-_.!~*'()a-zA-Z\d;/?:@&=+$,\[\]]%)}
@@ -277,5 +763,5 @@ class SimpleRSS
   end
 end
 
-class SimpleRSSError < StandardError
+class SimpleRSSError < StandardError # rubocop:disable Style/OneClassPerFile
 end

data/simple-rss.gemspec

@@ -1,14 +1,14 @@
 Gem::Specification.new do |s|
   s.name = "simple-rss"
-  s.version = "2.0.0"
+  s.version = "2.2.0"
   s.date = "2025-12-28"
   s.summary = "A simple, flexible, extensible, and liberal RSS and Atom reader for Ruby. It is designed to be backwards compatible with the standard RSS parser, but will never do RSS generation."
   s.email = "lucas@rufy.com"
-  s.homepage = "http://github.com/cardmagic/simple-rss"
+  s.homepage = "https://github.com/cardmagic/simple-rss"
   s.description = "A simple, flexible, extensible, and liberal RSS and Atom reader for Ruby. It is designed to be backwards compatible with the standard RSS parser, but will never do RSS generation."
   s.authors = ["Lucas Carlson"]
-  s.files = Dir["lib/**/*", "test/**/*", "LICENSE", "README.markdown", "Rakefile", "simple-rss.gemspec"]
-  s.rubyforge_project = "simple-rss"
+  s.files = Dir["lib/**/*", "test/**/*", "LICENSE", "README.md", "Rakefile", "simple-rss.gemspec"]
+  s.required_ruby_version = ">= 3.1"
   s.add_development_dependency "rake"
   s.add_development_dependency "rdoc"
   s.add_development_dependency "test-unit"

data/test/base/enumerable_test.rb

@@ -0,0 +1,101 @@
+require "test_helper"
+
+class EnumerableTest < Test::Unit::TestCase
+  def setup
+    @rss20 = SimpleRSS.parse open(File.dirname(__FILE__) + "/../data/rss20.xml")
+    @atom = SimpleRSS.parse open(File.dirname(__FILE__) + "/../data/atom.xml")
+  end
+
+  def test_includes_enumerable
+    assert_includes SimpleRSS.included_modules, Enumerable
+  end
+
+  def test_each_iterates_over_items
+    titles = @rss20.map { |item| item[:title] }
+    assert_equal @rss20.items.map { |i| i[:title] }, titles
+  end
+
+  def test_each_returns_enumerator_without_block
+    enumerator = @rss20.each
+    assert_kind_of Enumerator, enumerator
+    assert_equal @rss20.items.size, enumerator.count
+  end
+
+  def test_each_returns_self_with_block
+    count = 0
+    result = @rss20.each { |_item| count += 1 }
+    assert_equal @rss20, result
+    assert_equal @rss20.items.size, count
+  end
+
+  def test_enumerable_map
+    titles = @rss20.map { |item| item[:title] }
+    assert_equal @rss20.items.map { |i| i[:title] }, titles
+  end
+
+  def test_enumerable_select
+    items_with_link = @rss20.select { |item| item[:link] }
+    assert_equal @rss20.items.select { |i| i[:link] }, items_with_link
+  end
+
+  def test_enumerable_first
+    assert_equal @rss20.items.first, @rss20.first
+    assert_equal @rss20.items.first(3), @rss20.first(3)
+  end
+
+  def test_enumerable_count
+    assert_equal @rss20.items.size, @rss20.count
+  end
+
+  def test_index_accessor
+    assert_equal @rss20.items[0], @rss20[0]
+    assert_equal @rss20.items[5], @rss20[5]
+    assert_equal @rss20.items[-1], @rss20[-1]
+  end
+
+  def test_index_accessor_out_of_bounds
+    assert_nil @rss20[100]
+  end
+
+  def test_latest_returns_sorted_items
+    latest = @rss20.latest(3)
+    assert_equal 3, latest.size
+
+    dates = latest.map { |item| item[:pubDate] }
+    assert_equal dates, dates.sort.reverse
+  end
+
+  def test_latest_default_count
+    latest = @rss20.latest
+    assert latest.size <= 10
+  end
+
+  def test_latest_with_atom_uses_updated
+    latest = @atom.latest(1)
+    assert_equal 1, latest.size
+  end
+
+  def test_latest_handles_missing_dates
+    rss_with_missing_dates = SimpleRSS.parse <<~RSS
+      <?xml version="1.0" encoding="UTF-8"?>
+      <rss version="2.0">
+        <channel>
+          <title>Test Feed</title>
+          <link>http://example.com</link>
+          <item>
+            <title>No Date</title>
+          </item>
+          <item>
+            <title>Has Date</title>
+            <pubDate>Wed, 24 Aug 2005 13:33:34 GMT</pubDate>
+          </item>
+        </channel>
+      </rss>
+    RSS
+
+    latest = rss_with_missing_dates.latest(2)
+    assert_equal 2, latest.size
+    assert_equal "Has Date", latest.first[:title]
+    assert_equal "No Date", latest.last[:title]
+  end
+end