simple-rss 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d7399eb7c1eee38cca3bd3de50a18cdedbf85b1aeb8536688b628abca814cab
-  data.tar.gz: 7a27767cd9be24307344430c311507859ac825d7845ea9e703985355dd3ccfa3
+  metadata.gz: f7e2a8e829ef0776194df8fd028266dbcecaeb0a5b7b1025aa75b739acbd6ad9
+  data.tar.gz: 664c6319db58dab8bf81e9f540afb6f1251997fa669b3e433a30748eb599ac16
 SHA512:
-  metadata.gz: 6e01cdc590e4fdac9d0be8df7307491b8f67e8b68422d7970b589b72e52872f8dab23935a6225b05993f4adf614f4641d24e0a23538daf7ed512969d1104a84f
-  data.tar.gz: 3568cebc46ca358c7d3a49b0615d49592ed7698e5fcb0c60a3a392c1904de4d4fb7d03fec3ac1d5270ada6c8679737c3a91b880e8dfb91d7aaa69bbfc1f9dab4
+  metadata.gz: 3885af60f0b54553af1e3545a781f6f1179825386cc3edcf1575ed75bb79240eefc83998295d21e842287f1c949a0554918d39d1df1df924701d27f20b26c192
+  data.tar.gz: 81394817f11b09d433eb7b07031120661a7de18d678deff66fdbf4f331f8ec6483a155069f36539e4ba6122210ec3c58cf08b67f3a44d9afc582c0952861d073

data/README.md

