#front-matter #toml-parser #markdown-parser #yaml-parser #parser #markdown #json-parser

gray_matter

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

10 releases

0.2.8 May 27, 2024
0.2.6 Apr 8, 2023
0.2.5 Jan 13, 2023
0.2.4 Jul 22, 2022
0.1.0 Feb 7, 2021

#97 in Parser implementations

Download history 1498/week @ 2024-08-04 2259/week @ 2024-08-11 1545/week @ 2024-08-18 1765/week @ 2024-08-25 1371/week @ 2024-09-01 1880/week @ 2024-09-08 1434/week @ 2024-09-15 1725/week @ 2024-09-22 2610/week @ 2024-09-29 1167/week @ 2024-10-06 1680/week @ 2024-10-13 2444/week @ 2024-10-20 2381/week @ 2024-10-27 2026/week @ 2024-11-03 2569/week @ 2024-11-10 3225/week @ 2024-11-17

10,354 downloads per month
Used in 18 crates (16 directly)

MIT license

56KB
1.5K 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();
}

Custom close delimiter

The open and close delimiter are the same by default (---). You can change this by modifiying close_delimiter property of 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.close_delimiter = Some("-->".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

~2.8–4MB
~70K SLoC