@zkochan/unified

unified

Text processing framework: Parse / Transform / Compile.

This library provides the boilerplate to make parsing and compiling pluggable. It’s in use by remark, retext, and hast.

Installation

npm:

npm install unified

unified is also available as an AMD, CommonJS, and globals module, uncompressed and compressed.

Usage

From remark:

var unified = require('unified');
var Parser = require('./lib/parse.js');
var Compiler = require('./lib/stringify.js');

module.exports = unified({
    'name': 'mdast',
    'Parser': Parser,
    'Compiler': Compiler
});

Table of Contents

• List of Processors

• Bridges

• API

  • unified(options)

  • Processor([processor])

  • processor.Parser

  • processor.Compiler

  • Processor#use(plugin[, input...])

    • Plugin
    • function attacher(processor[, input...])
    • function transformer(node, file[, next])

  • Processor#parse(file[, options])

  • Processor#run(node[, file][, done])

    • function done(err, node, file)

  • Processor#stringify(node[, file][, options])

  • Processor#process(file[, options][, done])

    • function done(err, doc, file)

  • Processor#data

• License

List of Processors

• remark — Markdown processor powered by plugins.

• retext — Extensible system for analysing and manipulating natural language.

• hast — HTML processor powered by plugins.

Bridges

Bridges are a concept which support two-way transformation between processors. See unified-bridge for more information.

• remark-retext — Transformation from markdown to natural language (currently it’s not possible to return to markdown);

API

unified(options)

Create a new Processor constructor.

Parameters — options (Object):

• name (string) — Unique namespace, e.g. 'mdast' or 'retext'.

• data (Object, optional) — JSON.stringifyable dictionary providing information to Parser, Compiler, and plug-ins.

• Parser (Function) — Constructor which transforms a virtual file into a syntax tree. When input is parsed, this function will be constructed with a file, settings, and the processor. Parser instances must have a parse method which returns a node (an object with a type property).

  The string representation of a file can be accessed by executing file.toString();.

• Compiler (Function) — Constructor which transforms a node into a string. When input is compiled, this function will be constructed with a file, settings, and the processor. Compiler instances must have a compile method which returns a string.

  The syntax tree representation of a file can be accessed by executing file.namespace(name).tree.

Returns — Function (Processor constructor).

Processor([processor])

Note that all methods on the instance are also available as functions on the constructor, which, when invoked, create a new instance.

Thus, invoking new Processor().process() is the same as Processor.process().

Create a new Processor instance.

Parameters

• processor (Processor, optional) — Uses all plug-ins available on the reference processor instance, on the newly constructed processor instance.

Returns

Processor.

processor.Parser

processor.Compiler

The constructors passed to unified at 'Parser' and 'Compiler' are stored on Processor instances. The Parser is responsible for parsing a virtual file into a syntax tree, and the Compiler for compiling a syntax tree into something else.

When a processor is constructed, both are passed to unherit, which ensures that plug-ins can change how the processor instance parses and compiles without affecting other processors.

Parsers must have a parse method, Compilers a compile method.

Processor#use(plugin[, input...])

Change the way the processor works by using a plugin.

Signatures

• processor.use(plugin[, input...]);
• processor.use(plugins[, input...]);
• processor.use(list);
• processor.use(matrix).

Parameters

• plugin (Function) — Plugin.

• plugins (Array.<Function>) — List of plugins.

• list (Array) — List where the first value is a plugin, and further values are input;

• matrix (Array) — Matrix where each entry is a list.

• input (*) — Passed to plugin. Specified by its documentation.

Returns

Processor — this (the context object).

Plugin

A uniware plugin changes the way the applied-on processor works. It does two things:

• It modifies the instance: such as changing the Parser or the Compiler;
• It transforms a syntax tree representation of a file.

Both have their own function. The first is called an “attacher”. The second is named a “transformer”. An “attacher” may return a “transformer”.

function attacher(processor[, input...])

To modify the processor, create an attacher. An attacher is the thing passed to use. It can receive plugin specific options, but that’s entirely up to the third-party developer.

An attacher is invoked when the plugin is used, and can return a transformer which will be called on subsequent process()s and run()s.

Signatures

• transformer? = attacher(processor[, input...]).

Parameters

• processor (Processor) — Context on which the plugin was used;
• input (*) — Passed by the user of a plug-in.

Returns

transformer (optional).

function transformer(node, file[, next])

To transform a syntax tree, create a transformer. A transformer is a simple (generator) function which is invoked each time a file is process()s and run()s. A transformer should change the syntax tree representation of a file.

Signatures

• err? = transformer(node, file);
• transformer(node, file, next);
• Promise.<null, Error> = transformer(node, file);
• transformer*(node, file).

Parameters

• node (Node) — Syntax tree representation of a file;

• file (VFile) — Virtual file;

• next (function([err]), optional) — If the signature includes both next, transformer may finish asynchronous, and must invoke next() on completion with an optional error.

Returns — Optionally:

• Error — Exception which will be thrown;

• Promise.<null, Error> — Promise which must be resolved or rejected on completion.

Processor#parse(file[, options])

Parse a document into a syntax tree.

When given a file, stores the returned node on that file.

Signatures

• node = processor.parse(file|value[, options]).

Parameters

• file (VFile) — Virtual file.
• value (string) — String representation of a file.
• options (Object) — Configuration given to the parser.

Returns

Node — (Object).

Processor#run(node[, file][, done])

Transform a syntax tree by applying plug-ins to it.

Either a node or a file which was previously passed to processor.parse(), must be given.

Signatures

• node = processor.run(node[, file|value][, done]);
• node = processor.run(file[, done]).

Parameters

• node (Object) — Syntax tree as returned by parse();
• file (VFile) — Virtual file.
• value (string) — String representation of a file.
• done (function done(err, node, file)).

Returns

Node — The given syntax tree node.

Throws

When no node was given and no node was found on the file.

function done(err, node, file)

Invoked when transformation is complete.

Signatures

• function done(err);
• function done(null, node, file).

Parameters

• exception (Error) — Failure;
• doc (string) — Document generated by the process;
• file (File) — File object representing the input file;

Processor#stringify(node[, file][, options])

Compile a syntax tree into a document.

Either a node or a file which was previously passed to processor.parse(), must be given.

Signatures

• doc = processor.stringify(node[, file|value][, options]);
• doc = processor.stringify(file[, options]).

Parameters

• node (Object) — Syntax tree as returned by parse();
• file (VFile) — Virtual file.
• value (string) — String representation of a file.
• options (Object) — Configuration.

Returns

doc (string) — Document.

Throws

When no node was given and no node was found on the file.

Processor#process(file[, options][, done])

Parse / Transform / Compile. When an async transformer is used, null is returned and done must be given to receive the results upon completion.

Signatures

• doc = processor.process(file|value[, options][, done]).

Parameters

• file (File) — Virtual file;
• value (string) — String representation of a file;
• options (Object) — Configuration.
• done (function done(err?, doc?, file?)).

Returns

string — Document generated by the process;

function done(err, doc, file)

Invoked when processing is complete.

Signatures

• function done(err);
• function done(null, doc, file).

Parameters

• exception (Error) — Failure;
• doc (string) — Document generated by the process;
• file (File) — File object representing the input file;

Processor#data

JSON.stringifyable dictionary providing information to Parser, Compiler, and plug-ins. Cloned when a Processor is constructed and to processor.data.

Type: Object, optional.

License

MIT © Titus Wormer