README
¶
rss
RSS is a small library for simplifying the parsing of RSS and Atom feeds. The package conforms to the RSS 1.0, RSS 2.0, and Atom 1.0 specifications.
If you encounter any problems with feeds being parsed incorrectly, please open an issue on GitHub.
Example usage:
package main
import (
"context"
"github.com/SlyMarbo/rss/v2"
)
func main() {
reader, err := rss.NewReader()
if err != nil {
// handle error.
}
feed, err := reader.Fetch(context.Background(), "https://example.com/rss")
if err != nil {
// handle error.
}
// ... Some time later ...
err = reader.UpdatePatiently(feed)
if err != nil {
// handle error.
}
}
The library does its best to follow the appropriate specifications and not to set the NextUpdate time
too soon. It currently follows all update time management methods in the RSS 1.0, 2.0, and Atom 1.0
specifications. If one is not provided, it defaults to 12 hour intervals. If you are having issues
with feed providors dropping connections, use WithDefaultUpdateInterval to set the default update
interval.
The project is not proactively maintained, but I'll respond to issues and PRs as soon as I can.
Documentation
¶
Overview ¶
Package rss is a small library for simplifying the parsing of RSS and Atom feeds.
The package conforms to the RSS 1.0, RSS 2.0, and Atom 1.0 specifications.
If you encounter any problems with feeds being parsed incorrectly, please open an issue on GitHub.
Example usage:
package main
import (
"context"
"github.com/SlyMarbo/rss/v2"
)
func main() {
ctx := context.Background()
reader, err := rss.NewReader()
if err != nil {
// handle error.
}
feed, err := reader.Fetch(ctx, "https://example.com/rss")
if err != nil {
// handle error.
}
// ... Some time later ...
err = reader.UpdatePatiently(ctx, feed)
if err != nil {
// handle error.
}
}
The library does its best to follow the appropriate specifications and not to set the `NextUpdate` time too soon. It currently follows all update time management methods in the RSS 1.0, 2.0, and Atom 1.0 specifications. If one is not provided, it defaults to 12 hour intervals. If you are having issues with feed providors dropping connections, use `WithDefaultUpdateInterval` to set the default update interval.
The project is not proactively maintained, but I'll respond to issues and PRs as soon as I can.
Index ¶
- Variables
- type Author
- type Enclosure
- type Feed
- type Image
- type Item
- type Link
- type Option
- func WithDefaultUpdateInterval(interval time.Duration) Option
- func WithExtraTimeLayouts(layouts ...string) Option
- func WithExtraTimeLayoutsWithNamedLocation(layouts ...string) Option
- func WithHTTPClient(client *http.Client) Option
- func WithLogger(logger *slog.Logger) Option
- func WithNow(now func() time.Time) Option
- type Reader
- func (r *Reader) ConvertAtom1(url string, atomFeed *atom1.Feed) (*Feed, error)
- func (r *Reader) ConvertRSS1(url string, rssFeed *rss1.Feed) (*Feed, error)
- func (r *Reader) ConvertRSS2(url string, rssFeed *rss2.Feed) (*Feed, error)
- func (r *Reader) Fetch(ctx context.Context, url string) (*Feed, error)
- func (r *Reader) Parse(url string, data io.Reader) (*Feed, error)
- func (r *Reader) Update(ctx context.Context, feed *Feed) error
- func (r *Reader) UpdatePatiently(ctx context.Context, feed *Feed) error
Constants ¶
This section is empty.
Variables ¶
var ErrTooSoon = errors.New("rss: too soon to update feed")
ErrTooSoon indicates that a feed cannot be updated yet, as the desired interval between updates has not yet elapsed.
Functions ¶
This section is empty.
Types ¶
type Feed ¶
type Feed struct {
Title string
Language string
Author *Author
Description string
Links []*Link // Link to the creator's website.
UpdateURL string // URL of the feed itself.
Image *Image // Optional feed icon.
Categories []string
Items []*Item
NextUpdate time.Time // Earliest time this feed should next be checked.
Unread uint32 // Number of unread items. Used by aggregators.
}
Feed is the top-level structure for an RSS/Atom feed.
type Item ¶
type Item struct {
Title string
Summary string
Content string
Categories []string
Links []*Link
Date time.Time
Image *Image
ID string
Enclosures []*Enclosure
// When items are stored, they are
// marked as unread (Read is false).
// This can be used by aggregators
// to track when the user has read
// the item.
Read bool
}
Item represents a single story.
type Option ¶
Option represents a function that can be used to configure a Reader. Options are typically used with NewReader.
func WithDefaultUpdateInterval ¶
WithDefaultUpdateInterval configures the reader to use the given minimum interval between updates if the feed has not specified its interval.
func WithExtraTimeLayouts ¶
WithExtraTimeLayouts configures the reader to use the given time layouts in addition to the built-in layouts when tyring to parse timestamps.
These layouts must not use names like `"EST"` to represent time zones. If the layouts do use named locations, use WithExtraTimeLayoutsWithNamedLocation instead.
func WithExtraTimeLayoutsWithNamedLocation ¶
WithExtraTimeLayoutsWithNamedLocation configures the reader to use the given time layouts in addition to the built-in layouts when tyring to parse timestamps.
These layouts can use names like `"EST"` to represent time zones. If the layouts do not use named locations, use WithExtraTimeLayouts instead.
func WithHTTPClient ¶
WithHTTPClient configures the reader to use the given HTTP client when fetching or updating feeds.
func WithLogger ¶
WithLogger configures the reader to use the given structured logger.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader stores the configuration data used to fetch, parse, and update RSS feeds. Reader supports RSS 2.0, RSS 1.0, and Atom 1.0. A single Reader can process many different feeds.
func NewReader ¶
NewReader is used to configure a Reader. The resulting reader will start with sensible defaults, which are then updated by any provided options.
NewReader will only return an error if one of the provided options fails.
func (*Reader) ConvertAtom1 ¶
ConvertAtom1 transforms data in Atom 1.0 format to this package's equivalent data structures.
Most users should use Reader.Parse instead.
func (*Reader) ConvertRSS1 ¶
ConvertRSS1 transforms data in RSS 1.0 format to this package's equivalent data structures.
Most users should use Reader.Parse instead.
func (*Reader) ConvertRSS2 ¶
ConvertRSS2 transforms data in RSS 1.0 format to this package's equivalent data structures.
Most users should use Reader.Parse instead.
func (*Reader) Update ¶
Update attempts to update the feed with new items. If it is too soon to update the feed, Update will return immediately with ErrTooSoon.
Callers that would rather wait until an update can be performed should instead use Reader.UpdatePatiently.
func (*Reader) UpdatePatiently ¶
UpdatePatiently attempts to update the feed with new items. If it is too soon to update the feed, UpdatePatiently will wait until the chosen interval has elapsed and then attempt an update. If the given context expires while UpdatePatiently is waiting, it will return with the context's error.
Callers that would rather return immediately if it is too soon to perform an update should instead use Reader.Update.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package atom1 provides parsing functionality for [Atom] feeds.
|
Package atom1 provides parsing functionality for [Atom] feeds. |
|
cmd
|
|
|
rss-new-test
command
Command rss-new-test is a helper for recording new test vectors.
|
Command rss-new-test is a helper for recording new test vectors. |
|
internal
|
|
|
testar
Package testar is a small helper for checking test vectors in txtar archives.
|
Package testar is a small helper for checking test vectors in txtar archives. |
|
Package rss1 provides parsing functionality for [RSS 1.0] feeds.
|
Package rss1 provides parsing functionality for [RSS 1.0] feeds. |
|
Package rss2 provides parsing functionality for [RSS 2.0] feeds.
|
Package rss2 provides parsing functionality for [RSS 2.0] feeds. |