first commit

README.md

@@ -0,0 +1,142 @@
+# RSS Library
+
+A Go library for parsing RSS, Atom, and JSON feeds with a unified interface.
+
+## Features
+
+- **Unified API**: Parse RSS, Atom, and JSON Feed formats using a single `Parse()` function
+- **Automatic Format Detection**: Automatically detects the feed format
+- **No External Dependencies**: Pure Go implementation
+- **Comprehensive Testing**: Full test coverage for all supported formats including real-world feeds
+
+## Supported Formats
+
+- **RSS 2.0**: Full support for RSS 2.0 specification
+- **Atom 1.0**: Complete Atom 1.0 parsing
+- **JSON Feed 1.1**: Support for JSON Feed version 1.1
+
+## Installation
+
+```bash
+go get git.quad4.io/Go-Libs/RSS
+```
+
+## Usage
+
+```go
+package main
+
+import (
+    "fmt"
+    "log"
+
+    "git.quad4.io/Go-Libs/RSS"
+)
+
+func main() {
+    // Parse any feed format (RSS, Atom, or JSON Feed)
+    feed, err := rss.Parse(feedData)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("Feed Title:", feed.Title)
+    fmt.Println("Feed Description:", feed.Description)
+
+    for _, item := range feed.Items {
+        fmt.Println("Item:", item.Title)
+        fmt.Println("Link:", item.Link)
+        fmt.Println("Published:", item.Published)
+    }
+}
+```
+
+## API Reference
+
+### Types
+
+#### Feed
+Represents a parsed feed with unified interface across all formats.
+
+```go
+type Feed struct {
+    Title       string     // Feed title
+    Description string     // Feed description
+    Link        string     // Link to feed's website
+    FeedURL     string     // URL of the feed itself
+    Language    string     // Feed language
+    Author      *Person    // Feed author
+    Published   *time.Time // Publication date
+    Updated     *time.Time // Last updated date
+    Items       []*Item    // Feed items
+}
+```
+
+#### Item
+Represents an individual item/entry in a feed.
+
+```go
+type Item struct {
+    Title       string       // Item title
+    Description string       // Item content/description
+    Link        string       // Link to item
+    GUID        string       // Unique identifier
+    Published   *time.Time   // Publication date
+    Updated     *time.Time   // Last updated date
+    Author      *Person      // Item author
+    Categories  []string     // Tags/categories
+    Enclosures  []*Enclosure // Attachments/media
+}
+```
+
+#### Person
+Represents a person (author, contributor).
+
+```go
+type Person struct {
+    Name  string // Person's name
+    Email string // Email address
+    URI   string // Website/profile URL
+}
+```
+
+#### Enclosure
+Represents an attachment or media file.
+
+```go
+type Enclosure struct {
+    URL    string // File URL
+    Length int64  // File size in bytes
+    Type   string // MIME type
+}
+```
+
+### Functions
+
+#### Parse(data []byte) (*Feed, error)
+Parses feed data and returns a unified Feed structure. Automatically detects the format (RSS, Atom, or JSON Feed).
+
+## Examples
+
+See the `examples/` directory for complete usage examples demonstrating parsing of RSS, Atom, and JSON feeds.
+
+## Running Tests
+
+```bash
+go test
+```
+
+## Running Examples
+
+The example demonstrates fetching and parsing real RSS feeds from popular websites:
+
+```bash
+cd examples
+go run example.go
+```
+
+This will fetch live feeds from Hacker News, Ars Technica, and The Verge, showing how the unified API works with real-world data.
+
+## License
+
+MIT License - see LICENSE file for details.