simple-rss 1.3.3 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ec1f1ac7917068016cb104c8167d66cfe171ea4d1abc6275b3691d4cfc7609c
-  data.tar.gz: 81320090aa73a8befaf55ed41ac80cc19f11ebdd7e1aeb733f016f1617281e93
+  metadata.gz: f7e2a8e829ef0776194df8fd028266dbcecaeb0a5b7b1025aa75b739acbd6ad9
+  data.tar.gz: 664c6319db58dab8bf81e9f540afb6f1251997fa669b3e433a30748eb599ac16
 SHA512:
-  metadata.gz: c95d7d0111de45e671d01a2e05b14548e7d4e4d0152c2ff1e4f5f1eca8c7d5fbb9b184eca08da0439cd6322513fdc370102df6931ea26f795c447b6fdeb9553c
-  data.tar.gz: 628901aedd08ff41428e44eb37e79fc1b5ed3d77ddc00613d0a3b2c4d0b0c1c6f663b724a1048fbd297bc84943ba3ce2f8ce0e80fb67d153a19e94f4eae6d7df
+  metadata.gz: 3885af60f0b54553af1e3545a781f6f1179825386cc3edcf1575ed75bb79240eefc83998295d21e842287f1c949a0554918d39d1df1df924701d27f20b26c192
+  data.tar.gz: 81394817f11b09d433eb7b07031120661a7de18d678deff66fdbf4f331f8ec6483a155069f36539e4ba6122210ec3c58cf08b67f3a44d9afc582c0952861d073

data/LICENSE

@@ -1,8 +1,8 @@
-		  GNU LESSER GENERAL PUBLIC LICENSE
-		       Version 2.1, February 1999
+                  GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 2.1, February 1999
 
  Copyright (C) 1991, 1999 Free Software Foundation, Inc.
-     59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ <https://fsf.org/>
  Everyone is permitted to copy and distribute verbatim copies
  of this license document, but changing it is not allowed.
 
@@ -10,7 +10,7 @@
  as the successor of the GNU Library Public License, version 2, hence
  the version number 2.1.]
 
-			    Preamble
+                            Preamble
 
   The licenses for most software are designed to take away your
 freedom to share and change it.  By contrast, the GNU General Public
@@ -112,7 +112,7 @@ modification follow.  Pay close attention to the difference between a
 former contains code derived from the library, whereas the latter must
 be combined with the library in order to run.
 
-		  GNU LESSER GENERAL PUBLIC LICENSE
+                  GNU LESSER GENERAL PUBLIC LICENSE
    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
 
   0. This License Agreement applies to any software library or other
@@ -146,7 +146,7 @@ such a program is covered only if its contents constitute a work based
 on the Library (independent of the use of the Library in a tool for
 writing it).  Whether that is true depends on what the Library does
 and what the program that uses the Library does.
-  
+
   1. You may copy and distribute verbatim copies of the Library's
 complete source code as you receive it, in any medium, provided that
 you conspicuously and appropriately publish on each copy an
@@ -426,4 +426,76 @@ the Free Software Foundation.
   14. If you wish to incorporate parts of the Library into other free
 programs whose distribution conditions are incompatible with these,
 write to the author to ask for permission.  For software which is
-copyrighted by
+copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this.  Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.
+
+                            NO WARRANTY
+
+  15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+           How to Apply These Terms to Your New Libraries
+
+  If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change.  You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms of the
+ordinary General Public License).
+
+  To apply these terms, attach the following notices to the library.  It is
+safest to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the library's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2.1 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the library, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the
+  library `Frob' (a library for tweaking knobs) written by James Random Hacker.
+
+  <signature of Moe Ghoul>, 1 April 1990
+  Moe Ghoul, President of Vice
+
+That's all there is to it!

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