Added a proper README

2024-10-18 06:04:05 +02:00 · 2024-10-18 06:04:05 +02:00 · e075175fc7
commit e075175fc7
parent b7e2927292
1 changed files with 134 additions and 1 deletions
--- a/README.md
+++ b/README.md
@ -1,3 +1,136 @@
 # atom

-An extensible implementation of an Atom feed that aims to be very close to RFC4287.
+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.
+
+```
+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>
+```