atom

An extensible Atom feed generator library that aims to be very close to RFC4287. It diligently checks for compliance with the standard and provides functions for easy creation, extension and deletion of elements.

Installation

To install the latest version of the module, use the following command:

go get git.streifling.com/jason/atom@latest

Usage

Basic Feed

This library provides convenient functions to safely create, extend and delete elements and attributes of Atom feeds. It also provides checks for all constructs' adherence to RFC4287.

package main

import (
    "fmt"
    "log"

    "git.streifling.com/jason/atom"
)

func main() {
    feed := atom.NewFeed("Example Feed")
    if err := feed.Check(); err != nil {
        log.Fatalln(err)
    }

    author := atom.NewPerson("John Doe")
    author.Email = "john.doe@example.com"
    if err := author.Check(); err != nil {
        log.Fatalln(err)
    }
    feed.AddAuthor(author)

    entry := atom.NewEntry("First Entry")
    entry.Content = atom.NewContent(atom.InlineText, "text", "This is the content of the first entry.")
    if err := entry.Check(); err != nil {
        log.Fatalln(err)
    }
    feed.AddEntry(entry)

    feedString, err := feed.ToXML("UTF-8")
    if err != nil {
        log.Fatalln(err)
    }
    fmt.Println(feedString)
}

It is also possible to use this library in a way similar to what other libraries provide.

package main

import (
    "fmt"
    "log"
    "time"

    "git.streifling.com/jason/atom"
    "github.com/google/uuid"
)

func main() {
    now := time.Now()

    feed := &atom.Feed{
        Title: &atom.PlainText{
            Type: "text",
            Text: "Example Feed",
        },
        ID:      &atom.ID{URI: fmt.Sprint("urn:uuid:", uuid.New())},
        Updated: &atom.Date{DateTime: atom.DateTime(now)},
        Authors: []*atom.Person{
            {
                Name:  "John Doe",
                Email: "john.doe@example.com",
            },
        },
        Entries: []*atom.Entry{
            {
                Title: &atom.PlainText{
                    Type: "text",
                    Text: "First Entry",
                },
                ID:      &atom.ID{URI: fmt.Sprint("urn:uuid:", uuid.New())},
                Updated: &atom.Date{DateTime: atom.DateTime(now)},
                Content: &atom.InlineTextContent{
                    Type: "text",
                    Text: "This is the content of the first entry.",
                },
            },
        },
    }

    feedString, err := feed.ToXML("UTF-8")
    if err != nil {
        log.Fatalln(err)
    }
    fmt.Println(feedString)
}

The output of both ways of using it is an RFC4287 compliant Atom feed.

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
    <author>
        <name>John Doe</name>
        <email>john.doe@example.com</email>
    </author>
    <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
    <title type="text">Example Feed</title>
    <updated>2024-10-18T05:49:08+02:00</updated>
    <entry>
        <content type="text">This is the content of the first entry.</content>
        <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
        <title type="text">First Entry</title>
        <updated>2006-01-02T15:04:05+07:00</updated>
    </entry>
</feed>

Compliance and Error Checking

All Atom constructs have their own construct.Check() method. It checks for compliance with RFC4287 and errors. This allows one to be certain that only compliant constructs are added to their respective parent construct. It also means that not the entire feed has to be checked every time a new construct is added. Instead one only checks the current construct and all of its sub-constructs with a single construct.Check() call.

package main

import (
    "fmt"
    "log"

    "git.streifling.com/jason/atom"
)

func main() {
    feed := atom.NewFeed("Example Feed")
    if err := feed.Check(); err != nil {
        log.Fatalln(err)
    }

    entry := atom.NewEntry("One")
    entry.Content = atom.NewContent(atom.InlineText, "text", "Entry One")
    entry.AddAuthor(atom.NewPerson("John Doe"))
    if err := entry.Check(); err != nil {
        log.Fatalln(err)
    }
    feed.AddEntry(entry)

    feedString, err := feed.ToXML("UTF-8")
    if err != nil {
        log.Fatalln(err)
    }
    fmt.Println(feedString)
}

Adding and Deleting Items

To add elements to any slice one calls the appropriate someone.AddSomething(toBeAdded) method. It returns the item's index number. To delete the item one calls the Delete method.

package main

import (
    "fmt"
    "log"

    "git.streifling.com/jason/atom"
)

func main() {
    feed := atom.NewFeed("Feed")
    if err := feed.Check(); err != nil {
        log.Fatalln(err)
    }

    e1 := atom.NewEntry("One")
    e1.Content = atom.NewContent(atom.InlineText, "text", "Entry One")
    if err := e1.Check(); err != nil {
        log.Fatalln(err)
    }
    i1 := feed.AddEntry(e1)

    e2 := atom.NewEntry("Two")
    e2.Content = atom.NewContent(atom.InlineText, "text", "Entry Two")
    if err := e2.Check(); err != nil {
        log.Fatalln(err)
    }
    feed.AddEntry(e2)

    if err := feed.DeleteEntry(i1); err != nil {
        log.Fatalln(err)
    }

    feedString, err := feed.ToXML("UTF-8")
    if err != nil {
        log.Fatalln(err)
    }
    fmt.Println(feedString)
}

The output of this example looks like this. It only shows the second entry.

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
    <id>urn:uuid:ae89d343-b535-447d-ac14-4b80d3e02a2f</id>
    <title type="text">Example Feed</title>
    <updated>2024-10-20T14:57:02+02:00</updated>
    <entry>
        <content type="text">Entry Two</content>
        <id>urn:uuid:620c6f73-ee1d-4c1e-be98-b0b1ad7a053f</id>
        <title type="text">Two</title>
        <updated>2024-10-20T14:57:02+02:00</updated>
    </entry>
</feed>