@@ -0,0 +1,321 @@
+# SimpleRSS
+
+[![Gem Version](https://badge.fury.io/rb/simple-rss.svg)](https://badge.fury.io/rb/simple-rss)
+[![CI](https://github.com/cardmagic/simple-rss/actions/workflows/ruby.yml/badge.svg)](https://github.com/cardmagic/simple-rss/actions/workflows/ruby.yml)
+[![License: LGPL](https://img.shields.io/badge/License-LGPL-blue.svg)](https://opensource.org/licenses/LGPL-3.0)
+
+A simple, flexible, extensible, and liberal RSS and Atom reader for Ruby. Designed to be backwards compatible with Ruby's standard RSS parser while handling malformed feeds gracefully.
+
+## Features
+
+- Parses both RSS and Atom feeds
+- Tolerant of malformed XML (regex-based parsing)
+- Built-in URL fetching with conditional GET support (ETags, Last-Modified)
+- JSON and XML serialization
+- Extensible tag definitions
+- Zero runtime dependencies
+
+## What's New in 2.0
+
+Version 2.0 is a major update with powerful new capabilities:
+
+- **URL Fetching** - One-liner feed fetching with `SimpleRSS.fetch(url)`. Supports timeouts, custom headers, and automatic redirect following.
+
+- **Conditional GET** - Bandwidth-efficient polling with ETag and Last-Modified support. Returns `nil` when feeds haven't changed (304 Not Modified).
+
+- **JSON Serialization** - Export feeds with `to_json`, `to_hash`, and Rails-compatible `as_json`. Time objects serialize to ISO 8601.
+
+- **XML Serialization** - Convert any parsed feed to clean RSS 2.0 or Atom XML with `to_xml(format: :rss2)` or `to_xml(format: :atom)`.
+
+- **Array Tags** - Collect all occurrences of a tag (like multiple categories) with the `array_tags:` option.
+
+- **Attribute Parsing** - Extract attributes from feed, item, and media tags using the `tag#attr` syntax.
+
+- **UTF-8 Normalization** - All parsed content is automatically normalized to UTF-8 encoding.
+
+- **Modern Ruby** - Full compatibility with Ruby 3.1 through 4.0, with RBS type annotations and Steep type checking.
+
+- **Enumerable Support** - Iterate feeds naturally with `each`, `map`, `select`, and all Enumerable methods. Access items by index with `rss[0]` and get the latest items sorted by date with `latest(n)`.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "simple-rss"
+```
+
+Or install directly:
+
+```bash
+gem install simple-rss
+```
+
+## Quick Start
+
+```ruby
+require "simple-rss"
+require "uri"
+require "net/http"
+
+# Parse from a string or IO object
+xml = Net::HTTP.get(URI("https://example.com/feed.xml"))
+rss = SimpleRSS.parse(xml)
+
+rss.channel.title        # => "Example Feed"
+rss.items.first.title    # => "First Post"
+rss.items.first.pubDate  # => 2024-01-15 12:00:00 -0500 (Time object)
+```
+
+## Usage
+
+### Fetching Feeds
+
+SimpleRSS includes a built-in fetcher with conditional GET support for efficient polling:
+
+```ruby
+# Simple fetch
+feed = SimpleRSS.fetch("https://example.com/feed.xml")
+
+# With timeout
+feed = SimpleRSS.fetch("https://example.com/feed.xml", timeout: 10)
+
+# Conditional GET - only download if modified
+feed = SimpleRSS.fetch("https://example.com/feed.xml")
+# Store these for next request
+etag = feed.etag
+last_modified = feed.last_modified
+
+# On subsequent requests, pass the stored values
+feed = SimpleRSS.fetch(
+  "https://example.com/feed.xml",
+  etag:,
+  last_modified:
+)
+# Returns nil if feed hasn't changed (304 Not Modified)
+```
+
+### Accessing Feed Data
+
+SimpleRSS provides both RSS and Atom style accessors:
+
+```ruby
+feed = SimpleRSS.parse(xml)
+
+# RSS style
+feed.channel.title
+feed.channel.link
+feed.channel.description
+feed.items
+
+# Atom style (aliases)
+feed.feed.title
+feed.entries
+```
+
+### Item Attributes
+
+Items support both hash and method access:
+
+```ruby
+item = feed.items.first
+
+# Hash access
+item[:title]
+item[:link]
+item[:pubDate]
+
+# Method access
+item.title
+item.link
+item.pubDate
+```
+
+Date fields are automatically parsed into `Time` objects:
+
+```ruby
+item.pubDate.class  # => Time
+item.pubDate.year   # => 2024
+```
+
+### Iterating with Enumerable
+
+SimpleRSS includes `Enumerable`, so you can iterate feeds naturally:
+
+```ruby
+feed = SimpleRSS.parse(xml)
+
+# Iterate over items
+feed.each { |item| puts item.title }
+
+# Use any Enumerable method
+titles = feed.map { |item| item.title }
+tech_posts = feed.select { |item| item.category == "tech" }
+first_five = feed.first(5)
+total = feed.count
+
+# Access items by index
+feed[0].title   # first item
+feed[-1].title  # last item
+
+# Get the n most recent items (sorted by pubDate or updated)
+feed.latest(10)
+```
+
+### JSON Serialization
+
+```ruby
+feed = SimpleRSS.parse(xml)
+
+# Get as hash
+feed.to_hash
+# => { title: "Feed Title", link: "...", items: [...] }
+
+# Get as JSON string
+feed.to_json
+# => '{"title":"Feed Title","link":"...","items":[...]}'
+
+# Works with Rails/ActiveSupport
+feed.as_json
+```
+
+### XML Serialization
+
+Convert parsed feeds to standard RSS 2.0 or Atom format:
+
+```ruby
+feed = SimpleRSS.parse(xml)
+
+# Convert to RSS 2.0
+feed.to_xml(format: :rss2)
+
+# Convert to Atom
+feed.to_xml(format: :atom)
+```
+
+### Extending Tag Support
+
+Add support for custom or non-standard tags:
+
+```ruby
+# Add a new feed-level tag
+SimpleRSS.feed_tags << :custom_tag
+
+# Add item-level tags
+SimpleRSS.item_tags << :custom_item_tag
+
+# Parse tags with specific rel attributes (common in Atom)
+SimpleRSS.item_tags << :"link+enclosure"
+# Accessible as: item.link_enclosure
+
+# Parse tag attributes
+SimpleRSS.item_tags << :"media:content#url"
+# Accessible as: item.media_content_url
+
+# Parse item/entry attributes
+SimpleRSS.item_tags << :"entry#xml:lang"
+# Accessible as: item.entry_xml_lang
+```
+
+#### Tag Syntax Reference
+
+| Syntax | Example | Accessor | Description |
+|--------|---------|----------|-------------|
+| `tag` | `:title` | `.title` | Simple element content |
+| `tag#attr` | `:"media:content#url"` | `.media_content_url` | Attribute value |
+| `tag+rel` | `:"link+alternate"` | `.link_alternate` | Element with specific `rel` attribute |
+
+### Collecting Multiple Values
+
+By default, SimpleRSS returns only the first occurrence of each tag. To collect all values:
+
+```ruby
+# Collect all categories for each item
+feed = SimpleRSS.parse(xml, array_tags: [:category])
+
+item.category  # => ["tech", "programming", "ruby"]
+```
+
+## API Reference
+
+### `SimpleRSS.parse(source, options = {})`
+
+Parse RSS/Atom content from a string or IO object.
+
+**Parameters:**
+- `source` - String or IO object containing feed XML
+- `options` - Hash of options
+  - `:array_tags` - Array of tag symbols to collect as arrays
+
+**Returns:** `SimpleRSS` instance
+
+### `SimpleRSS.fetch(url, options = {})`
+
+Fetch and parse a feed from a URL.
+
+**Parameters:**
+- `url` - Feed URL string
+- `options` - Hash of options
+  - `:timeout` - Request timeout in seconds
+  - `:etag` - ETag from previous request (for conditional GET)
+  - `:last_modified` - Last-Modified header from previous request
+  - `:follow_redirects` - Follow redirects (default: true)
+  - `:headers` - Hash of additional HTTP headers
+
+**Returns:** `SimpleRSS` instance, or `nil` if 304 Not Modified
+
+### Instance Methods
+
+| Method | Description |
+|--------|-------------|
+| `#channel` / `#feed` | Returns self (for RSS/Atom style access) |
+| `#items` / `#entries` | Array of parsed items |
+| `#each` | Iterate over items (includes `Enumerable`) |
+| `#[](index)` | Access item by index |
+| `#latest(n = 10)` | Get n most recent items by date |
+| `#to_json` | JSON string representation |
+| `#to_hash` / `#as_json` | Hash representation |
+| `#to_xml(format:)` | XML string (`:rss2` or `:atom`) |
+| `#etag` | ETag header from fetch (if applicable) |
+| `#last_modified` | Last-Modified header from fetch (if applicable) |
+| `#source` | Original source XML string |
+
+## Compatibility
+
+- Ruby 3.1+
+- No runtime dependencies
+
+## Development
+
+```bash
+# Run tests
+bundle exec rake test
+
+# Run linter
+bundle exec rubocop
+
+# Type checking
+bundle exec steep check
+
+# Interactive console
+bundle exec rake console
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Make your changes with tests
+4. Ensure tests pass (`bundle exec rake test`)
+5. Submit a pull request
+
+## Authors
+
+- [Lucas Carlson](mailto:lucas@rufy.com)
+- [Herval Freire](mailto:hervalfreire@gmail.com)
+
+Inspired by [Blagg](http://www.raelity.org/lang/perl/blagg) by Rael Dornfest.
+
+## License
+
+This library is released under the terms of the [GNU LGPL](LICENSE).

data/lib/simple-rss.rb

@@ -4,14 +4,24 @@ require "cgi"
 require "time"
 
 class SimpleRSS
-  VERSION = "2.0.0".freeze
+  # @rbs skip
+  include Enumerable
+
+  # @rbs!
+  #   include Enumerable[Hash[Symbol, untyped]]
+
+  VERSION = "2.1.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[
@@ -60,6 +70,65 @@ 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 (?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 +156,84 @@ class SimpleRSS
     def parse(source, options = {})
       new source, options
     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
@@ -265,6 +412,127 @@ class SimpleRSS
     tag.to_s.tr(":", "_").intern
   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;/?:@&=+$,\[\]]%)}

data/simple-rss.gemspec

@@ -1,14 +1,14 @@
 Gem::Specification.new do |s|
   s.name = "simple-rss"
-  s.version = "2.0.0"
-  s.date = "2025-12-28"
+  s.version = "2.1.0"
+  s.date = "2025-12-29"
   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

data/test/base/fetch_test.rb

@@ -0,0 +1,117 @@
+require "test_helper"
+require "net/http"
+
+class FetchTest < Test::Unit::TestCase
+  def setup
+    @sample_feed = File.read(File.dirname(__FILE__) + "/../data/rss20.xml")
+  end
+
+  # Test attr_readers exist and default to nil for parsed feeds
+
+  def test_etag_attr_reader_exists
+    rss = SimpleRSS.parse(@sample_feed)
+    assert_respond_to rss, :etag
+  end
+
+  def test_last_modified_attr_reader_exists
+    rss = SimpleRSS.parse(@sample_feed)
+    assert_respond_to rss, :last_modified
+  end
+
+  def test_etag_nil_for_parsed_feed
+    rss = SimpleRSS.parse(@sample_feed)
+    assert_nil rss.etag
+  end
+
+  def test_last_modified_nil_for_parsed_feed
+    rss = SimpleRSS.parse(@sample_feed)
+    assert_nil rss.last_modified
+  end
+
+  # Test fetch class method exists
+
+  def test_fetch_class_method_exists
+    assert_respond_to SimpleRSS, :fetch
+  end
+
+  # Test fetch with invalid URL raises error
+
+  def test_fetch_raises_on_invalid_host
+    # Socket::ResolutionError was added in Ruby 3.3, use SocketError for older versions
+    expected_errors = [SocketError, Errno::ECONNREFUSED, SimpleRSSError]
+    expected_errors << Socket::ResolutionError if defined?(Socket::ResolutionError)
+    assert_raise(*expected_errors) do
+      SimpleRSS.fetch("http://this-host-does-not-exist-12345.invalid/feed.xml", timeout: 1)
+    end
+  end
+
+  # Test fetch options are accepted
+
+  def test_fetch_accepts_etag_option
+    # Just verify it doesn't raise an ArgumentError
+    assert_nothing_raised do
+      SimpleRSS.fetch("http://localhost:1/feed.xml", etag: '"abc123"', timeout: 0.1)
+    rescue StandardError
+      # Expected - connection will fail
+    end
+  end
+
+  def test_fetch_accepts_last_modified_option
+    assert_nothing_raised do
+      SimpleRSS.fetch("http://localhost:1/feed.xml", last_modified: "Wed, 21 Oct 2015 07:28:00 GMT", timeout: 0.1)
+    rescue StandardError
+      # Expected - connection will fail
+    end
+  end
+
+  def test_fetch_accepts_headers_option
+    assert_nothing_raised do
+      SimpleRSS.fetch("http://localhost:1/feed.xml", headers: { "X-Custom" => "test" }, timeout: 0.1)
+    rescue StandardError
+      # Expected - connection will fail
+    end
+  end
+
+  def test_fetch_accepts_timeout_option
+    assert_nothing_raised do
+      SimpleRSS.fetch("http://localhost:1/feed.xml", timeout: 0.1)
+    rescue StandardError
+      # Expected - connection will fail
+    end
+  end
+
+  def test_fetch_accepts_follow_redirects_option
+    assert_nothing_raised do
+      SimpleRSS.fetch("http://localhost:1/feed.xml", follow_redirects: false, timeout: 0.1)
+    rescue StandardError
+      # Expected - connection will fail
+    end
+  end
+end
+
+# Integration tests that require network access
+# These are skipped by default, run with NETWORK_TESTS=1
+class FetchIntegrationTest < Test::Unit::TestCase
+  def test_fetch_real_feed
+    omit unless ENV["NETWORK_TESTS"]
+    # Use a reliable, long-lived RSS feed
+    rss = SimpleRSS.fetch("https://feeds.bbci.co.uk/news/rss.xml", timeout: 10)
+    assert_kind_of SimpleRSS, rss
+    assert rss.title
+    assert rss.items.any?
+  end
+
+  def test_fetch_stores_caching_headers
+    omit unless ENV["NETWORK_TESTS"]
+    rss = SimpleRSS.fetch("https://feeds.bbci.co.uk/news/rss.xml", timeout: 10)
+    # At least one of these should be present for most feeds
+    assert(rss.etag || rss.last_modified, "Expected ETag or Last-Modified header")
+  end
+
+  def test_fetch_follows_redirect
+    omit unless ENV["NETWORK_TESTS"]
+    # GitHub raw URLs often redirect
+    rss = SimpleRSS.fetch("https://github.com/cardmagic/simple-rss/commits/master.atom", timeout: 10)
+    assert_kind_of SimpleRSS, rss
+  end
+end

data/test/base/hash_xml_serialization_test.rb

@@ -0,0 +1,142 @@
+require "test_helper"
+
+class HashXmlSerializationTest < 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
+
+  # to_hash tests
+
+  def test_to_hash_returns_hash
+    result = @rss20.to_hash
+    assert_kind_of Hash, result
+  end
+
+  def test_to_hash_includes_feed_title
+    result = @rss20.to_hash
+    assert_equal "Technoblog", result[:title]
+  end
+
+  def test_to_hash_includes_items
+    result = @rss20.to_hash
+    assert_kind_of Array, result[:items]
+    assert_equal 10, result[:items].size
+  end
+
+  def test_to_hash_is_alias_for_as_json
+    assert_equal @rss20.as_json, @rss20.to_hash
+  end
+
+  # to_xml RSS 2.0 tests
+
+  def test_to_xml_returns_string
+    result = @rss20.to_xml
+    assert_kind_of String, result
+  end
+
+  def test_to_xml_default_format_is_rss2
+    result = @rss20.to_xml
+    assert_match(/<rss version="2.0">/, result)
+  end
+
+  def test_to_xml_rss2_has_xml_declaration
+    result = @rss20.to_xml(format: :rss2)
+    assert_match(/^<\?xml version="1.0" encoding="UTF-8"\?>/, result)
+  end
+
+  def test_to_xml_rss2_has_channel
+    result = @rss20.to_xml(format: :rss2)
+    assert_match(/<channel>/, result)
+    assert_match(%r{</channel>}, result)
+  end
+
+  def test_to_xml_rss2_has_title
+    result = @rss20.to_xml(format: :rss2)
+    assert_match(%r{<title>Technoblog</title>}, result)
+  end
+
+  def test_to_xml_rss2_has_link
+    result = @rss20.to_xml(format: :rss2)
+    assert_match(%r{<link>http://tech.rufy.com</link>}, result)
+  end
+
+  def test_to_xml_rss2_has_items
+    result = @rss20.to_xml(format: :rss2)
+    assert_match(/<item>/, result)
+    assert_match(%r{</item>}, result)
+  end
+
+  def test_to_xml_rss2_item_has_title
+    result = @rss20.to_xml(format: :rss2)
+    assert_match(/<item>\n<title>/, result)
+  end
+
+  def test_to_xml_rss2_item_has_guid
+    result = @rss20.to_xml(format: :rss2)
+    assert_match(%r{<guid>http://tech.rufy.com/entry/\d+</guid>}, result)
+  end
+
+  def test_to_xml_rss2_escapes_special_characters
+    rss = SimpleRSS.parse('<rss version="2.0"><channel><title>Test &amp; Title</title><item><title>Item &lt;1&gt;</title></item></channel></rss>')
+    result = rss.to_xml(format: :rss2)
+    assert_match(/&amp;/, result)
+  end
+
+  # to_xml Atom tests
+
+  def test_to_xml_atom_format
+    result = @atom.to_xml(format: :atom)
+    assert_match(%r{<feed xmlns="http://www.w3.org/2005/Atom">}, result)
+  end
+
+  def test_to_xml_atom_has_title
+    result = @atom.to_xml(format: :atom)
+    assert_match(%r{<title>dive into mark</title>}, result)
+  end
+
+  def test_to_xml_atom_has_link
+    result = @atom.to_xml(format: :atom)
+    assert_match(%r{<link href="http://example.org/" rel="alternate"/>}, result)
+  end
+
+  def test_to_xml_atom_has_entries
+    result = @atom.to_xml(format: :atom)
+    assert_match(/<entry>/, result)
+    assert_match(%r{</entry>}, result)
+  end
+
+  def test_to_xml_atom_entry_has_title
+    result = @atom.to_xml(format: :atom)
+    assert_match(%r{<entry>\n<title>Atom draft-07 snapshot</title>}, result)
+  end
+
+  # Error handling
+
+  def test_to_xml_raises_on_unknown_format
+    assert_raise(ArgumentError) { @rss20.to_xml(format: :unknown) }
+  end
+
+  def test_to_xml_error_message_includes_supported_formats
+    error = assert_raise(ArgumentError) { @rss20.to_xml(format: :foo) }
+    assert_match(/Supported: :rss2, :atom/, error.message)
+  end
+
+  # Round-trip tests
+
+  def test_to_xml_rss2_can_be_reparsed
+    xml = @rss20.to_xml(format: :rss2)
+    reparsed = SimpleRSS.parse(xml)
+
+    assert_equal "Technoblog", reparsed.title
+    assert_equal 10, reparsed.items.size
+  end
+
+  def test_to_xml_atom_can_be_reparsed
+    xml = @atom.to_xml(format: :atom)
+    reparsed = SimpleRSS.parse(xml)
+
+    assert_equal "dive into mark", reparsed.title
+    assert_equal 1, reparsed.items.size
+  end
+end

data/test/base/json_serialization_test.rb

@@ -0,0 +1,81 @@
+require "test_helper"
+require "json"
+
+class JsonSerializationTest < 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_as_json_returns_hash
+    result = @rss20.as_json
+    assert_kind_of Hash, result
+  end
+
+  def test_as_json_includes_feed_title
+    result = @rss20.as_json
+    assert_equal "Technoblog", result[:title]
+  end
+
+  def test_as_json_includes_feed_link
+    result = @rss20.as_json
+    assert_equal "http://tech.rufy.com", result[:link]
+  end
+
+  def test_as_json_includes_items
+    result = @rss20.as_json
+    assert_kind_of Array, result[:items]
+    assert_equal 10, result[:items].size
+  end
+
+  def test_as_json_items_have_title
+    result = @rss20.as_json
+    assert result[:items].first[:title].include?("some_string.starts_with?")
+  end
+
+  def test_as_json_converts_time_to_iso8601
+    result = @rss20.as_json
+    pub_date = result[:items].first[:pubDate]
+    assert_kind_of String, pub_date
+    assert_match(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/, pub_date)
+  end
+
+  def test_as_json_works_with_atom
+    result = @atom.as_json
+    assert_equal "dive into mark", result[:title]
+    assert_equal 1, result[:items].size
+  end
+
+  def test_to_json_returns_string
+    result = @rss20.to_json
+    assert_kind_of String, result
+  end
+
+  def test_to_json_is_valid_json
+    result = @rss20.to_json
+    parsed = JSON.parse(result)
+    assert_kind_of Hash, parsed
+  end
+
+  def test_to_json_roundtrip
+    json_string = @rss20.to_json
+    parsed = JSON.parse(json_string, symbolize_names: true)
+
+    assert_equal "Technoblog", parsed[:title]
+    assert_equal 10, parsed[:items].size
+    assert parsed[:items].first[:title].include?("some_string.starts_with?")
+  end
+
+  def test_as_json_excludes_nil_feed_tags
+    result = @rss20.as_json
+    # Feed tags that weren't in the source shouldn't appear
+    refute result.key?(:subtitle)
+    refute result.key?(:id)
+  end
+
+  def test_as_json_accepts_options_parameter
+    # Should not raise, even if options aren't used yet
+    result = @rss20.as_json(only: [:title])
+    assert_kind_of Hash, result
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: simple-rss
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Lucas Carlson
 bindir: bin
 cert_chain: []
-date: 2025-12-28 00:00:00.000000000 Z
+date: 2025-12-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -60,7 +60,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
-- README.markdown
+- README.md
 - Rakefile
 - lib/simple-rss.rb
 - simple-rss.gemspec
@@ -68,8 +68,12 @@ files:
 - test/base/base_test.rb
 - test/base/empty_tag_test.rb
 - test/base/encoding_test.rb
+- test/base/enumerable_test.rb
 - test/base/feed_attributes_test.rb
+- test/base/fetch_test.rb
+- test/base/hash_xml_serialization_test.rb
 - test/base/item_attributes_test.rb
+- test/base/json_serialization_test.rb
 - test/data/atom.xml
 - test/data/atom_with_entry_attrs.xml
 - test/data/atom_with_feed_attrs.xml
@@ -81,7 +85,7 @@ files:
 - test/data/rss20_with_channel_attrs.xml
 - test/data/rss20_with_item_attrs.xml
 - test/test_helper.rb
-homepage: http://github.com/cardmagic/simple-rss
+homepage: https://github.com/cardmagic/simple-rss
 licenses: []
 metadata: {}
 rdoc_options: []
@@ -91,7 +95,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/README.markdown

@@ -1,47 +0,0 @@
-## Welcome to Simple RSS
-
-Simple RSS is 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.
-
-## Download
-
-* gem install simple-rss
-* https://github.com/cardmagic/simple-rss
-* git clone git@github.com:cardmagic/simple-rss.git
-
-### Usage
-The API is similar to Ruby's standard RSS parser:
-
-    require 'rubygems'
-    require 'simple-rss'
-    require 'open-uri'
-
-    rss = SimpleRSS.parse open('http://rss.slashdot.org/Slashdot/slashdot/to')
-
-    rss.channel.title # => "Slashdot"
-    rss.channel.link # => "http://slashdot.org/"
-    rss.items.first.link # => "http://books.slashdot.org/article.pl?sid=05/08/29/1319236&from=rss"
-
-But since the parser can read Atom feeds as easily as RSS feeds, there are optional aliases that allow more atom like reading:
-
-    rss.feed.title # => "Slashdot"
-    rss.feed.link # => "http://slashdot.org/"
-    rss.entries.first.link # => "http://books.slashdot.org/article.pl?sid=05/08/29/1319236&from=rss"
-
-The parser does not care about the correctness of the XML as it does not use an XML library to read the information. Thus it is flexible and allows for easy extending via:
-
-    SimpleRSS.feed_tags << :some_new_tag
-    SimpleRSS.item_tags << :"item+myrel" # this will extend SimpleRSS to be able to parse RSS items or ATOM entries that have a rel specified, common in many blogger feeds
-    SimpleRSS.item_tags << :"feedburner:origLink" # this will extend SimpleRSS to be able to parse RSS items or ATOM entries that have a specific pre-tag specified, common in many feedburner feeds
-    SimpleRSS.item_tags << :"media:content#url" # this will grab the url attribute of the media:content tag 
-
-## Authors
-
-* Lucas Carlson  (mailto:lucas@rufy.com)
-* Herval Freire (mailto:hervalfreire@gmail.com)
-
-Inspired by [Blagg](http://www.raelity.org/lang/perl/blagg) from Rael Dornfest.
-
-This library is released under the terms of the GNU LGPL.
-