gray-matter
Advanced tools
Comparing version 0.4.2 to 0.5.0
@@ -1,14 +0,29 @@ | ||
# {%= name %} {%= badge('fury') %} | ||
--- | ||
tags: ['verb-tag-jscomments'] | ||
--- | ||
# {%= name %} {%= badge("fury") %} | ||
> {%= description %} | ||
v0.4.0 has breaking changes! `context` has been changed to `data`. | ||
Used by [assemble](https://github.com/assemble/assemble), [verb](https://github.com/assemble/verb), and thousands of other projects! | ||
* Use custom delimiters | ||
**v0.5.0 has breaking changes!** | ||
* YAML is now parsed using the `.safeLoad()` method from [js-yaml](http://github.com/nodeca/js-yaml). | ||
* To parse coffee, CSON or javascript front matter, you must set `options.eval` to true. | ||
* `stringify()` has been renamed to `toJSON()` | ||
* `stringifyYAML()` has been renamed to `toYAML()` | ||
## Highlights | ||
* Reliable and battle-tested. | ||
* Will extract and parse: | ||
* [YAML](http://github.com/nodeca/js-yaml) | ||
* [JSON](http://en.wikipedia.org/wiki/Json) | ||
* [CoffeeScript](http://coffeescript.org) | ||
* [TOML](http://github.com/mojombo/toml) | ||
* Easy to add additional parsers! | ||
* [CoffeeScript](http://coffeescript.org) when `options.eval` is set to `true` | ||
* [CSON](https://github.com/bevry/cson) when `options.eval` is set to `true` | ||
* JavaScript: when `options.eval` is set to `true` | ||
* Easy to add additional parsers! pull requests welcome! | ||
@@ -20,10 +35,17 @@ #### TOC | ||
## Install | ||
{%= docs("install") %} | ||
{%= include("install-npm", {save: true}) %} | ||
{%= include("install-bower") %} | ||
## Usage | ||
{%= docs("usage") %} | ||
## Methods | ||
{%= docs("methods") %} | ||
```js | ||
var matter = require('gray-matter'); | ||
console.log(matter('---\ntitle: foo\n---\nbar'); | ||
//=> {data: {title: 'foo'}, content: 'bar', orig: '---\ntitle: foo\n---\nbar'} | ||
``` | ||
## API | ||
{%= docs("api") %} | ||
## Options | ||
@@ -38,7 +60,8 @@ {%= docs("options") %} | ||
## Authors | ||
{%= contrib("authors") %} | ||
{%= include("author") %} | ||
## License | ||
Copyright (c) 2014 Jon Schlinkert, Brian Woodward, contributors. | ||
{%= copyright() %} | ||
{%= license() %} | ||
@@ -48,2 +71,7 @@ | ||
{%= include("footer") %} | ||
{%= include("footer") %} | ||
[js-yaml]: https://github.com/nodeca/js-yaml | ||
[coffee-script]: https://github.com/jashkenas/coffeescript | ||
[toml-node]: https://github.com/BinaryMuse/toml-node |
{ | ||
"name": "gray-matter", | ||
"version": "0.4.2", | ||
"version": "0.5.0", | ||
"main": [ | ||
@@ -5,0 +5,0 @@ "index.js" |
@@ -1,2 +0,1 @@ | ||
## matter | ||
@@ -42,3 +41,3 @@ Let's say our page, `foo.html` contains | ||
## matter.extend | ||
## .extend | ||
@@ -71,2 +70,2 @@ Given this page: | ||
Hooray! | ||
``` | ||
``` |
> All methods will accept an options object to be passed as a second parameter | ||
## lang | ||
## options.eval | ||
Type: `Boolean` | ||
Default: `false` | ||
Evaluate coffee-script, CSON or JavaScript in front-matter. If you aren't aware of the dangers, google is your friend. | ||
## options.lang | ||
Type: `String` | ||
@@ -9,8 +16,11 @@ | ||
The parser to use on the extracted front matter. Valid options include: | ||
* `yaml` | ||
* `json` | ||
* `coffee` requires the [`coffee-script`](https://www.npmjs.org/package/coffee-script) package | ||
* `toml` requires the [`toml`](https://www.npmjs.org/package/toml) package | ||
* `coffee` | ||
* `cson` | ||
* `toml` | ||
* `js`|`javascript` | ||
## delims | ||
## options.delims | ||
Type: `Object` | ||
@@ -38,3 +48,4 @@ | ||
## autodetect | ||
## options.autodetect | ||
Type: `Boolean` | ||
@@ -55,4 +66,4 @@ | ||
[%= user %] | ||
[%= reverse(user) %] | ||
``` | ||
{%%= user %} | ||
{%%= reverse(user) %} | ||
``` |
@@ -7,7 +7,7 @@ > Why another YAML Front Matter library? | ||
* Allow custom delimiters | ||
* Use a dependable and well-supported library for parsing YAML | ||
* Don't fail if YAML front matter exists, but no content | ||
* Don't fail if content exists, but no YAML front matter | ||
* Use a dependable and well-supported library for parsing YAML and other languages | ||
* Don't fail when no content exists | ||
* Don't fail when no front matter exists | ||
* Have no problem reading YAML files directly | ||
* Have no problem with complex content, including fenced code blocks containing examples of YAML front matter. | ||
* Have no problem with complex content, including fenced code blocks that contain examples of YAML front matter. Other parsers fail on this. | ||
* Should return an object that contains the parsed YAML front matter and content, as well as the "original" content. |
171
index.js
@@ -1,2 +0,2 @@ | ||
/** | ||
/**! | ||
* gray-matter <https://github.com/assemble/gray-matter> | ||
@@ -8,44 +8,55 @@ * | ||
const YAML = require('js-yaml'); | ||
const delims = require('delims'); | ||
const file = require('fs-utils'); | ||
const log = require('verbalize'); | ||
const _ = require('lodash'); | ||
'use strict'; | ||
const parsers = require('./lib/parsers'); | ||
const utils = require('./lib/utils'); | ||
var fs = require('fs'); | ||
var YAML = require('js-yaml'); | ||
var log = require('verbalize'); | ||
var Delims = require('delims'); | ||
var _ = require('lodash'); | ||
var parsers = require('./lib/parsers'); | ||
var utils = require('./lib/utils'); | ||
/** | ||
* Parse the given string | ||
* Parse front matter from the given `str` and return an object | ||
* with `data`, `content` and the `original` string. | ||
* | ||
* @param {String} the string to parse | ||
* @param {Object} object of options | ||
* | ||
* @return {Object} | ||
* @param {String} `str` The string to parse | ||
* @param {Object} `options` Object of options | ||
* @option {Array} [option] `delims` Define custom delimiters to use as an array, e.g. `['~~~', '~~~']` | ||
* @option {Boolean} [option] `autodetect` If `true` will attempt to use the parser `lang` defined after the first front matter fence. | ||
* @return {Object} `file` Object with the following properties. | ||
* @property {Object} [file] `data` Parsed front matter | ||
* @property {String} [file] `content` The content of the file, excluding front-matter | ||
* @property {String} [file] `orig` The original, un-parsed content of the file, including front-matter. | ||
* @api public | ||
*/ | ||
function matter(str, options) { | ||
str = str.replace(/^\uFEFF/, '').replace(/\r/g, ''); | ||
var orig = str; | ||
var data = {}; | ||
var opts = _.defaults({}, options, { | ||
delims: ['---', '---'], | ||
delimsOpts: {}, | ||
lang: 'yaml' | ||
delimsOpts: {} | ||
}); | ||
var metadata = {}; | ||
var content = str; | ||
var delimiters = delims(opts.delims, opts.delimsOpts).evaluate; | ||
var delimiters = createDelims(opts.delims, opts.delimsOpts); | ||
// If true, will attempt to detect and register | ||
// the correct parser based on the returned string | ||
var lang; | ||
if(opts.autodetect) { | ||
opts.lang = utils.detectLang(opts.delims[0], content) || 'yaml'; | ||
content = utils.stripLang(opts.delims[0], content); | ||
lang = utils.detectLang(opts.delims[0], str); | ||
str = utils.stripLang(opts.delims[0], str); | ||
} | ||
// File object | ||
var fileObject = content.match(delimiters); | ||
if (fileObject && fileObject.length === 3) { | ||
opts.lang = String(opts.lang || lang || 'yaml'); | ||
var file = str.match(delimiters); | ||
if (file && file.length === 3) { | ||
try { | ||
metadata = parsers[opts.lang](fileObject[1]); | ||
data = parsers[opts.lang](file[1], opts); | ||
} catch(e) { | ||
@@ -55,18 +66,34 @@ e.origin = __filename; | ||
} | ||
content = fileObject[2]; | ||
str = file[2]; | ||
} | ||
return { | ||
data: metadata, | ||
content: file.normalizeNL(content), | ||
original: file.normalizeNL(str) | ||
}; | ||
return {data: data, content: str.trim(), orig: orig}; | ||
} | ||
// Read the file, then parse | ||
matter.read = function(src, options) { | ||
return matter(file.readFileSync(src, options), options); | ||
/** | ||
* Read a file then pass the string and `options` to `matter()`. | ||
* | ||
* @param {String} `filepath` The file to parse. | ||
* @param {Object} `options` Options to pass to `matter` | ||
* @return {Object} `file` Same object as `matter`, with one additional property, `path` | ||
* @api public | ||
*/ | ||
matter.read = function(filepath, options) { | ||
var opts = _.extend({}, options); | ||
var obj = matter(fs.readFileSync(filepath, 'utf8'), opts); | ||
return _.extend(obj, {path: filepath}); | ||
}; | ||
// Does YAML front matter exist? | ||
/** | ||
* Return `true` if front-matter exists. | ||
* | ||
* @param {String} `str` The string to parse | ||
* @param {Object} `options` Options to pass to `matter()` | ||
* @return {Boolean} `true` or `false` | ||
* @api public | ||
*/ | ||
matter.exists = function(str, options) { | ||
@@ -77,7 +104,17 @@ var obj = matter(str, options).data; | ||
// Extend and stringify YAML. | ||
/** | ||
* Parse YAML front matter from `str` and extend it with the | ||
* given `obj`, then return a string of YAML front matter. | ||
* | ||
* @param {String} `str` The string to parse | ||
* @param {Object} `obj` The object to use to extend the front matter. | ||
* @return {String} Extended YAML front matter. | ||
* @api public | ||
*/ | ||
matter.extend = function(str, obj) { | ||
if(matter.exists(str)) { | ||
var data = _.extend({}, matter(str).data, obj); | ||
var yaml = matter.stringifyYAML(data); | ||
var yaml = matter.toYAML(data); | ||
return '---\n' + yaml + '---'; | ||
@@ -89,19 +126,63 @@ } else { | ||
// Extend YAML, then put the file back together | ||
/** | ||
* Same as `.extend()`, but this method also adds the original | ||
* content string back as well. | ||
* | ||
* @param {String} `str` The string to parse | ||
* @param {Object} `obj` The object to use to extend the front matter. | ||
* @return {String} Original string with extended front matter. | ||
* @api public | ||
*/ | ||
matter.reconstruct = function(str, obj) { | ||
var front = matter.extend(str, obj); | ||
var content = matter(str).content; | ||
return front + content; | ||
return [front, content].join('\n'); | ||
}; | ||
// Stringify to jSON | ||
matter.stringify = function(str, options) { | ||
/** | ||
* Stringify front matter to JSON. | ||
* | ||
* @param {String} `str` | ||
* @param {Object} `options` | ||
* @return {Object} Parsed front matter as JSON. | ||
*/ | ||
matter.toJSON = function(str, options) { | ||
return matter(str, options).data; | ||
}; | ||
// Stringify to YAML | ||
matter.stringifyYAML = function(obj) { | ||
/** | ||
* Stringify front matter to YAML. | ||
* | ||
* @param {String} `str` | ||
* @param {Object} `options` | ||
* @return {String} Stringified YAML. | ||
*/ | ||
matter.toYAML = function(obj) { | ||
return YAML.dump(obj); | ||
}; | ||
module.exports = matter; | ||
/** | ||
* Utility method to create delimiters | ||
* | ||
* @api private | ||
*/ | ||
function createDelims(arr, options) { | ||
var delims = new Delims(); | ||
return delims.create(arr, options).evaluate; | ||
} | ||
/** | ||
* Expose `matter` | ||
* | ||
* @type {Object} | ||
*/ | ||
module.exports = matter; |
/** | ||
* gray-matter <https://github.com/assemble/gray-matter> | ||
* | ||
* Copyright (c) 2014 Jon Schlinkert, Brian Woodward, contributors. | ||
* Copyright (c) 2014 Jon Schlinkert, contributors. | ||
* Licensed under the MIT license. | ||
*/ | ||
'use strict'; | ||
/** | ||
* Module dependencies | ||
*/ | ||
var YAML = require('js-yaml'); | ||
var log = require('verbalize'); | ||
var _ = require('lodash'); | ||
var parse = module.exports = {}; | ||
function generateMessage (parser, e) { | ||
log.error(' [gray-matter]', log.bold(e)); | ||
// log.error(' [gray-matter]', log.yellow(parser) + ' detected but not found in node_modules.'); | ||
// log.error(' [gray-matter]', 'Please run `npm i ' + parser + '` to install.'); | ||
} | ||
/** | ||
* Expose `parser` | ||
* | ||
* @type {Object} | ||
*/ | ||
parse.yaml = function(src) { | ||
return YAML.load(src); | ||
}; | ||
var parser = module.exports; | ||
parse.json = function(src) { | ||
return JSON.parse(src); | ||
}; | ||
parse.coffee = function(src, options) { | ||
options = options || {}; | ||
/** | ||
* Parse YAML front matter | ||
* | ||
* @param {String} `str` The string to parse. | ||
* @param {Object} `options` Options to pass to [js-yaml]. | ||
* @return {Object} Parsed object of data. | ||
* @api public | ||
*/ | ||
parser.yaml = function(str, options) { | ||
var data = {}; | ||
try { | ||
var coffee = require('coffee-script'); | ||
return coffee['eval'](src, options); | ||
} catch (e) { | ||
generateMessage('coffee-script', e); | ||
data = YAML.safeLoad(str, options); | ||
} catch (err) { | ||
log.error(' [gray-matter] json:', log.bold(err)); | ||
} | ||
return data; | ||
}; | ||
parse.cson = function(src, options) { | ||
options = options || {}; | ||
/** | ||
* Parse JSON front matter | ||
* | ||
* @param {String} `str` The string to parse. | ||
* @return {Object} Parsed object of data. | ||
* @api public | ||
*/ | ||
parser.json = function(str) { | ||
var data = {}; | ||
try { | ||
var cson = require('cson'); | ||
return cson.parseSync(src, options); | ||
} catch (e) { | ||
generateMessage('cson', e); | ||
data = JSON.parse(str); | ||
} catch (err) { | ||
log.error(' [gray-matter] json:', log.bold(err)); | ||
} | ||
return data; | ||
}; | ||
parse.toml = function(src) { | ||
/** | ||
* Parse JavaScript front matter. To use javascript front-matter, you must | ||
* set `options.eval` to `true`. | ||
* | ||
* By default, javascript code is wrapped in a function that is immediately | ||
* executed when the parser is called. Thus, to be returned as a useful object, | ||
* code should be written as object properties. | ||
* | ||
* **Example:** | ||
* | ||
* ```coffee | ||
* ---js | ||
* title: 'autodetect-javascript', | ||
* // this function won't be invoked when the parser is called | ||
* fn: { | ||
* reverse: function(str) { | ||
* return str.split('').reverse().join(''); | ||
* } | ||
* } | ||
* --- | ||
* ``` | ||
* | ||
* @param {String} `str` The string to parse. | ||
* @param {Object} `options` Set `options.wrapped` to `false` to enable writing raw, un-wrapped javascript. | ||
* @return {Object} Parsed object of data. | ||
* @api public | ||
*/ | ||
parser.javascript = function(str, options) { | ||
var opts = _.extend({wrapped: true, eval: false}, options); | ||
if (opts.eval) { | ||
var fn = str; | ||
if (opts.wrapped) { | ||
fn = 'function data() {return { ' + str + '} } data();'; | ||
} | ||
var data = {}; | ||
try { | ||
data = eval(fn); | ||
} catch (err) { | ||
log.error(' [gray-matter] javascript:', log.bold(err)); | ||
} | ||
return data; | ||
} else { | ||
var msg = 'to parse javascript, you must set `options.eval` to `true`'; | ||
log.error(' [gray-matter] javascript:', log.bold(msg)); | ||
} | ||
}; | ||
/** | ||
* Alias for `parse.javascript()`. | ||
* | ||
* @api public | ||
*/ | ||
parser.js = parser.javascript; | ||
/** | ||
* Parse Coffee-Script front matter. To use coffee front-matter, you must | ||
* set `options.eval` to `true`. | ||
* | ||
* @param {String} `str` The string to parse. | ||
* @param {Object} `options` Options to pass to [coffee-script]. | ||
* @return {Object} Parsed object of data. | ||
* @api public | ||
*/ | ||
parser.coffee = function(str, options) { | ||
var opts = _.extend({eval: false}, options); | ||
if (opts.eval) { | ||
try { | ||
var coffee = require('coffee-script'); | ||
return coffee['eval'](str, options); | ||
} catch (e) { | ||
log.error(' [gray-matter] coffee-script:', log.bold(e)); | ||
} | ||
} else { | ||
var msg = 'to parse javascript, you must set `options.eval` to `true`'; | ||
log.error(' [gray-matter] javascript:', log.bold(msg)); | ||
} | ||
}; | ||
/** | ||
* Alias for `parse.coffee()`. | ||
* | ||
* @api public | ||
*/ | ||
parser.cson = parser.coffee; | ||
/** | ||
* Parse TOML front matter. | ||
* | ||
* @param {String} `str` The string to parse. | ||
* @param {Object} `options` Options to pass to [toml-node]. | ||
* @return {Object} Parsed object of data. | ||
* @api public | ||
*/ | ||
parser.toml = function(str) { | ||
try { | ||
var toml = require('toml'); | ||
return toml.parse(src.trim()); | ||
return toml.parse(str.trim()); | ||
} catch (e) { | ||
generateMessage('toml', e); | ||
log.error(' [gray-matter] TOML:', log.bold(e)); | ||
} | ||
}; |
{ | ||
"name": "gray-matter", | ||
"description": "A simple to use and extend front matter library. Supports parsing and extracting YAML, JSON, TOML or Coffee Front-Matter, with options to set custom delimiters.", | ||
"version": "0.4.2", | ||
"version": "0.5.0", | ||
"author": { | ||
@@ -20,14 +20,23 @@ "name": "Jon Schlinkert", | ||
"keywords": [ | ||
"JSON", | ||
"coffee", | ||
"coffee-script", | ||
"data", | ||
"docs", | ||
"documentation", | ||
"front", | ||
"front-matter", | ||
"front matter", | ||
"frontmatter", | ||
"yaml front matter", | ||
"generator", | ||
"javascript", | ||
"js", | ||
"markdown", | ||
"matter", | ||
"parse", | ||
"parser", | ||
"yfm", | ||
"JSON", | ||
"coffee", | ||
"coffee-script", | ||
"yaml" | ||
"site", | ||
"static", | ||
"toml", | ||
"yaml", | ||
"yfm" | ||
], | ||
@@ -42,16 +51,18 @@ "main": "index.js", | ||
"dependencies": { | ||
"delims": "^0.1.4", | ||
"fs-utils": "^0.4.3", | ||
"js-yaml": "^3.0.2", | ||
"coffee-script": "^1.8.0", | ||
"delims": "^0.3.0", | ||
"js-yaml": "^3.2.1", | ||
"lodash": "^2.4.1", | ||
"toml": "^2.0.6", | ||
"verbalize": "^0.1.2" | ||
}, | ||
"devDependencies": { | ||
"chai": "^1.9.1", | ||
"coffee-script": "^1.7.1", | ||
"cson-safe": "^0.1.1", | ||
"mocha": "^1.19.0", | ||
"toml": "^2.0.5", | ||
"verb": "^0.2.7" | ||
"should": "^4.0.4", | ||
"verb": "^0.2.15", | ||
"verb-tag-jscomments": "^0.2.2" | ||
}, | ||
"bugs": { | ||
"url": "" | ||
} | ||
} | ||
} |
147
README.md
@@ -1,35 +0,51 @@ | ||
# gray-matter [![NPM version](https://badge.fury.io/js/gray-matter.png)](http://badge.fury.io/js/gray-matter) | ||
# gray-matter [![NPM version](https://badge.fury.io/js/gray-matter.svg)](http://badge.fury.io/js/gray-matter) | ||
> A simple to use and extend front matter library. Supports parsing and extracting YAML, JSON, TOML or Coffee Front-Matter, with options to set custom delimiters. | ||
v0.4.0 has breaking changes! `context` has been changed to `data`. | ||
Used by [assemble](https://github.com/assemble/assemble), [verb](https://github.com/assemble/verb), and thousands of other projects! | ||
* Use custom delimiters | ||
**v0.5.0 has breaking changes!** | ||
* YAML is now parsed using the `.safeLoad()` method from [js-yaml](http://github.com/nodeca/js-yaml). | ||
* To parse coffee, CSON or javascript front matter, you must set `options.eval` to true. | ||
* `stringify()` has been renamed to `toJSON()` | ||
* `stringifyYAML()` has been renamed to `toYAML()` | ||
## Highlights | ||
* Reliable and battle-tested. | ||
* Will extract and parse: | ||
* [YAML](http://github.com/nodeca/js-yaml) | ||
* [JSON](http://en.wikipedia.org/wiki/Json) | ||
* [CoffeeScript](http://coffeescript.org) | ||
* [TOML](http://github.com/mojombo/toml) | ||
* Easy to add additional parsers! | ||
* [CoffeeScript](http://coffeescript.org) when `options.eval` is set to `true` | ||
* [CSON](https://github.com/bevry/cson) when `options.eval` is set to `true` | ||
* JavaScript: when `options.eval` is set to `true` | ||
* Easy to add additional parsers! pull requests welcome! | ||
#### TOC | ||
<!-- toc --> | ||
* [Highlights](#highlights) | ||
* [Install](#install) | ||
* [Usage](#usage) | ||
* [Methods](#methods) | ||
* [matter](#matter) | ||
* [matter.read](#matterread) | ||
* [matter.exists](#matterexists) | ||
* [matter.extend](#matterextend) | ||
* [matter.recontruct](#matterrecontruct) | ||
* [matter.stringify](#matterstringify) | ||
* [matter.stringifyYAML](#matterstringifyyaml) | ||
* [API](#api) | ||
* [.read](#read) | ||
* [.exists](#exists) | ||
* [.extend](#extend) | ||
* [.reconstruct](#reconstruct) | ||
* [.toJSON](#tojson) | ||
* [.toYAML](#toyaml) | ||
* [Options](#options) | ||
* [lang](#lang) | ||
* [delims](#delims) | ||
* [autodetect](#autodetect) | ||
* [options.eval](#optionseval) | ||
* [options.lang](#optionslang) | ||
* [options.delims](#optionsdelims) | ||
* [options.autodetect](#optionsautodetect) | ||
* [Examples](#examples) | ||
* [matter](#matter) | ||
* [matter.extend](#matterextend) | ||
* [.extend](#extend) | ||
* [Why?](#why) | ||
@@ -40,4 +56,6 @@ * [Authors](#authors) | ||
<!-- toc stop --> | ||
## Install | ||
Install with [npm](npmjs.org) | ||
#### Install with [npm](npmjs.org) | ||
@@ -47,3 +65,3 @@ ```bash | ||
``` | ||
Install with [bower](https://github.com/bower/bower) | ||
#### Install with [bower](https://github.com/bower/bower) | ||
@@ -55,12 +73,14 @@ ```bash | ||
## Usage | ||
```js | ||
var matter = require('gray-matter'); | ||
matter(String, Object); | ||
console.log(matter('---\ntitle: foo\n---\nbar'); | ||
//=> {data: {title: 'foo'}, content: 'bar', orig: '---\ntitle: foo\n---\nbar'} | ||
``` | ||
## Methods | ||
### matter | ||
By default the `matter()` method expects a string. So this: | ||
## API | ||
`matter()` method expects a string and returns and object: | ||
```js | ||
@@ -80,3 +100,3 @@ matter(str); | ||
### matter.read | ||
### .read | ||
@@ -98,3 +118,3 @@ Read a file from the file system before parsing. | ||
### matter.exists | ||
### .exists | ||
@@ -107,3 +127,3 @@ Returns `true` or `false` if front matter exists: | ||
### matter.extend | ||
### .extend | ||
@@ -116,3 +136,3 @@ Extend and stringify **YAML** front matter. Takes an object as the second parameter, and returns either the extended, stringified object (YAML), or if no front matter is found an empty string is returned. | ||
### matter.recontruct | ||
### .reconstruct | ||
@@ -122,6 +142,6 @@ A convenience wrapper around the `matter` and `matter.extend`. Extends YAML front matter, then re-assembles front matter with the content of the file. | ||
```js | ||
matter.recontruct(str, obj); | ||
matter.reconstruct(str, obj); | ||
``` | ||
### matter.stringify | ||
### .toJSON | ||
@@ -131,7 +151,7 @@ A convenience wrapper around the `matter(str).data` method. | ||
```js | ||
matter.stringify(str); | ||
matter.toJSON(str); | ||
``` | ||
### matter.stringifyYAML | ||
### .toYAML | ||
@@ -141,9 +161,17 @@ Stringify parsed front matter back to YAML. | ||
```js | ||
matter.stringifyYAML(str); | ||
matter.toYAML(str); | ||
``` | ||
## Options | ||
> All methods will accept an options object to be passed as a second parameter | ||
### lang | ||
### options.eval | ||
Type: `Boolean` | ||
Default: `false` | ||
Evaluate coffee-script, CSON or JavaScript in front-matter. If you aren't aware of the dangers, google is your friend. | ||
### options.lang | ||
Type: `String` | ||
@@ -154,8 +182,11 @@ | ||
The parser to use on the extracted front matter. Valid options include: | ||
* `yaml` | ||
* `json` | ||
* `coffee` requires the [`coffee-script`](https://www.npmjs.org/package/coffee-script) package | ||
* `toml` requires the [`toml`](https://www.npmjs.org/package/toml) package | ||
* `coffee` | ||
* `cson` | ||
* `toml` | ||
* `js`|`javascript` | ||
### delims | ||
### options.delims | ||
Type: `Object` | ||
@@ -183,3 +214,4 @@ | ||
### autodetect | ||
### options.autodetect | ||
Type: `Boolean` | ||
@@ -200,8 +232,8 @@ | ||
[%= user %] | ||
[%= reverse(user) %] | ||
{%= user %} | ||
{%= reverse(user) %} | ||
``` | ||
## Examples | ||
### matter | ||
@@ -247,3 +279,3 @@ Let's say our page, `foo.html` contains | ||
### matter.extend | ||
### .extend | ||
@@ -278,2 +310,3 @@ Given this page: | ||
## Why? | ||
@@ -286,25 +319,20 @@ > Why another YAML Front Matter library? | ||
* Allow custom delimiters | ||
* Use a dependable and well-supported library for parsing YAML | ||
* Don't fail if YAML front matter exists, but no content | ||
* Don't fail if content exists, but no YAML front matter | ||
* Use a dependable and well-supported library for parsing YAML and other languages | ||
* Don't fail when no content exists | ||
* Don't fail when no front matter exists | ||
* Have no problem reading YAML files directly | ||
* Have no problem with complex content, including fenced code blocks containing examples of YAML front matter. | ||
* Have no problem with complex content, including fenced code blocks that contain examples of YAML front matter. Other parsers fail on this. | ||
* Should return an object that contains the parsed YAML front matter and content, as well as the "original" content. | ||
## Authors | ||
**Jon Schlinkert** | ||
+ [github/assemble](https://github.com/assemble) | ||
+ [twitter/assemble](http://twitter.com/assemble) | ||
+ [github/jonschlinkert](https://github.com/jonschlinkert) | ||
+ [twitter/jonschlinkert](http://twitter.com/jonschlinkert) | ||
**Brian Woodward** | ||
+ [github/doowb](https://github.com/doowb) | ||
+ [twitter/doowb](http://twitter.com/doowb) | ||
## License | ||
Copyright (c) 2014 Jon Schlinkert, Brian Woodward, contributors. | ||
Copyright (c) 2014 Jon Schlinkert, contributors. | ||
Released under the MIT license | ||
@@ -314,2 +342,7 @@ | ||
_This file was generated by [verb-cli](https://github.com/assemble/verb-cli) on May 19, 2014._ | ||
_This file was generated by [verb-cli](https://github.com/assemble/verb-cli) on August 29, 2014._ | ||
[js-yaml]: https://github.com/nodeca/js-yaml | ||
[coffee-script]: https://github.com/jashkenas/coffeescript | ||
[toml-node]: https://github.com/BinaryMuse/toml-node |
---cson | ||
title: 'autodetect-CSON' | ||
user: 'jonschlinkert' | ||
--- | ||
Content |
@@ -1,8 +0,8 @@ | ||
;;; json | ||
---json | ||
{ | ||
"title": "JSON", | ||
"title": "autodetect-JSON", | ||
"description": "Front Matter" | ||
} | ||
;;; | ||
--- | ||
# This page has JSON front matter! |
--- | ||
title: autodetect-no-lang | ||
user: jonschlinkert | ||
--- | ||
Content |
--- toml | ||
[data] | ||
title = "autodetect-TOML" | ||
[props] | ||
user = "jonschlinkert" | ||
--- | ||
Content |
---yaml | ||
title: autodetect-yaml | ||
user: jonschlinkert | ||
--- | ||
Content |
Sorry, the diff of this file is not supported yet
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Major refactor
Supply chain riskPackage has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.
Found 1 instance in 1 package
Uses eval
Supply chain riskPackage uses dynamic code execution (e.g., eval()), which is a dangerous practice. This can prevent the code from running in certain environments and increases the risk that the code may contain exploits or malicious behavior.
Found 1 instance in 1 package
Filesystem access
Supply chain riskAccesses the file system, and could potentially read sensitive data.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Filesystem access
Supply chain riskAccesses the file system, and could potentially read sensitive data.
Found 1 instance in 1 package
No bug tracker
MaintenancePackage does not have a linked bug tracker in package.json.
Found 1 instance in 1 package
4
57
332
51691
6
796
14
2
+ Addedcoffee-script@^1.8.0
+ Addedtoml@^2.0.6
+ Addedarray-flatten@2.1.2(transitive)
+ Addedarrayify-compact@0.1.1(transitive)
+ Addedcoffee-script@1.12.7(transitive)
+ Addeddelims@0.3.0(transitive)
+ Addedtoml@2.3.6(transitive)
+ Addedxtend@3.0.0(transitive)
- Removedfs-utils@^0.4.3
- Removedargparse@0.1.16(transitive)
- Removedasync@0.6.2(transitive)
- Removeddelims@0.1.4(transitive)
- Removedesprima@1.0.4(transitive)
- Removedfs-utils@0.4.3(transitive)
- Removedglob@3.2.11(transitive)
- Removedglobule@0.2.0(transitive)
- Removedgraceful-fs@2.0.3(transitive)
- Removedinherits@2.0.4(transitive)
- Removedjs-yaml@3.0.2(transitive)
- Removedlru-cache@2.7.3(transitive)
- Removedminimatch@0.2.140.3.0(transitive)
- Removedmkdirp@0.3.5(transitive)
- Removedrimraf@2.2.8(transitive)
- Removedsigmund@1.0.1(transitive)
- Removedunderscore@1.7.0(transitive)
- Removedunderscore.string@2.4.0(transitive)
Updateddelims@^0.3.0
Updatedjs-yaml@^3.2.1