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.
npm:
npm install unified
unified is also available as an AMD, CommonJS, and globals module, uncompressed and compressed.
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
});
-
remark — Markdown processor powered by plugins.
-
retext — Extensible system for analysing and manipulating natural language.
-
hast — HTML processor powered by plugins.
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);
Create a new Processor
constructor.
Parameters — options
(Object
):
-
name
(string
) — Unique namespace, e.g.'mdast'
or'retext'
. -
data
(Object
, optional) —JSON.stringify
able dictionary providing information toParser
,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 afile
,settings
, and the processor.Parser
instances must have aparse
method which returns anode
(an object with atype
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 afile
,settings
, and the processor.Compiler
instances must have acompile
method which returns astring
.The syntax tree representation of a file can be accessed by executing
file.namespace(name).tree
.
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 asProcessor.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
.
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.
Parser
s must have a parse
method, Compiler
s a compile
method.
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 aplugin
, and further values areinput
; -
matrix
(Array
) — Matrix where each entry is alist
. -
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 use
d, 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 wasuse
d;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 bothnext
,transformer
may finish asynchronous, and must invokenext()
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 byparse()
;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 byparse()
;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;
JSON.stringify
able dictionary providing information to Parser
, Compiler
,
and plug-ins. Cloned when a Processor
is constructed and to processor.data
.
Type: Object
, optional.