Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
unified - npm Package Compare versions
Comparing version 7.1.0 to 8.0.0
31
index.js
@@ -7,3 +7,2 @@ 'use strict' | ||
| var trough = require('trough') | ||
| var string = require('x-is-string') | ||
| var plain = require('is-plain-obj') | ||
@@ -91,5 +90,5 @@ | ||
| // | ||
| // For example, take unified itself. It’s frozen. Plugins should not be | ||
| // added to it. Rather, it should be extended, by invoking it, before | ||
| // modifying it. | ||
| // For example, take unified itself: it’s frozen. | ||
| // Plugins should not be added to it. | ||
| // Rather, it should be extended, by invoking it, before modifying it. | ||
| // | ||
@@ -134,5 +133,6 @@ // In essence, always invoke this when exporting a processor. | ||
| // Data management. Getter / setter for processor-specific informtion. | ||
| // Data management. | ||
| // Getter / setter for processor-specific informtion. | ||
| function data(key, value) { | ||
| if (string(key)) { | ||
| if (typeof key === 'string') { | ||
| // Set `key`. | ||
@@ -273,3 +273,3 @@ if (arguments.length === 2) { | ||
| if (newable(Parser)) { | ||
| if (newable(Parser, 'parse')) { | ||
| return new Parser(String(file), file).parse() | ||
@@ -344,3 +344,3 @@ } | ||
| if (newable(Compiler)) { | ||
| if (newable(Compiler, 'compile')) { | ||
| return new Compiler(node, file).compile() | ||
@@ -407,5 +407,11 @@ } | ||
| // Check if `func` is a constructor. | ||
| function newable(value) { | ||
| return typeof value === 'function' && keys(value.prototype) | ||
| // Check if `value` is a constructor. | ||
| function newable(value, name) { | ||
| return ( | ||
| typeof value === 'function' && | ||
| // A function with keys in its prototype is probably a constructor. | ||
| // Classes’ prototype methods are not enumerable, so we check if some value | ||
| // exists in the prototype. | ||
| (keys(value.prototype) || name in value.prototype) | ||
| ) | ||
| } | ||
@@ -419,2 +425,3 @@ | ||
| } | ||
| return false | ||
@@ -450,3 +457,3 @@ } | ||
| function assertNode(node) { | ||
| if (!node || !string(node.type)) { | ||
| if (!node || typeof node.type !== 'string') { | ||
| throw new Error('Expected node, got `' + node + '`') | ||
@@ -453,0 +460,0 @@ } |
| { | ||
| "name": "unified", | ||
| "version": "7.1.0", | ||
| "description": "Pluggable text processing interface", | ||
| "version": "8.0.0", | ||
| "description": "Interface for processing text using syntax trees", | ||
| "license": "MIT", | ||
@@ -21,3 +21,8 @@ "keywords": [ | ||
| "contributors": [ | ||
| "Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)" | ||
| "Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)", | ||
| "Junyoung Choi <fluke8259@gmail.com>", | ||
| "Hernan Rajchert <hrajchert@gmail.com>", | ||
| "Christian Murphy <christian.murphy.42@gmail.com>", | ||
| "Vse Mozhet Byt <vsemozhetbyt@gmail.com>", | ||
| "Richard Littauer <richard.littauer@gmail.com>" | ||
| ], | ||
@@ -31,27 +36,26 @@ "types": "types/index.d.ts", | ||
| "dependencies": { | ||
| "@types/unist": "^2.0.0", | ||
| "@types/vfile": "^3.0.0", | ||
| "bail": "^1.0.0", | ||
| "extend": "^3.0.0", | ||
| "is-plain-obj": "^1.1.0", | ||
| "is-plain-obj": "^2.0.0", | ||
| "trough": "^1.0.0", | ||
| "vfile": "^3.0.0", | ||
| "x-is-string": "^0.1.0" | ||
| "vfile": "^4.0.0" | ||
| }, | ||
| "devDependencies": { | ||
| "@types/unist": "^2.0.0", | ||
| "@types/vfile": "^3.0.0", | ||
| "browserify": "^16.0.0", | ||
| "dtslint": "^0.4.1", | ||
| "esmangle": "^1.0.0", | ||
| "nyc": "^13.0.0", | ||
| "prettier": "^1.12.1", | ||
| "dtslint": "^0.8.0", | ||
| "nyc": "^14.0.0", | ||
| "prettier": "^1.0.0", | ||
| "remark-cli": "^6.0.0", | ||
| "remark-preset-wooorm": "^4.0.0", | ||
| "tape": "^4.4.0", | ||
| "typescript": "^3.2.2", | ||
| "xo": "^0.23.0" | ||
| "remark-preset-wooorm": "^5.0.0", | ||
| "tape": "^4.0.0", | ||
| "tinyify": "^2.5.1", | ||
| "typescript": "^3.0.0", | ||
| "xo": "^0.24.0" | ||
| }, | ||
| "scripts": { | ||
| "format": "remark . -qfo && prettier --write '**/{*.js,*.ts}' && xo --fix", | ||
| "build-bundle": "browserify index.js -s unified > unified.js", | ||
| "build-mangle": "esmangle unified.js > unified.min.js", | ||
| "format": "remark . -qfo && prettier --write \"**/{*.js,*.ts}\" && xo --fix", | ||
| "build-bundle": "browserify index.js -s unified -o unified.js", | ||
| "build-mangle": "browserify index.js -s unified -p tinyify -o unified.min.js", | ||
| "build": "npm run build-bundle && npm run build-mangle", | ||
@@ -82,5 +86,2 @@ "test-api": "node test", | ||
| "guard-for-in": "off", | ||
| "no-var": "off", | ||
| "object-shorthand": "off", | ||
| "prefer-arrow-callback": "off", | ||
| "unicorn/prefer-type-error": "off" | ||
@@ -87,0 +88,0 @@ }, |
749
readme.md
| # [![unified][logo]](https://unified.js.org/) | ||
| [![Travis][build-badge]][build] | ||
| [![Build][build-badge]][build] | ||
| [![Coverage][coverage-badge]][coverage] | ||
| [![Downloads][downloads-badge]][downloads] | ||
| [![Size][size-badge]][size] | ||
| [![Sponsors][sponsors-badge]][collective] | ||
| [![Backers][backers-badge]][collective] | ||
| [![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], and allows for processing between formats. | ||
| **unified** enabled new exciting projects like [Gatsby][] to pull in markdown, | ||
| ## Intro | ||
| **unified** enables new exciting projects like [Gatsby][] to pull in Markdown, | ||
| [MDX][] to embed [JSX][], and [Prettier][] to format it. | ||
| It’s used to check code for [Storybook][], [debugger.html][] ([Mozilla][]), | ||
| and [opensource.guide][] ([GitHub][]). | ||
| It’s used in about 200k projects on GitHub and has about 10m downloads each | ||
| month on npm: you’re probably using it. | ||
| Some notable users are [Node.js][], [ZEIT][], [Netlify][], [GitHub][], | ||
| [Mozilla][], [WordPress][], [Adobe][], [Facebook][], [Google][], and many more. | ||
| * To read about what we’re up to, follow us on [Medium][] and [Twitter][] | ||
| * To read about what we are up to, follow us on [Medium][] and [Twitter][] | ||
| * For a less technical and more practical introduction to unified, visit | ||
| [`unified.js.org`][site] and try its introductory [Guides][] | ||
| * To help us out, see [`contributing.md`][contributing], or become a backer | ||
| or sponsor on [Open Collective][collective] | ||
| * Browse [awesome unified][awesome] to find out more about the ecosystem | ||
| * Questions? | ||
| Get help on [our Spectrum community][spectrum]! | ||
| * Check out [Contribute][] below to find out how to help out, or become a | ||
| backer or sponsor on [Open Collective][collective] | ||
| * * * | ||
| <!--lint ignore no-html--> | ||
| **Announcing the unified collective! 🎉 | ||
| [Read more about it on Medium »][medium]** | ||
| ## Sponsors | ||
@@ -63,12 +65,18 @@ | ||
| ## Installation | ||
| [**Read more about the unified collective on Medium »**][announcement] | ||
| ## Install | ||
| [npm][]: | ||
| ```bash | ||
| ```sh | ||
| npm install unified | ||
| ``` | ||
| ## Usage | ||
| This package comes with types. | ||
| If you’re using TypeScript, make sure to also install [`@types/unist`][ts-unist] | ||
| and [`@types/vfile`][ts-vfile]. | ||
| ## Use | ||
| ```js | ||
@@ -86,3 +94,3 @@ var unified = require('unified') | ||
| .use(remark2rehype) | ||
| .use(doc) | ||
| .use(doc, {title: '👋🌍'}) | ||
| .use(format) | ||
@@ -98,4 +106,7 @@ .use(html) | ||
| ```txt | ||
| no issues found | ||
| ``` | ||
| ```html | ||
| no issues found | ||
| <!doctype html> | ||
@@ -105,2 +116,3 @@ <html lang="en"> | ||
| <meta charset="utf-8"> | ||
| <title>👋🌍</title> | ||
| <meta name="viewport" content="width=device-width, initial-scale=1"> | ||
@@ -120,7 +132,7 @@ </head> | ||
| * [processor.use(plugin\[, options\])](#processoruseplugin-options) | ||
| * [processor.parse(file|value)](#processorparsefilevalue) | ||
| * [processor.parse(file)](#processorparsefile) | ||
| * [processor.stringify(node\[, file\])](#processorstringifynode-file) | ||
| * [processor.run(node\[, file\]\[, done\])](#processorrunnode-file-done) | ||
| * [processor.runSync(node\[, file\])](#processorrunsyncnode-file) | ||
| * [processor.process(file|value\[, done\])](#processorprocessfilevalue-done) | ||
| * [processor.process(file\[, done\])](#processorprocessfile-done) | ||
| * [processor.processSync(file|value)](#processorprocesssyncfilevalue) | ||
@@ -139,12 +151,13 @@ * [processor.data(\[key\[, value\]\])](#processordatakey-value) | ||
| **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**. | ||
| **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 inspect and | ||
| modify them. | ||
| To get to the syntax tree from text, there is a [*parser*][parser]. | ||
| To get from that back to text, there is a [*compiler*][compiler]. | ||
| This is the [*process*][process] of a *processor*. | ||
| ```ascii | ||
| | ....................... process() ......................... | | ||
| | ......... parse() ..... | run() | ..... stringify() ....... | | ||
| | ........................ process ........................... | | ||
| | .......... parse ... | ... run ... | ... stringify ..........| | ||
@@ -163,36 +176,41 @@ +--------+ +----------+ | ||
| 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. | ||
| Every **processor** implements another processor. | ||
| To create a processor, call another processor. | ||
| The new processor is configured to work the same as its ancestor. | ||
| But when the descendant processor is configured in the future it does not affect | ||
| the ancestral processor. | ||
| When processors are exposed from a module (for example, unified itself) they | ||
| 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. | ||
| module users. | ||
| Those processors are [*frozen*][freeze] and they should be called to create a | ||
| new processor before they are used. | ||
| ###### Node | ||
| ###### Syntax trees | ||
| 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. | ||
| The **syntax trees** used in **unified** are [**unist**][unist] nodes. | ||
| A [**node**][node] is a plain JavaScript objects with a `type` field. | ||
| The semantics of nodes and format of syntax trees is defined by other projects. | ||
| There are several [utilities][unist-utilities] for working with these nodes. | ||
| There are several [*utilities*][unist-utilities] for working with nodes. | ||
| * [**hast**][hast] — HTML | ||
| * [**mdast**][mdast] — Markdown | ||
| * [**nlcst**][nlcst] — Natural language | ||
| ###### 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 **unified** and other plugins to process between different | ||
| syntaxes. | ||
| The following projects process different [*syntax tree*][syntax-tree] formats. | ||
| They parse text to a syntax tree and compile that back to text. | ||
| These processors can be used as is, or their parser and stringifier can be mixed | ||
| and matched with **unified** and plugins to process between different syntaxes. | ||
| * [**rehype**][rehype] ([**hast**][hast]) — HTML | ||
| * [**remark**][remark] ([**mdast**][mdast]) — Markdown | ||
| * [**retext**][retext] ([**nlcst**][nlcst]) — Natural language | ||
| * [**rehype**][rehype] ([*hast*][hast]) — HTML | ||
| * [**remark**][remark] ([*mdast*][mdast]) — Markdown | ||
| * [**retext**][retext] ([*nlcst*][nlcst]) — Natural language | ||
| ###### List of Plugins | ||
| The below plugins work with **unified**, unrelated to what flavour the syntax | ||
| tree is in: | ||
| The below [**plugins**][plugin] work with **unified**, on all [*syntax | ||
| tree*][syntax-tree] formats: | ||
@@ -203,30 +221,30 @@ * [`unified-diff`](https://github.com/unifiedjs/unified-diff) | ||
| See [**remark**][remark-plugins], [**rehype**][rehype-plugins], and | ||
| [**retext**][retext-plugins] for lists of their plugins. | ||
| [**retext**][retext-plugins] for their lists of 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 plugins. | ||
| When processing a document, **metadata** is often gathered about that document. | ||
| [**vfile**][vfile] is a virtual file format that stores data, metadata, and | ||
| messages about files 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 | ||
| [**plugin**][plugin], and optionally settings. | ||
| [*Processors*][processors] are configured with [*plugin*][plugin]s or | ||
| with the [`data`][data] method. | ||
| ###### 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 plugins with [`unified-engine-gulp`][gulp], and | ||
| Atom Linters with [`unified-engine-atom`][atom]. | ||
| **unified** can integrate with the file system with [`unified-engine`][engine]. | ||
| 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]. | ||
| [`unified-stream`][stream] provides a streaming interface. | ||
| ###### Programming interface | ||
| The API gives access to processing metadata (such as lint messages) and | ||
| supports multiple passed through files: | ||
| The API provided by **unified** allows multiple files to be processed and gives | ||
| access to *metadata* (such as lint messages): | ||
@@ -255,3 +273,3 @@ ```js | ||
| .use(html) | ||
| .process('*Emphasis* and _importance_, you guys!', function(err, file) { | ||
| .process('*Emphasis* and _stress_, you guys!', function(err, file) { | ||
| console.error(report(err || file)) | ||
@@ -265,25 +283,28 @@ console.log(String(file)) | ||
| ```txt | ||
| 1:16-1:28 warning Emphasis should use `*` as a marker emphasis-marker remark-lint | ||
| 1:34-1:38 warning `guys` may be insensitive, use `people`, `persons`, `folks` instead gals-men retext-equality | ||
| 1:16-1:24 warning Emphasis should use `*` as a marker emphasis-marker remark-lint | ||
| 1:30-1:34 warning `guys` may be insensitive, use `people`, `persons`, `folks` instead gals-men retext-equality | ||
| ⚠ 2 warnings | ||
| <p><em>Emphasis</em> and <em>importance</em>, you guys!</p> | ||
| ``` | ||
| ```html | ||
| <p><em>Emphasis</em> and <em>stress</em>, you guys!</p> | ||
| ``` | ||
| ###### Processing between syntaxes | ||
| The processors can be combined in two modes. | ||
| [*Processors*][processors] can be combined in two modes. | ||
| **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*][syntax-tree] from one format | ||
| (*origin*) to another (*destination*). | ||
| Another processor runs on the destination tree. | ||
| Finally, the original processor continues transforming the origin 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 format to another. | ||
| But the original processor continues transforming the destination tree. | ||
| 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. | ||
| *bridge* mode: the origin syntax tree is kept after [**retext**][retext] is | ||
| done; whereas `remark-rehype` is used in *mutate* mode: it sets a new syntax | ||
| tree and discards the origin tree. | ||
@@ -299,9 +320,10 @@ * [`remark-retext`][remark-retext] | ||
| Object describing how to process text. | ||
| [*Processor*][processors] describing how to *process* text. | ||
| ###### Returns | ||
| `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. | ||
| `Function` — New [*unfrozen*][freeze] processor that is configured to work the | ||
| same as its ancestor. | ||
| When the descendant processor is configured in the future it does not affect the | ||
| ancestral processor. | ||
@@ -330,4 +352,4 @@ ###### Example | ||
| Configure the processor to use a [**plugin**][plugin] and optionally configure | ||
| that plugin with options. | ||
| [*Configure*][configuration] the processor to use a [*plugin*][plugin] and | ||
| optionally configure that plugin with options. | ||
@@ -342,3 +364,3 @@ ###### Signatures | ||
| * `plugin` ([`Plugin`][plugin]) | ||
| * `plugin` ([`Attacher`][plugin]) | ||
| * `options` (`*`, optional) — Configuration for `plugin` | ||
@@ -352,13 +374,13 @@ * `preset` (`Object`) — Object with an optional `plugins` (set to `list`), | ||
| `processor` — The processor on which `use` is invoked. | ||
| `processor` — The processor that `use` was called on. | ||
| ###### Note | ||
| `use` cannot be called on [frozen][freeze] processors. Invoke the processor | ||
| first to create a new unfrozen processor. | ||
| `use` cannot be called on [*frozen*][freeze] processors. | ||
| Call the processor first to create a new unfrozen processor. | ||
| ###### Example | ||
| 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. | ||
@@ -384,26 +406,25 @@ ```js | ||
| ### `processor.parse(file|value)` | ||
| ### `processor.parse(file)` | ||
| Parse text to a syntax tree. | ||
| Parse text to a [*syntax tree*][syntax-tree]. | ||
| ###### Parameters | ||
| * `file` ([`VFile`][file]) | ||
| — Or anything which can be given to `vfile()` | ||
| * `file` ([`VFile`][vfile]) — [*File*][file], any value accepted by `vfile()` | ||
| ###### Returns | ||
| [`Node`][node] — Syntax tree representation of input. | ||
| [`Node`][node] — Parsed [*syntax tree*][syntax-tree] representing `file`. | ||
| ###### Note | ||
| `parse` [freezes][freeze] the processor if not already frozen. | ||
| `parse` freezes the processor if not already [*frozen*][freeze]. | ||
| `parse` does not apply [transformers from the run phase][description] to the | ||
| [syntax tree][node]. | ||
| `parse` performs the [*parse phase*][description], not the *run phase* or other | ||
| phases. | ||
| ###### Example | ||
| The below example shows how the `parse` function can be used to create a | ||
| [syntax tree][node] from a [file][]. | ||
| The below example shows how `parse` can be used to create a syntax tree from a | ||
| file. | ||
@@ -437,39 +458,45 @@ ```js | ||
| 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. | ||
| A **parser** handles the parsing of text to a [*syntax tree*][syntax-tree]. | ||
| Used in the [*parse phase*][description] and called with a `string` and | ||
| [`VFile`][vfile] representation of the text to parse. | ||
| `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 be a 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 (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]. | ||
| `Parser` can also be a constructor function (a function with a `parse` field, or | ||
| other fields, in its `prototype`), in which case it’s constructed with `new`. | ||
| Instances must have a `parse` method that is called without arguments and must | ||
| return a [`Node`][node]. | ||
| ### `processor.stringify(node[, file])` | ||
| Compile a syntax tree to text. | ||
| Stringify a [*syntax tree*][syntax-tree] to text. | ||
| ###### Parameters | ||
| * `node` ([`Node`][node]) | ||
| * `file` ([`VFile`][file], optional); | ||
| — Or anything which can be given to `vfile()` | ||
| * `node` ([`Node`][node]) — [*Syntax tree*][syntax-tree] to stringify | ||
| * `file` ([`VFile`][vfile], optional) — [*File*][file], any value accepted by | ||
| `vfile()` | ||
| ###### Returns | ||
| `string` — String representation of the syntax tree file. | ||
| `string` (see notes) — Textual representation of the [*syntax | ||
| tree*][syntax-tree] | ||
| ###### Note | ||
| `stringify` [freezes][freeze] the processor if not already frozen. | ||
| `stringify` freezes the processor if not already [*frozen*][freeze]. | ||
| `stringify` does not apply [transformers from the run phase][description] | ||
| to the [syntax tree][node]. | ||
| `stringify` performs the [*stringify phase*][description], not the *run phase* | ||
| or other phases. | ||
| Be aware that [*compiler*][compiler]s typically, but not always, return | ||
| `string`. | ||
| Some compilers, such as the one configured with [`rehype-react`][rehype-react], | ||
| return other values (in this case, a React tree). | ||
| When using TypeScript, cast the type on your side. | ||
| ###### Example | ||
| The below example shows how the `stringify` function can be used to generate a | ||
| [file][] from a [syntax tree][node]. | ||
| The below example shows how `stringify` can be used to stringify a syntax tree. | ||
@@ -498,48 +525,52 @@ ```js | ||
| Function handling the compilation of syntax tree to a text. Used in the | ||
| [**stringify**][stringify] phase in the process and invoked with a | ||
| [`Node`][node] and [`VFile`][file] representation of the document to stringify. | ||
| A **compiler** handles the compiling of a [*syntax tree*][syntax-tree] to text. | ||
| Used in the [*stringify phase*][description] and called with a [`Node`][node] | ||
| and [`VFile`][file] representation of syntax tree to compile. | ||
| `Compiler` can be a normal function in which case it must return a `string`: | ||
| the text representation of the given syntax tree. | ||
| `Compiler` can be a function, in which case it should return a `string`: the | ||
| textual representation of the syntax tree. | ||
| `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`. | ||
| `Compiler` can also be a constructor function (a function with a `compile` | ||
| field, or other fields, in its `prototype`), in which case it’s constructed with | ||
| `new`. | ||
| Instances must have a `compile` method that is called without arguments and | ||
| should return a `string`. | ||
| ### `processor.run(node[, file][, done])` | ||
| Transform a syntax tree by applying [**plugin**][plugin]s to it. | ||
| Run [*transformers*][transformer] on a [*syntax tree*][syntax-tree]. | ||
| ###### Parameters | ||
| * `node` ([`Node`][node]) | ||
| * `file` ([`VFile`][file], optional) | ||
| — Or anything which can be given to `vfile()` | ||
| * `done` ([`Function`][run-done], optional) | ||
| * `node` ([`Node`][node]) — [*Syntax tree*][syntax-tree] to run on | ||
| * `file` ([`VFile`][vfile], optional) — [*File*][file], any value accepted by | ||
| `vfile()` | ||
| * `done` ([`Function`][run-done], optional) — Callback | ||
| ###### Returns | ||
| [`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. | ||
| The returned promise is rejected with a fatal error, or resolved with the | ||
| transformed [*syntax tree*][syntax-tree]. | ||
| ###### Note | ||
| `run` [freezes][freeze] the processor if not already frozen. | ||
| `run` freezes the processor if not already [*frozen*][freeze]. | ||
| `run` performs the [*run phase*][description], not other phases. | ||
| #### `function done(err[, node, file])` | ||
| Invoked when transformation is complete. Either invoked with an error or a | ||
| syntax tree and a file. | ||
| Callback called when [*transformers*][transformer] are done. | ||
| Called with either an error or results. | ||
| ###### Parameters | ||
| * `err` (`Error`) — Fatal error | ||
| * `node` ([`Node`][node]) | ||
| * `file` ([`VFile`][file]) | ||
| * `err` (`Error`, optional) — Fatal error | ||
| * `node` ([`Node`][node], optional) — Transformed [*syntax tree*][syntax-tree] | ||
| * `file` ([`VFile`][vfile], optional) — [*File*][file] | ||
| ###### Example | ||
| The below example shows how the `run` function can be used to transform a | ||
| [syntax tree][node]. | ||
| The below example shows how `run` can be used to transform a syntax tree. | ||
@@ -579,44 +610,58 @@ ```js | ||
| Transform a syntax tree by applying [**plugin**][plugin]s to it. | ||
| Run [*transformers*][transformer] on a [*syntax tree*][syntax-tree]. | ||
| If asynchronous [**plugin**][plugin]s are configured an error is thrown. | ||
| An error is thrown if asynchronous [*plugin*][plugin]s are configured. | ||
| ###### Parameters | ||
| * `node` ([`Node`][node]) | ||
| * `file` ([`VFile`][file], optional) | ||
| — Or anything which can be given to `vfile()` | ||
| * `node` ([`Node`][node]) — [*Syntax tree*][syntax-tree] to run on | ||
| * `file` ([`VFile`][vfile], optional) — [*File*][file], any value accepted by | ||
| `vfile()` | ||
| ###### Returns | ||
| [`Node`][node] — The given syntax tree. | ||
| [`Node`][node] — Transformed [*syntax tree*][syntax-tree]. | ||
| ###### Note | ||
| `runSync` [freezes][freeze] the processor if not already frozen. | ||
| `runSync` freezes the processor if not already [*frozen*][freeze]. | ||
| ### `processor.process(file|value[, done])` | ||
| `runSync` performs the [*run phase*][description], not other phases. | ||
| Process the given representation of a file as configured on the processor. The | ||
| process invokes `parse`, `run`, and `stringify` internally. | ||
| ### `processor.process(file[, done])` | ||
| [*Process*][description] the given [*file*][file] as configured on the | ||
| processor. | ||
| ###### Parameters | ||
| * `file` ([`VFile`][file]) | ||
| * `value` (`string`) — String representation of a file | ||
| * `done` ([`Function`][process-done], optional) | ||
| * `file` ([`VFile`][vfile]) — [*File*][file], any value accepted by `vfile()` | ||
| * `done` ([`Function`][process-done], optional) — Callback | ||
| ###### Returns | ||
| [`Promise`][promise] if `done` is not given. Rejected with an error or | ||
| resolved with the resulting file. | ||
| [`Promise`][promise] if `done` is not given. | ||
| The returned promise is rejected with a fatal error, or resolved with the | ||
| processed [*file*][file]. | ||
| The parsed, transformed, and stringified value is exposed on | ||
| [`file.contents`][vfile-contents]. | ||
| ###### Note | ||
| `process` [freezes][freeze] the processor if not already frozen. | ||
| `process` freezes the processor if not already [*frozen*][freeze]. | ||
| `process` performs the [*parse*, *run*, and *stringify* phases][description]. | ||
| Be aware that [*compiler*][compiler]s typically, but not always, return | ||
| `string`. | ||
| Some compilers, such as the one configured with [`rehype-react`][rehype-react], | ||
| return other values (in this case, a React tree). | ||
| When using TypeScript, cast the type of [`file.contents`][vfile-contents] on | ||
| your side. | ||
| ###### Example | ||
| The below example shows how the `process` function can be used to process a | ||
| [file][] whether plugins are asynchronous or not with Promises. | ||
| The below example shows how `process` can be used to process a file, whether | ||
| transformers are asynchronous or not, with promises. | ||
@@ -634,3 +679,3 @@ ```js | ||
| .use(remark2rehype) | ||
| .use(doc) | ||
| .use(doc, {title: '👋🌍'}) | ||
| .use(format) | ||
@@ -656,2 +701,3 @@ .use(html) | ||
| <meta charset="utf-8"> | ||
| <title>👋🌍</title> | ||
| <meta name="viewport" content="width=device-width, initial-scale=1"> | ||
@@ -667,4 +713,4 @@ </head> | ||
| Invoked when the process is complete. Invoked with a fatal error, if any, and | ||
| the [`VFile`][file]. | ||
| Callback called when the [*process*][description] is done. | ||
| Called with a fatal error, if any, and a [*file*][file]. | ||
@@ -674,8 +720,8 @@ ###### Parameters | ||
| * `err` (`Error`, optional) — Fatal error | ||
| * `file` ([`VFile`][file]) | ||
| * `file` ([`VFile`][vfile]) — Processed [*file*][file] | ||
| ###### Example | ||
| The below example shows how the `process` function can be used to process a | ||
| [file][] whether plugins are asynchronous or not with a callback. | ||
| The below example shows how `process` can be used to process a file, whether | ||
| transformers are asynchronous or not, with a callback. | ||
@@ -693,3 +739,3 @@ ```js | ||
| .use(stringify) | ||
| .process('@mention', function(err, file) { | ||
| .process('@wooorm', function(err, file) { | ||
| console.error(report(err || file)) | ||
@@ -702,31 +748,43 @@ console.log(String(file)) | ||
| ```markdown | ||
| ```txt | ||
| no issues found | ||
| [**@mention**](https://github.com/blog/821) | ||
| ``` | ||
| ```markdown | ||
| [**@wooorm**](https://github.com/wooorm) | ||
| ``` | ||
| ### `processor.processSync(file|value)` | ||
| Process the given representation of a file as configured on the processor. The | ||
| process invokes `parse`, `run`, and `stringify` internally. | ||
| [*Process*][description] the given [*file*][file] as configured on the | ||
| processor. | ||
| If asynchronous [**plugin**][plugin]s are configured an error is thrown. | ||
| An error is thrown if asynchronous [*plugin*][plugin]s are configured. | ||
| ###### Parameters | ||
| * `file` ([`VFile`][file]) | ||
| * `value` (`string`) — String representation of a file | ||
| * `file` ([`VFile`][vfile]) — [*File*][file], any value accepted by `vfile()` | ||
| ###### Returns | ||
| [`VFile`][file] — Virtual file with modified [`contents`][vfile-contents]. | ||
| ([`VFile`][vfile]) — Processed [*file*][file] | ||
| ###### Note | ||
| `processSync` [freezes][freeze] the processor if not already frozen. | ||
| `processSync` freezes the processor if not already [*frozen*][freeze]. | ||
| `processSync` performs the [*parse*, *run*, and *stringify* | ||
| phases][description]. | ||
| Be aware that [*compiler*][compiler]s typically, but not always, return | ||
| `string`. | ||
| Some compilers, such as the one configured with [`rehype-react`][rehype-react], | ||
| return other values (in this case, a React tree). | ||
| When using TypeScript, cast the type of [`file.contents`][vfile-contents] on | ||
| your side. | ||
| ###### Example | ||
| The below example shows how the `processSync` function can be used to process a | ||
| [file][] if all plugins are known to be synchronous. | ||
| The below example shows how `processSync` can be used to process a file, if all | ||
| transformers are synchronous. | ||
@@ -744,3 +802,3 @@ ```js | ||
| .use(remark2rehype) | ||
| .use(doc) | ||
| .use(doc, {title: '👋🌍'}) | ||
| .use(format) | ||
@@ -759,2 +817,3 @@ .use(html) | ||
| <meta charset="utf-8"> | ||
| <title>👋🌍</title> | ||
| <meta name="viewport" content="width=device-width, initial-scale=1"> | ||
@@ -770,21 +829,34 @@ </head> | ||
| 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. | ||
| [*Configure*][configuration] the processor with information available to all | ||
| [*plugin*][plugin]s. | ||
| Information is stored in an in-memory key-value store. | ||
| Typically, options can be given to a specific plugin, but sometimes it makes | ||
| sense to have information shared with several plugins. | ||
| For example, a list of HTML elements that are self-closing, which is needed | ||
| during all [*phases*][description] of the *process*. | ||
| ###### Signatures | ||
| * `processor = processor.data(key, value)` | ||
| * `processor = processor.data(values)` | ||
| * `value = processor.data(key)` | ||
| * `info = processor.data()` | ||
| ###### Parameters | ||
| * `key` (`string`, optional) — Identifier | ||
| * `value` (`*`, optional) — Value to set. Omit if getting `key` | ||
| * `value` (`*`, optional) — Value to set | ||
| * `values` (`Object`, optional) — Values to set | ||
| ###### Returns | ||
| * `processor` — If setting, the processor on which `data` is invoked | ||
| * `*` — If getting, the value at `key` | ||
| * `object` - Without arguments, the key-value store | ||
| * `processor` — If setting, the processor that `data` is called on | ||
| * `value` (`*`) — If getting, the value at `key` | ||
| * `info` (`Object`) — Without arguments, the key-value store | ||
| ###### Note | ||
| Setting information with `data` cannot occur on [frozen][freeze] processors. | ||
| Invoke the processor first to create a new unfrozen processor. | ||
| Setting information cannot occur on [*frozen*][freeze] processors. | ||
| Call the processor first to create a new unfrozen processor. | ||
@@ -798,7 +870,11 @@ ###### Example | ||
| var processor = unified() | ||
| .data('alpha', 'bravo') | ||
| .data('alpha') // => 'bravo' | ||
| var processor = unified().data('alpha', 'bravo') | ||
| processor.data('alpha') // => 'bravo' | ||
| processor.data() // {alpha: 'bravo'} | ||
| processor.data({charlie: 'delta'}) | ||
| processor.data() // {charlie: 'delta'} | ||
| ``` | ||
@@ -808,20 +884,21 @@ | ||
| 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 directly. | ||
| Once a processor is frozen it cannot be unfrozen. New processors functioning | ||
| just like it can be created by invoking the processor. | ||
| Once a processor is frozen it cannot be *unfrozen*. | ||
| New processors working the same way can be created by calling the processor. | ||
| It’s possible to freeze processors explicitly, by calling `.freeze()`, but | ||
| [`.parse()`][parse], [`.run()`][run], [`.stringify()`][stringify], and | ||
| [`.process()`][process] call `.freeze()` to freeze a processor too. | ||
| It’s possible to freeze processors explicitly by calling `.freeze()`. | ||
| Processors freeze implicitly when [`.parse()`][parse], [`.run()`][run], | ||
| [`.runSync()`][run-sync], [`.stringify()`][stringify], [`.process()`][process], | ||
| or [`.processSync()`][process-sync] are called. | ||
| ###### Returns | ||
| `Processor` — The processor on which `freeze` is invoked. | ||
| `processor` — The processor that `freeze` was called on. | ||
| ###### Example | ||
| The following example, `index.js`, shows how [**rehype**][rehype] prevents | ||
| extensions to itself: | ||
| The following example, `index.js`, shows how rehype prevents extensions to | ||
| itself: | ||
@@ -844,13 +921,14 @@ ```js | ||
| var format = require('rehype-format') | ||
| // ... | ||
| // … | ||
| rehype() | ||
| .use(format) | ||
| // ... | ||
| // … | ||
| ``` | ||
| 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 that operates on the | ||
| frozen rehype interface because it does not call `rehype`. | ||
| If this behaviour was allowed it would result in unexpected behaviour so an | ||
| error is thrown. | ||
| **This is invalid**: | ||
@@ -860,7 +938,7 @@ ```js | ||
| var format = require('rehype-format') | ||
| // ... | ||
| // … | ||
| rehype | ||
| .use(format) | ||
| // ... | ||
| // … | ||
| ``` | ||
@@ -884,11 +962,11 @@ | ||
| **unified** plugins change the way the applied-on processor works in the | ||
| following ways: | ||
| **Plugins** [*configure*][configuration] the processors they are applied on in | ||
| the following ways: | ||
| * 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 | ||
| * They change the processor: such as the [*parser*][parser], the | ||
| [*compiler*][compiler], or configuring [*data*][data] | ||
| * They specify how to handle [*syntax trees*][syntax-tree] and [*files*][file] | ||
| Plugins are a concept. They materialise as [`attacher`][attacher]s. | ||
| Plugins are a concept. | ||
| They materialise as [`attacher`][attacher]s. | ||
@@ -919,2 +997,8 @@ ###### Example | ||
| `index.md`: | ||
| ```markdown | ||
| # Hello, World! | ||
| ``` | ||
| `index.js`: | ||
@@ -944,14 +1028,27 @@ | ||
| Yields: | ||
| ```txt | ||
| index.md: no issues found | ||
| ``` | ||
| `index.html`: | ||
| ```html | ||
| <h1>Hello, World!</h1> | ||
| ``` | ||
| ### `function attacher([options])` | ||
| An attacher is the thing passed to [`use`][use]. It configures the processor | ||
| and in turn can receive options. | ||
| **Attachers** are materialised [*plugin*][plugin]s. | ||
| An attacher is a function that can receive options and | ||
| [*configures*][configuration] the processor. | ||
| 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 change the processor, such as the [*parser*][parser], the | ||
| [*compiler*][compiler], configuring [*data*][data], or by specifying how the | ||
| [*syntax tree*][syntax-tree] or [*file*][file] are handled. | ||
| ###### Context | ||
| The context object is set to the invoked on [`processor`][processor]. | ||
| The context object (`this`) is set to the processor the attacher is applied on. | ||
@@ -968,21 +1065,20 @@ ###### Parameters | ||
| Attachers are invoked when the processor is [frozen][freeze]: either when | ||
| `.freeze()` is called explicitly, or when [`.parse()`][parse], [`.run()`][run], | ||
| [`.stringify()`][stringify], or [`.process()`][process] is called for the first | ||
| time. | ||
| Attachers are called when the processor is [*frozen*][freeze], not when they are | ||
| applied. | ||
| ### `function transformer(node, file[, next])` | ||
| 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** handle [*syntax tree*][syntax-tree]s and [*file*][file]s. | ||
| A transformer is a function that is called each time a syntax tree and file are | ||
| passed through the [*run phase*][description]. | ||
| 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 *run phase* is handled by [`trough`][trough], see its documentation for the | ||
| exact semantics of these functions. | ||
| ###### Parameters | ||
| * `node` ([`Node`][node]) | ||
| * `file` ([`VFile`][file]) | ||
| * `node` ([`Node`][node]) — [*Syntax tree*][syntax-tree] to handle | ||
| * `file` ([`VFile`][vfile]) — [*File*][file] to handle | ||
| * `next` ([`Function`][next], optional) | ||
@@ -992,24 +1088,27 @@ | ||
| * `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`) | ||
| * `Error` — Fatal error to stop the process | ||
| * `node` ([`Node`][node]) — New [*syntax tree*][syntax-tree]. | ||
| If returned, the next transformer is given this new tree | ||
| * `Promise` — Returned to perform an asynchronous operation. | ||
| The promise **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*][transformer] includes `next` (the third | ||
| argument), the transformer **may** perform asynchronous operations, and **must** | ||
| call `next()`. | ||
| ###### Parameters | ||
| * `err` (`Error`, optional) — Stop the process | ||
| * `node` ([`Node`][node], optional) — New syntax tree | ||
| * `file` ([`VFile`][file], optional) — New virtual file | ||
| * `err` (`Error`, optional) — Fatal error to stop the process | ||
| * `node` ([`Node`][node], optional) — New [*syntax tree*][syntax-tree]. | ||
| If given, the next transformer is given this new tree | ||
| * `file` ([`VFile`][vfile], optional) — New [*file*][file]. | ||
| If given, the next transformer is given this new file | ||
| ## `Preset` | ||
| Presets provide a potentially sharable way to configure processors. They can | ||
| contain multiple plugins and optionally settings as well. | ||
| **Presets** are sharable [*configuration*][configuration]. | ||
| They can contain [*plugins*][plugin] and settings. | ||
@@ -1021,13 +1120,27 @@ ###### Example | ||
| ```js | ||
| exports.settings = {bullet: '*', fences: true} | ||
| exports.settings = {bullet: '*', emphasis: '*', fences: true} | ||
| exports.plugins = [ | ||
| require('remark-preset-lint-recommended'), | ||
| require('remark-preset-lint-consistent'), | ||
| require('remark-comment-config'), | ||
| require('remark-preset-lint-markdown-style-guide'), | ||
| [require('remark-toc'), {maxDepth: 3, tight: true}], | ||
| require('remark-github') | ||
| require('remark-license') | ||
| ] | ||
| ``` | ||
| `readme.md`: | ||
| ```markdown | ||
| # Hello, World! | ||
| _Emphasis_ and **importance**. | ||
| ## Table of Contents | ||
| ## API | ||
| ## License | ||
| ``` | ||
| `index.js`: | ||
@@ -1043,3 +1156,3 @@ | ||
| .use(preset) | ||
| .process(vfile.readSync('index.md'), function(err, file) { | ||
| .process(vfile.readSync('readme.md'), function(err, file) { | ||
| console.error(report(err || file)) | ||
@@ -1053,7 +1166,37 @@ | ||
| Yields: | ||
| ```txt | ||
| readme.md: no issues found | ||
| ``` | ||
| `readme.md` now contains: | ||
| ```markdown | ||
| # Hello, World! | ||
| *Emphasis* and **importance**. | ||
| ## Table of Contents | ||
| * [API](#api) | ||
| * [License](#license) | ||
| ## API | ||
| ## License | ||
| [MIT](license) © [Titus Wormer](https://wooorm.com) | ||
| ``` | ||
| ## Contribute | ||
| **unified** is built by people just like you! | ||
| Check out [`contributing.md`][contributing] for ways to get started. | ||
| See [`contributing.md`][contributing] in [`unifiedjs/.github`][health] for ways | ||
| to get started. | ||
| See [`support.md`][support] for ways to get help. | ||
| Ideas for new plugins and tools can be posted in [`unifiedjs/ideas`][ideas]. | ||
| A curated list of awesome unified resources can be found in [**awesome | ||
| unified**][awesome]. | ||
| This project has a [Code of Conduct][coc]. | ||
@@ -1063,22 +1206,14 @@ By interacting with this repository, organisation, or community you agree to | ||
| Want to chat with the community and contributors? | ||
| Join us in [spectrum][chat]! | ||
| Have an idea for a cool new utility or tool? | ||
| That’s great! | ||
| If you want feedback, help, or just to share it with the world you can do so by | ||
| creating an issue in the [`unifiedjs/ideas`][ideas] repository! | ||
| ## Acknowledgments | ||
| Preliminary work for unified was done [in 2014][preliminary] for | ||
| [**retext**][retext] and inspired by [`ware`][ware]. Further incubation | ||
| happened in [**remark**][remark]. The project was finally [externalised][] | ||
| in 2015 and [published][] as `unified`. The project was authored by | ||
| [**@wooorm**](https://github.com/wooorm). | ||
| [**retext**][retext] and inspired by [`ware`][ware]. | ||
| Further incubation happened in [**remark**][remark]. | ||
| The project was finally [externalised][] in 2015 and [published][] as `unified`. | ||
| The project was authored by [**@wooorm**](https://github.com/wooorm). | ||
| Although `unified` since moved it’s plugin architecture to [`trough`][trough], | ||
| Although `unified` since moved its plugin architecture to [`trough`][trough], | ||
| thanks to [**@calvinfo**](https://github.com/calvinfo), | ||
| [**@ianstormtaylor**](https://github.com/ianstormtaylor), and others for their | ||
| work on [`ware`][ware], which was a huge initial inspiration. | ||
| work on [`ware`][ware], as it was a huge initial inspiration. | ||
@@ -1093,3 +1228,3 @@ ## License | ||
| [build-badge]: https://img.shields.io/travis/unifiedjs/unified/master.svg | ||
| [build-badge]: https://img.shields.io/travis/unifiedjs/unified.svg | ||
@@ -1110,2 +1245,8 @@ [build]: https://travis-ci.org/unifiedjs/unified | ||
| [sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg | ||
| [backers-badge]: https://opencollective.com/unified/backers/badge.svg | ||
| [collective]: https://opencollective.com/unified | ||
| [chat-badge]: https://img.shields.io/badge/join%20the%20community-on%20spectrum-7b16ff.svg | ||
@@ -1115,4 +1256,12 @@ | ||
| [npm]: https://docs.npmjs.com/cli/install | ||
| [health]: https://github.com/unifiedjs/.github | ||
| [contributing]: https://github.com/unifiedjs/.github/blob/master/contributing.md | ||
| [support]: https://github.com/unifiedjs/.github/blob/master/support.md | ||
| [coc]: https://github.com/unifiedjs/.github/blob/master/code-of-conduct.md | ||
| [awesome]: https://github.com/unifiedjs/awesome-unified | ||
| [license]: license | ||
@@ -1122,2 +1271,8 @@ | ||
| [npm]: https://docs.npmjs.com/cli/install | ||
| [ts-unist]: https://www.npmjs.com/package/@types/unist | ||
| [ts-vfile]: https://www.npmjs.com/package/@types/vfile | ||
| [site]: https://unified.js.org | ||
@@ -1127,8 +1282,10 @@ | ||
| [announcement]: https://medium.com/unifiedjs/collectively-evolving-through-crowdsourcing-22c359ea95cc | ||
| [twitter]: https://twitter.com/unifiedjs | ||
| [collective]: https://opencollective.com/unified | ||
| [guides]: https://unified.js.org/#guides | ||
| [spectrum]: https://spectrum.chat/unified | ||
| [rehype]: https://github.com/rehypejs/rehype | ||
@@ -1172,13 +1329,19 @@ | ||
| [node]: https://github.com/syntax-tree/unist#node | ||
| [description]: #description | ||
| [syntax-tree]: #syntax-trees | ||
| [configuration]: #configuration | ||
| [file]: #file | ||
| [node]: #node | ||
| [processors]: #processors | ||
| [processor]: #processor | ||
| [process]: #processorprocessfile-done | ||
| [process]: #processorprocessfilevalue-done | ||
| [process-sync]: #processorprocesssyncfilevalue | ||
| [parse]: #processorparsefilevalue | ||
| [parse]: #processorparsefile | ||
@@ -1191,5 +1354,7 @@ [parser]: #processorparser | ||
| [run-sync]: #processorrunsyncnode-file | ||
| [compiler]: #processorcompiler | ||
| [use]: #processoruseplugin-options | ||
| [data]: #processordatakey-value | ||
@@ -1210,2 +1375,6 @@ [attacher]: #function-attacheroptions | ||
| [contribute]: #contribute | ||
| [rehype-react]: https://github.com/rhysd/rehype-react | ||
| [trough]: https://github.com/wooorm/trough#function-fninput-next | ||
@@ -1223,6 +1392,2 @@ | ||
| [contributing]: contributing.md | ||
| [coc]: code-of-conduct.md | ||
| [ideas]: https://github.com/unifiedjs/ideas | ||
@@ -1246,10 +1411,18 @@ | ||
| [storybook]: https://storybook.js.org | ||
| [node.js]: https://nodejs.org | ||
| [debugger.html]: https://github.com/devtools-html/debugger.html | ||
| [zeit]: https://zeit.co | ||
| [netlify]: https://www.netlify.com | ||
| [github]: https://github.com | ||
| [mozilla]: https://www.mozilla.org | ||
| [opensource.guide]: https://opensource.guide | ||
| [wordpress]: https://wordpress.com | ||
| [github]: https://github.com | ||
| [adobe]: https://www.adobe.com | ||
| [facebook]: https://www.facebook.com | ||
| [google]: https://www.google.com |
| // TypeScript Version: 3.0 | ||
| import * as Unist from 'unist' | ||
| import {Node} from 'unist' | ||
| import vfile = require('vfile') | ||
| import {VFile, VFileOptions, VFileContents} from 'vfile' | ||
| declare namespace unified { | ||
| interface Processor { | ||
| /** | ||
| * @returns New unfrozen 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. | ||
| */ | ||
| (): Processor | ||
| export interface Processor { | ||
| /** | ||
| * @returns New unfrozen 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. | ||
| */ | ||
| (): Processor | ||
| /** | ||
| * Configure the processor to use a plugin and optionally configure that plugin with options. | ||
| * | ||
| * @param plugin unified plugin | ||
| * @param options Configuration for plugin] | ||
| * @returns The processor on which use is invoked | ||
| */ | ||
| use(plugin: Plugin, options?: unknown): Processor | ||
| /** | ||
| * @param preset `Object` with an optional plugins (set to list), and/or an optional settings object | ||
| */ | ||
| use(preset: Preset): Processor | ||
| /** | ||
| * @param pluginTuple pairs, plugin and options in an array | ||
| */ | ||
| use(pluginTuple: PluginTuple): Processor | ||
| /** | ||
| * @param list List of plugins, presets, and pairs | ||
| */ | ||
| use(list: PluggableList): Processor | ||
| /** | ||
| * Configure the processor to use a plugin and optionally configure that plugin with options. | ||
| * | ||
| * @param plugin unified plugin | ||
| * @param options Configuration for plugin] | ||
| * @returns The processor on which use is invoked | ||
| */ | ||
| use(plugin: Plugin, options?: unknown): Processor | ||
| /** | ||
| * @param preset `Object` with an optional plugins (set to list), and/or an optional settings object | ||
| */ | ||
| use(preset: Preset): Processor | ||
| /** | ||
| * @param pluginTuple pairs, plugin and options in an array | ||
| */ | ||
| use(pluginTuple: PluginTuple): Processor | ||
| /** | ||
| * @param list List of plugins, presets, and pairs | ||
| */ | ||
| use(list: PluggableList): Processor | ||
| /** | ||
| * Parse text to a syntax tree. | ||
| * | ||
| * @param file VFile or anything which can be given to vfile() | ||
| * @returns Syntax tree representation of input. | ||
| */ | ||
| parse(file: VFileCompatible): Unist.Node | ||
| /** | ||
| * Parse text to a syntax tree. | ||
| * | ||
| * @param file VFile or anything which can be given to vfile() | ||
| * @returns Syntax tree representation of input. | ||
| */ | ||
| parse(file: VFileCompatible): Node | ||
| /** | ||
| * Function handling the parsing of text to a syntax tree. | ||
| * Used in the parse phase in the process and invoked with a `string` and `VFile` representation of the document to parse. | ||
| * | ||
| * `Parser` can be a normal function in which case it must return a `Node`: the syntax tree representation of the given file. | ||
| * | ||
| * `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`. | ||
| */ | ||
| Parser: ParserFunction | typeof Parser | ||
| /** | ||
| * Function handling the parsing of text to a syntax tree. | ||
| * Used in the parse phase in the process and invoked with a `string` and `VFile` representation of the document to parse. | ||
| * | ||
| * `Parser` can be a normal function in which case it must return a `Node`: the syntax tree representation of the given file. | ||
| * | ||
| * `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`. | ||
| */ | ||
| Parser: ParserFunction | typeof Parser | ||
| /** | ||
| * Compile a syntax tree to text. | ||
| * | ||
| * @param node | ||
| * @param file `VFile` or anything which can be given to `vfile()` | ||
| * @returns String representation of the syntax tree file | ||
| */ | ||
| stringify(node: Unist.Node, file?: VFileCompatible): string | ||
| /** | ||
| * Compile a syntax tree to text. | ||
| * | ||
| * @param node | ||
| * @param file `VFile` or anything which can be given to `vfile()` | ||
| * @returns String representation of the syntax tree file | ||
| */ | ||
| stringify(node: Node, file?: VFileCompatible): string | ||
| /** | ||
| * Function handling the compilation of syntax tree to a text. | ||
| * Used in the stringify phase in the process and invoked with a `Node` and `VFile` representation of the document to stringify. | ||
| * | ||
| * `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 (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`. | ||
| */ | ||
| Compiler: CompilerFunction | typeof Compiler | ||
| /** | ||
| * Function handling the compilation of syntax tree to a text. | ||
| * Used in the stringify phase in the process and invoked with a `Node` and `VFile` representation of the document to stringify. | ||
| * | ||
| * `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 (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`. | ||
| */ | ||
| Compiler: CompilerFunction | typeof Compiler | ||
| /** | ||
| * Transform a syntax tree by applying plugins to it. | ||
| * | ||
| * @param node | ||
| * @param file `VFile` or anything which can be given to `vfile()` | ||
| * @param done Invoked when transformation is complete. | ||
| * Either invoked with an error or a syntax tree and a file. | ||
| * @returns `Promise` if `done` is not given. Rejected with an error, or resolved with the resulting syntax tree. | ||
| */ | ||
| run(node: Unist.Node): Promise<Unist.Node> | ||
| run(node: Unist.Node, file: VFileCompatible): Promise<Unist.Node> | ||
| run(node: Unist.Node, done: RunCallback): void | ||
| run(node: Unist.Node, file: VFileCompatible, done: RunCallback): void | ||
| /** | ||
| * Transform a syntax tree by applying plugins to it. | ||
| * | ||
| * @param node | ||
| * @param file `VFile` or anything which can be given to `vfile()` | ||
| * @param done Invoked when transformation is complete. | ||
| * Either invoked with an error or a syntax tree and a file. | ||
| * @returns `Promise` if `done` is not given. Rejected with an error, or resolved with the resulting syntax tree. | ||
| */ | ||
| run(node: Node): Promise<Node> | ||
| run(node: Node, file: VFileCompatible): Promise<Node> | ||
| run(node: Node, done: RunCallback): void | ||
| run(node: Node, file: VFileCompatible, done: RunCallback): void | ||
| /** | ||
| * Transform a syntax tree by applying plugins to it. | ||
| * | ||
| * If asynchronous plugins are configured an error is thrown. | ||
| * | ||
| * @param node | ||
| * @param file `VFile` or anything which can be given to `vfile()` | ||
| * @returns The given syntax tree. | ||
| */ | ||
| runSync(node: Unist.Node, file?: VFileCompatible): Unist.Node | ||
| /** | ||
| * Transform a syntax tree by applying plugins to it. | ||
| * | ||
| * If asynchronous plugins are configured an error is thrown. | ||
| * | ||
| * @param node | ||
| * @param file `VFile` or anything which can be given to `vfile()` | ||
| * @returns The given syntax tree. | ||
| */ | ||
| runSync(node: Node, file?: VFileCompatible): Node | ||
| /** | ||
| * Process the given representation of a file as configured on the processor. The process invokes `parse`, `run`, and `stringify` internally. | ||
| * @param file | ||
| * @param done Invoked when the process is complete. Invoked with a fatal error, if any, and the VFile. | ||
| * @returns `Promise` if `done` is not given. | ||
| * Rejected with an error or resolved with the resulting file. | ||
| */ | ||
| process(file: VFileCompatible): Promise<vfile.VFile> | ||
| process(file: VFileCompatible, done: ProcessCallback): void | ||
| /** | ||
| * Process the given representation of a file as configured on the processor. The process invokes `parse`, `run`, and `stringify` internally. | ||
| * | ||
| * If asynchronous plugins are configured an error is thrown. | ||
| * | ||
| * @param file | ||
| * @returns Virtual file with modified contents. | ||
| */ | ||
| processSync(file: VFileCompatible): vfile.VFile | ||
| /** | ||
| * 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. | ||
| * | ||
| * @returns key-value store object | ||
| */ | ||
| data(): {[key: string]: unknown} | ||
| /** | ||
| * @param key Identifier | ||
| * @returns If getting, the value at key | ||
| */ | ||
| data(key: string): unknown | ||
| /** | ||
| * @param value Value to set. Omit if getting key | ||
| * @returns If setting, the processor on which data is invoked | ||
| */ | ||
| data(key: string, value: any): Processor | ||
| /** | ||
| * 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. New processors functioning just like it can be created by invoking the processor. | ||
| * | ||
| * It’s possible to freeze processors explicitly, by calling `.freeze()`, but `.parse()`, `.run()`, `.stringify()`, and `.process()` call `.freeze()` to freeze a processor too. | ||
| * | ||
| * @returns The processor on which freeze is invoked. | ||
| */ | ||
| freeze(): Processor | ||
| } | ||
| type Plugin = Attacher | ||
| type Settings = { | ||
| [key: string]: unknown | ||
| } | ||
| /** | ||
| * Presets provide a potentially sharable way to configure processors. | ||
| * They can contain multiple plugins and optionally settings as well. | ||
| * Process the given representation of a file as configured on the processor. The process invokes `parse`, `run`, and `stringify` internally. | ||
| * @param file | ||
| * @param done Invoked when the process is complete. Invoked with a fatal error, if any, and the VFile. | ||
| * @returns `Promise` if `done` is not given. | ||
| * Rejected with an error or resolved with the resulting file. | ||
| */ | ||
| interface Preset { | ||
| plugins?: PluggableList | ||
| settings?: Settings | ||
| } | ||
| type PluginTuple = [Plugin, Settings] | ||
| type Pluggable = Plugin | Preset | PluginTuple | ||
| type PluggableList = Pluggable[] | ||
| process(file: VFileCompatible): Promise<VFile> | ||
| process(file: VFileCompatible, done: ProcessCallback): void | ||
| /** | ||
| * An attacher is the thing passed to `use`. | ||
| * It configures the processor and in turn can receive options. | ||
| * Process the given representation of a file as configured on the processor. The process invokes `parse`, `run`, and `stringify` internally. | ||
| * | ||
| * 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. | ||
| * If asynchronous plugins are configured an error is thrown. | ||
| * | ||
| * @this Processor context object is set to the invoked on processor. | ||
| * @param options Configuration | ||
| * @returns Optional. | ||
| * @param file | ||
| * @returns Virtual file with modified contents. | ||
| */ | ||
| interface Attacher { | ||
| (this: Processor, options?: unknown): Transformer | void | ||
| } | ||
| processSync(file: VFileCompatible): VFile | ||
| /** | ||
| * 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`), the process stops. | ||
| * 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. | ||
| * | ||
| * The transformation process in unified is handled by `trough`, see it’s documentation for the exact semantics of transformers. | ||
| * @returns key-value store object | ||
| */ | ||
| data(): {[key: string]: unknown} | ||
| /** | ||
| * @param key Identifier | ||
| * @returns If getting, the value at key | ||
| */ | ||
| data(key: string): unknown | ||
| /** | ||
| * @param value Value to set. Omit if getting key | ||
| * @returns If setting, the processor on which data is invoked | ||
| */ | ||
| data(key: string, value: any): Processor | ||
| /** | ||
| * Freeze a processor. Frozen processors are meant to be extended and not to be configured or processed directly. | ||
| * | ||
| * @param node | ||
| * @param file | ||
| * @param next If the signature of a transformer includes `next` (third argument), the function may finish asynchronous, and must invoke `next()`. | ||
| * @returns | ||
| * - `Error` — Can be returned to stop the process | ||
| * - `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`) or rejected (optionally with an `Error`) | ||
| * Once a processor is frozen it cannot be unfrozen. New processors functioning just like it can be created by invoking the processor. | ||
| * | ||
| * It’s possible to freeze processors explicitly, by calling `.freeze()`, but `.parse()`, `.run()`, `.stringify()`, and `.process()` call `.freeze()` to freeze a processor too. | ||
| * | ||
| * @returns The processor on which freeze is invoked. | ||
| */ | ||
| interface Transformer { | ||
| ( | ||
| node: Unist.Node, | ||
| file: VFileCompatible, | ||
| next?: (error: Error | null, tree: Unist.Node, file: vfile.VFile) => {} | ||
| ): Error | Unist.Node | Promise<Unist.Node> | ||
| } | ||
| freeze(): Processor | ||
| } | ||
| class Parser { | ||
| parse(file: VFileCompatible): Unist.Node | ||
| } | ||
| export type Plugin = Attacher | ||
| export type Settings = { | ||
| [key: string]: unknown | ||
| } | ||
| /** | ||
| * Presets provide a potentially sharable way to configure processors. | ||
| * They can contain multiple plugins and optionally settings as well. | ||
| */ | ||
| export interface Preset { | ||
| plugins?: PluggableList | ||
| settings?: Settings | ||
| } | ||
| export type PluginTuple = [Plugin, Settings] | ||
| export type Pluggable = Plugin | Preset | PluginTuple | ||
| export type PluggableList = Pluggable[] | ||
| type ParserFunction = (file: VFileCompatible) => Unist.Node | ||
| /** | ||
| * An attacher is the thing passed to `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. | ||
| * | ||
| * @this Processor context object is set to the invoked on processor. | ||
| * @param options Configuration | ||
| * @returns Optional. | ||
| */ | ||
| export interface Attacher { | ||
| (this: Processor, options?: unknown): Transformer | void | ||
| } | ||
| class Compiler { | ||
| compile(node: Unist.Node, file?: VFileCompatible): string | ||
| } | ||
| type CompilerFunction = (node: Unist.Node, file?: VFileCompatible) => string | ||
| /** | ||
| * 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`), the process stops. | ||
| * | ||
| * The transformation process in unified is handled by `trough`, see it’s documentation for the exact semantics of transformers. | ||
| * | ||
| * @param node | ||
| * @param file | ||
| * @param next If the signature of a transformer includes `next` (third argument), the function may finish asynchronous, and must invoke `next()`. | ||
| * @returns | ||
| * - `Error` — Can be returned to stop the process | ||
| * - `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`) or rejected (optionally with an `Error`) | ||
| */ | ||
| export interface Transformer { | ||
| ( | ||
| node: Node, | ||
| file: VFileCompatible, | ||
| next?: (error: Error | null, tree: Node, file: VFile) => {} | ||
| ): Error | Node | Promise<Node> | ||
| } | ||
| type RunCallback = ( | ||
| error: Error | null, | ||
| node: Unist.Node, | ||
| file: vfile.VFile | ||
| ) => void | ||
| export class Parser { | ||
| parse(file: VFileCompatible): Node | ||
| } | ||
| type ProcessCallback = (error: Error | null, file: vfile.VFile) => void | ||
| export type ParserFunction = (file: VFileCompatible) => Node | ||
| type VFileCompatible = vfile.VFile | vfile.VFileOptions | vfile.VFileContents | ||
| export class Compiler { | ||
| compile(node: Node, file?: VFileCompatible): string | ||
| } | ||
| export type CompilerFunction = (node: Node, file?: VFileCompatible) => string | ||
| export type RunCallback = (error: Error | null, node: Node, file: VFile) => void | ||
| export type ProcessCallback = (error: Error | null, file: VFile) => void | ||
| export type VFileCompatible = VFile | VFileOptions | VFileContents | ||
| /** | ||
| * Object describing how to process text. | ||
| */ | ||
| declare function unified(): unified.Processor | ||
| export = unified | ||
| export default function unified(): Processor |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by7.95%
59409
- Dependency count
- decreased by-37.5%
5
- Number of lines in readme file
- increased by14.34%
1379
Worsened metrics
- Dev dependency count
- increased by20%
12
Dependency changes
+ Addedis-plain-obj@2.1.0(transitive)
+ Addedunist-util-stringify-position@2.0.3(transitive)
+ Addedvfile@4.2.1(transitive)
+ Addedvfile-message@2.0.4(transitive)
- Removed@types/unist@^2.0.0
- Removed@types/vfile@^3.0.0
- Removedx-is-string@^0.1.0
- Removed@types/node@22.9.0(transitive)
- Removed@types/unist@3.0.3(transitive)
- Removed@types/vfile@3.0.2(transitive)
- Removed@types/vfile-message@2.0.0(transitive)
- Removedis-plain-obj@1.1.0(transitive)
- Removedreplace-ext@1.0.0(transitive)
- Removedundici-types@6.19.8(transitive)
- Removedunist-util-stringify-position@1.1.24.0.0(transitive)
- Removedvfile@3.0.1(transitive)
- Removedvfile-message@1.1.14.0.2(transitive)
- Removedx-is-string@0.1.0(transitive)
Updatedis-plain-obj@^2.0.0
Updatedvfile@^4.0.0