diff --git a/README.md b/README.md index 02b067a..56d4711 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,8 @@ 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. @@ -22,37 +24,37 @@ constructs' adherence to RFC4287. package main import ( - "fmt" - "log" + "fmt" + "log" - "git.streifling.com/jason/atom" + "git.streifling.com/jason/atom" ) func main() { - feed := atom.NewFeed("Example Feed") - if err := feed.Check(); err != nil { - log.Fatalln(err) - } + 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) + 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) + 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) + feedString, err := feed.ToXML("UTF-8") + if err != nil { + log.Fatalln(err) + } + fmt.Println(feedString) } ``` @@ -63,70 +65,177 @@ provide. package main import ( - "fmt" - "log" - "time" + "fmt" + "log" + "time" - "git.streifling.com/jason/atom" + "git.streifling.com/jason/atom" + "github.com/google/uuid" ) func main() { - now := time.Now() + 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.", - }, - }, - }, - } + 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) + 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 - + - - John Doe - john.doe@example.com - - urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6 - Example Feed - 2024-10-18T05:49:08+02:00 - - This is the content of the first entry. - urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a - First Entry - 2006-01-02T15:04:05+07:00 - + + John Doe + john.doe@example.com + + urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6 + Example Feed + 2024-10-18T05:49:08+02:00 + + This is the content of the first entry. + urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a + First Entry + 2006-01-02T15:04:05+07:00 + + +``` + +### 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 + + + urn:uuid:ae89d343-b535-447d-ac14-4b80d3e02a2f + Example Feed + 2024-10-20T14:57:02+02:00 + + Entry Two + urn:uuid:620c6f73-ee1d-4c1e-be98-b0b1ad7a053f + Two + 2024-10-20T14:57:02+02:00 + ``` diff --git a/atom.go b/atom.go index 92db796..8158efb 100644 --- a/atom.go +++ b/atom.go @@ -21,8 +21,8 @@ func addToSlice[C Countable](slice *[]C, countable C) int { if *slice == nil { *slice = make([]C, 0) } - *slice = append(*slice, countable) + *slice = append(*slice, countable) return len(*slice) - 1 }