gray_matter 0.3.2

Smart front matter parser. An implementation of gray-matter in rust. Parses YAML, JSON, TOML and support for custom parsers.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

#![allow(clippy::from_over_into)]
#![cfg_attr(docsrs, feature(doc_cfg))]

//! **gray_matter** is a tool for easily extracting front matter out of a string. It is a fast Rust
//! implementation of the original [gray-matter](https://github.com/jonschlinkert/gray-matter) by
//! [Jon Schlinkert](https://github.com/jonschlinkert).
//!
//! ## What can gray_matter do?
//!
//! It can take some string or file like this:
//!
//! ```markdown
//! ---
//! title: This is the title
//! tags:
//!     - awesome-tag
//!     - more-awesome-tag
//! ---
//!
//! # Header
//!
//! This is my really cool document!
//! ```
//!
//! and strip the YAML contained within the delimiters (`---`), to create a struct like this[^1]:
//!
//! ```ignore
//! MyStruct {
//!     title: "This is the title",
//!     tags: ["awesome-tag", "more-awesome-tag"]
//! }
//! ```
//!
//! [^1]: The struct is purely for demonstration.
//!
//! ## Why would I use this?
//!
//! You want to have configurability inside plain text documents, like for example a Markdown document.
//! [Pandoc](https://pandoc.org) and [Hugo](https://gohugo.io) are examples of tools that use this
//! kind of configuration, but the sky really is the limit.
//!
//! ## What formats are supported?
//!
//! **gray_matter** has built in support for [YAML](crate::engine::YAML),
//! [TOML](crate::engine::TOML) and [JSON](crate::engine::JSON), but the
//! [`Engine`](crate::engine::Engine) trait allows for virtually any format you wish to be
//! supported.
//!
//! # Examples
//!
//! ## Basic parsing
//!
//! ```rust
//! use gray_matter::{Matter, ParsedEntity, Result};
//! use serde::Deserialize;
//!
//! const INPUT: &str = r#"---
//! title: gray-matter-rs
//! tags:
//!   - gray-matter
//!   - rust
//! ---
//! Some excerpt
//! ---
//! Other stuff
//! "#;
//!
//! #[cfg(feature = "yaml")]
//! fn main() -> Result<()> {
//!     // Select one parser engine, such as YAML, and parse it
//!     // into gray_matter's custom data type: `Pod`
//!     use gray_matter::engine::YAML;
//!     let matter = Matter::<YAML>::new();
//!     let result: ParsedEntity = 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 default `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>
//!     }
//!
//!     let result_with_struct = matter.parse::<FrontMatter>(INPUT)?;
//!     println!("{:?}", result_with_struct.data);
//!     // FrontMatter { title: "gray-matter-rs", tags: ["gray-matter", "rust"] }
//!     Ok(())
//! }
//! ```

// Test README
#[cfg(doctest)]
macro_rules! doc_check {
    ($x:expr) => {
        #[doc = $x]
        extern "C" {}
    };
}

#[cfg(doctest)]
doc_check!(include_str!("../README.md"));

/// A module containing the [`Engine`](crate::engine::Engine) trait, along with gray_matter's default engines.
pub mod engine;

#[doc(hidden)]
pub mod entity;
#[doc(inline)]
pub use entity::ParsedEntity;

#[doc(hidden)]
pub mod matter;
#[doc(inline)]
pub use matter::Matter;

#[doc(hidden)]
pub mod value;
#[doc(inline)]
pub use value::pod::Result;
#[doc(inline)]
pub use value::{error::Error, pod::Pod};