Socket
Socket
Sign inDemoInstall

unified

Package Overview
Dependencies
Maintainers
1
Versions
57
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

unified - npm Package Compare versions

Comparing version 6.1.5 to 6.1.6

4

package.json
{
"name": "unified",
"version": "6.1.5",
"version": "6.1.6",
"description": "Pluggable text processing interface",

@@ -39,3 +39,3 @@ "license": "MIT",

"nyc": "^11.0.0",
"remark-cli": "^3.0.0",
"remark-cli": "^4.0.0",
"remark-preset-wooorm": "^3.0.0",

@@ -42,0 +42,0 @@ "tape": "^4.4.0",

402

readme.md

@@ -5,11 +5,11 @@ # ![unified][logo]

[![Coverage Status][codecov-badge]][codecov]
[![Chat][chat-badge]][chat]
**unified** is an interface for processing text using syntax trees.
It’s what powers [**remark**][remark], [**retext**][retext], and
[**rehype**][rehype], but it also allows for processing between
multiple syntaxes.
**unified** is an interface for processing text using syntax trees. It’s what
powers [**remark**][remark], [**retext**][retext], and [**rehype**][rehype],
but it also allows for processing between multiple syntaxes.
[`unifiedjs.github.io`][site], the website for **unified** provides a less
technical, more practical, introduction to unified. Make sure to visit it
and try its introductionary [Guides][].
The website for **unified**, [`unifiedjs.github.io`][site], provides a less
technical and more practical introduction to unified. Make sure to visit it
and try its introductory [Guides][].

@@ -33,3 +33,3 @@ ## Installation

var html = require('rehype-stringify');
var reporter = require('vfile-reporter');
var report = require('vfile-reporter');

@@ -43,3 +43,3 @@ unified()

.process('# Hello world!', function (err, file) {
console.error(reporter(err || file));
console.error(report(err || file));
console.log(String(file));

@@ -87,19 +87,21 @@ });

**unified** is an interface for processing text using syntax trees.
Syntax trees are a representation understandable to programs.
Those programs, called [**plug-in**][plugin]s, take these trees and
modify them, amongst other things. To get to the syntax tree from
input text, there’s a [**parser**][parser], and, to get from that
back to text, there’s a [**compiler**][compiler]. This is the
**unified** is an interface for processing text using syntax trees. Syntax
trees are a representation understandable to programs. Those programs, called
[**plugin**][plugin]s, take these trees and modify them, amongst other things.
To get to the syntax tree from input text there’s a [**parser**][parser]. To
get from that back to text there’s a [**compiler**][compiler]. This is the
[**process**][process] of a **processor**.
```ascii
┌──────────────┐
┌─ │ Transformers │ ─┐
▲ └──────────────┘ ▼
└────────┐ ┌────────┘
│ │
┌────────┐ │ │ ┌──────────┐
Input ──▶ │ Parser │ ──▶ Tree ──▶ │ Compiler │ ──▶ Output
└────────┘ └──────────┘
| ....................... process() ......................... |
| ......... parse() ..... | run() | ..... stringify() ....... |
+--------+ +----------+
Input ->- | Parser | ->- Syntax Tree ->- | Compiler | ->- Output
+--------+ | +----------+
X
|
+--------------+
| Transformers |
+--------------+
```

@@ -109,30 +111,27 @@

Every processor implements another processor. To create a new
processor, invoke another processor. This creates a processor that is
configured to function the same as its ancestor. But, when
the descendant processor is configured in the future, that
configuration does not change the ancestral processor.
Every processor implements another processor. To create a new processor invoke
another processor. This creates a processor that is configured to function the
same as its ancestor. But when the descendant processor is configured in the
future it does not affect the ancestral processor.
Often, when processors are exposed from a library (for example,
unified itself), they should not be configured directly, as that
would change their behaviour for all users. Those processors are
[**frozen**][freeze], and new processors should be made from them before
they are used, by invoking them.
When processors are exposed from a module (for example, unified itself) they
should not be configured directly, as that would change their behaviour for all
module users. Those processors are [**frozen**][freeze] and they should be
invoked to create a new processor before they are used.
###### Node
The syntax trees used in **unified** are [**Unist**][unist] nodes,
which are plain JavaScript objects with a `type` property. The
semantics of those `type`s are defined by other projects.
The syntax trees used in **unified** are [**Unist**][unist] nodes: plain
JavaScript objects with a `type` property. The semantics of those `type`s are
defined by other projects.
There are several [utilities][unist-utilities] for working with these
nodes.
There are several [utilities][unist-utilities] for working with these nodes.
###### List of Processors
The following projects process different syntax trees. They parse
text to their respective syntax tree, and they compile their syntax
trees back to text. These processors can be used as-is, or their
parsers and compilers can be mixed and matched with other plug-ins
to process between different syntaxes.
The following projects process different syntax trees. They parse text to
their respective syntax tree and they compile their syntax trees back to text.
These processors can be used as-is, or their parsers and compilers can be mixed
and matched with **unified** and other plugins to process between different
syntaxes.

@@ -143,16 +142,25 @@ * [**rehype**][rehype] ([**HAST**][hast]) — HTML

###### List of Plugins
The below plugins work with **unified**, unrelated to what flavour the syntax
tree is in:
* [`unified-diff`](https://github.com/unifiedjs/unified-diff)
— Ignore messages for unchanged lines in Travis
See [**remark**][remark-plugins], [**rehype**][rehype-plugins], and
[**retext**][retext-plugins] for lists of their plugins.
###### File
When processing documents, metadata is often gathered about that
document. [**VFile**][vfile] is a virtual file format which stores
data, and handles metadata and messages for **unified** and its
plug-ins.
When processing documents metadata is often gathered about that document.
[**VFile**][vfile] is a virtual file format which stores data and handles
metadata and messages for **unified** and its plugins.
There are several [utilities][vfile-utilities] for working with these
files.
There are several [utilities][vfile-utilities] for working with these files.
###### Configuration
To configure a processor, invoke its [`use`][use] method, supply it a
[**plug-in**][plugin], and optionally settings.
To configure a processor invoke its [`use`][use] method, supply it a
[**plugin**][plugin], and optionally settings.

@@ -162,10 +170,11 @@ ###### Integrations

**unified** can integrate with the file-system through
[**unified-engine**][engine]. On top of that, CLI apps can be created
with [**unified-args**][args], Gulp plug-ins with
[**unified-engine-gulp**][gulp], and Atom Linters with
[**unified-engine-atom**][atom].
[`unified-engine`][engine]. On top of that, CLI apps can be created with
[`unified-args`][args], Gulp plugins with [`unified-engine-gulp`][gulp], and
Atom Linters with [`unified-engine-atom`][atom].
A streaming interface is provided through [`unified-stream`][stream].
###### Programming interface
The API gives access to processing metadata (such as lint messages), and
The API gives access to processing metadata (such as lint messages) and
supports multiple passed through files:

@@ -182,3 +191,3 @@

var html = require('rehype-stringify');
var reporter = require('vfile-reporter');
var report = require('vfile-reporter');

@@ -192,3 +201,3 @@ unified()

.process('*Emphasis* and _importance_, you guys!', function (err, file) {
console.error(reporter(err || file));
console.error(report(err || file));
console.log(String(file));

@@ -198,3 +207,3 @@ });

Which yields:
Yields:

@@ -213,20 +222,19 @@ ```txt

**Bridge** mode transforms the syntax tree from one flavour (the origin)
to another (the destination). Then, transformations are applied on that
tree. Finally, the origin processor continues transforming the original
syntax tree.
**Bridge** mode transforms the syntax tree from one flavour (the origin) to
another (the destination). Then, transformations are applied on that tree.
Finally, the origin processor continues transforming the original syntax tree.
**Mutate** mode also transforms the syntax tree from one flavour to
another. But then the origin processor continues transforming the
destination syntax tree.
**Mutate** mode also transforms the syntax tree from one flavour to another.
But then the origin processor continues transforming the destination syntax
tree.
In the previous example (“Programming interface”), `remark-retext` is
used in bridge mode: the origin syntax tree is kept after retext is
finished; whereas `remark-rehype` is used in mutate mode: it sets a
new syntax tree and discards the original.
In the previous example (“Programming interface”), `remark-retext` is used in
bridge mode: the origin syntax tree is kept after retext is done; whereas
`remark-rehype` is used in mutate mode: it sets a new syntax tree and discards
the original.
* [**remark-retext**][remark-retext]
* [**remark-rehype**][remark-rehype]
* [**rehype-retext**][rehype-retext]
* [**rehype-remark**][rehype-remark]
* [`remark-retext`][remark-retext]
* [`remark-rehype`][remark-rehype]
* [`rehype-retext`][rehype-retext]
* [`rehype-remark`][rehype-remark]

@@ -241,11 +249,10 @@ ## API

`Function` — A new [**unfrozen**][freeze] processor which is
configured to function the same as its ancestor. But, when the
descendant processor is configured in the future, that configuration
does not change the ancestral processor.
`Function` — New [**unfrozen**][freeze] processor which is configured to
function the same as its ancestor. But when the descendant processor is
configured in the future it does not affect the ancestral processor.
###### Example
The following example shows how a new processor can be created (from
the remark processor) and linked to **stdin**(4) and **stdout**(4).
The following example shows how a new processor can be created (from the remark
processor) and linked to **stdin**(4) and **stdout**(4).

@@ -263,4 +270,4 @@ ```js

Configure the processor to use a [**plug-in**][plugin], and configure
that plug-in with optional options.
Configure the processor to use a [**plugin**][plugin] and optionally configure
that plugin with options.

@@ -279,4 +286,4 @@ ###### Signatures

and/or an optional `settings` object
* `list` (`Array`) — plugins, presets, and arguments (a plugin and options
in an array), in an array
* `list` (`Array`) — List of plugins, presets, and pairs (`plugin` and
`options` in an array)

@@ -294,4 +301,4 @@ ###### Returns

There are many ways to pass plugins to `.use()`. The below example
gives an overview.
There are many ways to pass plugins to `.use()`. The below example gives an
overview.

@@ -323,3 +330,3 @@ ```js

* `file` ([**VFile**][file])
* `file` ([`VFile`][file])
— Or anything which can be given to `vfile()`

@@ -329,7 +336,7 @@

[**Node**][node] — Syntax tree representation of input.
[`Node`][node] — Syntax tree representation of input.
###### Note
`parse` [freezes][freeze] the processor, if not already frozen.
`parse` [freezes][freeze] the processor if not already frozen.

@@ -339,11 +346,12 @@ #### `processor.Parser`

Function handling the parsing of text to a syntax tree. Used in the
[**parse**][parse] phase in the process and invoked with a `string`
and [**VFile**][file] representation of the document to parse.
[**parse**][parse] phase in the process and invoked with a `string` and
[`VFile`][file] representation of the document to parse.
If `Parser` is a normal parser, it should return a [`Node`][node]: the syntax
tree representation of the given file.
`Parser` can be a normal function in which case it must return a
[`Node`][node]: the syntax tree representation of the given file.
`Parser` can also be a constructor function, in which case it’s invoked with
`new`. In that case, instances should have a `parse` method, which is invoked
(without arguments), and should return a [`Node`][node].
`Parser` can also be a constructor function (a function with keys in its
`prototype`) in which case it’s invoked with `new`. Instances must have a
`parse` method which is invoked without arguments and must return a
[`Node`][node].

@@ -356,4 +364,4 @@ ### `processor.stringify(node[, file])`

* `node` ([**Node**][node])
* `file` ([**VFile**][file], optional);
* `node` ([`Node`][node])
* `file` ([`VFile`][file], optional);
— Or anything which can be given to `vfile()`

@@ -367,3 +375,3 @@

`stringify` [freezes][freeze] the processor, if not already frozen.
`stringify` [freezes][freeze] the processor if not already frozen.

@@ -374,20 +382,19 @@ #### `processor.Compiler`

[**stringify**][stringify] phase in the process and invoked with a
[`Node`][node] and [**VFile**][file] representation of the document to
stringify.
[`Node`][node] and [`VFile`][file] representation of the document to stringify.
If `Compiler` is a normal stringifier, it should return a `string`: the text
representation of the given syntax tree.
`Compiler` can be a normal function in which case it must return a `string`:
the text representation of the given syntax tree.
`Compiler` can also be a constructor function, in which case it’s invoked with
`new`. In that case, instances should have a `compile` method, which is invoked
(without arguments), and should return a `string`.
`Compiler` can also be a constructor function (a function with keys in its
`prototype`) in which case it’s invoked with `new`. Instances must have a
`compile` method which is invoked without arguments and must return a `string`.
### `processor.run(node[, file][, done])`
Transform a syntax tree by applying [**plug-in**][plugin]s to it.
Transform a syntax tree by applying [**plugin**][plugin]s to it.
###### Parameters
* `node` ([**Node**][node])
* `file` ([**VFile**][file], optional)
* `node` ([`Node`][node])
* `file` ([`VFile`][file], optional)
— Or anything which can be given to `vfile()`

@@ -398,13 +405,13 @@ * `done` ([`Function`][run-done], optional)

[**Promise**][promise], if `done` is not given. Rejected with an error,
or resolved with the resulting syntax tree.
[`Promise`][promise] if `done` is not given. Rejected with an error, or
resolved with the resulting syntax tree.
###### Note
`run` [freezes][freeze] the processor, if not already frozen.
`run` [freezes][freeze] the processor if not already frozen.
##### `function done(err[, node, file])`
Invoked when transformation is complete. Either invoked with an
error, or a syntax tree and a file.
Invoked when transformation is complete. Either invoked with an error or a
syntax tree and a file.

@@ -414,15 +421,15 @@ ###### Parameters

* `err` (`Error`) — Fatal error
* `node` ([**Node**][node])
* `file` ([**VFile**][file])
* `node` ([`Node`][node])
* `file` ([`VFile`][file])
### `processor.runSync(node[, file])`
Transform a syntax tree by applying [**plug-in**][plugin]s to it.
Transform a syntax tree by applying [**plugin**][plugin]s to it.
If asynchronous [**plug-in**][plugin]s are configured, an error is thrown.
If asynchronous [**plugin**][plugin]s are configured an error is thrown.
###### Parameters
* `node` ([**Node**][node])
* `file` ([**VFile**][file], optional)
* `node` ([`Node`][node])
* `file` ([`VFile`][file], optional)
— Or anything which can be given to `vfile()`

@@ -432,17 +439,16 @@

[**Node**][node] — The given syntax tree.
[`Node`][node] — The given syntax tree.
###### Note
`runSync` [freezes][freeze] the processor, if not already frozen.
`runSync` [freezes][freeze] the processor if not already frozen.
### `processor.process(file|value[, done])`
Process the given representation of a file as configured on the
processor. The process invokes `parse`, `run`, and `stringify`
internally.
Process the given representation of a file as configured on the processor. The
process invokes `parse`, `run`, and `stringify` internally.
###### Parameters
* `file` ([**VFile**][file])
* `file` ([`VFile`][file])
* `value` (`string`) — String representation of a file

@@ -453,13 +459,13 @@ * `done` ([`Function`][process-done], optional)

[**Promise**][promise], if `done` is not given. Rejected with an error,
or resolved with the resulting file.
[`Promise`][promise] if `done` is not given. Rejected with an error or
resolved with the resulting file.
###### Note
`process` [freezes][freeze] the processor, if not already frozen.
`process` [freezes][freeze] the processor if not already frozen.
#### `function done(err, file)`
Invoked when the process is complete. Invoked with a fatal error, if
any, and the [**VFile**][file].
Invoked when the process is complete. Invoked with a fatal error, if any, and
the [`VFile`][file].

@@ -469,3 +475,3 @@ ###### Parameters

* `err` (`Error`, optional) — Fatal error
* `file` ([**VFile**][file])
* `file` ([`VFile`][file])

@@ -481,3 +487,2 @@ ###### Example

var html = require('rehype-stringify');
var reporter = require('vfile-reporter');

@@ -515,11 +520,10 @@ unified()

Process the given representation of a file as configured on the
processor. The process invokes `parse`, `run`, and `stringify`
internally.
Process the given representation of a file as configured on the processor. The
process invokes `parse`, `run`, and `stringify` internally.
If asynchronous [**plug-in**][plugin]s are configured, an error is thrown.
If asynchronous [**plugin**][plugin]s are configured an error is thrown.
###### Parameters
* `file` ([**VFile**][file])
* `file` ([`VFile`][file])
* `value` (`string`) — String representation of a file

@@ -529,7 +533,7 @@

[**VFile**][file] — Virtual file with modified [`contents`][vfile-contents].
[`VFile`][file] — Virtual file with modified [`contents`][vfile-contents].
###### Note
`processSync` [freezes][freeze] the processor, if not already frozen.
`processSync` [freezes][freeze] the processor if not already frozen.

@@ -545,3 +549,2 @@ ###### Example

var html = require('rehype-stringify');
var reporter = require('vfile-reporter');

@@ -575,6 +578,5 @@ var processor = unified()

Get or set information in an in-memory key-value store accessible to
all phases of the process. An example is a list of HTML elements
which are self-closing (i.e., do not need a closing tag), which is
needed when parsing, transforming, and compiling HTML.
Get or set information in an in-memory key-value store accessible to all phases
of the process. An example is a list of HTML elements which are self-closing,
which is needed when parsing, transforming, and compiling HTML.

@@ -614,7 +616,7 @@ ###### Parameters

Freeze a processor. Frozen processors are meant to be extended, and not to
be configured or processed directly.
Freeze a processor. Frozen processors are meant to be extended and not to be
configured or processed directly.
Once a processor is frozen, it cannot be unfrozen. But, a new processor
functioning just like it can be created by invoking the processor.
Once a processor is frozen it cannot be unfrozen. New processors functioning
just like it can be created by invoking the processor.

@@ -631,4 +633,4 @@ It’s possible to freeze processors explicitly, by calling `.freeze()`, but

The following example, `index.js`, shows how [**rehype**][rehype]
prevents extensions to itself:
The following example, `index.js`, shows how [**rehype**][rehype] prevents
extensions to itself:

@@ -643,4 +645,3 @@ ```js

The below example, `a.js`, shows how that processor can be used and
configured.
The below example, `a.js`, shows how that processor can be used and configured.

@@ -657,6 +658,6 @@ ```js

The below example, `b.js`, shows a similar looking example which
operates on the frozen [**rehype**][rehype] interface. If this
behaviour was allowed it would result in unexpected behaviour, so
an error is thrown. **This is invalid**:
The below example, `b.js`, shows a similar looking example which operates on
the frozen [**rehype**][rehype] interface. If this behaviour was allowed it
would result in unexpected behaviour so an error is thrown. **This is
invalid**:

@@ -689,11 +690,11 @@ ```js

A **unified** plugin changes the way the applied-on processor works,
in the following ways:
**unified** plugins change the way the applied-on processor works in the
following ways:
* It modifies the [**processor**][processor]: such as changing the
parser, the compiler, or linking the processor to other processors
* It transforms the [**syntax tree**][node] representation of a file
* It modifies metadata of a file
* They modify the [**processor**][processor]: such as changing the parser,
the compiler, or linking it to other processors
* They transform [**syntax tree**][node] representation of files
* They modify metadata of files
Plug-in’s are a concept which materialise as [**attacher**][attacher]s.
Plugins are a concept. They materialise as [`attacher`][attacher]s.

@@ -732,3 +733,3 @@ ###### Example

var vfile = require('to-vfile');
var reporter = require('vfile-reporter');
var report = require('vfile-reporter');
var move = require('./move');

@@ -742,3 +743,3 @@

.process(vfile.readSync('index.md'), function (err, file) {
console.error(reporter(err || file));
console.error(report(err || file));
if (file) {

@@ -752,8 +753,8 @@ vfile.writeSync(file); // Written to `index.html`.

An attacher is the thing passed to [`use`][use]. It configures the
processor and in turn can receive options.
An attacher is the thing passed to [`use`][use]. It configures the processor
and in turn can receive options.
Attachers can configure processors, such as by interacting with parsers
and compilers, linking them to other processors, or by specifying how
the syntax tree is handled.
Attachers can configure processors, such as by interacting with parsers and
compilers, linking them to other processors, or by specifying how the syntax
tree is handled.

@@ -781,15 +782,14 @@ ###### Context

Transformers modify the syntax tree or metadata of a file.
A transformer is a function which is invoked each time a file is
passed through the transform phase. If an error occurs (either
because it’s thrown, returned, rejected, or passed to [`next`][next]),
the process stops.
Transformers modify the syntax tree or metadata of a file. A transformer is a
function which is invoked each time a file is passed through the transform
phase. If an error occurs (either because it’s thrown, returned, rejected, or
passed to [`next`][next]), the process stops.
The transformation process in **unified** is handled by [`trough`][trough],
see it’s documentation for the exact semantics of transformers.
The transformation process in **unified** is handled by [`trough`][trough], see
it’s documentation for the exact semantics of transformers.
###### Parameters
* `node` ([**Node**][node])
* `file` ([**VFile**][file])
* `node` ([`Node`][node])
* `file` ([`VFile`][file])
* `next` ([`Function`][next], optional)

@@ -800,13 +800,12 @@

* `Error` — Can be returned to stop the process
* [**Node**][node] — Can be returned and results in further
transformations and `stringify`s to be performed on the new
tree
* `Promise` — If a promise is returned, the function is asynchronous,
and **must** be resolved (optionally with a [**Node**][node]) or
rejected (optionally with an `Error`)
* [`Node`][node] — Can be returned and results in further transformations
and `stringify`s to be performed on the new tree
* `Promise` — If a promise is returned, the function is asynchronous, and
**must** be resolved (optionally with a [`Node`][node]) or rejected
(optionally with an `Error`)
#### `function next(err[, tree[, file]])`
If the signature of a transformer includes `next` (third argument),
the function **may** finish asynchronous, and **must** invoke `next()`.
If the signature of a transformer includes `next` (third argument), the
function **may** finish asynchronous, and **must** invoke `next()`.

@@ -816,10 +815,9 @@ ###### Parameters

* `err` (`Error`, optional) — Stop the process
* `node` ([**Node**][node], optional) — New syntax tree
* `file` ([**VFile**][file], optional) — New virtual file
* `node` ([`Node`][node], optional) — New syntax tree
* `file` ([`VFile`][file], optional) — New virtual file
## `Preset`
A **unified** preset provides a potentially sharable way to configure
processors. They can contain multiple plugins and optionally settings as
well.
Presets provide a potentially sharable way to configure processors. They can
contain multiple plugins and optionally settings as well.

@@ -847,3 +845,3 @@ ###### Example

var vfile = require('to-vfile');
var reporter = require('vfile-reporter');
var report = require('vfile-reporter');
var preset = require('./preset');

@@ -854,3 +852,3 @@

.process(vfile.readSync('index.md'), function (err, file) {
console.error(reporter(err || file));
console.error(report(err || file));

@@ -869,3 +867,3 @@ if (file) {

[logo]: https://cdn.rawgit.com/unifiedjs/unified/84f55c8/logo.svg
[logo]: https://cdn.rawgit.com/unifiedjs/unified/0cd3a41/logo.svg

@@ -880,2 +878,6 @@ [travis-badge]: https://img.shields.io/travis/unifiedjs/unified.svg

[chat-badge]: https://img.shields.io/gitter/room/unifiedjs/Lobby.svg
[chat]: https://gitter.im/unifiedjs/Lobby
[npm]: https://docs.npmjs.com/cli/install

@@ -966,1 +968,9 @@

[promise]: https://developer.mozilla.org/Web/JavaScript/Reference/Global_Objects/Promise
[remark-plugins]: https://github.com/wooorm/remark/blob/master/doc/plugins.md#list-of-plugins
[rehype-plugins]: https://github.com/wooorm/rehype/blob/master/doc/plugins.md#list-of-plugins
[retext-plugins]: https://github.com/wooorm/retext/blob/master/doc/plugins.md#list-of-plugins
[stream]: https://github.com/unifiedjs/unified-stream
SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc