jason/atom
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 14 Wiki Activity

Touched up README

Browse Source
This commit is contained in:
Jason Streifling 2024-10-20 15:10:58 +02:00
parent ae24db0c08
commit cf131f0bcf
2 changed files with 186 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

261
README.md
View File

@ -14,6 +14,8 @@ go get git.streifling.com/jason/atom@latest
## Usage ## Usage
### Basic Feed
This library provides convenient functions to safely create, extend and delete This library provides convenient functions to safely create, extend and delete
elements and attributes of Atom feeds. It also provides checks for all elements and attributes of Atom feeds. It also provides checks for all
constructs' adherence to RFC4287. constructs' adherence to RFC4287.
@ -22,37 +24,37 @@ constructs' adherence to RFC4287.
package main package main
import ( import (
"fmt" "fmt"
"log" "log"
"git.streifling.com/jason/atom" "git.streifling.com/jason/atom"
) )
func main() { func main() {
feed := atom.NewFeed("Example Feed") feed := atom.NewFeed("Example Feed")
if err := feed.Check(); err != nil { if err := feed.Check(); err != nil {
log.Fatalln(err) log.Fatalln(err)
} }
author := atom.NewPerson("John Doe") author := atom.NewPerson("John Doe")
author.Email = "john.doe@example.com" author.Email = "john.doe@example.com"
if err := author.Check(); err != nil { if err := author.Check(); err != nil {
log.Fatalln(err) log.Fatalln(err)
} }
feed.AddAuthor(author) feed.AddAuthor(author)
entry := atom.NewEntry("First Entry") entry := atom.NewEntry("First Entry")
entry.Content = atom.NewContent(atom.InlineText, "text", "This is the content of the first entry.") entry.Content = atom.NewContent(atom.InlineText, "text", "This is the content of the first entry.")
if err := entry.Check(); err != nil { if err := entry.Check(); err != nil {
log.Fatalln(err) log.Fatalln(err)
} }
feed.AddEntry(entry) feed.AddEntry(entry)
feedString, err := feed.ToXML("utf-8") feedString, err := feed.ToXML("UTF-8")
if err != nil { if err != nil {
log.Fatalln(err) log.Fatalln(err)
} }
fmt.Println(feedString) fmt.Println(feedString)
} }
``` ```
@ -63,70 +65,177 @@ provide.
package main package main
import ( import (
"fmt" "fmt"
"log" "log"
"time" "time"
"git.streifling.com/jason/atom" "git.streifling.com/jason/atom"
"github.com/google/uuid"
) )
func main() { func main() {
now := time.Now() now := time.Now()
feed := &atom.Feed{ feed := &atom.Feed{
Title: &atom.PlainText{ Title: &atom.PlainText{
Type: "text", Type: "text",
Text: "Example Feed", Text: "Example Feed",
}, },
ID: &atom.ID{URI: "urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6"}, ID: &atom.ID{URI: fmt.Sprint("urn:uuid:", uuid.New())},
Updated: &atom.Date{DateTime: atom.DateTime(now)}, Updated: &atom.Date{DateTime: atom.DateTime(now)},
Authors: []*atom.Person{ Authors: []*atom.Person{
{ {
Name: "John Doe", Name: "John Doe",
Email: "john.doe@example.com", Email: "john.doe@example.com",
}, },
}, },
Entries: []*atom.Entry{ Entries: []*atom.Entry{
{ {
Title: &atom.PlainText{ Title: &atom.PlainText{
Type: "text", Type: "text",
Text: "First Entry", Text: "First Entry",
}, },
ID: &atom.ID{URI: "urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a"}, ID: &atom.ID{URI: fmt.Sprint("urn:uuid:", uuid.New())},
Updated: &atom.Date{DateTime: atom.DateTime(now)}, Updated: &atom.Date{DateTime: atom.DateTime(now)},
Content: &atom.InlineTextContent{ Content: &atom.InlineTextContent{
Type: "text", Type: "text",
Text: "This is the content of the first entry.", Text: "This is the content of the first entry.",
}, },
}, },
}, },
} }
feedString, err := feed.ToXML("utf-8") feedString, err := feed.ToXML("UTF-8")
if err != nil { if err != nil {
log.Fatalln(err) log.Fatalln(err)
} }
fmt.Println(feedString) fmt.Println(feedString)
} }
``` ```
The output of both ways of using it is an RFC4287 compliant Atom feed. The output of both ways of using it is an RFC4287 compliant Atom feed.
```xml ```xml
<?xml version="1.0" encoding="utf-8"?> <?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"> <feed xmlns="http://www.w3.org/2005/Atom">
<author> <author>
<name>John Doe</name> <name>John Doe</name>
<email>john.doe@example.com</email> <email>john.doe@example.com</email>
</author> </author>
<id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id> <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
<title type="text">Example Feed</title> <title type="text">Example Feed</title>
<updated>2024-10-18T05:49:08+02:00</updated> <updated>2024-10-18T05:49:08+02:00</updated>
<entry> <entry>
<content type="text">This is the content of the first entry.</content> <content type="text">This is the content of the first entry.</content>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<title type="text">First Entry</title> <title type="text">First Entry</title>
<updated>2006-01-02T15:04:05+07:00</updated> <updated>2006-01-02T15:04:05+07:00</updated>
</entry> </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> </feed>
``` ```

2
atom.go
View File

@ -21,8 +21,8 @@ func addToSlice[C Countable](slice *[]C, countable C) int {
if *slice == nil { if *slice == nil {
*slice = make([]C, 0) *slice = make([]C, 0)
} }
*slice = append(*slice, countable)
*slice = append(*slice, countable)
return len(*slice) - 1 return len(*slice) - 1
} }