feeds

README

===== feeds ====================================================================

feeds is a general-use library for syndication formats.

===== usage ====================================================================

feeds contains a central, protocol-agnostic package "feeds" and extra packages
to support specific protocols. For some input bytes "raw", you can parse a
specific protocol:

  atomFeed, err := atom.Unmarshal(raw)
  rssChannel, err := rss.Unmarshal(raw)

and to use the central package, use (package).Standard:

  feed, err := atom.Standard(atomFeed, ...)
  rssChannel, err := rss.Standard(rssChannel, ...)

The required arguments between protocols may vary, but are generally aimed at
compatibilty with inputs that aren't following the spec. You can marshal to the
desired output format by doing the above in reverse:

  atomFeed := atom.Atom(feed)
  raw, err := atom.Marshal(atomFeed)

===== arbitrary data ===========================================================

non-spec attributes and elements will be stored as Attributes and Extensions.
On outbound data, attributes are name->string pairs and extensions are name->any
pairs. On inbound data, both are strings. Extensions are the innerxml of the
source surrounded by <extension> tags, and can be parsed using xml.Unmarshal
into the expected value.

this behavior isn't ideal, especially in the central package. I'm working to
improve handling of arbitrary data as I learn what works best.

===== support/interoperability =================================================

feeds supports:
  - Atom
  - RSS 2.0

the central package is provided to allow translation between protocols/formats,
but since every format has different information, lossless conversion isn't
always possible. I recommend using the package for your primary protocol and
using the central package to convert when necessary.

Documentation

Index

• Constants
• type Attribute
  • func NewAttribute(namespace, name string, value string) (out Attribute)
• type Attributes
  • func GetAttributes(attrs Attributes, namespace, name string) (out Attributes)
• type Category
• type Entry
  • func (e *Entry) Author() (author Person)
  • func (e *Entry) SelfLink() (link Link)
• type Extension
  • func NewExtension(namespace, name string, value any) (out Extension)
• type Extensions
  • func GetExtensions(exts Extensions, namespace, name string) (out Extensions)
• type Feed
• type FeedMeta
  • func (fm FeedMeta) Value() bool
• type Link
  • func GetLinksWithRel(ls []Link, rel LinkRelType) (out []Link)
• type LinkRelType
• type Person

Constants

const (
	// LinkRelAlternate links are to an alternative version of the same resource.
	LinkRelAlternate = LinkRelType("alternate")
	// LinkRelRelated links are to a related resource.
	LinkRelRelated = LinkRelType("related")
	// LinkRelSelf links are a self-referential link.
	LinkRelSelf = LinkRelType("self")
	// LinkRelAttachment links are to a large or special attachment.
	LinkRelAttachment = LinkRelType("attachment")
	// LinkRelSource links are links to the source of information in the resource.
	LinkRelSource = LinkRelType("source")
	// LinkRelOther links are any not included in the above.
	LinkRelOther = LinkRelType("other")
)

Types

type Attribute

type Attribute struct {
	Namespace string
	Name      string
	Value     string
}

func NewAttribute

func NewAttribute(namespace, name string, value string) (out Attribute)

type Attributes

type Attributes []Attribute

func GetAttributes

func GetAttributes(attrs Attributes, namespace, name string) (out Attributes)

type Category

type Category struct {
	Id   string
	Name string
}

Category is a category that a feed or entry belongs to. Id should be reasonably unique, and Name can be provided if the desired user-readable name should be different from the Id.

type Entry

type Entry struct {
	Attributes   Attributes
	UniqueID     string
	Language     string
	Title        string
	Subtitle     string
	Categories   []Category
	Updated      time.Time
	Published    time.Time
	Source       FeedMeta
	Id           string
	Links        []Link
	Authors      []Person
	Contributors []Person
	Extensions   Extensions
	Content      string
}

func (*Entry) Author

func (e *Entry) Author() (author Person)

func (*Entry) SelfLink

func (e *Entry) SelfLink() (link Link)

type Extension

type Extension struct {
	Namespace string
	Name      string
	Value     any
}

Extension defines a value that extends a feed. The expression of this depends on the protocol, but generally, they'll be elements not defined by the normal protocol separated by some namespace or object name.

func NewExtension

func NewExtension(namespace, name string, value any) (out Extension)

type Extensions

type Extensions []Extension

Extensions defines a set of values to tack on to a specific feed element.

func GetExtensions

func GetExtensions(exts Extensions, namespace, name string) (out Extensions)

Get gets the subset of Extensions where every Extension has namespace and name. If there is no namespace, ignores namespace and just matches the name.

type Feed

type Feed struct {
	Attributes Attributes
	FeedMeta
	Extensions Extensions
	Entries    []Entry
}

type FeedMeta

type FeedMeta struct {
	UniqueID   string
	Language   string
	Title      string
	Subtitle   string
	IconLink   Link
	LogoLink   Link
	Categories []Category
	Updated    time.Time
	Id         string
	Links      []Link
	Rights     string
}

func (FeedMeta) Value

func (fm FeedMeta) Value() bool

type Link

type Link struct {
	Href          string
	RelType       LinkRelType
	MediaType     string
	ContentLength int
	Language      string
}

Link represents a link to something in a feed. Usually, these are links to a specific resource related to the feed or entry, like self-links, alternative translations, etc. The constants defined for the LinkRel type represent defined Link.RelType for various formats and protocols, but every type isn't guaranteed to work for every format depending on where I am in development.

func GetLinksWithRel

func GetLinksWithRel(ls []Link, rel LinkRelType) (out []Link)

type LinkRelType

type LinkRelType string

type Person

type Person struct {
	Name       string
	Link       Link
	Email      string
	Extensions Extensions
}