Results and normalized data
Copy MarkdownFeedReader normalizes RSS, Atom, and RDF input into two structs:
FeedReader.Feed for feed-level metadata and FeedReader.Item for each entry.
Collection APIs wrap them in result structs; streaming APIs emit them as
events.
Collection results
parse_file/2,parse_binary/2, andparse_stream/2return{:ok, %FeedReader.ParseResult{feed: feed, items: items, item_limit_reached?: limit_reached?}}.fetch_and_parse/2returns{:ok, %FeedReader.RemoteResult{feed: feed, items: items, fetch: fetch, item_limit_reached?: limit_reached?}}.- Collection gathers all accepted items by default. If an optional positive
:max_itemscap is reached, parsing stops anditem_limit_reached?istrue; the returned items may be only a prefix of the feed. If the cap is omitted, the field isfalse.
Remote calls may instead return {:ok, :not_modified} after a conditional
HTTP 304 or {:ok, :not_changed} after a matching decoded-body checksum.
Those outcomes contain no parsed result.
Stream events
The events enumerable in a %FeedReader.Session{} emits:
{:feed, %FeedReader.Feed{}}
{:item, %FeedReader.Item{}}
{:error, reason}Feed metadata is emitted before items. A parser failure is a terminal error
event; an error that prevents session creation is returned directly from the
API as {:error, reason}. See Streaming and verified parsing
for consumption and cleanup patterns.
Feed fields
| Field | Meaning |
|---|---|
title | Normalized feed title, with format-specific fallbacks. |
description | Feed description or subtitle when present. |
feed_url | Source URL. For remote parsing this defaults to the final response URL; local parsing defaults to nil. |
html_url | Feed's website URL when available. |
type | Built-in format: :rss, :atom, or :rdf. |
categories | Unique category or subject strings. |
media | Ordered image resources. RSS channel images and direct RDF channel image references become :logo; Atom feed icons and logos become :icon and :logo. Feed media is snapshotted before the first item, so later feed-level media is omitted; feeds without items use completed metadata. |
extensions | Extension metadata keyed by namespace URI when retained by the format handler. |
Item fields
| Field | Meaning |
|---|---|
uuid | Source identifier, with a canonical URL fallback for some formats. |
title | Normalized and, for RSS and Atom, sanitized title. |
content_full | Full item content when supplied. |
content_summary | Summary or description, sometimes falling back to title. |
language | Language detected from a bounded sample of item text. |
published_at | Parsed UTC DateTime when available. |
canonical_url | Item URL; root-relative URLs are resolved against feed URLs. |
media | Ordered resources: RSS image/audio enclosures, Atom image/audio enclosure links and external image content, plus Media RSS image/audio content and image-only thumbnails in RSS, Atom, and RDF items. Other enclosure types, ordinary links, and media-like markup outside supported locations are omitted. |
author | Normalized author name when available. |
extensions | Extension metadata keyed by namespace URI when retained by the format handler. |
Fields may be nil when the source does not provide a value. Format handlers
also have format-specific fallback behavior. For example, RDF currently uses
the current UTC time when its date is missing or invalid, while RSS and Atom
leave an unparseable date as nil.
Media values
Each media entry is a %FeedReader.Media{} with url, kind, role,
mime_type, title, width, and height. RSS enclosures and Atom enclosure
links support image and audio MIME types; Atom external entry content remains
image-only. Media RSS content may be image or audio; its kind must be
unambiguous from medium and/or type. Media RSS thumbnails remain images.
Resources without a usable URL are omitted. Image and audio MIME types are
normalized to lowercase without parameters; invalid optional dimensions and
metadata are nil.
URLs are trimmed. Single-slash root-relative URLs resolve against the feed's HTML
URL, then source URL; other relative and scheme-relative references remain as-is.
Entries preserve encounter order, including interleaved enclosure/content/
thumbnail types and a content element before its nested thumbnail.
| Role | Sources |
|---|---|
:content | Image- or audio-identified Media RSS content; Atom external entry content with an image MIME type. |
:thumbnail | Image-only Media RSS thumbnail elements, including grouped and content-nested thumbnails. |
:enclosure | RSS image/audio enclosures and Atom entry links with rel="enclosure" and an image/audio MIME type. |
:icon, :logo | Atom feed icon/logo; RSS channel image and direct RDF channel image reference are :logo. |
Media RSS content accepts medium="image" or medium="audio" with no type or
the matching MIME type, or an image/audio MIME type with no medium. When both
are present they must agree. Missing or unsupported declarations, including
application/octet-stream, are omitted rather than guessed. Thumbnails follow
their element semantics; their MIME type is retained only when it identifies an
image. Media is collected only from the documented direct feed/item locations,
not scraped from HTML or unrelated extension markup.
Standard RSS and Atom enclosures require a MIME type whose top-level type is
image or audio; other types, including application/octet-stream, are
omitted. Atom external <content src> remains image-only.
Common errors and limit behavior
Errors are returned as {:error, reason}. Common reasons include :unknown
for undetected or unregistered formats, :invalid_url, :invalid_path, HTTP
status errors, XML parser errors, and {:resource_limit, option, limit}.
Exact transport and parser reasons can depend on the underlying library.
Collection APIs accept an optional :max_items cap. When reached, collection
stops successfully with the items gathered so far and sets
item_limit_reached?: true; the rest of the feed is not checked for parse
errors. The cap controls retained item count, not downloaded bytes or input
staging. Without a cap, collection retains every accepted item.