Crate frontmatter_gen

Frontmatter Gen (frontmatter-gen)

A robust Rust library for parsing and serializing frontmatter in various formats, including YAML, TOML, and JSON.

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

Overview

frontmatter-gen is a flexible Rust library that provides functionality for extracting, parsing, and serializing frontmatter in various formats. It’s designed for use in static site generators, content management systems, and any application that needs to handle metadata at the beginning of content files.

Key Features

• Multiple Format Support: Parse and serialize frontmatter in YAML, TOML, and JSON formats.
• Flexible Extraction: Extract frontmatter from content, supporting different delimiters.
• Robust Error Handling: Comprehensive error types for detailed problem reporting.
• Customizable Parsing: Configure parsing options to suit your needs.
• Efficient Conversions: Convert between different frontmatter formats seamlessly.
• Type-Safe Value Handling: Utilize the Value enum for type-safe frontmatter data manipulation.

Installation

Add this to your Cargo.toml:

[dependencies]
frontmatter-gen = "0.0.2"

Usage

Here are some examples of how to use the library:

Extracting Frontmatter

use frontmatter_gen::extract;

let content = r#"---
title: My Post
date: 2023-05-20
---
Content here"#;

let (frontmatter, remaining_content) = extract(content).unwrap();
assert_eq!(frontmatter.get("title").unwrap().as_str().unwrap(), "My Post");
assert_eq!(remaining_content, "Content here");

Converting Formats

use frontmatter_gen::{Frontmatter, Format, Value, to_format};

let mut frontmatter = Frontmatter::new();
frontmatter.insert("title".to_string(), Value::String("My Post".to_string()));
frontmatter.insert("date".to_string(), Value::String("2023-05-20".to_string()));

let yaml = to_format(&frontmatter, Format::Yaml).unwrap();
assert!(yaml.contains("title: My Post"));
assert!(yaml.contains("date: '2023-05-20'"));

Parsing Different Formats

use frontmatter_gen::{parser, Format};

let yaml = "title: My Post\ndate: 2023-05-20\n";
let frontmatter = parser::parse(yaml, Format::Yaml).unwrap();

let toml = "title = \"My Post\"\ndate = 2023-05-20\n";
let frontmatter = parser::parse(toml, Format::Toml).unwrap();

let json = r#"{"title": "My Post", "date": "2023-05-20"}"#;
let frontmatter = parser::parse(json, Format::Json).unwrap();

Error Handling

The library provides comprehensive error handling through the FrontmatterError enum:

use frontmatter_gen::error::FrontmatterError;

fn example_usage() -> Result<(), FrontmatterError> {
    let invalid_toml = "invalid toml content";
    match toml::from_str::<toml::Value>(invalid_toml) {
        Ok(_) => Ok(()),
        Err(e) => Err(FrontmatterError::TomlParseError(e)),
    }
}

Documentation

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

Examples

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

cargo run --example example_name

Available examples:

• error
• extractor
• lib
• parser
• types

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Acknowledgements

Special thanks to all contributors who have helped build the frontmatter-gen library.

Re-exports

• pub use types::Format;
• pub use types::Frontmatter;
• pub use types::Value;

Modules

• error
  The error module contains error types related to the frontmatter parsing process. This module defines the error types used throughout the frontmatter-gen crate.
• extractor
  The extractor module contains functions for extracting raw frontmatter from content. This module provides functionality for extracting frontmatter from content.
• parser
  The parser module contains functions for parsing frontmatter into a structured format. This module provides functionality for parsing and serializing frontmatter in various formats.
• types
  The types module contains types related to the frontmatter parsing process. This module defines the core types used throughout the frontmatter-gen crate. It includes the Format enum for representing different frontmatter formats, the Value enum for representing various data types that can be stored in frontmatter, and the Frontmatter struct which is the main container for frontmatter data.

Functions

• extract
  Extracts frontmatter from a string of content.
• to_format
  Converts frontmatter to a specific format.