Add engine specific delimiters

.verb.md

@@ -55,7 +55,7 @@ Into an object like this:
 
 **Why did we create gray-matter in the first place?**
 
-We created gray-matter after trying out other libraries that failed to meet our standards and requirements. 
+We created gray-matter after trying out other libraries that failed to meet our standards and requirements.
 
 Some libraries met most of the requirements, but _none met all of them_.
 
@@ -71,7 +71,7 @@ Some libraries met most of the requirements, but _none met all of them_.
 * Have no problem reading YAML files directly
 * Have no problem with complex content, including **non-front-matter** fenced code blocks that contain examples of YAML front matter. Other parsers fail on this.
 * Support stringifying back to front-matter. This is useful for linting, updating properties, etc.
-* Allow custom delimiters, when it's necessary for avoiding delimiter collision. 
+* Allow custom delimiters, when it's necessary for avoiding delimiter collision.
 * Should return an object with at least these three properties:
  - `data`: the parsed YAML front matter, as a JSON object
  - `content`: the contents as a string, without the front matter
@@ -137,6 +137,7 @@ In addition, the following non-enumberable properties are added to the object to
 - `file.language` **{String}**: the front-matter language that was parsed. `yaml` is the default
 - `file.matter` **{String}**: the _raw_, un-parsed front-matter string
 - `file.stringify` **{Function}**: [stringify](#stringify) the file by converting `file.data` to a string in the given language, wrapping it in delimiters and prepending it to `file.content`.
+- `file.delimiters` **{Array}**: The delimiters which surrounded the front-matter, stored as `[<open>, <close>]`. Will be `null` if there was no front-matter.
 
 
 ## Run the examples
@@ -275,7 +276,7 @@ Define custom engines for parsing and/or stringifying front-matter.
 
 **Engine format**
 
-Engines may either be an object with `parse` and (optionally) `stringify` methods, or a function that will be used for parsing only.
+Engines may either be an object with `parse` and (optionally) `stringify` method and `delimiters`, or a function that will be used for parsing only.
 
 **Examples**
 
@@ -300,7 +301,7 @@ const file = matter(str, {
  engines: {
  toml: {
  parse: toml.parse.bind(toml),
-
+ delimiters: '+++',
  // 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() {
@@ -363,6 +364,24 @@ categories = "front matter toml"
 This is content
 ```
 
+If you provide the `delimiters` property to a custom engine, then gray-matter will use that to detect the language. For example using `+++` to detect TOML.
+
+```js
+const str = `+++
+title = "My post"
+tags = ["random"]
++++
+Content goes here.
+`;
+const file = matter(str, {
+ engines: {
+ toml: {
+ parse: toml.parse.bind(toml),
+ delimiters: '+++',
+ }
+ }
+});
+```
 
 ### options.delimiters
 

examples/toml-custom.js

@@ -0,0 +1,26 @@
+const matter = require('..');
+const toml = require('toml');
+
+/**
+ * Parse TOML front-matter
+ */
+
+const str = [
+ '+++',
+ 'title = "TOML"',
+ 'description = "Front matter"',
+ 'categories = ["front", "matter", "toml"]',
+ '+++',
+ 'This is content'
+].join('\n');
+
+const file = matter(str, {
+ engines: {
+ toml: {
+ parse: toml.parse.bind(toml),
+ delimiters: '+++'
+ }
+ }
+});
+
+console.log(file);

gray-matter.d.ts

@@ -42,10 +42,11 @@ declare namespace matter {
  excerpt?: string
  orig: Buffer | I
  language: string
+ delimiters: [string, string]
  matter: string
  stringify(lang: string): string
  }
- 
+
  /**
  * Stringify an object to YAML or the specified language, and
  * append it to the given string. By default, only YAML and JSON
@@ -108,7 +109,7 @@ declare namespace matter {
  export function language<O extends matter.GrayMatterOption<string, O>>(
  str: string,
  options?: GrayMatterOption<string, O>
- ): { name: string; raw: string }
+ ): { name: string; raw: string; delimiters: null | [string, string] }
 }
 
 export = matter

index.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const sections = require('section-matter');
 const defaults = require('./lib/defaults');
+const delimiters = require('./lib/delimiters');
 const stringify = require('./lib/stringify');
 const excerpt = require('./lib/excerpt');
 const engines = require('./lib/engines');
@@ -56,39 +57,30 @@ function matter(input, options) {
 
 function parseMatter(file, options) {
  const opts = defaults(options);
- const open = opts.delimiters[0];
- const close = '\n' + opts.delimiters[1];
  let str = file.content;
 
  if (opts.language) {
  file.language = opts.language;
  }
 
- // get the length of the opening delimiter
- const openLen = open.length;
- if (!utils.startsWith(str, open, openLen)) {
- excerpt(file, opts);
- return file;
+ const language = matter.language(str, opts);
+ if (language.name) {
+ file.language = language.name;
  }
 
- // if the next character after the opening delimiter is
- // a character from the delimiter, then it's not a front-
- // matter delimiter
- if (str.charAt(openLen) === open.slice(-1)) {
+ if (!language.delimiters) {
+ excerpt(file, opts);
  return file;
  }
 
+ file.delimiters = language.delimiters;
+
+ const close = '\n' + file.delimiters[1];
+
  // strip the opening delimiter
- str = str.slice(openLen);
+ str = str.slice(language.raw.length);
  const len = str.length;
 
- // use the language defined after first delimiter, if it exists
- const language = matter.language(str, opts);
- if (language.name) {
- file.language = language.name;
- str = str.slice(language.raw.length);
- }
-
  // get the index of the closing delimiter
  let closeIndex = str.indexOf(close);
  if (closeIndex === -1) {
@@ -183,10 +175,10 @@ matter.read = function(filepath, options) {
 };
 
 /**
- * Returns true if the given `string` has front matter.
+ * Returns true if the given `string` has default front matter.
  * @param {String} `string`
  * @param {Object} `options`
- * @return {Boolean} True if front matter exists.
+ * @return {Boolean} True if default front matter exists.
  * @api public
  */
 
@@ -205,15 +197,32 @@ matter.test = function(str, options) {
 matter.language = function(str, options) {
  const opts = defaults(options);
  const open = opts.delimiters[0];
+ let raw, name, delims;
 
- if (matter.test(str)) {
- str = str.slice(open.length);
+ if (!matter.test(str, options)) {
+ return delimiters(str, options);
+ }
+ // if the next character after the opening delimiter is
+ // a character from the delimiter, then it's not a front-
+ // matter delimiter
+ if (str.charAt(open.length) === open.slice(-1)) {
+ return {
+ raw: '',
+ name: '',
+ delimiters: null
+ };
  }
+ str = str.slice(open.length);
+ name = str.slice(0, str.search(/\r?\n/));
+ raw = open + name;
+ name = name.trim();
+ delims = opts.delimiters;
+ delims[0] = open + name;
 
- const language = str.slice(0, str.search(/\r?\n/));
  return {
- raw: language,
- name: language ? language.trim() : ''
+ raw,
+ name,
+ delimiters: delims
  };
 };
 

lib/delimiters.js

@@ -0,0 +1,49 @@
+const defaults = require('./defaults');
+const utils = require('./utils');
+
+module.exports = function(str, options) {
+ const opts = defaults(options);
+ const dlen = str.search(/\r?\n/);
+ let raw, name, delimiters;
+ if (dlen > 0) {
+ const customDelims = mapCustomDelimiters(opts);
+ raw = str.substr(0, dlen);
+ const firstLine = raw.trim();
+ if (customDelims[firstLine]) {
+ name = customDelims[firstLine];
+ delimiters = utils.arrayify(opts.engines[name].delimiters);
+ if (delimiters.length === 1) {
+ delimiters.push(delimiters[0]);
+ }
+ return {
+ raw: raw || '',
+ name: name || '',
+ delimiters
+ };
+ }
+ }
+
+ // No frontmatter
+ return {
+ raw: '',
+ name: '',
+ delimiters: null
+ };
+};
+
+function mapCustomDelimiters(opts) {
+ const customDelims = {};
+ for (const engine in opts.engines) {
+ if (opts.engines[engine].delimiters) {
+ const delims = utils.arrayify(opts.engines[engine].delimiters);
+ if (customDelims[delims[0]]) {
+ throw new Error('Another engine has already used delimiter: ' + delims[0]);
+ }
+ if (delims[0] === opts.delimiters[0]) {
+ throw new Error('Engine specific delimiters cannot match the default delimiters: ' + opts.delimiters[0]);
+ }
+ customDelims[delims[0]] = engine;
+ }
+ }
+ return customDelims;
+}

lib/stringify.js

@@ -33,8 +33,9 @@ module.exports = function(file, data, options) {
  }
 
  data = Object.assign({}, file.data, data);
- const open = opts.delimiters[0];
- const close = opts.delimiters[1];
+ file.delimiters = file.delimiters || [];
+ const open = file.delimiters[0] || opts.delimiters[0];
+ const close = file.delimiters[1] || opts.delimiters[1];
  const matter = engine.stringify(data, options).trim();
  let buf = '';
 

lib/to-file.js

@@ -27,6 +27,7 @@ module.exports = function(file) {
  // set non-enumerable properties on the file object
  utils.define(file, 'orig', utils.toBuffer(file.content));
  utils.define(file, 'language', file.language || '');
+ utils.define(file, 'delimiters', file.delimiters || ['', '']);
  utils.define(file, 'matter', file.matter || '');
  utils.define(file, 'stringify', function(data, options) {
  if (options && options.language) {

test/matter.language.js

@@ -13,31 +13,37 @@ var matter = require('..');
 describe('.language', function() {
  it('should detect the name of the language to parse', function() {
  assert.deepEqual(matter.language('---\nfoo: bar\n---'), {
- raw: '',
- name: ''
+ raw: '---',
+ name: '',
+ delimiters: ['---', '---']
  });
  assert.deepEqual(matter.language('---js\nfoo: bar\n---'), {
- raw: 'js',
- name: 'js'
+ raw: '---js',
+ name: 'js',
+ delimiters: ['---js', '---']
  });
  assert.deepEqual(matter.language('---coffee\nfoo: bar\n---'), {
- raw: 'coffee',
- name: 'coffee'
+ raw: '---coffee',
+ name: 'coffee',
+ delimiters: ['---coffee', '---']
  });
  });
 
  it('should work around whitespace', function() {
  assert.deepEqual(matter.language('--- \nfoo: bar\n---'), {
- raw: ' ',
- name: ''
+ raw: '--- ',
+ name: '',
+ delimiters: ['---', '---']
  });
  assert.deepEqual(matter.language('--- js \nfoo: bar\n---'), {
- raw: ' js ',
- name: 'js'
+ raw: '--- js ',
+ name: 'js',
+ delimiters: ['---js', '---']
  });
  assert.deepEqual(matter.language('--- coffee \nfoo: bar\n---'), {
- raw: ' coffee ',
- name: 'coffee'
+ raw: '--- coffee ',
+ name: 'coffee',
+ delimiters: ['---coffee', '---']
  });
  });
 });

test/parse-toml.js

@@ -45,4 +45,19 @@ describe('parse TOML:', function() {
  matter('---toml\n[props\nuser = "jonschlinkert"\n---\nContent\n');
  });
  });
+
+ it('should auto-detect TOML with custom delimiters.', function() {
+ var actual = parse('+++\ntitle = "autodetect-TOML-custom-delims"\n[props]\nuser = "jonschlinkert"\n+++\nContent\n', {
+ engines: {
+ toml: {
+ parse: toml.parse.bind(toml),
+ delimiters: '+++'
+ }
+ }
+ });
+ assert.equal(actual.data.title, 'autodetect-TOML-custom-delims');
+ assert(actual.hasOwnProperty('data'));
+ assert(actual.hasOwnProperty('content'));
+ assert(actual.hasOwnProperty('orig'));
+ });
 });

test/stringify.js

@@ -51,6 +51,28 @@ describe('.stringify', function() {
  ].join('\n'));
  });
 
+ it('should stringify a file object with custom delimiters', function() {
+ var file = { content: 'Name: {{name}}', data: {name: 'gray-matter'}, delimiters: ['+++', '+++'] };
+ var actual = matter.stringify(file);
+ assert.equal(actual, [
+ '+++',
+ 'name: gray-matter',
+ '+++',
+ 'Name: {{name}}\n'
+ ].join('\n'));
+ });
+
+ it('should stringify a file object with extra language info', function() {
+ var file = { content: 'Name: {{name}}', data: {name: 'gray-matter'}, delimiters: ['---toml', '---'] };
+ var actual = matter.stringify(file);
+ assert.equal(actual, [
+ '---toml',
+ 'name: gray-matter',
+ '---',
+ 'Name: {{name}}\n'
+ ].join('\n'));
+ });
+
  it('should stringify an excerpt', function() {
  var file = { content: 'Name: {{name}}', data: {name: 'gray-matter'} };
  file.excerpt = 'This is an excerpt.';