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
129
130
131
132

#![allow(clippy::from_over_into)]

//! **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;
//! 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"] }
//! }
//! ```

// 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, ParsedEntityStruct};

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

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

#[cfg(test)]
mod tests;