Results and normalized data

Copy Markdown

FeedReader 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, and parse_stream/2 return {:ok, %FeedReader.ParseResult{feed: feed, items: items, item_limit_reached?: limit_reached?}}.
  • fetch_and_parse/2 returns {: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_items cap is reached, parsing stops and item_limit_reached? is true; the returned items may be only a prefix of the feed. If the cap is omitted, the field is false.

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

FieldMeaning
titleNormalized feed title, with format-specific fallbacks.
descriptionFeed description or subtitle when present.
feed_urlSource URL. For remote parsing this defaults to the final response URL; local parsing defaults to nil.
html_urlFeed's website URL when available.
typeBuilt-in format: :rss, :atom, or :rdf.
categoriesUnique category or subject strings.
extensionsExtension metadata keyed by namespace URI when retained by the format handler.

Item fields

FieldMeaning
uuidSource identifier, with a canonical URL fallback for some formats.
titleNormalized and, for RSS and Atom, sanitized title.
content_fullFull item content when supplied.
content_summarySummary or description, sometimes falling back to title.
languageLanguage detected from a bounded sample of item text.
published_atParsed UTC DateTime when available.
canonical_urlItem URL; root-relative URLs are resolved against feed URLs.
alternateAlternate links when exposed by a format handler.
authorNormalized author name when available.
extensionsExtension 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.

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.