flexible front matter parser
JavaScript
Latest commit c004fc8 Sep 24, 2013 @justinvdm Bump version (0.1.1 -> 0.2.0) after API change to pass along the actu…
…al file data for inFile()
Permalink
Failed to load latest commit information.
src
test
.gitignore
.jshintrc
Gruntfile.js
LICENSE
README.md
index.js
package.json

README.md

matter

Flexible front matter parser.

matter.yaml('---\nfoo: bar\n---');
// => {foo: 'bar'}

matter.yaml.inFile('./stuff.md', function(err, metadata) {
  // ...
});

matter.json('---\n{"foo": "bar"}\n---');
// => {foo: 'bar'}

matter.json.inFile('./stuff.md', function(err, metadata) {
  // ...
});

What can it do?

  • Parse front matters embedded in comments (or any configurable tokens)
  • Allow custom parsers to be plugged in
  • Keep the parsing as configurable as possible

API

matter.yaml(string, [options])

Alias to matter.parse.yaml.

console.log(matter.yaml('---\nfoo: bar\n---'));
// => {foo: 'bar'}

matter.yaml.inFile(filepath, [options], callback)

Alias to matter.parse.yaml.inFile.

matter.yaml.inFile('./stuff.md', function(err, metadata, data) {
  if (!err) {
    console.log(metadata);
  };
});

matter.json(string, [options])

Alias to matter.parse.json.

console.log(matter.json('---\n{"foo": "bar"}\n---'));
// => {foo: 'bar'}

matter.json.inFile(filepath, [options], callback)

Alias to matter.parse.json.inFile.

matter.json.inFile('./stuff.md', function(err, metadata, data) {
  if (!err) {
    console.log(metadata);
  };
});

matter.parse.<parserName>(string, [options])

  • string: A string containing the front matter to be parsed
  • options: An object of options
    • ignore: A regex or string representing tokens to be ignored when extracting the front matter. Used to extract the front matter. The tokens ignored by default are //, /*, */, #.
    • indicator (default=/---/): A regex or string to use as the front matter head and tail indicators
    • indicators: An object of options to use for the front matter head and tail indicators:
      • head: A regex or string to use as the front matter's head indicator. Defaults to indicator's value.
      • tail: A regex or string to use as the front matter's tail indicator. Defaults to indicators's value

Parses a string containing a front matter using the parser registered as parserName.

console.log(matter.parse.yaml('---\nfoo: bar\n---'));
// => {foo: 'bar'}

matter.parse.<parserName>.inFile(filepath, [options], callback)

  • filename: A relative or absolute path to the file with the front matter to be parsed
  • options: An object of options:
    • encoding (default='utf8'): The encoding to be used when reading the file
    • ignore: A regex or string representing tokens to be ignored when extracting the front matter. Used to extract the front matter. The tokens ignored by default are //, /*, */, #.
    • indicator (default=/---/): A regex or string to use as the front matter head and tail indicators
    • indicators: An object of options to use for the front matter head and tail indicators:
      • head: A regex or string to use as the front matter's head indicator. Defaults to indicator's value.
      • tail: A regex or string to use as the front matter's tail indicator. Defaults to indicators's value
    • [fs.readFile options]
  • callback(err, metadata, data): A function to be called when the file has been read and the front matter has been parsed.
    • err: An error object for an error which may have occured while reading and parsing the file. null if no error occured.
    • metadata: An object containing the extracted and parsed front matter data
    • data: A string of the actual data contained in the file

Parses a file containing a front matter using the parser registered as parserName.

matter.parse.yaml.inFile('./stuff.md', function(err, metadata, data) {
  if (!err) {
    console.log(metadata);
  };
});

matter.parsers.register(name, fn)

  • name: The name of the parser. Once registered, the parser becomes a property of matter.parse.
  • fn(data): The function to convert the extracted front matter string into a JSON object.
    • data: A string containing the extracted front matter data. matter tries clean the data up as best it can without breaking the format.

Registers a new front matter parser.

matter.parsers.register('odd', function(data) {
  var obj = {};

  data
    .split(',')
    .map(function(kv) {
      kv = kv.split('=');
      obj[kv[0]] = kv[1];
    });

  return obj;
});

console.log(matter.parse.odd('---\nfoo=bar,baz=qux\n---\n'));
// => {foo: 'bar', baz: 'qux'});

matter.parsers.unregister(name)

  • name: The name of the parser to unregister.

Unregisters a parser.

matter.parsers.unregister('odd');

matter.parsers.defaults(overrides)

  • overrides: An object containing the new defaults. matter uses the following defaults:
    • encoding (default='utf8'): The encoding to be used when reading files
    • ignore: A regex or string representing tokens to be ignored when extracting the front matter. Used to extract the front matter. The tokens ignored by default are //, /*, */, #.
    • indicator (default=/---/): A regex or string to use as the front matter head and tail indicators
    • indicators: An object of options to use for the front matter head and tail indicators:
      • head: A regex or string to use as the front matter's head indicator. Defaults to indicator's value.
      • tail: A regex or string to use as the front matter's tail indicator. Defaults to indicators's value

Sets new defaults for parsing.

matter.parsers.defaults({ignore: /!/g});

matter.parsers.defaults()

Returns a shallow copy of the parsing defaults.

console.log(matter.parsers.defaults());