rss2

README

You can find documentation and examples at GoDoc (click the badge above).

Documentation

Overview

Package rss2 let's you parse, modify, create and render RSS 2.0 feeds. Specification was taken from https://cyber.harvard.edu/rss/rss.html .

Example (ParseRSS)

This example shows how you can parse a simple RSS 2.0 feed. The user must ensure that the input is UTF-8 encoded when parsing.

package main

import (
	"encoding/xml"
	"fmt"

	"github.com/codesoap/rss2"
)

func main() {
	input := `
		<?xml version="1.0" encoding="UTF-8"?>
		<rss version="2.0">
		    <channel>
		        <title>Channel title</title>
		        <link>channel.link.net</link>
		        <description>Channel description</description>
		        <category>Channel&#39;s category</category>
		        <item>
		            <title>Title of my RSS item</title>
		            <pubDate>03 Jun 2019 09:39:21 GMT</pubDate>
		        </item>
		    </channel>
		</rss>`
	var parse rss2.RSS
	// Remember to handle any error xml.Unmarshal() gives in your code.
	xml.Unmarshal([]byte(input), &parse)
	fmt.Println(`RSS Version:        `, parse.Version)
	fmt.Println(`RSS channel's title:`, parse.Channel.Title)
	fmt.Println(`RSS item's title:   `, parse.Channel.Items[0].Title)
	// The date of any date fields is hidden behind .Time for technical reasons.
	fmt.Println(`RSS item's pubDate: `, parse.Channel.Items[0].PubDate.Time)
}

Example (RenderRSS)

This example shows how you can create a simple RSS 2.0 feed. Using the New<element>() functions to create RSS elements helps to avoid invalid RSS.

package main

import (
	"encoding/xml"
	"fmt"
	"time"

	"github.com/codesoap/rss2"
)

func main() {
	item, _ := rss2.NewItem(`Title of my RSS item`, ``)
	item.PubDate = &rss2.RSSTime{time.Date(2019, 6, 3, 9, 39, 21, 0, time.UTC)}

	category, _ := rss2.NewCategory(`MSFT`)
	category.Domain = `http://www.fool.com/cusips`

	channel, _ := rss2.NewChannel(`Channel title`, `channel.link.net`,
		`Channel description`)
	channel.Categories = []*rss2.Category{category}
	channel.Items = []*rss2.Item{item}

	// All created RSS elements are structs with XML tags.
	// Thus xml.Marshal() and the likes can be used.
	rss, _ := xml.MarshalIndent(rss2.NewRSS(channel), ``, `    `)
	fmt.Println(xml.Header + string(rss))
}

Index

• type Category
  • func NewCategory(value string) (*Category, error)
• type Channel
  • func NewChannel(title, link, description string) (*Channel, error)
• type Cloud
  • func NewCloud(domain string, port int, path, rp, protocol string) (*Cloud, error)
• type Enclosure
  • func NewEnclosure(url string, length int, t string) (*Enclosure, error)
• type GUID
  • func NewGUID(value string) (*GUID, error)
• type Image
  • func NewImage(url, title, link string) (*Image, error)
• type Item
  • func NewItem(title, description string) (*Item, error)
• type RSS
  • func NewRSS(ch *Channel) *RSS
• type RSSTime
  • func ParseRSSTime(in string) (out RSSTime, err error)
  • func (t RSSTime) MarshalXML(e *xml.Encoder, start xml.StartElement) error
  • func (t *RSSTime) UnmarshalXML(decoder *xml.Decoder, start xml.StartElement) (err error)
• type SkipDays
  • func NewSkipDays(days []time.Weekday) *SkipDays
• type SkipHours
  • func NewSkipHours(hours []int) (*SkipHours, error)
• type Source
  • func NewSource(value, url string) (*Source, error)
• type TextInput
  • func NewTextInput(title, description, name, link string) (*TextInput, error)

Examples

• Package (ParseRSS)
• Package (RenderRSS)

Types

type Category

type Category struct {
	XMLName xml.Name `xml:"category"`
	Value   string   `xml:",chardata"`
	Domain  string   `xml:"domain,attr,omitempty"`
}

Category represents a Channel's or Item's category. Domain is optional.

func NewCategory

func NewCategory(value string) (*Category, error)

NewCategory creates a new Category.

type Channel

type Channel struct {
	XMLName        xml.Name    `xml:"channel"`
	Title          string      `xml:"title"`
	Link           string      `xml:"link"`
	Description    string      `xml:"description"`
	Language       string      `xml:"language,omitempty"`
	Copyright      string      `xml:"copyright,omitempty"`
	ManagingEditor string      `xml:"managingEditor,omitempty"`
	WebMaster      string      `xml:"webMaster,omitempty"`
	PubDate        *RSSTime    `xml:"pubDate,omitempty"`
	LastBuildDate  *RSSTime    `xml:"lastBuildDate,omitempty"`
	Categories     []*Category `xml:"category,omitempty"`
	Generator      string      `xml:"generator,omitempty"`
	Docs           string      `xml:"docs,omitempty"`
	Cloud          *Cloud      `xml:"cloud,omitempty"`
	TTL            int         `xml:"ttl,omitempty"`
	Image          *Image      `xml:"image,omitempty"`
	Rating         string      `xml:"rating,omitempty"`
	TextInput      *TextInput  `xml:"textInput,omitempty"`
	SkipHours      *SkipHours  `xml:"skipHours,omitempty"`
	SkipDays       *SkipDays   `xml:"skipDays,omitempty"`
	Items          []*Item     `xml:"item,omitempty"`
}

