Crate rss_gen

source
Expand description

RSS Gen logo

§RSS Gen

A comprehensive Rust library for generating, parsing, serializing, and deserializing RSS feeds across various RSS versions.

Made With Love Crates.io lib.rs Docs.rs License Build Status

• Website • Documentation • Report Bug • Request Feature • Contributing Guidelines

§Overview

rss-gen is a powerful Rust library designed for working with RSS feeds. It provides functionality for generating, parsing, serializing, and deserializing RSS content across multiple RSS versions. It supports the following RSS versions: RSS 0.90, RSS 0.91, RSS 0.92, RSS 1.0, and RSS 2.0. The library offers a flexible and efficient way to handle RSS feeds in your Rust projects.

§Features

  • Support for RSS versions 0.90, 0.91, 0.92, 1.0, and 2.0
  • Generation of RSS feeds from structured data
  • Parsing of existing RSS feeds into structured data
  • Serialization and deserialization of RSS data
  • Extensible elements for managing standard and optional RSS fields
  • Atom link support for modern syndication compatibility
  • Image embedding for RSS feeds
  • Comprehensive error handling and validation
  • Performance-optimized XML processing using quick-xml
  • Convenient macros for RSS generation and data manipulation

§Installation

Add this to your Cargo.toml:

[dependencies]
rss-gen = "0.0.3"

§Usage

Here’s a basic example of how to use the rss-gen library to generate an RSS feed:

use rss_gen::{RssData, RssVersion, generate_rss};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let rss_data = RssData::new(Some(RssVersion::RSS2_0))
        .title("My Rust Blog")
        .link("https://myrustblog.com")
        .description("A blog about Rust programming and tutorials.");

    match generate_rss(&rss_data) {
        Ok(rss_feed) => println!("Generated RSS feed:\n{}", rss_feed),
        Err(e) => eprintln!("Error generating RSS feed: {}", e),
    }

    Ok(())
}

For parsing an existing RSS feed:

use rss_gen::parse_rss;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let rss_content = r#"
        <?xml version="1.0" encoding="UTF-8"?>
        <rss version="2.0">
            <channel>
                <title>My Rust Blog</title>
                <link>https://myrustblog.com</link>
                <description>A blog about Rust programming and tutorials.</description>
            </channel>
        </rss>
    "#;

    match parse_rss(rss_content, None) {
        Ok(parsed_data) => println!("Parsed RSS data: {:?}", parsed_data),
        Err(e) => eprintln!("Error parsing RSS feed: {}", e),
    }

    Ok(())
}

§Macros

RSS Gen provides a set of convenient macros to simplify RSS feed generation and data manipulation tasks:

  • macro_generate_rss!: Generates a complete RSS feed in XML format from a given RssData struct.
  • macro_write_element!: Writes an individual XML element with a given name and content.
  • macro_set_rss_data_fields!: Sets multiple fields of an RssData struct in one go.
  • macro_get_args!: Retrieves a named argument from a clap::ArgMatches object, useful for command-line interfaces.
  • macro_metadata_option!: Extracts an option value from metadata, typically used with HashMap<String, String>.

Refer to the documentation for more details on how to use these macros.

§Documentation

For full API documentation, please visit docs.rs/rss-gen.

§Examples

The library comes with several examples demonstrating various features:

  • example_data.rs: Shows how to create and manipulate RSS data structures.
  • example_error.rs: Demonstrates error handling in RSS Gen.
  • example_generator.rs: Illustrates RSS feed generation for different RSS versions.
  • example_lib.rs: Provides general usage examples of the library.
  • example_macros.rs: Shows how to use the provided macros.
  • example_parser.rs: Demonstrates parsing RSS feeds from XML content.
  • example_validator.rs: Illustrates the usage of the RSS feed validator.

To run an example, use the following command:

cargo run --example example_name

Replace example_name with the name of the example you want to run (e.g., example_generator).

§Benchmarks

The library includes benchmarks to measure performance. You can run them using:

cargo bench

§Supported RSS Versions

  • RSS 0.90
  • RSS 0.91
  • RSS 0.92
  • RSS 1.0
  • RSS 2.0

§Rust Version Compatibility

Compiler support: requires rustc 1.56.0+

§Examples

To run the examples, clone the repository and use the following command:

cargo run --example example_name

Replace example_name with the name of the example you want to run.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

§License

The project is dual-licensed under the terms of both the MIT license and the Apache License (Version 2.0).

§Acknowledgments

This crate wouldn’t be possible without the valuable open-source work of others, especially:

  • quick-xml for fast XML serialization and deserialization.

Re-exports§

Modules§

  • data
    Contains the main types and data structures used to represent RSS feeds. This module contains the core data structures and functionality for RSS feeds.
  • error
    Defines error types used throughout the library.
  • generator
    Implements RSS feed generation functionality.
  • macros
    Provides procedural macros for simplifying RSS operations. This module provides macros for generating RSS feeds and setting fields for RSS data.
  • parser
    Implements RSS feed parsing functionality. A robust and flexible RSS feed parser.
  • prelude
    Prelude module for convenient importing of common types and functions.
  • validator
    Provides utilities for validating RSS feeds. RSS feed validator module

Macros§

Constants§

Functions§

  • quick_rss
    A convenience function to generate a minimal valid RSS 2.0 feed.