Rust元数据解析库gray_matter的使用

gray_matter是一个高效的Rust库，用于从Markdown、YAML等文件中提取和解析Front Matter数据。它是gray-matter的Rust实现版本，支持以下格式的Front Matter解析：

• TOML
• YAML
• JSON

该库还提供了Engine trait接口，允许开发者实现自定义的解析器。

基础用法

添加依赖

首先需要在Cargo.toml中添加依赖：

[dependencies]
gray_matter = "0.3"

基本解析示例

use gray_matter::{Matter, ParsedEntity, Result};
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() -> Result<()> {
    // 使用YAML引擎创建解析器
    let matter = Matter::<YAML>::new();
    let result: ParsedEntity = matter.parse(INPUT)?;

    // 验证解析结果
    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()));

    // 将数据反序列化为自定义结构体
    #[derive(Deserialize, Debug)]
    struct FrontMatter {
        title: String,
        tags: Vec<String>
    }

    let result_with_struct = matter.parse::<FrontMatter>(INPUT)?;
    println!("{:?}", result_with_struct.data);
    // 输出: FrontMatter { title: "gray-matter-rs", tags: ["gray-matter", "rust"] }
    Ok(())
}

自定义分隔符

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

fn main() -> Result<()> {
    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: ParsedEntity<FrontMatter> = matter.parse(
        "~~~\nabc: xyz\n~~~\nfoo\nbar\nbaz\n<!-- endexcerpt -->\ncontent",
    )?;

    Ok(())
}

自定义关闭分隔符

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

fn main() -> Result<()> {
    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: ParsedEntity<FrontMatter> = matter.parse(
        "<!--\nabc: xyz\n-->\nfoo\nbar\nbaz\n<!-- endexcerpt -->\ncontent",
    )?;

    Ok(())
}

完整示例

下面是一个完整的Markdown文件解析示例：

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

fn main() -> Result<()> {
    // 包含Front Matter的Markdown内容
    const MARKDOWN: &str = r#"---
title: Rust元数据解析
author: 张伟
date: 2023-05-15
categories:
  - 编程
  - Rust
---
这是文章的摘要部分

<!-- endexcerpt -->

这里是文章的正文内容..."#;
    
    // 创建解析器并配置分隔符
    let mut matter = Matter::<YAML>::new();
    matter.delimiter = "---".to_owned();
    matter.close_delimiter = Some("---".to_owned());
    matter.excerpt_delimiter = Some("<!-- endexcerpt -->".to_owned());

    // 定义Front Matter数据结构
    #[derive(Deserialize, Debug)]
    struct ArticleMeta {
        title: String,
        author: String,
        date: String,
        categories: Vec<String>,
    }

    // 解析内容
    let result = matter.parse::<ArticleMeta>(MARKDOWN)?;
    
    // 输出解析结果
    println!("元数据: {:?}", result.data.unwrap());
    println!("正文内容: {}", result.content);
    println!("摘要: {}", result.excerpt.unwrap());
    
    Ok(())
}

这个完整示例展示了如何：

1. 配置gray_matter解析器
2. 定义自定义数据结构来反序列化Front Matter
3. 解析包含Front Matter的Markdown内容
4. 提取并输出元数据、正文和摘要

你可以根据需要调整解析引擎(TOML/JSON/YAML)或修改分隔符配置以适应不同的文档格式。