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 and extension of elements.

## Installation

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

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

## Usage

This library provides easy to use functions to create and extend elements of an
Atom feed. The intended way of using it entails using these functions.

```
package main

import (
 "fmt"
 "log"

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

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

 author := atom.NewPerson("John Doe")
 author.Email = "john.doe@example.com"
 feed.AddAuthor(author)

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

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

 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 would provide. This, of course, making it easier to make mistakes.

```
package main

import (
 "fmt"
 "log"
 "time"

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

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

 feed := &atom.Feed{
  Title: &atom.PlainText{
   Type: "text",
   Text: "Example Feed",
  },
  ID:      &atom.ID{URI: "urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6"},
  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: "urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a"},
    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 being 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>
```