Channel represents an rss channel element. Title, Link and Description are required.

func NewChannel

func NewChannel(title, link, description string) (*Channel, error)

NewChannel creates a new Channel.

type Cloud

type Cloud struct {
	XMLName           xml.Name `xml:"cloud"`
	Domain            string   `xml:"domain,attr"`
	Port              int      `xml:"port,attr"`
	Path              string   `xml:"path,attr"`
	RegisterProcedure string   `xml:"registerProcedure,attr"`
	Protocol          string   `xml:"protocol,attr"`
}

Cloud represents a Channel's cloud element. All attributes must be present.

func NewCloud

func NewCloud(domain string, port int, path, rp, protocol string) (*Cloud, error)

NewCloud creates a new Cloud element.

type Enclosure

type Enclosure struct {
	XMLName xml.Name `xml:"enclosure"`
	URL     string   `xml:"url,attr"`
	Length  int      `xml:"length,attr"`
	Type    string   `xml:"type,attr"`
}

Enclosure represents an Item's enclosure element. All attributes must be present. Type must be a MIME type.

func NewEnclosure

func NewEnclosure(url string, length int, t string) (*Enclosure, error)

NewEnclosure creates a new Enclosure element.

type GUID

type GUID struct {
	XMLName     xml.Name `xml:"guid"`
	Value       string   `xml:",chardata"`
	IsPermaLink bool     `xml:"isPermaLink,attr"`
}

GUID represents a Channel's guid element. sPermaLink is optional.

func NewGUID

func NewGUID(value string) (*GUID, error)

NewGUID creates a new GUID element.

type Image

type Image struct {
	XMLName     xml.Name `xml:"image"`
	URL         string   `xml:"url"`
	Title       string   `xml:"title"`
	Link        string   `xml:"link"`
	Width       int      `xml:"width,omitempty"`
	Height      int      `xml:"height,omitempty"`
	Description string   `xml:"description,omitempty"`
}

Image represents a Channel's image. URL, Title and Link must be present. Width must not exceed 144. Height must not exceed 400.

func NewImage

func NewImage(url, title, link string) (*Image, error)

NewImage creates new Image.

type Item

type Item struct {
	XMLName     xml.Name    `xml:"item"`
	Title       string      `xml:"title,omitempty"`
	Link        string      `xml:"link,omitempty"`
	Description string      `xml:"description,omitempty"`
	Author      string      `xml:"author,omitempty"`
	Categories  []*Category `xml:"category,omitempty"`
	Comments    string      `xml:"comments,omitempty"`
	Enclosure   *Enclosure  `xml:"enclosure,omitempty"`
	GUID        *GUID       `xml:"guid,omitempty"`
	PubDate     *RSSTime    `xml:"pubDate,omitempty"`
	Source      *Source     `xml:"source,omitempty"`
}

Item represents an rss item. At least Title or Description must be present.

func NewItem

func NewItem(title, description string) (*Item, error)

NewItem creates a new Item. Either title or description may be empty.

type RSS

type RSS struct {
	XMLName xml.Name `xml:"rss"`
	Version string   `xml:"version,attr"`
	Channel *Channel `xml:"channel"`
}

RSS represents an rss feed. All fields are mandatory. Version must be "2.0" for this library.

func NewRSS

func NewRSS(ch *Channel) *RSS

NewRSS creates a new RSS element.

type RSSTime

type RSSTime struct {
	Time time.Time
}

RSSTime is a wrapper around time.Time, that makes it possible to define custom MarshalXML() and UnmarshalXML() functions.

func ParseRSSTime

func ParseRSSTime(in string) (out RSSTime, err error)

ParseRSSTime parses a time as specified in RFC822, with the difference, that four digit years are allowed.

func (RSSTime) MarshalXML

func (t RSSTime) MarshalXML(e *xml.Encoder, start xml.StartElement) error

MarshalXML marshals an RSSTime element.

func (*RSSTime) UnmarshalXML

func (t *RSSTime) UnmarshalXML(decoder *xml.Decoder,
	start xml.StartElement) (err error)

UnmarshalXML unmarshals an RSSTime element.

type SkipDays

type SkipDays struct {
	XMLName xml.Name `xml:"skipDays"`
	Days    []string `xml:"day"`
}

SkipDays represents a Channel's skipDays element.

func NewSkipDays

func NewSkipDays(days []time.Weekday) *SkipDays

NewSkipDays creates a new SkipDays element.

type SkipHours

type SkipHours struct {
	XMLName xml.Name `xml:"skipHours"`
	Hours   []int    `xml:"hour"`
}

SkipHours represents a Channel's skipHours element. Hours must be between 0 and 23.

func NewSkipHours

func NewSkipHours(hours []int) (*SkipHours, error)

NewSkipHours creates a new SkipHours element. Hours must be between 0 and 23.

type Source

type Source struct {
	XMLName xml.Name `xml:"source"`
	Value   string   `xml:",chardata"`
	URL     string   `xml:"url,attr"`
}

Source represents an Item's source element. URL must be present.

func NewSource

func NewSource(value, url string) (*Source, error)

NewSource creates a new Source element.

type TextInput

type TextInput struct {
	XMLName     xml.Name `xml:"textInput"`
	Title       string   `xml:"title"`
	Description string   `xml:"description"`
	Name        string   `xml:"name"`
	Link        string   `xml:"link"`
}

TextInput represents a Channel's textInput element. All sub-elements must be present.

func NewTextInput

func NewTextInput(title, description, name, link string) (*TextInput, error)

NewTextInput creates a new TextInput element.