#markdown #parse #front-matter #gray-matter #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.

6 releases

0.2.4 Jul 22, 2022
0.2.3 Jun 1, 2022
0.2.2 Feb 24, 2022
0.2.1 Sep 12, 2021
0.1.0 Feb 7, 2021

#112 in Parser implementations

Download history 103/week @ 2022-08-02 128/week @ 2022-08-09 89/week @ 2022-08-16 77/week @ 2022-08-23 70/week @ 2022-08-30 97/week @ 2022-09-06 86/week @ 2022-09-13 77/week @ 2022-09-20 106/week @ 2022-09-27 139/week @ 2022-10-04 65/week @ 2022-10-11 52/week @ 2022-10-18 120/week @ 2022-10-25 186/week @ 2022-11-01 141/week @ 2022-11-08 167/week @ 2022-11-15

618 downloads per month
Used in fewer than 6 crates

MIT license

52KB
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();
}

Contribution

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

Dependencies

~0.8–1.5MB
~35K SLoC