syndfeed

README

Overview

syndfeed is a Go library for RSS 2.0 and Atom 1.0 feeds, supported implement extension module to parse any RSS and Atom extension element.

Dependencies

• xmlquery

Getting Started

Parse a feed from URL

feed, _ := syndfeed.LoadURL("https://cn.engadget.com/rss.xml")
fmt.Println(feed.Title)

Parse a feed from io.Reade

feedData := `<rss version="2.0">
<channel>
<title>Sample Feed</title>
</channel>
</rss>`
feed, _ := syndfeed.Parse(strings.NewReader(feedData))
fmt.Println(feed.Title)

Parse an Atom feed into syndfeed.Feed

feedData := `<feed xmlns="http://www.w3.org/2005/Atom">
<title>Example Atom</title>
</feed>`
feed, _ := syndfeed.ParseAtom(strings.NewReader(feedData))
fmt.Println(feed.Title)

Parse a RSS feed into syndfeed.Feed

feedData := `<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/">
<channel>
<dc:creator>example@site.com (Example Name)</dc:creator>
</channel>`
feed, _ := syndfeed.ParseRSS(strings.NewReader(feedData))
fmt.Println(feed.Authors[0].Name)

Extension Modules

In some syndication feeds, they have some valid XML elements but are not specified in either the Atom 1.0 or RSS 2.0 specifications. You can add extension module to process these elements.

The syndfeed build-in supported following modules: Dublin Core, Content, Syndication.

You can implement your own modules to parse any extension element like: iTunes RSS, Media RSS.

iTunes Module

iTunesHandler := func(n *xmlquery.Node, v interface{}) {
    item := v.(*syndfeed.Item)
    switch n.Data {
    case "artist":
        item.Authors = append(item.Authors, &syndfeed.Person{Name: n.InnerText()})
    case "releaseDate":
		item.PublishDate = ParseDate(n.InnerText())
    }
}
// Register a new module to the syndfeed module list.
syndfeed.RegisterExtensionModule("https://rss.itunes.apple.com", syndfeed.ModuleHandlerFunc(iTunesHandler))
// Now can parse iTunes feed. 
feed, err := syndfeed.LoadURL("https://github.com/zhengchun/syndfeed/blob/master/_samples/itunes.atom")
fmt.Println(feed.Items[0].Authors[0].Name)
// Output author name.

TODO

• Add RSS/Atom format output.

Please let me know if you have any questions.

Documentation

Index

• func RegisterExtensionModule(nsURL string, m Module)
• type Atom
  • func (a *Atom) Parse(r io.Reader) (*Feed, error)
• type ElementExtension
• type Feed
  • func LoadURL(url string) (*Feed, error)
  • func Parse(r io.Reader) (*Feed, error)
  • func ParseAtom(r io.Reader) (*Feed, error)
  • func ParseRSS(r io.Reader) (*Feed, error)
• type Item
• type Link
• type Module
• type ModuleHandlerFunc
  • func (f ModuleHandlerFunc) ParseElement(n *xmlquery.Node, v interface{})
• type Person
• type RSS
  • func (s *RSS) Parse(r io.Reader) (*Feed, error)

Examples

• Atom
• Parse
• RSS

Functions

func RegisterExtensionModule

func RegisterExtensionModule(nsURL string, m Module)

RegisterExtensionModule registers Module with the specified XML namespace.

Types

type Atom

type Atom struct{}

Atom is an Atom feed parser. https://validator.w3.org/feed/docs/rfc4287.html

Example

The following example is parse an Atom feed.

f, err := os.Open("./a.atom")
if err != nil {
	panic(err)
}
feed, err := ParseAtom(f)
if err != nil {
	panic(err)
}
fmt.Println(feed.Title)
fmt.Println(feed.Version)

func (*Atom) Parse

func (a *Atom) Parse(r io.Reader) (*Feed, error)

Parse parses an atom feed.

type ElementExtension

type ElementExtension struct {
	Name, Namespace, Value string
}

ElementExtension is an syndication element extension.

type Feed

