simple-rss 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d7399eb7c1eee38cca3bd3de50a18cdedbf85b1aeb8536688b628abca814cab
-  data.tar.gz: 7a27767cd9be24307344430c311507859ac825d7845ea9e703985355dd3ccfa3
+  metadata.gz: 0b914acfc63bfc4e787b6a0373e6c4fbbcec1b953a6517a2709a70b96e5993a6
+  data.tar.gz: 26e9dddcca6e05b34e8ef6da52a3654fadb6932ac9558f9ee8e70117e99f1e9f
 SHA512:
-  metadata.gz: 6e01cdc590e4fdac9d0be8df7307491b8f67e8b68422d7970b589b72e52872f8dab23935a6225b05993f4adf614f4641d24e0a23538daf7ed512969d1104a84f
-  data.tar.gz: 3568cebc46ca358c7d3a49b0615d49592ed7698e5fcb0c60a3a392c1904de4d4fb7d03fec3ac1d5270ada6c8679737c3a91b880e8dfb91d7aaa69bbfc1f9dab4
+  metadata.gz: 0bbb1967e261cec7c2fdb1bb00fd511562a4647043c40f5b7b6e56aedc5d8d8f003727988ffd2fb77fb7291b397d41008e40eb3a14d156889168423d90f934c5
+  data.tar.gz: c1428ee431c4bfd718a573d2d89e5121e9cef46cbd1ce5ade80b21b9bc98b939f35dcdd133287fb70de83c3a00b7a5099d97a2f12699c6224a194c874a42e215

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).