#front-matter #parse #markdown #yaml-json #json-toml #data-format #front-matter-parsers

gray_matter

Smart front matter parser. An implementation of gray-matter in rust. Parses YAML, JSON, TOML and support for custom parsers.

8 releases

0.2.6 Apr 8, 2023
0.2.5 Jan 13, 2023
0.2.4 Jul 22, 2022
0.2.3 Jun 1, 2022
0.1.0 Feb 7, 2021

#129 in Parser implementations

Download history 1294/week @ 2023-11-23 2035/week @ 2023-11-30 1852/week @ 2023-12-07 1832/week @ 2023-12-14 2338/week @ 2023-12-21 2067/week @ 2023-12-28 3456/week @ 2024-01-04 3080/week @ 2024-01-11 2698/week @ 2024-01-18 3229/week @ 2024-01-25 2652/week @ 2024-02-01 1255/week @ 2024-02-08 1791/week @ 2024-02-15 2517/week @ 2024-02-22 3003/week @ 2024-02-29 2381/week @ 2024-03-07

9,950 downloads per month
Used in 11 crates

MIT license

54KB
1K SLoC

Latest Version Documentation

gray_matter is a tool for easily extracting front matter out of a string. It is a fast Rust implementation of gray-matter. It supports the following front matter formats:

  • TOML
  • YAML
  • JSON

It also has an Engine trait interface for implementing your own parsers that work with gray_matter.

Usage

Add gray_matter as a dependency

Append this crate to the Cargo.toml:

[dependencies]
# other dependencies...
gray_matter = "0.2"

Basic parsing

use gray_matter::Matter;
use gray_matter::engine::YAML;
use serde::Deserialize;

const INPUT: &str = r#"---
title: gray-matter-rs
tags:
  - gray-matter
  - rust
---
Some excerpt
---
Other stuff
"#;

fn main() {
    // Select one parser engine, such as YAML, and parse it
    // into gray_matter's custom data type: `Pod`
    let matter = Matter::<YAML>::new();
    let result = matter.parse(INPUT);

    // You can now inspect the data from gray_matter.
    assert_eq!(result.content, "Some excerpt\n---\nOther stuff");
    assert_eq!(result.excerpt, Some("Some excerpt".to_owned()));
    assert_eq!(result.data.as_ref().unwrap()["title"].as_string(), Ok("gray-matter-rs".to_string()));
    assert_eq!(result.data.as_ref().unwrap()["tags"][0].as_string(), Ok("gray-matter".to_string()));
    assert_eq!(result.data.as_ref().unwrap()["tags"][1].as_string(), Ok("rust".to_string()));

    // The `Pod` data type can be a bit unwieldy, so
    // you can also deserialize it into a custom struct
    #[derive(Deserialize, Debug)]
    struct FrontMatter {
        title: String,
        tags: Vec<String>
    }

    // Deserialize `result` manually:
    let front_matter: FrontMatter = result.data.unwrap().deserialize().unwrap();
    println!("{:?}", front_matter);
    // FrontMatter { title: "gray-matter-rs", tags: ["gray-matter", "rust"] }

    // ...or skip a step, by using `parse_with_struct`.
    let result_with_struct = matter.parse_with_struct::<FrontMatter>(INPUT).unwrap();
    println!("{:?}", result_with_struct.data)
    // FrontMatter { title: "gray-matter-rs", tags: ["gray-matter", "rust"] }
}

Custom Delimiters

The default delimiter is ---, both for front matter and excerpts. You can change this by modifiying the Matter struct.

use gray_matter::{Matter, ParsedEntityStruct};
use gray_matter::engine::YAML;
use serde::Deserialize;

fn main() {
    let mut matter: Matter<YAML> = Matter::new();
    matter.delimiter = "~~~".to_owned();
    matter.excerpt_delimiter = Some("<!-- endexcerpt -->".to_owned());

    #[derive(Deserialize, Debug)]
    struct FrontMatter {
        abc: String,
    }

    let result: ParsedEntityStruct<FrontMatter> = matter.parse_with_struct(
        "~~~\nabc: xyz\n~~~\nfoo\nbar\nbaz\n<!-- endexcerpt -->\ncontent",
    ).unwrap();
}

Contributors

Contribution

If you need more parser engines, feel free to create a PR to help me complete this crate.

Dependencies

~1–1.8MB
~42K SLoC