gray matter

灰色

从字符串或文件中解析前符号。快速，可靠且易于使用。默认情况下对YAML的前提进行解析，但也支持YAML，JSON，TOML或Coffee Front-Matter，并提供设置自定义定界符的选项。由金属匠，组装，动词和许多其他项目使用。

请考虑关注该项目的作者乔恩·施林克特（Jon Schlinkert），并考虑主演该项目以显示您的❤️和支持。

安装

使用NPM安装：

$ npm install --save gray-matter

小心！

请参阅ChangElog，了解有关v3.0中进行的破坏变化。

赞助商

多亏了以下公司，组织和个人支持灰色 – 灰色持续的维护和发展！成为赞助商，将您的徽标添加到此读数或我的其他任何项目中

这做什么？

 const fs = require ( \'fs\' ) ;
const matter = require ( \'gray-matter\' ) ;
const str = fs . readFileSync ( \'example.html\' , \'utf8\' ) ;
console . log ( matter ( str ) ) ;

像这样将字符串转换为前符号：

 ---
title : Hello
slug : home
---
< h1 >Hello world!</ h1 >

像这样的对象：

 {
  content : \'<h1>Hello world!</h1>\' ,
  data : {
    title : \'Hello\' ,
    slug : \'home\'
  }
} 

为什么要使用灰色膜？

• 简单：主函数采用字符串并返回对象
• 准确：比依靠正则解析的前摩托解析器更好地捕捉和处理边缘壳体
• 快速：比其他使用正则解析的前后解析器快的速度
• 灵活：默认情况下，Gray-Matter能够解析YAML，JSON和JavaScript Front-Matter。但是可以添加其他引擎。
• 可扩展：使用自定义定系数，或添加对任何语言的支持，例如TOML，Coffeescript或CSON
• 战斗测试：由汇编，金属史密斯，现象，动词，生成，更新和其他许多人使用。

用法

使用Node的require()系统：

 const matter = require ( \'gray-matter\' ) ;

或与打字稿

 import matter = require ( \'gray-matter\' ) ;
// OR
import * as matter from \'gray-matter\' ;

将字符串和选项传递给灰色 – 毛线：

 console . log ( matter ( \'---\\ntitle: Front Matter\\n---\\nThis is content.\' ) ) ;

返回：

 {
  content : \'\\nThis is content.\' ,
  data : {
    title : \'Front Matter\'
  }
}

有关返回对象的更多信息，请参见下面的部分。

返回的对象

灰色 – 模 – 返回具有以下属性的file对象。

枚举

• file.data {object} ：通过解析前模创建的对象
• file.content {string} ：输入字符串，删除matter
• file.excerpt {string} ：摘录，如果在选项上定义
• file.empty {string} ：当前形式为“空”（所有空格，根本没有，或者只是注释，没有数据）时，该属性将设置原始字符串。有关用例的详细信息，请参见＃65。
• file.isEmpty {boolean} ：true如果前消息是空的。

不可能

此外，将以下不可耗尽的属性添加到对象中以帮助调试。

• file.orig {buffer} ：原始输入字符串（或buffer）
• file.language {string} ：解析的前后语言。 yaml是默认
• file.matter {string} ：原始的，未散布的前后字符串
• file.stringify {function} ：通过将file.data转换为给定语言中的字符串，将其包装在定界符中，然后将其预先准备为file.content 。

运行示例

如果您想测试示例，请首先克隆灰色 – 重点到my-project中（或任何想要的地方）：

$ git clone https://github*.c**om/jonschlinkert/gray-matter my-project

CD进入my-project并安装依赖项：

$ cd my-project && npm install

然后运行任何示例以查看灰色 – 象征的工作方式：

$ node examples/ < example_name >

链接到示例

• 咖啡
• 摘录 – 分离器
• 摘录统计
• 摘抄
• JavaScript
• JSON-Stringify
• JSON
• 恢复空
• 部分 – 开发
• 部分
• 汤姆
• YAML分解
• yaml

API

事情

从字符串中获取content或对象，并从字符串中提取和解析，然后返回具有data ， content和其他有用属性的对象。

参数

• input {object | string} ：字符串，或带有content字符串的对象
• options {对象}
• returns {对象}

例子

 const matter = require ( \'gray-matter\' ) ;
console . log ( matter ( \'---\\ntitle: Home\\n---\\nOther stuff\' ) ) ;
//=> { data: { title: \'Home\'}, content: \'Other stuff\' }

.Stringify

将对象串起到YAML或指定的语言，然后将其附加到给定的字符串。默认情况下，只能将YAML和JSON串制。请参阅“引擎部分”部分，以了解如何串用其他语言。

参数

• file {String | Object} ：要附加到字符串的Front-Matter或带有file.content字符串的文件对象的内容字符串。
• data {object} ：前面要弦乐。
• options {Object} ：将传递到灰色粘合和JS-yaml的选项。
• returns {string} ：返回一个通过将字符串的yaml与定界数包装而创建的字符串，并将其附加到给定的字符串中。

例子

 console . log ( matter . stringify ( \'foo bar baz\' , { title : \'Home\' } ) ) ;
// results in:
// ---
// title: Home
// ---
// foo bar baz

。读

同步读取文件系统中的文件并解析前事项。返回与主函数相同的对象。

参数

• filepath {string} ：要读取的文件路径。
• options {Object} ：传递给灰色象征的选项。
• returns {对象} ：返回带有data和content对象

例子

 const file = matter . read ( \'./content/blog-post.md\' ) ;

。测试

如果给定的string具有正面功能，则返回true。

参数

• string {字符串}
• options {对象}
• returns {boolean} ：如果存在前面物质，则为true。

选项

options.excerpt

类型： Boolean|Function

默认值： undefined

提取直接遵循前后符号的摘录，或者如果不存在前者，则是字符串中的第一件事。

如果设置为excerpt: true ，它将默认情况下寻找前肌定界符---并抓住所有导致其的所有内容。

例子

 const str = \'---\\nfoo: bar\\n---\\nThis is an excerpt.\\n---\\nThis is content\' ;
const file = matter ( str , { excerpt : true } ) ;

结果：

 {
  content : \'This is an excerpt.\\n---\\nThis is content\' ,
  data : { foo : \'bar\' } ,
  excerpt : \'This is an excerpt.\\n\'
}

您还可以将excerpt设置为函数。此函数使用最初将其作为参数传递给灰色 – 毛线的“文件”和“选项”，因此您可以控制如何从内容中提取摘录。

例子

 // returns the first 4 lines of the contents
function firstFourLines ( file , options ) {
  file . excerpt = file . content . split ( \'\\n\' ) . slice ( 0 , 4 ) . join ( \' \' ) ;
}

const file =  matter ( [
  \'---\' ,
  \'foo: bar\' ,
  \'---\' ,
  \'Only this\' ,
  \'will be\' ,
  \'in the\' ,
  \'excerpt\' ,
  \'but not this...\'
] . join ( \'\\n\' ) , { excerpt : firstFourLines } ) ;

结果：

 {
  content : \'Only this\\nwill be\\nin the\\nexcerpt\\nbut not this...\' ,
  data : { foo : \'bar\' } ,
  excerpt : \'Only this will be in the excerpt\'
}

options.excerpt_separator

类型： String

默认值： undefined

定义用于摘录的自定义分离器。

\’}));\”>

 console . log ( matter ( string , { excerpt_separator : \'<!-- end -->\' } ) ) ;

例子

以下HTML字符串：

<h1>Hello world</h1>\”>

---
title: Blog
---
My awesome blog.
<!-- end -->
< h1 > Hello world </ h1 >

结果：

\\n<h1>Hello world</h1>\’
}\”>

 {
  data : { title : \'Blog\' } ,
  excerpt : \'My awesome blog.\' ,
  content : \'My awesome blog.\\n<!-- end -->\\n<h1>Hello world</h1>\'
}

选项。发动机

定义用于解析和/或串起前摩擦的自定义引擎。

类型：引擎的Object对象

默认值： JSON ， YAML和JavaScript默认情况下已处理。

发动机格式

引擎可以是带有parse对象，并且（（可选）） stringify方法，也可以是仅用于解析的函数。

例子

 const toml = require ( \'toml\' ) ;

/**
 * defined as a function
 */

const file = matter ( str , {
  engines : {
    toml : toml . parse . bind ( toml ) ,
  }
} ) ;

/**
 * Or as an object
 */

const file = matter ( str , {
  engines : {
    toml : {
      parse : toml . parse . bind ( toml ) ,

      // example of throwing an error to let users know stringifying is
      // not supported (a TOML stringifier might exist, this is just an example)
      stringify : function ( ) {
        throw new Error ( \'cannot stringify to TOML\' ) ;
      }
    }
  }
} ) ;

console . log ( file ) ;

选项。语言

类型： String

默认值： yaml

定义用于解析前后解析的引擎。

 console . log ( matter ( string , { language : \'toml\' } ) ) ;

例子

以下HTML字符串：

---
title = \"TOML\"
description = \"Front matter\"
categories = \"front matter toml\"
---
This is content

结果：

 { content : \'This is content\' ,
  excerpt : \'\' ,
  data :
   { title : \'TOML\' ,
     description : \'Front matter\' ,
     categories : \'front matter toml\' } }

动态语言检测

Gray-Matter不会在选项上定义语言，而是会自动检测第一个定界符后定义的语言，并选择用于解析的正确引擎。

---toml
title = \"TOML\"
description = \"Front matter\"
categories = \"front matter toml\"
---
This is content

options.delimiters

类型： String

默认： ---

可以作为一系列字符串传递开放和关闭的定系数。

例子：

 // format delims as a string
matter . read ( \'file.md\' , { delims : \'~~~\' } ) ;
// or an array (open/close)
matter . read ( \'file.md\' , { delims : [ \'~~~\' , \'~~~\' ] } ) ;

会解析：

~~~
title: Home
~~~
This is the {{title}} page.

弃用的选项

options.lang

减少，请使用options.language。

options.delims

减少，请使用options.delimiters。

options.parsers

减少，请使用options.engines。

关于

$ npm install && npm test

$ npm install -g verbose/verb#dev verb-generate-readme && verb

相关项目

您可能对这些项目感兴趣：

• 组装：将岩石从袜子中拿出来！组装使您快速创建Web项目……更多|首页
• 金属史密斯：一个非常简单，可插入的静态站点生成器。 |首页
• 动词：GitHub项目的文档生成器。动词非常强大，易于使用，并且被使用……更多|首页

贡献者

作者

乔恩·施林克特（Jon Schlinkert）

• github概况
• Twitter个人资料
• LinkedIn个人资料

执照

版权所有©2023，Jon Schlinkert。根据MIT许可发布。

该文件是由2023年7月12日的V0.8.0 v0.8.0生成的。