Text processing framework: Parse / Transform / Compile.

This library provides the boilerplate to make parsing and compiling pluggable.

npm:

npm install unified

unified is also available for bower, component, and duo, and as an AMD, CommonJS, and globals module, uncompressed and compressed.

From mdast:

var unified = require('unified'); var Parser = require('./lib/parse.js'); var Compiler = require('./lib/stringify.js'); module.exports = unified({ 'name': 'mdast', 'type': 'ast', 'Parser': Parser, 'Compiler': Compiler });

• API

  • unified(options)

  • Processor([processor])

  • 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)

• License

Create a new Processor constructor.

Parameters — options (Object):

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

• type (string) — Type of the produced syntax tree. For example, mdast uses an 'ast' (Abstract Syntax Tree), whereas retext uses a 'cst' (Concrete Syntax Tree).

  Used to store the syntax tree after parsing on the file (at file.namespace(name)[type]).

• Parser (Function) — Constructor which transforms a virtual file into a syntax tree. When input is parsed, this function will be constructed with a file and settings. Parser instances should 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 and settings. Compiler instances should have a compile method which returns a string.

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

Returns — Function (Processor constructor).

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.

Change the way the processor works by using a plugin.

Signatures

• unified = unified.use(plugin[, input...]);
• unified = unified.use(plugins).

Parameters

• plugin (Function) — Plugin.
• plugins (Array.<Function>) — List of plugins.
• input (*) — Passed to plugin. Specified by its documentation.

Returns

Processor — this (the context object).

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”.

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).

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.

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).

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.

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;

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.

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;

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;

MIT © Titus Wormer