Crate rss_gen

RSS Gen

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

• 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).

• Apache License, Version 2.0
• MIT license

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

pub use data::RssData;

pub use data::RssItem;

pub use data::RssVersion;

pub use error::Result;

pub use error::RssError;

pub use generator::generate_rss;

pub use parser::parse_rss;

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

macro_generate_rss

Generates an RSS feed from the given RssData struct.

macro_get_args

macro_get_args Macro

macro_metadata_option

macro_metadata_option Macro

macro_set_rss_data_fields

Sets fields of the RssData struct.

macro_write_element

Writes an XML element with the given name and content.

Constants

MAX_DESCRIPTION_LENGTH

Maximum length for description fields in the RSS feed.

MAX_FEED_SIZE

Maximum size for the entire RSS feed.

MAX_GENERAL_LENGTH

Maximum length for general fields in the RSS feed.

MAX_LINK_LENGTH

Maximum length for link fields in the RSS feed.

MAX_TITLE_LENGTH

Maximum length for title fields in the RSS feed.

VERSION

The current version of the rss-gen crate, set at compile-time from Cargo.toml.

Functions

quick_rss

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