`feed` API reference

Web syndication feeds: build and parse both RSS 2.0 and Atom 1.0 through one module. A feed is a value-semantic Feed (title, link, updated, entries) of Entry (title, link, id, published / updated, summary, content). The format is chosen when you build ("rss" or "atom") and detected from the root element when you parse, so the same Feed shape serves both - a feed reader, podcast client, news aggregator, or changelog-to-feed generator.

Parsing rides the xml library (entities, CDATA, Atom's namespaces); building emits escaped XML through the same. Dates go through time (RFC 822 pubDate for RSS, RFC 3339 updated for Atom); an unset date is the Unix epoch and is omitted on build. fetch pulls a feed over the http module.

Import with import "feed.j" as feed;. See the feed guide for prose and examples.

Functions

`feed.add(f as Feed, e as Entry)`

A copy of f with e appended to its entries.

Parameters

f {Feed} - the source feed
e {Entry} - the entry to append

Returns {Feed} - the feed with the entry added

`feed.build(f as Feed, format as string)`

Render f to feed XML in the named format: "rss" (RSS 2.0) or "atom" (Atom 1.0). Values are XML-escaped; unset dates are omitted.

Parameters

f {Feed} - the feed to render
format {string} - "rss" or "atom"

Returns {string} - the feed document as XML text

Throws

{Error} - when format is not "rss" or "atom"

`feed.entry(title as string, link as string)`

A new Entry with the given title and link (empty id / summary / content, unset dates).

Parameters

title {string} - the entry title
link {string} - the entry URL

Returns {Entry} - the new entry

`feed.entryAuthor(e as Entry, author as string)`

A copy of e with its author set.

Parameters

e {Entry} - the source entry
author {string} - the item author (a name or email)

Returns {Entry} - the updated entry

`feed.entryCategory(e as Entry, category as string)`

A copy of e with category appended to its category tags.

Parameters

e {Entry} - the source entry
category {string} - the category / tag to add

Returns {Entry} - the entry with the category added

`feed.entryContent(e as Entry, c as string)`

A copy of e with its full content set (Atom).

Parameters

e {Entry} - the source entry
c {string} - the content text

Returns {Entry} - the updated entry

`feed.entryEnclosure(e as Entry, url as string, length as int, type as string)`

A copy of e with a media enclosure set (the podcast / audio / video file).

Parameters

e {Entry} - the source entry
url {string} - the media URL
length {int} - the media size in bytes (0 when unknown)
type {string} - the MIME type (e.g. "audio/mpeg")

Returns {Entry} - the entry with the enclosure set

`feed.entryId(e as Entry, id as string)`

A copy of e with its stable id set.

Parameters

e {Entry} - the source entry
id {string} - the identifier (RSS guid / Atom id)

Returns {Entry} - the updated entry

`feed.entryPublished(e as Entry, t as time.Time)`

A copy of e with its published instant set.

Parameters

e {Entry} - the source entry
t {time.Time} - the first-published instant

Returns {Entry} - the updated entry

`feed.entrySummary(e as Entry, s as string)`

A copy of e with its summary set.

Parameters

e {Entry} - the source entry
s {string} - the summary / description text

Returns {Entry} - the updated entry

`feed.entryUpdated(e as Entry, t as time.Time)`

A copy of e with its updated instant set.

Parameters

e {Entry} - the source entry
t {time.Time} - the last-updated instant

Returns {Entry} - the updated entry

`feed.feed(title as string, link as string)`

A new empty Feed with the given title and site link (no entries, unset date).

Parameters

title {string} - the feed title
link {string} - the feed's site URL

Returns {Feed} - the new feed

`feed.feedAuthor(f as Feed, author as string)`

A copy of f with its author set.

Parameters

f {Feed} - the source feed
author {string} - the feed author (a name or email)

Returns {Feed} - the updated feed

`feed.feedCategory(f as Feed, category as string)`

A copy of f with category appended to its category tags.

Parameters

f {Feed} - the source feed
category {string} - the category / tag to add

Returns {Feed} - the feed with the category added

`feed.feedUpdated(f as Feed, t as time.Time)`

A copy of f with its updated instant set.

Parameters

f {Feed} - the source feed
t {time.Time} - the last-updated instant

Returns {Feed} - the updated feed

`feed.fetch(url as string)`

Fetch a feed over HTTP and parse it: http.get the URL, then parse the body. Needs the http module (the default jennifer; a friendly network error on jennifer-tiny).

Parameters

url {string} - the feed URL

Returns {Feed} - the fetched, parsed feed

Throws

{Error} - on a transport error, a non-2xx status, or malformed feed XML

`feed.hasEnclosure(e as Entry)`

Report whether an entry carries a media enclosure (a non-empty enclosure url).

Parameters

e {Entry} - the entry to test

Returns {bool} - true when the entry has an attached media file

`feed.kind(text as string)`

The feed format of text, by its root element: "rss" or "atom".

Parameters

text {string} - the feed XML

Returns {string} - "rss" or "atom"

Throws

{Error} - when the XML is malformed or the root is neither

`feed.parse(text as string)`

Parse feed XML into a Feed, detecting RSS vs Atom from the root element. Malformed dates degrade to the epoch sentinel rather than failing the parse.

Parameters

text {string} - the feed XML (RSS 2.0 or Atom 1.0)

Returns {Feed} - the parsed feed

Throws

{Error} - when the XML is malformed or the root is neither feed format

Structs

`feed.Enclosure`

A media enclosure attached to an entry: the podcast / audio / video file. Maps to RSS <enclosure url length type> and Atom <link rel="enclosure">. An entry with an empty url has no enclosure (omitted on build).

Field	Type	Description
`url`	`string`	the media URL
`length`	`int`	the media size in bytes (0 when unknown)
`type`	`string`	the MIME type (e.g. "audio/mpeg")

`feed.Entry`

One feed item. link is the item URL, id its stable identifier (RSS guid / Atom id), summary a short description (RSS description / Atom summary) and content the full body (Atom content; RSS carries only the one description, mapped to summary). author is the item author, categories its tags, and enclosure an attached media file (podcast episode). An unset date is the Unix epoch.

Field	Type	Description
`title`	`string`	the entry title
`link`	`string`	the entry URL
`id`	`string`	the stable identifier (RSS guid / Atom id)
`published`	`time.Time`	the first-published instant (epoch if unset)
`updated`	`time.Time`	the last-updated instant (epoch if unset)
`summary`	`string`	a short summary / description
`content`	`string`	the full content (Atom only)
`author`	`string`	the item author (RSS author / dc:creator, Atom author/name)
`categories`	`list of string`	the item's category tags
`enclosure`	`Enclosure`	an attached media file (empty url = none)

`feed.Feed`

A syndication feed: channel-level metadata plus its entries.

Field	Type	Description
`title`	`string`	the feed title
`link`	`string`	the feed's site URL
`updated`	`time.Time`	the feed's last-build / updated instant (epoch if unset)
`entries`	`list of Entry`	the feed items, in document order
`author`	`string`	the feed author (RSS managingEditor, Atom author/name)
`categories`	`list of string`	the feed's category tags

#feed API reference

#Functions

#feed.add(f as Feed, e as Entry)

#feed.build(f as Feed, format as string)

#feed.entry(title as string, link as string)

#feed.entryAuthor(e as Entry, author as string)

#feed.entryCategory(e as Entry, category as string)

#feed.entryContent(e as Entry, c as string)

#feed.entryEnclosure(e as Entry, url as string, length as int, type as string)

#feed.entryId(e as Entry, id as string)

#feed.entryPublished(e as Entry, t as time.Time)

#feed.entrySummary(e as Entry, s as string)

#feed.entryUpdated(e as Entry, t as time.Time)

#feed.feed(title as string, link as string)

#feed.feedAuthor(f as Feed, author as string)

#feed.feedCategory(f as Feed, category as string)

#feed.feedUpdated(f as Feed, t as time.Time)

#feed.fetch(url as string)

#feed.hasEnclosure(e as Entry)

#feed.kind(text as string)

#feed.parse(text as string)

#Structs

#feed.Enclosure

#feed.Entry

#feed.Feed

`feed` API reference

Functions

`feed.add(f as Feed, e as Entry)`

`feed.build(f as Feed, format as string)`

`feed.entry(title as string, link as string)`

`feed.entryAuthor(e as Entry, author as string)`

`feed.entryCategory(e as Entry, category as string)`

`feed.entryContent(e as Entry, c as string)`

`feed.entryEnclosure(e as Entry, url as string, length as int, type as string)`

`feed.entryId(e as Entry, id as string)`

`feed.entryPublished(e as Entry, t as time.Time)`

`feed.entrySummary(e as Entry, s as string)`

`feed.entryUpdated(e as Entry, t as time.Time)`

`feed.feed(title as string, link as string)`

`feed.feedAuthor(f as Feed, author as string)`

`feed.feedCategory(f as Feed, category as string)`

`feed.feedUpdated(f as Feed, t as time.Time)`

`feed.fetch(url as string)`

`feed.hasEnclosure(e as Entry)`

`feed.kind(text as string)`

`feed.parse(text as string)`

Structs

`feed.Enclosure`

`feed.Entry`

`feed.Feed`