atom/README.md

# 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:

```sh
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.

```go
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.

```go
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
<?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.

```go
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.

```go
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
<?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>
```