type Feed struct {
	Authors      []*Person
	BaseURL      string
	Categories   []string
	Contributors []*Person
	Copyright    string
	Namespace    map[string]string // map[namespace-prefix]namespace-url
	Description  string
	Generator    string
	Id           string
	ImageURL     string
	Items        []*Item
	Language     string
	// LastUpdatedTime is the feed was last updated time.
	LastUpdatedTime   time.Time
	Title             string
	Links             []*Link
	Version           string
	ElementExtensions []*ElementExtension
}

Feed is top-level feed object, <feed> in Atom 1.0 and <rss> in RSS 2.0.

func LoadURL

func LoadURL(url string) (*Feed, error)

LoadURL loads a syndication feed URL.

func Parse

func Parse(r io.Reader) (*Feed, error)

Parse parses a syndication feed(RSS,Atom).

Example

s := `<?xml version="1.0" encoding="UTF-8" ?>
	<rss version="2.0">
	<channel>
	 <title>RSS Title</title>
	 <description>This is an example of an RSS feed</description>
	 <link>http://www.example.com/main.html</link>
	 <lastBuildDate>Mon, 06 Sep 2010 00:01:00 +0000 </lastBuildDate>
	 <pubDate>Sun, 06 Sep 2009 16:20:00 +0000</pubDate>
	 <ttl>1800</ttl>	
	 <item>
	  <title>Example entry</title>
	  <description>Here is some text containing an interesting description.</description>
	  <link>http://www.example.com/blog/post/1</link>
	  <guid isPermaLink="false">7bd204c6-1655-4c27-aeee-53f933c5395f</guid>
	  <pubDate>Sun, 06 Sep 2009 16:20:00 +0000</pubDate>
	 </item>	
	</channel>
	</rss>`
feed, err := Parse(strings.NewReader(s))
if err != nil {
	panic(err)
}
fmt.Println(feed.Title)
fmt.Println(feed.Version)
fmt.Println(len(feed.Items))

func ParseAtom

func ParseAtom(r io.Reader) (*Feed, error)

ParseAtom parses Atom feed from the specified io.Reader r.

func ParseRSS

func ParseRSS(r io.Reader) (*Feed, error)

ParseRSS parses RSS feed from the specified io.Reader r.

type Item

type Item struct {
	BaseURL      string
	Authors      []*Person
	Contributors []*Person
	Categories   []string
	Content      string
	Copyright    string
	Id           string
	// LastUpdatedTime is the feed item last updated time.
	LastUpdatedTime time.Time
	Links           []*Link
	// PublishDate is the feed item publish date.
	PublishDate       time.Time
	Summary           string
	Title             string
	ElementExtensions []*ElementExtension
}

Item is a feed item.

type Link

type Link struct {
	MediaType string
	URL       string
	Title     string
	RelType   string
}

Link represents a link within a syndication feed or item.

type Module

type Module interface {
	ParseElement(n *xmlquery.Node, v interface{})
}

Module is an interface is used to handle an extension element which not specified in either the Atom 1.0 or RSS 2.0 specifications.

type ModuleHandlerFunc

type ModuleHandlerFunc func(*xmlquery.Node, interface{})

ModuleHandlerFunc is a utility function that wrapper a function as Module object.

func (ModuleHandlerFunc) ParseElement

func (f ModuleHandlerFunc) ParseElement(n *xmlquery.Node, v interface{})

type Person

type Person struct {
	Name  string
	URL   string
	Email string
}

Person is an author or contributor of the feed content.

type RSS

type RSS struct{}

RSS is an RSS feed parser. https://validator.w3.org/feed/docs/rss2.html

Example

The following example is parse an RSS feed.

f, err := os.Open("./a.rss")
if err != nil {
	panic(err)
}
feed, err := ParseRSS(f)
if err != nil {
	panic(err)
}
fmt.Println(feed.Title)
fmt.Println(feed.Version)

func (*RSS) Parse

func (s *RSS) Parse(r io.Reader) (*Feed, error)

Parse parses an Rss feed.