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:

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

## Usage

This library provides convenient functions to safely create and extend 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"
)

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